diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-06 22:26:21 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-06 22:26:21 +0000 |
| commit | 2af6978846121e75175bd329c3d3cdbd3cb835fb (patch) | |
| tree | 6a7afde888944a525db32b1b53d9f732846795fb /docs | |
| parent | 9a6c5f36e4435c3f8dd04b21458e18074310e2fa (diff) | |
| download | genenetwork4-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.md | 163 |
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** |
