diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/auth.rs | 72 | ||||
| -rw-r--r-- | src/config.rs | 9 | ||||
| -rw-r--r-- | src/lib.rs | 15 | ||||
| -rw-r--r-- | src/routes/dev.rs | 4 | ||||
| -rw-r--r-- | src/routes/mod.rs | 1 | ||||
| -rw-r--r-- | src/routes/tokens.rs | 426 | ||||
| -rw-r--r-- | src/tokens.rs | 538 |
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()); + } +} |
