@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/auth/cleanup.js

@@ -1,17 +1,17 @@
 /**
- * Periodic auth cleanup — sweeps expired sessions and permit offers.
+ * Periodic auth cleanup — sweeps expired sessions and role_grant offers.
  *
  * Single entry point for consumers scheduling auth maintenance. Internally
  * runs every known sweep and emits the corresponding audit events so
  * consumer code only manages cadence, not per-task wiring.
  *
  * The per-task primitives remain exported from their home modules
- * (`query_session_cleanup_expired`, `query_permit_offer_sweep_expired`);
- * `cleanup_expired_permit_offers` here wraps the latter with the required
- * `permit_offer_expire` audit emission and is the piece most likely to be
+ * (`query_session_cleanup_expired`, `query_role_grant_offer_sweep_expired`);
+ * `cleanup_expired_role_grant_offers` here wraps the latter with the required
+ * `role_grant_offer_expire` audit emission and is the piece most likely to be
  * reused in a consumer's bespoke scheduler.
  *
- * Idempotency: the audit log has no tombstone on `permit_offer_expire`, so
+ * Idempotency: the audit log has no tombstone on `role_grant_offer_expire`, so
  * concurrent sweep runs double-audit. The expected deployment pattern is a
  * single scheduled invocation per instance — matching
  * `query_session_cleanup_expired`.
@@ -19,73 +19,59 @@
  * @module
  */
 import { query_session_cleanup_expired } from './session_queries.js';
-import { query_permit_offer_sweep_expired } from './permit_offer_queries.js';
-import { query_audit_log } from './audit_log_queries.js';
+import { query_role_grant_offer_sweep_expired } from './role_grant_offer_queries.js';
 /**
- * Sweep expired permit offers and emit one `permit_offer_expire` audit
+ * Sweep expired role_grant offers and emit one `role_grant_offer_expire` audit
  * event per row.
  *
  * Returns the count of offers audit-stamped. The offer rows themselves are
  * preserved — offers carry audit value for the history view even after
- * expiry, and accepted rows are the provenance for the resulting permit
+ * expiry, and accepted rows are the provenance for the resulting role_grant
  * (deleting expired rows would not threaten that, but keeping them uniform
  * with the retention policy for terminal rows is simpler).
  *
- * @mutates `audit_log` table - inserts one `permit_offer_expire` row per swept offer
+ * @mutates `audit_log` table - inserts one `role_grant_offer_expire` row per swept offer
  */
-export const cleanup_expired_permit_offers = async (deps) => {
-    const expired = await query_permit_offer_sweep_expired(deps);
-    const { on_audit_event, audit_log_config } = deps;
+export const cleanup_expired_role_grant_offers = async (deps) => {
+    const expired = await query_role_grant_offer_sweep_expired(deps);
     for (const offer of expired) {
-        try {
-            // `permit_offer_expire` populates `target_actor_id` only when the
-            // offer was actor-targeted (`to_actor_id` set at create time).
-            // Account-grain offers (no `to_actor_id`) never bound to a
-            // specific actor and leave the field null.
-            const event = await query_audit_log(deps, {
-                event_type: 'permit_offer_expire',
-                actor_id: offer.from_actor_id,
-                target_account_id: offer.to_account_id,
-                target_actor_id: offer.to_actor_id,
-                ip: null,
-                metadata: {
-                    offer_id: offer.id,
-                    role: offer.role,
-                    scope_id: offer.scope_id,
-                },
-            }, audit_log_config);
-            if (on_audit_event) {
-                try {
-                    on_audit_event(event);
-                }
-                catch (callback_err) {
-                    deps.log.error('on_audit_event callback failed:', callback_err);
-                }
-            }
-        }
-        catch (err) {
-            // One failed audit write must not starve siblings — log and continue.
-            deps.log.error('permit_offer_expire audit write failed:', err);
-        }
+        // `role_grant_offer_expire` populates `target_actor_id` only when the
+        // offer was actor-targeted (`to_actor_id` set at create time).
+        // Account-grain offers (no `to_actor_id`) never bound to a
+        // specific actor and leave the field null.
+        // `emit_pool` swallows + logs both write errors and per-listener
+        // throws, so a single bad row never starves the rest of the sweep.
+        await deps.audit.emit_pool({
+            event_type: 'role_grant_offer_expire',
+            actor_id: offer.from_actor_id,
+            target_account_id: offer.to_account_id,
+            target_actor_id: offer.to_actor_id,
+            ip: null,
+            metadata: {
+                offer_id: offer.id,
+                role: offer.role,
+                scope_id: offer.scope_id,
+            },
+        });
     }
     return expired.length;
 };
 /**
- * Run every auth cleanup sweep — expired sessions and expired permit
+ * Run every auth cleanup sweep — expired sessions and expired role_grant
  * offers — and return the counts.
  *
  * Consumers call this from a scheduled task (setInterval, cron, etc.)
  * alongside their own domain cleanup. Errors from individual sweeps are
  * re-thrown so the caller's scheduler can log/alert; use the per-task
- * helpers (`query_session_cleanup_expired`, `cleanup_expired_permit_offers`)
+ * helpers (`query_session_cleanup_expired`, `cleanup_expired_role_grant_offers`)
  * directly if you need finer error isolation.
  *
  * @mutates `auth_session` table - deletes expired sessions
- * @mutates `audit_log` table - emits `permit_offer_expire` rows for expired offers
+ * @mutates `audit_log` table - emits `role_grant_offer_expire` rows for expired offers
  * @throws Error re-thrown from any sweep that fails (no per-sweep isolation here)
  */
 export const run_auth_cleanup = async (deps) => {
     const expired_sessions = await query_session_cleanup_expired(deps);
-    const expired_offers = await cleanup_expired_permit_offers(deps);
+    const expired_offers = await cleanup_expired_role_grant_offers(deps);
     return { expired_sessions, expired_offers };
 };

package/dist/auth/credential_type_schema.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Credential-type registry — how a request was authenticated.
+ *
+ * Three builtins: `session` (cookie-based), `api_token` (HTTP Bearer
+ * token), `daemon_token` (filesystem proof for the keeper account).
+ * Open-string registry on top so consumers can declare additional
+ * credential types (e.g. `'sso_assertion'`, `'agent_token'`) without an
+ * upstream release. `RoleSpec.required_credential_types` references
+ * entries from this registry; v1 keeps the field informative-only
+ * (consumed by `auth/middleware.ts` and the dispatcher). Mirrors the
+ * open-registry pattern used for `RoleName`, `ScopeKindName`,
+ * `GrantPathName`, and `AuditEventTypeName`.
+ *
+ * The Hono-side wire-validated `CredentialType` Zod enum (in
+ * `hono_context.ts`) is the closed-set narrow type middleware sets on
+ * the context; the constants below are the source of truth for those
+ * three string values. Future builtin credential types added here
+ * propagate to the wire enum by editing the import list.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Letter (lowercase a-z) start and end (or single letter), with letters
+ * and underscores in between. Mirrors `RoleName`, `ScopeKindName`,
+ * `GrantPathName`. Rejects empty strings, leading or trailing
+ * underscores, uppercase, and digits.
+ */
+export declare const CREDENTIAL_TYPE_NAME_REGEX: RegExp;
+/** Zod schema for valid credential-type name strings. */
+export declare const CredentialTypeName: z.ZodString;
+export type CredentialTypeName = z.infer<typeof CredentialTypeName>;
+/** Cookie-based session credential. */
+export declare const CREDENTIAL_TYPE_SESSION = "session";
+/**
+ * HTTP `Authorization: Bearer` API token credential. The wire literal
+ * `'api_token'` aligns with the `api_token` storage table name; the
+ * constant is named `_API_TOKEN` (not `_BEARER`) to keep wire and
+ * storage nomenclature in lockstep.
+ */
+export declare const CREDENTIAL_TYPE_API_TOKEN = "api_token";
+/** Daemon-token credential — filesystem proof for the keeper account. */
+export declare const CREDENTIAL_TYPE_DAEMON_TOKEN = "daemon_token";
+/** The builtin credential-type names as a const tuple. */
+export declare const BUILTIN_CREDENTIAL_TYPES: readonly ["session", "api_token", "daemon_token"];
+/** Zod enum for builtin credential types only. */
+export declare const BuiltinCredentialType: z.ZodEnum<{
+    daemon_token: "daemon_token";
+    session: "session";
+    api_token: "api_token";
+}>;
+export type BuiltinCredentialType = z.infer<typeof BuiltinCredentialType>;
+/**
+ * Per-credential-type metadata. `description` is admin-UI-facing copy
+ * (mirrors `RoleSpec.description` and `ScopeKindMeta.description`).
+ * Open shape so v2 can extend without a breaking change.
+ */
+export interface CredentialTypeMeta {
+    description?: string;
+}
+/**
+ * Builtin credential-type metadata. Not overridable by consumers.
+ *
+ * Typed `ReadonlyMap` for the contract — but JS Maps don't honor
+ * `Object.freeze` for `.set` / `.delete` / `.clear` (they mutate
+ * internal slots, not own properties), so freeze adds no runtime guard
+ * here. Read once at startup by `create_credential_type_schema`;
+ * runtime mutation has no effect on already-built schemas.
+ */
+export declare const BUILTIN_CREDENTIAL_TYPE_META: ReadonlyMap<string, CredentialTypeMeta>;
+/** The result of `create_credential_type_schema` — a Zod schema and metadata map. */
+export interface CredentialTypeSchemaResult {
+    /**
+     * Zod schema that validates credential-type name strings against the
+     * registered set (builtins + consumer-declared). Use at I/O
+     * boundaries (admin UIs, codegen) and as the construction-time check
+     * inside `create_role_schema` for every
+     * `RoleSpec.required_credential_types` entry.
+     */
+    CredentialType: z.ZodType<string>;
+    /**
+     * Map of every registered credential-type to its metadata. Keyed by
+     * name. Read at startup by admin / codegen surfaces.
+     */
+    credential_types: ReadonlyMap<string, CredentialTypeMeta>;
+}
+/**
+ * Create a credential-type schema from the builtin set plus optional
+ * consumer-declared additions.
+ *
+ * Builtins (`session`, `api_token`, `daemon_token`) are always present;
+ * consumer entries that collide with a builtin name throw at
+ * construction. Pass the result into `create_role_schema`'s optional
+ * `credential_types` parameter so each role's
+ * `required_credential_types` entries are validated against this set
+ * at construction time.
+ *
+ * @param consumer_types - optional consumer-declared credential-type set with optional metadata
+ * @returns `{CredentialType, credential_types}` — Zod schema and metadata map
+ *
+ * @throws Error if any `consumer_types` key fails the `CredentialTypeName` regex, collides with a builtin name, or appears more than once
+ *
+ * @example
+ * ```ts
+ * // simple — builtins only
+ * const {CredentialType, credential_types} = create_credential_type_schema();
+ *
+ * // with consumer extensions
+ * const {CredentialType} = create_credential_type_schema({
+ *   sso_assertion: {description: 'OIDC SSO assertion bound to an IdP-asserted account.'},
+ * });
+ * ```
+ */
+export declare const create_credential_type_schema: (consumer_types?: Record<string, CredentialTypeMeta>) => CredentialTypeSchemaResult;
+//# sourceMappingURL=credential_type_schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credential_type_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/credential_type_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAgC,CAAC;AAExE,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,aAK7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAIpE,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAE3D,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,mDAI3B,CAAC;AAEX,kDAAkD;AAClD,eAAO,MAAM,qBAAqB;;;;EAAmC,CAAC;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAa/E,CAAC;AAEH,qFAAqF;AACrF,MAAM,WAAW,0BAA0B;IAC1C;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC;;;OAGG;IACH,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,6BAA6B,GACzC,iBAAgB,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAM,KACrD,0BA2BF,CAAC"}

package/dist/auth/credential_type_schema.js

@@ -0,0 +1,127 @@
+/**
+ * Credential-type registry — how a request was authenticated.
+ *
+ * Three builtins: `session` (cookie-based), `api_token` (HTTP Bearer
+ * token), `daemon_token` (filesystem proof for the keeper account).
+ * Open-string registry on top so consumers can declare additional
+ * credential types (e.g. `'sso_assertion'`, `'agent_token'`) without an
+ * upstream release. `RoleSpec.required_credential_types` references
+ * entries from this registry; v1 keeps the field informative-only
+ * (consumed by `auth/middleware.ts` and the dispatcher). Mirrors the
+ * open-registry pattern used for `RoleName`, `ScopeKindName`,
+ * `GrantPathName`, and `AuditEventTypeName`.
+ *
+ * The Hono-side wire-validated `CredentialType` Zod enum (in
+ * `hono_context.ts`) is the closed-set narrow type middleware sets on
+ * the context; the constants below are the source of truth for those
+ * three string values. Future builtin credential types added here
+ * propagate to the wire enum by editing the import list.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Letter (lowercase a-z) start and end (or single letter), with letters
+ * and underscores in between. Mirrors `RoleName`, `ScopeKindName`,
+ * `GrantPathName`. Rejects empty strings, leading or trailing
+ * underscores, uppercase, and digits.
+ */
+export const CREDENTIAL_TYPE_NAME_REGEX = /^[a-z][a-z_]*[a-z]$|^[a-z]$/;
+/** Zod schema for valid credential-type name strings. */
+export const CredentialTypeName = z
+    .string()
+    .regex(CREDENTIAL_TYPE_NAME_REGEX, 'Credential-type names must be lowercase letters and underscores (a-z_), no leading/trailing underscore');
+// Builtin credential types — provided by fuz_app, always available.
+/** Cookie-based session credential. */
+export const CREDENTIAL_TYPE_SESSION = 'session';
+/**
+ * HTTP `Authorization: Bearer` API token credential. The wire literal
+ * `'api_token'` aligns with the `api_token` storage table name; the
+ * constant is named `_API_TOKEN` (not `_BEARER`) to keep wire and
+ * storage nomenclature in lockstep.
+ */
+export const CREDENTIAL_TYPE_API_TOKEN = 'api_token';
+/** Daemon-token credential — filesystem proof for the keeper account. */
+export const CREDENTIAL_TYPE_DAEMON_TOKEN = 'daemon_token';
+/** The builtin credential-type names as a const tuple. */
+export const BUILTIN_CREDENTIAL_TYPES = [
+    CREDENTIAL_TYPE_SESSION,
+    CREDENTIAL_TYPE_API_TOKEN,
+    CREDENTIAL_TYPE_DAEMON_TOKEN,
+];
+/** Zod enum for builtin credential types only. */
+export const BuiltinCredentialType = z.enum(BUILTIN_CREDENTIAL_TYPES);
+/**
+ * Builtin credential-type metadata. Not overridable by consumers.
+ *
+ * Typed `ReadonlyMap` for the contract — but JS Maps don't honor
+ * `Object.freeze` for `.set` / `.delete` / `.clear` (they mutate
+ * internal slots, not own properties), so freeze adds no runtime guard
+ * here. Read once at startup by `create_credential_type_schema`;
+ * runtime mutation has no effect on already-built schemas.
+ */
+export const BUILTIN_CREDENTIAL_TYPE_META = new Map([
+    [
+        CREDENTIAL_TYPE_SESSION,
+        { description: 'Cookie-based session credential, signed and validated server-side.' },
+    ],
+    [
+        CREDENTIAL_TYPE_API_TOKEN,
+        { description: 'HTTP Authorization: Bearer API token credential, hashed at rest.' },
+    ],
+    [
+        CREDENTIAL_TYPE_DAEMON_TOKEN,
+        { description: 'Filesystem-proof daemon-token credential, scoped to the keeper account.' },
+    ],
+]);
+/**
+ * Create a credential-type schema from the builtin set plus optional
+ * consumer-declared additions.
+ *
+ * Builtins (`session`, `api_token`, `daemon_token`) are always present;
+ * consumer entries that collide with a builtin name throw at
+ * construction. Pass the result into `create_role_schema`'s optional
+ * `credential_types` parameter so each role's
+ * `required_credential_types` entries are validated against this set
+ * at construction time.
+ *
+ * @param consumer_types - optional consumer-declared credential-type set with optional metadata
+ * @returns `{CredentialType, credential_types}` — Zod schema and metadata map
+ *
+ * @throws Error if any `consumer_types` key fails the `CredentialTypeName` regex, collides with a builtin name, or appears more than once
+ *
+ * @example
+ * ```ts
+ * // simple — builtins only
+ * const {CredentialType, credential_types} = create_credential_type_schema();
+ *
+ * // with consumer extensions
+ * const {CredentialType} = create_credential_type_schema({
+ *   sso_assertion: {description: 'OIDC SSO assertion bound to an IdP-asserted account.'},
+ * });
+ * ```
+ */
+export const create_credential_type_schema = (consumer_types = {}) => {
+    const consumer_names = Object.keys(consumer_types);
+    const seen = new Set();
+    for (const name of consumer_names) {
+        const parsed = CredentialTypeName.safeParse(name);
+        if (!parsed.success) {
+            throw new Error(`Invalid credential-type name "${name}": ${parsed.error.issues[0].message}`);
+        }
+        if (BUILTIN_CREDENTIAL_TYPE_META.has(name)) {
+            throw new Error(`Consumer credential-type "${name}" collides with builtin credential-type`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`Duplicate credential-type name "${name}"`);
+        }
+        seen.add(name);
+    }
+    const all_names = [...BUILTIN_CREDENTIAL_TYPES, ...consumer_names];
+    const CredentialType = z.enum(all_names);
+    const credential_types = new Map(BUILTIN_CREDENTIAL_TYPE_META);
+    for (const name of consumer_names) {
+        credential_types.set(name, consumer_types[name]);
+    }
+    return { CredentialType, credential_types };
+};

package/dist/auth/daemon_token_middleware.d.ts

@@ -42,7 +42,7 @@ export declare const get_daemon_token_path: (runtime: Pick<EnvDeps, "env_get">,
 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.
+ * keeper role_grant.
  *
  * There is exactly one keeper account (the bootstrap account). Runs once
  * at server startup — the result is cached in

package/dist/auth/daemon_token_middleware.js

@@ -14,7 +14,7 @@ import { write_file_atomic } from '../runtime/fs.js';
 import { get_app_dir } from '../cli/config.js';
 import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
 import { ERROR_INVALID_DAEMON_TOKEN, ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED, } from '../http/error_schemas.js';
-import { query_permit_find_account_id_for_role } from './permit_queries.js';
+import { query_role_grant_find_account_id_for_role } from './role_grant_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). */
@@ -48,7 +48,7 @@ export const write_daemon_token = async (runtime, token_path, token) => {
 };
 /**
  * Resolve the keeper account ID by querying for the account with an active
- * keeper permit.
+ * keeper role_grant.
  *
  * There is exactly one keeper account (the bootstrap account). Runs once
  * at server startup — the result is cached in
@@ -62,7 +62,7 @@ export const write_daemon_token = async (runtime, token_path, token) => {
  * @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);
+    return query_role_grant_find_account_id_for_role(deps, ROLE_KEEPER);
 };
 /**
  * Start daemon token rotation.

package/dist/auth/ddl.d.ts

@@ -9,8 +9,8 @@
 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 ROLE_GRANT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS role_grant (\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 ROLE_GRANT_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)";

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

@@ -1 +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"}
+{"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,iBAAiB,2ZAU5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,UAI9B,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

@@ -29,8 +29,8 @@ CREATE TABLE IF NOT EXISTS actor (
 )`;
 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 (
+export const ROLE_GRANT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS role_grant (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,
   role TEXT NOT NULL,
@@ -40,10 +40,10 @@ CREATE TABLE IF NOT EXISTS permit (
   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 ROLE_GRANT_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_role_grant_actor ON role_grant(actor_id)`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS role_grant_actor_role_active_unique
+    ON role_grant (actor_id, role) WHERE revoked_at IS NULL`,
 ];
 export const AUTH_SESSION_SCHEMA = `
 CREATE TABLE IF NOT EXISTS auth_session (

package/dist/auth/deps.d.ts

@@ -12,7 +12,7 @@ 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 { AuditLogConfig, AuditLogEvent } from './audit_log_schema.js';
+import type { AuditEmitter } from './audit_emitter.js';
 /**
  * Stateless capabilities bundle for fuz_app backends.
  *
@@ -35,24 +35,13 @@ export interface AppDeps {
     /** 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.
+     * Bound audit emitter. Closes over the pool, the `on_audit_event`
+     * subscriber chain, and the optional `AuditLogConfig`. Built once at
+     * backend assembly via `create_audit_emitter` so handlers can never
+     * accidentally write audits against the request transaction — there
+     * is no pool slot on the handler context.
      */
-    on_audit_event: (event: AuditLogEvent) => void;
-    /**
-     * Audit-log config for `audit_log_fire_and_forget` and `query_audit_log`.
-     * Built once at startup via `create_audit_log_config({extra_events})` to
-     * register consumer event types. Optional — defaults to
-     * `BUILTIN_AUDIT_LOG_CONFIG` when absent.
-     *
-     * Threaded through `AppDeps` (instead of a per-call positional arg) so
-     * consumer handlers cannot silently fall back to the builtin config by
-     * forgetting to pass theirs — the deps bundle carries it everywhere
-     * fuz_app emits an audit event.
-     */
-    audit_log_config?: AuditLogConfig;
+    audit: AuditEmitter;
 }
 /**
  * Capabilities for route spec factories.
@@ -61,18 +50,4 @@ export interface AppDeps {
  * via `RouteContext`, so factories don't capture a pool-level `Db`.
  */
 export type RouteFactoryDeps = Omit<AppDeps, 'db'>;
-/**
- * Capabilities required by anything that emits audit events.
- *
- * The slice every audit-emitting site needs: `log` for sibling failure
- * reporting, `on_audit_event` for SSE/WS fan-out, and the optional
- * `audit_log_config` for consumer-extended event-type validation. Used
- * by `audit_log_fire_and_forget` / `emit_permit_target_event` (the
- * primitives) and by every action-factory deps type in `auth/`
- * (`AdminActionDeps`, `AccountActionDeps`, `PermitOfferActionDeps`,
- * `SelfServiceRoleActionDeps`) that runs through them. Lifted here so
- * the five factory deps stop spelling the same `Pick<RouteFactoryDeps,
- * 'log' | 'on_audit_event' | 'audit_log_config'>` independently.
- */
-export type AuditEmitDeps = Pick<AppDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
 //# sourceMappingURL=deps.d.ts.map

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

@@ -1 +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,cAAc,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzE;;;;;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,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,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;IAC/C;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC"}
+{"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,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;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,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,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;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC"}

package/dist/auth/grant_path_schema.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Grant-path registry — the surfaces through which a role can be
+ * granted to an actor.
+ *
+ * Four builtins:
+ *
+ * - `admin` — granted by an admin via `role_grant_offer_create` (subject to
+ *   the consumer's `authorize` callback) or admin-side direct grant.
+ * - `self_service` — toggled by the holder themselves via
+ *   `self_service_role_set` (allowlisted by `eligible_roles`).
+ * - `system` — granted by system code paths (signup, automation, etc.)
+ *   that don't fit either of the above.
+ * - `bootstrap` — granted exactly once during the bootstrap flow
+ *   (`keeper`, `admin` on a fresh install).
+ *
+ * Open registry on top so consumers can declare additional paths
+ * (e.g. `'invite_only'`, `'sso_assertion'`) without an upstream release.
+ * `RoleSpec.grant_paths` references entries from this registry; the
+ * default for `admin_actions.grantable_roles` is `grant_paths.includes('admin')`,
+ * the default for `self_service_role_actions` eligibility is
+ * `grant_paths.includes('self_service')`. Mirrors the open-registry
+ * pattern used for `RoleName`, `ScopeKindName`, `CredentialTypeName`,
+ * and `AuditEventTypeName`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Letter (lowercase a-z) start and end (or single letter), with letters
+ * and underscores in between. Mirrors `RoleName`, `ScopeKindName`,
+ * `CredentialTypeName`. Rejects empty strings, leading or trailing
+ * underscores, uppercase, and digits.
+ */
+export declare const GRANT_PATH_NAME_REGEX: RegExp;
+/** Zod schema for valid grant-path name strings. */
+export declare const GrantPathName: z.ZodString;
+export type GrantPathName = z.infer<typeof GrantPathName>;
+/** Admin-mediated grant — `role_grant_offer_create` plus admin-direct flows. */
+export declare const GRANT_PATH_ADMIN = "admin";
+/** Self-service grant — caller toggles their own role_grant via `self_service_role_set`. */
+export declare const GRANT_PATH_SELF_SERVICE = "self_service";
+/** System-mediated grant — signup hooks, automation, internal service flows. */
+export declare const GRANT_PATH_SYSTEM = "system";
+/** Bootstrap grant — one-shot flow during the keep's first-run bootstrap. */
+export declare const GRANT_PATH_BOOTSTRAP = "bootstrap";
+/** The builtin grant-path names as a const tuple. */
+export declare const BUILTIN_GRANT_PATHS: readonly ["admin", "self_service", "system", "bootstrap"];
+/** Zod enum for builtin grant paths only. */
+export declare const BuiltinGrantPath: z.ZodEnum<{
+    admin: "admin";
+    self_service: "self_service";
+    system: "system";
+    bootstrap: "bootstrap";
+}>;
+export type BuiltinGrantPath = z.infer<typeof BuiltinGrantPath>;
+/**
+ * Per-grant-path metadata. `description` is admin-UI-facing copy
+ * (mirrors `RoleSpec.description` and `ScopeKindMeta.description`).
+ * Open shape so v2 can extend without a breaking change.
+ */
+export interface GrantPathMeta {
+    description?: string;
+}
+/**
+ * Builtin grant-path metadata. Not overridable by consumers.
+ *
+ * Typed `ReadonlyMap` for the contract — but JS Maps don't honor
+ * `Object.freeze` for `.set` / `.delete` / `.clear` (they mutate
+ * internal slots, not own properties), so freeze adds no runtime guard
+ * here. Read once at startup by `create_grant_path_schema`; runtime
+ * mutation has no effect on already-built schemas.
+ */
+export declare const BUILTIN_GRANT_PATH_META: ReadonlyMap<string, GrantPathMeta>;
+/** The result of `create_grant_path_schema` — a Zod schema and metadata map. */
+export interface GrantPathSchemaResult {
+    /**
+     * Zod schema that validates grant-path name strings against the
+     * registered set (builtins + consumer-declared). Use at I/O
+     * boundaries (admin UIs, codegen) and as the construction-time check
+     * inside `create_role_schema` for every `RoleSpec.grant_paths`
+     * entry.
+     */
+    GrantPath: z.ZodType<string>;
+    /**
+     * Map of every registered grant-path to its metadata. Keyed by
+     * name. Read at startup by admin / codegen surfaces.
+     */
+    grant_paths: ReadonlyMap<string, GrantPathMeta>;
+}
+/**
+ * Create a grant-path schema from the builtin set plus optional
+ * consumer-declared additions.
+ *
+ * Builtins (`admin`, `self_service`, `system`, `bootstrap`) are always
+ * present; consumer entries that collide with a builtin name throw at
+ * construction. Pass the result into `create_role_schema`'s optional
+ * `grant_paths` parameter so each role's `grant_paths` entries are
+ * validated against this set at construction time.
+ *
+ * @param consumer_paths - optional consumer-declared grant-path set with optional metadata
+ * @returns `{GrantPath, grant_paths}` — Zod schema and metadata map
+ *
+ * @throws Error if any `consumer_paths` key fails the `GrantPathName` regex, collides with a builtin name, or appears more than once
+ *
+ * @example
+ * ```ts
+ * // simple — builtins only
+ * const {GrantPath, grant_paths} = create_grant_path_schema();
+ *
+ * // with consumer extensions
+ * const {GrantPath} = create_grant_path_schema({
+ *   invite_only: {description: 'Granted by claiming a consumer-issued invite.'},
+ * });
+ * ```
+ */
+export declare const create_grant_path_schema: (consumer_paths?: Record<string, GrantPathMeta>) => GrantPathSchemaResult;
+//# sourceMappingURL=grant_path_schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grant_path_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/grant_path_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAgC,CAAC;AAEnE,oDAAoD;AACpD,eAAO,MAAM,aAAa,aAKxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAI1D,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,2DAKtB,CAAC;AAEX,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB;;;;;EAA8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAuBrE,CAAC;AAEH,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACrC;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,wBAAwB,GACpC,iBAAgB,MAAM,CAAC,MAAM,EAAE,aAAa,CAAM,KAChD,qBA2BF,CAAC"}