@fuzdev/fuz_app 0.54.0 → 0.56.0

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,20 +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 { AppDeps } from './deps.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. */
@@ -32,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`.
@@ -57,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.
  *
@@ -82,31 +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>;
-/**
- * Capabilities required by `audit_log_fire_and_forget`.
- *
- * Defined as a slice of `AppDeps` so call sites can pass the surrounding deps
- * bundle directly without a structural-compatibility coincidence. 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. `audit_log_config` is optional on `AppDeps` and defaults to
- * `BUILTIN_AUDIT_LOG_CONFIG` inside `audit_log_fire_and_forget` when absent.
- */
-export type AuditLogFireAndForgetDeps = Pick<AppDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
-/**
- * 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.
- *
- * @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: AuditLogFireAndForgetDeps) => 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":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,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;;;;;;;;;;;;;;;GAeG;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,CAmCvB,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;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAA+B,KAC7B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAO9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,cAA+B,EAC/B,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAYvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,OAAO,EACP,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,MAAM,EACzD,OAAO,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,iBAAiB,CAAC,EAC9D,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAed,CAAC"}
+{"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"}

package/dist/auth/audit_log_queries.js

@@ -1,13 +1,13 @@
 /**
  * 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
  */
@@ -53,6 +53,12 @@ export const reset_audit_unknown_event_type_failures = () => {
  * 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`.
@@ -75,14 +81,15 @@ export const query_audit_log = async (deps, input, config = BUILTIN_AUDIT_LOG_CO
             }
         }
     }
-    const rows = await deps.db.query(`INSERT INTO audit_log (event_type, outcome, actor_id, account_id, target_account_id, ip, metadata)
-		 VALUES ($1, $2, $3, $4, $5, $6, $7)
+    const rows = await deps.db.query(`INSERT INTO audit_log (event_type, outcome, actor_id, account_id, target_account_id, target_actor_id, ip, metadata)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
 		 RETURNING *`, [
         input.event_type,
         input.outcome ?? 'success',
         input.actor_id ?? null,
         input.account_id ?? null,
         input.target_account_id ?? null,
+        input.target_actor_id ?? null,
         input.ip ?? null,
         input.metadata ? JSON.stringify(input.metadata) : null,
     ]);
@@ -171,33 +178,21 @@ export const query_audit_log_list_with_usernames = async (deps, options) => {
 		 ${where} ORDER BY al.seq DESC LIMIT $${param_index++} OFFSET $${param_index}`, [...params, limit, offset]);
 };
 /**
- * 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 const query_audit_log_list_for_account = async (deps, account_id, limit = AUDIT_LOG_DEFAULT_LIMIT) => {
-    return deps.db.query(`SELECT * FROM audit_log
-		 WHERE account_id = $1 OR target_account_id = $1
-		 ORDER BY seq DESC LIMIT $2`, [account_id, limit]);
-};
-/**
- * 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 const query_audit_log_list_permit_history = async (deps, limit = AUDIT_LOG_DEFAULT_LIMIT, offset = 0) => {
+export const query_audit_log_list_role_grant_history = async (deps, limit = AUDIT_LOG_DEFAULT_LIMIT, offset = 0) => {
     return deps.db.query(`SELECT al.*,
 			a1.username AS username,
 			a2.username AS target_username
 		 FROM audit_log al
 		 LEFT JOIN account a1 ON a1.id = al.account_id
 		 LEFT JOIN account a2 ON a2.id = al.target_account_id
-		 WHERE al.event_type IN ('permit_grant', 'permit_revoke')
+		 WHERE al.event_type IN ('role_grant_create', 'role_grant_revoke')
 		 ORDER BY al.seq DESC LIMIT $1 OFFSET $2`, [limit, offset]);
 };
 /**
@@ -212,34 +207,3 @@ export const query_audit_log_cleanup_before = async (deps, before) => {
     const rows = await deps.db.query(`DELETE FROM audit_log WHERE created_at < $1 RETURNING id`, [before.toISOString()]);
     return rows.length;
 };
-/**
- * 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.
- *
- * @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 const audit_log_fire_and_forget = (route, input, deps) => {
-    const { log, on_audit_event, audit_log_config = BUILTIN_AUDIT_LOG_CONFIG } = deps;
-    const p = query_audit_log({ db: route.background_db }, input, audit_log_config)
-        .then((event) => {
-        try {
-            on_audit_event(event);
-        }
-        catch (callback_err) {
-            log.error('Audit log on_audit_event callback failed:', callback_err);
-        }
-    })
-        .catch((err) => {
-        log.error('Audit log write failed:', err);
-    });
-    route.pending_effects.push(p);
-    return p;
-};

package/dist/auth/audit_log_routes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Audit log SSE stream route.
  *
- * The two list-reads (`audit_log_list`, `audit_log_permit_history`) moved to
+ * The two list-reads (`audit_log_list`, `audit_log_role_grant_history`) moved to
  * RPC in `auth/admin_actions.ts`, and the admin session listing moved to
  * `admin_session_list` on the same file. What remains here is the optional
  * `GET /audit/stream` SSE route — streams aren't an action-kind, so they

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAsB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAC,MAAM,oBAAoB,CAAC;AAC7F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oCAAoC,CAAC;AAIzE,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;QAC1F,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CAgC5F,CAAC"}
+{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAsB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAC,MAAM,oBAAoB,CAAC;AAC7F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oCAAoC,CAAC;AAQzE,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;QAC1F,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CAiC5F,CAAC"}

package/dist/auth/audit_log_routes.js

@@ -1,7 +1,7 @@
 /**
  * Audit log SSE stream route.
  *
- * The two list-reads (`audit_log_list`, `audit_log_permit_history`) moved to
+ * The two list-reads (`audit_log_list`, `audit_log_role_grant_history`) moved to
  * RPC in `auth/admin_actions.ts`, and the admin session listing moved to
  * `admin_session_list` on the same file. What remains here is the optional
  * `GET /audit/stream` SSE route — streams aren't an action-kind, so they
@@ -15,6 +15,9 @@ import { z } from 'zod';
 import { create_sse_response } from '../realtime/sse.js';
 import { AUTH_SESSION_TOKEN_HASH_KEY, require_request_context } from './request_context.js';
 import { AUDIT_LOG_CHANNEL } from '../realtime/sse_auth_guard.js';
+import { ActingActor } from '../http/auth_shape.js';
+/** Query schema for the audit-log SSE route — multi-actor admins pass `?acting=<uuid>`. */
+const AuditStreamQuery = z.strictObject({ acting: ActingActor });
 /**
  * Create the optional audit-log SSE route spec.
  *
@@ -33,15 +36,16 @@ export const create_audit_log_route_specs = (options) => {
         {
             method: 'GET',
             path: '/audit/stream',
-            auth: { type: 'role', role },
+            auth: { account: 'required', actor: 'required', roles: [role] },
             description: 'Subscribe to realtime audit log events',
+            query: AuditStreamQuery,
             input: z.null(),
             output: z.null(), // SSE — no JSON response
             handler: (c) => {
                 const ctx = require_request_context(c);
                 // scope = session hash (capped → tabs-per-session limit and
                 // session-specific `session_revoke` close). groups = [account_id]
-                // (uncapped → coarse close on permit_revoke / session_revoke_all
+                // (uncapped → coarse close on role_grant_revoke / session_revoke_all
                 // / password_change).
                 const token_hash = c.get(AUTH_SESSION_TOKEN_HASH_KEY) ?? null;
                 const { response, stream } = create_sse_response(c, log);