@fuzdev/fuz_app 0.38.0 → 0.39.0

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -13,6 +13,16 @@
 import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { AuditLogEvent } from '../auth/audit_log_schema.js';
 import type { BackendWebsocketTransport } from './transports_ws_backend.js';
+/**
+ * Audit-event callback shape — the function `CreateAppBackendOptions.on_audit_event`
+ * accepts and that the helpers in this module return.
+ *
+ * Exported so consumers composing multiple handlers (typically
+ * `create_ws_auth_guard` + `create_ws_logout_closer` + their own
+ * pre-existing `on_audit_event`) can annotate their composed callback
+ * without reaching for `Parameters<typeof create_ws_auth_guard>[0]`.
+ */
+export type AuditEventHandler = (event: AuditLogEvent) => void;
 /**
  * Audit event types that trigger WebSocket socket closure.
  *
@@ -39,7 +49,7 @@ export declare const WS_DISCONNECT_EVENT_TYPES: ReadonlySet<string>;
  * @param log - logger for disconnect events (info level on non-zero closures)
  * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`
  */
-export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => ((event: AuditLogEvent) => void);
+export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 /**
  * Create an audit event handler that closes WebSocket connections on
  * user-initiated logout.
@@ -70,5 +80,5 @@ export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport
  * @param log - logger for disconnect events (info level on non-zero closures)
  * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`
  */
-export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => ((event: AuditLogEvent) => void);
+export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 //# sourceMappingURL=transports_ws_auth_guard.d.ts.map

package/dist/actions/transports_ws_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAajC,CAAC"}
+{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}

package/dist/auth/CLAUDE.md

@@ -162,22 +162,40 @@ Separated from runtime types to isolate DDL concerns. Consumed by
   `_decline` / `_retract` / `_expire` / `_supersede`.
 - `AuditEventType` (Zod enum), `AuditOutcome` (`'success' | 'failure'`).
 - `AUDIT_METADATA_SCHEMAS` — per-type `z.looseObject`. Notable shapes:
-  - `permit_grant` metadata carries `scope_id`, optional `permit_id` (failed
-    grants omit — `web_grantable` denial never produces a row), optional
-    `source_offer_id`.
-  - `permit_revoke` metadata carries `scope_id`, optional `reason`.
-  - `permit_offer_create` metadata carries optional `offer_id` (failed
-    creates omit).
-  - `permit_offer_supersede` metadata carries
-    `reason: 'sibling_accepted' | 'permit_revoked'` + `cause_id` (accepted
-    offer id or revoked permit id).
-- `AuditLogEvent` (row), `AuditLogInput<T>` (narrow metadata), `AuditLogListOptions`
-  (supports `since_seq` for SSE reconnection gap fill).
+  - `permit_grant` — `scope_id`, optional `permit_id` (failed grants
+    omit — `web_grantable` denial never produces a row), optional `source_offer_id`.
+  - `permit_revoke` — `scope_id`, optional `reason`.
+  - `permit_offer_create` — optional `offer_id` (failed creates omit).
+  - `permit_offer_supersede` — `reason: 'sibling_accepted' | 'permit_revoked'`
+    plus `cause_id` (accepted offer id or revoked permit id).
+- `AuditLogEvent` (row); `AuditLogInput<T extends string = AuditEventType>`
+  (narrow metadata when `T` is builtin, generic record otherwise);
+  `AuditLogListOptions` (supports `since_seq` for SSE reconnection gap fill).
 - Client-safe: `AuditLogEventJson`, `AuditLogEventWithUsernamesJson`,
   `PermitHistoryEventJson`, `AdminSessionJson`.
-- `get_audit_metadata(event)` type-narrows metadata after checking `event_type`.
+- `get_audit_metadata(event)` type-narrows after checking `event_type`.
 - DDL: `AUDIT_LOG_SCHEMA` (includes monotonically-increasing `seq SERIAL`
-  column for cursor-based gap fill), `AUDIT_LOG_INDEXES`.
+  for cursor-based gap fill), `AUDIT_LOG_INDEXES`.
+- **Consumer extensibility**: `create_audit_log_config({extra_events})`
+  builds an `AuditLogConfig` merging builtins with consumer event-type
+  strings keyed to a Zod schema (validates metadata) or `null` (registers
+  without validation). Pass the result as the trailing `config` argument
+  to `audit_log_fire_and_forget` / `query_audit_log`; both default to
+  `BUILTIN_AUDIT_LOG_CONFIG`. Builtin collisions and `AuditEventTypeName`
+  format failures throw at construction. The DB column is `TEXT NOT NULL`
+  (no enum), so consumer types round-trip through list queries and SSE
+  identically to builtins. The `audit_log_list` RPC filter still uses the
+  closed `AuditEventType` — widening that is future work.
+- **Drift counters**: `audit_metadata_validation_failures` (schema mismatch)
+  and `audit_unknown_event_type_failures` (`event_type` not in active
+  config). Both fail-open. Independent in implementation; under the
+  factory they track the same config, but a hand-rolled `AuditLogConfig`
+  (or a cast escape) can fire both on a single emission. Sample via
+  `get_*` getters; `reset_*` are test-only. `AUDIT_EVENT_TYPES`,
+  `AUDIT_METADATA_SCHEMAS`, `BUILTIN_AUDIT_LOG_CONFIG`, and the configs
+  returned by `create_audit_log_config` are `Object.freeze`'d to convert
+  accidental mutation (bugs, test cross-contamination, cast escapes)
+  into loud TypeErrors — not a security boundary.
 
 ### Permit offer (`permit_offer_schema.ts`)
 
@@ -422,31 +440,29 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 ### `audit_log_queries.ts`
 
 - `AUDIT_LOG_DEFAULT_LIMIT = 50`.
-- `query_audit_log<T>(deps, input)` — validates metadata against
-  `AUDIT_METADATA_SCHEMAS[event_type]` in production + DEV both.
-  Mismatches `console.error` and increment
-  `audit_metadata_validation_failures` (sample via
-  `get_audit_metadata_validation_failures()`), but never throw — fail-open
-  by design, matching the rest of the fire-and-forget audit pipeline.
-  Returns the inserted row via `RETURNING *` (so callers get `id`, `seq`,
-  `created_at`).
-- `get_audit_metadata_validation_failures()` / `reset_audit_metadata_validation_failures()` —
-  read / clear the in-process counter. Single-process scope (resets on
-  restart); operators thread it into a future `/metrics` surface or a
-  debug RPC handler when external observability is needed.
+- `query_audit_log<T>(deps, input, config?)` — `config` defaults to
+  `BUILTIN_AUDIT_LOG_CONFIG`. Membership check runs against
+  `config.event_types`; metadata validation runs independently against
+  `config.metadata_schemas[event_type]` when present. Mismatches and
+  unknown types log + bump their counters (see schema section);
+  never throws. Returns the inserted row via `RETURNING *`.
+- Drift counters live alongside in this module:
+  `get_audit_metadata_validation_failures()` /
+  `get_audit_unknown_event_type_failures()` (read);
+  `reset_*` (test-only). In-process; reset on restart.
 - `query_audit_log_list(deps, options?)` — supports `event_type`,
-  `event_type_in`, `account_id` (matches either `account_id` OR
+  `event_type_in`, `account_id` (matches `account_id` OR
   `target_account_id`), `outcome`, `since_seq`, `limit`, `offset`.
 - `query_audit_log_list_with_usernames` — joins twice to `account`.
 - `query_audit_log_list_for_account`, `query_audit_log_list_permit_history`
   (filters to `permit_grant` / `permit_revoke`).
 - `query_audit_log_cleanup_before`.
-- **`audit_log_fire_and_forget(route, input, log, on_event)`** — writes to
-  `route.background_db` (pool-level), **not** the handler's transaction,
-  so audit entries **persist even when the request transaction rolls back**.
-  Write failures and `on_event` callback failures are logged separately so
-  the error message indicates the failing phase. Pushes onto
-  `route.pending_effects` for test flushing.
+- **`audit_log_fire_and_forget(route, input, log, on_event, config?)`** —
+  writes to `route.background_db` (pool-level), so audit entries persist
+  even when the request transaction rolls back. Write and `on_event`
+  callback failures are logged separately. Pushes onto
+  `route.pending_effects` for test flushing. Pass a consumer `config`
+  built once at startup; builtin handlers omit the argument.
 
 ### `migrations.ts`
 

package/dist/auth/audit_log_queries.d.ts

@@ -14,30 +14,32 @@
 import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { QueryDeps } from '../db/query_deps.js';
 import type { RouteContext } from '../http/route_spec.js';
-import { type AuditEventType, 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 PermitHistoryEventJson } from './audit_log_schema.js';
 /** Default limit for audit log listings. */
 export declare const AUDIT_LOG_DEFAULT_LIMIT = 50;
 /** 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; production code should not call this. */
+/** Reset the counter — for tests only. */
 export declare const reset_audit_metadata_validation_failures: () => void;
+/** Number of audit unknown-event-type failures observed since process start. */
+export declare const get_audit_unknown_event_type_failures: () => number;
+/** Reset the counter — for tests only. */
+export declare const reset_audit_unknown_event_type_failures: () => void;
 /**
  * Insert an audit log entry.
  *
- * Uses `RETURNING *` to return the full inserted row including
- * DB-assigned fields (`id`, `seq`, `created_at`).
- *
- * Validates `metadata` against the per-event-type schema in production +
- * DEV both. Mismatches log to `console.error` and increment
- * `audit_metadata_validation_failures` (sampled via the exported getter)
- * but never throw — the audit row is still written. Schema-vs-runtime
- * drift is an operator signal, not a request-failing condition.
+ * `RETURNING *` so callers receive DB-assigned fields (`id`, `seq`,
+ * `created_at`). Validates `metadata` against `config.metadata_schemas`;
+ * unknown `event_type` and metadata mismatches log + bump their counters
+ * but write the row anyway. Consumers extend the recognized set via
+ * `create_audit_log_config({extra_events})`.
  *
  * @param deps - query dependencies
  * @param input - the audit event to record
+ * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
  * @returns the inserted audit log row
  */
-export declare const query_audit_log: <T extends AuditEventType>(deps: QueryDeps, input: AuditLogInput<T>) => Promise<AuditLogEvent>;
+export declare const query_audit_log: <T extends string>(deps: QueryDeps, input: AuditLogInput<T>, config?: AuditLogConfig) => Promise<AuditLogEvent>;
 /**
  * List audit log entries, newest first.
  *
@@ -82,16 +84,16 @@ export declare const query_audit_log_cleanup_before: (deps: QueryDeps, before: D
 /**
  * Log an audit event without blocking the caller.
  *
- * Errors are logged to console — audit logging never breaks auth flows.
- * Uses `background_db` so audit entries persist even if the request transaction rolls back.
- * Write failures and `on_event` callback failures are logged separately
- * so the error message indicates which phase failed.
+ * 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_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 log - the logger instance
  * @param on_event - callback invoked with the inserted row after a successful write
- * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * @returns the settled promise (callers may ignore it)
  */
-export declare const audit_log_fire_and_forget: <T extends AuditEventType>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, log: Logger, on_event: (event: AuditLogEvent) => void) => Promise<void>;
+export declare const audit_log_fire_and_forget: <T extends string>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, log: Logger, on_event: (event: AuditLogEvent) => void, config?: AuditLogConfig) => 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,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAmB1C,iFAAiF;AACjF,eAAO,MAAM,sCAAsC,QAAO,MACvB,CAAC;AAEpC,gFAAgF;AAChF,eAAO,MAAM,wCAAwC,QAAO,IAE3D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,SAAS,cAAc,EAC7D,MAAM,SAAS,EACf,OAAO,aAAa,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC,aAAa,CA2BvB,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;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,cAAc,EACjE,OAAO,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,iBAAiB,CAAC,EAC9D,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,KAAK,MAAM,EACX,UAAU,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,KACtC,OAAO,CAAC,IAAI,CAcd,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,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAa1C,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;;;;;;;;;;;;;GAaG;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;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,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,KAAK,MAAM,EACX,UAAU,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EACxC,SAAQ,cAAyC,KAC/C,OAAO,CAAC,IAAI,CAcd,CAAC"}

package/dist/auth/audit_log_queries.js

@@ -12,54 +12,67 @@
  * @module
  */
 import { assert_row } from '../db/assert_row.js';
-import { AUDIT_METADATA_SCHEMAS, } from './audit_log_schema.js';
+import { BUILTIN_AUDIT_LOG_CONFIG, } from './audit_log_schema.js';
 /** Default limit for audit log listings. */
 export const AUDIT_LOG_DEFAULT_LIMIT = 50;
 /**
- * Process-wide counter for audit metadata validation failures.
- *
- * `query_audit_log` validates each `metadata` payload against the per-event
- * schema in `AUDIT_METADATA_SCHEMAS` and increments this counter on
- * mismatch. The audit row is still written — validation is fail-open by
- * design, matching the rest of the fire-and-forget audit pipeline (a
- * schema-vs-runtime drift should not break auth flows). Operators sample
- * the counter via `get_audit_metadata_validation_failures()` (e.g. from
- * a future `/metrics` surface or a debug RPC handler).
- *
- * Single-process scope: fuz_app's runtime state lives in-process (rate
- * limiter, daemon token state); this counter follows the same pattern
- * and resets on server restart.
+ * Process-wide counter for audit metadata validation failures. `query_audit_log`
+ * increments on `safeParse` mismatch and writes the row anyway (fail-open —
+ * schema drift should not break auth flows). Independent of the
+ * unknown-event-type counter — `create_audit_log_config` keeps the two in
+ * sync, but a hand-rolled `AuditLogConfig` (or a cast escape) can have a
+ * schema entry without a matching `event_types` entry, in which case both
+ * counters bump on a single emission. In-process; resets on restart.
  */
 let audit_metadata_validation_failures = 0;
 /** Number of audit metadata validation failures observed since process start. */
 export const get_audit_metadata_validation_failures = () => audit_metadata_validation_failures;
-/** Reset the counter — for tests only; production code should not call this. */
+/** Reset the counter — for tests only. */
 export const reset_audit_metadata_validation_failures = () => {
     audit_metadata_validation_failures = 0;
 };
+/**
+ * Process-wide counter for audit-log emissions whose `event_type` is missing
+ * from the active config. Same fail-open posture as the metadata counter;
+ * orthogonal in implementation — metadata validation runs regardless of
+ * registration — though under the factory both counters track the same
+ * config (see `audit_metadata_validation_failures`). Catches typos and
+ * missing `extra_events` registrations.
+ */
+let audit_unknown_event_type_failures = 0;
+/** Number of audit unknown-event-type failures observed since process start. */
+export const get_audit_unknown_event_type_failures = () => audit_unknown_event_type_failures;
+/** Reset the counter — for tests only. */
+export const reset_audit_unknown_event_type_failures = () => {
+    audit_unknown_event_type_failures = 0;
+};
 /**
  * Insert an audit log entry.
  *
- * Uses `RETURNING *` to return the full inserted row including
- * DB-assigned fields (`id`, `seq`, `created_at`).
- *
- * Validates `metadata` against the per-event-type schema in production +
- * DEV both. Mismatches log to `console.error` and increment
- * `audit_metadata_validation_failures` (sampled via the exported getter)
- * but never throw — the audit row is still written. Schema-vs-runtime
- * drift is an operator signal, not a request-failing condition.
+ * `RETURNING *` so callers receive DB-assigned fields (`id`, `seq`,
+ * `created_at`). Validates `metadata` against `config.metadata_schemas`;
+ * unknown `event_type` and metadata mismatches log + bump their counters
+ * but write the row anyway. Consumers extend the recognized set via
+ * `create_audit_log_config({extra_events})`.
  *
  * @param deps - query dependencies
  * @param input - the audit event to record
+ * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
  * @returns the inserted audit log row
  */
-export const query_audit_log = async (deps, input) => {
+export const query_audit_log = async (deps, input, config = BUILTIN_AUDIT_LOG_CONFIG) => {
+    if (!config.event_types.includes(input.event_type)) {
+        audit_unknown_event_type_failures++;
+        console.error(`[audit_log] unknown event_type '${input.event_type}' — register via create_audit_log_config({extra_events})`);
+    }
     if (input.metadata != null) {
-        const schema = AUDIT_METADATA_SCHEMAS[input.event_type];
-        const result = schema.safeParse(input.metadata);
-        if (!result.success) {
-            audit_metadata_validation_failures++;
-            console.error(`[audit_log] metadata mismatch for '${input.event_type}':`, result.error.issues);
+        const schema = config.metadata_schemas[input.event_type];
+        if (schema) {
+            const result = schema.safeParse(input.metadata);
+            if (!result.success) {
+                audit_metadata_validation_failures++;
+                console.error(`[audit_log] metadata mismatch for '${input.event_type}':`, result.error.issues);
+            }
         }
     }
     const rows = await deps.db.query(`INSERT INTO audit_log (event_type, outcome, actor_id, account_id, target_account_id, ip, metadata)
@@ -201,19 +214,19 @@ export const query_audit_log_cleanup_before = async (deps, before) => {
 /**
  * Log an audit event without blocking the caller.
  *
- * Errors are logged to console — audit logging never breaks auth flows.
- * Uses `background_db` so audit entries persist even if the request transaction rolls back.
- * Write failures and `on_event` callback failures are logged separately
- * so the error message indicates which phase failed.
+ * 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_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 log - the logger instance
  * @param on_event - callback invoked with the inserted row after a successful write
- * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * @returns the settled promise (callers may ignore it)
  */
-export const audit_log_fire_and_forget = (route, input, log, on_event) => {
-    const p = query_audit_log({ db: route.background_db }, input)
+export const audit_log_fire_and_forget = (route, input, log, on_event, config = BUILTIN_AUDIT_LOG_CONFIG) => {
+    const p = query_audit_log({ db: route.background_db }, input, config)
         .then((event) => {
         try {
             on_event(event);

package/dist/auth/audit_log_schema.d.ts

@@ -8,7 +8,12 @@
  */
 import { z } from 'zod';
 import { Uuid } from '../uuid.js';
-/** All tracked auth event types. */
+/**
+ * All tracked auth event types. Frozen to convert accidental in-process
+ * mutation (test cross-contamination, cast escapes) into loud TypeErrors.
+ * Not a security boundary — in-process code has many other paths to subvert
+ * audit logging.
+ */
 export declare const AUDIT_EVENT_TYPES: readonly ["login", "logout", "bootstrap", "signup", "password_change", "session_revoke", "session_revoke_all", "token_create", "token_revoke", "token_revoke_all", "permit_grant", "permit_revoke", "permit_offer_create", "permit_offer_accept", "permit_offer_decline", "permit_offer_retract", "permit_offer_expire", "permit_offer_supersede", "invite_create", "invite_delete", "app_settings_update"];
 /** Zod schema for audit event types. */
 export declare const AuditEventType: z.ZodEnum<{
@@ -35,6 +40,15 @@ export declare const AuditEventType: z.ZodEnum<{
     app_settings_update: "app_settings_update";
 }>;
 export type AuditEventType = z.infer<typeof AuditEventType>;
+/**
+ * Letter start, then letters, digits, `_`, `.`, `/`, `-`. Accepts snake_case,
+ * dotted, and namespaced consumer conventions; rejects empty strings, leading
+ * separators, whitespace, and control characters.
+ */
+export declare const AUDIT_EVENT_TYPE_NAME_REGEX: RegExp;
+/** Zod schema for valid audit event-type name strings. */
+export declare const AuditEventTypeName: z.ZodString;
+export type AuditEventTypeName = z.infer<typeof AuditEventTypeName>;
 /** Zod schema for audit event outcomes. */
 export declare const AuditOutcome: z.ZodEnum<{
     success: "success";
@@ -42,13 +56,13 @@ export declare const AuditOutcome: z.ZodEnum<{
 }>;
 export type AuditOutcome = z.infer<typeof AuditOutcome>;
 /**
- * Per-event-type metadata Zod schemas.
- *
- * Uses `z.looseObject` so consumers can add extra fields
- * (e.g. visiones `self_service`) while known fields are validated.
- * Events with outcome-dependent metadata use a union with `z.null()`.
+ * Per-event-type metadata Zod schemas. `z.looseObject` so consumers can
+ * add fields while known ones are validated. The record is frozen to
+ * catch mutation bugs at the key level (e.g. tests that try to swap in a
+ * stub schema); the Zod schemas themselves are reachable and mutable —
+ * freeze isn't a security boundary.
  */
-export declare const AUDIT_METADATA_SCHEMAS: {
+export declare const AUDIT_METADATA_SCHEMAS: Readonly<{
     login: z.ZodNullable<z.ZodObject<{
         username: z.ZodString;
     }, z.core.$loose>>;
@@ -147,7 +161,7 @@ export declare const AUDIT_METADATA_SCHEMAS: {
         old_value: z.ZodUnknown;
         new_value: z.ZodUnknown;
     }, z.core.$loose>;
-};
+}>;
 /** Mapped type of metadata shapes per event type, derived from Zod schemas. */
 export type AuditMetadataMap = {
     [K in AuditEventType]: z.infer<(typeof AUDIT_METADATA_SCHEMAS)[K]>;
@@ -174,15 +188,72 @@ export declare const get_audit_metadata: <T extends AuditEventType>(event: Audit
     event_type: T;
 }) => AuditMetadataMap[T] | null;
 /** Input for creating an audit log entry. */
-export interface AuditLogInput<T extends AuditEventType = AuditEventType> {
+export interface AuditLogInput<T extends string = AuditEventType> {
     event_type: T;
     outcome?: AuditOutcome;
     actor_id?: Uuid | null;
     account_id?: Uuid | null;
     target_account_id?: Uuid | null;
     ip?: string | null;
-    metadata?: (AuditMetadataMap[T] & Record<string, unknown>) | null;
+    /**
+     * Per-event-type metadata. Builtin `T` narrows to `AuditMetadataMap[T]`;
+     * consumer strings widen to a generic record (validation runs against
+     * `AuditLogConfig.metadata_schemas` at insert time).
+     */
+    metadata?: T extends AuditEventType ? (AuditMetadataMap[T] & Record<string, unknown>) | null : Record<string, unknown> | null;
+}
+/**
+ * Configuration bundle for audit-log event types and metadata schemas.
+ *
+ * Lets consumers extend the closed `AUDIT_EVENT_TYPES` enum with their own
+ * event strings (and metadata Zod schemas) without forking. Pass to
+ * `audit_log_fire_and_forget` / `query_audit_log` as the optional `config`
+ * argument; both default to `BUILTIN_AUDIT_LOG_CONFIG`.
+ *
+ * The DB column is `TEXT NOT NULL` and never enforced an enum, so consumer
+ * event types round-trip through `query_audit_log_list` and SSE identically
+ * to builtins.
+ *
+ * Constructed configs are deep-frozen (wrapper, `event_types`,
+ * `metadata_schemas`) to catch accidental mutation bugs early. Not a
+ * security boundary against in-process code, which can subvert audit
+ * logging through other paths.
+ */
+export interface AuditLogConfig {
+    /** All recognized event-type strings — fuz_app builtins plus consumer extras. */
+    readonly event_types: ReadonlyArray<string>;
+    /**
+     * Per-event-type metadata schemas. Missing entries skip metadata
+     * validation for that type (row still written; metadata stored as raw JSONB).
+     */
+    readonly metadata_schemas: Readonly<Record<string, z.ZodType>>;
+}
+/** Builtin fuz_app audit-log config — every existing event type and its metadata schema. */
+export declare const BUILTIN_AUDIT_LOG_CONFIG: AuditLogConfig;
+/** Options for `create_audit_log_config`. */
+export interface CreateAuditLogConfigOptions {
+    /**
+     * Extra event types keyed by event-type string. Value is a Zod metadata
+     * schema, or `null` to register the type without validation (row still
+     * written, metadata stored as raw JSONB).
+     *
+     * Collisions with builtin event-type strings throw at construction.
+     * Schemas are run via `safeParse` at insert time; mismatches log + count
+     * but never throw (fail-open — see the drift counters in `audit_log_queries.ts`).
+     */
+    extra_events?: Readonly<Record<string, z.ZodType | null>>;
 }
+/**
+ * Build an `AuditLogConfig` by merging fuz_app builtins with consumer extras.
+ *
+ * Throws when an `extra_events` key collides with a builtin event type, or
+ * fails `AuditEventTypeName` format validation.
+ *
+ * Call once at startup; pass the result to consumer-emitted
+ * `audit_log_fire_and_forget` calls. Builtin handlers omit the argument and
+ * pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ */
+export declare const create_audit_log_config: (options?: CreateAuditLogConfigOptions) => AuditLogConfig;
 /** Options for listing audit log entries. */
 export interface AuditLogListOptions {
     limit?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit_log_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_schema.ts"],"names":[],"mappings":"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"}

package/dist/auth/audit_log_schema.js

@@ -9,8 +9,13 @@
 import { z } from 'zod';
 import { Uuid } from '../uuid.js';
 import { AuthSessionJson } from './account_schema.js';
-/** All tracked auth event types. */
-export const AUDIT_EVENT_TYPES = [
+/**
+ * All tracked auth event types. Frozen to convert accidental in-process
+ * mutation (test cross-contamination, cast escapes) into loud TypeErrors.
+ * Not a security boundary — in-process code has many other paths to subvert
+ * audit logging.
+ */
+export const AUDIT_EVENT_TYPES = Object.freeze([
     'login',
     'logout',
     'bootstrap',
@@ -32,19 +37,29 @@ export const AUDIT_EVENT_TYPES = [
     'invite_create',
     'invite_delete',
     'app_settings_update',
-];
+]);
 /** Zod schema for audit event types. */
 export const AuditEventType = z.enum(AUDIT_EVENT_TYPES);
+/**
+ * Letter start, then letters, digits, `_`, `.`, `/`, `-`. Accepts snake_case,
+ * dotted, and namespaced consumer conventions; rejects empty strings, leading
+ * separators, whitespace, and control characters.
+ */
+export const AUDIT_EVENT_TYPE_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_./-]*$/;
+/** Zod schema for valid audit event-type name strings. */
+export const AuditEventTypeName = z.string().regex(AUDIT_EVENT_TYPE_NAME_REGEX, {
+    message: 'must start with a letter; only letters, digits, _ . / - allowed',
+});
 /** Zod schema for audit event outcomes. */
 export const AuditOutcome = z.enum(['success', 'failure']);
 /**
- * Per-event-type metadata Zod schemas.
- *
- * Uses `z.looseObject` so consumers can add extra fields
- * (e.g. visiones `self_service`) while known fields are validated.
- * Events with outcome-dependent metadata use a union with `z.null()`.
+ * Per-event-type metadata Zod schemas. `z.looseObject` so consumers can
+ * add fields while known ones are validated. The record is frozen to
+ * catch mutation bugs at the key level (e.g. tests that try to swap in a
+ * stub schema); the Zod schemas themselves are reachable and mutable —
+ * freeze isn't a security boundary.
  */
-export const AUDIT_METADATA_SCHEMAS = {
+export const AUDIT_METADATA_SCHEMAS = Object.freeze({
     login: z.looseObject({ username: z.string() }).nullable(),
     logout: z.null(),
     bootstrap: z.looseObject({ error: z.string() }).nullable(),
@@ -139,7 +154,7 @@ export const AUDIT_METADATA_SCHEMAS = {
         old_value: z.unknown(),
         new_value: z.unknown(),
     }),
-};
+});
 /**
  * Narrow metadata type for a known event type.
  *
@@ -148,6 +163,48 @@ export const AUDIT_METADATA_SCHEMAS = {
 export const get_audit_metadata = (event) => {
     return event.metadata;
 };
+/** Builtin fuz_app audit-log config — every existing event type and its metadata schema. */
+export const BUILTIN_AUDIT_LOG_CONFIG = Object.freeze({
+    event_types: AUDIT_EVENT_TYPES,
+    metadata_schemas: AUDIT_METADATA_SCHEMAS,
+});
+/**
+ * Build an `AuditLogConfig` by merging fuz_app builtins with consumer extras.
+ *
+ * Throws when an `extra_events` key collides with a builtin event type, or
+ * fails `AuditEventTypeName` format validation.
+ *
+ * Call once at startup; pass the result to consumer-emitted
+ * `audit_log_fire_and_forget` calls. Builtin handlers omit the argument and
+ * pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ */
+export const create_audit_log_config = (options) => {
+    const extras = options?.extra_events;
+    if (!extras)
+        return BUILTIN_AUDIT_LOG_CONFIG;
+    const extra_entries = Object.entries(extras);
+    if (extra_entries.length === 0)
+        return BUILTIN_AUDIT_LOG_CONFIG;
+    const builtin_set = new Set(AUDIT_EVENT_TYPES);
+    const extra_keys = [];
+    const metadata_schemas = { ...AUDIT_METADATA_SCHEMAS };
+    for (const [t, schema] of extra_entries) {
+        if (builtin_set.has(t)) {
+            throw new Error(`extra_events key "${t}" collides with a builtin event type — pick a distinct string (e.g. "app_${t}")`);
+        }
+        const name_check = AuditEventTypeName.safeParse(t);
+        if (!name_check.success) {
+            throw new Error(`extra_events key "${t}" has invalid format: ${name_check.error.issues[0].message}`);
+        }
+        extra_keys.push(t);
+        if (schema !== null)
+            metadata_schemas[t] = schema;
+    }
+    return Object.freeze({
+        event_types: Object.freeze([...AUDIT_EVENT_TYPES, ...extra_keys]),
+        metadata_schemas: Object.freeze(metadata_schemas),
+    });
+};
 /** Zod schema for client-safe audit log event. */
 export const AuditLogEventJson = z.strictObject({
     id: Uuid,

package/dist/auth/role_schema.d.ts

@@ -35,7 +35,16 @@ export interface RoleOptions {
     /** If true, admins can grant this role via the web UI. Default `true`. */
     web_grantable?: boolean;
 }
-/** Builtin role configs. Not overridable by consumers. */
+/**
+ * Builtin role configs. 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_role_schema` and the admin / permit-offer
+ * action factories; runtime mutation has no effect on already-built role
+ * schemas.
+ */
 export declare const BUILTIN_ROLE_OPTIONS: ReadonlyMap<string, Required<RoleOptions>>;
 /** The result of `create_role_schema` — a Zod schema and config map for all roles. */
 export interface RoleSchemaResult {