hanna/fabrica

feat(auth): argon2id, sessions, HS256 JWTs, and the access model

1f61684 · hanna committed on 2026-07-25

Implement phase 4. `crates/auth` is I/O-free and splits into four concerns:

- password: Argon2id PHC hashing; verification runs full hashing work on the
  missing/malformed-hash paths so account existence never leaks via timing.
- session: 32-byte OsRng tokens, base64url in the cookie, only their SHA-256
  kept server-side as the sessions.id.
- token: HS256 JWTs minted/verified over hmac+sha2 (no `ring`, keeping the
  license set clean); fixed header rejects alg-confusion; revocation stays a
  store concern.
- scope + access: the authorization vocabulary and the single `access()`
  function, with the five ordered rules and an exhaustive viewer × visibility ×
  collaborator × anonymous matrix test.

docs/decisions.md records the hand-rolled JWT and the widened access() signature.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +87 −2

Cargo.toml +11 −0

crates/auth/Cargo.toml +9 −0

crates/auth/src/access.rs +304 −0

crates/auth/src/lib.rs +54 −1

crates/auth/src/password.rs +151 −0

crates/auth/src/scope.rs +135 −0

crates/auth/src/session.rs +94 −0

crates/auth/src/token.rs +216 −0

docs/decisions.md +36 −0

 version = "0.1.0"
 [[package]]
+name = "argon2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+dependencies = [
+ "base64ct",
+ "blake2",
+ "cpufeatures 0.2.17",
+ "password-hash",
+]
+[[package]]
 name = "atoi"
 version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "auth"
 version = "0.1.0"
+dependencies = [
+ "argon2",
+ "base64",
+ "hmac 0.12.1",
+ "model",
+ "rand_core 0.6.4",
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "thiserror",
+]
 [[package]]
 name = "autocfg"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 [[package]]
+name = "base64ct"
+version = "1.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
+[[package]]
 name = "bitflags"
 version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest 0.10.7",
+]
+[[package]]
 name = "block-buffer"
 version = "0.10.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "block-buffer 0.10.4",
  "crypto-common 0.1.6",
+ "subtle",
+]
 [[package]]
 [[package]]
 name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+[[package]]
+name = "getrandom"
 version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018"
 dependencies = [
- "hmac",
+ "hmac 0.13.0",
+]
+[[package]]
+name = "hmac"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
+dependencies = [
+ "digest 0.10.7",
+]
 [[package]]
+]
 [[package]]
+name = "password-hash"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
+dependencies = [
+ "base64ct",
+ "rand_core 0.6.4",
+ "subtle",
+]
+[[package]]
 name = "pear"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom 0.2.17",
+]
+[[package]]
+name = "rand_core"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
  "futures-util",
  "hex",
  "hkdf",
- "hmac",
+ "hmac 0.13.0",
  "itoa",
  "log",
  "md-5",
 checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 [[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+[[package]]
 name = "syn"
 version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"

 ulid = "1"
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 tempfile = "3"
+# Authentication primitives. Argon2id password hashing; SHA-256 for session and
+# invite token digests; HMAC-SHA256 for hand-rolled HS256 JWTs (avoiding a `ring`
+# dependency, whose license set is not in our allow-list — see docs/decisions.md);
+# base64url for token encoding; OsRng for salts and session bytes.
+argon2 = { version = "0.5", features = ["std"] }
+sha2 = "0.10"
+hmac = "0.12"
+base64 = "0.22"
+rand_core = { version = "0.6", features = ["getrandom"] }
+# Interactive, non-echoing password entry for the CLI.
+rpassword = "7"
 [workspace.lints.rust]
 unsafe_code = "forbid"

 publish.workspace = true
 [dependencies]
+model = { workspace = true }
+argon2 = { workspace = true }
+sha2 = { workspace = true }
+hmac = { workspace = true }
+base64 = { workspace = true }
+rand_core = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
 [lints]
 workspace = true

 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-//! Authentication and authorization: argon2id, sessions, JWTs, and `access()`.
+//! Authentication and authorization primitives.
+//!
+//! This crate is deliberately I/O-free: it turns bytes into decisions and never
+//! touches the database or the network. The [`store`](../store/index.html) crate
+//! persists what these functions produce (password hashes, session-id digests,
+//! token rows) and the `web`/`api`/`ssh` crates call in at request time.
+//!
+//! Four concerns, one per module:
+//!
+//! * [`password`] — Argon2id hashing and constant-time verification. A missing
+//!   hash still does the work of a real verify so account existence never leaks
+//!   through timing.
+//! * [`session`] — opaque session tokens: 32 bytes of OS randomness handed to the
+//!   browser, only their SHA-256 kept server-side.
+//! * [`token`] — HS256 JSON Web Tokens for the API, minted and verified against
+//!   the instance secret. Revocation is a database concern; this module only
+//!   proves a token is authentic and unexpired.
+//! * [`scope`] and [`access`] — the authorization vocabulary. [`access::access`]
+//!   is the single, exhaustively tested function every route funnels through.
+pub mod access;
+pub mod password;
+pub mod scope;
+pub mod session;
+pub mod token;
+pub use access::{Access, Permission, Viewer, access};
+pub use password::{HashParams, hash_password, verify_password};
+pub use scope::{Scope, format_scopes, parse_scopes};
+pub use session::{SESSION_TOKEN_BYTES, SessionToken, new_session_token, session_id};
+pub use token::{Claims, mint_jwt, verify_jwt};
+/// Errors produced by the authentication primitives.
+///
+/// Variants stay coarse on purpose: a caller authenticating a request should not
+/// be able to tell *why* a credential failed (bad signature vs. expired vs.
+/// malformed), so verification failures collapse into a single
+/// [`AuthError::InvalidToken`].
+#[derive(Debug, thiserror::Error)]
+pub enum AuthError {
+    /// A password could not be hashed, or a stored hash could not be parsed.
+    /// Carries the library's message; never contains the password itself.
+    #[error("password hashing failed: {0}")]
+    Hash(String),
+    /// A JWT was malformed, carried a bad signature, or had expired. One variant
+    /// for every failure mode so nothing distinguishes them to the caller.
+    #[error("invalid or expired token")]
+    InvalidToken,
+    /// A scope string held a token outside the known set.
+    #[error("unknown scope {0:?}")]
+    UnknownScope(String),
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Argon2id password hashing and verification.
+//!
+//! Hashes are stored in PHC string format, which embeds the algorithm, version,
+//! and cost parameters — so a stored hash is self-describing and verification
+//! never needs the config that produced it. That matters when the operator tunes
+//! the cost parameters over time: old hashes keep verifying against the costs
+//! they were made with.
+use argon2::password_hash::rand_core::OsRng;
+use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
+use argon2::{Algorithm, Argon2, Params, Version};
+use crate::AuthError;
+/// Argon2id cost parameters, mirroring the `[auth]` config keys. Kept as a plain
+/// value type so the `auth` crate need not depend on `config`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct HashParams {
+    /// Memory cost, in KiB (`auth.argon2_m_cost`).
+    pub m_cost: u32,
+    /// Time cost — the number of iterations (`auth.argon2_t_cost`).
+    pub t_cost: u32,
+    /// Degree of parallelism — lanes (`auth.argon2_p_cost`).
+    pub p_cost: u32,
+}
+impl Default for HashParams {
+    /// The spec's baseline: 19 MiB, two iterations, one lane.
+    fn default() -> Self {
+        Self {
+            m_cost: 19_456,
+            t_cost: 2,
+            p_cost: 1,
+        }
+    }
+}
+impl HashParams {
+    /// Build the concrete Argon2 hasher for these parameters.
+    fn hasher(self) -> Result<Argon2<'static>, AuthError> {
+        let params = Params::new(self.m_cost, self.t_cost, self.p_cost, None)
+            .map_err(|e| AuthError::Hash(e.to_string()))?;
+        Ok(Argon2::new(Algorithm::Argon2id, Version::V0x13, params))
+    }
+}
+/// Hash `password` with Argon2id, returning a PHC string ready to store.
+///
+/// A fresh random salt is drawn from the OS CSPRNG for every call, so identical
+/// passwords produce different hashes.
+///
+/// # Errors
+///
+/// Returns [`AuthError::Hash`] if the cost parameters are invalid or the hasher
+/// fails.
+pub fn hash_password(password: &str, params: HashParams) -> Result<String, AuthError> {
+    let salt = SaltString::generate(&mut OsRng);
+    let hash = params
+        .hasher()?
+        .hash_password(password.as_bytes(), &salt)
+        .map_err(|e| AuthError::Hash(e.to_string()))?;
+    Ok(hash.to_string())
+}
+/// Verify `password` against a stored PHC hash.
+///
+/// `stored` is [`Option`] because a user may have no password yet (the invite is
+/// still outstanding). In that case — and whenever the stored hash fails to parse
+/// — we still run a full Argon2 computation against a throwaway salt before
+/// returning `false`, so the "no such credential" path costs the same as a real
+/// verification and account state does not leak through response timing.
+///
+/// Returns `true` only when the password matches a well-formed stored hash.
+#[must_use]
+pub fn verify_password(password: &str, stored: Option<&str>) -> bool {
+    let Some(hash) = stored else {
+        dummy_verify(password);
+        return false;
+    };
+    let Ok(parsed) = PasswordHash::new(hash) else {
+        dummy_verify(password);
+        return false;
+    };
+    // Argon2id verification reads its parameters from the PHC string itself, so a
+    // default-configured verifier honours whatever costs the hash was made with.
+    Argon2::default()
+        .verify_password(password.as_bytes(), &parsed)
+        .is_ok()
+}
+/// Perform throwaway hashing work to equalise the timing of the failure paths in
+/// [`verify_password`]. The result is intentionally discarded.
+fn dummy_verify(password: &str) {
+    let _ = hash_password(password, HashParams::default());
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    // Cheap parameters keep the hashing tests fast; production costs come from
+    // config. The minimum Argon2 memory cost is 8 KiB.
+    const FAST: HashParams = HashParams {
+        m_cost: 8,
+        t_cost: 1,
+        p_cost: 1,
+    };
+    #[test]
+    fn hash_is_phc_argon2id_and_verifies() {
+        let hash = hash_password("correct horse", FAST).unwrap();
+        assert!(hash.starts_with("$argon2id$"), "PHC prefix, got {hash}");
+        assert!(verify_password("correct horse", Some(&hash)));
+        assert!(!verify_password("wrong horse", Some(&hash)));
+    }
+    #[test]
+    fn hashing_is_salted() {
+        let a = hash_password("same", FAST).unwrap();
+        let b = hash_password("same", FAST).unwrap();
+        assert_ne!(a, b, "distinct salts should yield distinct hashes");
+        assert!(verify_password("same", Some(&a)));
+        assert!(verify_password("same", Some(&b)));
+    }
+    #[test]
+    fn absent_hash_never_verifies() {
+        assert!(!verify_password("anything", None));
+    }
+    #[test]
+    fn malformed_hash_never_verifies() {
+        assert!(!verify_password("anything", Some("not-a-phc-string")));
+        assert!(!verify_password("anything", Some("$argon2id$garbage")));
+    }
+    #[test]
+    fn params_round_trip_through_the_hash() {
+        // A hash made with non-default costs still verifies with the default
+        // verifier, because the costs travel inside the PHC string.
+        let hash = hash_password("pw", FAST).unwrap();
+        assert!(hash.contains("m=8"), "params embedded, got {hash}");
+        assert!(verify_password("pw", Some(&hash)));
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! The permission model: one function, [`access`], that every route funnels
+//! through.
+//!
+//! Keeping authorization in a single pure function is what makes it testable to
+//! exhaustion (see the matrix test below) and impossible for a route to get
+//! subtly wrong. The function takes everything it needs by value or reference and
+//! returns a verdict; the *consequences* of that verdict — in particular that
+//! [`Access::None`] on a private repo renders `404`, never `403`, so existence
+//! does not leak — belong to the web and API layers.
+use model::Repo;
+/// The access level a viewer has to a repository, in increasing order of power.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Access {
+    /// No access. On a private repo the caller MUST render `404`, not `403`.
+    None,
+    /// May read: browse, clone, and read-only API.
+    Read,
+    /// May read and push.
+    Write,
+    /// May read, push, and administer (settings, collaborators, deletion).
+    Admin,
+}
+/// A stored collaborator permission — the `repo_collaborators.permission` column.
+///
+/// Distinct from [`Access`] because a collaborator row can never say "no access"
+/// (its absence does); the two convert one way, [`Permission`] into [`Access`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Permission {
+    /// Read-only collaborator.
+    Read,
+    /// Read-write collaborator.
+    Write,
+    /// Administrative collaborator.
+    Admin,
+}
+impl Permission {
+    /// The wire/database spelling (`read` | `write` | `admin`).
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Read => "read",
+            Self::Write => "write",
+            Self::Admin => "admin",
+        }
+    }
+    /// Parse a stored permission string, returning `None` for anything
+    /// unrecognized (a corrupt row grants nothing rather than panicking).
+    #[must_use]
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "read" => Some(Self::Read),
+            "write" => Some(Self::Write),
+            "admin" => Some(Self::Admin),
+            _ => None,
+        }
+    }
+}
+impl From<Permission> for Access {
+    fn from(permission: Permission) -> Self {
+        match permission {
+            Permission::Read => Self::Read,
+            Permission::Write => Self::Write,
+            Permission::Admin => Self::Admin,
+        }
+    }
+}
+/// The authenticated identity making a request, as far as authorization cares.
+///
+/// Anonymous requests pass `None` in place of a `Viewer`. A disabled account must
+/// never be turned into a `Viewer` — that check belongs to the authentication
+/// layer, upstream of every call here.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Viewer {
+    /// The viewer's user id (`users.id`).
+    pub id: String,
+    /// Whether the viewer is a site administrator.
+    pub is_admin: bool,
+}
+/// Resolve the access `viewer` has to `repo`.
+///
+/// The rules are applied strictly in order; the first that matches wins:
+///
+/// 1. a site admin gets [`Access::Admin`];
+/// 2. the repo's owner gets [`Access::Admin`];
+/// 3. an explicit collaborator gets exactly their stored permission;
+/// 4. a public repo, when the instance allows anonymous access, grants
+///    [`Access::Read`] to anyone;
+/// 5. otherwise [`Access::None`].
+///
+/// `collaborator` is the viewer's row in `repo_collaborators` for this repo, if
+/// any; the caller looks it up. `allow_anonymous` is `instance.allow_anonymous`.
+/// Note rule 4 is gated on that flag for *every* viewer, so disabling anonymous
+/// access closes public repos to non-collaborators as well — matching the spec's
+/// private-by-default posture.
+#[must_use]
+pub fn access(
+    viewer: Option<&Viewer>,
+    repo: &Repo,
+    collaborator: Option<Permission>,
+    allow_anonymous: bool,
+) -> Access {
+    if let Some(v) = viewer {
+        if v.is_admin {
+            return Access::Admin;
+        }
+        if v.id == repo.owner_id {
+            return Access::Admin;
+        }
+        if let Some(permission) = collaborator {
+            return permission.into();
+        }
+    }
+    if !repo.is_private && allow_anonymous {
+        return Access::Read;
+    }
+    Access::None
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    /// A repo owned by `owner`, with the given visibility. Only the fields
+    /// `access` reads are meaningful; the rest are filler.
+    fn repo(owner: &str, is_private: bool) -> Repo {
+        Repo {
+            id: "01reporeporeporeporeporepo".to_string(),
+            owner_id: owner.to_string(),
+            group_id: None,
+            name: "r".to_string(),
+            path: "r".to_string(),
+            description: None,
+            is_private,
+            default_branch: "main".to_string(),
+            archived_at: None,
+            size_bytes: 0,
+            pushed_at: None,
+            created_at: 0,
+            updated_at: 0,
+        }
+    }
+    fn viewer(id: &str, is_admin: bool) -> Viewer {
+        Viewer {
+            id: id.to_string(),
+            is_admin,
+        }
+    }
+    #[test]
+    fn permission_strings_round_trip() {
+        for p in [Permission::Read, Permission::Write, Permission::Admin] {
+            assert_eq!(Permission::parse(p.as_str()), Some(p));
+        }
+        assert_eq!(Permission::parse("owner"), None);
+    }
+    #[test]
+    fn access_is_ordered() {
+        assert!(Access::None < Access::Read);
+        assert!(Access::Read < Access::Write);
+        assert!(Access::Write < Access::Admin);
+    }
+    /// One row of the access matrix: the inputs and the verdict they must yield.
+    struct Case {
+        viewer: Option<Viewer>,
+        collaborator: Option<Permission>,
+        is_private: bool,
+        allow_anonymous: bool,
+        expect: Access,
+    }
+    /// The whole point of this crate: enumerate every combination of viewer kind,
+    /// visibility, collaborator permission, and the anonymous-access flag, and
+    /// assert the exact verdict. Nothing here is sampled — it is the full matrix.
+    #[test]
+    fn access_matrix_is_exhaustive() {
+        // Viewer kinds, expressed relative to a repo owned by "owner".
+        let admin = viewer("boss", true);
+        let owner = viewer("owner", false);
+        let other = viewer("stranger", false);
+        let mut cases = Vec::new();
+        let mut push = |viewer: Option<&Viewer>,
+                        collaborator: Option<Permission>,
+                        is_private: bool,
+                        allow_anonymous: bool,
+                        expect: Access| {
+            cases.push(Case {
+                viewer: viewer.cloned(),
+                collaborator,
+                is_private,
+                allow_anonymous,
+                expect,
+            });
+        };
+        // Rule 1: a site admin is Admin everywhere, regardless of every other
+        // dimension.
+        for &private in &[true, false] {
+            for &anon in &[true, false] {
+                for collab in [None, Some(Permission::Read)] {
+                    push(Some(&admin), collab, private, anon, Access::Admin);
+                }
+            }
+        }
+        // Rule 2: the owner is Admin everywhere, even with a lesser collaborator
+        // row somehow present, and even when anonymous access is off.
+        for &private in &[true, false] {
+            for &anon in &[true, false] {
+                for collab in [None, Some(Permission::Read), Some(Permission::Write)] {
+                    push(Some(&owner), collab, private, anon, Access::Admin);
+                }
+            }
+        }
+        // Rule 3: an explicit collaborator gets exactly their permission — this
+        // beats rule 4, so it holds even on a public repo, and is unaffected by
+        // the anonymous flag or visibility.
+        for &private in &[true, false] {
+            for &anon in &[true, false] {
+                push(
+                    Some(&other),
+                    Some(Permission::Read),
+                    private,
+                    anon,
+                    Access::Read,
+                );
+                push(
+                    Some(&other),
+                    Some(Permission::Write),
+                    private,
+                    anon,
+                    Access::Write,
+                );
+                push(
+                    Some(&other),
+                    Some(Permission::Admin),
+                    private,
+                    anon,
+                    Access::Admin,
+                );
+            }
+        }
+        // Rule 4 / 5: a non-collaborator (authenticated stranger or anonymous)
+        // reads a public repo only when anonymous access is allowed; a private
+        // repo is always None; and anon-off closes public repos too.
+        for viewer in [Some(&other), None] {
+            // Public repo, anonymous allowed -> Read.
+            push(viewer, None, false, true, Access::Read);
+            // Public repo, anonymous disallowed -> None.
+            push(viewer, None, false, false, Access::None);
+            // Private repo -> None regardless of the flag.
+            push(viewer, None, true, true, Access::None);
+            push(viewer, None, true, false, Access::None);
+        }
+        for case in &cases {
+            let repo = repo("owner", case.is_private);
+            let got = access(
+                case.viewer.as_ref(),
+                &repo,
+                case.collaborator,
+                case.allow_anonymous,
+            );
+            assert_eq!(
+                got, case.expect,
+                "viewer={:?} collab={:?} private={} anon={}",
+                case.viewer, case.collaborator, case.is_private, case.allow_anonymous
+            );
+        }
+    }
+    #[test]
+    fn private_repo_never_leaks_to_a_stranger() {
+        // The security-critical invariant, called out on its own: no combination
+        // of a non-privileged stranger on a private repo yields anything but None.
+        let stranger = viewer("stranger", false);
+        for &anon in &[true, false] {
+            assert_eq!(
+                access(Some(&stranger), &repo("owner", true), None, anon),
+                Access::None
+            );
+            assert_eq!(access(None, &repo("owner", true), None, anon), Access::None);
+        }
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! API token scopes.
+//!
+//! A token carries a comma-separated scope list, stored verbatim in
+//! `api_tokens.scopes` and echoed inside the JWT. The wire spelling
+//! (`repo:read`, …) is the single source of truth; this module is the only place
+//! that maps those strings to and from the [`Scope`] enum.
+use crate::AuthError;
+/// A capability a token may grant. The string forms match the spec exactly and
+/// are what appears in config, the CLI, and the JWT payload.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Scope {
+    /// Read repository contents (clone, browse, read API).
+    RepoRead,
+    /// Push to repositories and mutate their contents.
+    RepoWrite,
+    /// Administer repositories (settings, collaborators, deletion).
+    RepoAdmin,
+    /// Read user and account information.
+    UserRead,
+    /// Mutate user and account information.
+    UserWrite,
+    /// Full administrative access, equivalent to a site admin.
+    Admin,
+}
+impl Scope {
+    /// The canonical wire spelling.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::RepoRead => "repo:read",
+            Self::RepoWrite => "repo:write",
+            Self::RepoAdmin => "repo:admin",
+            Self::UserRead => "user:read",
+            Self::UserWrite => "user:write",
+            Self::Admin => "admin",
+        }
+    }
+    /// Parse a single scope token.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`AuthError::UnknownScope`] if `s` is not a known scope. Leading
+    /// and trailing whitespace is tolerated so a hand-written `--scopes a, b`
+    /// list parses.
+    pub fn parse(s: &str) -> Result<Self, AuthError> {
+        match s.trim() {
+            "repo:read" => Ok(Self::RepoRead),
+            "repo:write" => Ok(Self::RepoWrite),
+            "repo:admin" => Ok(Self::RepoAdmin),
+            "user:read" => Ok(Self::UserRead),
+            "user:write" => Ok(Self::UserWrite),
+            "admin" => Ok(Self::Admin),
+            other => Err(AuthError::UnknownScope(other.to_string())),
+        }
+    }
+}
+/// Parse a comma-separated scope list. Empty entries (a trailing comma, or an
+/// entirely blank string) are skipped rather than rejected.
+///
+/// # Errors
+///
+/// Returns [`AuthError::UnknownScope`] on the first unrecognized entry.
+pub fn parse_scopes(list: &str) -> Result<Vec<Scope>, AuthError> {
+    list.split(',')
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(Scope::parse)
+        .collect()
+}
+/// Render scopes as the canonical comma-separated string stored in the database.
+#[must_use]
+pub fn format_scopes(scopes: &[Scope]) -> String {
+    scopes
+        .iter()
+        .map(|s| s.as_str())
+        .collect::<Vec<_>>()
+        .join(",")
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    #[test]
+    fn every_scope_round_trips() {
+        for scope in [
+            Scope::RepoRead,
+            Scope::RepoWrite,
+            Scope::RepoAdmin,
+            Scope::UserRead,
+            Scope::UserWrite,
+            Scope::Admin,
+        ] {
+            assert_eq!(Scope::parse(scope.as_str()).unwrap(), scope);
+        }
+    }
+    #[test]
+    fn list_parses_and_reformats_canonically() {
+        let scopes = parse_scopes(" repo:read, repo:write ,admin ").unwrap();
+        assert_eq!(scopes, [Scope::RepoRead, Scope::RepoWrite, Scope::Admin]);
+        assert_eq!(format_scopes(&scopes), "repo:read,repo:write,admin");
+    }
+    #[test]
+    fn blank_and_trailing_commas_are_ignored() {
+        assert!(parse_scopes("").unwrap().is_empty());
+        assert_eq!(
+            parse_scopes("repo:read,,").unwrap(),
+            [Scope::RepoRead],
+            "empty entries dropped, not rejected"
+        );
+    }
+    #[test]
+    fn unknown_scope_is_rejected() {
+        let err = parse_scopes("repo:read,repo:destroy").unwrap_err();
+        assert!(
+            matches!(&err, AuthError::UnknownScope(s) if s == "repo:destroy"),
+            "got {err:?}"
+        );
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Opaque session tokens.
+//!
+//! A session token is 32 bytes of OS randomness, base64url-encoded and handed to
+//! the browser in a cookie. The database stores **only** the SHA-256 of that
+//! cookie value as the session-row id, so a leak of the database does not leak
+//! usable session tokens: an attacker would still need the pre-image. Lookup
+//! hashes the presented cookie the same way and matches on the digest.
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use rand_core::{OsRng, RngCore};
+use sha2::{Digest, Sha256};
+/// Number of random bytes behind a session token, before encoding.
+pub const SESSION_TOKEN_BYTES: usize = 32;
+/// A freshly minted session token, split into the two halves that live in
+/// different places.
+#[derive(Debug, Clone)]
+pub struct SessionToken {
+    /// The value placed in the user's cookie. Secret — treat like a password.
+    pub cookie: String,
+    /// The SHA-256 of [`SessionToken::cookie`], stored as the `sessions.id`
+    /// primary key. Safe to persist and log.
+    pub id: String,
+}
+/// Mint a new session token: draw 32 bytes from the OS CSPRNG, encode them for
+/// the cookie, and derive the id the database will key on.
+#[must_use]
+pub fn new_session_token() -> SessionToken {
+    let mut bytes = [0u8; SESSION_TOKEN_BYTES];
+    OsRng.fill_bytes(&mut bytes);
+    let cookie = URL_SAFE_NO_PAD.encode(bytes);
+    let id = session_id(&cookie);
+    SessionToken { cookie, id }
+}
+/// Derive the `sessions.id` for a presented cookie value. This is the one place
+/// the cookie-to-id mapping is defined; login (minting) and every subsequent
+/// request (lookup) both route through it so they cannot disagree.
+#[must_use]
+pub fn session_id(cookie: &str) -> String {
+    let digest = Sha256::digest(cookie.as_bytes());
+    hex(&digest)
+}
+/// Lowercase hex encoding of a byte slice.
+fn hex(bytes: &[u8]) -> String {
+    use std::fmt::Write as _;
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for b in bytes {
+        // Writing to a String is infallible.
+        let _ = write!(out, "{b:02x}");
+    }
+    out
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn tokens_are_unique_and_hex_ided() {
+        let a = new_session_token();
+        let b = new_session_token();
+        assert_ne!(a.cookie, b.cookie, "each token draws fresh randomness");
+        assert_ne!(a.id, b.id);
+        // SHA-256 hex is 64 characters, all hex digits.
+        assert_eq!(a.id.len(), 64);
+        assert!(a.id.bytes().all(|c| c.is_ascii_hexdigit()));
+    }
+    #[test]
+    fn id_is_a_pure_function_of_the_cookie() {
+        let token = new_session_token();
+        assert_eq!(
+            session_id(&token.cookie),
+            token.id,
+            "lookup must reproduce the stored id"
+        );
+    }
+    #[test]
+    fn different_cookies_hash_differently() {
+        assert_ne!(session_id("a"), session_id("b"));
+        // Known-answer: SHA-256("") has a well-known digest prefix.
+        assert!(session_id("").starts_with("e3b0c44298fc1c14"));
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! HS256 JSON Web Tokens for the API.
+//!
+//! We hand-roll the (small, well-specified) HS256 construction rather than pull
+//! in a JWT library, because the mainstream crates depend on `ring`, whose
+//! license set falls outside this project's allow-list. The surface we need is
+//! tiny: base64url of a fixed header and a JSON payload, an HMAC-SHA256 over the
+//! two, and constant-time verification of the same.
+//!
+//! Signature and expiry are all this module proves. **Revocation is not checked
+//! here** — a valid signature only means the token is authentic and unexpired.
+//! Callers MUST additionally confirm the `jti` row in `api_tokens` has
+//! `revoked_at IS NULL`; that database check is what makes revocation real.
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use hmac::{Hmac, Mac};
+use serde::{Deserialize, Serialize};
+use sha2::Sha256;
+use crate::AuthError;
+type HmacSha256 = Hmac<Sha256>;
+/// The fixed JOSE header for every token we mint: `{"alg":"HS256","typ":"JWT"}`.
+/// Pre-encoded so minting never re-serializes it, and matched exactly on verify
+/// so a token advertising any other algorithm is rejected out of hand (closing
+/// the classic "alg" confusion attack).
+const HEADER_B64: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
+/// The claims carried by an API token. Field names are the JWT wire names.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Claims {
+    /// Subject: the owning user's id (`users.id`).
+    pub sub: String,
+    /// JWT id: the `api_tokens` row id, checked against `revoked_at` on every
+    /// request to enforce revocation.
+    pub jti: String,
+    /// Comma-separated scope list (see [`crate::scope`]).
+    pub scopes: String,
+    /// Issued-at, Unix seconds.
+    pub iat: i64,
+    /// Expiry, Unix seconds. A token is rejected once `exp <= now`.
+    pub exp: i64,
+}
+/// Mint a signed HS256 token for `claims`, signed with the instance `secret`.
+///
+/// # Errors
+///
+/// Returns [`AuthError::Hash`] if the claims cannot be serialized (in practice
+/// only an allocation failure), reusing that variant to avoid widening the error
+/// enum for an all-but-impossible case.
+pub fn mint_jwt(secret: &str, claims: &Claims) -> Result<String, AuthError> {
+    let payload_json =
+        serde_json::to_vec(claims).map_err(|e| AuthError::Hash(format!("claims: {e}")))?;
+    let payload_b64 = URL_SAFE_NO_PAD.encode(payload_json);
+    let signing_input = format!("{HEADER_B64}.{payload_b64}");
+    let signature = sign(secret, signing_input.as_bytes());
+    Ok(format!("{signing_input}.{signature}"))
+}
+/// Verify a token's signature and expiry against `secret` and the current time
+/// `now` (Unix seconds), returning its claims on success.
+///
+/// Every failure — wrong shape, unexpected algorithm, bad signature, malformed
+/// payload, or expiry — collapses to [`AuthError::InvalidToken`] so nothing about
+/// *why* a token was rejected reaches the caller.
+///
+/// # Errors
+///
+/// Returns [`AuthError::InvalidToken`] on any verification failure.
+pub fn verify_jwt(secret: &str, token: &str, now: i64) -> Result<Claims, AuthError> {
+    let mut parts = token.split('.');
+    let (Some(header_b64), Some(payload_b64), Some(signature_b64), None) =
+        (parts.next(), parts.next(), parts.next(), parts.next())
+    else {
+        return Err(AuthError::InvalidToken);
+    };
+    // Reject anything not signed with our fixed HS256 header before spending an
+    // HMAC on it.
+    if header_b64 != HEADER_B64 {
+        return Err(AuthError::InvalidToken);
+    }
+    // Constant-time signature check via the MAC's own verifier.
+    let provided = URL_SAFE_NO_PAD
+        .decode(signature_b64)
+        .map_err(|_| AuthError::InvalidToken)?;
+    let signing_input = format!("{header_b64}.{payload_b64}");
+    let mut mac =
+        HmacSha256::new_from_slice(secret.as_bytes()).map_err(|_| AuthError::InvalidToken)?;
+    mac.update(signing_input.as_bytes());
+    mac.verify_slice(&provided)
+        .map_err(|_| AuthError::InvalidToken)?;
+    // Signature is good; now decode and check the claims.
+    let payload = URL_SAFE_NO_PAD
+        .decode(payload_b64)
+        .map_err(|_| AuthError::InvalidToken)?;
+    let claims: Claims = serde_json::from_slice(&payload).map_err(|_| AuthError::InvalidToken)?;
+    if claims.exp <= now {
+        return Err(AuthError::InvalidToken);
+    }
+    Ok(claims)
+}
+/// Compute the base64url HMAC-SHA256 signature of `message` under `secret`.
+fn sign(secret: &str, message: &[u8]) -> String {
+    // `new_from_slice` only fails for key sizes HMAC cannot accept, which is
+    // none — every byte length is valid — so this cannot error in practice.
+    let Ok(mut mac) = HmacSha256::new_from_slice(secret.as_bytes()) else {
+        return String::new();
+    };
+    mac.update(message);
+    URL_SAFE_NO_PAD.encode(mac.finalize().into_bytes())
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    fn claims(exp: i64) -> Claims {
+        Claims {
+            sub: "01useruseruseruseruseruser".to_string(),
+            jti: "01tokentokentokentokentoken".to_string(),
+            scopes: "repo:read,repo:write".to_string(),
+            iat: 1_000,
+            exp,
+        }
+    }
+    #[test]
+    fn round_trips_a_valid_token() {
+        let token = mint_jwt("s3cr3t", &claims(2_000)).unwrap();
+        // Three base64url segments.
+        assert_eq!(token.split('.').count(), 3);
+        let decoded = verify_jwt("s3cr3t", &token, 1_500).unwrap();
+        assert_eq!(decoded, claims(2_000));
+    }
+    #[test]
+    fn header_is_the_canonical_hs256_header() {
+        let token = mint_jwt("s", &claims(2_000)).unwrap();
+        let header = token.split('.').next().unwrap();
+        let json = URL_SAFE_NO_PAD.decode(header).unwrap();
+        assert_eq!(&json, br#"{"alg":"HS256","typ":"JWT"}"#);
+    }
+    #[test]
+    fn wrong_secret_is_rejected() {
+        let token = mint_jwt("right", &claims(2_000)).unwrap();
+        assert!(matches!(
+            verify_jwt("wrong", &token, 1_500),
+            Err(AuthError::InvalidToken)
+        ));
+    }
+    #[test]
+    fn expired_token_is_rejected() {
+        let token = mint_jwt("s", &claims(2_000)).unwrap();
+        // At exactly exp the token is already expired (exp <= now).
+        assert!(matches!(
+            verify_jwt("s", &token, 2_000),
+            Err(AuthError::InvalidToken)
+        ));
+        assert!(verify_jwt("s", &token, 1_999).is_ok());
+    }
+    #[test]
+    fn tampered_payload_is_rejected() {
+        let token = mint_jwt("s", &claims(2_000)).unwrap();
+        let mut parts: Vec<&str> = token.split('.').collect();
+        // Re-encode a payload that escalates scopes; the signature no longer fits.
+        let forged = Claims {
+            scopes: "admin".to_string(),
+            ..claims(2_000)
+        };
+        let forged_b64 = URL_SAFE_NO_PAD.encode(serde_json::to_vec(&forged).unwrap());
+        parts[1] = &forged_b64;
+        let tampered = parts.join(".");
+        assert!(matches!(
+            verify_jwt("s", &tampered, 1_500),
+            Err(AuthError::InvalidToken)
+        ));
+    }
+    #[test]
+    fn malformed_shapes_are_rejected() {
+        for bad in ["", "onlyonepart", "two.parts", "a.b.c.d", "..", "x.y.z"] {
+            assert!(
+                matches!(verify_jwt("s", bad, 0), Err(AuthError::InvalidToken)),
+                "should reject {bad:?}"
+            );
+        }
+    }
+    #[test]
+    fn algorithm_confusion_is_rejected() {
+        // A token whose header claims "alg":"none" but is otherwise well-formed
+        // must not verify, even with an empty signature.
+        let payload = URL_SAFE_NO_PAD.encode(serde_json::to_vec(&claims(2_000)).unwrap());
+        let none_header = URL_SAFE_NO_PAD.encode(br#"{"alg":"none","typ":"JWT"}"#);
+        let forged = format!("{none_header}.{payload}.");
+        assert!(matches!(
+            verify_jwt("s", &forged, 1_500),
+            Err(AuthError::InvalidToken)
+        ));
+    }
+}

 break every derivation that compiles `store`. Widening the filter is the minimal,
 explicit fix and leaves room to add further asset globs (themes, vendored htmx)
 the same way in later phases.
+## 2026-07-24 — Hand-rolled HS256 JWTs instead of a JWT crate
+**Decision:** `crates/auth` implements the HS256 JSON Web Token construction
+directly (base64url of a fixed JOSE header and a serde JSON payload, an
+`hmac`/`sha2` HMAC-SHA256, constant-time verification via `Mac::verify_slice`)
+rather than depending on `jsonwebtoken` or similar.
+**Alternatives:** Use the `jsonwebtoken` crate.
+**Rationale:** The mainstream JWT crates depend on `ring`, whose license set is
+not in `deny.toml`'s allow-list (it carries OpenSSL-derived terms), so pulling
+one in would fail `cargo-deny` — the same reason sqlx is built without a TLS
+backend. The HS256 surface we need is tiny and well-specified; hand-rolling it is
+a few dozen lines over crates already in the tree (`hmac`, `sha2`, `base64`,
+`serde_json`) and lets us reject algorithm-confusion tokens explicitly. Tokens
+are minted and verified only by fabrica, so interop with other JWT producers is a
+non-goal.
+## 2026-07-24 — `access()` takes the collaborator row and anonymous flag explicitly
+**Decision:** The permission function is
+`access(viewer: Option<&Viewer>, repo: &Repo, collaborator: Option<Permission>,
+allow_anonymous: bool) -> Access`, widening the two-argument shape sketched in
+the spec.
+**Alternatives:** Keep the literal `access(viewer, repo)` signature and thread the
+collaborator lookup and `instance.allow_anonymous` in via `Viewer` or a context
+struct.
+**Rationale:** Rule 3 needs the viewer's `repo_collaborators` row and rule 4 needs
+`instance.allow_anonymous`; neither lives on `Viewer` or `Repo`. Passing them as
+explicit parameters keeps `access` a pure function of its inputs — which is what
+makes the exhaustive matrix test possible — and keeps the collaborator lookup at
+the call site (the store), where it belongs. The five ordered rules are unchanged
+from the spec.