@fuzdev/fuz_app 0.1.0

package/dist/auth/audit_log_schema.js

@@ -0,0 +1,123 @@
+/**
+ * Audit log database schema and types.
+ *
+ * Records auth mutations (login, logout, grant, revoke, etc.) for
+ * security monitoring and operational visibility.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { AuthSessionJson } from './account_schema.js';
+/** All tracked auth event types. */
+export const AUDIT_EVENT_TYPES = [
+    'login',
+    'logout',
+    'bootstrap',
+    'signup',
+    'password_change',
+    'session_revoke',
+    'session_revoke_all',
+    'token_create',
+    'token_revoke',
+    'token_revoke_all',
+    'permit_grant',
+    'permit_revoke',
+    'invite_create',
+    'invite_delete',
+    'app_settings_update',
+];
+/** Zod schema for audit event types. */
+export const AuditEventType = z.enum(AUDIT_EVENT_TYPES);
+/** Zod schema for audit event outcomes. */
+export const AuditOutcome = z.enum(['success', 'failure']);
+/**
+ * Per-event-type metadata Zod schemas.
+ *
+ * Uses `z.looseObject` so consumers can add extra fields
+ * (e.g. visiones `self_service`) while known fields are validated.
+ * Events with outcome-dependent metadata use a union with `z.null()`.
+ */
+export const AUDIT_METADATA_SCHEMAS = {
+    login: z.looseObject({ username: z.string() }).nullable(),
+    logout: z.null(),
+    bootstrap: z.looseObject({ error: z.string() }).nullable(),
+    signup: z.looseObject({
+        username: z.string(),
+        invite_id: z.string().optional(),
+        open_signup: z.boolean().optional(),
+    }),
+    password_change: z.looseObject({ sessions_revoked: z.number() }).nullable(),
+    session_revoke: z.looseObject({ session_id: z.string() }),
+    session_revoke_all: z.looseObject({ count: z.number() }),
+    token_create: z.looseObject({ token_id: z.string(), name: z.string() }),
+    token_revoke: z.looseObject({ token_id: z.string() }),
+    token_revoke_all: z.looseObject({ count: z.number() }),
+    permit_grant: z.looseObject({ role: z.string(), permit_id: z.string() }),
+    permit_revoke: z.looseObject({ role: z.string(), permit_id: z.string() }),
+    invite_create: z.looseObject({
+        invite_id: z.string(),
+        email: z.string().nullable(),
+        username: z.string().nullable(),
+    }),
+    invite_delete: z.looseObject({ invite_id: z.string() }),
+    app_settings_update: z.looseObject({
+        setting: z.string(),
+        old_value: z.unknown(),
+        new_value: z.unknown(),
+    }),
+};
+/**
+ * Narrow metadata type for a known event type.
+ *
+ * Use after checking `event_type` to get typed metadata access.
+ */
+export const get_audit_metadata = (event) => {
+    return event.metadata;
+};
+/** Zod schema for client-safe audit log event. */
+export const AuditLogEventJson = z.strictObject({
+    id: z.string(),
+    seq: z.number().int(),
+    event_type: AuditEventType,
+    outcome: AuditOutcome,
+    actor_id: z.string().nullable(),
+    account_id: z.string().nullable(),
+    target_account_id: z.string().nullable(),
+    ip: z.string().nullable(),
+    created_at: z.string(),
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+/** Zod schema for audit log events with resolved usernames. */
+export const AuditLogEventWithUsernamesJson = AuditLogEventJson.extend({
+    username: z.string().nullable(),
+    target_username: z.string().nullable(),
+});
+/** Zod schema for permit history events with resolved usernames. */
+export const PermitHistoryEventJson = AuditLogEventJson.extend({
+    username: z.string().nullable(),
+    target_username: z.string().nullable(),
+});
+/** Zod schema for admin session listing (session + username). */
+export const AdminSessionJson = AuthSessionJson.extend({
+    username: z.string(),
+});
+// Schema DDL
+export const AUDIT_LOG_SCHEMA = `
+CREATE TABLE IF NOT EXISTS audit_log (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  seq SERIAL NOT NULL,
+  event_type TEXT NOT NULL,
+  outcome TEXT NOT NULL DEFAULT 'success',
+  actor_id UUID REFERENCES actor(id) ON DELETE SET NULL,
+  account_id UUID REFERENCES account(id) ON DELETE SET NULL,
+  target_account_id UUID REFERENCES account(id) ON DELETE SET NULL,
+  ip TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  metadata JSONB
+)`;
+export const AUDIT_LOG_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_audit_log_seq ON audit_log(seq DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_audit_log_account ON audit_log(account_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_audit_log_event_type ON audit_log(event_type)`,
+    `CREATE INDEX IF NOT EXISTS idx_audit_log_target_account ON audit_log(target_account_id)`,
+];

package/dist/auth/bearer_auth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bearer auth middleware for API token authentication.
+ *
+ * Bearer tokens are rejected when `Origin` or `Referer` headers are present —
+ * browsers must use cookie auth. This reduces attack surface: a stolen token
+ * cannot be replayed from a browser context (the browser adds `Origin`
+ * automatically).
+ *
+ * Token generation and hashing utilities live in `auth/api_token.ts`.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import { type RateLimiter } from '../rate_limiter.js';
+/**
+ * Create middleware that authenticates via bearer token.
+ *
+ * Rejects bearer tokens when an `Origin` or `Referer` header is present —
+ * browsers must use cookie auth to reduce attack surface.
+ * Auth scheme matching is case-insensitive per RFC 7235.
+ * On success, builds the request context (`{ account, actor, permits }`)
+ * and sets it on the Hono context. Skips if a request context is already set
+ * (e.g. by session middleware).
+ *
+ * @param deps - query dependencies (pool-level db for middleware)
+ * @param ip_rate_limiter - per-IP rate limiter for bearer token attempts (null to disable)
+ * @param log - the logger instance
+ */
+export declare const create_bearer_auth_middleware: (deps: QueryDeps, ip_rate_limiter: RateLimiter | null, log: Logger) => MiddlewareHandler;
+//# sourceMappingURL=bearer_auth.d.ts.map

package/dist/auth/bearer_auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bearer_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAKpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAOlF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,iBAAiB,WAAW,GAAG,IAAI,EACnC,KAAK,MAAM,KACT,iBAwEF,CAAC"}

package/dist/auth/bearer_auth.js

@@ -0,0 +1,90 @@
+/**
+ * Bearer auth middleware for API token authentication.
+ *
+ * Bearer tokens are rejected when `Origin` or `Referer` headers are present —
+ * browsers must use cookie auth. This reduces attack surface: a stolen token
+ * cannot be replayed from a browser context (the browser adds `Origin`
+ * automatically).
+ *
+ * Token generation and hashing utilities live in `auth/api_token.ts`.
+ *
+ * @module
+ */
+import { REQUEST_CONTEXT_KEY, build_request_context } from './request_context.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { query_validate_api_token } from './api_token_queries.js';
+import { get_client_ip } from '../http/proxy.js';
+import { rate_limit_exceeded_response } from '../rate_limiter.js';
+import { ERROR_BEARER_REJECTED_BROWSER, ERROR_INVALID_TOKEN, ERROR_ACCOUNT_NOT_FOUND, } from '../http/error_schemas.js';
+/**
+ * Create middleware that authenticates via bearer token.
+ *
+ * Rejects bearer tokens when an `Origin` or `Referer` header is present —
+ * browsers must use cookie auth to reduce attack surface.
+ * Auth scheme matching is case-insensitive per RFC 7235.
+ * On success, builds the request context (`{ account, actor, permits }`)
+ * and sets it on the Hono context. Skips if a request context is already set
+ * (e.g. by session middleware).
+ *
+ * @param deps - query dependencies (pool-level db for middleware)
+ * @param ip_rate_limiter - per-IP rate limiter for bearer token attempts (null to disable)
+ * @param log - the logger instance
+ */
+export const create_bearer_auth_middleware = (deps, ip_rate_limiter, log) => {
+    return async (c, next) => {
+        // Skip if already authenticated via session
+        if (c.get(REQUEST_CONTEXT_KEY)) {
+            await next();
+            return;
+        }
+        const auth_header = c.req.header('Authorization');
+        // Case-insensitive scheme matching per RFC 7235 §2.1 — defense-in-depth:
+        // without this, a `bearer` (lowercase) header silently bypasses token
+        // validation and browser-context rejection instead of being processed.
+        // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+        if (!auth_header || auth_header.slice(0, 7).toLowerCase() !== 'bearer ') {
+            await next();
+            return;
+        }
+        // Reject bearer tokens in browser context — defense-in-depth:
+        // checks both Origin and Referer (not just Origin) because some browser
+        // requests send only Referer. Uses `!== undefined` so that empty-string
+        // headers (e.g. `Origin: ''`) are still treated as browser context.
+        if (c.req.header('Origin') !== undefined || c.req.header('Referer') !== undefined) {
+            return c.json({ error: ERROR_BEARER_REJECTED_BROWSER }, 403);
+        }
+        const raw_token = auth_header.slice(7);
+        // Reject empty token body before any hashing or DB work.
+        // (The Fetch API trims 'Bearer ' to 'Bearer' which skips this middleware entirely,
+        // but raw HTTP clients may send 'Bearer ' with an empty token.)
+        if (!raw_token) {
+            return c.json({ error: ERROR_INVALID_TOKEN }, 401);
+        }
+        const ip = get_client_ip(c);
+        // Per-IP rate limit: record before async DB work to close the TOCTOU
+        // window where concurrent requests could all pass check() before any
+        // reaches record(). On valid token, reset the counter below.
+        if (ip_rate_limiter) {
+            const check = ip_rate_limiter.check(ip);
+            if (!check.allowed) {
+                return rate_limit_exceeded_response(c, check.retry_after);
+            }
+            ip_rate_limiter.record(ip);
+        }
+        const api_token = await query_validate_api_token({ ...deps, log }, raw_token, ip, c.var.pending_effects);
+        if (!api_token) {
+            return c.json({ error: ERROR_INVALID_TOKEN }, 401);
+        }
+        // Valid token — reset rate limit counter
+        if (ip_rate_limiter)
+            ip_rate_limiter.reset(ip);
+        // Build request context from the token's account
+        const ctx = await build_request_context(deps, api_token.account_id);
+        if (!ctx) {
+            return c.json({ error: ERROR_ACCOUNT_NOT_FOUND }, 401);
+        }
+        c.set(REQUEST_CONTEXT_KEY, ctx);
+        c.set(CREDENTIAL_TYPE_KEY, 'api_token');
+        await next();
+    };
+};

package/dist/auth/bootstrap_account.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Bootstrap flow for creating the first account.
+ *
+ * Uses an atomic `bootstrap_lock` table to prevent TOCTOU race conditions.
+ * Token verification and account creation happen in a single transaction.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { PasswordHashDeps } from './password.js';
+import { ERROR_INVALID_TOKEN, ERROR_ALREADY_BOOTSTRAPPED, ERROR_TOKEN_FILE_MISSING } from '../http/error_schemas.js';
+import type { Account, Actor, Permit } from './account_schema.js';
+import type { Db } from '../db/db.js';
+/** Input for the bootstrap account creation. */
+export interface BootstrapAccountInput {
+    username: string;
+    password: string;
+}
+/** Successful bootstrap result with the created entities. */
+export interface BootstrapAccountSuccess {
+    ok: true;
+    account: Account;
+    actor: Actor;
+    permits: {
+        keeper: Permit;
+        admin: Permit;
+    };
+    /** Whether the bootstrap token file was successfully deleted after account creation. */
+    token_file_deleted: boolean;
+}
+/** Bootstrap failure result. */
+export type BootstrapAccountFailure = {
+    ok: false;
+    error: typeof ERROR_ALREADY_BOOTSTRAPPED;
+    status: 403;
+} | {
+    ok: false;
+    error: typeof ERROR_TOKEN_FILE_MISSING;
+    status: 404;
+} | {
+    ok: false;
+    error: typeof ERROR_INVALID_TOKEN;
+    status: 401;
+};
+/** Bootstrap account result — either success or a bootstrap verification failure. */
+export type BootstrapAccountResult = BootstrapAccountSuccess | BootstrapAccountFailure;
+/**
+ * Dependencies for `bootstrap_account`.
+ */
+export interface BootstrapAccountDeps {
+    db: Db;
+    /** Path to the bootstrap token file on disk. */
+    token_path: string;
+    /** Read a file's contents as a string. */
+    read_file: (path: string) => Promise<string>;
+    /** Delete a file. */
+    delete_file: (path: string) => Promise<void>;
+    /** Only hashing is needed — verification happens separately during login. */
+    password: Pick<PasswordHashDeps, 'hash_password'>;
+    /** Structured logger instance. */
+    log: Logger;
+}
+/**
+ * Bootstrap the first account with keeper and admin privileges.
+ *
+ * Uses an atomic `bootstrap_lock` UPDATE to prevent concurrent bootstrap
+ * attempts (TOCTOU). The full flow runs in a single transaction:
+ *
+ * 1. Read and verify the bootstrap token (before transaction)
+ * 2. Hash the password (CPU-intensive, before transaction)
+ * 3. Acquire the bootstrap lock atomically (inside transaction)
+ * 4. Create account + actor
+ * 5. Grant keeper and admin permits (no expiry, `granted_by = null`)
+ * 6. Delete the token file (after commit, reported via `token_file_deleted`)
+ *
+ * @param deps - database, token path, filesystem callbacks, and password hashing
+ * @param provided_token - the bootstrap token from the user
+ * @param input - username and password
+ * @returns the created account, actor, and permits — or a bootstrap failure
+ */
+export declare const bootstrap_account: (deps: BootstrapAccountDeps, provided_token: string, input: BootstrapAccountInput) => Promise<BootstrapAccountResult>;
+//# sourceMappingURL=bootstrap_account.d.ts.map

package/dist/auth/bootstrap_account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap_account.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;IACzC,wFAAwF;IACxF,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAChC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,0BAA0B,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAClE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAChE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,CAAC;AAE/D,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,EAAE,CAAC;IACP,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,oBAAoB,EAC1B,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CA4EhC,CAAC"}

package/dist/auth/bootstrap_account.js

@@ -0,0 +1,97 @@
+/**
+ * Bootstrap flow for creating the first account.
+ *
+ * Uses an atomic `bootstrap_lock` table to prevent TOCTOU race conditions.
+ * Token verification and account creation happen in a single transaction.
+ *
+ * @module
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { ERROR_INVALID_TOKEN, ERROR_ALREADY_BOOTSTRAPPED, ERROR_TOKEN_FILE_MISSING, } from '../http/error_schemas.js';
+import { ROLE_ADMIN, ROLE_KEEPER } from './role_schema.js';
+import { query_create_account_with_actor, query_account_has_any } from './account_queries.js';
+import { query_grant_permit } from './permit_queries.js';
+/**
+ * Bootstrap the first account with keeper and admin privileges.
+ *
+ * Uses an atomic `bootstrap_lock` UPDATE to prevent concurrent bootstrap
+ * attempts (TOCTOU). The full flow runs in a single transaction:
+ *
+ * 1. Read and verify the bootstrap token (before transaction)
+ * 2. Hash the password (CPU-intensive, before transaction)
+ * 3. Acquire the bootstrap lock atomically (inside transaction)
+ * 4. Create account + actor
+ * 5. Grant keeper and admin permits (no expiry, `granted_by = null`)
+ * 6. Delete the token file (after commit, reported via `token_file_deleted`)
+ *
+ * @param deps - database, token path, filesystem callbacks, and password hashing
+ * @param provided_token - the bootstrap token from the user
+ * @param input - username and password
+ * @returns the created account, actor, and permits — or a bootstrap failure
+ */
+export const bootstrap_account = async (deps, provided_token, input) => {
+    const { db, token_path, read_file, delete_file, password, log } = deps;
+    // 1. Read and verify token (non-destructive, before transaction)
+    let expected_token;
+    try {
+        expected_token = (await read_file(token_path)).trim();
+    }
+    catch {
+        return { ok: false, error: ERROR_TOKEN_FILE_MISSING, status: 404 };
+    }
+    // Defense-in-depth: no .trim() on provided_token — tokens must match exactly.
+    // The expected_token is already trimmed above.
+    const provided_buf = Buffer.from(provided_token);
+    const expected_buf = Buffer.from(expected_token);
+    if (provided_buf.length !== expected_buf.length || !timingSafeEqual(provided_buf, expected_buf)) {
+        return { ok: false, error: ERROR_INVALID_TOKEN, status: 401 };
+    }
+    // 2. Hash password (CPU-intensive, before transaction)
+    const password_hash = await password.hash_password(input.password);
+    // 3. Atomic transaction: lock + create
+    const tx_result = await db.transaction(async (tx) => {
+        const lock_rows = await tx.query('UPDATE bootstrap_lock SET bootstrapped = true WHERE id = 1 AND bootstrapped = false RETURNING id');
+        if (lock_rows.length === 0) {
+            return { ok: false, error: ERROR_ALREADY_BOOTSTRAPPED, status: 403 };
+        }
+        // Belt-and-suspenders: verify no accounts exist even if lock was available
+        if (await query_account_has_any({ db: tx })) {
+            return { ok: false, error: ERROR_ALREADY_BOOTSTRAPPED, status: 403 };
+        }
+        const tx_deps = { db: tx };
+        const { account, actor } = await query_create_account_with_actor(tx_deps, {
+            username: input.username,
+            password_hash,
+        });
+        const keeper_permit = await query_grant_permit(tx_deps, {
+            actor_id: actor.id,
+            role: ROLE_KEEPER,
+            granted_by: null,
+            expires_at: null,
+        });
+        const admin_permit = await query_grant_permit(tx_deps, {
+            actor_id: actor.id,
+            role: ROLE_ADMIN,
+            granted_by: null,
+            expires_at: null,
+        });
+        return {
+            ok: true,
+            account,
+            actor,
+            permits: { keeper: keeper_permit, admin: admin_permit },
+        };
+    });
+    if (!tx_result.ok)
+        return tx_result;
+    // 4. Delete token file (after commit)
+    let token_file_deleted = true;
+    try {
+        await delete_file(token_path);
+    }
+    catch {
+        token_file_deleted = false;
+        log.error(`CRITICAL: Failed to delete bootstrap token file at ${token_path}. Delete it manually.`);
+    }
+    return { ...tx_result, token_file_deleted };
+};

package/dist/auth/bootstrap_routes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bootstrap route spec for first-time account creation.
+ *
+ * One-shot endpoint: exchanges a bootstrap token + credentials for
+ * an account with keeper privileges and a session cookie.
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { SessionOptions } from './session_cookie.js';
+import { type BootstrapAccountSuccess } from './bootstrap_account.js';
+import type { Db } from '../db/db.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import { type RateLimiter } from '../rate_limiter.js';
+import type { RouteFactoryDeps } from './deps.js';
+import type { StatResult } from '../runtime/deps.js';
+/**
+ * Bootstrap status — runtime state computed once at startup.
+ */
+export interface BootstrapStatus {
+    available: boolean;
+    token_path: string | null;
+}
+/**
+ * Per-factory configuration for bootstrap route specs.
+ *
+ * `bootstrap_status` is runtime state (a mutable ref), not a dep or options value —
+ * it is passed through so the route handler can flip it on success.
+ */
+export interface BootstrapRouteOptions {
+    session_options: SessionOptions<string>;
+    /** Shared mutable reference — flipped to false after successful bootstrap. */
+    bootstrap_status: BootstrapStatus;
+    /**
+     * Called after successful bootstrap (account + session created).
+     * Use for app-specific post-bootstrap work like generating API tokens.
+     */
+    on_bootstrap?: (result: BootstrapAccountSuccess, c: Context) => Promise<void>;
+    /** Rate limiter for bootstrap attempts (per-IP). Pass `null` to disable. */
+    ip_rate_limiter: RateLimiter | null;
+}
+/**
+ * Dependencies for checking bootstrap status at startup.
+ */
+export interface CheckBootstrapStatusDeps {
+    stat: (path: string) => Promise<StatResult | null>;
+    db: Db;
+    log: Logger;
+}
+/**
+ * Check bootstrap availability at startup.
+ *
+ * Bootstrap is available when:
+ * 1. A token path is configured
+ * 2. The token file exists on disk
+ * 3. The `bootstrap_lock` table shows `bootstrapped = false`
+ *
+ * @param deps - filesystem and database access for the check
+ * @param options - static configuration including `token_path`
+ * @returns an object with `available` (boolean) and `token_path` (string | null)
+ */
+export declare const check_bootstrap_status: (deps: CheckBootstrapStatusDeps, options: {
+    token_path: string | null;
+}) => Promise<BootstrapStatus>;
+/**
+ * Create bootstrap route specs for first-time account creation.
+ *
+ * @param deps - stateless capabilities including filesystem access
+ * @param options - per-factory configuration (session, token path, bootstrap status)
+ * @returns route specs (not yet applied to Hono)
+ */
+export declare const create_bootstrap_route_specs: (deps: RouteFactoryDeps, options: BootstrapRouteOptions) => Array<RouteSpec>;
+//# sourceMappingURL=bootstrap_routes.d.ts.map

package/dist/auth/bootstrap_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAoB,KAAK,uBAAuB,EAAC,MAAM,wBAAwB,CAAC;AAGvF,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAenD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACrC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,8EAA8E;IAC9E,gBAAgB,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,4EAA4E;IAC5E,eAAe,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,EAAE,EAAE,EAAE,CAAC;IACP,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,wBAAwB,EAC9B,SAAS;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,KAClC,OAAO,CAAC,eAAe,CAwBzB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,gBAAgB,EACtB,SAAS,qBAAqB,KAC5B,KAAK,CAAC,SAAS,CAsHjB,CAAC"}

package/dist/auth/bootstrap_routes.js

@@ -0,0 +1,154 @@
+/**
+ * Bootstrap route spec for first-time account creation.
+ *
+ * One-shot endpoint: exchanges a bootstrap token + credentials for
+ * an account with keeper privileges and a session cookie.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { create_session_and_set_cookie } from './session_lifecycle.js';
+import { bootstrap_account } from './bootstrap_account.js';
+import { Username } from './account_schema.js';
+import { Password } from './password.js';
+import { get_route_input } from '../http/route_spec.js';
+import { get_client_ip } from '../http/proxy.js';
+import { rate_limit_exceeded_response } from '../rate_limiter.js';
+import { ERROR_BOOTSTRAP_NOT_CONFIGURED, ERROR_INVALID_TOKEN, ERROR_ALREADY_BOOTSTRAPPED, ERROR_TOKEN_FILE_MISSING, } from '../http/error_schemas.js';
+import { audit_log_fire_and_forget } from './audit_log_queries.js';
+const bootstrap_input = z.strictObject({
+    token: z.string().min(1).meta({ sensitivity: 'secret' }),
+    username: Username,
+    password: Password,
+});
+/**
+ * Check bootstrap availability at startup.
+ *
+ * Bootstrap is available when:
+ * 1. A token path is configured
+ * 2. The token file exists on disk
+ * 3. The `bootstrap_lock` table shows `bootstrapped = false`
+ *
+ * @param deps - filesystem and database access for the check
+ * @param options - static configuration including `token_path`
+ * @returns an object with `available` (boolean) and `token_path` (string | null)
+ */
+export const check_bootstrap_status = async (deps, options) => {
+    const { stat, db, log } = deps;
+    const { token_path } = options;
+    if (!token_path) {
+        return { available: false, token_path: null };
+    }
+    const token_stat = await stat(token_path);
+    if (token_stat === null) {
+        log.info('Bootstrap unavailable: token file not found');
+        return { available: false, token_path };
+    }
+    const lock_row = await db.query_one('SELECT bootstrapped FROM bootstrap_lock WHERE id = 1');
+    if (lock_row?.bootstrapped) {
+        log.info('Bootstrap unavailable: already bootstrapped');
+        return { available: false, token_path };
+    }
+    log.info(`Bootstrap token available: ${token_path}`);
+    return { available: true, token_path };
+};
+/**
+ * Create bootstrap route specs for first-time account creation.
+ *
+ * @param deps - stateless capabilities including filesystem access
+ * @param options - per-factory configuration (session, token path, bootstrap status)
+ * @returns route specs (not yet applied to Hono)
+ */
+export const create_bootstrap_route_specs = (deps, options) => {
+    const { keyring, on_audit_event } = deps;
+    const { session_options, bootstrap_status, on_bootstrap, ip_rate_limiter } = options;
+    const { token_path } = bootstrap_status;
+    return [
+        {
+            method: 'POST',
+            path: '/bootstrap',
+            auth: { type: 'none' },
+            description: 'Create initial keeper account (one-shot)',
+            transaction: false, // bootstrap_account manages its own transaction
+            input: bootstrap_input,
+            output: z.strictObject({ ok: z.literal(true), username: z.string() }),
+            rate_limit: 'ip',
+            errors: {
+                401: z.looseObject({ error: z.literal(ERROR_INVALID_TOKEN) }),
+                403: z.looseObject({ error: z.literal(ERROR_ALREADY_BOOTSTRAPPED) }),
+                404: z.looseObject({
+                    error: z.enum([ERROR_TOKEN_FILE_MISSING, ERROR_BOOTSTRAP_NOT_CONFIGURED]),
+                }),
+            },
+            handler: async (c, route) => {
+                // Short-circuit if bootstrap already completed
+                if (!bootstrap_status.available) {
+                    return c.json({ error: ERROR_ALREADY_BOOTSTRAPPED }, 403);
+                }
+                // Per-IP rate limit check (before any token/DB work)
+                const ip = ip_rate_limiter ? get_client_ip(c) : null;
+                if (ip_rate_limiter && ip) {
+                    const check = ip_rate_limiter.check(ip);
+                    if (!check.allowed) {
+                        return rate_limit_exceeded_response(c, check.retry_after);
+                    }
+                }
+                const input = get_route_input(c);
+                if (token_path === null) {
+                    return c.json({ error: ERROR_BOOTSTRAP_NOT_CONFIGURED }, 404);
+                }
+                const result = await bootstrap_account({
+                    db: route.background_db,
+                    token_path,
+                    read_file: deps.read_file,
+                    delete_file: deps.delete_file,
+                    password: deps.password,
+                    log: deps.log,
+                }, input.token, input);
+                if (!result.ok) {
+                    if (ip_rate_limiter && ip)
+                        ip_rate_limiter.record(ip);
+                    void audit_log_fire_and_forget(route, {
+                        event_type: 'bootstrap',
+                        outcome: 'failure',
+                        ip: get_client_ip(c),
+                        metadata: { error: result.error },
+                    }, deps.log, on_audit_event);
+                    return c.json({ error: result.error }, result.status);
+                }
+                // Successful bootstrap — update state immediately
+                if (ip_rate_limiter && ip)
+                    ip_rate_limiter.reset(ip);
+                bootstrap_status.available = false;
+                await create_session_and_set_cookie({
+                    keyring,
+                    deps: { db: route.background_db },
+                    c,
+                    account_id: result.account.id,
+                    session_options,
+                });
+                if (on_bootstrap) {
+                    try {
+                        await on_bootstrap(result, c);
+                    }
+                    catch (err) {
+                        deps.log.error(`on_bootstrap callback failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'bootstrap',
+                    actor_id: result.actor.id,
+                    account_id: result.account.id,
+                    ip: get_client_ip(c),
+                }, deps.log, on_audit_event);
+                // CRITICAL: If token file deletion failed, throw to force operator attention.
+                // All success work (session, on_bootstrap, audit) has completed above.
+                // The error response alerts the operator to delete the token file manually.
+                if (!result.token_file_deleted) {
+                    throw new Error(`Bootstrap succeeded but token file was not deleted at ${token_path}. Delete it manually and log in.`);
+                }
+                return c.json({ ok: true, username: result.account.username });
+            },
+        },
+    ];
+};