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. --- README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index d6a2bdc..55374c0 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,10 @@ A Rust/Axum-based API server for GeneNetwork. | POST | `/plot/bnw` | The BNW network, as SVG. | | GET | `/compute/rqtl/status/{run_id}` | Poll an rqtl run's progress. | | POST | `/get-test-token` | Get a test bearer token (local). | +| GET | `/tokens` | List short API tokens (local). | +| POST | `/tokens` | Mint a short API token (local). | +| DELETE | `/tokens/{id}` | Revoke a short API token (local). | +| GET | `/tokens/who` | Describe the presented credential (local). | | GET | `/search` | Search traits (free-text). | | GET | `/openapi.json` | OpenAPI 3.1 document. | @@ -50,7 +54,27 @@ Every endpoint above requires a valid gn-auth bearer token (`Authorization: Bearer `) except `/`, `/version`, `/openapi.json` and `/get-test-token` itself -- see docs/gn-auth.md and the "Development" section below (`POST /get-test-token`) for how to get -one for local testing. A missing or invalid token is a 401; which +one for local testing. + +**Short API tokens.** Beside gn-auth's JWT there is a second credential +format for agents and scripts: `gn4ai_` + 64-char opaque tokens, stored as +SHA-256 hashes in one SQLite database (`tokens.sqlite`, `GN4_API_TOKENS_DB`, +chmod 0600, gitignored). Nothing is stored *in* the token, so revocation is +deleting a row and takes effect on the next request; a token in a log line +reveals nothing; and if the registry is lost every short token stops working. +Mint, list, revoke and introspect with `scripts/gn4-token.py +create|list|revoke|who`; the token is printed once and never again. +Administration lives at `/tokens`, `/tokens/{id}` and `/tokens/who`, which +**answer only a direct caller on this machine** (TCP peer address, plus a +refusal for anything claiming to be proxied) -- minting credentials is not +reachable from the network, and there is no switch to change that. A short +token reads **public data only**: it works everywhere a token suffices, and on +`#[gnauth(secured)]` endpoints for public rows; a confidential dataset answers +403 telling the caller to use a JWT, since gn-auth cannot validate an opaque +token. Send it as `Authorization: Bearer gn4ai_...` and never in a query +string, which would land in nginx's log and in `next` links. + +A missing or invalid token is a 401; which further, resource-level authorization (if any) an endpoint checks once a token is valid is a separate, per-endpoint matter covered in each entry below. -- cgit 1.4.1