about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-10-04 09:20:41 +0000
committerPjotr <wrk@bosa.lan>2026-10-04 09:20:41 +0000
commit0a58bfdbec94d3c249a905226bd33480198f2e95 (patch)
tree1add70a7555473cd464f3e56ad53f8ebbfde60eb /docs
parent6a5f9ef61d19b2a1a3204df223e2ffb21691a988 (diff)
downloadgenenetwork4-0a58bfdbec94d3c249a905226bd33480198f2e95.tar.gz
doc: Update gn-auth.md and RELEASE_NOTES.md for the Rust implementation.
* docs/gn-auth.md: Document the GN2 public>0 AND confidentiality<1
threshold (the test for whether data needs a gn-auth authorization
call at all, versus just a valid token), the now-implemented
src/auth.rs mechanism, and the four gn-auth bugs found and fixed while
building it.
* RELEASE_NOTES.md: Likewise.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XDDpXvZBQat9uSgDeEMJ8d
Diffstat (limited to 'docs')
-rw-r--r--docs/gn-auth.md59
1 files changed, 49 insertions, 10 deletions
diff --git a/docs/gn-auth.md b/docs/gn-auth.md
index 42ff910..27bcd88 100644
--- a/docs/gn-auth.md
+++ b/docs/gn-auth.md
@@ -185,14 +185,53 @@ has many more (`/auth/role/...`, `/auth/user/...`,
 genenetwork4 doesn't need to talk to gn-auth for every request -- only
 for the two things above: verifying a presented token's signature
 (cache the JWKS, refresh periodically, don't refetch per-request), and
--- for endpoints that should be scoped to a specific group/species --
-asking gn-auth what that token's holder is allowed to do on that
-resource. Endpoints with no sensitive data behind them don't need to
-call gn-auth at all.
-
-This document describes the mechanism; implementing it in Rust --
-likely a custom Axum extractor that verifies the JWT (e.g. via the
-`jsonwebtoken` or `josekit` crate for RS256) and yields the resolved
-user to handlers that opt in, so endpoints that don't need auth aren't
-forced to go through it -- is still to be done.
+-- for data that isn't public -- asking gn-auth what that token's
+holder is allowed to do on a specific resource. Endpoints with no
+sensitive data behind them don't need to call gn-auth at all.
+
+Whether data "is public" is answered by GeneNetwork's own schema, not
+by asking gn-auth: GeneNetwork2 treats a dataset (`ProbeSetFreeze`,
+`PublishFreeze`, `GenoFreeze`) as public exactly when
+`public > 0 AND confidentiality < 1` (`wqflask/api/router.py`, used
+consistently throughout GN2/GN3). `InbredSet`/group rows carry a
+`public` column too, but GN2 never actually filters on it anywhere --
+it's informational only there -- so groups/species endpoints need no
+gating at all, matching GN2's own behavior. For data that *is* public
+by this test, still require a valid token (don't skip verification
+entirely), but skip the resource-authorization call to gn-auth -- one
+less network round trip for what is, in practice, most of the data.
+
+### Implemented, in `src/auth.rs`
+
+- `AuthToken`, an Axum extractor (`impl FromRequestParts`): verifies a
+  bearer token's RS256 signature and standard time claims (`exp`/`nbf`,
+  checked when present -- gn-auth itself treats them as optional,
+  confirmed against its own validator) against a cached, periodically
+  refreshed JWKS. Add it as a handler parameter to require a valid
+  token; omit it for endpoints that don't need one.
+- `is_publicly_readable(public, confidentiality)`: the GN2 threshold
+  above, as a plain function a handler calls on its own fetched row.
+- `authorise(auth_server_url, token, resource_id, privilege)`: the two
+  gn-auth calls (resource-id resolution is the caller's job --
+  `GET /auth/resource/populations/resource-id/...` -- `authorise`
+  itself only wraps `POST /auth/resource/authorisation`), with the
+  per-(user, resource) answer cached briefly so repeated requests for
+  the same resource by the same user don't each cost a round trip.
+- `tests/auth.rs` runs all of this against a real gn-auth instance
+  (set `GN4_TEST_AUTH_TOKEN`/`GN4_TEST_RESOURCE_ID`; skips otherwise).
+
+Wiring this into specific existing endpoints (which ones should
+require a token at all, and which privilege string each should check)
+is a separate decision, not yet made here.
+
+### Found wrong in gn-auth while building this
+
+Four bugs in gn-auth itself blocked this integration before they were
+fixed (see gn-auth's own `RELEASE_NOTES.md` and its
+`fix-fresh-deployment-bugs` branch): a JWKS cache that could stay empty
+for hours after a fresh deployment's first token was issued, a dev
+client whose secret was never hashed so it could never authenticate,
+`public_resources()` crashing on every fresh deployment, and
+`POST /auth/resource/authorisation` crashing (instead of degrading to
+the anonymous view) on an invalid rather than missing bearer token.