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

@@ @@ -69,6 +69,18 @@ name = "api" @@
 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"
@@ @@ -89,6 +101,17 @@ dependencies = [ @@
 [[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"
@@ @@ -112,6 +141,15 @@ dependencies = [ @@
+]
 [[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]]
@@ @@ -566,6 +605,17 @@ dependencies = [ @@
 [[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"
@@ @@ -640,7 +690,16 @@ version = "0.13.0" @@
 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]]
@@ @@ -935,6 +994,17 @@ dependencies = [ @@
+]
 [[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"
@@ @@ -1069,6 +1139,15 @@ dependencies = [ @@
 [[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"
@@ @@ -1370,7 +1449,7 @@ dependencies = [ @@
  "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"

@@ @@ -10,6 +10,15 @@ repository.workspace = true @@
 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

@@ @@ -2,4 +2,57 @@ @@
 // 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),
+}

@@ @@ -0,0 +1,151 @@ @@
 // 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)));
+    }
+}

@@ @@ -0,0 +1,304 @@ @@
 // 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);
+        }
+    }
+}

@@ @@ -0,0 +1,135 @@ @@
 // 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:?}"
         );
+    }
+}

@@ @@ -0,0 +1,94 @@ @@
 // 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"));
+    }
+}

@@ @@ -0,0 +1,216 @@ @@
 // 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)
         ));
+    }
+}

@@ @@ -170,3 +170,39 @@ into `OUT_DIR`. @@
 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.