hanna/fabrica

feat(api): /api/v1 JSON surface with JWT auth and scopes

c21dfed · hanna committed on 2026-07-25

Add the API crate: a self-contained axum router nested by web at
/api/v1. A Bearer-JWT extractor verifies the signature and expiry, that
the jti row exists and is unrevoked, and that the account is enabled,
bumping last_used_at — so revocation is real. Scopes gate each handler
(admin grants all); a private resource the token cannot reach returns
404, never 403.

Endpoints: version, user, users (admin), repos (list + create), repo
detail and git sub-resources (branches/tags/commits/commit/tree/raw),
delete (with ?purge), groups, and a name/description search. Errors share
{"error":{code,message,details}}; timestamps are RFC 3339; lists carry
X-Total-Count and ?page/per_page (capped 100).

web nests it via nest_service (web -> api is allowed; nothing depends on
web). Verified end-to-end: 401 without a token, RFC3339 output, git
sub-resources, POST 201, DELETE 204, and the error shape.

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

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

Cargo.lock +14 −0

crates/api/Cargo.toml +11 −0

crates/api/src/handlers.rs +527 −0

crates/api/src/lib.rs +254 −1

crates/web/Cargo.toml +1 −0

crates/web/src/lib.rs +8 −0

docs/decisions.md +19 −0

 [[package]]
 name = "api"
 version = "0.1.0"
+dependencies = [
+ "auth",
+ "axum",
+ "config",
+ "git",
+ "model",
+ "serde",
+ "serde_json",
+ "store",
+ "time",
+ "tokio",
+ "tracing",
+]
 [[package]]
 name = "argon2"
 version = "0.1.0"
 dependencies = [
  "ammonia",
+ "api",
  "auth",
  "axum",
  "axum-extra",

 publish.workspace = true
 [dependencies]
+config = { workspace = true }
+store = { workspace = true }
+model = { workspace = true }
+git = { workspace = true }
+auth = { workspace = true }
+axum = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+time = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
 [lints]
 workspace = true

 auth = { workspace = true }
 mail = { workspace = true }
 git = { workspace = true }
+api = { workspace = true }
 highlight = { workspace = true }
 axum = { workspace = true }
 axum-extra = { workspace = true }

 pub fn build_router(state: AppState) -> Router {
     let x_request_id = HeaderName::from_static("x-request-id");
+    // The JSON API is a self-contained, fully-stated router nested under /api/v1.
+    let api = api::router(
+        state.store.clone(),
+        Arc::clone(&state.config),
+        (*state.secret).clone(),
+    );
     Router::new()
+        .nest_service("/api/v1", api)
         .route("/", get(pages::home))
         .route("/login", get(pages::login_form).post(pages::login_submit))
         .route("/logout", post(pages::logout))

 **Rationale:** Foreground is correct for systemd and Docker, which own process
 lifecycle. This deviates from an earlier `server start`/`server stop` sketch.
+## 2026-07-25 — API nested into web via `nest_service`; web may depend on api
+**Decision:** The `/api/v1` JSON surface is a self-contained `Router` built by
+`api::router(store, config, secret)` with its own state applied, and `web` nests it
+with `.nest_service("/api/v1", …)`. `web` depends on `api`.
+**Alternatives:** Run the API on a separate port/server; have `api` depend on `web`
+(forbidden — nothing may depend on `web`).
+**Rationale:** The dependency rule bars anything depending on `web`, but says
+nothing against `web → api` (both are top-level). Nesting keeps one server, one
+port, and one middleware stack. Because the nested router is fully stated
+(`Router<()>`), `nest_service` mounts it as a `Service` and strips the `/api/v1`
+prefix, so `api` defines routes relative to root and never learns `web`'s
+`AppState`. Repo sub-resources are parsed by scanning `{*rest}` for the first
+keyword segment (`branches`/`tags`/`commits`/`tree`/`raw`); a repo named exactly
+after one of those would be misrouted — a documented MVP limitation. The API
+search returns name/description matches only (content search stays in `web`).
 ## 2026-07-25 — Search lives in `web`; `path:` is a substring for the MVP
 **Decision:** Search (the qualifier parser, in-repo scan, and bounded global scan)

+// 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 `/api/v1` handlers.
+use std::path::Path as FsPath;
+use auth::{Access, Scope};
+use axum::Json;
+use axum::extract::{Path, Query, State};
+use axum::http::{StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use model::{Repo, User};
+use serde::Deserialize;
+use serde_json::{Value, json};
+use crate::{ApiAuth, ApiError, ApiResult, ApiState, git_read, rfc3339, rfc3339_opt};
+/// Pagination + ref query parameters.
+#[derive(Debug, Default, Deserialize)]
+pub struct ListParams {
+    page: Option<usize>,
+    per_page: Option<usize>,
+    #[serde(rename = "ref")]
+    reference: Option<String>,
+    #[serde(default)]
+    q: Option<String>,
+    #[serde(default)]
+    purge: Option<bool>,
+}
+impl ListParams {
+    /// The zero-based offset and page size (`per_page` capped at 100).
+    fn page(&self) -> (usize, usize) {
+        let per_page = self.per_page.unwrap_or(30).clamp(1, 100);
+        let page = self.page.unwrap_or(1).max(1);
+        ((page - 1) * per_page, per_page)
+    }
+}
+/// `GET /version`.
+pub async fn version(State(state): State<ApiState>) -> Json<Value> {
+    Json(json!({
+        "name": state.config.instance.name,
+        "version": env!("CARGO_PKG_VERSION"),
+    }))
+}
+/// `GET /user` — the current token's user.
+pub async fn current_user(auth: ApiAuth) -> ApiResult<Json<Value>> {
+    Ok(Json(user_json(&auth.user)))
+}
+/// `GET /users` — admin only.
+pub async fn list_users(State(state): State<ApiState>, auth: ApiAuth) -> ApiResult<Response> {
+    auth.require(Scope::Admin)?;
+    let users = state.store.list_users().await?;
+    let total = users.len();
+    let (offset, limit) = ListParams::default().page();
+    let view: Vec<Value> = users
+        .iter()
+        .skip(offset)
+        .take(limit)
+        .map(user_json)
+        .collect();
+    Ok(with_total(Json(view), total))
+}
+/// `GET /repos` — repos visible to the token.
+pub async fn list_repos(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Query(params): Query<ListParams>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoRead)?;
+    let mut visible = Vec::new();
+    for repo in state.store.list_repos().await? {
+        if repo_access(&state, &auth, &repo).await? >= Access::Read {
+            visible.push(repo);
+        }
+    }
+    let total = visible.len();
+    let (offset, limit) = params.page();
+    let mut view = Vec::new();
+    for repo in visible.into_iter().skip(offset).take(limit) {
+        let owner = owner_name(&state, &repo.owner_id).await;
+        view.push(repo_json(&repo, &owner));
+    }
+    Ok(with_total(Json(view), total))
+}
+/// New-repo request body.
+#[derive(Debug, Deserialize)]
+pub struct CreateRepo {
+    owner: Option<String>,
+    name: String,
+    #[serde(default)]
+    private: Option<bool>,
+    #[serde(default)]
+    description: Option<String>,
+    #[serde(default)]
+    default_branch: Option<String>,
+}
+/// `POST /repos`.
+pub async fn create_repo(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Json(body): Json<CreateRepo>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoWrite)?;
+    // Resolve the owner; only an admin may create for someone else.
+    let owner = match &body.owner {
+        Some(name) => state
+            .store
+            .user_by_username(name)
+            .await?
+            .ok_or(ApiError::NotFound)?,
+        None => auth.user.clone(),
+    };
+    if owner.id != auth.user.id && !auth.user.is_admin {
+        return Err(ApiError::Forbidden("cannot create repos for another user"));
+    }
+    let (group_path, leaf) = match body.name.rsplit_once('/') {
+        Some((g, l)) => (Some(g.to_string()), l.to_string()),
+        None => (None, body.name.clone()),
+    };
+    let group_id = match &group_path {
+        Some(g) => Some(state.store.ensure_group_path(&owner.id, g).await?.id),
+        None => None,
+    };
+    let branch = body
+        .default_branch
+        .unwrap_or_else(|| state.config.instance.default_branch.clone());
+    let repo = state
+        .store
+        .create_repo(store::NewRepo {
+            owner_id: owner.id.clone(),
+            group_id,
+            name: leaf,
+            path: body.name.clone(),
+            description: body.description,
+            is_private: body.private.unwrap_or(true),
+            default_branch: branch.clone(),
+        })
+        .await?;
+    let hook = std::env::current_exe().unwrap_or_else(|_| std::path::PathBuf::from("fabrica"));
+    if let Err(err) = git::create_bare(&state.config.storage.repo_dir, &repo.id, &branch, &hook) {
+        let _ = state.store.delete_repo(&repo.id).await;
+        return Err(ApiError::internal(err));
+    }
+    Ok((StatusCode::CREATED, Json(repo_json(&repo, &owner.username))).into_response())
+}
+/// A parsed repo sub-resource.
+enum Sub {
+    Detail,
+    Branches,
+    Tags,
+    Commits,
+    Commit(String),
+    Tree(String, String),
+    Raw(String, String),
+}
+/// Split `{*rest}` into the repo path and its sub-resource. The first segment that
+/// is a known keyword ends the repo path (repos should not be named after these
+/// keywords — a documented MVP limitation).
+fn split_rest(rest: &str) -> (String, Sub) {
+    let segs: Vec<&str> = rest.split('/').filter(|s| !s.is_empty()).collect();
+    let keyword = segs
+        .iter()
+        .position(|s| matches!(*s, "branches" | "tags" | "commits" | "tree" | "raw"));
+    let Some(i) = keyword else {
+        return (segs.join("/"), Sub::Detail);
+    };
+    let repo_path = segs[..i].join("/");
+    let rest = &segs[i + 1..];
+    let sub = match segs[i] {
+        "branches" => Sub::Branches,
+        "tags" => Sub::Tags,
+        "commits" => rest
+            .first()
+            .map_or(Sub::Commits, |sha| Sub::Commit((*sha).to_string())),
+        "tree" => Sub::Tree(
+            rest.first().copied().unwrap_or_default().to_string(),
+            rest.get(1..).map(|s| s.join("/")).unwrap_or_default(),
+        ),
+        _ => Sub::Raw(
+            rest.first().copied().unwrap_or_default().to_string(),
+            rest.get(1..).map(|s| s.join("/")).unwrap_or_default(),
+        ),
+    };
+    (repo_path, sub)
+}
+/// `GET /repos/{owner}/{*rest}` — repo detail or a git sub-resource.
+pub async fn repo_get(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Query(params): Query<ListParams>,
+    Path((owner, rest)): Path<(String, String)>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoRead)?;
+    let (repo_path, sub) = split_rest(&rest);
+    let repo = resolve_repo(&state, &auth, &owner, &repo_path, Access::Read).await?;
+    let default_ref = repo.default_branch.clone();
+    match sub {
+        Sub::Detail => Ok(Json(repo_json(&repo, &owner)).into_response()),
+        Sub::Branches => {
+            let branches = git_read(&state, &repo.id, git::Repo::branches).await?;
+            let view: Vec<Value> = branches
+                .iter()
+                .map(|b| {
+                    json!({
+                        "name": b.name, "commit": b.oid.as_str(), "default": b.is_default,
+                        "ahead": b.ahead, "behind": b.behind,
+                    })
+                })
+                .collect();
+            Ok(Json(view).into_response())
+        }
+        Sub::Tags => {
+            let tags = git_read(&state, &repo.id, git::Repo::tags).await?;
+            let view: Vec<Value> = tags
+                .iter()
+                .map(|t| json!({ "name": t.name, "commit": t.oid.as_str(), "annotated": t.annotated }))
+                .collect();
+            Ok(Json(view).into_response())
+        }
+        Sub::Commits => {
+            let (offset, limit) = params.page();
+            let reference = params.reference.unwrap_or(default_ref);
+            let commits = git_read(&state, &repo.id, move |repo| {
+                let rev = repo.resolve_ref(&reference)?;
+                repo.commits(&rev, None, git::Page { offset, limit })
+            })
+            .await?;
+            let view: Vec<Value> = commits.iter().map(commit_summary_json).collect();
+            Ok(Json(view).into_response())
+        }
+        Sub::Commit(sha) => {
+            let detail = git_read(&state, &repo.id, move |repo| {
+                repo.commit(&git::Oid::new(sha))
+            })
+            .await?;
+            Ok(Json(commit_detail_json(&detail)).into_response())
+        }
+        Sub::Tree(reference, path) => {
+            let reference = if reference.is_empty() {
+                default_ref
+            } else {
+                reference
+            };
+            let entries = git_read(&state, &repo.id, move |repo| {
+                let rev = repo.resolve_ref(&reference)?;
+                repo.tree_entries(&rev, FsPath::new(&path))
+            })
+            .await?;
+            let view: Vec<Value> = entries
+                .iter()
+                .map(|e| {
+                    json!({
+                        "name": e.name, "kind": entry_kind(e.kind),
+                        "mode": format!("{:o}", e.mode), "oid": e.oid.as_str(), "size": e.size,
+                    })
+                })
+                .collect();
+            Ok(Json(view).into_response())
+        }
+        Sub::Raw(reference, path) => {
+            let reference = if reference.is_empty() {
+                default_ref
+            } else {
+                reference
+            };
+            let path2 = path.clone();
+            let blob = git_read(&state, &repo.id, move |repo| {
+                let rev = repo.resolve_ref(&reference)?;
+                repo.blob(&rev, FsPath::new(&path2))
+            })
+            .await?;
+            let content_type = if blob.is_binary {
+                "application/octet-stream"
+            } else {
+                "text/plain; charset=utf-8"
+            };
+            Ok((
+                [
+                    (header::CONTENT_TYPE, content_type),
+                    (header::X_CONTENT_TYPE_OPTIONS, "nosniff"),
+                ],
+                blob.content,
+            )
+                .into_response())
+        }
+    }
+}
+/// `DELETE /repos/{owner}/{*rest}?purge=`.
+pub async fn repo_delete(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Query(params): Query<ListParams>,
+    Path((owner, rest)): Path<(String, String)>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoAdmin)?;
+    let (repo_path, _) = split_rest(&rest);
+    let repo = resolve_repo(&state, &auth, &owner, &repo_path, Access::Admin).await?;
+    state.store.delete_repo(&repo.id).await?;
+    if let Ok(dir) = git::repo_path(&state.config.storage.repo_dir, &repo.id) {
+        if dir.exists() {
+            if params.purge.unwrap_or(false) {
+                let _ = std::fs::remove_dir_all(&dir);
+            } else {
+                let trash = state.config.storage.data_dir.join("trash").join(format!(
+                    "{}-{}.git",
+                    repo.id,
+                    crate::now_secs()
+                ));
+                if let Some(parent) = trash.parent() {
+                    let _ = std::fs::create_dir_all(parent);
+                }
+                let _ = std::fs::rename(&dir, &trash);
+            }
+        }
+    }
+    Ok(StatusCode::NO_CONTENT.into_response())
+}
+/// `GET /groups/{owner}`.
+pub async fn list_groups(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Path(owner): Path<String>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoRead)?;
+    let owner_user = state
+        .store
+        .user_by_username(&owner)
+        .await?
+        .ok_or(ApiError::NotFound)?;
+    let groups = state.store.groups_by_owner(&owner_user.id).await?;
+    let view: Vec<Value> = groups
+        .iter()
+        .map(|g| json!({ "name": g.name, "path": g.path, "description": g.description }))
+        .collect();
+    Ok(Json(view).into_response())
+}
+/// `GET /search?q=` — repos and users matching the query (name/description).
+pub async fn search(
+    State(state): State<ApiState>,
+    auth: ApiAuth,
+    Query(params): Query<ListParams>,
+) -> ApiResult<Response> {
+    auth.require(Scope::RepoRead)?;
+    let needle = params.q.unwrap_or_default().to_lowercase();
+    if needle.is_empty() {
+        return Ok(Json(json!({ "repos": [], "users": [] })).into_response());
+    }
+    let mut repos = Vec::new();
+    for repo in state.store.list_repos().await? {
+        if repo_access(&state, &auth, &repo).await? < Access::Read {
+            continue;
+        }
+        let owner = owner_name(&state, &repo.owner_id).await;
+        let hay = format!(
+            "{}/{} {}",
+            owner,
+            repo.path,
+            repo.description.clone().unwrap_or_default()
+        )
+        .to_lowercase();
+        if hay.contains(&needle) {
+            repos.push(repo_json(&repo, &owner));
+        }
+    }
+    let users: Vec<Value> = state
+        .store
+        .list_users()
+        .await?
+        .iter()
+        .filter(|u| u.username.to_lowercase().contains(&needle))
+        .map(user_json)
+        .collect();
+    Ok(Json(json!({ "repos": repos, "users": users })).into_response())
+}
+/// The API fallback for unmatched routes.
+pub async fn not_found() -> ApiError {
+    ApiError::NotFound
+}
+// ---- helpers ----
+/// Resolve `(owner, path)` to a repo the token may access at `required`, else 404.
+async fn resolve_repo(
+    state: &ApiState,
+    auth: &ApiAuth,
+    owner: &str,
+    repo_path: &str,
+    required: Access,
+) -> ApiResult<Repo> {
+    let owner_user = state
+        .store
+        .user_by_username(owner)
+        .await?
+        .ok_or(ApiError::NotFound)?;
+    let repo = state
+        .store
+        .repo_by_owner_path(&owner_user.id, repo_path)
+        .await?
+        .ok_or(ApiError::NotFound)?;
+    if repo_access(state, auth, &repo).await? >= required {
+        Ok(repo)
+    } else {
+        Err(ApiError::NotFound) // 404, never 403, for a private resource.
+    }
+}
+/// The token's access level to a repo.
+async fn repo_access(state: &ApiState, auth: &ApiAuth, repo: &Repo) -> ApiResult<Access> {
+    let collaborator = state
+        .store
+        .collaborator_permission(&repo.id, &auth.user.id)
+        .await?
+        .and_then(|p| auth::Permission::parse(&p));
+    Ok(auth::access(
+        Some(&auth.viewer()),
+        repo,
+        collaborator,
+        state.config.instance.allow_anonymous,
+    ))
+}
+/// Resolve an owner id to a username.
+async fn owner_name(state: &ApiState, owner_id: &str) -> String {
+    state
+        .store
+        .user_by_id(owner_id)
+        .await
+        .ok()
+        .flatten()
+        .map_or_else(|| owner_id.to_string(), |u| u.username)
+}
+/// Attach an `X-Total-Count` header to a JSON list response.
+fn with_total(json: Json<Vec<Value>>, total: usize) -> Response {
+    (
+        [(
+            header::HeaderName::from_static("x-total-count"),
+            header::HeaderValue::from(u64::try_from(total).unwrap_or(0)),
+        )],
+        json,
+    )
+        .into_response()
+}
+/// Render a user (never the password hash).
+fn user_json(user: &User) -> Value {
+    json!({
+        "username": user.username,
+        "email": user.email,
+        "display_name": user.display_name,
+        "is_admin": user.is_admin,
+        "disabled": user.disabled_at.is_some(),
+        "created_at": rfc3339(user.created_at),
+    })
+}
+/// Render a repo.
+fn repo_json(repo: &Repo, owner: &str) -> Value {
+    json!({
+        "id": repo.id,
+        "owner": owner,
+        "name": repo.name,
+        "path": repo.path,
+        "private": repo.is_private,
+        "default_branch": repo.default_branch,
+        "description": repo.description,
+        "archived": repo.archived_at.is_some(),
+        "size_bytes": repo.size_bytes,
+        "pushed_at": rfc3339_opt(repo.pushed_at),
+        "created_at": rfc3339(repo.created_at),
+        "updated_at": rfc3339(repo.updated_at),
+    })
+}
+/// Render a commit summary.
+fn commit_summary_json(c: &git::CommitSummary) -> Value {
+    json!({
+        "sha": c.oid.as_str(),
+        "summary": c.summary,
+        "author": { "name": c.author.name, "email": c.author.email, "date": rfc3339(c.author.time_ms) },
+        "parents": c.parents,
+    })
+}
+/// Render a full commit.
+fn commit_detail_json(c: &git::CommitDetail) -> Value {
+    json!({
+        "sha": c.oid.as_str(),
+        "message": c.message,
+        "tree": c.tree.as_str(),
+        "parents": c.parents.iter().map(git::Oid::as_str).collect::<Vec<_>>(),
+        "author": { "name": c.author.name, "email": c.author.email, "date": rfc3339(c.author.time_ms) },
+        "committer": { "name": c.committer.name, "email": c.committer.email, "date": rfc3339(c.committer.time_ms) },
+    })
+}
+/// The wire name for a tree entry kind.
+fn entry_kind(kind: git::EntryKind) -> &'static str {
+    match kind {
+        git::EntryKind::Directory => "dir",
+        git::EntryKind::File => "file",
+        git::EntryKind::Symlink => "symlink",
+        git::EntryKind::Submodule => "submodule",
+    }
+}

 // 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 JSON API surface.
+//! The JSON API served under `/api/v1`.
+//!
+//! Bearer-JWT authenticated (`auth`), scoped, and — like the web UI — it renders
+//! `404` (never `403`) for a private resource the token cannot reach, so existence
+//! never leaks. Errors share one shape:
+//! `{"error": {"code": …, "message": …, "details": {}}}`. Timestamps are RFC 3339
+//! strings on the wire even though they are epoch-ms at rest. The router is built
+//! by [`router`] and nested at `/api/v1` by the web server.
+mod handlers;
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+use axum::extract::FromRequestParts;
+use axum::http::request::Parts;
+use axum::http::{StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::get;
+use axum::{Json, Router};
+use config::Config;
+use model::User;
+use store::Store;
+/// Shared state for the API router.
+#[derive(Clone)]
+pub struct ApiState {
+    /// Database handle.
+    pub store: Store,
+    /// Effective configuration.
+    pub config: Arc<Config>,
+    /// The HS256 signing secret used to verify tokens.
+    pub secret: Arc<String>,
+}
+/// Build the API router, fully stated. Nest it at `/api/v1`.
+pub fn router(store: Store, config: Arc<Config>, secret: String) -> Router {
+    let state = ApiState {
+        store,
+        config,
+        secret: Arc::new(secret),
+    };
+    Router::new()
+        .route("/version", get(handlers::version))
+        .route("/user", get(handlers::current_user))
+        .route("/users", get(handlers::list_users))
+        .route(
+            "/repos",
+            get(handlers::list_repos).post(handlers::create_repo),
+        )
+        .route(
+            "/repos/{owner}/{*rest}",
+            get(handlers::repo_get).delete(handlers::repo_delete),
+        )
+        .route("/groups/{owner}", get(handlers::list_groups))
+        .route("/search", get(handlers::search))
+        .fallback(handlers::not_found)
+        .with_state(state)
+}
+/// An API error, rendered as the shared JSON error shape.
+#[derive(Debug)]
+pub enum ApiError {
+    /// 401 — missing or invalid bearer token.
+    Unauthorized(&'static str),
+    /// 403 — the token lacks the required scope.
+    Forbidden(&'static str),
+    /// 404 — missing, or a private resource the token cannot reach.
+    NotFound,
+    /// 400 — a malformed request.
+    BadRequest(String),
+    /// 409 — a uniqueness conflict.
+    Conflict(String),
+    /// 500 — an internal failure (detail logged, not shown).
+    Internal(String),
+}
+impl ApiError {
+    /// Build an internal error, logging the detail.
+    pub fn internal(detail: impl std::fmt::Display) -> Self {
+        Self::Internal(detail.to_string())
+    }
+}
+impl From<store::StoreError> for ApiError {
+    fn from(err: store::StoreError) -> Self {
+        match err {
+            store::StoreError::Conflict { entity, field } => {
+                Self::Conflict(format!("{entity} already exists with that {field}"))
+            }
+            store::StoreError::Name(e) => Self::BadRequest(e.to_string()),
+            other => Self::internal(other),
+        }
+    }
+}
+impl From<git::GitError> for ApiError {
+    fn from(err: git::GitError) -> Self {
+        Self::internal(err)
+    }
+}
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        let (status, code, message) = match self {
+            ApiError::Unauthorized(m) => (StatusCode::UNAUTHORIZED, "unauthorized", m.to_string()),
+            ApiError::Forbidden(m) => (StatusCode::FORBIDDEN, "forbidden", m.to_string()),
+            ApiError::NotFound => (StatusCode::NOT_FOUND, "not_found", "not found".to_string()),
+            ApiError::BadRequest(m) => (StatusCode::BAD_REQUEST, "bad_request", m),
+            ApiError::Conflict(m) => (StatusCode::CONFLICT, "conflict", m),
+            ApiError::Internal(detail) => {
+                tracing::error!(error.detail = %detail, "api internal error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "internal",
+                    "internal error".to_string(),
+                )
+            }
+        };
+        let body = Json(serde_json::json!({
+            "error": { "code": code, "message": message, "details": {} }
+        }));
+        let mut response = (status, body).into_response();
+        if status == StatusCode::UNAUTHORIZED {
+            response.headers_mut().insert(
+                header::WWW_AUTHENTICATE,
+                header::HeaderValue::from_static("Bearer"),
+            );
+        }
+        response
+    }
+}
+/// A result alias for API handlers.
+pub type ApiResult<T> = Result<T, ApiError>;
+/// The authenticated token identity, extracted from the `Authorization: Bearer`
+/// header. Verifies the signature and expiry, that the `jti` row exists and is not
+/// revoked, and that the user is enabled; bumps `last_used_at`.
+pub struct ApiAuth {
+    /// The token's user.
+    pub user: User,
+    /// The token's scopes.
+    pub scopes: Vec<auth::Scope>,
+}
+impl ApiAuth {
+    /// Require a scope; `admin` grants everything.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ApiError::Forbidden`] if the scope is absent.
+    pub fn require(&self, scope: auth::Scope) -> ApiResult<()> {
+        if self.scopes.contains(&scope) || self.scopes.contains(&auth::Scope::Admin) {
+            Ok(())
+        } else {
+            Err(ApiError::Forbidden("missing required scope"))
+        }
+    }
+    /// A [`auth::Viewer`] for permission checks.
+    #[must_use]
+    pub fn viewer(&self) -> auth::Viewer {
+        auth::Viewer {
+            id: self.user.id.clone(),
+            is_admin: self.user.is_admin,
+        }
+    }
+}
+impl FromRequestParts<ApiState> for ApiAuth {
+    type Rejection = ApiError;
+    async fn from_request_parts(
+        parts: &mut Parts,
+        state: &ApiState,
+    ) -> Result<Self, Self::Rejection> {
+        let token = parts
+            .headers
+            .get(header::AUTHORIZATION)
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| v.strip_prefix("Bearer "))
+            .ok_or(ApiError::Unauthorized("missing bearer token"))?;
+        let claims = auth::verify_jwt(&state.secret, token.trim(), now_secs())
+            .map_err(|_| ApiError::Unauthorized("invalid or expired token"))?;
+        // Revocation is real only because we check the jti row here.
+        let row = state
+            .store
+            .token_by_id(&claims.jti)
+            .await?
+            .ok_or(ApiError::Unauthorized("token revoked"))?;
+        if row.revoked_at.is_some() {
+            return Err(ApiError::Unauthorized("token revoked"));
+        }
+        let user = state
+            .store
+            .user_by_id(&claims.sub)
+            .await?
+            .ok_or(ApiError::Unauthorized("no such user"))?;
+        if user.disabled_at.is_some() {
+            return Err(ApiError::Unauthorized("account disabled"));
+        }
+        let _ = state.store.touch_token(&claims.jti).await;
+        Ok(Self {
+            user,
+            scopes: auth::parse_scopes(&claims.scopes).unwrap_or_default(),
+        })
+    }
+}
+/// The current time in Unix seconds.
+pub(crate) fn now_secs() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| i64::try_from(d.as_secs()).unwrap_or(i64::MAX))
+}
+/// Format an epoch-millisecond timestamp as an RFC 3339 string, or `null` on
+/// overflow.
+pub(crate) fn rfc3339(ms: i64) -> serde_json::Value {
+    let nanos = i128::from(ms) * 1_000_000;
+    match time::OffsetDateTime::from_unix_timestamp_nanos(nanos) {
+        Ok(dt) => dt
+            .format(&time::format_description::well_known::Rfc3339)
+            .map_or(serde_json::Value::Null, serde_json::Value::String),
+        Err(_) => serde_json::Value::Null,
+    }
+}
+/// Format an optional timestamp.
+pub(crate) fn rfc3339_opt(ms: Option<i64>) -> serde_json::Value {
+    ms.map_or(serde_json::Value::Null, rfc3339)
+}
+/// Run a blocking git read for a repo on the blocking pool.
+pub(crate) async fn git_read<T, F>(state: &ApiState, repo_id: &str, f: F) -> ApiResult<T>
+where
+    F: FnOnce(&git::Repo) -> Result<T, git::GitError> + Send + 'static,
+    T: Send + 'static,
+{
+    let repo_dir = state.config.storage.repo_dir.clone();
+    let repo_id = repo_id.to_string();
+    tokio::task::spawn_blocking(move || {
+        let path = git::repo_path(&repo_dir, &repo_id)?;
+        let repo = git::Repo::open_path(&path)?;
+        f(&repo)
+    })
+    .await
+    .map_err(ApiError::internal)?
+    .map_err(ApiError::from)
+}