@fuzdev/fuz_app 0.63.0 → 0.64.0

package/dist/auth/audit_emitter.d.ts

@@ -2,11 +2,14 @@
  * 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).
+ * subscriber chain, and the optional `AuditLogConfig`. Built by the
+ * consumer's `audit_factory` callback on `CreateAppBackendOptions` —
+ * `create_app_backend` invokes the factory once with its constructed
+ * `{db, log}` and lands the result on `AppDeps.audit`. 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:
  *
@@ -26,9 +29,13 @@
  *   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.
+ * The chain is a documented mutable seam — `create_app_server` appends
+ * additional listeners after the backend is built (the factory-managed
+ * audit-log SSE, per-endpoint WS auth guards and logout closers, any
+ * `extra_audit_handlers` on a `WsEndpointSpec`) before the first request
+ * runs. Consumers can also append listeners directly on the emitter
+ * they return from `audit_factory` for setups that don't pass through
+ * `create_app_server`.
  *
  * @module
  */
@@ -126,12 +133,36 @@ export interface AuditEmitter {
      */
     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`.
+     * Mutable subscriber chain. `create_app_server` appends the
+     * factory-managed audit-log SSE listener and per-endpoint WS auth
+     * guards / logout closers here so SSE + WS fan-out compose on top of
+     * the consumer's `on_audit_event` callback without shallow-copying
+     * `AppDeps`. Consumers can also append listeners directly for setups
+     * that don't run through `create_app_server`.
      */
     readonly on_event_chain: Array<(event: AuditLogEvent) => void>;
 }
+/**
+ * Signature of `AuditEmitter.emit` — captured by the inner closure so
+ * `emit_role_grant_target` reaches the decorated function rather than
+ * a `this.emit` lookup. Exposed as a type so `EmitDecorator` can name
+ * the inner / outer slot.
+ */
+export type AuditEmitFn = <T extends string>(ctx: AuditEmitterContext, input: AuditLogInput<T>) => void;
+/**
+ * Wrap the bound `emit` before it gets captured by `emit_role_grant_target`'s
+ * closure and exposed on the returned `AuditEmitter`. Test instrumentation
+ * uses this to record `emit` invocation ordering against external markers
+ * (e.g. eager `ConnectionCloser` calls in `connection_closer.db.test.ts`)
+ * without paying the freeze-breaking footgun the pre-decorator
+ * `patch_audit_emit_capture` hot-patcher had.
+ *
+ * Because the inner closure captures the decorated function (not the
+ * outer slot reference), `emit_role_grant_target` also routes through
+ * the wrap — the close-vs-emit ordering helper sees role-grant-shape
+ * emissions, not just bare `emit` calls. Production never sets this.
+ */
+export type EmitDecorator = (inner: AuditEmitFn) => AuditEmitFn;
 /** Options for `create_audit_emitter`. */
 export interface CreateAuditEmitterOptions {
     /** Pool-level `Db`. Captured by every emit call. */
@@ -149,9 +180,22 @@ export interface CreateAuditEmitterOptions {
      * registered here once at backend assembly.
      */
     audit_log_config?: AuditLogConfig;
+    /**
+     * Test-only hook to wrap `emit` at construction time. The decorated
+     * function is captured by `emit_role_grant_target`'s closure and is
+     * the function exposed on the returned `AuditEmitter`, so both call
+     * shapes route through it — see `EmitDecorator` for the rationale.
+     *
+     * Leave unset in production. The intended caller is
+     * `create_emit_ordering_audit_factory` in `testing/audit_drift_guard.ts`.
+     */
+    emit_decorator?: EmitDecorator;
 }
 /**
- * Build a bound `AuditEmitter`. Called once at `create_app_backend` time.
+ * Build a bound `AuditEmitter`. Typical caller is the consumer's
+ * `audit_factory` callback on `CreateAppBackendOptions` —
+ * `create_app_backend` invokes that callback with its constructed
+ * `{db, log}` and lands the result on `AppDeps.audit`.
  *
  * @param options - pool, logger, optional initial subscriber, optional config
  * @returns the bound emitter; closes over the pool + config + listener chain

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

@@ -1 +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"}
+{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KACnB,IAAI,CAAC;AAEV;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,CAAC;AAEhE,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;IAClC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YAoEzE,CAAC"}

package/dist/auth/audit_emitter.js

@@ -2,11 +2,14 @@
  * 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).
+ * subscriber chain, and the optional `AuditLogConfig`. Built by the
+ * consumer's `audit_factory` callback on `CreateAppBackendOptions` —
+ * `create_app_backend` invokes the factory once with its constructed
+ * `{db, log}` and lands the result on `AppDeps.audit`. 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:
  *
@@ -26,22 +29,29 @@
  *   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.
+ * The chain is a documented mutable seam — `create_app_server` appends
+ * additional listeners after the backend is built (the factory-managed
+ * audit-log SSE, per-endpoint WS auth guards and logout closers, any
+ * `extra_audit_handlers` on a `WsEndpointSpec`) before the first request
+ * runs. Consumers can also append listeners directly on the emitter
+ * they return from `audit_factory` for setups that don't pass through
+ * `create_app_server`.
  *
  * @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.
+ * Build a bound `AuditEmitter`. Typical caller is the consumer's
+ * `audit_factory` callback on `CreateAppBackendOptions` —
+ * `create_app_backend` invokes that callback with its constructed
+ * `{db, log}` and lands the result on `AppDeps.audit`.
  *
  * @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 { db, log, audit_log_config = builtin_audit_log_config, emit_decorator } = options;
     const on_event_chain = [];
     if (options.on_audit_event)
         on_event_chain.push(options.on_audit_event);
@@ -64,9 +74,14 @@ export const create_audit_emitter = (options) => {
             log.error('Audit log write failed:', err);
         }
     };
-    const emit = (ctx, input) => {
+    const base_emit = (ctx, input) => {
         ctx.pending_effects.push(emit_pool(input));
     };
+    // The decorated `emit` is what `emit_role_grant_target` captures below
+    // and what gets exposed on the returned object — both call shapes
+    // route through any `emit_decorator` the caller supplied. Production
+    // passes no decorator, so this collapses to `base_emit`.
+    const emit = emit_decorator ? emit_decorator(base_emit) : base_emit;
     const emit_role_grant_target = (ctx, auth, input) => {
         emit(ctx, {
             event_type: input.event_type,
@@ -79,5 +94,16 @@ export const create_audit_emitter = (options) => {
             metadata: input.metadata,
         });
     };
-    return { emit, emit_role_grant_target, emit_pool, notify, on_event_chain };
+    // Freeze the slot layout so consumers cannot hot-patch `emit` /
+    // `emit_role_grant_target` / `emit_pool` / `notify` after construction.
+    // The previous test helper `patch_audit_emit_capture` did exactly this
+    // and only happened to work because the four slots were writable —
+    // `emit_role_grant_target` calls the closed-over inner `emit`, not
+    // `this.emit`, so the patch silently bypassed role-grant-shape emits.
+    // Tests that need instrumentation pass `emit_decorator` so the wrap
+    // is captured by the closure before the freeze (see
+    // `create_emit_ordering_audit_factory`). `on_event_chain` is a
+    // frozen reference but its array contents stay mutable —
+    // `create_app_server` appends to it post-assembly, by design.
+    return Object.freeze({ emit, emit_role_grant_target, emit_pool, notify, on_event_chain });
 };

package/dist/auth/audit_log_schema.d.ts

@@ -336,9 +336,11 @@ export interface CreateAuditLogConfigOptions {
  * 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 `create_app_backend` (which
- * threads it into `AppDeps.audit`). Builtin handlers omit the
- * `audit_log_config` slot and pick up `builtin_audit_log_config`.
+ * Call once at startup; pass the result into the consumer's `audit_factory`
+ * body — typically `({db, log}) => create_audit_emitter({db, log,
+ * audit_log_config, ...})` — so it gets captured inside the bound
+ * `AppDeps.audit` emitter. Builtin handlers omit the `audit_log_config`
+ * slot and pick up `builtin_audit_log_config`.
  *
  * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */

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":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAoB5C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,8aAsBnB,CAAC;AAEZ,wCAAwC;AACxC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QAA+B,CAAC;AAExE,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,aAE7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,2CAA2C;AAC3C,eAAO,MAAM,YAAY;;;EAAiC,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkNW,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG;KAC7B,CAAC,IAAI,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC;AAEF,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,cAAc,EAC1D,OAAO,aAAa,GAAG;IAAC,UAAU,EAAE,CAAC,CAAA;CAAC,KACpC,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAExB,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,cAAc;IAC/D,UAAU,EAAE,CAAC,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,iBAAiB,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,eAAe,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,SAAS,cAAc,GAChC,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GACtD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,cAAc;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CAC/D;AAED,4FAA4F;AAC5F,eAAO,MAAM,wBAAwB,EAAE,cAGrC,CAAC;AAEH,6CAA6C;AAC7C,MAAM,WAAW,2BAA2B;IAC3C;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,2BAA2B,KAAG,cA2B/E,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;kBAY5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,+DAA+D;AAC/D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;kBAGzC,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE5F,wEAAwE;AACxE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;kBAGpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;kBAE3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"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

@@ -291,9 +291,11 @@ export const builtin_audit_log_config = Object.freeze({
  * 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 `create_app_backend` (which
- * threads it into `AppDeps.audit`). Builtin handlers omit the
- * `audit_log_config` slot and pick up `builtin_audit_log_config`.
+ * Call once at startup; pass the result into the consumer's `audit_factory`
+ * body — typically `({db, log}) => create_audit_emitter({db, log,
+ * audit_log_config, ...})` — so it gets captured inside the bound
+ * `AppDeps.audit` emitter. Builtin handlers omit the `audit_log_config`
+ * slot and pick up `builtin_audit_log_config`.
  *
  * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */

package/dist/auth/bootstrap_routes.d.ts

@@ -19,7 +19,7 @@ import type { StatResult } from '../runtime/deps.js';
 /** Input for `POST /bootstrap`. `token` is the one-shot token file contents. */
 export declare const BootstrapInput: z.ZodObject<{
     token: z.ZodString;
-    username: z.ZodString;
+    username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     password: z.ZodString;
 }, z.core.$strict>;
 export type BootstrapInput = z.infer<typeof BootstrapInput>;

package/dist/auth/invite_schema.d.ts

@@ -23,7 +23,7 @@ export interface Invite {
 export declare const InviteJson: z.ZodObject<{
     id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
     email: z.ZodNullable<z.ZodEmail>;
-    username: z.ZodNullable<z.ZodString>;
+    username: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
     claimed_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
     claimed_at: z.ZodNullable<z.ZodString>;
     created_at: z.ZodString;
@@ -34,7 +34,7 @@ export type InviteJson = z.infer<typeof InviteJson>;
 export declare const InviteWithUsernamesJson: z.ZodObject<{
     id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
     email: z.ZodNullable<z.ZodEmail>;
-    username: z.ZodNullable<z.ZodString>;
+    username: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
     claimed_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
     claimed_at: z.ZodNullable<z.ZodString>;
     created_at: z.ZodString;

package/dist/auth/signup_routes.d.ts

@@ -24,7 +24,7 @@ export interface SignupRouteOptions extends AuthSessionRouteOptions {
 }
 /** Input for `POST /signup`. `email` is optional and must match any referenced invite. */
 export declare const SignupInput: z.ZodObject<{
-    username: z.ZodString;
+    username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     password: z.ZodString;
     email: z.ZodOptional<z.ZodEmail>;
 }, z.core.$strict>;

package/dist/auth/standard_rpc_actions.d.ts

@@ -10,6 +10,7 @@
  * Option routing: shared `roles` flows to both admin and role-grant-offer;
  * `app_settings` goes to admin only; `default_ttl_ms` and `authorize` go
  * to role-grant-offer only; `max_tokens` goes to account only;
+ * shared `connection_closer` flows to admin + account (role-grant-offer ignores);
  * `notification_sender` reaches role-grant-offer transparently (admin + account
  * ignore it).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"standard_rpc_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/standard_rpc_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAuB,KAAK,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAEN,KAAK,2BAA2B,EAChC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAyB,KAAK,oBAAoB,EAAC,MAAM,sBAAsB,CAAC;AACvF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAChB,SAAQ,kBAAkB,EAAE,2BAA2B,EAAE,oBAAoB;CAAG;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC;IACtF,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,sBAAsB,EAC5B,UAAS,yBAA8B,KACrC,KAAK,CAAC,SAAS,CAIjB,CAAC"}
+{"version":3,"file":"standard_rpc_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/standard_rpc_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAuB,KAAK,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAEN,KAAK,2BAA2B,EAChC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAyB,KAAK,oBAAoB,EAAC,MAAM,sBAAsB,CAAC;AACvF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAChB,SAAQ,kBAAkB,EAAE,2BAA2B,EAAE,oBAAoB;CAAG;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC;IACtF,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,sBAAsB,EAC5B,UAAS,yBAA8B,KACrC,KAAK,CAAC,SAAS,CAIjB,CAAC"}

package/dist/auth/standard_rpc_actions.js

@@ -10,6 +10,7 @@
  * Option routing: shared `roles` flows to both admin and role-grant-offer;
  * `app_settings` goes to admin only; `default_ttl_ms` and `authorize` go
  * to role-grant-offer only; `max_tokens` goes to account only;
+ * shared `connection_closer` flows to admin + account (role-grant-offer ignores);
  * `notification_sender` reaches role-grant-offer transparently (admin + account
  * ignore it).
  *

package/dist/http/CLAUDE.md

@@ -24,7 +24,8 @@ see ../../docs/architecture.md.
 | `surface.ts`         | `AppSurface`, `AppSurfaceSpec`, `generate_app_surface`, diagnostics                                    |
 | `surface_query.ts`   | Pure filters/groupings over `AppSurface`                                                               |
 | `proxy.ts`           | Trusted-proxy middleware, CIDR parsing, rightmost-first XFF resolution                                 |
-| `origin.ts`          | Origin/Referer allowlist middleware with wildcard patterns                                             |
+| `ip_canonical.ts`    | RFC 5952 IPv6 canonicalization + IPv4-mapped collapse; `IP_LITERAL_CHARS` regex                        |
+| `origin.ts`          | Origin allowlist middleware with wildcard patterns (Origin-only)                                       |
 | `jsonrpc.ts`         | JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`                              |
 | `jsonrpc_errors.ts`  | `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings                                  |
 | `jsonrpc_helpers.ts` | Message builders, type guards, input/result normalizers                                                |
@@ -280,7 +281,7 @@ invariant 2's throw) was the empirical confirmation.
 - **Auth**: `ERROR_AUTHENTICATION_REQUIRED`, `ERROR_INSUFFICIENT_PERMISSIONS`,
   `ERROR_CREDENTIAL_TYPE_REQUIRED`, `ERROR_RATE_LIMIT_EXCEEDED`,
   `ERROR_INVALID_CREDENTIALS`, `ERROR_PAYLOAD_TOO_LARGE`
-- **Origin + bearer**: `ERROR_FORBIDDEN_ORIGIN`, `ERROR_FORBIDDEN_REFERER`,
+- **Origin + bearer**: `ERROR_FORBIDDEN_ORIGIN`, `ERROR_FORBIDDEN_REFERER` (retained for consumer compat; no longer emitted),
   `ERROR_BEARER_REJECTED_BROWSER`, `ERROR_INVALID_TOKEN`, `ERROR_ACCOUNT_NOT_FOUND`
 - **Keeper/daemon**: `ERROR_INVALID_DAEMON_TOKEN`,
   `ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED`, `ERROR_KEEPER_ACCOUNT_NOT_FOUND`
@@ -415,10 +416,15 @@ connection is from a configured trusted proxy. Without this middleware,
 Must run **before** auth and rate-limiting middleware. See the root
 ../../CLAUDE.md §Middleware Ordering.
 
-- `normalize_ip(ip)` — idempotent: lowercase + strip `::ffff:` prefix on
-  IPv4-mapped IPv6 addresses; safe on non-IP strings (`'unknown'` → `'unknown'`).
-  Subtle: only strips `::ffff:` when the suffix contains `.`, so pure
-  IPv6 like `::ffff:1` is preserved
+- `normalize_ip(ip)` — delegates to `canonicalize_ip` from `ip_canonical.ts`:
+  RFC 5952 IPv6 canonicalization (lowercase hex, longest-zero-run
+  compression), IPv4-mapped IPv6 emitted in dotted form and stripped of
+  the `::ffff:` prefix so the bucket collapses to plain IPv4. Idempotent;
+  safe on non-IP strings (`'unknown'` → `'unknown'`); strict char-set
+  filter (`IP_LITERAL_CHARS`) preserves malformed forms unchanged so
+  downstream `validate_ip_strict` can still reject them. Pure IPv6 like
+  `::ffff:1` (group[5]=0, not 0xffff — NOT IPv4-mapped) stays preserved.
+  Mirrors `zzz_server::proxy::normalize_ip`
 - `ProxyOptions` — `{trusted_proxies, get_connection_ip, log?}`
 - `ParsedProxy` — `{type: 'ip'; address}` or `{type: 'cidr'; network; prefix; address_type}`
 - `parse_proxy_entry(entry)` — accepts `'127.0.0.1'`, `'::1'`,
@@ -461,7 +467,7 @@ distinction in rate limiting and collapse to the proxy's connection
 IP (one bucket for everyone behind that proxy). nginx + cloud LBs
 don't include ports — bounded by operator configuration in practice.
 
-### Origin/Referer allowlist — `origin.ts`
+### Origin allowlist — `origin.ts`
 
 Origin allowlisting for locally-running services — **not** the CSRF
 layer. CSRF is handled by `SameSite: strict` on session cookies (see
@@ -471,9 +477,19 @@ layer. CSRF is handled by `SameSite: strict` on session cookies (see
 - `should_allow_origin(origin, patterns)` — case-insensitive match
 - `verify_request_source(allowed_patterns)` — Hono handler:
   1. `Origin` header present → must match allowlist or 403 `ERROR_FORBIDDEN_ORIGIN`
-  2. No `Origin` + `Referer` present → extract origin, check, 403
-     `ERROR_FORBIDDEN_REFERER` on mismatch
-  3. Neither header → allow through (curl, CLI, token auth is primary control)
+  2. No `Origin` → allow through (curl, CLI, token auth is primary control)
+
+**Origin-only by design.** Fetch spec mandates `Origin` on every unsafe
+method, so a real browser request on any state-changing surface always
+carries it. Non-browser clients (curl, server-to-server, CLI) don't
+ship auto-attached session cookies, so CSRF isn't the relevant threat
+there — auth (bearer / daemon token) is the actual control. A `Referer`
+fallback would only widen the accepted-shape envelope without closing
+a real CSRF hole. Mirrors `zzz_server::auth::is_request_origin_allowed`.
+
+`ERROR_FORBIDDEN_REFERER` stays exported from `error_schemas.ts` for
+consumers whose error-schema unions or test assertions still reference
+it — the emit site is gone, the constant is not.
 
 Pattern syntax:
 

package/dist/http/ip_canonical.d.ts

@@ -0,0 +1,99 @@
+/**
+ * IP address canonicalization — collapse equivalent string forms into a
+ * single key per RFC 5952 (IPv6) plus the dotted form for IPv4-mapped
+ * IPv6 addresses.
+ *
+ * **Why this exists.** Without canonicalization, the four representations
+ * `::1`, `::01`, `::0001`, and `0:0:0:0:0:0:0:1` are the same IPv6 address
+ * but produce four distinct strings — so an attacker rotating
+ * equivalent forms behind a trusted-passthrough proxy could defeat
+ * per-IP rate limiting (each form gets a fresh bucket) and pollute
+ * `audit_log.ip` forensics. The collision can extend to IPv4-mapped
+ * IPv6 forms (`::ffff:127.0.0.1` vs `0:0:0:0:0:ffff:7f00:1` vs the
+ * bare `127.0.0.1`) — three keys for one address.
+ *
+ * Canonicalization runs through {@link canonicalize_ip} which:
+ *
+ * 1. Lowercases and char-set filters (`IP_LITERAL_CHARS`) — non-IP
+ *    strings (`'unknown'`, `'attacker:controlled'`, `'::1\n'`) pass
+ *    through unchanged so downstream strict validators can still
+ *    reject them.
+ * 2. Parses via Hono's `convertIPv*ToBinary` family.
+ * 3. Re-emits the canonical RFC 5952 string (lowercase hex,
+ *    longest-zero-run compressed, IPv4-mapped emitted in the dotted
+ *    form mandated by RFC 5952 §5).
+ * 4. Strips the `::ffff:` prefix from dotted IPv4-mapped forms so the
+ *    bucket collapses to plain IPv4 — the strip moves AFTER
+ *    canonicalization because the dotted form is the only form the
+ *    strip can recognize symmetrically.
+ *
+ * Mirrors `zzz_server::proxy::normalize_ip` (landed 2026-05-16) which
+ * uses the same parse-then-canonicalize-then-strip ordering for the
+ * same rate-limit-key-poisoning surface. See
+ * `~/dev/grimoire/lore/fuz_app/TODO_PROXY.md` §IPv6 String
+ * Canonicalization for the cross-backend parity record.
+ *
+ * @module
+ */
+/**
+ * Allowed character set for a bare IP literal.
+ *
+ * Covers the union of IPv4 (digits + `.`), IPv6 (hex digits + `:`), and
+ * IPv4-mapped IPv6 forms (`::ffff:127.0.0.1`). Anything outside this
+ * set — brackets, whitespace, control bytes, letters g–z — disqualifies
+ * the input from parsing.
+ *
+ * Same regex `proxy.ts`'s `validate_ip_strict` uses; exported here so
+ * both modules can share one source of truth.
+ */
+export declare const IP_LITERAL_CHARS: RegExp;
+/**
+ * Canonicalize an IP address string.
+ *
+ * Returns the RFC 5952 canonical form for parseable IPv4 or IPv6
+ * input. Returns the input unchanged (only lowercased) when the input
+ * is non-IP (`'unknown'`), malformed (`'attacker:controlled'`,
+ * `'::1\n'`), or any string the strict char-set filter rejects.
+ *
+ * **Idempotent.** `canonicalize_ip(canonicalize_ip(x)) === canonicalize_ip(x)`
+ * for every input.
+ *
+ * **Order-safe for IPv4-mapped IPv6.** The `::ffff:` prefix strip
+ * runs AFTER the canonical emit because the canonical form of an
+ * IPv4-mapped IPv6 address is the dotted form (`::ffff:127.0.0.1`,
+ * not `::ffff:7f00:1`). Stripping before canonicalize would miss the
+ * full-hex form. Closes the
+ * `normalize_ipv4_mapped_collapse_is_order_safe` test from the Rust
+ * port.
+ *
+ * @example
+ * canonicalize_ip('::0001')                    // → '::1'
+ * canonicalize_ip('0:0:0:0:0:0:0:1')           // → '::1'
+ * canonicalize_ip('2001:0DB8::0001')           // → '2001:db8::1'
+ * canonicalize_ip('::ffff:127.0.0.1')          // → '127.0.0.1'
+ * canonicalize_ip('0:0:0:0:0:ffff:7f00:1')     // → '127.0.0.1'
+ * canonicalize_ip('::ffff:1')                  // → '::ffff:1' (NOT IPv4-mapped — group[5] is 0, not ffff)
+ * canonicalize_ip('127.0.0.1')                 // → '127.0.0.1'
+ * canonicalize_ip('not-an-ip')                 // → 'not-an-ip' (passes through)
+ * canonicalize_ip('::1\n')                     // → '::1\n' (fails char-set; passes through)
+ * canonicalize_ip('203.0.113.1:8080')          // → '203.0.113.1:8080' (passes through; validate_ip_strict rejects)
+ */
+export declare const canonicalize_ip: (ip: string) => string;
+/**
+ * Convert a 128-bit IPv6 binary value into its RFC 5952 canonical string form.
+ *
+ * - IPv4-mapped (groups[0..5] = 0, groups[5] = 0xffff) emits the
+ *   `::ffff:a.b.c.d` dotted form per RFC 5952 §5.
+ * - Otherwise: lowercase hex with no leading zeros per group (§4.1),
+ *   the longest run of consecutive zero groups (≥ 2 groups) is
+ *   replaced with `::` (§4.2.1, §4.2.3), and on equal-length runs the
+ *   first one wins (§4.2.3). Single-zero groups stay as `0` (§4.2.2).
+ *
+ * Pure helper exported for the test suite to exercise the
+ * canonicalization invariants directly without a full
+ * `convertIPv6ToBinary` round-trip.
+ *
+ * @param bits - the 128-bit IPv6 value as `bigint` (only the low 128 bits are read)
+ */
+export declare const ipv6_bigint_to_canonical: (bits: bigint) => string;
+//# sourceMappingURL=ip_canonical.d.ts.map

package/dist/http/ip_canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAmC5C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MA6DvD,CAAC"}