about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-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
7 files changed, 1063 insertions, 2 deletions
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());
+    }
+}