about summary refs log tree commit diff
path: root/src/tokens.rs
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:20:54 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:20:54 +0000
commit586b0f63ef31fde987e00a305e91ee4e2136332e (patch)
tree47eea9436d52d4634023b053f99049fa3ff21f39 /src/tokens.rs
parentc822ba22ce00c1615bf47fc8a13f28590aba424a (diff)
downloadgenenetwork4-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.rs538
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());
+    }
+}