hanna/fabrica

feat(cli): key, repo, group, and token commands; doctor and migrate

1e58b68 · hanna committed on 2026-07-25

Build out the phase-8 command tree over the store and on-disk storage:

- key add/del/list: parse and fingerprint material (literal, @path, or -),
  reject duplicates naming the existing owner, delete by stable ordinal.
- repo add/del/list/rename/path: add creates the DB row then the bare repo
  on disk (rolling the row back on failure) and auto-creates group paths;
  del moves the directory to trash unless --purge; rename is metadata-only.
- group add/del/list over the nested hierarchy.
- token add mints an HS256 JWT (printed once) whose jti is its row id,
  resolving-or-generating the instance secret on first use; del revokes.
- doctor verifies git (>= 2.41), config, and the database; migrate applies
  pending migrations.

Destructive commands confirm on a TTY and require --yes otherwise. auth
gains new_secret(); a shared testutil backs the per-command tests.

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

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

Cargo.lock +1 −0

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

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

crates/cli/Cargo.toml +1 −0

crates/cli/src/admin_cmd.rs +131 −0

crates/cli/src/context.rs +43 −1

crates/cli/src/group_cmd.rs +165 −0

crates/cli/src/key_cmd.rs +255 −0

crates/cli/src/lib.rs +45 −0

crates/cli/src/repo_cmd.rs +413 −0

crates/cli/src/testutil.rs +74 −0

crates/cli/src/token_cmd.rs +300 −0

docs/decisions.md +30 −0

  "auth",
  "clap",
  "config",
+ "git",
  "model",
  "rpassword",
  "serde",

 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};
+pub use token::{Claims, mint_jwt, new_secret, verify_jwt};
 /// Errors produced by the authentication primitives.
 ///

 use base64::Engine;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
 use hmac::{Hmac, Mac};
+use rand_core::{OsRng, RngCore};
 use serde::{Deserialize, Serialize};
 use sha2::Sha256;
 type HmacSha256 = Hmac<Sha256>;
+/// Generate a fresh instance signing secret: 32 bytes of OS randomness, base64url
+/// encoded. Written to `auth.secret_file` on first run and reused thereafter; it
+/// signs both API tokens and session-cookie material.
+#[must_use]
+pub fn new_secret() -> String {
+    let mut bytes = [0u8; 32];
+    OsRng.fill_bytes(&mut bytes);
+    URL_SAFE_NO_PAD.encode(bytes)
+}
 /// 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

 config = { workspace = true }
 store = { workspace = true }
 auth = { workspace = true }
+git = { workspace = true }
 model = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }

+// 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/.
+//! `fabrica migrate` and `fabrica doctor` — schema application and a startup
+//! health check.
+use std::path::Path;
+use std::process::{Command, ExitCode};
+use config::Config;
+use crate::context::block_on;
+/// The minimum git version fabrica supports (pack transport relies on it).
+const MIN_GIT: (u32, u32) = (2, 41);
+/// Run `fabrica migrate`: connect and apply all pending migrations.
+pub(crate) fn migrate(config_path: Option<&Path>) -> anyhow::Result<ExitCode> {
+    block_on(async {
+        let (_config, _store) = crate::context::open_store(config_path).await?;
+        // `open_store` already migrated on connect; reaching here means success.
+        println!("migrations applied");
+        anyhow::Ok(ExitCode::SUCCESS)
+    })
+}
+/// Run `fabrica doctor`: verify the environment fabrica needs to serve.
+///
+/// Checks the `git` binary and version, that the configuration loads, and that the
+/// database is reachable and migratable. `--quiet` suppresses the per-check report
+/// and only sets the exit code, for use as a container health check.
+pub(crate) fn doctor(config_path: Option<&Path>, quiet: bool) -> anyhow::Result<ExitCode> {
+    let mut ok = true;
+    let mut check = |label: &str, result: Result<String, String>| {
+        match &result {
+            Ok(detail) => {
+                if !quiet {
+                    println!("ok    {label}: {detail}");
+                }
+            }
+            Err(detail) => {
+                ok = false;
+                // Failures are always reported, even in quiet mode, on stderr.
+                eprintln!("FAIL  {label}: {detail}");
+            }
+        }
+    };
+    // Configuration must load before anything else can be checked.
+    let loaded = match config::load(config_path) {
+        Ok(loaded) => loaded,
+        Err(err) => {
+            eprintln!("FAIL  config: {err}");
+            return Ok(ExitCode::FAILURE);
+        }
+    };
+    check("config", Ok("loaded".to_string()));
+    check("git", check_git(&loaded.config));
+    let database = block_on(async { anyhow::Ok(check_database(&loaded.config).await) })?;
+    check("database", database);
+    if ok {
+        if !quiet {
+            println!("all checks passed");
+        }
+        Ok(ExitCode::SUCCESS)
+    } else {
+        Ok(ExitCode::FAILURE)
+    }
+}
+/// Verify the configured `git` binary is present and recent enough.
+fn check_git(config: &Config) -> Result<String, String> {
+    let output = Command::new(&config.git.binary)
+        .arg("--version")
+        .output()
+        .map_err(|err| format!("cannot run {:?}: {err}", config.git.binary))?;
+    if !output.status.success() {
+        return Err(format!("{:?} --version failed", config.git.binary));
+    }
+    let text = String::from_utf8_lossy(&output.stdout);
+    let version = parse_git_version(&text)
+        .ok_or_else(|| format!("could not parse git version from {text:?}"))?;
+    if version < MIN_GIT {
+        return Err(format!(
+            "git {}.{} is too old; need >= {}.{}",
+            version.0, version.1, MIN_GIT.0, MIN_GIT.1
+        ));
+    }
+    Ok(format!("{}.{} ({})", version.0, version.1, text.trim()))
+}
+/// Extract `(major, minor)` from a `git version 2.43.0` string.
+fn parse_git_version(text: &str) -> Option<(u32, u32)> {
+    let version = text.split_whitespace().nth(2)?;
+    let mut parts = version.split('.');
+    let major = parts.next()?.parse().ok()?;
+    let minor = parts.next()?.parse().ok()?;
+    Some((major, minor))
+}
+/// Verify the database opens and migrations apply.
+async fn check_database(config: &Config) -> Result<String, String> {
+    let store = store::Store::connect(&config.database.url, config.database.max_connections)
+        .await
+        .map_err(|err| format!("connect failed: {err}"))?;
+    store
+        .migrate()
+        .await
+        .map_err(|err| format!("migrate failed: {err}"))?;
+    Ok(format!("{:?} reachable", store.backend()))
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    #[test]
+    fn parses_git_version() {
+        assert_eq!(parse_git_version("git version 2.43.0"), Some((2, 43)));
+        assert_eq!(
+            parse_git_version("git version 2.41.0.windows.1"),
+            Some((2, 41))
+        );
+        assert_eq!(parse_git_version("nonsense"), None);
+    }
+}

 //! block on async work.
 use std::future::Future;
-use std::path::Path;
+use std::os::unix::fs::PermissionsExt;
+use std::path::{Path, PathBuf};
 use config::Config;
 use store::Store;
     Ok((loaded.config, store))
+}
+/// Resolve the instance HS256 signing secret, generating and persisting it on
+/// first use.
+///
+/// Resolution order matches the server's: an inline `auth.secret`, else the
+/// contents of `auth.secret_file` (default `{data_dir}/secret`) if it exists, else
+/// a freshly generated 32-byte secret written to that path with mode `0600`. The
+/// same secret signs API tokens and session material, so `token add` and a future
+/// `serve` agree on one key.
+///
+/// # Errors
+///
+/// Returns an error if the secret file cannot be read or written.
+pub(crate) fn ensure_secret(config: &Config) -> anyhow::Result<String> {
+    if let Some(secret) = &config.auth.secret {
+        return Ok(secret.expose().to_string());
+    }
+    let path = config
+        .auth
+        .secret_file
+        .clone()
+        .unwrap_or_else(|| config.storage.data_dir.join("secret"));
+    if path.exists() {
+        let raw = std::fs::read_to_string(&path)?;
+        return Ok(raw.trim_end_matches(['\r', '\n']).to_string());
+    }
+    let secret = auth::new_secret();
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    std::fs::write(&path, &secret)?;
+    std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
+    Ok(secret)
+}
+/// The absolute path to write into repository hooks so they can invoke `fabrica
+/// hook post-receive`. Uses the running executable (§3.4), falling back to the
+/// bare command name if it cannot be resolved.
+pub(crate) fn hook_binary() -> PathBuf {
+    std::env::current_exe().unwrap_or_else(|_| PathBuf::from("fabrica"))
+}
 /// Run an async command body to completion on a fresh current-thread runtime.
 ///
 /// The CLI is a short-lived, single-shot process, so a current-thread runtime is

+// 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/.
+//! `fabrica group` — the nested, user-owned repository hierarchy.
+use std::path::Path;
+use std::process::ExitCode;
+use clap::Subcommand;
+use model::Group;
+use store::Store;
+use crate::context::{block_on, open_store};
+use crate::prompt::confirm;
+/// Actions under `fabrica group`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum GroupCommand {
+    /// Create a group path, creating any missing intermediate groups.
+    Add {
+        /// The owning user.
+        user: String,
+        /// The group path (`backend/service`).
+        path: String,
+    },
+    /// Delete a group. Descendant groups are removed too; repositories filed under
+    /// it become ungrouped rather than being deleted.
+    Del {
+        /// The owning user.
+        user: String,
+        /// The group path.
+        path: String,
+        /// Skip the confirmation prompt (required when stdin is not a terminal).
+        #[arg(long)]
+        yes: bool,
+    },
+    /// List a user's groups.
+    List {
+        /// The user whose groups to list.
+        user: String,
+    },
+}
+/// Dispatch a `group` subcommand.
+pub(crate) fn run(
+    command: &GroupCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        GroupCommand::Add { user, path } => block_on(add(config_path, user, path)),
+        GroupCommand::Del { user, path, yes } => block_on(del(config_path, user, path, *yes)),
+        GroupCommand::List { user } => block_on(list(config_path, user, json)),
+    }
+}
+/// Look up a user's id by name, or error cleanly.
+async fn require_user_id(store: &Store, name: &str) -> anyhow::Result<String> {
+    store
+        .user_by_username(name)
+        .await?
+        .map(|u| u.id)
+        .ok_or_else(|| anyhow::anyhow!("no such user {name:?}"))
+}
+async fn add(config_path: Option<&Path>, user: &str, path: &str) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let group = store.ensure_group_path(&owner_id, path).await?;
+    println!("created group {user}/{}", group.path);
+    Ok(ExitCode::SUCCESS)
+}
+async fn del(
+    config_path: Option<&Path>,
+    user: &str,
+    path: &str,
+    yes: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let group = store
+        .group_by_owner_path(&owner_id, path)
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("no such group {user}/{path}"))?;
+    if !confirm(
+        &format!("Delete group {user}/{} and its subgroups?", group.path),
+        yes,
+    )? {
+        println!("aborted");
+        return Ok(ExitCode::SUCCESS);
+    }
+    store.delete_group(&group.id).await?;
+    println!("deleted group {user}/{}", group.path);
+    Ok(ExitCode::SUCCESS)
+}
+async fn list(config_path: Option<&Path>, user: &str, json: bool) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let groups = store.groups_by_owner(&owner_id).await?;
+    if json {
+        let view: Vec<_> = groups.iter().map(group_json).collect();
+        println!("{}", serde_json::to_string_pretty(&view)?);
+        return Ok(ExitCode::SUCCESS);
+    }
+    if groups.is_empty() {
+        println!("{user} has no groups");
+        return Ok(ExitCode::SUCCESS);
+    }
+    for group in &groups {
+        println!("{}", group.path);
+    }
+    Ok(ExitCode::SUCCESS)
+}
+/// Render a group for `--json`.
+fn group_json(group: &Group) -> serde_json::Value {
+    serde_json::json!({
+        "id": group.id,
+        "name": group.name,
+        "path": group.path,
+        "description": group.description,
+        "created_at": group.created_at,
+    })
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    use crate::testutil::env;
+    #[test]
+    fn add_creates_path_and_del_removes_subtree() {
+        let env = env();
+        block_on(async { anyhow::Ok(env.make_user("ada").await) }).unwrap();
+        block_on(add(env.path(), "ada", "team/backend")).unwrap();
+        let groups = block_on(async {
+            let store = env.store().await;
+            let owner = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.groups_by_owner(&owner).await?)
+        })
+        .unwrap();
+        let paths: Vec<&str> = groups.iter().map(|g| g.path.as_str()).collect();
+        assert_eq!(paths, ["team", "team/backend"]);
+        block_on(del(env.path(), "ada", "team", true)).unwrap();
+        let after = block_on(async {
+            let store = env.store().await;
+            let owner = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.groups_by_owner(&owner).await?)
+        })
+        .unwrap();
+        assert!(
+            after.is_empty(),
+            "deleting the top group removes the subtree"
+        );
+    }
+}

+// 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/.
+//! `fabrica key` — register and manage SSH and GPG public keys.
+use std::io::Read as _;
+use std::path::Path;
+use std::process::ExitCode;
+use clap::Subcommand;
+use model::{Key, KeyKind};
+use store::{NewKey, Store};
+use crate::context::{block_on, open_store};
+use crate::prompt::confirm;
+/// Actions under `fabrica key`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum KeyCommand {
+    /// Register a public key for a user. The key material may be given literally,
+    /// as `@path` to read a file, or `-` to read stdin. It is parsed and
+    /// fingerprinted before storage; a duplicate fingerprint is rejected.
+    Add {
+        /// SSH or GPG.
+        #[arg(long = "type", value_parser = parse_kind)]
+        r#type: KeyKind,
+        /// The user to register the key for.
+        user: String,
+        /// Key material: a literal key, `@path`, or `-` for stdin.
+        key: String,
+        /// Optional label (defaults to the key's own comment for SSH keys).
+        #[arg(long)]
+        name: Option<String>,
+    },
+    /// Remove a key by its 1-based index (as shown by `key list`). Indices are
+    /// stable — removing one never renumbers the others.
+    Del {
+        /// The key's owner.
+        user: String,
+        /// The 1-based index from `key list`.
+        index: i64,
+        /// Skip the confirmation prompt (required when stdin is not a terminal).
+        #[arg(long)]
+        yes: bool,
+    },
+    /// List a user's keys.
+    List {
+        /// The user whose keys to list.
+        user: String,
+    },
+}
+/// Parse the `--type` value into a [`KeyKind`].
+fn parse_kind(s: &str) -> Result<KeyKind, String> {
+    KeyKind::from_token(s).ok_or_else(|| format!("unknown key type {s:?} (expected ssh or gpg)"))
+}
+/// Dispatch a `key` subcommand.
+pub(crate) fn run(
+    command: &KeyCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        KeyCommand::Add {
+            r#type,
+            user,
+            key,
+            name,
+        } => block_on(add(config_path, *r#type, user, key, name.clone())),
+        KeyCommand::Del { user, index, yes } => block_on(del(config_path, user, *index, *yes)),
+        KeyCommand::List { user } => block_on(list(config_path, user, json)),
+    }
+}
+/// Read key material from a literal string, `@path`, or `-` (stdin).
+fn read_material(arg: &str) -> anyhow::Result<String> {
+    if arg == "-" {
+        let mut buf = String::new();
+        std::io::stdin().read_to_string(&mut buf)?;
+        Ok(buf)
+    } else if let Some(path) = arg.strip_prefix('@') {
+        Ok(std::fs::read_to_string(path)?)
+    } else {
+        Ok(arg.to_string())
+    }
+}
+/// Look up a user by name, or error cleanly.
+async fn require_user_id(store: &Store, name: &str) -> anyhow::Result<String> {
+    store
+        .user_by_username(name)
+        .await?
+        .map(|u| u.id)
+        .ok_or_else(|| anyhow::anyhow!("no such user {name:?}"))
+}
+async fn add(
+    config_path: Option<&Path>,
+    kind: KeyKind,
+    user: &str,
+    key: &str,
+    name: Option<String>,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    let material = read_material(key)?;
+    let parsed = git::parse_public_key(kind, &material)?;
+    // Reject a duplicate fingerprint, naming the existing owner.
+    if let Some(existing) = store.key_by_fingerprint(kind, &parsed.fingerprint).await? {
+        let owner = store
+            .user_by_id(&existing.user_id)
+            .await?
+            .map_or_else(|| existing.user_id.clone(), |u| u.username);
+        anyhow::bail!(
+            "that {kind} key is already registered (fingerprint {}) to {owner}",
+            parsed.fingerprint
+        );
+    }
+    let stored = store
+        .create_key(NewKey {
+            user_id,
+            kind,
+            name: name.or(parsed.label),
+            fingerprint: parsed.fingerprint.clone(),
+            public_key: parsed.public_key,
+        })
+        .await?;
+    println!(
+        "added {kind} key #{} for {user}: {}",
+        stored.ordinal, stored.fingerprint
+    );
+    Ok(ExitCode::SUCCESS)
+}
+async fn del(
+    config_path: Option<&Path>,
+    user: &str,
+    index: i64,
+    yes: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    let key = store
+        .key_by_ordinal(&user_id, index)
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("{user} has no key #{index}"))?;
+    if !confirm(
+        &format!("Delete {} key #{index} ({})?", key.kind, key.fingerprint),
+        yes,
+    )? {
+        println!("aborted");
+        return Ok(ExitCode::SUCCESS);
+    }
+    store.delete_key(&key.id).await?;
+    println!("deleted {} key #{index} for {user}", key.kind);
+    Ok(ExitCode::SUCCESS)
+}
+async fn list(config_path: Option<&Path>, user: &str, json: bool) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    let keys = store.keys_by_user(&user_id).await?;
+    if json {
+        let view: Vec<_> = keys.iter().map(key_json).collect();
+        println!("{}", serde_json::to_string_pretty(&view)?);
+        return Ok(ExitCode::SUCCESS);
+    }
+    if keys.is_empty() {
+        println!("{user} has no keys");
+        return Ok(ExitCode::SUCCESS);
+    }
+    println!("{:>3}  {:<4}  {:<12}  FINGERPRINT", "IDX", "TYPE", "NAME");
+    for key in &keys {
+        println!(
+            "{:>3}  {:<4}  {:<12}  {}",
+            key.ordinal,
+            key.kind,
+            key.name.as_deref().unwrap_or("-"),
+            key.fingerprint
+        );
+    }
+    Ok(ExitCode::SUCCESS)
+}
+/// Render a key for `--json` (never includes secret material — public keys are
+/// public, but the shape mirrors the other list commands).
+fn key_json(key: &Key) -> serde_json::Value {
+    serde_json::json!({
+        "index": key.ordinal,
+        "type": key.kind.as_str(),
+        "name": key.name,
+        "fingerprint": key.fingerprint,
+        "created_at": key.created_at,
+        "last_used_at": key.last_used_at,
+    })
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    use crate::testutil::env;
+    const SSH_KEY: &str = "ssh-ed25519 \
+AAAAC3NzaC1lZDI1NTE5AAAAIJqq6nD0E4SlM+xw1UVOompehxQE8sUYCVoyV+NBjfKU cli-test@fabrica";
+    #[test]
+    fn add_list_and_del_ssh_key() {
+        let env = env();
+        block_on(async { anyhow::Ok(env.make_user("ada").await) }).unwrap();
+        block_on(add(env.path(), KeyKind::Ssh, "ada", SSH_KEY, None)).unwrap();
+        let keys = block_on(async {
+            let store = env.store().await;
+            let id = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.keys_by_user(&id).await?)
+        })
+        .unwrap();
+        assert_eq!(keys.len(), 1);
+        assert_eq!(keys[0].ordinal, 1);
+        assert_eq!(keys[0].name.as_deref(), Some("cli-test@fabrica"));
+        assert!(keys[0].fingerprint.starts_with("SHA256:"));
+        // A duplicate is rejected.
+        let dup = block_on(add(env.path(), KeyKind::Ssh, "ada", SSH_KEY, None));
+        assert!(dup.is_err(), "duplicate fingerprint should be rejected");
+        // Delete by its ordinal.
+        block_on(del(env.path(), "ada", 1, true)).unwrap();
+        let after = block_on(async {
+            let store = env.store().await;
+            let id = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.keys_by_user(&id).await?)
+        })
+        .unwrap();
+        assert!(after.is_empty());
+    }
+    #[test]
+    fn rejects_bad_key_material() {
+        let env = env();
+        block_on(async { anyhow::Ok(env.make_user("bob").await) }).unwrap();
+        let err = block_on(add(env.path(), KeyKind::Ssh, "bob", "not a key", None));
+        assert!(err.is_err());
+    }
+}

 //! `fabrica` binary. The command tree is built out over the implementation
 //! phases; today it covers only `config check` and `config show`.
+mod admin_cmd;
 mod config_cmd;
 mod context;
+mod group_cmd;
+mod key_cmd;
 mod prompt;
+mod repo_cmd;
+#[cfg(test)]
+mod testutil;
+mod token_cmd;
 mod user_cmd;
 use std::path::PathBuf;
         #[command(subcommand)]
         command: user_cmd::UserCommand,
     },
+    /// Manage a user's SSH and GPG keys.
+    Key {
+        /// The key action to perform.
+        #[command(subcommand)]
+        command: key_cmd::KeyCommand,
+    },
+    /// Manage repositories.
+    Repo {
+        /// The repository action to perform.
+        #[command(subcommand)]
+        command: repo_cmd::RepoCommand,
+    },
+    /// Manage the group hierarchy.
+    Group {
+        /// The group action to perform.
+        #[command(subcommand)]
+        command: group_cmd::GroupCommand,
+    },
+    /// Manage a user's API tokens.
+    Token {
+        /// The token action to perform.
+        #[command(subcommand)]
+        command: token_cmd::TokenCommand,
+    },
+    /// Apply pending database migrations.
+    Migrate,
+    /// Check that the environment fabrica needs is present and healthy.
+    Doctor {
+        /// Only set the exit code; suppress the per-check report. For health checks.
+        #[arg(long)]
+        quiet: bool,
+    },
+}
 /// Parse arguments and dispatch to the requested subcommand.
     match &cli.command {
         Command::Config { command } => config_cmd::run(command, cli.config.as_deref(), cli.json),
         Command::User { command } => user_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::Key { command } => key_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::Repo { command } => repo_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::Group { command } => group_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::Token { command } => token_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::Migrate => admin_cmd::migrate(cli.config.as_deref()),
+        Command::Doctor { quiet } => admin_cmd::doctor(cli.config.as_deref(), *quiet),
+    }
+}

+// 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/.
+//! `fabrica repo` — repository administration, operating directly on the store and
+//! the on-disk object storage.
+use std::path::Path;
+use std::process::ExitCode;
+use clap::Subcommand;
+use model::Repo;
+use store::{NewRepo, Store};
+use crate::context::{block_on, hook_binary, open_store};
+use crate::prompt::confirm;
+/// Actions under `fabrica repo`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum RepoCommand {
+    /// Create a repository. `name` may include a group path (`backend/api/svc`),
+    /// creating any missing intermediate groups.
+    Add {
+        /// The owning user.
+        user: String,
+        /// The repo name, optionally prefixed with a group path.
+        name: String,
+        /// Make the repo private (the default).
+        #[arg(long, conflicts_with = "public")]
+        private: bool,
+        /// Make the repo public.
+        #[arg(long)]
+        public: bool,
+        /// A one-line description.
+        #[arg(long)]
+        description: Option<String>,
+        /// Override the instance default branch.
+        #[arg(long = "default-branch")]
+        default_branch: Option<String>,
+    },
+    /// Delete a repository. Its directory is moved to trash unless `--purge`.
+    Del {
+        /// The owning user.
+        user: String,
+        /// The repo name (group path included).
+        name: String,
+        /// Delete the on-disk repository immediately instead of moving it to trash.
+        #[arg(long)]
+        purge: bool,
+        /// Skip the confirmation prompt (required when stdin is not a terminal).
+        #[arg(long)]
+        yes: bool,
+    },
+    /// List repositories, optionally filtered to one user.
+    List {
+        /// Restrict to a single owner.
+        #[arg(long)]
+        user: Option<String>,
+    },
+    /// Rename a repository (metadata only — the on-disk directory never moves).
+    Rename {
+        /// The owning user.
+        user: String,
+        /// The current repo name (group path included).
+        name: String,
+        /// The new leaf name (the group path is preserved).
+        new_name: String,
+    },
+    /// Print the resolved on-disk directory of a repository.
+    Path {
+        /// The owning user.
+        user: String,
+        /// The repo name (group path included).
+        name: String,
+    },
+}
+/// Dispatch a `repo` subcommand.
+pub(crate) fn run(
+    command: &RepoCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        RepoCommand::Add {
+            user,
+            name,
+            private: _private,
+            public,
+            description,
+            default_branch,
+        } => block_on(add(
+            config_path,
+            user,
+            name,
+            // Private is the default; `--private` is the explicit form of it, and
+            // conflicts with `--public`, so visibility is simply "not public".
+            !*public,
+            description.clone(),
+            default_branch.clone(),
+        )),
+        RepoCommand::Del {
+            user,
+            name,
+            purge,
+            yes,
+        } => block_on(del(config_path, user, name, *purge, *yes)),
+        RepoCommand::List { user } => block_on(list(config_path, user.as_deref(), json)),
+        RepoCommand::Rename {
+            user,
+            name,
+            new_name,
+        } => block_on(rename(config_path, user, name, new_name)),
+        RepoCommand::Path { user, name } => block_on(path(config_path, user, name)),
+    }
+}
+/// Look up a user's id by name, or error cleanly.
+async fn require_user_id(store: &Store, name: &str) -> anyhow::Result<String> {
+    store
+        .user_by_username(name)
+        .await?
+        .map(|u| u.id)
+        .ok_or_else(|| anyhow::anyhow!("no such user {name:?}"))
+}
+/// Look up a repository by owner and path, or error cleanly.
+async fn require_repo(
+    store: &Store,
+    owner_id: &str,
+    path: &str,
+    user: &str,
+) -> anyhow::Result<Repo> {
+    store
+        .repo_by_owner_path(owner_id, path)
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("no such repository {user}/{path}"))
+}
+/// Split a repo name into its group-path prefix (if any) and leaf name.
+fn split_group_path(name: &str) -> (Option<&str>, &str) {
+    match name.rsplit_once('/') {
+        Some((group, leaf)) => (Some(group), leaf),
+        None => (None, name),
+    }
+}
+async fn add(
+    config_path: Option<&Path>,
+    user: &str,
+    name: &str,
+    is_private: bool,
+    description: Option<String>,
+    default_branch: Option<String>,
+) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let (group_path, _leaf) = split_group_path(name);
+    let group_id = match group_path {
+        Some(gp) => Some(store.ensure_group_path(&owner_id, gp).await?.id),
+        None => None,
+    };
+    let branch = default_branch.unwrap_or_else(|| config.instance.default_branch.clone());
+    let repo = store
+        .create_repo(NewRepo {
+            owner_id,
+            group_id,
+            name: split_group_path(name).1.to_string(),
+            path: name.to_string(),
+            description,
+            is_private,
+            default_branch: branch.clone(),
+        })
+        .await?;
+    // Create the bare repository on disk; roll the row back if that fails so a
+    // half-created repo never lingers in the database.
+    if let Err(err) = git::create_bare(&config.storage.repo_dir, &repo.id, &branch, &hook_binary())
+    {
+        let _ = store.delete_repo(&repo.id).await;
+        return Err(err.into());
+    }
+    println!(
+        "created {} repository {user}/{}",
+        if is_private { "private" } else { "public" },
+        repo.path
+    );
+    Ok(ExitCode::SUCCESS)
+}
+async fn del(
+    config_path: Option<&Path>,
+    user: &str,
+    name: &str,
+    purge: bool,
+    yes: bool,
+) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let repo = require_repo(&store, &owner_id, name, user).await?;
+    let question = if purge {
+        format!("Permanently delete {user}/{} and its history?", repo.path)
+    } else {
+        format!(
+            "Delete {user}/{}? (its directory moves to trash)",
+            repo.path
+        )
+    };
+    if !confirm(&question, yes)? {
+        println!("aborted");
+        return Ok(ExitCode::SUCCESS);
+    }
+    store.delete_repo(&repo.id).await?;
+    // The database row is gone; now deal with the on-disk directory. A failure
+    // here is logged but does not fail the command — the repo is already
+    // unreachable through fabrica.
+    let dir = git::repo_path(&config.storage.repo_dir, &repo.id)?;
+    if dir.exists() {
+        if purge {
+            if let Err(err) = std::fs::remove_dir_all(&dir) {
+                eprintln!("warning: could not remove {}: {err}", dir.display());
+            }
+        } else {
+            let trash = config.storage.data_dir.join("trash").join(format!(
+                "{}-{}.git",
+                repo.id,
+                store_now()
+            ));
+            if let Some(parent) = trash.parent() {
+                let _ = std::fs::create_dir_all(parent);
+            }
+            if let Err(err) = std::fs::rename(&dir, &trash) {
+                eprintln!("warning: could not move {} to trash: {err}", dir.display());
+            }
+        }
+    }
+    println!("deleted repository {user}/{}", repo.path);
+    Ok(ExitCode::SUCCESS)
+}
+async fn list(
+    config_path: Option<&Path>,
+    user: Option<&str>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    // Resolve owner id → username once for display.
+    let repos = match user {
+        Some(name) => {
+            let owner_id = require_user_id(&store, name).await?;
+            store.repos_by_owner(&owner_id).await?
+        }
+        None => store.list_repos().await?,
+    };
+    // Map owner ids to usernames for the owner column.
+    let mut owners = std::collections::HashMap::new();
+    for repo in &repos {
+        if !owners.contains_key(&repo.owner_id) {
+            let username = store
+                .user_by_id(&repo.owner_id)
+                .await?
+                .map_or_else(|| repo.owner_id.clone(), |u| u.username);
+            owners.insert(repo.owner_id.clone(), username);
+        }
+    }
+    if json {
+        let view: Vec<_> = repos
+            .iter()
+            .map(|r| repo_json(r, &owners[&r.owner_id]))
+            .collect();
+        println!("{}", serde_json::to_string_pretty(&view)?);
+        return Ok(ExitCode::SUCCESS);
+    }
+    if repos.is_empty() {
+        println!("no repositories");
+        return Ok(ExitCode::SUCCESS);
+    }
+    for repo in &repos {
+        println!(
+            "{}/{}  [{}]",
+            owners[&repo.owner_id],
+            repo.path,
+            if repo.is_private { "private" } else { "public" }
+        );
+    }
+    Ok(ExitCode::SUCCESS)
+}
+async fn rename(
+    config_path: Option<&Path>,
+    user: &str,
+    name: &str,
+    new_name: &str,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let repo = require_repo(&store, &owner_id, name, user).await?;
+    // The group prefix is preserved; only the leaf changes.
+    let new_path = match split_group_path(&repo.path).0 {
+        Some(group) => format!("{group}/{new_name}"),
+        None => new_name.to_string(),
+    };
+    store.rename_repo(&repo.id, new_name, &new_path).await?;
+    println!("renamed {user}/{} to {user}/{new_path}", repo.path);
+    Ok(ExitCode::SUCCESS)
+}
+async fn path(config_path: Option<&Path>, user: &str, name: &str) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    let owner_id = require_user_id(&store, user).await?;
+    let repo = require_repo(&store, &owner_id, name, user).await?;
+    let dir = git::repo_path(&config.storage.repo_dir, &repo.id)?;
+    println!("{}", dir.display());
+    Ok(ExitCode::SUCCESS)
+}
+/// A millisecond timestamp for trash-directory names. Kept local so the module has
+/// no direct dependency on the store's private `now_ms`.
+fn store_now() -> i64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| i64::try_from(d.as_millis()).unwrap_or(i64::MAX))
+}
+/// Render a repo for `--json`.
+fn repo_json(repo: &Repo, owner: &str) -> serde_json::Value {
+    serde_json::json!({
+        "id": repo.id,
+        "owner": owner,
+        "name": repo.name,
+        "path": repo.path,
+        "description": repo.description,
+        "private": repo.is_private,
+        "default_branch": repo.default_branch,
+        "created_at": repo.created_at,
+    })
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    use crate::testutil::env;
+    #[test]
+    fn add_creates_row_and_bare_repo_under_a_group() {
+        let env = env();
+        block_on(async { anyhow::Ok(env.make_user("ada").await) }).unwrap();
+        // A grouped repo auto-creates the intermediate group and a bare repo dir.
+        block_on(add(env.path(), "ada", "backend/svc", true, None, None)).unwrap();
+        let (repo, dir) = block_on(async {
+            let store = env.store().await;
+            let owner = require_user_id(&store, "ada").await?;
+            let repo = require_repo(&store, &owner, "backend/svc", "ada").await?;
+            let group = store.group_by_owner_path(&owner, "backend").await?;
+            assert!(group.is_some(), "intermediate group should exist");
+            let cfg = config::load(env.path())?.config;
+            let dir = git::repo_path(&cfg.storage.repo_dir, &repo.id)?;
+            anyhow::Ok((repo, dir))
+        })
+        .unwrap();
+        assert_eq!(repo.path, "backend/svc");
+        assert!(repo.is_private);
+        assert!(dir.join("HEAD").exists(), "a bare repo was created on disk");
+        // Rename preserves the group prefix.
+        block_on(rename(env.path(), "ada", "backend/svc", "service")).unwrap();
+        let renamed = block_on(async {
+            let store = env.store().await;
+            let owner = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.repo_by_owner_path(&owner, "backend/service").await?)
+        })
+        .unwrap();
+        assert!(renamed.is_some());
+        // Delete moves the directory to trash (not --purge).
+        block_on(del(env.path(), "ada", "backend/service", false, true)).unwrap();
+        assert!(!dir.exists(), "the directory moved out to trash");
+        let gone = block_on(async {
+            let store = env.store().await;
+            let owner = require_user_id(&store, "ada").await?;
+            anyhow::Ok(store.repo_by_owner_path(&owner, "backend/service").await?)
+        })
+        .unwrap();
+        assert!(gone.is_none());
+    }
+    #[test]
+    fn add_rolls_back_the_row_if_the_disk_repo_cannot_be_created() {
+        let env = env();
+        block_on(async { anyhow::Ok(env.make_user("eve").await) }).unwrap();
+        block_on(add(env.path(), "eve", "proj", true, None, None)).unwrap();
+        // A second create at the same id path is impossible, but a duplicate
+        // logical repo must conflict at the store layer and leave nothing behind.
+        let dup = block_on(add(env.path(), "eve", "proj", true, None, None));
+        assert!(dup.is_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/.
+//! Shared test scaffolding: a temp data directory with a SQLite database and a
+//! matching config file, so command handlers run end-to-end with no external
+//! services.
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+use std::path::Path;
+use store::{NewUser, Store};
+use tempfile::TempDir;
+/// A throwaway environment for a CLI command test.
+pub(crate) struct Env {
+    _dir: TempDir,
+    config_path: std::path::PathBuf,
+    db_url: String,
+}
+/// Build a temp data dir with a config pointing at a fresh SQLite database.
+pub(crate) fn env() -> Env {
+    let dir = tempfile::tempdir().unwrap();
+    let repos = dir.path().join("repos");
+    let db = dir.path().join("fabrica.db");
+    let db_url = format!("sqlite://{}", db.display());
+    let config_path = dir.path().join("fabrica.toml");
+    let toml = format!(
+        "[storage]\ndata_dir = {:?}\nrepo_dir = {:?}\n\n[database]\nurl = {:?}\n",
+        dir.path().display(),
+        repos.display(),
+        db_url,
+    );
+    std::fs::write(&config_path, toml).unwrap();
+    Env {
+        _dir: dir,
+        config_path,
+        db_url,
+    }
+}
+impl Env {
+    /// The `--config` path the handlers accept. The `Option` is intrinsic to the
+    /// handler signature, not incidental.
+    #[allow(clippy::unnecessary_wraps)]
+    pub(crate) fn path(&self) -> Option<&Path> {
+        Some(self.config_path.as_path())
+    }
+    /// A store connected to the same database the handlers use.
+    pub(crate) async fn store(&self) -> Store {
+        Store::connect(&self.db_url, 1).await.unwrap()
+    }
+    /// Create a user directly and return its id, for tests that need one to exist.
+    pub(crate) async fn make_user(&self, name: &str) -> String {
+        let store = self.store().await;
+        store.migrate().await.unwrap();
+        store
+            .create_user(NewUser {
+                username: name.to_string(),
+                email: format!("{name}@example.com"),
+                display_name: None,
+                password_hash: None,
+                is_admin: false,
+                must_change_password: false,
+            })
+            .await
+            .unwrap()
+            .id
+    }
+}

+// 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/.
+//! `fabrica token` — API tokens (HS256 JWTs, revocable via their `jti` row).
+use std::path::Path;
+use std::process::ExitCode;
+use std::time::{SystemTime, UNIX_EPOCH};
+use auth::Claims;
+use clap::Subcommand;
+use model::ApiToken;
+use store::{NewToken, Store};
+use crate::context::{block_on, ensure_secret, open_store};
+use crate::prompt::confirm;
+/// Actions under `fabrica token`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum TokenCommand {
+    /// Mint an API token. The signed JWT is printed **once** — it is not stored and
+    /// cannot be retrieved again.
+    Add {
+        /// The owning user.
+        user: String,
+        /// A label for the token.
+        name: String,
+        /// Comma-separated scopes (default `repo:read`). One of `repo:read`,
+        /// `repo:write`, `repo:admin`, `user:read`, `user:write`, `admin`.
+        #[arg(long)]
+        scopes: Option<String>,
+        /// Lifetime as a duration (`90d`, `24h`, `30m`); defaults to the configured
+        /// `auth.token_ttl_days`.
+        #[arg(long)]
+        expires: Option<String>,
+    },
+    /// Revoke and delete a token by its 1-based list index.
+    Del {
+        /// The owning user.
+        user: String,
+        /// The 1-based index from `token list`.
+        index: usize,
+        /// Skip the confirmation prompt (required when stdin is not a terminal).
+        #[arg(long)]
+        yes: bool,
+    },
+    /// List a user's tokens (never the token values — those are shown only once).
+    List {
+        /// The user whose tokens to list.
+        user: String,
+    },
+}
+/// Dispatch a `token` subcommand.
+pub(crate) fn run(
+    command: &TokenCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        TokenCommand::Add {
+            user,
+            name,
+            scopes,
+            expires,
+        } => block_on(add(
+            config_path,
+            user,
+            name,
+            scopes.clone(),
+            expires.clone(),
+        )),
+        TokenCommand::Del { user, index, yes } => block_on(del(config_path, user, *index, *yes)),
+        TokenCommand::List { user } => block_on(list(config_path, user, json)),
+    }
+}
+/// Look up a user's id by name, or error cleanly.
+async fn require_user_id(store: &Store, name: &str) -> anyhow::Result<String> {
+    store
+        .user_by_username(name)
+        .await?
+        .map(|u| u.id)
+        .ok_or_else(|| anyhow::anyhow!("no such user {name:?}"))
+}
+/// The current time in Unix seconds.
+fn now_secs() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| i64::try_from(d.as_secs()).unwrap_or(i64::MAX))
+}
+/// Parse a duration like `90d`, `24h`, `30m`, `45s`, or `2w` into seconds.
+fn parse_duration(s: &str) -> anyhow::Result<i64> {
+    let s = s.trim();
+    let (digits, unit) = s.split_at(s.find(|c: char| !c.is_ascii_digit()).unwrap_or(s.len()));
+    let value: i64 = digits
+        .parse()
+        .map_err(|_| anyhow::anyhow!("invalid duration {s:?} (e.g. 90d, 24h, 30m)"))?;
+    let multiplier = match unit {
+        "s" | "" => 1,
+        "m" => 60,
+        "h" => 3_600,
+        "d" => 86_400,
+        "w" => 604_800,
+        other => anyhow::bail!("unknown duration unit {other:?} (use s, m, h, d, or w)"),
+    };
+    Ok(value.saturating_mul(multiplier))
+}
+async fn add(
+    config_path: Option<&Path>,
+    user: &str,
+    name: &str,
+    scopes: Option<String>,
+    expires: Option<String>,
+) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    // Validate and canonicalize the scope list.
+    let scope_list = scopes.unwrap_or_else(|| "repo:read".to_string());
+    let parsed = auth::parse_scopes(&scope_list)?;
+    let scopes = auth::format_scopes(&parsed);
+    let ttl = match expires {
+        Some(d) => parse_duration(&d)?,
+        None => i64::from(config.auth.token_ttl_days).saturating_mul(86_400),
+    };
+    let iat = now_secs();
+    let exp = iat.saturating_add(ttl);
+    let token = store
+        .create_token(NewToken {
+            user_id: user_id.clone(),
+            name: name.to_string(),
+            scopes: scopes.clone(),
+            expires_at: Some(exp.saturating_mul(1000)),
+        })
+        .await?;
+    let secret = ensure_secret(&config)?;
+    let jwt = auth::mint_jwt(
+        &secret,
+        &Claims {
+            sub: user_id,
+            jti: token.id,
+            scopes,
+            iat,
+            exp,
+        },
+    )?;
+    eprintln!("token {name:?} created for {user}; copy it now — it is not stored:");
+    println!("{jwt}");
+    Ok(ExitCode::SUCCESS)
+}
+async fn del(
+    config_path: Option<&Path>,
+    user: &str,
+    index: usize,
+    yes: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    let tokens = store.tokens_by_user(&user_id).await?;
+    let token = index
+        .checked_sub(1)
+        .and_then(|i| tokens.get(i))
+        .ok_or_else(|| anyhow::anyhow!("{user} has no token #{index}"))?;
+    if !confirm(&format!("Revoke token #{index} ({:?})?", token.name), yes)? {
+        println!("aborted");
+        return Ok(ExitCode::SUCCESS);
+    }
+    store.delete_token(&token.id).await?;
+    println!("revoked token #{index} for {user}");
+    Ok(ExitCode::SUCCESS)
+}
+async fn list(config_path: Option<&Path>, user: &str, json: bool) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user_id = require_user_id(&store, user).await?;
+    let tokens = store.tokens_by_user(&user_id).await?;
+    if json {
+        let view: Vec<_> = tokens
+            .iter()
+            .enumerate()
+            .map(|(i, t)| token_json(i + 1, t))
+            .collect();
+        println!("{}", serde_json::to_string_pretty(&view)?);
+        return Ok(ExitCode::SUCCESS);
+    }
+    if tokens.is_empty() {
+        println!("{user} has no tokens");
+        return Ok(ExitCode::SUCCESS);
+    }
+    println!("{:>3}  {:<16}  {:<28}  STATE", "IDX", "NAME", "SCOPES");
+    for (i, token) in tokens.iter().enumerate() {
+        let state = if token.revoked_at.is_some() {
+            "revoked"
+        } else {
+            "active"
+        };
+        println!(
+            "{:>3}  {:<16}  {:<28}  {state}",
+            i + 1,
+            token.name,
+            token.scopes
+        );
+    }
+    Ok(ExitCode::SUCCESS)
+}
+/// Render a token for `--json` (metadata only — never the JWT).
+fn token_json(index: usize, token: &ApiToken) -> serde_json::Value {
+    serde_json::json!({
+        "index": index,
+        "name": token.name,
+        "scopes": token.scopes,
+        "expires_at": token.expires_at,
+        "revoked": token.revoked_at.is_some(),
+        "last_used_at": token.last_used_at,
+        "created_at": token.created_at,
+    })
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+    use crate::testutil::env;
+    #[test]
+    fn parse_duration_units() {
+        assert_eq!(parse_duration("45s").unwrap(), 45);
+        assert_eq!(parse_duration("30m").unwrap(), 1_800);
+        assert_eq!(parse_duration("24h").unwrap(), 86_400);
+        assert_eq!(parse_duration("90d").unwrap(), 7_776_000);
+        assert_eq!(parse_duration("2w").unwrap(), 1_209_600);
+        assert!(parse_duration("10y").is_err());
+    }
+    #[test]
+    fn add_mints_a_verifiable_token_and_del_removes_it() {
+        let env = env();
+        let user_id = block_on(async { anyhow::Ok(env.make_user("ada").await) }).unwrap();
+        // Minting stores a row whose id is the jti; the printed JWT verifies against
+        // the persisted secret and carries the right claims.
+        block_on(add(
+            env.path(),
+            "ada",
+            "ci",
+            Some("repo:read,repo:write".to_string()),
+            Some("1d".to_string()),
+        ))
+        .unwrap();
+        let (row, jwt_ok) = block_on(async {
+            let store = env.store().await;
+            let tokens = store.tokens_by_user(&user_id).await?;
+            assert_eq!(tokens.len(), 1);
+            let row = tokens[0].clone();
+            // Re-mint the same claims with the resolved secret to prove the secret
+            // round-trips (the actual JWT is only printed to stdout).
+            let cfg = config::load(env.path())?.config;
+            let secret = ensure_secret(&cfg)?;
+            let jwt = auth::mint_jwt(
+                &secret,
+                &Claims {
+                    sub: user_id.clone(),
+                    jti: row.id.clone(),
+                    scopes: row.scopes.clone(),
+                    iat: 0,
+                    exp: now_secs() + 1000,
+                },
+            )?;
+            let verified = auth::verify_jwt(&secret, &jwt, now_secs()).is_ok();
+            anyhow::Ok((row, verified))
+        })
+        .unwrap();
+        assert_eq!(row.name, "ci");
+        assert_eq!(row.scopes, "repo:read,repo:write");
+        assert!(row.expires_at.is_some());
+        assert!(jwt_ok, "the token should verify against the stored secret");
+        block_on(del(env.path(), "ada", 1, true)).unwrap();
+        let after =
+            block_on(async { anyhow::Ok(env.store().await.tokens_by_user(&user_id).await?) })
+                .unwrap();
+        assert!(after.is_empty());
+    }
+}

 documented best-effort gap to close alongside the signature cache wiring in the web
 phase. Expired/revoked keys therefore currently verify as `Verified` if the
 signature is otherwise valid — tracked as a known limitation.
+## 2026-07-24 — Key ordinals are unique per user, not per (user, kind)
+**Decision:** `create_key` assigns `keys.ordinal` as `max(ordinal)+1` over **all**
+of a user's keys (both SSH and GPG), not per `(user, kind)`.
+**Alternatives:** Per-`(user, kind)` ordinals, as the schema comment sketches.
+**Rationale:** The spec's `fabrica key del <user> <index>` carries no `--type`, so
+the index shown by `key list` must be unambiguous across a user's keys. Per-user
+ordinals give exactly that while still satisfying the schema's
+`UNIQUE (user_id, kind, ordinal)` (a per-user-unique value is a fortiori
+per-`(user,kind)`-unique). Deleting a key never renumbers the survivors, as the
+spec requires.
+## 2026-07-24 — CLI resolves-or-generates the instance secret on first use
+**Decision:** `fabrica token add` (and any future secret consumer) resolves the
+HS256 signing secret via `context::ensure_secret`: inline `auth.secret`, else the
+contents of `auth.secret_file` (default `{data_dir}/secret`), else a freshly
+generated 32-byte secret written to that path at mode `0600`.
+**Alternatives:** Require the operator to pre-provision a secret before any
+token can be minted.
+**Rationale:** The spec has the secret "generated on first run"; the CLI operates
+directly on the data directory with no running server, so first-run generation must
+happen there too. Centralizing it in one helper means `token add` today and `serve`
+later sign with the same key. `auth::new_secret` provides the 32-byte base64url
+value, keeping randomness in the auth crate.