about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-10-13 06:06:37 +0000
committerPjotr <wrk@bosa.lan>2026-10-13 06:06:37 +0000
commit2551418eede25d0ffaebef67f9950f13e3551567 (patch)
tree1d173432582191401f69622925d7337d5ebe81c8 /docs
parent2456d66fc2c14345ab0730ef0a4ae07458af8ec6 (diff)
downloadgenenetwork4-2551418eede25d0ffaebef67f9950f13e3551567.tar.gz
auth: add gnauth compile-time tags (secured/token_only/disabled)
Adds a gnauth-macros proc-macro crate and a private-field Authorized
capability type in src/auth.rs, so #[gnauth(secured)] is a real,
compile-time-checked guarantee that a handler performs the gn-auth
resource-authorisation round trip before sharing trait/probeset
values, rather than just a comment. #[gnauth(token_only)] marks
handlers that require a token but skip the round trip, and
#[gnauth(disabled)] marks the two handlers that need no token at all.

Also fixes groups.rs: group_trait_values, group_trait_info and
group_traits previously performed no gn-auth round trip at all for
published-trait data; they now resolve the group's PublishFreeze row
and call the same auth::check used elsewhere, denying by default when
no such row exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/gn-auth.md55
1 files changed, 49 insertions, 6 deletions
diff --git a/docs/gn-auth.md b/docs/gn-auth.md
index 8e39773..2802784 100644
--- a/docs/gn-auth.md
+++ b/docs/gn-auth.md
@@ -252,6 +252,16 @@ failure.
   dataset at once (e.g. before listing every probeset in it) -- gn-auth
   resolves a trait's resource purely from its dataset name, so the
   trait half of the `"Dataset::Trait"` string never affects the answer.
+- `check(auth_server_url, token, dataset_name, trait_name, public,
+  confidentiality, create_time)`: combines `is_publicly_readable` and
+  `authorise_trait`/`authorise_dataset` (always with
+  `"group:resource:view-resource"`, the only privilege any route here
+  checks) into the one branch every gated handler below actually
+  wants, returning `Option<Authorized>` -- the capability a handler
+  can require to construct a "found and visible" result, rather than
+  writing the branch out by hand. `is_authorised` is its boolean form,
+  for a caller that filters a list instead of rejecting one request
+  (`publication_traits`).
 - `tests/auth.rs` runs all of this against a real gn-auth instance
   (set `GN4_TEST_AUTH_TOKEN`/`GN4_TEST_RESOURCE_ID`; skips otherwise).
 
@@ -278,11 +288,42 @@ probeset in the list):
   and `tests/dataset_probesets.rs` for all of these cases exercised
   against a real gn-auth instance.
 
-`GET /groups/{group}/traits` and its singular siblings (Publish/
-phenotype data) require a token like every endpoint now (see "Every
-endpoint requires a token" below) but don't check any further
-resource-level authorization -- that remains a separate, not yet made
-decision, same as every endpoint outside this family and `/traits`.
+`GET /groups/{group}/traits` and its singular siblings (`/traits/
+{trait_id}` and its `/values` sibling) are gated the same way as
+`/traits/{dataset}/...` below: resolve the group's own `PublishFreeze`
+row (by the group's name -- `PublishXRef`/`PublishFreeze` aren't tied
+by a foreign key, so this is a name lookup, not a join) and run the
+same `is_publicly_readable`/`authorise_trait`/`authorise_dataset`
+check against it. If a group has published traits but no matching
+`PublishFreeze` row to check, that's treated as a deny rather than as
+ungated/public data. `/traits` (the listing) skips the round trip only
+when the group has zero published traits -- there's nothing to
+protect in an empty list, so no reason to spend a gn-auth call (or
+risk denying) on it.
+
+All three endpoints, and the two above them
+(`/datasets/{dataset}/probesets/{probeset}/values` and `/traits/
+{dataset}/{trait}/values`), carry `#[gnauth(secured)]`
+(`gnauth-macros`): a compile-time tag, checked by that attribute
+macro, for handlers that can share actual trait/probeset *values*.
+It's a textual check only -- it can't see across function calls -- so
+it verifies the handler takes `AuthToken` and mentions
+`auth::Authorized`, the capability type only `auth::check` can
+produce (its field is private, so it can't be fabricated outside
+`src/auth.rs`). Metadata-only endpoints (`/traits/{dataset}`,
+`/datasets/{dataset}/probesets`, `/groups/{group}/traits` and their
+singular siblings) are gated the same way but don't carry the tag --
+they don't share values, just whether a trait/dataset is visible at
+all.
+
+`gnauth-macros` also has the opposite tag, `#[gnauth(disabled)]`, for
+the handful of endpoints that intentionally take no `AuthToken` at
+all -- `hello_world` and `version` (`src/lib.rs`) carry it, marking
+"no token needed" as a deliberate decision rather than an oversight.
+It checks the converse of `secured`: the signature must *not* take
+`AuthToken`. (`routes::dev::get_test_token` also takes no token, but
+isn't tagged -- it's a conditionally-registered test utility, a
+different category from a normal public endpoint.)
 
 ### Wired into routes: `/traits/{dataset}/...`, spanning both categories
 
@@ -306,7 +347,9 @@ No non-public `PublishFreeze` exists in the database this was tested
 against, so the deny path for the Publish branch specifically wasn't
 exercised against real data -- only against the already-proven
 ProbeSet branch and gn-auth's own "unlinked dataset" 404-to-deny
-behavior, which this new branch calls unchanged.
+behavior, which this new branch calls unchanged. The same caveat
+applies to `/groups/{group}/traits...` above, which resolves to the
+same `PublishFreeze` check.
 
 ### Every endpoint requires a token