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. --- .gitignore | 4 + README.md | 26 ++- docs/www/SKILL.md | 28 +++ scripts/gn4-token.py | 172 ++++++++++++++++ src/auth.rs | 72 +++++++ src/config.rs | 9 + src/lib.rs | 15 ++ src/routes/dev.rs | 4 +- src/routes/mod.rs | 1 + src/routes/tokens.rs | 426 ++++++++++++++++++++++++++++++++++++++++ src/tokens.rs | 538 +++++++++++++++++++++++++++++++++++++++++++++++++++ tests/tokens.rs | 200 +++++++++++++++++++ 12 files changed, 1492 insertions(+), 3 deletions(-) create mode 100755 scripts/gn4-token.py create mode 100644 src/routes/tokens.rs create mode 100644 src/tokens.rs create mode 100644 tests/tokens.rs 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 `) 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= --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 `. 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, /// The token subject (gn-auth user id). pub sub: String, /// Space-separated OAuth2 scopes, e.g. "profile group resource". @@ -117,6 +144,34 @@ impl FromRequestParts 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::>() + .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::() { + 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 FromRequestParts 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 ) 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, + pub last_used_at: Option, + pub note: Option, + pub revoked_at: Option, + 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, + /// Lifetime in days; omitted means `tokens::DEFAULT_TTL_DAYS`. + #[serde(default)] + pub ttl_days: Option, + #[serde(default)] + pub note: Option, +} + +#[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, + 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::>() + .cloned(); + let rid = request + .extensions() + .get::() + .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>>, + 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(&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>), + (status = 403, description = "The request did not come from localhost", body = ApiError) +), security())] +pub async fn list_tokens( + ctx: Ctx, + peer: Option>>, + headers: HeaderMap, +) -> Result>>, 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), + (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>>, + headers: HeaderMap, + Json(request): Json, +) -> Result>, 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), + (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>>, + headers: HeaderMap, + Path(id): Path, +) -> Result>, 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, + pub created_at: Option, + pub expires_at: Option, + pub last_used_at: Option, +} + +#[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), + (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>>, + headers: HeaderMap, + token: AuthToken, +) -> Result>, 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, + pub last_used_at: Option, + pub note: Option, + pub revoked_at: Option, +} + +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 { + 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>, + /// hash -> (the `data_version` it was read at, the row) + cache: std::sync::Arc>>, +} + +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 { + 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(&self, f: impl FnOnce(&Connection) -> rusqlite::Result) -> Result { + 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 { + 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, + 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, 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, 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, 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, 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 { + 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, String> { + if !plausible(secret) { + return Ok(None); + } + self.by_hash(&digest(secret)) + } +} + +fn row_to_record(row: &rusqlite::Row<'_>) -> rusqlite::Result { + 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 { + static REGISTRIES: OnceLock>>> = 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 = 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, + body: Option, +) -> 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() +} -- cgit 1.4.1