From 586b0f63ef31fde987e00a305e91ee4e2136332e Mon Sep 17 00:00:00 2001 From: Pjotr Prins Date: Sat, 14 Nov 2026 14:20:54 +0000 Subject: tokens: short opaque API tokens in a single tokens.sqlite A second credential format beside gn-auth's JWT, for agents and scripts: `gn4ai_` + 56 body characters + 2 checksum characters = 64, from an alphabet with no look-alikes, so a typo is refused before the registry is consulted. Opaque by design -- nothing is stored in the token; every fact lives in one SQLite database (`tokens.sqlite`, GN4_API_TOKENS_DB, mode 0600, gitignored) keyed by the SHA-256 of the secret. Revoking is a row, takes effect on the next request, and a token in a log line reveals nothing; lose the registry and every short token stops working. Administration is local-only: GET/POST /tokens, DELETE /tokens/{id} and GET /tokens/who are behind a router layer that refuses any caller whose TCP peer is not 127.x.x.x/::1, and any request claiming to come through a proxy. A layer rather than a per-handler check, so nothing of a remote request is parsed before it is refused; there is no configuration switch, because minting credentials must never be reachable from the network. A short token reads public data only: every token-only endpoint, and `#[gnauth(secured)]` endpoints for public rows; a confidential dataset is refused with a 403 that names the JWT route, since gn-auth cannot validate an opaque token (the on-the-fly-bridge and registry-grant alternatives were both rejected for v1). scripts/gn4-token.py create|list|revoke|who drives the routes, so there is one implementation of the format and the revocation rules; the token is printed exactly once. Tests: the localhost guard over all four routes (remote peer, no peer, proxied header), and mint -> authenticate -> who -> revoke -> 401. --- docs/www/SKILL.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs') diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md index b6864c1..b4454ec 100644 --- a/docs/www/SKILL.md +++ b/docs/www/SKILL.md @@ -152,6 +152,34 @@ curl -s -H "$AUTH" --get --data-urlencode locus= --data window=1000 Give the user the SVGs (they render directly) and quote the `x-plot-summary` header (peak, and the reference lines drawn when you asked for them). +### Short API tokens (`gn4ai_...`) + +A second credential format beside gn-auth's JWT, for agents and scripts that +should not carry a user's password or a long-lived JWT. Opaque: nothing is +stored inside it, and everything about it lives in the server's registry (one +SQLite database, `tokens.sqlite`). + +- **Administer them from this machine only.** `scripts/gn4-token.py + create|list|revoke|who` (routes `/tokens`, `/tokens/{id}`, `/tokens/who`). + Those routes answer only a direct caller on this machine — the server checks + the TCP peer address, not a header — and a request that arrives through a + proxy is refused, so this can never be driven from the network. +- **The token is shown exactly once**, by `create`. Only its SHA-256 is stored; + there is no way to recover or enumerate one. `list` shows id, subject, scope, + status, prefix, expiry and last use. +- **Send it as `Authorization: Bearer gn4ai_...`** — never as a query + parameter, which would land in nginx's log and in `next` links. +- **Public data only.** It works on every token-only endpoint (search, compute, + plots, genotype metadata and frequencies, baskets, uploads, matrices) and on + secured endpoints for public rows; a confidential dataset answers 403 telling + the caller to use a gn-auth JWT, because gn-auth cannot validate an opaque + token. +- **Revocation takes effect on the next request**, with no restart: it is a row + in the registry. Expiry is fixed when minted (30 days by default). +- 64 characters, `gn4ai_` + 56 body characters + a 2-character checksum, from an + alphabet with no look-alikes (`0/O`, `1/l/I`) — a typo is refused before the + registry is asked. + ### Which GEMMA endpoint: ravanan by default Two endpoints run the same computation, and the reply shape is identical: -- cgit 1.4.1