@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/auth/admin_actions.js

@@ -5,59 +5,62 @@
  *
  * - Account management: `admin_account_list`, `admin_session_list`,
  *   `admin_session_revoke_all`, `admin_token_revoke_all`.
- * - Audit log reads: `audit_log_list`, `audit_log_permit_history`.
+ * - Audit log reads: `audit_log_list`, `audit_log_role_grant_history`.
  * - Invite CRUD: `invite_create`, `invite_list`, `invite_delete`.
  * - App settings: `app_settings_get`, `app_settings_update` (registered only
  *   when `AdminActionOptions.app_settings` is provided — the mutable ref is
  *   owned by the server context and shared with signup middleware).
  *
  * The action specs themselves live in `auth/admin_action_specs.ts`. Mutations
- * emit matching audit events via `audit_log_fire_and_forget`.
+ * emit matching audit events via `deps.audit.emit`.
  *
  * Authorization is declared at the spec level (`auth: {role: 'admin'}`) so
  * the RPC dispatcher enforces it before the handler runs and the generated
- * surface accurately reports the requirement. `permit_revoke` in
- * `auth/permit_offer_actions.ts` uses the same spec-level pattern even though its
+ * surface accurately reports the requirement. `role_grant_revoke` in
+ * `auth/role_grant_offer_actions.ts` uses the same spec-level pattern even though its
  * sibling methods are authenticated-but-not-admin — the dispatcher checks
  * auth per-spec, so mixed-auth endpoints compose cleanly. Handler-level
  * gates are reserved for input-dependent elevation (e.g.
- * `permit_offer_list`/`_history` elevate to admin only when the caller
+ * `role_grant_offer_list`/`_history` elevate to admin only when the caller
  * passes an `account_id` other than their own — an input-dependent check
  * the spec can't express).
  *
  * @module
  */
-import { rpc_actor_action } from '../actions/action_rpc.js';
+import { rpc_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { BUILTIN_ROLE_OPTIONS } from './role_schema.js';
+import { BUILTIN_ROLE_SPECS_BY_NAME, list_roles_with_grant_path, } from './role_schema.js';
+import { GRANT_PATH_ADMIN } from './grant_path_schema.js';
 import { query_account_by_email, query_account_by_id, query_account_by_username, query_admin_account_list, } from './account_queries.js';
 import { query_session_list_all_active, query_session_revoke_all_for_account, } from './session_queries.js';
 import { query_revoke_all_api_tokens_for_account } from './api_token_queries.js';
-import { audit_log_fire_and_forget, query_audit_log_list_permit_history, query_audit_log_list_with_usernames, } from './audit_log_queries.js';
+import { query_audit_log_list_role_grant_history, query_audit_log_list_with_usernames, } from './audit_log_queries.js';
 import { AUDIT_LOG_DEFAULT_LIMIT } from './audit_log_schema.js';
 import { query_create_invite, query_invite_delete_unclaimed, query_invite_list_all_with_usernames, } from './invite_queries.js';
 import {} from './app_settings_schema.js';
 import { query_app_settings_load_with_username, query_app_settings_update, } from './app_settings_queries.js';
 import { is_pg_unique_violation } from '../db/pg_error.js';
 import { ERROR_ACCOUNT_NOT_FOUND, ERROR_INVITE_ACCOUNT_EXISTS_EMAIL, ERROR_INVITE_ACCOUNT_EXISTS_USERNAME, ERROR_INVITE_DUPLICATE, ERROR_INVITE_MISSING_IDENTIFIER, ERROR_INVITE_NOT_FOUND, } from '../http/error_schemas.js';
-import { admin_account_list_action_spec, admin_session_list_action_spec, admin_session_revoke_all_action_spec, admin_token_revoke_all_action_spec, audit_log_list_action_spec, audit_log_permit_history_action_spec, invite_create_action_spec, invite_list_action_spec, invite_delete_action_spec, app_settings_get_action_spec, app_settings_update_action_spec, } from './admin_action_specs.js';
+import { admin_account_list_action_spec, admin_session_list_action_spec, admin_session_revoke_all_action_spec, admin_token_revoke_all_action_spec, audit_log_list_action_spec, audit_log_role_grant_history_action_spec, invite_create_action_spec, invite_list_action_spec, invite_delete_action_spec, app_settings_get_action_spec, app_settings_update_action_spec, } from './admin_action_specs.js';
 /**
  * Create the admin-only RPC actions.
  *
- * @param deps - `AdminActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
+ * @param deps - `RouteFactoryDeps` (`log`, `audit`, …). `log` drives RPC-
+ *   internal error logging; `audit.emit` writes audit rows via the captured
+ *   pool. The bound emitter encapsulates `on_audit_event` fan-out and the
+ *   optional `AuditLogConfig`.
  * @param options - role schema for `grantable_roles` derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
  * @mutates `options.app_settings` ref - `app_settings_update` writes `open_signup`, `updated_at`, and `updated_by` so signup middleware reads without a DB round trip
  */
 export const create_admin_actions = (deps, options = {}) => {
-    const role_options = options.roles?.role_options ?? BUILTIN_ROLE_OPTIONS;
-    const grantable_roles = [];
-    for (const [name, rc] of role_options) {
-        if (rc.web_grantable)
-            grantable_roles.push(name);
-    }
-    const account_list_handler = async (_input, ctx) => {
-        const accounts = await query_admin_account_list(ctx);
+    const role_specs = options.roles?.role_specs ?? BUILTIN_ROLE_SPECS_BY_NAME;
+    const grantable_roles = list_roles_with_grant_path(role_specs, GRANT_PATH_ADMIN);
+    const account_list_handler = async (input, ctx) => {
+        const accounts = await query_admin_account_list(ctx, {
+            limit: input.limit,
+            offset: input.offset,
+        });
         return { accounts, grantable_roles };
     };
     const session_list_handler = async (_input, ctx) => {
@@ -68,7 +71,7 @@ export const create_admin_actions = (deps, options = {}) => {
         const auth = ctx.auth;
         const account = await query_account_by_id(ctx, input.account_id);
         if (!account) {
-            void audit_log_fire_and_forget(ctx, {
+            deps.audit.emit(ctx, {
                 event_type: 'session_revoke_all',
                 outcome: 'failure',
                 account_id: auth.account.id,
@@ -81,24 +84,24 @@ export const create_admin_actions = (deps, options = {}) => {
                     reason: ERROR_ACCOUNT_NOT_FOUND,
                     attempted_account_id: input.account_id,
                 },
-            }, deps);
+            });
             throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
         }
         const count = await query_session_revoke_all_for_account(ctx, input.account_id);
-        void audit_log_fire_and_forget(ctx, {
+        deps.audit.emit(ctx, {
             event_type: 'session_revoke_all',
             account_id: auth.account.id,
             target_account_id: input.account_id,
             ip: ctx.client_ip,
             metadata: { count },
-        }, deps);
+        });
         return { ok: true, count };
     };
     const token_revoke_all_handler = async (input, ctx) => {
         const auth = ctx.auth;
         const account = await query_account_by_id(ctx, input.account_id);
         if (!account) {
-            void audit_log_fire_and_forget(ctx, {
+            deps.audit.emit(ctx, {
                 event_type: 'token_revoke_all',
                 outcome: 'failure',
                 account_id: auth.account.id,
@@ -110,17 +113,17 @@ export const create_admin_actions = (deps, options = {}) => {
                     reason: ERROR_ACCOUNT_NOT_FOUND,
                     attempted_account_id: input.account_id,
                 },
-            }, deps);
+            });
             throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
         }
         const count = await query_revoke_all_api_tokens_for_account(ctx, input.account_id);
-        void audit_log_fire_and_forget(ctx, {
+        deps.audit.emit(ctx, {
             event_type: 'token_revoke_all',
             account_id: auth.account.id,
             target_account_id: input.account_id,
             ip: ctx.client_ip,
             metadata: { count },
-        }, deps);
+        });
         return { ok: true, count };
     };
     const audit_log_list_handler = async (input, ctx) => {
@@ -134,8 +137,8 @@ export const create_admin_actions = (deps, options = {}) => {
         });
         return { events };
     };
-    const audit_log_permit_history_handler = async (input, ctx) => {
-        const events = await query_audit_log_list_permit_history(ctx, input.limit ?? AUDIT_LOG_DEFAULT_LIMIT, input.offset ?? 0);
+    const audit_log_role_grant_history_handler = async (input, ctx) => {
+        const events = await query_audit_log_list_role_grant_history(ctx, input.limit ?? AUDIT_LOG_DEFAULT_LIMIT, input.offset ?? 0);
         return { events };
     };
     const invite_create_handler = async (input, ctx) => {
@@ -179,12 +182,12 @@ export const create_admin_actions = (deps, options = {}) => {
             }
             throw err;
         }
-        void audit_log_fire_and_forget(ctx, {
+        deps.audit.emit(ctx, {
             event_type: 'invite_create',
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { invite_id: invite.id, email, username },
-        }, deps);
+        });
         return { ok: true, invite };
     };
     const invite_list_handler = async (_input, ctx) => {
@@ -197,24 +200,24 @@ export const create_admin_actions = (deps, options = {}) => {
         if (!deleted) {
             throw jsonrpc_errors.not_found('invite', { reason: ERROR_INVITE_NOT_FOUND });
         }
-        void audit_log_fire_and_forget(ctx, {
+        deps.audit.emit(ctx, {
             event_type: 'invite_delete',
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { invite_id: input.invite_id },
-        }, deps);
+        });
         return { ok: true };
     };
     const actions = [
-        rpc_actor_action(admin_account_list_action_spec, account_list_handler),
-        rpc_actor_action(admin_session_list_action_spec, session_list_handler),
-        rpc_actor_action(admin_session_revoke_all_action_spec, session_revoke_all_handler),
-        rpc_actor_action(admin_token_revoke_all_action_spec, token_revoke_all_handler),
-        rpc_actor_action(audit_log_list_action_spec, audit_log_list_handler),
-        rpc_actor_action(audit_log_permit_history_action_spec, audit_log_permit_history_handler),
-        rpc_actor_action(invite_create_action_spec, invite_create_handler),
-        rpc_actor_action(invite_list_action_spec, invite_list_handler),
-        rpc_actor_action(invite_delete_action_spec, invite_delete_handler),
+        rpc_action(admin_account_list_action_spec, account_list_handler),
+        rpc_action(admin_session_list_action_spec, session_list_handler),
+        rpc_action(admin_session_revoke_all_action_spec, session_revoke_all_handler),
+        rpc_action(admin_token_revoke_all_action_spec, token_revoke_all_handler),
+        rpc_action(audit_log_list_action_spec, audit_log_list_handler),
+        rpc_action(audit_log_role_grant_history_action_spec, audit_log_role_grant_history_handler),
+        rpc_action(invite_create_action_spec, invite_create_handler),
+        rpc_action(invite_list_action_spec, invite_list_handler),
+        rpc_action(invite_delete_action_spec, invite_delete_handler),
     ];
     const { app_settings } = options;
     if (app_settings) {
@@ -231,7 +234,7 @@ export const create_admin_actions = (deps, options = {}) => {
             app_settings.open_signup = updated.open_signup;
             app_settings.updated_at = updated.updated_at;
             app_settings.updated_by = updated.updated_by;
-            void audit_log_fire_and_forget(ctx, {
+            deps.audit.emit(ctx, {
                 event_type: 'app_settings_update',
                 account_id: auth.account.id,
                 ip: ctx.client_ip,
@@ -240,11 +243,11 @@ export const create_admin_actions = (deps, options = {}) => {
                     old_value,
                     new_value: input.open_signup,
                 },
-            }, deps);
+            });
             const settings = await query_app_settings_load_with_username(ctx);
             return { ok: true, settings };
         };
-        actions.push(rpc_actor_action(app_settings_get_action_spec, app_settings_get_handler), rpc_actor_action(app_settings_update_action_spec, app_settings_update_handler));
+        actions.push(rpc_action(app_settings_get_action_spec, app_settings_get_handler), rpc_action(app_settings_update_action_spec, app_settings_update_handler));
     }
     return actions;
 };

package/dist/auth/audit_emitter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Bound audit-emit capability.
+ *
+ * `AuditEmitter` closes over the pool-level `Db`, the `on_audit_event`
+ * subscriber chain, and the optional `AuditLogConfig` at backend-assembly
+ * time. Consumers reach for `deps.audit.emit(ctx, input)` and never see the
+ * pool — handlers cannot accidentally emit an audit event against the
+ * request's transactional `db` (which would be rolled back with the parent
+ * on a handler throw).
+ *
+ * Four methods cover every fan-out shape the auth domain needs:
+ *
+ * - `emit(ctx, input)` — fire-and-forget pool write. Pushes the in-flight
+ *   promise onto `ctx.pending_effects` for post-response flushing. Errors are
+ *   logged, never thrown. Returns `void` so callers don't pile up `void`
+ *   keywords or accidentally `await` something whose handle is already in
+ *   `pending_effects`.
+ * - `emit_role_grant_target(ctx, auth, input)` — wrapper that lifts the
+ *   `actor_id` / `account_id` / `ip` boilerplate every role-grant-shape audit
+ *   site repeated. Delegates to `emit`.
+ * - `emit_pool(input)` — awaitable pool write for code paths without a
+ *   `pending_effects` queue (cleanup sweeps, ad-hoc maintenance scripts).
+ *   Same write-then-notify semantics as `emit`, just synchronous-with-await.
+ * - `notify(event)` — fan out an already-written audit row (e.g. rows
+ *   returned by `query_accept_offer` that were inserted in-transaction by
+ *   the query layer). Runs every listener on the chain; per-listener throws
+ *   are isolated.
+ *
+ * The chain is mutable so server assembly can append additional listeners
+ * (e.g. the audit-log SSE registry composed by `create_app_server`) after
+ * the backend is built but before the first request runs.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { Db } from '../db/db.js';
+import type { RequestActorContext } from './request_context.js';
+import { type AuditLogConfig, type AuditLogEvent, type AuditLogInput } from './audit_log_schema.js';
+/**
+ * Per-request context required by `AuditEmitter.emit` — just the eager
+ * `pending_effects` queue. The bound emitter carries its own `log`
+ * reference inside the closure, so per-call contexts don't need one.
+ *
+ * Audit emits are eager-only by design: the bound emitter fires the
+ * pool write immediately and pushes the in-flight `Promise<void>` here.
+ * They never go through `emit_after_commit` — pool-routed audit writes
+ * are already rollback-resilient because they run outside the request
+ * transaction, so the post-commit timing the deferred queue provides
+ * would only delay forensic visibility without any safety benefit.
+ *
+ * Both `RouteContext` and `ActionContext` structurally satisfy this
+ * shape (they each carry `pending_effects`), so handlers pass `route`
+ * / `ctx` directly.
+ */
+export interface AuditEmitterContext {
+    pending_effects: Array<Promise<void>>;
+}
+/**
+ * Context required by `AuditEmitter.emit_role_grant_target` — adds
+ * `client_ip` so the helper can lift the `ip: ctx.client_ip`
+ * boilerplate every role-grant-shape emit site repeated.
+ */
+export interface AuditEmitRoleGrantContext extends AuditEmitterContext {
+    /** Resolved client IP from the trusted-proxy middleware — `'unknown'` if not resolved. */
+    client_ip: string;
+}
+/**
+ * Bound audit-emit capability. Built once at backend assembly via
+ * `create_audit_emitter`; lives on `AppDeps.audit` so factories never see
+ * the pool.
+ */
+export interface AuditEmitter {
+    /**
+     * Fire-and-forget audit write via the captured pool.
+     *
+     * The in-flight promise is pushed onto `ctx.pending_effects` so tests
+     * with `await_pending_effects: true` can assert side effects inline.
+     * Errors are logged, never thrown. Successful writes fan out to every
+     * listener on the chain (`notify`).
+     *
+     * Returns `void` deliberately — the in-flight promise is already on
+     * `ctx.pending_effects`, and exposing it would tempt callers to `await`
+     * (sequencing audit writes onto the response hot path) or sprinkle
+     * `void` to placate `no-floating-promises`. For awaitable writes from
+     * code paths without `pending_effects`, use `emit_pool`.
+     *
+     * @mutates `audit_log` table - inserts the row via the captured pool
+     * @mutates `ctx.pending_effects` - appends the in-flight settled promise
+     */
+    emit<T extends string>(ctx: AuditEmitterContext, input: AuditLogInput<T>): void;
+    /**
+     * Emit a role-grant-shape audit event with `actor_id` / `account_id` /
+     * `ip` lifted from `auth` + `ctx`. Delegates to `emit`.
+     *
+     * Use for any event populating one of the `target_*_id` columns.
+     * Reach for the lower-level `emit` only when the event is non-role-grant
+     * shape (e.g. `app_settings_update`, bootstrap, signup).
+     */
+    emit_role_grant_target<T extends string>(ctx: AuditEmitRoleGrantContext, auth: RequestActorContext, input: {
+        event_type: T;
+        target_account_id: Uuid | null;
+        target_actor_id: Uuid | null;
+        metadata: AuditLogInput<T>['metadata'];
+        outcome?: 'success' | 'failure';
+    }): void;
+    /**
+     * Awaitable pool write for code paths without a `pending_effects` queue.
+     *
+     * Same write-then-notify semantics as `emit`. Errors are logged and
+     * swallowed (resolved void), so callers can sequence sweeps with
+     * `await audit.emit_pool(...)` without try/catch boilerplate. The
+     * primary user is `auth/cleanup.ts` — sweeps have no per-request
+     * `pending_effects` to attach to.
+     *
+     * @mutates `audit_log` table - inserts the row via the captured pool
+     */
+    emit_pool<T extends string>(input: AuditLogInput<T>): Promise<void>;
+    /**
+     * Fan out an already-written audit row to the listener chain.
+     *
+     * Use only when the row was inserted in-transaction by a query helper
+     * that returned the `AuditLogEvent` (e.g. `query_accept_offer.audit_events`).
+     * Per-listener exceptions are caught and logged; one failing listener
+     * does not starve siblings.
+     */
+    notify(event: AuditLogEvent): void;
+    /**
+     * Mutable subscriber chain. Append at server assembly to compose the
+     * factory-managed audit-log SSE on top of the consumer's
+     * `on_audit_event` callback without shallow-copying `AppDeps`.
+     */
+    readonly on_event_chain: Array<(event: AuditLogEvent) => void>;
+}
+/** Options for `create_audit_emitter`. */
+export interface CreateAuditEmitterOptions {
+    /** Pool-level `Db`. Captured by every emit call. */
+    db: Db;
+    /** Logger for write + listener-callback failures. */
+    log: Logger;
+    /**
+     * Initial subscriber appended to `on_event_chain`. Omit for backends
+     * that compose listeners post-assembly (e.g. via `audit_log_sse`).
+     */
+    on_audit_event?: ((event: AuditLogEvent) => void) | null;
+    /**
+     * Audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`. Consumer-
+     * extended configs from `create_audit_log_config({extra_events})` get
+     * registered here once at backend assembly.
+     */
+    audit_log_config?: AuditLogConfig;
+}
+/**
+ * Build a bound `AuditEmitter`. Called once at `create_app_backend` time.
+ *
+ * @param options - pool, logger, optional initial subscriber, optional config
+ * @returns the bound emitter; closes over the pool + config + listener chain
+ */
+export declare const create_audit_emitter: (options: CreateAuditEmitterOptions) => AuditEmitter;
+//# sourceMappingURL=audit_emitter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IACnC,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACrE,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChF;;;;;;;OAOG;IACH,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACtC,GAAG,EAAE,yBAAyB,EAC9B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE;QACN,UAAU,EAAE,CAAC,CAAC;QACd,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;QAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACvC,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;KAChC,GACC,IAAI,CAAC;IACR;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,CAAC;CAC/D;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,oDAAoD;IACpD,EAAE,EAAE,EAAE,CAAC;IACP,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YAoDzE,CAAC"}

package/dist/auth/audit_emitter.js

@@ -0,0 +1,83 @@
+/**
+ * Bound audit-emit capability.
+ *
+ * `AuditEmitter` closes over the pool-level `Db`, the `on_audit_event`
+ * subscriber chain, and the optional `AuditLogConfig` at backend-assembly
+ * time. Consumers reach for `deps.audit.emit(ctx, input)` and never see the
+ * pool — handlers cannot accidentally emit an audit event against the
+ * request's transactional `db` (which would be rolled back with the parent
+ * on a handler throw).
+ *
+ * Four methods cover every fan-out shape the auth domain needs:
+ *
+ * - `emit(ctx, input)` — fire-and-forget pool write. Pushes the in-flight
+ *   promise onto `ctx.pending_effects` for post-response flushing. Errors are
+ *   logged, never thrown. Returns `void` so callers don't pile up `void`
+ *   keywords or accidentally `await` something whose handle is already in
+ *   `pending_effects`.
+ * - `emit_role_grant_target(ctx, auth, input)` — wrapper that lifts the
+ *   `actor_id` / `account_id` / `ip` boilerplate every role-grant-shape audit
+ *   site repeated. Delegates to `emit`.
+ * - `emit_pool(input)` — awaitable pool write for code paths without a
+ *   `pending_effects` queue (cleanup sweeps, ad-hoc maintenance scripts).
+ *   Same write-then-notify semantics as `emit`, just synchronous-with-await.
+ * - `notify(event)` — fan out an already-written audit row (e.g. rows
+ *   returned by `query_accept_offer` that were inserted in-transaction by
+ *   the query layer). Runs every listener on the chain; per-listener throws
+ *   are isolated.
+ *
+ * The chain is mutable so server assembly can append additional listeners
+ * (e.g. the audit-log SSE registry composed by `create_app_server`) after
+ * the backend is built but before the first request runs.
+ *
+ * @module
+ */
+import { query_audit_log } from './audit_log_queries.js';
+import { BUILTIN_AUDIT_LOG_CONFIG, } from './audit_log_schema.js';
+/**
+ * Build a bound `AuditEmitter`. Called once at `create_app_backend` time.
+ *
+ * @param options - pool, logger, optional initial subscriber, optional config
+ * @returns the bound emitter; closes over the pool + config + listener chain
+ */
+export const create_audit_emitter = (options) => {
+    const { db, log, audit_log_config = BUILTIN_AUDIT_LOG_CONFIG } = options;
+    const on_event_chain = [];
+    if (options.on_audit_event)
+        on_event_chain.push(options.on_audit_event);
+    const notify = (event) => {
+        for (const listener of on_event_chain) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log.error('Audit log listener failed:', err);
+            }
+        }
+    };
+    const emit_pool = async (input) => {
+        try {
+            const event = await query_audit_log({ db }, input, audit_log_config);
+            notify(event);
+        }
+        catch (err) {
+            log.error('Audit log write failed:', err);
+        }
+    };
+    const emit = (ctx, input) => {
+        ctx.pending_effects.push(emit_pool(input));
+    };
+    const emit_role_grant_target = (ctx, auth, input) => {
+        emit(ctx, {
+            event_type: input.event_type,
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            outcome: input.outcome,
+            target_account_id: input.target_account_id,
+            target_actor_id: input.target_actor_id,
+            ip: ctx.client_ip,
+            metadata: input.metadata,
+        });
+    };
+    return { emit, emit_role_grant_target, emit_pool, notify, on_event_chain };
+};

package/dist/auth/audit_log_queries.d.ts

@@ -1,22 +1,18 @@
 /**
  * Audit log database queries.
  *
- * Records and retrieves auth mutation events for security monitoring.
- * All write operations should use `audit_log_fire_and_forget` to
- * ensure audit logging never blocks or breaks auth flows.
- *
- * Rollback resilience: `audit_log_fire_and_forget` writes to `background_db`
- * (pool-level), not the handler's transaction-scoped `db`, so audit entries
- * persist even when the request transaction rolls back.
+ * Records and retrieves auth mutation events for security monitoring. The
+ * canonical fire-and-forget entry point is `AppDeps.audit.emit(ctx, input)`
+ * (see `auth/audit_emitter.ts`) — it closes over the pool so audit rows
+ * persist even when the request transaction rolls back. This module only
+ * exposes the in-transaction `query_*` primitives and the drift counters;
+ * the bound emitter writes through `query_audit_log` against its captured
+ * pool.
  *
  * @module
  */
 import type { QueryDeps } from '../db/query_deps.js';
-import type { RouteContext } from '../http/route_spec.js';
-import type { Uuid } from '@fuzdev/fuz_util/id.js';
-import type { AuditEmitDeps } from './deps.js';
-import type { RequestActorContext } from './request_context.js';
-import { type AuditLogConfig, type AuditLogEvent, type AuditLogInput, type AuditLogListOptions, type AuditLogEventWithUsernamesJson, type PermitHistoryEventJson } from './audit_log_schema.js';
+import { type AuditLogConfig, type AuditLogEvent, type AuditLogInput, type AuditLogListOptions, type AuditLogEventWithUsernamesJson, type RoleGrantHistoryEventJson } from './audit_log_schema.js';
 /** Number of audit metadata validation failures observed since process start. */
 export declare const get_audit_metadata_validation_failures: () => number;
 /** Reset the counter — for tests only. */
@@ -34,6 +30,12 @@ export declare const reset_audit_unknown_event_type_failures: () => void;
  * but write the row anyway. Consumers extend the recognized set via
  * `create_audit_log_config({extra_events})`.
  *
+ * In-transaction call site for query helpers that must atomically write the
+ * row alongside other mutations (e.g. `query_accept_offer`). Fire-and-forget
+ * call sites should reach for `AppDeps.audit.emit` instead — that wrapper
+ * closes over the pool so audit rows persist when the parent transaction
+ * rolls back.
+ *
  * @param deps - query dependencies
  * @param input - the audit event to record
  * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
@@ -59,22 +61,14 @@ export declare const query_audit_log_list: (deps: QueryDeps, options?: AuditLogL
  */
 export declare const query_audit_log_list_with_usernames: (deps: QueryDeps, options?: AuditLogListOptions) => Promise<Array<AuditLogEventWithUsernamesJson>>;
 /**
- * List audit log entries related to an account (as actor or target).
- *
- * @param deps - query dependencies
- * @param account_id - the account to query for
- * @param limit - maximum entries to return
- */
-export declare const query_audit_log_list_for_account: (deps: QueryDeps, account_id: string, limit?: number) => Promise<Array<AuditLogEvent>>;
-/**
- * List permit grant/revoke events with resolved usernames.
+ * List role_grant grant/revoke events with resolved usernames.
  *
  * @param deps - query dependencies
  * @param limit - maximum entries to return
  * @param offset - number of entries to skip
- * @returns permit history events with `username` and `target_username`
+ * @returns role_grant history events with `username` and `target_username`
  */
-export declare const query_audit_log_list_permit_history: (deps: QueryDeps, limit?: number, offset?: number) => Promise<Array<PermitHistoryEventJson>>;
+export declare const query_audit_log_list_role_grant_history: (deps: QueryDeps, limit?: number, offset?: number) => Promise<Array<RoleGrantHistoryEventJson>>;
 /**
  * Delete audit log entries older than the given date.
  *
@@ -84,68 +78,4 @@ export declare const query_audit_log_list_permit_history: (deps: QueryDeps, limi
  * @mutates `audit_log` table - deletes every row with `created_at < before`
  */
 export declare const query_audit_log_cleanup_before: (deps: QueryDeps, before: Date) => Promise<number>;
-/**
- * Log an audit event without blocking the caller.
- *
- * Errors are logged — audit logging never breaks auth flows. Uses
- * `background_db` so entries persist even when the request transaction
- * rolls back. Write and `on_audit_event` callback failures are logged separately.
- *
- * `deps` is the shared `AuditEmitDeps` bundle (`log`, `on_audit_event`,
- * optional `audit_log_config`) so call sites pass the surrounding deps
- * object directly. The bundled shape replaces the prior `(log,
- * on_audit_event, config?)` positional args — consumers that forgot the
- * trailing `config` would silently fall back to `BUILTIN_AUDIT_LOG_CONFIG`
- * and skip metadata validation for their own event types.
- *
- * @param route - `background_db` and `pending_effects` from the route context
- * @param input - the audit event to record
- * @param deps - logger, `on_audit_event` callback, and optional `audit_log_config`
- * @returns the settled promise (callers may ignore it)
- * @mutates `audit_log` table - inserts a row via `background_db` (independent of the request transaction)
- * @mutates `route.pending_effects` - pushes the in-flight settled promise for test flushing
- */
-export declare const audit_log_fire_and_forget: <T extends string>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, deps: AuditEmitDeps) => Promise<void>;
-/**
- * Per-request context required by `emit_permit_target_event` —
- * `RouteContext` plus the resolved `client_ip` (lives on `ActionContext`
- * for RPC handlers and on the route's Hono context for REST). Declared
- * locally rather than reaching into `actions/action_rpc.ts` so the helper
- * stays usable from REST handlers that haven't promoted to RPC yet.
- */
-export type EmitPermitTargetEventContext = Pick<RouteContext, 'background_db' | 'pending_effects'> & {
-    client_ip: string;
-};
-/**
- * Stamp a permit-shape audit event with both `target_account_id` (drives
- * SSE/WS socket-close — sessions are account-grain) and `target_actor_id`
- * (the actor-grain forensic field). Both target fields nullable so emit
- * sites without a recipient binding (e.g. `permit_revoke` on a missing
- * account, offer-shape events with no `to_actor_id`) can call through
- * uniformly.
- *
- * Lifts the six-site `{actor_id: auth.actor.id, account_id: auth.account.id,
- * ip: ctx.client_ip, ...}` boilerplate around `audit_log_fire_and_forget`
- * so callers thread auth + ctx + deps once and the event metadata once,
- * without re-derivable plumbing.
- *
- * Outcome defaults to `'success'`; pass `'failure'` for denial-shape
- * events. Other audit envelope shapes (target_*-by-actor-id-only events,
- * non-permit-shape events) should call `audit_log_fire_and_forget`
- * directly — this helper deliberately narrows to the permit-target shape.
- *
- * @param ctx - request context with `background_db`, `pending_effects`, `client_ip`
- * @param auth - the resolved `RequestActorContext` for the current handler — actor invariant captured in the type so the helper stops needing `auth.actor!`
- * @param deps - `log`, `on_audit_event`, optional `audit_log_config`
- * @param input - event type, target columns, metadata, optional outcome
- * @returns the settled promise (callers may ignore it)
- * @mutates `audit_log` table - inserts a row via `background_db`
- */
-export declare const emit_permit_target_event: <T extends string>(ctx: EmitPermitTargetEventContext, auth: RequestActorContext, deps: AuditEmitDeps, input: {
-    event_type: T;
-    target_account_id: Uuid | null;
-    target_actor_id: Uuid | null;
-    metadata: AuditLogInput<T>["metadata"];
-    outcome?: "success" | "failure";
-}) => Promise<void>;
 //# sourceMappingURL=audit_log_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_queries.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit_log_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC9B,MAAM,uBAAuB,CAAC;AAa/B,iFAAiF;AACjF,eAAO,MAAM,sCAAsC,QAAO,MACvB,CAAC;AAEpC,0CAA0C;AAC1C,eAAO,MAAM,wCAAwC,QAAO,IAE3D,CAAC;AAYF,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,QAAO,MACvB,CAAC;AAEnC,0CAA0C;AAC1C,eAAO,MAAM,uCAAuC,QAAO,IAE1D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,SAAS,MAAM,EACrD,MAAM,SAAS,EACf,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,SAAQ,cAAyC,KAC/C,OAAO,CAAC,aAAa,CAoCvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAwC9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CA8C/C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,cAA+B,EAC/B,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAY1C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,CAAC"}