@fuzdev/fuz_app 0.1.0

package/dist/auth/daemon_token.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Daemon token primitives — schema, generation, and validation.
+ *
+ * Pure auth operations with no I/O or state management.
+ * The middleware, rotation, and persistence logic lives in
+ * `daemon_token_middleware.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Daemon token format: 43 base64url characters (256 bits). */
+export declare const DaemonToken: z.ZodString;
+export type DaemonToken = z.infer<typeof DaemonToken>;
+/** The `X-Daemon-Token` header name. */
+export declare const DAEMON_TOKEN_HEADER = "X-Daemon-Token";
+/**
+ * Mutable runtime state for daemon token rotation.
+ *
+ * This is runtime state (not `AppDeps` or `*Options`) — it changes during
+ * operation. Created at server startup, passed to the middleware factory.
+ */
+export interface DaemonTokenState {
+    /** Current valid token. */
+    current_token: string;
+    /** Previous token, still valid during the race window. `null` before first rotation. */
+    previous_token: string | null;
+    /** When the last rotation occurred. */
+    rotated_at: Date;
+    /** The account ID of the keeper (resolved at startup, set by `on_bootstrap`). */
+    keeper_account_id: string | null;
+}
+/**
+ * Generate a new daemon token (256-bit random, base64url).
+ *
+ * @returns a 43-character base64url string
+ */
+export declare const generate_daemon_token: () => string;
+/**
+ * Validate a daemon token against the current state.
+ *
+ * Accepts both the current and previous token (2-token race window).
+ * Uses timing-safe comparison.
+ *
+ * @param provided - the token from the `X-Daemon-Token` header
+ * @param state - the daemon token state
+ * @returns `true` if the token is valid
+ */
+export declare const validate_daemon_token: (provided: string, state: DaemonTokenState) => boolean;
+//# sourceMappingURL=daemon_token.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daemon_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAKtB,+DAA+D;AAC/D,eAAO,MAAM,WAAW,aAAyE,CAAC;AAClG,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,uCAAuC;IACvC,UAAU,EAAE,IAAI,CAAC;IACjB,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAO,MAExC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,EAAE,OAAO,gBAAgB,KAAG,OAgBjF,CAAC"}

package/dist/auth/daemon_token.js

@@ -0,0 +1,49 @@
+/**
+ * Daemon token primitives — schema, generation, and validation.
+ *
+ * Pure auth operations with no I/O or state management.
+ * The middleware, rotation, and persistence logic lives in
+ * `daemon_token_middleware.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { timingSafeEqual } from 'node:crypto';
+import { generate_random_base64url } from '../crypto.js';
+/** Daemon token format: 43 base64url characters (256 bits). */
+export const DaemonToken = z.string().regex(/^[A-Za-z0-9_-]{43}$/, 'Invalid daemon token format');
+/** The `X-Daemon-Token` header name. */
+export const DAEMON_TOKEN_HEADER = 'X-Daemon-Token';
+/**
+ * Generate a new daemon token (256-bit random, base64url).
+ *
+ * @returns a 43-character base64url string
+ */
+export const generate_daemon_token = () => {
+    return generate_random_base64url();
+};
+/**
+ * Validate a daemon token against the current state.
+ *
+ * Accepts both the current and previous token (2-token race window).
+ * Uses timing-safe comparison.
+ *
+ * @param provided - the token from the `X-Daemon-Token` header
+ * @param state - the daemon token state
+ * @returns `true` if the token is valid
+ */
+export const validate_daemon_token = (provided, state) => {
+    const provided_buf = Buffer.from(provided);
+    const current_buf = Buffer.from(state.current_token);
+    if (provided_buf.length === current_buf.length && timingSafeEqual(provided_buf, current_buf)) {
+        return true;
+    }
+    if (state.previous_token !== null) {
+        const previous_buf = Buffer.from(state.previous_token);
+        if (provided_buf.length === previous_buf.length &&
+            timingSafeEqual(provided_buf, previous_buf)) {
+            return true;
+        }
+    }
+    return false;
+};

package/dist/auth/daemon_token_middleware.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Daemon token rotation, persistence, and middleware.
+ *
+ * Manages the lifecycle of filesystem-resident daemon tokens: writing to disk,
+ * rotation on an interval, and HTTP middleware for authentication.
+ *
+ * Pure token primitives (schema, generation, validation) live in `daemon_token.ts`.
+ * See docs/identity.md for design rationale.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type FsWriteDeps, type FsRemoveDeps, type EnvDeps } from '../runtime/deps.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import { type DaemonTokenState } from './daemon_token.js';
+/** Default rotation interval in milliseconds (30 seconds). */
+export declare const DEFAULT_ROTATION_INTERVAL_MS = 30000;
+/** Deps for writing the daemon token to disk. */
+export type DaemonTokenWriteDeps = Pick<EnvDeps, 'env_get'> & FsWriteDeps & {
+    /** Set file permissions. Optional — consumers provide when available (e.g. `Deno.chmod`). */
+    chmod?: (path: string, mode: number) => Promise<void>;
+};
+/**
+ * Get the daemon token file path (`~/.{name}/run/daemon_token`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `daemon_token`, or `null` if `$HOME` is not set
+ */
+export declare const get_daemon_token_path: (runtime: Pick<EnvDeps, "env_get">, name: string) => string | null;
+/**
+ * Write the current token to disk atomically.
+ *
+ * Uses `write_file_atomic` (temp file + rename) and optionally sets mode 0600.
+ *
+ * @param runtime - runtime with file write capabilities
+ * @param token_path - path to write the token
+ * @param token - the raw token string
+ */
+export declare const write_daemon_token: (runtime: DaemonTokenWriteDeps, token_path: string, token: string) => Promise<void>;
+/**
+ * Resolve the keeper account ID by querying for the account with an active keeper permit.
+ *
+ * There is exactly one keeper account (the bootstrap account). Runs once at
+ * server startup — the result is cached in `DaemonTokenState.keeper_account_id`.
+ *
+ * @param deps - query dependencies
+ * @returns the keeper account ID, or `null` if no keeper exists yet (pre-bootstrap)
+ */
+export declare const resolve_keeper_account_id: (deps: QueryDeps) => Promise<string | null>;
+/** Options for daemon token rotation. */
+export interface DaemonTokenRotationOptions {
+    /** Application name (for `~/.{name}/run/daemon_token`). */
+    app_name: string;
+    /** Rotation interval in ms. Default: `30000` (30s). */
+    rotation_interval_ms?: number;
+}
+/** Result of starting daemon token rotation. */
+export interface DaemonTokenRotation {
+    /** The mutable runtime state. Pass to `create_daemon_token_middleware`. */
+    state: DaemonTokenState;
+    /** Stop rotation, clean up the interval, and delete the token file. Call on graceful shutdown. */
+    stop: () => Promise<void>;
+}
+/**
+ * Start daemon token rotation.
+ *
+ * Generates an initial token, writes it to disk, resolves the keeper account,
+ * and sets up periodic rotation. Returns the mutable state object and a stop function.
+ *
+ * @param runtime - runtime with file, env, and remove capabilities
+ * @param deps - query dependencies for resolving keeper account
+ * @param options - rotation configuration
+ * @param log - the logger instance
+ * @returns rotation state and stop function
+ */
+export declare const start_daemon_token_rotation: (runtime: DaemonTokenWriteDeps & FsRemoveDeps, deps: QueryDeps, options: DaemonTokenRotationOptions, log: Logger) => Promise<DaemonTokenRotation>;
+/**
+ * Create middleware that authenticates via daemon token.
+ *
+ * Checks the `X-Daemon-Token` header. Behavior:
+ * - No header: pass through (don't touch existing context)
+ * - Header present + valid: build `RequestContext` from keeper account,
+ *   set `credential_type: 'daemon_token'` (overrides any existing session/bearer context)
+ * - Header present + invalid: return 401 (fail-closed, no downgrade)
+ * - Header present + valid but `keeper_account_id` is null: return 503
+ *
+ * @param state - the daemon token runtime state
+ * @param deps - query dependencies (pool-level db for middleware)
+ */
+export declare const create_daemon_token_middleware: (state: DaemonTokenState, deps: QueryDeps) => MiddlewareHandler;
+//# sourceMappingURL=daemon_token_middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daemon_token_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAWrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAC1D,WAAW,GAAG;IACb,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,oBAAoB,EAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACX,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAEtF,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,gBAAgB,CAAC;IACxB,kGAAkG;IAClG,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,oBAAoB,GAAG,YAAY,EAC5C,MAAM,SAAS,EACf,SAAS,0BAA0B,EACnC,KAAK,MAAM,KACT,OAAO,CAAC,mBAAmB,CAwD7B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,gBAAgB,EACvB,MAAM,SAAS,KACb,iBAoCF,CAAC"}

package/dist/auth/daemon_token_middleware.js

@@ -0,0 +1,167 @@
+/**
+ * Daemon token rotation, persistence, and middleware.
+ *
+ * Manages the lifecycle of filesystem-resident daemon tokens: writing to disk,
+ * rotation on an interval, and HTTP middleware for authentication.
+ *
+ * Pure token primitives (schema, generation, validation) live in `daemon_token.ts`.
+ * See docs/identity.md for design rationale.
+ *
+ * @module
+ */
+import {} from '../runtime/deps.js';
+import { write_file_atomic } from '../runtime/fs.js';
+import { get_app_dir } from '../cli/config.js';
+import { REQUEST_CONTEXT_KEY, build_request_context } from './request_context.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { ERROR_INVALID_DAEMON_TOKEN, ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED, ERROR_KEEPER_ACCOUNT_NOT_FOUND, } from '../http/error_schemas.js';
+import { query_permit_find_account_id_for_role } from './permit_queries.js';
+import { ROLE_KEEPER } from './role_schema.js';
+import { DaemonToken, DAEMON_TOKEN_HEADER, generate_daemon_token, validate_daemon_token, } from './daemon_token.js';
+/** Default rotation interval in milliseconds (30 seconds). */
+export const DEFAULT_ROTATION_INTERVAL_MS = 30_000;
+/**
+ * Get the daemon token file path (`~/.{name}/run/daemon_token`).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param name - application name
+ * @returns path to `daemon_token`, or `null` if `$HOME` is not set
+ */
+export const get_daemon_token_path = (runtime, name) => {
+    const app_dir = get_app_dir(runtime, name);
+    return app_dir ? `${app_dir}/run/daemon_token` : null;
+};
+/**
+ * Write the current token to disk atomically.
+ *
+ * Uses `write_file_atomic` (temp file + rename) and optionally sets mode 0600.
+ *
+ * @param runtime - runtime with file write capabilities
+ * @param token_path - path to write the token
+ * @param token - the raw token string
+ */
+export const write_daemon_token = async (runtime, token_path, token) => {
+    await write_file_atomic(runtime, token_path, token + '\n');
+    if (runtime.chmod) {
+        await runtime.chmod(token_path, 0o600);
+    }
+};
+/**
+ * Resolve the keeper account ID by querying for the account with an active keeper permit.
+ *
+ * There is exactly one keeper account (the bootstrap account). Runs once at
+ * server startup — the result is cached in `DaemonTokenState.keeper_account_id`.
+ *
+ * @param deps - query dependencies
+ * @returns the keeper account ID, or `null` if no keeper exists yet (pre-bootstrap)
+ */
+export const resolve_keeper_account_id = async (deps) => {
+    return query_permit_find_account_id_for_role(deps, ROLE_KEEPER);
+};
+/**
+ * Start daemon token rotation.
+ *
+ * Generates an initial token, writes it to disk, resolves the keeper account,
+ * and sets up periodic rotation. Returns the mutable state object and a stop function.
+ *
+ * @param runtime - runtime with file, env, and remove capabilities
+ * @param deps - query dependencies for resolving keeper account
+ * @param options - rotation configuration
+ * @param log - the logger instance
+ * @returns rotation state and stop function
+ */
+export const start_daemon_token_rotation = async (runtime, deps, options, log) => {
+    const { app_name, rotation_interval_ms = DEFAULT_ROTATION_INTERVAL_MS } = options;
+    const token_path = get_daemon_token_path(runtime, app_name);
+    if (!token_path) {
+        throw new Error('$HOME not set — cannot determine daemon token path');
+    }
+    // ensure run directory exists
+    const app_dir = get_app_dir(runtime, app_name);
+    if (app_dir) {
+        await runtime.mkdir(`${app_dir}/run`, { recursive: true });
+    }
+    // resolve keeper account (may be null pre-bootstrap)
+    const keeper_account_id = await resolve_keeper_account_id(deps);
+    // generate initial token and write to disk
+    const initial_token = generate_daemon_token();
+    await write_daemon_token(runtime, token_path, initial_token);
+    const state = {
+        current_token: initial_token,
+        previous_token: null,
+        rotated_at: new Date(),
+        keeper_account_id,
+    };
+    let writing = false;
+    const interval_id = setInterval(async () => {
+        if (writing)
+            return; // skip if previous rotation write still in progress
+        writing = true;
+        try {
+            const new_token = generate_daemon_token();
+            state.previous_token = state.current_token;
+            state.current_token = new_token;
+            state.rotated_at = new Date();
+            await write_daemon_token(runtime, token_path, new_token);
+        }
+        catch (err) {
+            log.error('Failed to write rotated token:', err);
+        }
+        finally {
+            writing = false;
+        }
+    }, rotation_interval_ms);
+    const stop = async () => {
+        clearInterval(interval_id);
+        try {
+            await runtime.remove(token_path);
+        }
+        catch {
+            // already removed or never written
+        }
+    };
+    return { state, stop };
+};
+/**
+ * Create middleware that authenticates via daemon token.
+ *
+ * Checks the `X-Daemon-Token` header. Behavior:
+ * - No header: pass through (don't touch existing context)
+ * - Header present + valid: build `RequestContext` from keeper account,
+ *   set `credential_type: 'daemon_token'` (overrides any existing session/bearer context)
+ * - Header present + invalid: return 401 (fail-closed, no downgrade)
+ * - Header present + valid but `keeper_account_id` is null: return 503
+ *
+ * @param state - the daemon token runtime state
+ * @param deps - query dependencies (pool-level db for middleware)
+ */
+export const create_daemon_token_middleware = (state, deps) => {
+    return async (c, next) => {
+        const token_header = c.req.header(DAEMON_TOKEN_HEADER);
+        if (!token_header) {
+            await next();
+            return;
+        }
+        // Zod-validate the token format at the I/O boundary
+        const parse_result = DaemonToken.safeParse(token_header);
+        if (!parse_result.success) {
+            return c.json({ error: ERROR_INVALID_DAEMON_TOKEN }, 401);
+        }
+        // fail-closed: header present but invalid token value
+        if (!validate_daemon_token(parse_result.data, state)) {
+            return c.json({ error: ERROR_INVALID_DAEMON_TOKEN }, 401);
+        }
+        // daemon token valid — resolve keeper account
+        if (!state.keeper_account_id) {
+            return c.json({ error: ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED }, 503);
+        }
+        // build request context from the keeper account (overrides any existing session/bearer context)
+        const ctx = await build_request_context(deps, state.keeper_account_id);
+        if (!ctx) {
+            return c.json({ error: ERROR_KEEPER_ACCOUNT_NOT_FOUND }, 500);
+        }
+        c.set(REQUEST_CONTEXT_KEY, ctx);
+        c.set(CREDENTIAL_TYPE_KEY, 'daemon_token');
+        await next();
+    };
+};

package/dist/auth/ddl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Auth table DDL — CREATE TABLE, index, and seed statements.
+ *
+ * Consumed by `migrations.ts`. Separated from `account_schema.ts`
+ * to isolate DDL concerns from runtime types.
+ *
+ * @module
+ */
+export declare const ACCOUNT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS account (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  username TEXT UNIQUE NOT NULL,\n  email TEXT,\n  email_verified BOOLEAN NOT NULL DEFAULT false,\n  password_hash TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  created_by UUID,\n  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_by UUID\n)";
+export declare const ACTOR_SCHEMA = "\nCREATE TABLE IF NOT EXISTS actor (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  name TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at TIMESTAMPTZ,\n  updated_by UUID REFERENCES actor(id) ON DELETE SET NULL\n)";
+export declare const ACTOR_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_actor_account ON actor(account_id)";
+export declare const PERMIT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS permit (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,\n  role TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ,\n  revoked_at TIMESTAMPTZ,\n  revoked_by UUID REFERENCES actor(id) ON DELETE SET NULL,\n  granted_by UUID REFERENCES actor(id) ON DELETE SET NULL\n)";
+export declare const PERMIT_INDEXES: string[];
+export declare const AUTH_SESSION_SCHEMA = "\nCREATE TABLE IF NOT EXISTS auth_session (\n  id TEXT PRIMARY KEY,\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ NOT NULL,\n  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)";
+export declare const AUTH_SESSION_INDEXES: string[];
+export declare const API_TOKEN_SCHEMA = "\nCREATE TABLE IF NOT EXISTS api_token (\n  id TEXT PRIMARY KEY,\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  name TEXT NOT NULL,\n  token_hash TEXT NOT NULL,\n  expires_at TIMESTAMPTZ,\n  last_used_at TIMESTAMPTZ,\n  last_used_ip TEXT,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)";
+export declare const ACCOUNT_EMAIL_INDEX = "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_account_email ON account (LOWER(email)) WHERE email IS NOT NULL";
+export declare const ACCOUNT_USERNAME_CI_INDEX = "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_account_username_ci ON account (LOWER(username))";
+export declare const API_TOKEN_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_api_token_account ON api_token(account_id)";
+export declare const BOOTSTRAP_LOCK_SCHEMA = "\nCREATE TABLE IF NOT EXISTS bootstrap_lock (\n  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),\n  bootstrapped BOOLEAN NOT NULL DEFAULT false\n)";
+/** Seed the bootstrap_lock table, setting `bootstrapped` based on whether accounts exist. */
+export declare const BOOTSTRAP_LOCK_SEED = "\nINSERT INTO bootstrap_lock (id, bootstrapped)\n  SELECT 1, EXISTS(SELECT 1 FROM account)\n  ON CONFLICT DO NOTHING";
+export declare const INVITE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS invite (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email TEXT,\n  username TEXT,\n  claimed_by UUID REFERENCES account(id) ON DELETE SET NULL,\n  claimed_at TIMESTAMPTZ,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  created_by UUID REFERENCES actor(id) ON DELETE SET NULL,\n  CONSTRAINT invite_has_identifier CHECK (email IS NOT NULL OR username IS NOT NULL)\n)";
+export declare const INVITE_INDEXES: string[];
+export declare const APP_SETTINGS_SCHEMA = "\nCREATE TABLE IF NOT EXISTS app_settings (\n  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),\n  open_signup BOOLEAN NOT NULL DEFAULT false,\n  updated_at TIMESTAMPTZ,\n  updated_by UUID\n)";
+export declare const APP_SETTINGS_SEED = "\nINSERT INTO app_settings (id) VALUES (1) ON CONFLICT DO NOTHING";
+//# sourceMappingURL=ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,cAAc,8WAWzB,CAAC;AAEH,eAAO,MAAM,YAAY,mUAQvB,CAAC;AAEH,eAAO,MAAM,WAAW,wEAC0C,CAAC;AAEnE,eAAO,MAAM,aAAa,uZAUxB,CAAC;AAEH,eAAO,MAAM,cAAc,UAI1B,CAAC;AAEF,eAAO,MAAM,mBAAmB,0RAO9B,CAAC;AAEH,eAAO,MAAM,oBAAoB,UAGhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,iUAU3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,4GACsE,CAAC;AAEvG,eAAO,MAAM,yBAAyB,6FACiD,CAAC;AAExF,eAAO,MAAM,eAAe,gFAC8C,CAAC;AAE3E,eAAO,MAAM,qBAAqB,wJAIhC,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,yHAGP,CAAC;AAE1B,eAAO,MAAM,aAAa,6ZAUxB,CAAC;AAEH,eAAO,MAAM,cAAc,UAI1B,CAAC;AAEF,eAAO,MAAM,mBAAmB,oMAM9B,CAAC;AAEH,eAAO,MAAM,iBAAiB,sEACkC,CAAC"}

package/dist/auth/ddl.js

@@ -0,0 +1,111 @@
+/**
+ * Auth table DDL — CREATE TABLE, index, and seed statements.
+ *
+ * Consumed by `migrations.ts`. Separated from `account_schema.ts`
+ * to isolate DDL concerns from runtime types.
+ *
+ * @module
+ */
+export const ACCOUNT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS account (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  username TEXT UNIQUE NOT NULL,
+  email TEXT,
+  email_verified BOOLEAN NOT NULL DEFAULT false,
+  password_hash TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_by UUID,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_by UUID
+)`;
+export const ACTOR_SCHEMA = `
+CREATE TABLE IF NOT EXISTS actor (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ,
+  updated_by UUID REFERENCES actor(id) ON DELETE SET NULL
+)`;
+export const ACTOR_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_actor_account ON actor(account_id)`;
+export const PERMIT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS permit (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at TIMESTAMPTZ,
+  revoked_at TIMESTAMPTZ,
+  revoked_by UUID REFERENCES actor(id) ON DELETE SET NULL,
+  granted_by UUID REFERENCES actor(id) ON DELETE SET NULL
+)`;
+export const PERMIT_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_permit_actor ON permit(actor_id)`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS permit_actor_role_active_unique
+    ON permit (actor_id, role) WHERE revoked_at IS NULL`,
+];
+export const AUTH_SESSION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS auth_session (
+  id TEXT PRIMARY KEY,
+  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at TIMESTAMPTZ NOT NULL,
+  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`;
+export const AUTH_SESSION_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_auth_session_account ON auth_session(account_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_auth_session_expires ON auth_session(expires_at)`,
+];
+export const API_TOKEN_SCHEMA = `
+CREATE TABLE IF NOT EXISTS api_token (
+  id TEXT PRIMARY KEY,
+  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  expires_at TIMESTAMPTZ,
+  last_used_at TIMESTAMPTZ,
+  last_used_ip TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`;
+export const ACCOUNT_EMAIL_INDEX = `
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_email ON account (LOWER(email)) WHERE email IS NOT NULL`;
+export const ACCOUNT_USERNAME_CI_INDEX = `
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_username_ci ON account (LOWER(username))`;
+export const API_TOKEN_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_api_token_account ON api_token(account_id)`;
+export const BOOTSTRAP_LOCK_SCHEMA = `
+CREATE TABLE IF NOT EXISTS bootstrap_lock (
+  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+  bootstrapped BOOLEAN NOT NULL DEFAULT false
+)`;
+/** Seed the bootstrap_lock table, setting `bootstrapped` based on whether accounts exist. */
+export const BOOTSTRAP_LOCK_SEED = `
+INSERT INTO bootstrap_lock (id, bootstrapped)
+  SELECT 1, EXISTS(SELECT 1 FROM account)
+  ON CONFLICT DO NOTHING`;
+export const INVITE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS invite (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT,
+  username TEXT,
+  claimed_by UUID REFERENCES account(id) ON DELETE SET NULL,
+  claimed_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_by UUID REFERENCES actor(id) ON DELETE SET NULL,
+  CONSTRAINT invite_has_identifier CHECK (email IS NOT NULL OR username IS NOT NULL)
+)`;
+export const INVITE_INDEXES = [
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_invite_email_unclaimed ON invite (LOWER(email)) WHERE email IS NOT NULL AND claimed_at IS NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_invite_username_unclaimed ON invite (LOWER(username)) WHERE username IS NOT NULL AND claimed_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_invite_claimed ON invite (claimed_at)`,
+];
+export const APP_SETTINGS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS app_settings (
+  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+  open_signup BOOLEAN NOT NULL DEFAULT false,
+  updated_at TIMESTAMPTZ,
+  updated_by UUID
+)`;
+export const APP_SETTINGS_SEED = `
+INSERT INTO app_settings (id) VALUES (1) ON CONFLICT DO NOTHING`;

package/dist/auth/deps.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stateless capabilities bundle for fuz_app backends.
+ *
+ * `AppDeps` is the central dependency injection type — injectable and swappable
+ * per environment (production vs test). Does not contain config (static values)
+ * or runtime state (mutable refs).
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Keyring } from './keyring.js';
+import type { PasswordHashDeps } from './password.js';
+import type { Db } from '../db/db.js';
+import type { StatResult } from '../runtime/deps.js';
+import type { AuditLogEvent } from './audit_log_schema.js';
+/**
+ * Stateless capabilities bundle for fuz_app backends.
+ *
+ * Injectable and swappable per environment (production vs test).
+ * Does not contain config (static values) or runtime state (mutable refs).
+ */
+export interface AppDeps {
+    /** Get file/directory stats, or null if path doesn't exist. */
+    stat: (path: string) => Promise<StatResult | null>;
+    /** Read a file as text. */
+    read_file: (path: string) => Promise<string>;
+    /** Delete a file. */
+    delete_file: (path: string) => Promise<void>;
+    /** HMAC-SHA256 cookie signing keyring. */
+    keyring: Keyring;
+    /** Password hashing operations. Use `argon2_password_deps` in production. */
+    password: PasswordHashDeps;
+    /** Database instance. */
+    db: Db;
+    /** Structured logger instance. */
+    log: Logger;
+    /**
+     * Called after each audit log INSERT succeeds.
+     * Use to broadcast audit events via SSE. Flows automatically to all
+     * route factories that receive `deps` or `RouteFactoryDeps`.
+     * Defaults to a noop when not wired to SSE.
+     */
+    on_audit_event: (event: AuditLogEvent) => void;
+}
+/**
+ * Capabilities for route spec factories.
+ *
+ * `AppDeps` without `db` — route handlers receive database connections
+ * via `RouteContext`, so factories don't capture a pool-level `Db`.
+ */
+export type RouteFactoryDeps = Omit<AppDeps, 'db'>;
+//# sourceMappingURL=deps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACvB,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,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,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yBAAyB;IACzB,EAAE,EAAE,EAAE,CAAC;IACP,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC"}

package/dist/auth/deps.js

@@ -0,0 +1,10 @@
+/**
+ * Stateless capabilities bundle for fuz_app backends.
+ *
+ * `AppDeps` is the central dependency injection type — injectable and swappable
+ * per environment (production vs test). Does not contain config (static values)
+ * or runtime state (mutable refs).
+ *
+ * @module
+ */
+export {};

package/dist/auth/invite_queries.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Invite database queries.
+ *
+ * CRUD operations for the invite table — creating invites,
+ * finding unclaimed matches, claiming, and cleanup.
+ *
+ * @module
+ */
+import type { QueryDeps } from '../db/query_deps.js';
+import type { Invite, CreateInviteInput, InviteWithUsernamesJson } from './invite_schema.js';
+/**
+ * Create a new invite.
+ *
+ * @param deps - query dependencies
+ * @param input - the invite fields
+ * @returns the created invite
+ */
+export declare const query_create_invite: (deps: QueryDeps, input: CreateInviteInput) => Promise<Invite>;
+/**
+ * Find an unclaimed invite by email (case-insensitive).
+ */
+export declare const query_invite_find_unclaimed_by_email: (deps: QueryDeps, email: string) => Promise<Invite | undefined>;
+/**
+ * Find an unclaimed invite by username (case-insensitive).
+ */
+export declare const query_invite_find_unclaimed_by_username: (deps: QueryDeps, username: string) => Promise<Invite | undefined>;
+/**
+ * Find an unclaimed invite matching email and/or username using three scoping modes:
+ *
+ * - **Email-only invite** (email set, username NULL) → matches only if signup provides matching email.
+ * - **Username-only invite** (username set, email NULL) → matches only if signup provides matching username.
+ * - **Both-field invite** (both set) → requires BOTH email and username to match.
+ *
+ * @param deps - query dependencies
+ * @param email - email to match (or null if signup provides none)
+ * @param username - username to match
+ * @returns the matching invite, or `undefined`
+ */
+export declare const query_invite_find_unclaimed_match: (deps: QueryDeps, email: string | null, username: string) => Promise<Invite | undefined>;
+/**
+ * Claim an invite by setting the claimed_by and claimed_at fields.
+ *
+ * @param deps - query dependencies
+ * @param invite_id - the invite to claim
+ * @param account_id - the account claiming the invite
+ * @returns true if the invite was claimed, false if already claimed or not found
+ */
+export declare const query_invite_claim: (deps: QueryDeps, invite_id: string, account_id: string) => Promise<boolean>;
+/**
+ * List all invites, newest first.
+ */
+export declare const query_invite_list_all: (deps: QueryDeps) => Promise<Array<Invite>>;
+/**
+ * List all invites with resolved creator/claimer usernames, newest first.
+ *
+ * @param deps - query dependencies
+ * @returns invites with `created_by_username` and `claimed_by_username`
+ */
+export declare const query_invite_list_all_with_usernames: (deps: QueryDeps) => Promise<Array<InviteWithUsernamesJson>>;
+/**
+ * Delete an unclaimed invite.
+ *
+ * @param deps - query dependencies
+ * @param id - the invite id
+ * @returns true if deleted, false if not found or already claimed
+ */
+export declare const query_invite_delete_unclaimed: (deps: QueryDeps, id: string) => Promise<boolean>;
+//# sourceMappingURL=invite_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invite_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,OAAO,MAAM,GAAG,IAAI,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAe5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAElF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAUxC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,CAMjB,CAAC"}