about summary refs log tree commit diff
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
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.
-rw-r--r--.gitignore4
-rw-r--r--README.md26
-rw-r--r--docs/www/SKILL.md28
-rwxr-xr-xscripts/gn4-token.py172
-rw-r--r--src/auth.rs72
-rw-r--r--src/config.rs9
-rw-r--r--src/lib.rs15
-rw-r--r--src/routes/dev.rs4
-rw-r--r--src/routes/mod.rs1
-rw-r--r--src/routes/tokens.rs426
-rw-r--r--src/tokens.rs538
-rw-r--r--tests/tokens.rs200
12 files changed, 1492 insertions, 3 deletions
diff --git a/.gitignore b/.gitignore
index 46f24fc..1dc9d3c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,7 @@ __pycache__
 /cwl/gemma/gemma-loco.cwl
 # Editor swap files: vim leaves these behind while a file is open.
 *.swp
+
+# The short-token registry: a secret store, never committed.
+tokens.sqlite
+tokens.sqlite-*
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.
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=<peak marker> --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:
diff --git a/scripts/gn4-token.py b/scripts/gn4-token.py
new file mode 100755
index 0000000..44f0dea
--- /dev/null
+++ b/scripts/gn4-token.py
@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Administer this server's short API tokens (`gn4ai_...`).
+
+The registry is a single SQLite database (`tokens.sqlite`, `GN4_API_TOKENS_DB`),
+owned by the server; this script does not open it. It talks to the server's own
+routes instead, so there is exactly one implementation of the format, the
+checksum and the revocation rules:
+
+    create  mint a token and print it ONCE      POST   /tokens
+    list    every token, never the secret       GET    /tokens
+    revoke  revoke one by its id                DELETE /tokens/{id}
+    who     describe a credential               GET    /tokens/who
+
+Those routes only answer a caller on this machine (the server checks the TCP
+peer address, not a header), so this script is a local admin tool by
+construction -- there is no `--host` far-away variant worth having.
+
+    scripts/gn4-token.py create --id zachs-1 --subject zachs --ttl-days 30
+    scripts/gn4-token.py list
+    scripts/gn4-token.py who  gn4ai_...           # or pass it as --token-file
+    scripts/gn4-token.py revoke zachs-1
+
+The base URL defaults to $GN4_API, else http://127.0.0.1:$GENENETWORK4_PORT
+(3000 if unset) -- i.e. this machine, which is the only place the routes answer.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+DEFAULT_PORT = 3000
+
+
+def base_url() -> str:
+    explicit = os.environ.get("GN4_API")
+    if explicit:
+        return explicit.rstrip("/")
+    port = os.environ.get("GENENETWORK4_PORT", str(DEFAULT_PORT))
+    return f"http://127.0.0.1:{port}"
+
+
+def request(method: str, path: str, body: dict | None = None, token: str | None = None):
+    data = None if body is None else json.dumps(body).encode()
+    headers = {"content-type": "application/json"} if data else {}
+    if token:
+        headers["authorization"] = f"Bearer {token}"
+    call = urllib.request.Request(base_url() + path, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(call, timeout=30) as response:
+            return json.loads(response.read().decode())
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode(errors="replace")
+        try:
+            parsed = json.loads(detail)
+            message = parsed.get("detail") or parsed.get("message") or detail
+            code = parsed.get("code", "")
+        except json.JSONDecodeError:
+            message, code = detail, ""
+        if error.code == 403 and code == "not_local":
+            raise SystemExit(
+                f"{base_url()} refused this caller: token administration only answers "
+                "requests from this machine (127.0.x.x or ::1, not through a proxy)."
+            ) from error
+        raise SystemExit(f"{method} {path}: HTTP {error.code}: {message}") from error
+    except urllib.error.URLError as error:
+        raise SystemExit(
+            f"cannot reach {base_url()} ({error.reason}); is the server running, "
+            "and is this machine allowed to administer tokens?"
+        ) from error
+
+
+def secret_from(args) -> str:
+    if args.token:
+        return args.token.strip()
+    if args.token_file:
+        with open(args.token_file) as handle:
+            return handle.read().strip()
+    raise SystemExit("give the token as an argument, --token, or --token-file")
+
+
+def command_create(args) -> int:
+    reply = request(
+        "POST",
+        "/tokens",
+        {
+            "id": args.id,
+            "subject": args.subject,
+            "scope": args.scope,
+            **({"ttl_days": args.ttl_days} if args.ttl_days is not None else {}),
+            **({"note": args.note} if args.note else {}),
+        },
+    )["data"]
+    print(f"id        {reply['id']}")
+    print(f"subject   {reply['subject']}  scope {reply['scope']}  status {reply['status']}")
+    if reply.get("expires_at"):
+        print(f"expires   {reply['expires_at']}")
+    print()
+    print("This is the only time the token can be shown -- it is stored as a hash:")
+    print()
+    print(f"  {reply['token']}")
+    print()
+    print("Use it as `Authorization: Bearer <token>`. Never in a query string.")
+    return 0
+
+
+def command_list(args) -> int:
+    tokens = request("GET", "/tokens")["data"]
+    if not tokens:
+        print("no tokens")
+        return 0
+    width = max(len(token["id"]) for token in tokens)
+    for token in tokens:
+        expires = token.get("expires_at")
+        used = token.get("last_used_at")
+        print(
+            f"{token['id']:<{width}}  {token['subject']:<16}  {token['scope']:<8}"
+            f"  {token['status']:<8}  {token['prefix']}…"
+            f"  {'expires ' + str(expires) if expires else 'no expiry'}"
+            f"  {'used ' + str(used) if used else 'never used'}"
+        )
+    return 0
+
+
+def command_revoke(args) -> int:
+    reply = request("DELETE", f"/tokens/{args.id}")["data"]
+    print(f"revoked {reply['id']} ({reply['subject']}); effective on the next request")
+    return 0
+
+
+def command_who(args) -> int:
+    reply = request("GET", "/tokens/who", token=secret_from(args))["data"]
+    print(json.dumps(reply, indent=2))
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    create = commands.add_parser("create", help="mint a token, printing it once")
+    create.add_argument("--id", required=True, help="human handle, unique: zachs-1")
+    create.add_argument("--subject", required=True, help="who it acts as (gn-auth user id)")
+    create.add_argument("--scope", default="public", help="registry-declared scope (default: public)")
+    create.add_argument("--ttl-days", type=int, default=None, help="lifetime in days (default 30)")
+    create.add_argument("--note", default=None, help="free text, e.g. what it is for")
+    create.set_defaults(run=command_create)
+
+    listing = commands.add_parser("list", help="every token, never the secret")
+    listing.set_defaults(run=command_list)
+
+    revoke = commands.add_parser("revoke", help="revoke a token by its id")
+    revoke.add_argument("id")
+    revoke.set_defaults(run=command_revoke)
+
+    who = commands.add_parser("who", help="describe a credential (either scheme)")
+    who.add_argument("token", nargs="?", help="the credential itself")
+    who.add_argument("--token", dest="token_option", default=None, help=argparse.SUPPRESS)
+    who.add_argument("--token-file", default=None, help="read the credential from a file")
+    who.set_defaults(run=command_who, token=None)
+
+    args = parser.parse_args()
+    if args.command == "who":
+        args.token = args.token or args.token_option
+    return args.run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/src/auth.rs b/src/auth.rs
index 20145b8..a2036e1 100644
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -83,8 +83,35 @@ impl CallerSlot {
 /// treats them as optional, not every token carries them) checked.
 /// Does not by itself mean the caller is authorized for anything; see
 /// [`authorise`] for that.
+/// Which kind of credential a request presented. Downstream code -- the
+/// `#[gnauth(secured)]` gate, basket ownership, the access log -- treats
+/// both the same way; only the `raw` field's meaning and the places that
+/// forward it to gn-auth differ.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Scheme {
+    /// A gn-auth JWT: signed, and readable.
+    Jwt,
+    /// A `gn4ai_` token from this server's own registry: opaque, and
+    /// only meaningful here.
+    Opaque,
+}
+
+impl Scheme {
+    /// For the access log and the `who` reply.
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Scheme::Jwt => "jwt",
+            Scheme::Opaque => "opaque",
+        }
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct AuthToken {
+    /// Which kind of credential this is (see [`Scheme`]).
+    pub scheme: Scheme,
+    /// The registry id for an opaque token (`zachs-1`), `None` for a JWT.
+    pub id: Option<String>,
     /// The token subject (gn-auth user id).
     pub sub: String,
     /// Space-separated OAuth2 scopes, e.g. "profile group resource".
@@ -117,6 +144,34 @@ impl<S: Send + Sync> FromRequestParts<S> for AuthToken {
             .ok_or_else(|| unauthorized("Authorization header must be a Bearer token."))?;
 
         let config = Config::load();
+
+        // A `gn4ai_` credential never reaches gn-auth: it is opaque, and
+        // only this server's registry can say who it is. The prefix check
+        // comes first so a short token is never fed to the JWT validator
+        // (which would answer with a confusing signature error).
+        if token.starts_with(crate::tokens::PREFIX) {
+            let registry = crate::tokens::registry(&config.api_tokens_db)
+                .map_err(|e| unauthorized(&format!("token registry unavailable: {e}")))?;
+            let peer = parts
+                .extensions
+                .get::<axum::extract::ConnectInfo<std::net::SocketAddr>>()
+                .map(|axum::extract::ConnectInfo(address)| address.ip().to_string());
+            let record = registry
+                .authenticate(token, peer.as_deref())
+                .map_err(|e| unauthorized(&format!("token registry error: {e}")))?
+                .ok_or_else(|| unauthorized("That token is not valid, has been revoked or has expired."))?;
+            if let Some(slot) = parts.extensions.get::<CallerSlot>() {
+                slot.set(&record.subject);
+            }
+            return Ok(AuthToken {
+                scheme: Scheme::Opaque,
+                id: Some(record.id),
+                sub: record.subject,
+                scope: record.scope,
+                raw: token.to_string(),
+            });
+        }
+
         let claims =
             verify(token, &config.auth_server_url).map_err(|e| unauthorized(&e.to_string()))?;
         // For the response header the proxy logs (see `CallerSlot`).
@@ -124,6 +179,8 @@ impl<S: Send + Sync> FromRequestParts<S> for AuthToken {
             slot.set(&claims.sub);
         }
         Ok(AuthToken {
+            scheme: Scheme::Jwt,
+            id: None,
             sub: claims.sub,
             scope: claims.scope,
             raw: token.to_string(),
@@ -306,6 +363,21 @@ pub fn check(
     if is_publicly_readable(public, confidentiality, create_time) {
         return Ok(Some(Authorized(())));
     }
+    // A `gn4ai_` token cannot authorise confidential data: gn-auth has
+    // never heard of an opaque token, and the alternatives -- minting a
+    // gn-auth token on the fly from a stored credential, or keeping a
+    // second grant model in step with gn-auth's -- were both rejected for
+    // v1 (see the project memory: "API tokens: the one hard edge is
+    // gn-auth's resource-authorization round trip"). Say so explicitly,
+    // so the caller knows to use a JWT rather than that they lack a
+    // privilege.
+    if token.scheme == Scheme::Opaque {
+        return Err(
+            "Short API tokens can only read public data. This resource is not public; \
+             use a gn-auth JWT (Authorization: Bearer <jwt>) for confidential datasets."
+                .to_string(),
+        );
+    }
     let authorised = match trait_name {
         Some(trait_name) => authorise_trait(
             auth_server_url,
diff --git a/src/config.rs b/src/config.rs
index ff0ab8c..b23d39b 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -76,6 +76,11 @@ pub struct Config {
     /// Same GEMMA_WRAPPER_CMD config key GeneNetwork3 uses. Defaults to
     /// "gemma-wrapper", resolved via PATH.
     pub gemma_wrapper_cmd: String,
+    /// Where the short (`gn4ai_`) API tokens live: one SQLite database,
+    /// `GN4_API_TOKENS_DB`, default `tokens.sqlite` in the working
+    /// directory. See src/tokens.rs. The file is chmod 0600 on open --
+    /// it is a secret store, and it must not be in the repository.
+    pub api_tokens_db: String,
     /// Directory gemma-wrapper uses to cache K matrices and association
     /// results between calls (its own --cache-dir switch). Defaults to
     /// a "gn4-gemma" directory under the system temp dir.
@@ -274,6 +279,7 @@ impl Config {
         );
         values.insert("XAPIAN_DB_PATH".to_string(), String::new());
         values.insert("SEARCH_ENGINE".to_string(), "forward".to_string());
+        values.insert("GN4_API_TOKENS_DB".to_string(), "tokens.sqlite".to_string());
         values.insert("GEMMA_WRAPPER_CMD".to_string(), "gemma-wrapper".to_string());
         values.insert(
             "GEMMA_CACHE_DIR".to_string(),
@@ -443,6 +449,7 @@ impl Config {
             "GEMMA_PLOTTER",
             "XAPIAN_DB_PATH",
             "SEARCH_ENGINE",
+            "GN4_API_TOKENS_DB",
             "GEMMA_WRAPPER_CMD",
             "GEMMA_CACHE_DIR",
             "RAVANAN_CMD",
@@ -507,6 +514,7 @@ impl Config {
             dev_token_client_secret: values["GN_AUTH_DEV_CLIENT_SECRET"].clone(),
             dev_token_username: values["GN_AUTH_DEV_USERNAME"].clone(),
             dev_token_password: values["GN_AUTH_DEV_PASSWORD"].clone(),
+            api_tokens_db: values["GN4_API_TOKENS_DB"].clone(),
             gemma_wrapper_cmd: values["GEMMA_WRAPPER_CMD"].clone(),
             gemma_cache_dir: values["GEMMA_CACHE_DIR"].clone(),
             ravanan_cmd: values["RAVANAN_CMD"].clone(),
@@ -768,6 +776,7 @@ mod tests {
             "GN3_TIMEOUT_SECS",
             "XAPIAN_DB_PATH",
             "SEARCH_ENGINE",
+            "GN4_API_TOKENS_DB",
             "GEMMA_WRAPPER_CMD",
             "GEMMA_CACHE_DIR",
             "RAVANAN_CMD",
diff --git a/src/lib.rs b/src/lib.rs
index e054c42..3222369 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -31,6 +31,7 @@ mod rqtl;
 pub mod search;
 mod streaming;
 pub mod suggest;
+pub mod tokens;
 pub mod wikidata;
 
 use error::ApiError;
@@ -238,6 +239,20 @@ pub fn app() -> Router {
     if config::Config::load().test_token_enabled {
         api_router = api_router.routes(routes!(routes::dev::get_test_token));
     }
+    // Administering the short API tokens. Always registered, and each
+    // handler refuses anything that did not arrive directly from this
+    // machine (see src/routes/tokens.rs): minting credentials must not be
+    // reachable from the network, so there is no switch to turn that off.
+    // A sub-router so the localhost guard is a layer over exactly these
+    // four routes: it must refuse a remote caller before anything of the
+    // request is parsed (see routes::tokens::local_only).
+    let token_router = OpenApiRouter::new()
+        .routes(routes!(routes::tokens::list_tokens))
+        .routes(routes!(routes::tokens::mint_token))
+        .routes(routes!(routes::tokens::revoke_token))
+        .routes(routes!(routes::tokens::who_am_i))
+        .route_layer(axum::middleware::from_fn(routes::tokens::local_only));
+    api_router = api_router.merge(token_router);
     let (router, api) = api_router.split_for_parts();
     router
         .route("/openapi.json", axum::routing::get(|| async { Json(api) }))
diff --git a/src/routes/dev.rs b/src/routes/dev.rs
index 58f50c2..ef87986 100644
--- a/src/routes/dev.rs
+++ b/src/routes/dev.rs
@@ -50,7 +50,7 @@ struct TokenResponse {
 /// Whether the connection's peer is this machine: an address in
 /// 127.0.0.0/8 (127.0.x.x), the IPv6 loopback `::1`, or an IPv4-mapped
 /// 127.x.
-fn is_local(peer: &SocketAddr) -> bool {
+pub(crate) fn is_local(peer: &SocketAddr) -> bool {
     match peer.ip() {
         IpAddr::V4(ip) => ip.is_loopback(),
         IpAddr::V6(ip) => {
@@ -63,7 +63,7 @@ fn is_local(peer: &SocketAddr) -> bool {
 /// these headers to anything, so they are never trusted to *establish*
 /// that a caller is local -- only used to refuse a request that claims to
 /// have come through a proxy.
-fn via_proxy(headers: &HeaderMap) -> bool {
+pub(crate) fn via_proxy(headers: &HeaderMap) -> bool {
     ["x-forwarded-for", "forwarded", "x-real-ip"]
         .into_iter()
         .any(|name| headers.contains_key(name))
diff --git a/src/routes/mod.rs b/src/routes/mod.rs
index 55c8ce2..2bf783e 100644
--- a/src/routes/mod.rs
+++ b/src/routes/mod.rs
@@ -10,6 +10,7 @@ pub mod bulklmm;
 pub mod correlation;
 pub mod datasets;
 pub mod dev;
+pub mod tokens;
 pub mod fitqtl;
 pub mod gemma;
 pub mod frequencies;
diff --git a/src/routes/tokens.rs b/src/routes/tokens.rs
new file mode 100644
index 0000000..6bd7425
--- /dev/null
+++ b/src/routes/tokens.rs
@@ -0,0 +1,426 @@
+//! Administering the short API tokens (see src/tokens.rs).
+//!
+//! **These routes answer only a caller on this machine**: the TCP peer
+//! address must be 127.0.x.x or ::1, the connection must be direct (no
+//! `X-Forwarded-For` / `Forwarded` / `X-Real-IP`, which a reverse proxy
+//! on the same host would add), and a request with no known peer is
+//! refused. Anything else is a 403 (`not_local`). That guard is shared
+//! with `/get-test-token` (src/routes/dev.rs) rather than reinvented:
+//! minting credentials must never be reachable from the network, and
+//! there is no configuration switch that can change that.
+//!
+//! What is deliberately absent:
+//!
+//! - **no token in a query string.** Creating one is a POST, introspection
+//!   reads the caller's own `Authorization: Bearer`, and nothing here
+//!   takes a secret as a parameter, because query strings end up in
+//!   nginx's access log and in `next` links;
+//! - **no secret is ever returned again.** `POST /tokens` shows the token
+//!   exactly once, in its reply; `GET /tokens` lists handles, subjects and
+//!   timestamps, never the token or its hash;
+//! - **no way to impersonate with `x-gn4-user`.** That header is set by
+//!   this server on responses; it is never read as a credential.
+
+use axum::Json;
+use axum::extract::{ConnectInfo, Extension, Path};
+use axum::http::{HeaderMap, StatusCode};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+
+use crate::auth::AuthToken;
+use crate::config::Config;
+use crate::error::ApiError;
+use crate::response::{Ctx, Envelope};
+use crate::routes::dev::{is_local, via_proxy};
+use crate::tokens::{self, Record};
+
+/// One registry row as the API reports it: no secret, no hash.
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct TokenView {
+    pub id: String,
+    pub subject: String,
+    pub scope: String,
+    /// The first characters of the secret, so an operator can match a
+    /// row to a token they are holding without the row storing it.
+    pub prefix: String,
+    pub created_at: i64,
+    pub expires_at: Option<i64>,
+    pub last_used_at: Option<i64>,
+    pub note: Option<String>,
+    pub revoked_at: Option<i64>,
+    pub status: String,
+}
+
+impl TokenView {
+    fn of(record: &Record) -> Self {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs() as i64)
+            .unwrap_or(0);
+        let status = if record.revoked() {
+            "revoked"
+        } else if record.expired(now) {
+            "expired"
+        } else {
+            "active"
+        };
+        Self {
+            id: record.id.clone(),
+            subject: record.subject.clone(),
+            scope: record.scope.clone(),
+            prefix: record.prefix.clone(),
+            created_at: record.created_at,
+            expires_at: record.expires_at,
+            last_used_at: record.last_used_at,
+            note: record.note.clone(),
+            revoked_at: record.revoked_at,
+            status: status.to_string(),
+        }
+    }
+}
+
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct MintRequest {
+    /// Human handle, unique: `zachs-1`, `agent-ravanan-3`.
+    pub id: String,
+    /// Who the token is for (the gn-auth user id it acts as).
+    pub subject: String,
+    /// Registry-declared scope; v1 mints `public`.
+    #[serde(default)]
+    pub scope: Option<String>,
+    /// Lifetime in days; omitted means `tokens::DEFAULT_TTL_DAYS`.
+    #[serde(default)]
+    pub ttl_days: Option<i64>,
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct Minted {
+    /// Shown once, and only once: it is not stored anywhere.
+    pub token: String,
+    pub id: String,
+    pub subject: String,
+    pub scope: String,
+    pub prefix: String,
+    pub created_at: i64,
+    pub expires_at: Option<i64>,
+    pub status: String,
+}
+
+/// The localhost guard as middleware, applied to the whole token router
+/// in src/lib.rs.
+///
+/// A layer rather than a check inside each handler, deliberately: axum
+/// extracts a handler's arguments *before* its body runs, so a per-handler
+/// check would still answer a remote caller with a 415 for a malformed
+/// body. This refuses the request before anything is parsed, which is what
+/// "only responds to localhost" has to mean.
+pub async fn local_only(
+    request: axum::extract::Request,
+    next: axum::middleware::Next,
+) -> axum::response::Response {
+    use axum::response::IntoResponse;
+
+    let peer = request
+        .extensions()
+        .get::<ConnectInfo<SocketAddr>>()
+        .cloned();
+    let rid = request
+        .extensions()
+        .get::<crate::response::RequestInfo>()
+        .cloned()
+        .unwrap_or_else(|| crate::response::RequestInfo::new(None));
+    if let Err(error) = require_local(&peer.map(Extension), request.headers(), &rid, "tokens") {
+        return error.into_response();
+    }
+    next.run(request).await
+}
+
+/// The localhost guard, shared by every route in this module.
+fn require_local(
+    peer: &Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: &HeaderMap,
+    rid: &crate::response::RequestInfo,
+    operation: &str,
+) -> Result<(), ApiError> {
+    let local = peer
+        .as_ref()
+        .is_some_and(|Extension(ConnectInfo(address))| is_local(address));
+    if !local || via_proxy(headers) {
+        return Err(ApiError::new(
+            StatusCode::FORBIDDEN,
+            "not_local",
+            "Not authorized",
+            "Token administration only answers callers on this machine (127.0.x.x or ::1), \
+             directly and not through a proxy."
+                .to_string(),
+            operation,
+        )
+        .with_request_id(rid.clone()));
+    }
+    Ok(())
+}
+
+fn registry(config: &Config) -> Result<tokens::Registry, ApiError> {
+    tokens::registry(&config.api_tokens_db).map_err(|error| {
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "token_registry",
+            "Token registry unavailable",
+            error,
+            "tokens",
+        )
+    })
+}
+
+#[utoipa::path(get, path = "/tokens", summary = "List the short API tokens (localhost only)", description = "Answers only a caller on this machine (127.0.x.x or ::1, directly, not through a proxy); anything else is a 403. Never returns a token or its hash.", responses(
+    (status = 200, description = "Every registered token", body = Envelope<Vec<TokenView>>),
+    (status = 403, description = "The request did not come from localhost", body = ApiError)
+), security())]
+pub async fn list_tokens(
+    ctx: Ctx,
+    peer: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+) -> Result<Json<Envelope<Vec<TokenView>>>, ApiError> {
+    let rid = ctx.request_info();
+    // Defence in depth: the router layer has already refused non-local
+    // callers before anything was parsed (see `local_only`).
+    require_local(&peer, &headers, &rid, "list_tokens")?;
+    let config = Config::load();
+    let records = tokio::task::spawn_blocking(move || registry(&config).and_then(|r| {
+        r.list().map_err(|error| ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "token_registry",
+            "Token registry error",
+            error,
+            "list_tokens",
+        ))
+    }))
+    .await
+    .map_err(|error| {
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal_error",
+            "Internal error",
+            error.to_string(),
+            "list_tokens",
+        )
+        .with_request_id(rid.clone())
+    })??;
+    Ok(Json(ctx.envelope(records.iter().map(TokenView::of).collect())))
+}
+
+#[utoipa::path(post, path = "/tokens", summary = "Mint a short API token (localhost only)", description = "Answers only a caller on this machine (127.0.x.x or ::1, directly, not through a proxy). The token is returned exactly once and only its SHA-256 is stored.", responses(
+    (status = 200, description = "The new token, shown once", body = Envelope<Minted>),
+    (status = 403, description = "The request did not come from localhost", body = ApiError),
+    (status = 409, description = "That id is already taken", body = ApiError)
+), security())]
+pub async fn mint_token(
+    ctx: Ctx,
+    peer: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    Json(request): Json<MintRequest>,
+) -> Result<Json<Envelope<Minted>>, ApiError> {
+    let rid = ctx.request_info();
+    require_local(&peer, &headers, &rid, "mint_token")?;
+    let config = Config::load();
+    let scope = request.scope.unwrap_or_else(|| "public".to_string());
+    let minted = tokio::task::spawn_blocking(move || {
+        let registry = registry(&config)?;
+        let (secret, record) = registry
+            .mint(
+                request.id.trim(),
+                request.subject.trim(),
+                &scope,
+                request.ttl_days,
+                request.note.as_deref(),
+            )
+            .map_err(|error| {
+                // SQLite says "UNIQUE constraint failed" for a taken id; that
+                // is a 409, not a server error.
+                let status = if error.contains("UNIQUE") {
+                    StatusCode::CONFLICT
+                } else {
+                    StatusCode::INTERNAL_SERVER_ERROR
+                };
+                ApiError::new(
+                    status,
+                    "token_not_minted",
+                    "Could not mint the token",
+                    format!("{}: {error}", request.id),
+                    "mint_token",
+                )
+            })?;
+        let view = TokenView::of(&record);
+        Ok::<_, ApiError>(Minted {
+            token: secret,
+            id: view.id,
+            subject: view.subject,
+            scope: view.scope,
+            prefix: view.prefix,
+            created_at: view.created_at,
+            expires_at: view.expires_at,
+            status: view.status,
+        })
+    })
+    .await
+    .map_err(|error| {
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal_error",
+            "Internal error",
+            error.to_string(),
+            "mint_token",
+        )
+        .with_request_id(rid.clone())
+    })??;
+    Ok(Json(ctx.envelope(minted)))
+}
+
+#[utoipa::path(delete, path = "/tokens/{id}", summary = "Revoke a short API token (localhost only)", description = "Answers only a caller on this machine. Revocation takes effect on the next request, without a restart.", params(("id" = String, Path, description = "The token's handle, e.g. zachs-1")), responses(
+    (status = 200, description = "The revoked token", body = Envelope<TokenView>),
+    (status = 403, description = "The request did not come from localhost", body = ApiError),
+    (status = 404, description = "No such token", body = ApiError)
+), security())]
+pub async fn revoke_token(
+    ctx: Ctx,
+    peer: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    Path(id): Path<String>,
+) -> Result<Json<Envelope<TokenView>>, ApiError> {
+    let rid = ctx.request_info();
+    require_local(&peer, &headers, &rid, "revoke_token")?;
+    let config = Config::load();
+    let wanted = id.clone();
+    let revoked = tokio::task::spawn_blocking(move || {
+        let registry = registry(&config)?;
+        let changed = registry.revoke(&wanted).map_err(|error| {
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "token_registry",
+                "Token registry error",
+                error,
+                "revoke_token",
+            )
+        })?;
+        if !changed {
+            return Err(ApiError::new(
+                StatusCode::NOT_FOUND,
+                "no_such_token",
+                "No such token",
+                format!("There is no active token with id {wanted}."),
+                "revoke_token",
+            ));
+        }
+        let record = registry
+            .list()
+            .map_err(|error| {
+                ApiError::new(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "token_registry",
+                    "Token registry error",
+                    error,
+                    "revoke_token",
+                )
+            })?
+            .into_iter()
+            .find(|record| record.id == wanted);
+        Ok::<_, ApiError>(record)
+    })
+    .await
+    .map_err(|error| {
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal_error",
+            "Internal error",
+            error.to_string(),
+            "revoke_token",
+        )
+        .with_request_id(rid.clone())
+    })??;
+    match revoked {
+        Some(record) => Ok(Json(ctx.envelope(TokenView::of(&record)))),
+        None => Err(ApiError::new(
+            StatusCode::NOT_FOUND,
+            "no_such_token",
+            "No such token",
+            format!("There is no token with id {id}."),
+            "revoke_token",
+        )),
+    }
+}
+
+/// Who is this credential, and how long has it got? Works for both
+/// schemes: a JWT answers with its claims, an opaque token with its
+/// registry row. The credential is read from the `Authorization` header
+/// by [`AuthToken`] -- never from a query parameter.
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct WhoAmI {
+    pub scheme: String,
+    pub subject: String,
+    pub scope: String,
+    /// Present for an opaque token, absent for a JWT.
+    pub id: Option<String>,
+    pub created_at: Option<i64>,
+    pub expires_at: Option<i64>,
+    pub last_used_at: Option<i64>,
+}
+
+#[utoipa::path(get, path = "/tokens/who", summary = "Describe the presented credential (localhost only)", description = "Answers only a caller on this machine (127.0.x.x or ::1, directly, not through a proxy), for either a gn-auth JWT or a gn4ai_ token, read from the Authorization header.", responses(
+    (status = 200, description = "The credential's identity and lifetime", body = Envelope<WhoAmI>),
+    (status = 401, description = "Missing or invalid credential", body = ApiError),
+    (status = 403, description = "The request did not come from localhost", body = ApiError)
+), security(("bearer" = [])))]
+pub async fn who_am_i(
+    ctx: Ctx,
+    peer: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    token: AuthToken,
+) -> Result<Json<Envelope<WhoAmI>>, ApiError> {
+    let rid = ctx.request_info();
+    require_local(&peer, &headers, &rid, "who_am_i")?;
+    let mut who = WhoAmI {
+        scheme: token.scheme.as_str().to_string(),
+        subject: token.sub.clone(),
+        scope: token.scope.clone(),
+        id: token.id.clone(),
+        created_at: None,
+        expires_at: None,
+        last_used_at: None,
+    };
+    if token.scheme == crate::auth::Scheme::Opaque {
+        let config = Config::load();
+        let secret = token.raw.clone();
+        let record = tokio::task::spawn_blocking(move || {
+            registry(&config).and_then(|r| {
+                r.describe(&secret).map_err(|error| {
+                    ApiError::new(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "token_registry",
+                        "Token registry error",
+                        error,
+                        "who_am_i",
+                    )
+                })
+            })
+        })
+        .await
+        .map_err(|error| {
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal_error",
+                "Internal error",
+                error.to_string(),
+                "who_am_i",
+            )
+            .with_request_id(rid.clone())
+        })??;
+        if let Some(record) = record {
+            who.created_at = Some(record.created_at);
+            who.expires_at = record.expires_at;
+            who.last_used_at = record.last_used_at;
+        }
+    }
+    Ok(Json(ctx.envelope(who)))
+}
diff --git a/src/tokens.rs b/src/tokens.rs
new file mode 100644
index 0000000..6e92058
--- /dev/null
+++ b/src/tokens.rs
@@ -0,0 +1,538 @@
+//! Short, opaque API tokens, kept in a single SQLite database
+//! (`tokens.sqlite` by default, `GN4_API_TOKENS_DB`).
+//!
+//! Why opaque: nothing is stored *in* the token. A gn-auth JWT carries
+//! its subject, scope and expiry in a signed but readable payload; a
+//! `gn4ai_` token carries none of that, and every fact about it lives in
+//! this registry, keyed by the SHA-256 of the secret. Consequences, all
+//! deliberate:
+//!
+//! - revoking is deleting (or stamping `revoked_at` on) one row, and it
+//!   takes effect on the next request, with no restart and no
+//!   configuration reload;
+//! - a token in a log line, a screenshot or a bug report reveals nothing;
+//! - the registry is authoritative for who the caller is and how long
+//!   the token lives -- not whatever was signed into the string;
+//! - and if the registry is lost, every short token stops working: they
+//!   cannot be recovered from their hashes or enumerated.
+//!
+//! Why SQLite rather than a JSON file: the registry is written at mint
+//! and revoke time *and* on use (`last_used_at`), from the server and
+//! from the admin CLI at the same time. A JSON file would need
+//! rewriting per request and an mtime watch to notice a revocation;
+//! SQLite gives atomic single-row updates, a WAL so readers do not
+//! block the writer, and `PRAGMA data_version` as a cheap signal that
+//! another connection committed -- which is how the in-process cache
+//! knows to reload instead of guessing a TTL.
+//!
+//! Format: `gn4ai_` + 56 body characters + 2 checksum characters = 64
+//! characters in total (the two checksum characters come out of the 58
+//! the first draft gave the body, so the token stays the documented 64
+//! long while a typo is caught before any lookup). The alphabet is 31
+//! symbols (`23456789abcdefghjkmnpqrstuvwxyz`: no
+//! 0/O, 1/l/I, and no `- _ + / =`) so the token survives being pasted,
+//! double-clicked, quoted in a shell or dropped into a header, and the
+//! fixed prefix lets the auth extractor branch before it tries to
+//! validate a JWT. 56 body characters over 31 symbols is ~277 bits.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::{Mutex, OnceLock};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use rusqlite::{Connection, OptionalExtension};
+
+/// The scheme marker. The extractor branches on this before anything
+/// else, and secret scanners can flag it.
+pub const PREFIX: &str = "gn4ai_";
+
+const ALPHABET: &[u8] = b"23456789abcdefghjkmnpqrstuvwxyz";
+const BODY_LEN: usize = 56;
+const CHECKSUM_LEN: usize = 2;
+/// `PREFIX.len() + BODY_LEN + CHECKSUM_LEN`, and also the hard cap on
+/// any credential we will look at (see `plausible`).
+pub const TOTAL_LEN: usize = PREFIX.len() + BODY_LEN + CHECKSUM_LEN;
+
+/// The longest a token may live when minted without an explicit TTL.
+pub const DEFAULT_TTL_DAYS: i64 = 30;
+
+/// How often a token's `last_used_at` is written. Updating it on every
+/// request would turn an indexed read into a write on the hot path.
+const LAST_USED_GRANULARITY: i64 = 60;
+
+fn now() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+/// One registered token, as stored: never the secret.
+#[derive(Debug, Clone)]
+pub struct Record {
+    pub id: String,
+    pub subject: String,
+    pub scope: String,
+    pub prefix: String,
+    pub created_at: i64,
+    pub expires_at: Option<i64>,
+    pub last_used_at: Option<i64>,
+    pub note: Option<String>,
+    pub revoked_at: Option<i64>,
+}
+
+impl Record {
+    pub fn expired(&self, at: i64) -> bool {
+        self.expires_at.is_some_and(|expires| expires <= at)
+    }
+
+    pub fn revoked(&self) -> bool {
+        self.revoked_at.is_some()
+    }
+
+    /// Whether this token may authenticate a request right now.
+    pub fn usable(&self, at: i64) -> bool {
+        !self.revoked() && !self.expired(at)
+    }
+}
+
+// ---- the secret itself ----------------------------------------------------
+
+/// The checksum covers the body, so a typo is refused before the
+/// registry is consulted: "not a token we could have minted" is a
+/// different answer from "no such token".
+fn checksum(body: &[u8]) -> [u8; CHECKSUM_LEN] {
+    // Two independent accumulators over the body, each folded into the
+    // alphabet. Order-sensitive (unlike a plain sum) so a transposition
+    // is caught.
+    let mut a: u64 = 0xcbf2_9ce4_8422_2325;
+    let mut b: u64 = 0x9e37_79b9_7f4a_7c15;
+    for (i, byte) in body.iter().enumerate() {
+        a = a.wrapping_mul(0x1000_0000_01b3).wrapping_add(*byte as u64);
+        b = b.rotate_left(7) ^ ((*byte as u64).wrapping_add(i as u64 + 1));
+    }
+    [
+        ALPHABET[(a % ALPHABET.len() as u64) as usize],
+        ALPHABET[(b % ALPHABET.len() as u64) as usize],
+    ]
+}
+
+/// A fresh secret: the only time it exists in a form anyone can read.
+///
+/// Randomness comes from `/dev/urandom` rather than a new crate: the
+/// platforms this runs on all have it, and adding a dependency would
+/// mean regenerating the crate list in `guix.scm` (see docs/dev/SKILL.md
+/// on Cargo.lock drift).
+pub fn mint_secret() -> Result<String, String> {
+    use std::io::Read;
+
+    let mut words = [0u8; BODY_LEN * 4];
+    std::fs::File::open("/dev/urandom")
+        .and_then(|mut random| random.read_exact(&mut words))
+        .map_err(|e| format!("cannot read /dev/urandom: {e}"))?;
+
+    let mut body = String::with_capacity(BODY_LEN);
+    for chunk in words.chunks_exact(4) {
+        let word = u32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]) as usize;
+        // 2^32 is not a multiple of 31, so the modulo is very slightly
+        // biased (~2^-27); irrelevant at this entropy.
+        body.push(ALPHABET[word % ALPHABET.len()] as char);
+    }
+    let sum = checksum(body.as_bytes());
+    Ok(format!(
+        "{PREFIX}{body}{}",
+        std::str::from_utf8(&sum).expect("ascii")
+    ))
+}
+
+/// Cheap shape check: prefix, length, alphabet, checksum. Says nothing
+/// about whether the token exists.
+pub fn plausible(secret: &str) -> bool {
+    let Some(body) = secret.strip_prefix(PREFIX) else {
+        return false;
+    };
+    if body.len() != BODY_LEN + CHECKSUM_LEN || body.bytes().any(|b| !ALPHABET.contains(&b)) {
+        return false;
+    }
+    let (body, sum) = body.split_at(BODY_LEN);
+    checksum(body.as_bytes()) == sum.as_bytes()
+}
+
+/// SHA-256 of the secret, hex: the registry key. The secret itself is
+/// never stored, so this is one-way by construction.
+pub fn digest(secret: &str) -> String {
+    crate::indexer::sha256::hex_digest(secret.as_bytes())
+}
+
+/// The first characters of the secret, for `who` and for correlating an
+/// access-log line with a registry row without keeping the secret.
+pub fn display_prefix(secret: &str) -> String {
+    secret.chars().take(PREFIX.len() + 8).collect()
+}
+
+// ---- the registry ---------------------------------------------------------
+
+/// An open registry. Cloned handles share one connection (rusqlite's
+/// `Connection` is not `Sync`, so a mutex wraps it).
+#[derive(Clone)]
+pub struct Registry {
+    path: String,
+    connection: std::sync::Arc<Mutex<Connection>>,
+    /// hash -> (the `data_version` it was read at, the row)
+    cache: std::sync::Arc<Mutex<HashMap<String, (i64, Record)>>>,
+}
+
+fn schema(connection: &Connection) -> rusqlite::Result<()> {
+    connection.execute_batch(
+        "CREATE TABLE IF NOT EXISTS token (
+             id           TEXT PRIMARY KEY,
+             hash         TEXT NOT NULL UNIQUE,
+             prefix       TEXT NOT NULL,
+             subject      TEXT NOT NULL,
+             scope        TEXT NOT NULL,
+             created_at   INTEGER NOT NULL,
+             expires_at   INTEGER,
+             last_used_at INTEGER,
+             last_used_ip TEXT,
+             revoked_at   INTEGER,
+             note         TEXT
+         );
+         CREATE INDEX IF NOT EXISTS token_hash_idx ON token (hash);",
+    )
+}
+
+impl Registry {
+    /// Open (creating if needed) the registry at `path`.
+    ///
+    /// The file is a secret store: it is created or tightened to mode
+    /// 0600, so a token hash and its subject are not world-readable.
+    pub fn open(path: &str) -> Result<Self, String> {
+        let connection = Connection::open(path).map_err(|e| format!("{path}: {e}"))?;
+        connection
+            .busy_timeout(Duration::from_secs(5))
+            .and_then(|_| connection.pragma_update(None, "journal_mode", "WAL"))
+            .map_err(|e| format!("{path}: {e}"))?;
+        schema(&connection).map_err(|e| format!("{path}: {e}"))?;
+        restrict(path)?;
+        Ok(Self {
+            path: path.to_string(),
+            connection: std::sync::Arc::new(Mutex::new(connection)),
+            cache: std::sync::Arc::new(Mutex::new(HashMap::new())),
+        })
+    }
+
+    pub fn path(&self) -> &str {
+        &self.path
+    }
+
+    fn with<T>(&self, f: impl FnOnce(&Connection) -> rusqlite::Result<T>) -> Result<T, String> {
+        let guard = self.connection.lock().map_err(|_| "registry lock poisoned".to_string())?;
+        f(&guard).map_err(|e| e.to_string())
+    }
+
+    /// `PRAGMA data_version` changes when another connection commits.
+    /// That is the cache-invalidation signal: revocation stays immediate
+    /// without re-reading on every request, and without a TTL guess.
+    fn data_version(&self) -> Result<i64, String> {
+        self.with(|connection| {
+            connection.pragma_query_value(None, "data_version", |row| row.get::<_, i64>(0))
+        })
+    }
+
+    /// Mint a token for `subject`. Returns the secret -- the only time
+    /// it can be shown -- and the stored record.
+    pub fn mint(
+        &self,
+        id: &str,
+        subject: &str,
+        scope: &str,
+        ttl_days: Option<i64>,
+        note: Option<&str>,
+    ) -> Result<(String, Record), String> {
+        let secret = mint_secret()?;
+        let hash = digest(&secret);
+        let at = now();
+        let expires_at = Some(at + ttl_days.unwrap_or(DEFAULT_TTL_DAYS) * 86_400);
+        let record = Record {
+            id: id.to_string(),
+            subject: subject.to_string(),
+            scope: scope.to_string(),
+            prefix: display_prefix(&secret),
+            created_at: at,
+            expires_at,
+            last_used_at: None,
+            note: note.map(str::to_string),
+            revoked_at: None,
+        };
+        self.with(|connection| {
+            connection.execute(
+                "INSERT INTO token
+                     (id, hash, prefix, subject, scope, created_at, expires_at, note)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+                rusqlite::params![
+                    record.id,
+                    hash,
+                    record.prefix,
+                    record.subject,
+                    record.scope,
+                    record.created_at,
+                    record.expires_at,
+                    record.note,
+                ],
+            )
+        })?;
+        self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?.clear();
+        Ok((secret, record))
+    }
+
+    /// Look a secret up, refusing one that is revoked, expired or not a
+    /// token we could have minted.
+    ///
+    /// A successful lookup counts as use: `last_used_at` is refreshed at
+    /// most once a minute.
+    pub fn authenticate(&self, secret: &str, peer: Option<&str>) -> Result<Option<Record>, String> {
+        if !plausible(secret) {
+            return Ok(None);
+        }
+        let hash = digest(secret);
+        let record = match self.cached(&hash)? {
+            Some(record) => record,
+            None => return Ok(None),
+        };
+        let at = now();
+        if !record.usable(at) {
+            return Ok(None);
+        }
+        let stale = record
+            .last_used_at
+            .is_none_or(|used| at - used >= LAST_USED_GRANULARITY);
+        if stale {
+            // Best effort: a failed bookkeeping write must not fail the
+            // request that the token is valid for.
+            let written = self
+                .with(|connection| {
+                    connection.execute(
+                        "UPDATE token SET last_used_at = ?1, last_used_ip = ?2 WHERE hash = ?3",
+                        rusqlite::params![at, peer, hash],
+                    )
+                })
+                .is_ok();
+            if written {
+                // The cache is only invalidated by *other* connections'
+                // commits (that is what `data_version` reports), so drop the
+                // entry ourselves or the next request would see the old
+                // `last_used_at` and write again immediately.
+                if let Ok(mut cache) = self.cache.lock() {
+                    cache.remove(&hash);
+                }
+            }
+        }
+        Ok(Some(record))
+    }
+
+    fn cached(&self, hash: &str) -> Result<Option<Record>, String> {
+        let version = self.data_version()?;
+        {
+            let cache = self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?;
+            if let Some((seen, record)) = cache.get(hash) {
+                if *seen == version {
+                    return Ok(Some(record.clone()));
+                }
+            }
+        }
+        // Stale or absent: this connection's own version moved, or another
+        // writer committed. Either way, re-read and re-cache.
+        let record = self.by_hash(hash)?;
+        let recorded_version = self.data_version()?;
+        if let Some(record) = &record {
+            let mut cache = self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?;
+            // Store under the version read *after* the row, so a commit that
+            // landed in between invalidates on the next use.
+            cache.insert(hash.to_string(), (recorded_version, record.clone()));
+        }
+        Ok(record)
+    }
+
+    fn by_hash(&self, hash: &str) -> Result<Option<Record>, String> {
+        self.with(|connection| {
+            connection
+                .query_row(
+                    "SELECT id, subject, scope, prefix, created_at, expires_at,
+                            last_used_at, note, revoked_at
+                       FROM token WHERE hash = ?1",
+                    rusqlite::params![hash],
+                    row_to_record,
+                )
+                .optional()
+        })
+    }
+
+    /// Every token, secrets never included.
+    pub fn list(&self) -> Result<Vec<Record>, String> {
+        self.with(|connection| {
+            let mut statement = connection.prepare(
+                "SELECT id, subject, scope, prefix, created_at, expires_at,
+                        last_used_at, note, revoked_at
+                   FROM token ORDER BY created_at, id",
+            )?;
+            let rows = statement.query_map([], row_to_record)?;
+            rows.collect()
+        })
+    }
+
+    /// Revoke by id; returns whether a live row was stamped.
+    ///
+    /// Soft, so `who` can still explain a stale token ("revoked on ...")
+    /// rather than claiming it never existed.
+    pub fn revoke(&self, id: &str) -> Result<bool, String> {
+        let at = now();
+        let changed = self.with(|connection| {
+            connection.execute(
+                "UPDATE token SET revoked_at = ?1 WHERE id = ?2 AND revoked_at IS NULL",
+                rusqlite::params![at, id],
+            )
+        })?;
+        self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?.clear();
+        Ok(changed > 0)
+    }
+
+    /// The record for a secret, revoked or not: what `who` answers.
+    pub fn describe(&self, secret: &str) -> Result<Option<Record>, String> {
+        if !plausible(secret) {
+            return Ok(None);
+        }
+        self.by_hash(&digest(secret))
+    }
+}
+
+fn row_to_record(row: &rusqlite::Row<'_>) -> rusqlite::Result<Record> {
+    Ok(Record {
+        id: row.get(0)?,
+        subject: row.get(1)?,
+        scope: row.get(2)?,
+        prefix: row.get(3)?,
+        created_at: row.get(4)?,
+        expires_at: row.get(5)?,
+        last_used_at: row.get(6)?,
+        note: row.get(7)?,
+        revoked_at: row.get(8)?,
+    })
+}
+
+/// One registry per path, opened on first use. Config is effectively
+/// static, but tests point at their own databases.
+pub fn registry(path: &str) -> Result<Registry, String> {
+    static REGISTRIES: OnceLock<Mutex<HashMap<String, Result<Registry, String>>>> = OnceLock::new();
+    let registries = REGISTRIES.get_or_init(|| Mutex::new(HashMap::new()));
+    let mut guard = registries.lock().map_err(|_| "registry cache poisoned".to_string())?;
+    guard
+        .entry(path.to_string())
+        .or_insert_with(|| Registry::open(path))
+        .clone()
+}
+
+#[cfg(unix)]
+fn restrict(path: &str) -> Result<(), String> {
+    use std::os::unix::fs::PermissionsExt;
+    let permissions = std::fs::Permissions::from_mode(0o600);
+    std::fs::set_permissions(Path::new(path), permissions)
+        .map_err(|e| format!("{path}: cannot set mode 0600: {e}"))
+}
+
+#[cfg(not(unix))]
+fn restrict(_path: &str) -> Result<(), String> {
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_registry(name: &str) -> Registry {
+        let path = std::env::temp_dir().join(format!("gn4-tokens-{name}-{}.sqlite", std::process::id()));
+        let _ = std::fs::remove_file(&path);
+        Registry::open(&path.to_string_lossy()).expect("registry")
+    }
+
+    #[test]
+    fn a_minted_secret_is_the_documented_shape() {
+        let secret = mint_secret().expect("random");
+        assert_eq!(secret.len(), TOTAL_LEN);
+        assert!(secret.starts_with(PREFIX));
+        assert!(plausible(&secret));
+        assert!(secret
+            .trim_start_matches(PREFIX)
+            .bytes()
+            .all(|b| ALPHABET.contains(&b)));
+        assert_ne!(secret, mint_secret().expect("random"));
+    }
+
+    #[test]
+    fn a_typo_is_refused_before_the_registry_is_asked() {
+        let secret = mint_secret().expect("random");
+        for position in [PREFIX.len(), PREFIX.len() + 20, TOTAL_LEN - 1] {
+            let mut bytes = secret.clone().into_bytes();
+            bytes[position] = if bytes[position] == b'a' { b'b' } else { b'a' };
+            let typo = String::from_utf8(bytes).unwrap();
+            assert!(!plausible(&typo), "position {position} should not look minted");
+        }
+        assert!(!plausible("gn4ai_short"));
+        assert!(!plausible("not-a-token"));
+    }
+
+    #[test]
+    fn a_minted_token_authenticates_and_revocation_is_immediate() {
+        let registry = temp_registry("revoke");
+        let (secret, record) = registry
+            .mint("zachs-1", "zachs", "public", Some(30), Some("hand test"))
+            .expect("mint");
+        let found = registry.authenticate(&secret, Some("127.0.0.1")).expect("authenticate");
+        assert_eq!(found.map(|r| r.subject), Some("zachs".to_string()));
+        assert!(registry.revoke(&record.id).expect("revoke"));
+        assert!(registry
+            .authenticate(&secret, None)
+            .expect("authenticate")
+            .is_none());
+        // ... and `who` still explains it rather than denying it existed.
+        let described = registry.describe(&secret).expect("describe").expect("kept");
+        assert!(described.revoked());
+    }
+
+    #[test]
+    fn an_expired_token_stops_working_without_being_revoked() {
+        let registry = temp_registry("expired");
+        let (secret, record) = registry
+            .mint("old-1", "old", "public", Some(1), None)
+            .expect("mint");
+        assert!(record.usable(record.created_at));
+        assert!(!record.usable(record.created_at + 2 * 86_400));
+        // A negative TTL mints something already expired, which is how the
+        // test avoids waiting a day.
+        let expired = registry
+            .mint("old-2", "old", "public", Some(-1), None)
+            .expect("mint");
+        assert!(registry.authenticate(&expired.0, None).expect("authenticate").is_none());
+        assert!(registry.authenticate(&secret, None).expect("authenticate").is_some());
+    }
+
+    #[test]
+    fn last_used_is_recorded_at_most_once_a_minute() {
+        let registry = temp_registry("touch");
+        let (secret, _) = registry.mint("a-1", "a", "public", Some(30), None).expect("mint");
+        registry.authenticate(&secret, Some("10.0.0.9")).expect("authenticate");
+        let first = registry.describe(&secret).unwrap().unwrap().last_used_at.expect("stamped");
+        std::thread::sleep(std::time::Duration::from_millis(1100));
+        registry.authenticate(&secret, Some("10.0.0.9")).expect("authenticate");
+        let second = registry.describe(&secret).unwrap().unwrap().last_used_at.expect("stamped");
+        assert_eq!(first, second, "a second use within a minute must not rewrite the row");
+    }
+
+    #[test]
+    fn an_unknown_but_well_formed_token_is_not_authenticated() {
+        let registry = temp_registry("unknown");
+        let stranger = mint_secret().expect("random");
+        assert!(plausible(&stranger));
+        assert!(registry.authenticate(&stranger, None).expect("authenticate").is_none());
+        assert!(registry.describe(&stranger).expect("describe").is_none());
+    }
+}
diff --git a/tests/tokens.rs b/tests/tokens.rs
new file mode 100644
index 0000000..f751c0b
--- /dev/null
+++ b/tests/tokens.rs
@@ -0,0 +1,200 @@
+//! Token administration (`/tokens`, `/tokens/who`) answers only a caller
+//! on this machine, and mints a token whose secret is shown exactly once
+//! (src/routes/tokens.rs, src/tokens.rs).
+//!
+//! The peer address is the `ConnectInfo` a real server provides
+//! (src/main.rs); these in-process requests supply one the same way
+//! tests/get_test_token.rs does. The registry is a throwaway SQLite file
+//! under the temp dir, wired in through `GN4_API_TOKENS_DB` before the
+//! first `Config::load()` in this process.
+
+use axum::body::Body;
+use axum::extract::ConnectInfo;
+use axum::http::{Method, Request, StatusCode};
+use http_body_util::BodyExt;
+use serde_json::{Value, json};
+use std::net::SocketAddr;
+use std::sync::OnceLock;
+use tower::ServiceExt;
+
+fn registry_path() -> &'static str {
+    static PATH: OnceLock<String> = OnceLock::new();
+    PATH.get_or_init(|| {
+        let path = std::env::temp_dir().join(format!("gn4-tokens-it-{}.sqlite", std::process::id()));
+        let _ = std::fs::remove_file(&path);
+        let path = path.to_string_lossy().into_owned();
+        // SAFETY: set before any request in this test binary has loaded the
+        // configuration, and to one value for the whole process, so no other
+        // thread can observe a different one. `set_var` is unsafe on edition
+        // 2024 because a concurrent reader could see a torn value; the
+        // OnceLock makes this the only write.
+        unsafe { std::env::set_var("GN4_API_TOKENS_DB", &path) };
+        path
+    })
+}
+
+/// A request against the app, from `peer`, optionally with a JSON body.
+async fn call(
+    method: Method,
+    uri: &str,
+    peer: Option<SocketAddr>,
+    body: Option<Value>,
+) -> axum::response::Response {
+    let mut builder = Request::builder().method(method).uri(uri);
+    if body.is_some() {
+        builder = builder.header("content-type", "application/json");
+    }
+    let mut request = builder
+        .body(match body {
+            Some(body) => Body::from(body.to_string()),
+            None => Body::empty(),
+        })
+        .unwrap();
+    if let Some(peer) = peer {
+        request.extensions_mut().insert(ConnectInfo(peer));
+    }
+    genenetwork4::app().oneshot(request).await.unwrap()
+}
+
+async fn error_of(response: axum::response::Response) -> Value {
+    let body = response.into_body().collect().await.unwrap().to_bytes();
+    serde_json::from_slice(&body).unwrap()
+}
+
+async fn json_of(response: axum::response::Response) -> Value {
+    let body = response.into_body().collect().await.unwrap().to_bytes();
+    serde_json::from_slice(&body).unwrap()
+}
+
+#[tokio::test]
+async fn token_administration_refuses_every_caller_that_is_not_local() {
+    registry_path();
+    let remote: SocketAddr = "10.0.0.5:4000".parse().unwrap();
+    let local: SocketAddr = "127.0.0.1:4000".parse().unwrap();
+
+    // Every route, from another machine, and from a local caller that says it
+    // came through a proxy: minting a credential must never be reachable.
+    for (method, uri, body) in [
+        (Method::GET, "/tokens", None),
+        (
+            Method::POST,
+            "/tokens",
+            Some(json!({"id": "x-1", "subject": "x"})),
+        ),
+        (Method::DELETE, "/tokens/x-1", None),
+        (Method::GET, "/tokens/who", None),
+    ] {
+        let response = call(method.clone(), uri, Some(remote), body.clone()).await;
+        assert_eq!(response.status(), StatusCode::FORBIDDEN, "{method} {uri} remote");
+        let error = error_of(response).await;
+        assert_eq!(error["code"], "not_local", "{method} {uri}");
+        assert!(error["detail"].as_str().unwrap_or_default().contains("this machine"));
+
+        // Fail closed with no peer at all.
+        let response = call(method.clone(), uri, None, body.clone()).await;
+        assert_eq!(response.status(), StatusCode::FORBIDDEN, "{method} {uri} no peer");
+
+        // A local peer whose request claims to be proxied: a reverse proxy on
+        // this host would make every remote client look local.
+        let request = Request::builder()
+            .method(method.clone())
+            .uri(uri)
+            .header("x-forwarded-for", "203.0.113.9")
+            .body(Body::empty())
+            .unwrap();
+        let mut request = request;
+        request.extensions_mut().insert(ConnectInfo(local));
+        let response = genenetwork4::app().oneshot(request).await.unwrap();
+        assert_eq!(response.status(), StatusCode::FORBIDDEN, "{method} {uri} proxied");
+    }
+}
+
+#[tokio::test]
+async fn a_token_minted_locally_authenticates_and_is_then_revoked() {
+    registry_path();
+    let local: SocketAddr = "127.0.0.1:4000".parse().unwrap();
+
+    let response = call(
+        Method::POST,
+        "/tokens",
+        Some(local),
+        Some(json!({
+            "id": "it-1",
+            "subject": "zachs",
+            "scope": "public",
+            "ttl_days": 7,
+            "note": "integration test"
+        })),
+    )
+    .await;
+    assert_eq!(response.status(), StatusCode::OK);
+    let reply = json_of(response).await;
+    let token = reply["token"].as_str().expect("the secret, once").to_string();
+    assert!(token.starts_with("gn4ai_"), "{token}");
+    assert_eq!(token.len(), 64, "{token}");
+    assert_eq!(reply["id"], "it-1");
+    assert_eq!(reply["status"], "active");
+
+    // The listing never repeats the secret or its hash.
+    let response = call(Method::GET, "/tokens", Some(local), None).await;
+    let listing = json_of(response).await;
+    let listing_text = listing.to_string();
+    assert!(!listing_text.contains(&token), "the listing leaked the token");
+    assert!(!listing_text.contains("sha256"));
+    assert_eq!(listing["tokens"][0]["id"], "it-1");
+
+    // A second mint with the same id is a conflict, not a server error.
+    let response = call(
+        Method::POST,
+        "/tokens",
+        Some(local),
+        Some(json!({"id": "it-1", "subject": "zachs"})),
+    )
+    .await;
+    assert_eq!(response.status(), StatusCode::CONFLICT);
+
+    // The token works as a credential: /tokens/who describes it (it is the
+    // only route that needs no model access to prove the extractor branch).
+    let response = call_with_bearer(Method::GET, "/tokens/who", local, &token).await;
+    assert_eq!(response.status(), StatusCode::OK);
+    let who = json_of(response).await;
+    assert_eq!(who["scheme"], "opaque");
+    assert_eq!(who["subject"], "zachs");
+    assert_eq!(who["id"], "it-1");
+    assert!(who["created_at"].as_i64().is_some());
+
+    // Revoking takes effect on the next request, with no restart.
+    let response = call(Method::DELETE, "/tokens/it-1", Some(local), None).await;
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(json_of(response).await["status"], "revoked");
+
+    let response = call_with_bearer(Method::GET, "/tokens/who", local, &token).await;
+    assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+
+    // A typo is refused as unmintable, before any registry lookup, and
+    // says so the same way as an unknown-but-well-formed token: the answer
+    // must not distinguish "not ours" from "no such token" to a caller.
+    let mut typo = token.clone().into_bytes();
+    typo[10] = if typo[10] == b'a' { b'b' } else { b'a' };
+    let typo = String::from_utf8(typo).unwrap();
+    for candidate in [typo, "gn4ai_".to_string() + &"z".repeat(60), "not-a-token".to_string()] {
+        let response = call_with_bearer(Method::GET, "/tokens/who", local, &candidate).await;
+        assert_eq!(response.status(), StatusCode::UNAUTHORIZED, "{candidate}");
+    }
+}
+
+async fn call_with_bearer(
+    method: Method,
+    uri: &str,
+    peer: SocketAddr,
+    token: &str,
+) -> axum::response::Response {
+    let mut request = Request::builder()
+        .method(method)
+        .uri(uri)
+        .header("authorization", format!("Bearer {token}"))
+        .body(Body::empty())
+        .unwrap();
+    request.extensions_mut().insert(ConnectInfo(peer));
+    genenetwork4::app().oneshot(request).await.unwrap()
+}