about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-06 22:26:21 +0000
committerPjotr <wrk@bosa.lan>2026-11-06 22:26:21 +0000
commit2af6978846121e75175bd329c3d3cdbd3cb835fb (patch)
tree6a7afde888944a525db32b1b53d9f732846795fb /docs
parent9a6c5f36e4435c3f8dd04b21458e18074310e2fa (diff)
downloadgenenetwork4-2af6978846121e75175bd329c3d3cdbd3cb835fb.tar.gz
ai-instruction: issue a token per user without gn-auth
The page told the operator to mint with POST /get-test-token, which is
gn-auth's dev password grant and does not exist in the deployment being
set up. Issuing a second user's token also had no good answer: the stub
minted exactly one token per process, so a new user meant starting a
throwaway instance, grabbing --token-file and killing it.

So add --mint-only: mint for --subject, print, write --token-file and
exit without listening. Verification only depends on the key (committed,
so shared by every instance) and on iss, which now falls back to
AUTH_SERVER_URL -- a token minted this way verifies against the
long-running stub untouched.

* scripts/gn-auth-stub.py (main): --mint-only; --issuer defaults to
AUTH_SERVER_URL before the port-derived default. Docstring says how a
second user's token is issued.
* docs/www/ai-instruction.md (1. Get a token): the operator's command is
the stub, not /get-test-token; the token lasts whatever --expires-in said
rather than an hour, and there is no early revocation. (4. What is
public): minting is operator-side. Appendix: "Token issuance" rewritten
around the stub -- public-data-only, expiry as the only revocation, sub
as attribution, one token per user -- with gn-auth kept as what replaces
it later; the stub is no longer listed as a dev leftover to delete, but
as the auth server that must never be routed publicly.
* README.md (Tests): mention --mint-only next to the stub's other flags.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/ai-instruction.md163
1 files changed, 105 insertions, 58 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index 131aa43..dbd8ede 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -14,22 +14,28 @@ inside the public data.
 
 ## 1. Get a token
 
-**You cannot mint a token yourself.** Tokens are issued by hand: the
-operator runs a command on the server's own loopback interface and hands
-you the resulting JWT (that endpoint is not, and will not be, reachable
-from the internet). If you do not already have a token in your task
-context, stop and ask for one — do not go looking for a token URL, an
-API key or a login form on the public host; there is none.
+**You cannot mint a token yourself.** Tokens are issued by hand, on the
+server, one per user, and handed to you out of band. If you do not
+already have a token in your task context, stop and ask for one — do not
+go looking for a token URL, an API key or a login form on the public
+host; there is none.
 
 ```sh
-# what the operator runs, on the server itself:
-curl -sX POST http://127.0.0.1:3000/get-test-token | jq -r '.data.access_token'
+# what the operator runs, on the server itself, once per user:
+scripts/gn-auth-stub.py --mint-only --subject alice \
+    --expires-in 30d --token-file /run/gn4/alice.token
 ```
 
-```json
-{"data": {"access_token": "<JWT>", "token_type": "Bearer", "scope": "profile group resource"},
- "meta": {"state": "complete", "took_ms": 12, "request_id": "…"}, "notes": [], "next": []}
-```
+No gn-auth is involved: the deployment runs
+`scripts/gn-auth-stub.py` as its whole auth server, and `--mint-only`
+signs a JWT with that stub's key and issuer, prints it (and writes
+`--token-file`) and exits without listening — so issuing a token
+disturbs nothing already running, and the token verifies immediately.
+`--subject` is the name that becomes the token's `sub`: that is what
+makes a call attributable to one user rather than to the server as a
+whole. Installs that do have gn-auth mint from
+`POST /get-test-token` instead; either way, minting happens on the box,
+never through the public host.
 
 Paste that token into your environment and use it as a bearer token:
 
@@ -39,8 +45,12 @@ TOKEN=…                                      # the JWT you were given
 curl -s -H "Authorization: Bearer $TOKEN" "$API/groups/BXD/traits?limit=1"
 ```
 
-The token is a **JWT**, valid for about an hour. It identifies you; it
-does not by itself grant access to anything that is not public (see §4).
+The token is a **JWT**, valid until its `exp` — whatever `--expires-in`
+said when it was minted (30 days in the command above). Nothing renews
+or extends it, and there is no way to revoke one early, so treat the
+token you were given as your only credential for its whole life. It
+identifies you (`sub`); it does not by itself grant access to anything
+that is not public (see §4).
 
 Rules that keep you working:
 
@@ -125,9 +135,11 @@ That is the only rule; it matches GeneNetwork2/3. Everything else answers
   in the public surface: `POST /compute/*` (GEMMA, R/qtl, ravanan) runs
   jobs on the server's filesystem and is deliberately not exposed. Do not
   attempt to use it; it will be refused.
-* `/get-test-token` is the operator's token-minting route on the server's
-  loopback interface (see §1). It is not reachable from here and you do
-  not need it: your token comes from a human.
+* Token minting is entirely operator-side (`scripts/gn-auth-stub.py
+  --mint-only`, see §1): it runs on the server, never through the public
+  host. `/get-test-token` — the equivalent route on gn-auth-backed
+  installs — is not reachable from here either, and you do not need it:
+  your token comes from a human.
 
 If your task needs private data or server-side computation, stop and ask a
 human: it needs an account and a gn-auth grant, not a different URL.
@@ -174,15 +186,17 @@ politely (a few concurrent requests, backoff on 429).
 
 Deploying this on the internet without leaking is mostly about *not*
 exposing things that were built for a trusted caller, and about keeping
-the token-minting route off the public surface entirely.
+both the token-minting path and the auth stub off the public surface.
 
 **Must be off / not routed**
 
-* `POST /get-test-token` — this is the operator's minting route (see
-  "Token issuance"), and the only thing standing between it and the
-  internet is a loopback peer check plus a refusal of requests that carry
-  proxy headers (`src/routes/dev.rs`). Behind nginx the peer *is* loopback,
-  so one omitting `X-Forwarded-For` makes it open to the world: **do not
+* `POST /get-test-token` — irrelevant while there is no gn-auth (the
+  deployment's tokens come from `scripts/gn-auth-stub.py --mint-only`,
+  see "Token issuance"), but the moment gn-auth is behind it, this is a
+  minting route, and the only thing standing between it and the internet
+  is a loopback peer check plus a refusal of requests that carry proxy
+  headers (`src/routes/dev.rs`). Behind nginx the peer *is* loopback, so
+  one omitting `X-Forwarded-For` makes it open to the world: **do not
   proxy it**, keep GN4 bound to `127.0.0.1`, and set
   `GENENETWORK4_TEST_TOKEN=false` on any instance that is not the
   operator's.
@@ -193,47 +207,80 @@ the token-minting route off the public surface entirely.
   `token_only`, not resource-checked, and must stay on the internal
   listener. Same for `/compute/*/status/{id}`, which tails run logs by
   name.
-* Any dev-build leftovers: `target/debug` binaries, the JWKS stub on
-  `:8081`, the `GN4_DB_MODE=dev` "start without a database" mode.
+* Any dev-build leftovers: `target/debug` binaries, the `GN4_DB_MODE=dev`
+  "start without a database" mode.
+* The auth stub on `:8081` is *not* a leftover any more — without gn-auth
+  it is the auth server — but it must stay reachable from genenetwork4
+  only: **never** route it publicly. Its signing key
+  (`test/data/test_rsa_private.pem`) and JWKS are in this repository, so
+  anyone who can fetch its JWKS can mint tokens that genenetwork4 accepts
+  (see "Token issuance" below).
+
+**Token issuance (no gn-auth: the stub, one token per user)**
+
+Without gn-auth the deployment's auth server is
+`scripts/gn-auth-stub.py`, run once and left running (supervise it like
+genenetwork4 — see "Tokens are stateless" in the README for why an hour
+of downtime is survivable and longer is not):
+
+```sh
+AUTH_SERVER_URL=http://127.0.0.1:8081/ \
+  scripts/gn-auth-stub.py --token-file /run/gn4/stub.token
+```
 
-**Token issuance (interim: manual, on the server)**
+`AUTH_SERVER_URL` is where genenetwork4 fetches the key set
+(`/auth/public-jwks`), so it stays a loopback URL here: the public
+`/gn4` prefix has nothing to do with it (docs/nginx.md).
 
-Tokens are minted by a human, on the box, for the AI to use:
+Then one token per user, minted on the box, without touching the running
+stub:
 
 ```sh
-curl -sX POST http://127.0.0.1:3000/get-test-token | jq -r '.data.access_token'
+AUTH_SERVER_URL=http://127.0.0.1:8081/ \
+  scripts/gn-auth-stub.py --mint-only --subject alice \
+      --expires-in 30d --token-file /run/gn4/alice.token
 ```
 
-That route proxies gn-auth's `password` grant for gn-auth's development
-user and never leaves the host, so the public surface has no token
-endpoint at all — which is exactly what the AI-facing section says. The
-requirements that keep that safe:
-
-* bind GN4 to loopback (`GENENETWORK4_BIND=127.0.0.1`) and proxy only the
-  data routes; do **not** proxy `/get-test-token` (see "Must be off");
-* `get-test-token` is only mintable while `GENENETWORK4_TEST_TOKEN=true`,
-  the caller is loopback, carries no proxy headers, and GN4's
-  `AUTH_SERVER_URL` points at a live gn-auth with gn-auth's development
-  client registered (`GN_AUTH_DEV_CLIENT_ID`/`_SECRET`,
-  `GN_AUTH_DEV_USERNAME`/`_PASSWORD`) — fine for a human on the box, and
-  the reason the route must never be routed;
-* hand the token over out of band (it is a bearer credential for the whole
-  public read surface), keep its lifetime short (gn-auth default is ~1 h),
-  and mint a new one for a new session rather than reusing an old one —
-  there is no revocation list, expiry is the only revocation;
-* note that every token minted this way carries gn-auth's *development*
-  user as its `sub`: calls are attributable to that user, not to the
-  individual AI or person you handed the token to, so treat the audit
-  trail as "someone with a token" until `client_credentials` (one client
-  per consumer) exists;
-* if more than a couple of people/AIs need this, replace the manual step
-  with a `client_credentials` grant in gn-auth scoped to public reads
-  (gn-auth has `password`, `jwt-bearer` and `refresh_token` today), plus
-  per-client rate limits and an issuance audit log.
-
-The token must be verifiable offline by GN4 (`AUTH_SERVER_URL` →
-`/auth/public-jwks`), and its `iss` must equal `AUTH_SERVER_URL` exactly,
-trailing slash included.
+`--mint-only` mints, prints, writes the file and exits; `--issuer`
+defaults to `AUTH_SERVER_URL` when that is set, which is what makes the
+token verify against the running stub. Hand the file's contents over out
+of band.
+
+What that token is, and is not:
+
+* **public data only.** tokens minted without `--grant-resource-id` carry
+  no privileges at all: genenetwork4 decides what may go out from each
+  dataset's `public`/`confidentiality`/`create_time` columns, and asks
+  the authorisation lookup about the rest (`src/auth.rs`'s `check`). The
+  lookup says "no privileges", so public datasets read and every
+  non-public one is a 403. Dataset *metadata* stays visible either way,
+  by design. **Never** mint with `--grant-resource-id` for a shared or
+  long-lived token: that hands the holder that non-public resource, and
+  there is no way to take it back before `exp`.
+* **expiry is the only revocation.** There is no denylist, so a token is
+  good until its `exp` and no longer; `--expires-in` is therefore the
+  withdrawal mechanism (30d for a known user is fine, shorter for
+  anything you might need to pull). Revoking *everything* means changing
+  `AUTH_SERVER_URL` (or the key) — `iss` is compared verbatim, so a new
+  host/scheme/trailing slash invalidates every outstanding token.
+* **`sub` is attribution, not authentication.** It names the user in the
+  token and is used as an authorisation-cache key; it grants nothing.
+  Anyone holding a token is that `sub` as far as the API can tell, and
+  the `scope` claim is not consulted for data access.
+* **different users, different tokens** — `--subject alice`,
+  `--subject bob`: same key and issuer, independent `exp`, so one
+  person's token can be rotated or left to lapse without touching anyone
+  else's.
+* verify before handing over: `curl -s -H "Authorization: Bearer $TOKEN"
+  "$API/groups" | head -c 80` should return an envelope, and
+  `401 invalid_token` with `InvalidIssuer` means `AUTH_SERVER_URL` and
+  the minted `iss` disagree.
+
+When gn-auth lands, nothing above changes for the AI reader except where
+the token comes from: `POST /get-test-token` (gn-auth's dev password
+grant) replaces `--mint-only`, and the tokens gain gn-auth's own
+lifetime (7–14 days, bounded by JWKS rotation) and its per-user grants.
+That route must never be proxied — see "Must be off" above.
 
 **Data exposure**