diff options
| author | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-14 14:20:54 +0000 |
|---|---|---|
| committer | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-14 14:20:54 +0000 |
| commit | 586b0f63ef31fde987e00a305e91ee4e2136332e (patch) | |
| tree | 47eea9436d52d4634023b053f99049fa3ff21f39 /src/tokens.rs | |
| parent | c822ba22ce00c1615bf47fc8a13f28590aba424a (diff) | |
| download | genenetwork4-586b0f63ef31fde987e00a305e91ee4e2136332e.tar.gz | |
tokens: short opaque API tokens in a single tokens.sqlite
A second credential format beside gn-auth's JWT, for agents and scripts:
`gn4ai_` + 56 body characters + 2 checksum characters = 64, from an
alphabet with no look-alikes, so a typo is refused before the registry is
consulted. Opaque by design -- nothing is stored in the token; every fact
lives in one SQLite database (`tokens.sqlite`, GN4_API_TOKENS_DB, mode
0600, gitignored) keyed by the SHA-256 of the secret. Revoking is a row,
takes effect on the next request, and a token in a log line reveals
nothing; lose the registry and every short token stops working.
Administration is local-only: GET/POST /tokens, DELETE /tokens/{id} and
GET /tokens/who are behind a router layer that refuses any caller whose
TCP peer is not 127.x.x.x/::1, and any request claiming to come through a
proxy. A layer rather than a per-handler check, so nothing of a remote
request is parsed before it is refused; there is no configuration switch,
because minting credentials must never be reachable from the network.
A short token reads public data only: every token-only endpoint, and
`#[gnauth(secured)]` endpoints for public rows; a confidential dataset is
refused with a 403 that names the JWT route, since gn-auth cannot validate
an opaque token (the on-the-fly-bridge and registry-grant alternatives
were both rejected for v1).
scripts/gn4-token.py create|list|revoke|who drives the routes, so there is
one implementation of the format and the revocation rules; the token is
printed exactly once.
Tests: the localhost guard over all four routes (remote peer, no peer,
proxied header), and mint -> authenticate -> who -> revoke -> 401.
Diffstat (limited to 'src/tokens.rs')
| -rw-r--r-- | src/tokens.rs | 538 |
1 files changed, 538 insertions, 0 deletions
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()); + } +} |
