//! Short, opaque API tokens, kept in a single SQLite database //! (`tokens.sqlite` by default, `GN4_API_TOKENS_DB`). //! //! Why opaque: nothing is stored *in* the token. A gn-auth JWT carries //! its subject, scope and expiry in a signed but readable payload; a //! `gn4ai_` token carries none of that, and every fact about it lives in //! this registry, keyed by the SHA-256 of the secret. Consequences, all //! deliberate: //! //! - revoking is deleting (or stamping `revoked_at` on) one row, and it //! takes effect on the next request, with no restart and no //! configuration reload; //! - a token in a log line, a screenshot or a bug report reveals nothing; //! - the registry is authoritative for who the caller is and how long //! the token lives -- not whatever was signed into the string; //! - and if the registry is lost, every short token stops working: they //! cannot be recovered from their hashes or enumerated. //! //! Why SQLite rather than a JSON file: the registry is written at mint //! and revoke time *and* on use (`last_used_at`), from the server and //! from the admin CLI at the same time. A JSON file would need //! rewriting per request and an mtime watch to notice a revocation; //! SQLite gives atomic single-row updates, a WAL so readers do not //! block the writer, and `PRAGMA data_version` as a cheap signal that //! another connection committed -- which is how the in-process cache //! knows to reload instead of guessing a TTL. //! //! Format: `gn4ai_` + 56 body characters + 2 checksum characters = 64 //! characters in total (the two checksum characters come out of the 58 //! the first draft gave the body, so the token stays the documented 64 //! long while a typo is caught before any lookup). The alphabet is 31 //! symbols (`23456789abcdefghjkmnpqrstuvwxyz`: no //! 0/O, 1/l/I, and no `- _ + / =`) so the token survives being pasted, //! double-clicked, quoted in a shell or dropped into a header, and the //! fixed prefix lets the auth extractor branch before it tries to //! validate a JWT. 56 body characters over 31 symbols is ~277 bits. use std::collections::HashMap; use std::path::Path; use std::sync::{Mutex, OnceLock}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; use rusqlite::{Connection, OptionalExtension}; /// The scheme marker. The extractor branches on this before anything /// else, and secret scanners can flag it. pub const PREFIX: &str = "gn4ai_"; const ALPHABET: &[u8] = b"23456789abcdefghjkmnpqrstuvwxyz"; const BODY_LEN: usize = 56; const CHECKSUM_LEN: usize = 2; /// `PREFIX.len() + BODY_LEN + CHECKSUM_LEN`, and also the hard cap on /// any credential we will look at (see `plausible`). pub const TOTAL_LEN: usize = PREFIX.len() + BODY_LEN + CHECKSUM_LEN; /// The longest a token may live when minted without an explicit TTL. pub const DEFAULT_TTL_DAYS: i64 = 30; /// How often a token's `last_used_at` is written. Updating it on every /// request would turn an indexed read into a write on the hot path. const LAST_USED_GRANULARITY: i64 = 60; fn now() -> i64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs() as i64) .unwrap_or(0) } /// One registered token, as stored: never the secret. #[derive(Debug, Clone)] pub struct Record { pub id: String, pub subject: String, pub scope: String, pub prefix: String, pub created_at: i64, pub expires_at: Option, pub last_used_at: Option, pub note: Option, pub revoked_at: Option, } impl Record { pub fn expired(&self, at: i64) -> bool { self.expires_at.is_some_and(|expires| expires <= at) } pub fn revoked(&self) -> bool { self.revoked_at.is_some() } /// Whether this token may authenticate a request right now. pub fn usable(&self, at: i64) -> bool { !self.revoked() && !self.expired(at) } } // ---- the secret itself ---------------------------------------------------- /// The checksum covers the body, so a typo is refused before the /// registry is consulted: "not a token we could have minted" is a /// different answer from "no such token". fn checksum(body: &[u8]) -> [u8; CHECKSUM_LEN] { // Two independent accumulators over the body, each folded into the // alphabet. Order-sensitive (unlike a plain sum) so a transposition // is caught. let mut a: u64 = 0xcbf2_9ce4_8422_2325; let mut b: u64 = 0x9e37_79b9_7f4a_7c15; for (i, byte) in body.iter().enumerate() { a = a.wrapping_mul(0x1000_0000_01b3).wrapping_add(*byte as u64); b = b.rotate_left(7) ^ ((*byte as u64).wrapping_add(i as u64 + 1)); } [ ALPHABET[(a % ALPHABET.len() as u64) as usize], ALPHABET[(b % ALPHABET.len() as u64) as usize], ] } /// A fresh secret: the only time it exists in a form anyone can read. /// /// Randomness comes from `/dev/urandom` rather than a new crate: the /// platforms this runs on all have it, and adding a dependency would /// mean regenerating the crate list in `guix.scm` (see docs/dev/SKILL.md /// on Cargo.lock drift). pub fn mint_secret() -> Result { use std::io::Read; let mut words = [0u8; BODY_LEN * 4]; std::fs::File::open("/dev/urandom") .and_then(|mut random| random.read_exact(&mut words)) .map_err(|e| format!("cannot read /dev/urandom: {e}"))?; let mut body = String::with_capacity(BODY_LEN); for chunk in words.chunks_exact(4) { let word = u32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]) as usize; // 2^32 is not a multiple of 31, so the modulo is very slightly // biased (~2^-27); irrelevant at this entropy. body.push(ALPHABET[word % ALPHABET.len()] as char); } let sum = checksum(body.as_bytes()); Ok(format!( "{PREFIX}{body}{}", std::str::from_utf8(&sum).expect("ascii") )) } /// Cheap shape check: prefix, length, alphabet, checksum. Says nothing /// about whether the token exists. pub fn plausible(secret: &str) -> bool { let Some(body) = secret.strip_prefix(PREFIX) else { return false; }; if body.len() != BODY_LEN + CHECKSUM_LEN || body.bytes().any(|b| !ALPHABET.contains(&b)) { return false; } let (body, sum) = body.split_at(BODY_LEN); checksum(body.as_bytes()) == sum.as_bytes() } /// SHA-256 of the secret, hex: the registry key. The secret itself is /// never stored, so this is one-way by construction. pub fn digest(secret: &str) -> String { crate::indexer::sha256::hex_digest(secret.as_bytes()) } /// The first characters of the secret, for `who` and for correlating an /// access-log line with a registry row without keeping the secret. pub fn display_prefix(secret: &str) -> String { secret.chars().take(PREFIX.len() + 8).collect() } // ---- the registry --------------------------------------------------------- /// An open registry. Cloned handles share one connection (rusqlite's /// `Connection` is not `Sync`, so a mutex wraps it). #[derive(Clone)] pub struct Registry { path: String, connection: std::sync::Arc>, /// hash -> (the `data_version` it was read at, the row) cache: std::sync::Arc>>, } fn schema(connection: &Connection) -> rusqlite::Result<()> { connection.execute_batch( "CREATE TABLE IF NOT EXISTS token ( id TEXT PRIMARY KEY, hash TEXT NOT NULL UNIQUE, prefix TEXT NOT NULL, subject TEXT NOT NULL, scope TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER, last_used_at INTEGER, last_used_ip TEXT, revoked_at INTEGER, note TEXT ); CREATE INDEX IF NOT EXISTS token_hash_idx ON token (hash);", ) } impl Registry { /// Open (creating if needed) the registry at `path`. /// /// The file is a secret store: it is created or tightened to mode /// 0600, so a token hash and its subject are not world-readable. pub fn open(path: &str) -> Result { let connection = Connection::open(path).map_err(|e| format!("{path}: {e}"))?; connection .busy_timeout(Duration::from_secs(5)) .and_then(|_| connection.pragma_update(None, "journal_mode", "WAL")) .map_err(|e| format!("{path}: {e}"))?; schema(&connection).map_err(|e| format!("{path}: {e}"))?; restrict(path)?; Ok(Self { path: path.to_string(), connection: std::sync::Arc::new(Mutex::new(connection)), cache: std::sync::Arc::new(Mutex::new(HashMap::new())), }) } pub fn path(&self) -> &str { &self.path } fn with(&self, f: impl FnOnce(&Connection) -> rusqlite::Result) -> Result { let guard = self.connection.lock().map_err(|_| "registry lock poisoned".to_string())?; f(&guard).map_err(|e| e.to_string()) } /// `PRAGMA data_version` changes when another connection commits. /// That is the cache-invalidation signal: revocation stays immediate /// without re-reading on every request, and without a TTL guess. fn data_version(&self) -> Result { self.with(|connection| { connection.pragma_query_value(None, "data_version", |row| row.get::<_, i64>(0)) }) } /// Mint a token for `subject`. Returns the secret -- the only time /// it can be shown -- and the stored record. pub fn mint( &self, id: &str, subject: &str, scope: &str, ttl_days: Option, note: Option<&str>, ) -> Result<(String, Record), String> { let secret = mint_secret()?; let hash = digest(&secret); let at = now(); let expires_at = Some(at + ttl_days.unwrap_or(DEFAULT_TTL_DAYS) * 86_400); let record = Record { id: id.to_string(), subject: subject.to_string(), scope: scope.to_string(), prefix: display_prefix(&secret), created_at: at, expires_at, last_used_at: None, note: note.map(str::to_string), revoked_at: None, }; self.with(|connection| { connection.execute( "INSERT INTO token (id, hash, prefix, subject, scope, created_at, expires_at, note) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)", rusqlite::params![ record.id, hash, record.prefix, record.subject, record.scope, record.created_at, record.expires_at, record.note, ], ) })?; self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?.clear(); Ok((secret, record)) } /// Look a secret up, refusing one that is revoked, expired or not a /// token we could have minted. /// /// A successful lookup counts as use: `last_used_at` is refreshed at /// most once a minute. pub fn authenticate(&self, secret: &str, peer: Option<&str>) -> Result, String> { if !plausible(secret) { return Ok(None); } let hash = digest(secret); let record = match self.cached(&hash)? { Some(record) => record, None => return Ok(None), }; let at = now(); if !record.usable(at) { return Ok(None); } let stale = record .last_used_at .is_none_or(|used| at - used >= LAST_USED_GRANULARITY); if stale { // Best effort: a failed bookkeeping write must not fail the // request that the token is valid for. let written = self .with(|connection| { connection.execute( "UPDATE token SET last_used_at = ?1, last_used_ip = ?2 WHERE hash = ?3", rusqlite::params![at, peer, hash], ) }) .is_ok(); if written { // The cache is only invalidated by *other* connections' // commits (that is what `data_version` reports), so drop the // entry ourselves or the next request would see the old // `last_used_at` and write again immediately. if let Ok(mut cache) = self.cache.lock() { cache.remove(&hash); } } } Ok(Some(record)) } fn cached(&self, hash: &str) -> Result, String> { let version = self.data_version()?; { let cache = self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?; if let Some((seen, record)) = cache.get(hash) { if *seen == version { return Ok(Some(record.clone())); } } } // Stale or absent: this connection's own version moved, or another // writer committed. Either way, re-read and re-cache. let record = self.by_hash(hash)?; let recorded_version = self.data_version()?; if let Some(record) = &record { let mut cache = self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?; // Store under the version read *after* the row, so a commit that // landed in between invalidates on the next use. cache.insert(hash.to_string(), (recorded_version, record.clone())); } Ok(record) } fn by_hash(&self, hash: &str) -> Result, String> { self.with(|connection| { connection .query_row( "SELECT id, subject, scope, prefix, created_at, expires_at, last_used_at, note, revoked_at FROM token WHERE hash = ?1", rusqlite::params![hash], row_to_record, ) .optional() }) } /// Every token, secrets never included. pub fn list(&self) -> Result, String> { self.with(|connection| { let mut statement = connection.prepare( "SELECT id, subject, scope, prefix, created_at, expires_at, last_used_at, note, revoked_at FROM token ORDER BY created_at, id", )?; let rows = statement.query_map([], row_to_record)?; rows.collect() }) } /// Revoke by id; returns whether a live row was stamped. /// /// Soft, so `who` can still explain a stale token ("revoked on ...") /// rather than claiming it never existed. pub fn revoke(&self, id: &str) -> Result { let at = now(); let changed = self.with(|connection| { connection.execute( "UPDATE token SET revoked_at = ?1 WHERE id = ?2 AND revoked_at IS NULL", rusqlite::params![at, id], ) })?; self.cache.lock().map_err(|_| "cache lock poisoned".to_string())?.clear(); Ok(changed > 0) } /// The record for a secret, revoked or not: what `who` answers. pub fn describe(&self, secret: &str) -> Result, String> { if !plausible(secret) { return Ok(None); } self.by_hash(&digest(secret)) } } fn row_to_record(row: &rusqlite::Row<'_>) -> rusqlite::Result { Ok(Record { id: row.get(0)?, subject: row.get(1)?, scope: row.get(2)?, prefix: row.get(3)?, created_at: row.get(4)?, expires_at: row.get(5)?, last_used_at: row.get(6)?, note: row.get(7)?, revoked_at: row.get(8)?, }) } /// One registry per path, opened on first use. Config is effectively /// static, but tests point at their own databases. pub fn registry(path: &str) -> Result { static REGISTRIES: OnceLock>>> = OnceLock::new(); let registries = REGISTRIES.get_or_init(|| Mutex::new(HashMap::new())); let mut guard = registries.lock().map_err(|_| "registry cache poisoned".to_string())?; guard .entry(path.to_string()) .or_insert_with(|| Registry::open(path)) .clone() } #[cfg(unix)] fn restrict(path: &str) -> Result<(), String> { use std::os::unix::fs::PermissionsExt; let permissions = std::fs::Permissions::from_mode(0o600); std::fs::set_permissions(Path::new(path), permissions) .map_err(|e| format!("{path}: cannot set mode 0600: {e}")) } #[cfg(not(unix))] fn restrict(_path: &str) -> Result<(), String> { Ok(()) } #[cfg(test)] mod tests { use super::*; fn temp_registry(name: &str) -> Registry { let path = std::env::temp_dir().join(format!("gn4-tokens-{name}-{}.sqlite", std::process::id())); let _ = std::fs::remove_file(&path); Registry::open(&path.to_string_lossy()).expect("registry") } #[test] fn a_minted_secret_is_the_documented_shape() { let secret = mint_secret().expect("random"); assert_eq!(secret.len(), TOTAL_LEN); assert!(secret.starts_with(PREFIX)); assert!(plausible(&secret)); assert!(secret .trim_start_matches(PREFIX) .bytes() .all(|b| ALPHABET.contains(&b))); assert_ne!(secret, mint_secret().expect("random")); } #[test] fn a_typo_is_refused_before_the_registry_is_asked() { let secret = mint_secret().expect("random"); for position in [PREFIX.len(), PREFIX.len() + 20, TOTAL_LEN - 1] { let mut bytes = secret.clone().into_bytes(); bytes[position] = if bytes[position] == b'a' { b'b' } else { b'a' }; let typo = String::from_utf8(bytes).unwrap(); assert!(!plausible(&typo), "position {position} should not look minted"); } assert!(!plausible("gn4ai_short")); assert!(!plausible("not-a-token")); } #[test] fn a_minted_token_authenticates_and_revocation_is_immediate() { let registry = temp_registry("revoke"); let (secret, record) = registry .mint("zachs-1", "zachs", "public", Some(30), Some("hand test")) .expect("mint"); let found = registry.authenticate(&secret, Some("127.0.0.1")).expect("authenticate"); assert_eq!(found.map(|r| r.subject), Some("zachs".to_string())); assert!(registry.revoke(&record.id).expect("revoke")); assert!(registry .authenticate(&secret, None) .expect("authenticate") .is_none()); // ... and `who` still explains it rather than denying it existed. let described = registry.describe(&secret).expect("describe").expect("kept"); assert!(described.revoked()); } #[test] fn an_expired_token_stops_working_without_being_revoked() { let registry = temp_registry("expired"); let (secret, record) = registry .mint("old-1", "old", "public", Some(1), None) .expect("mint"); assert!(record.usable(record.created_at)); assert!(!record.usable(record.created_at + 2 * 86_400)); // A negative TTL mints something already expired, which is how the // test avoids waiting a day. let expired = registry .mint("old-2", "old", "public", Some(-1), None) .expect("mint"); assert!(registry.authenticate(&expired.0, None).expect("authenticate").is_none()); assert!(registry.authenticate(&secret, None).expect("authenticate").is_some()); } #[test] fn last_used_is_recorded_at_most_once_a_minute() { let registry = temp_registry("touch"); let (secret, _) = registry.mint("a-1", "a", "public", Some(30), None).expect("mint"); registry.authenticate(&secret, Some("10.0.0.9")).expect("authenticate"); let first = registry.describe(&secret).unwrap().unwrap().last_used_at.expect("stamped"); std::thread::sleep(std::time::Duration::from_millis(1100)); registry.authenticate(&secret, Some("10.0.0.9")).expect("authenticate"); let second = registry.describe(&secret).unwrap().unwrap().last_used_at.expect("stamped"); assert_eq!(first, second, "a second use within a minute must not rewrite the row"); } #[test] fn an_unknown_but_well_formed_token_is_not_authenticated() { let registry = temp_registry("unknown"); let stranger = mint_secret().expect("random"); assert!(plausible(&stranger)); assert!(registry.authenticate(&stranger, None).expect("authenticate").is_none()); assert!(registry.describe(&stranger).expect("describe").is_none()); } }