about summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:20:54 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:20:54 +0000
commit586b0f63ef31fde987e00a305e91ee4e2136332e (patch)
tree47eea9436d52d4634023b053f99049fa3ff21f39 /README.md
parentc822ba22ce00c1615bf47fc8a13f28590aba424a (diff)
downloadgenenetwork4-586b0f63ef31fde987e00a305e91ee4e2136332e.tar.gz
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.
Diffstat (limited to 'README.md')
-rw-r--r--README.md26
1 files changed, 25 insertions, 1 deletions
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 <token>`) 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.