@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/auth/account_schema.d.ts

@@ -121,6 +121,33 @@ export declare const is_role_grant_active: (p: {
     revoked_at?: string | null;
     expires_at: string | null;
 }, now?: Date) => boolean;
+/**
+ * Whether `role_grants` holds a live global grant of `role` — `scope_id` is
+ * `null` and the grant passes `is_role_grant_active`.
+ *
+ * This is the question a role gate asks. A scoped grant confers its role on
+ * one resource only, and a scoped grant of a builtin role (`admin`, `keeper`)
+ * confers nothing, so matching on the role name alone would read a grant for
+ * one resource as authority everywhere. Server-side the same rule is
+ * `has_scoped_role(ctx, role, null)` over a request context and
+ * `query_account_has_global_role` in SQL; this is the form for a bare list of
+ * grants — `AuthState.role_grants`, an admin listing row.
+ *
+ * The scope match is `scope_id === null`, so a grant decoded without the
+ * field is not read as global. Client-side the answer shapes the UI and
+ * nothing else: the server re-checks every request.
+ *
+ * @param role_grants - the grants to search, e.g. `AuthState.role_grants`
+ * @param role - the role to check
+ * @param now - current time (defaults to `new Date()`, pass for testability)
+ * @returns `true` iff a live grant of `role` with no scope is present
+ */
+export declare const has_global_role: (role_grants: ReadonlyArray<{
+    role: string;
+    scope_id: string | null;
+    revoked_at?: string | null;
+    expires_at: string | null;
+}>, role: string, now?: Date) => boolean;
 /**
  * A session's storage key — the blake3 hash of its raw token, branded so a
  * bare `string` can't stand in for one. `Blake3Hash` (`hash_schemas.ts`) is

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

@@ -1 +1 @@
-{"version":3,"file":"account_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAG9C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAK1D,mEAAmE;AACnE,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,4FAA4F;AAC5F,MAAM,WAAW,KAAK;IACrB,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sEAAsE;IACtE,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,IAAI,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iGAAiG;IACjG,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,sHAAsH;IACtH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,mGAAmG;IACnG,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,GAChC,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC5D,MAAK,IAAiB,KACpB,OACsF,CAAC;AAE1F;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,qDAAgC,CAAC;AACvD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAE1C,6CAA6C;AAC7C,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CACf;AAID,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB;;;;;;kBAM7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,eAAe;;;;;kBAK1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB;;;;;;;;IAQ9B;;;;;OAKG;;kBAEF,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,gFAAgF;AAChF,eAAO,MAAM,oBAAoB;;;;;;;;kBAQ/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB;;;kBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,iGAAiG;AACjG,eAAO,MAAM,gBAAgB;;;;;;;;;kBAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;kBASlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,sGAAsG;AACtG,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAKhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAI1E,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,IAAI,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,OAAO,KAAG,cAMpD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,OAAO,KAAG,gBAKlD,CAAC"}
+{"version":3,"file":"account_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_schema.ts"],"names":[],"mappings":"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"}

package/dist/auth/account_schema.js

@@ -49,6 +49,28 @@ export const ROLE_GRANT_REVOKED_REASON_LENGTH_MAX = 500;
  * @returns `true` when the grant is neither revoked nor expired
  */
 export const is_role_grant_active = (p, now = new Date()) => !p.revoked_at && (!p.expires_at || is_iso8601_seconds_live(p.expires_at, now.getTime()));
+/**
+ * Whether `role_grants` holds a live global grant of `role` — `scope_id` is
+ * `null` and the grant passes `is_role_grant_active`.
+ *
+ * This is the question a role gate asks. A scoped grant confers its role on
+ * one resource only, and a scoped grant of a builtin role (`admin`, `keeper`)
+ * confers nothing, so matching on the role name alone would read a grant for
+ * one resource as authority everywhere. Server-side the same rule is
+ * `has_scoped_role(ctx, role, null)` over a request context and
+ * `query_account_has_global_role` in SQL; this is the form for a bare list of
+ * grants — `AuthState.role_grants`, an admin listing row.
+ *
+ * The scope match is `scope_id === null`, so a grant decoded without the
+ * field is not read as global. Client-side the answer shapes the UI and
+ * nothing else: the server re-checks every request.
+ *
+ * @param role_grants - the grants to search, e.g. `AuthState.role_grants`
+ * @param role - the role to check
+ * @param now - current time (defaults to `new Date()`, pass for testability)
+ * @returns `true` iff a live grant of `role` with no scope is present
+ */
+export const has_global_role = (role_grants, role, now = new Date()) => role_grants.some((p) => p.role === role && p.scope_id === null && is_role_grant_active(p, now));
 /**
  * A session's storage key — the blake3 hash of its raw token, branded so a
  * bare `string` can't stand in for one. `Blake3Hash` (`hash_schemas.ts`) is

package/dist/auth/admin_actions.d.ts

@@ -29,9 +29,8 @@
  * @module
  */
 import { type RpcAction } from '../actions/action_rpc.js';
-import type { ConnectionCloser } from '../actions/connection_closer.js';
 import { type RoleSchemaResult } from './role_schema.js';
-import type { ActionFactoryDeps } from './deps.js';
+import type { RevokingActionFactoryDeps } from './deps.js';
 /** Options for `create_admin_actions`. */
 export interface AdminActionOptions {
     /**
@@ -41,26 +40,18 @@ export interface AdminActionOptions {
      * `admin_account_list`.
      */
     roles?: RoleSchemaResult;
-    /**
-     * Live-connection closer — when set, `admin_session_revoke_all` and
-     * `admin_token_revoke_all` handlers eagerly close affected WebSocket
-     * sockets for the target account BEFORE emitting the corresponding
-     * audit event. Mirrors the self-service surface (see
-     * `AccountActionOptions.connection_closer`). `BackendWebsocketTransport`
-     * satisfies this interface structurally. When absent, only the
-     * listener-based close (`transports_ws_auth_guard`) runs.
-     */
-    connection_closer?: ConnectionCloser | null;
 }
 /**
  * Create the admin-only RPC actions.
  *
- * @param deps - `ActionFactoryDeps` (`log`, `audit`). `log` drives RPC-
- *   internal error logging; `audit.emit` writes audit rows via the captured
- *   pool. The bound emitter encapsulates listener fan-out and the optional
- *   `AuditLogConfig`.
+ * @param deps - `RevokingActionFactoryDeps` (`log`, `audit`,
+ *   `connection_closer`). `log` drives RPC-internal error logging;
+ *   `audit.emit` writes audit rows via the captured pool. The bound emitter
+ *   encapsulates listener fan-out and the optional `AuditLogConfig`.
+ *   `connection_closer` closes the target account's live connections after a
+ *   revoke-all, delete, or purge commits.
  * @param options - role schema for `grantable_roles` derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
  */
-export declare const create_admin_actions: (deps: ActionFactoryDeps, options?: AdminActionOptions) => Array<RpcAction>;
+export declare const create_admin_actions: (deps: RevokingActionFactoryDeps, options?: AdminActionOptions) => Array<RpcAction>;
 //# sourceMappingURL=admin_actions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"admin_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAyC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AA0DnD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,iBAAiB,EACvB,UAAS,kBAAuB,KAC9B,KAAK,CAAC,SAAS,CAyfjB,CAAC"}
+{"version":3,"file":"admin_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG/F,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAyC1B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AA0D3D,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,yBAAyB,EAC/B,UAAS,kBAAuB,KAC9B,KAAK,CAAC,SAAS,CAogBjB,CAAC"}

package/dist/auth/admin_actions.js

@@ -29,6 +29,7 @@
  * @module
  */
 import { rpc_action } from '../actions/action_rpc.js';
+import { queue_connection_close } from '../actions/connection_closer.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
 import { builtin_role_specs_by_name, list_roles_with_grant_path, ROLE_ADMIN, ROLE_KEEPER } from './role_schema.js';
 import { has_scoped_role } from './request_context.js';
@@ -47,17 +48,19 @@ import { admin_account_list_action_spec, admin_session_list_action_spec, admin_s
 /**
  * Create the admin-only RPC actions.
  *
- * @param deps - `ActionFactoryDeps` (`log`, `audit`). `log` drives RPC-
- *   internal error logging; `audit.emit` writes audit rows via the captured
- *   pool. The bound emitter encapsulates listener fan-out and the optional
- *   `AuditLogConfig`.
+ * @param deps - `RevokingActionFactoryDeps` (`log`, `audit`,
+ *   `connection_closer`). `log` drives RPC-internal error logging;
+ *   `audit.emit` writes audit rows via the captured pool. The bound emitter
+ *   encapsulates listener fan-out and the optional `AuditLogConfig`.
+ *   `connection_closer` closes the target account's live connections after a
+ *   revoke-all, delete, or purge commits.
  * @param options - role schema for `grantable_roles` derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
  */
 export const create_admin_actions = (deps, options = {}) => {
     const role_specs = options.roles?.role_specs ?? builtin_role_specs_by_name;
     const grantable_roles = list_roles_with_grant_path(role_specs, GRANT_PATH_ADMIN);
-    const connection_closer = options.connection_closer ?? null;
+    const { connection_closer } = deps;
     const account_list_handler = async (input, ctx) => {
         const accounts = await query_admin_account_list(ctx, {
             limit: input.limit,
@@ -91,15 +94,15 @@ export const create_admin_actions = (deps, options = {}) => {
             throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
         }
         const count = await query_session_revoke_all_for_account(ctx, input.account_id);
-        // Handler-side belt+suspenders — close the target account's live WS
-        // sockets BEFORE the audit emit so revocation lands even if the audit
-        // INSERT fails. Listener-based close (`transports_ws_auth_guard`
-        // registered via `audit.add_listener`) stays as a fail-safe for
-        // out-of-band emit sites. Idempotent — see
+        // Close the target account's live connections once the revoke has
+        // committed — queued, so it never runs before the commit or on
+        // rollback, and it does not depend on the audit write below. Queued at
+        // every `count`, zero included. See
         // `account_actions.ts::session_revoke_handler`.
-        if (connection_closer) {
-            connection_closer.close_sockets_for_account(input.account_id);
-        }
+        queue_connection_close(ctx, connection_closer, {
+            kind: 'account',
+            account_id: input.account_id
+        });
         // TOCTOU window — admin B hard-deletes `input.account_id` between the
         // pre-check above and this emit; the FK rejects the row, the audit
         // emitter logs + swallows, and the operation goes unaudited. Bounded
@@ -138,10 +141,11 @@ export const create_admin_actions = (deps, options = {}) => {
             throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
         }
         const count = await query_revoke_all_api_tokens_for_account(ctx, input.account_id);
-        // Handler-side belt+suspenders — see `session_revoke_all_handler`.
-        if (connection_closer) {
-            connection_closer.close_sockets_for_account(input.account_id);
-        }
+        // Post-commit close — see `session_revoke_all_handler`.
+        queue_connection_close(ctx, connection_closer, {
+            kind: 'account',
+            account_id: input.account_id
+        });
         // TOCTOU window — see `session_revoke_all_handler` for the rationale on
         // keeping `target_account_id` populated rather than switching to the
         // failure-shape.
@@ -314,8 +318,12 @@ export const create_admin_actions = (deps, options = {}) => {
         }
         await query_session_revoke_all_for_account(ctx, target_account_id);
         await query_revoke_all_api_tokens_for_account(ctx, target_account_id);
-        if (connection_closer)
-            connection_closer.close_sockets_for_account(target_account_id);
+        // The tombstone ends every credential of the account; its connections
+        // close once that has committed.
+        queue_connection_close(ctx, connection_closer, {
+            kind: 'account',
+            account_id: target_account_id
+        });
         deps.audit.emit(ctx, {
             event_type: 'account_delete',
             actor_id: auth.actor.id,
@@ -366,8 +374,12 @@ export const create_admin_actions = (deps, options = {}) => {
             });
             throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
         }
-        if (connection_closer)
-            connection_closer.close_sockets_for_account(input.account_id);
+        // The cascade removed every credential of the account; its connections
+        // close once that has committed.
+        queue_connection_close(ctx, connection_closer, {
+            kind: 'account',
+            account_id: input.account_id
+        });
         deps.log.warn(`account hard-purged (irreversible cascading delete): ${input.account_id} by actor ${auth.actor.id}`);
         deps.audit.emit(ctx, {
             event_type: 'account_purge',

package/dist/auth/api_token_queries.d.ts

@@ -47,6 +47,22 @@ export declare const query_create_api_token: (deps: QueryDeps, id: string, accou
  * @mutates `pending_effects` - pushes the in-flight tracking promise when provided
  */
 export declare const query_validate_api_token: (deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Array<Promise<void>> | undefined) => Promise<ApiToken | undefined>;
+/**
+ * Look up the owning account of a live API token — one that still exists and
+ * has not expired — by its public id.
+ *
+ * The by-id counterpart of `query_validate_api_token`, for re-checking a token
+ * that already authenticated (`revalidate_resolved_auth`): no hash, no scope
+ * decode, and no touch of `last_used_at` / `last_used_ip` — a re-check is not
+ * a use. "Live" is the same predicate in both (`API_TOKEN_IS_LIVE`). The scope
+ * document is not re-read: the resolved credential carries the scope it was
+ * admitted with, and nothing rewrites the column after the mint.
+ *
+ * @param deps - query dependencies
+ * @param id - the public token id (e.g. `tok_abc123`)
+ * @returns the owning account id, or `undefined` when the token is gone or expired
+ */
+export declare const query_api_token_live_account: (deps: QueryDeps, id: string) => Promise<string | undefined>;
 /**
  * Revoke all tokens for an account.
  *
@@ -91,11 +107,16 @@ export declare const query_api_token_list_for_account: (deps: QueryDeps, account
  * caveat, as `query_session_enforce_limit` — deterministic survivors under a
  * `created_at` tie, not a guarantee that the row just inserted survives.
  *
+ * Deleting a token row does not end the connections it opened, so the
+ * returned ids are what the caller closes once the transaction commits
+ * (`queue_connection_close` with a `token` target) — `account_token_create`
+ * does.
+ *
  * @param deps - query dependencies (must be transaction-scoped)
  * @param account_id - the account to enforce the limit for
  * @param max_tokens - maximum number of tokens to keep
- * @returns the number of tokens evicted
+ * @returns the evicted tokens' ids, empty when nothing was evicted
  * @mutates `api_token` table - deletes the oldest rows past the cap
  */
-export declare const query_api_token_enforce_limit: (deps: QueryDeps, account_id: string, max_tokens: number) => Promise<number>;
+export declare const query_api_token_enforce_limit: (deps: QueryDeps, account_id: string, max_tokens: number) => Promise<Array<string>>;
 //# sourceMappingURL=api_token_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api_token_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token_queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,KAAK,UAAU,EAAmD,MAAM,kBAAkB,CAAC;AAEpG,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IACnD,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,0HAUoB,CAAC;AAgBnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,EAClB,MAAM,MAAM,EACZ,YAAY,MAAM,EAClB,OAAO,UAAU,EACjB,aAAa,IAAI,GAAG,IAAI,KACtB,OAAO,CAAC,QAAQ,CAelB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,iBAAiB,EACvB,WAAW,MAAM,EACjB,IAAI,MAAM,GAAG,SAAS,EACtB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,KAC/C,OAAO,CAAC,QAAQ,GAAG,SAAS,CAgC9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAM7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAYhB,CAAC"}
+{"version":3,"file":"api_token_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token_queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,KAAK,UAAU,EAAmD,MAAM,kBAAkB,CAAC;AAEpG,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IACnD,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,0HAUoB,CAAC;AA6BnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,EAClB,MAAM,MAAM,EACZ,YAAY,MAAM,EAClB,OAAO,UAAU,EACjB,aAAa,IAAI,GAAG,IAAI,KACtB,OAAO,CAAC,QAAQ,CAelB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,iBAAiB,EACvB,WAAW,MAAM,EACjB,IAAI,MAAM,GAAG,SAAS,EACtB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,KAC/C,OAAO,CAAC,QAAQ,GAAG,SAAS,CAgC9B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,MAAM,GAAG,SAAS,CAM5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAM7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAYvB,CAAC"}

package/dist/auth/api_token_queries.js

@@ -36,6 +36,18 @@ const api_token_expr = iso8601_timestamp_expr(API_TOKEN_COLUMNS, [
     'last_used_at',
     'created_at'
 ])('');
+/**
+ * The `WHERE` fragment that makes an `api_token` row **live**: not expired (an
+ * eternal token has no expiry).
+ *
+ * One definition for every query that decides whether a token authenticates —
+ * the resolve path's `query_validate_api_token` and the re-check's
+ * `query_api_token_live_account` — so a condition added to one is added to
+ * both, and the re-check can never admit a token resolution would refuse. A
+ * new liveness condition (a `revoked_at`, a `disabled` flag) goes here. The
+ * twin of the Rust spine's `API_TOKEN_IS_LIVE`.
+ */
+const API_TOKEN_IS_LIVE = '(expires_at IS NULL OR expires_at > NOW())';
 /**
  * Store a new API token (the hash, not the raw token).
  *
@@ -80,7 +92,7 @@ export const query_validate_api_token = async (deps, raw_token, ip, pending_effe
     const token_hash = hash_api_token(raw_token);
     const row = await deps.db.query_one(`SELECT ${columns_sql(API_TOKEN_COLUMNS, api_token_expr)} FROM api_token
 		 WHERE token_hash = $1
-		   AND (expires_at IS NULL OR expires_at > NOW())`, [token_hash]);
+		   AND ${API_TOKEN_IS_LIVE}`, [token_hash]);
     if (!row)
         return undefined;
     // **Fail-closed on an unreadable scope**: refuse the credential, the same
@@ -104,6 +116,25 @@ export const query_validate_api_token = async (deps, raw_token, ip, pending_effe
     pending_effects?.push(p);
     return row;
 };
+/**
+ * Look up the owning account of a live API token — one that still exists and
+ * has not expired — by its public id.
+ *
+ * The by-id counterpart of `query_validate_api_token`, for re-checking a token
+ * that already authenticated (`revalidate_resolved_auth`): no hash, no scope
+ * decode, and no touch of `last_used_at` / `last_used_ip` — a re-check is not
+ * a use. "Live" is the same predicate in both (`API_TOKEN_IS_LIVE`). The scope
+ * document is not re-read: the resolved credential carries the scope it was
+ * admitted with, and nothing rewrites the column after the mint.
+ *
+ * @param deps - query dependencies
+ * @param id - the public token id (e.g. `tok_abc123`)
+ * @returns the owning account id, or `undefined` when the token is gone or expired
+ */
+export const query_api_token_live_account = async (deps, id) => {
+    const row = await deps.db.query_one(`SELECT account_id FROM api_token WHERE id = $1 AND ${API_TOKEN_IS_LIVE}`, [id]);
+    return row?.account_id;
+};
 /**
  * Revoke all tokens for an account.
  *
@@ -157,10 +188,15 @@ export const query_api_token_list_for_account = async (deps, account_id) => {
  * caveat, as `query_session_enforce_limit` — deterministic survivors under a
  * `created_at` tie, not a guarantee that the row just inserted survives.
  *
+ * Deleting a token row does not end the connections it opened, so the
+ * returned ids are what the caller closes once the transaction commits
+ * (`queue_connection_close` with a `token` target) — `account_token_create`
+ * does.
+ *
  * @param deps - query dependencies (must be transaction-scoped)
  * @param account_id - the account to enforce the limit for
  * @param max_tokens - maximum number of tokens to keep
- * @returns the number of tokens evicted
+ * @returns the evicted tokens' ids, empty when nothing was evicted
  * @mutates `api_token` table - deletes the oldest rows past the cap
  */
 export const query_api_token_enforce_limit = async (deps, account_id, max_tokens) => {
@@ -171,5 +207,5 @@ export const query_api_token_enforce_limit = async (deps, account_id, max_tokens
 		   ORDER BY created_at DESC, id DESC
 		   OFFSET $2
 		 ) RETURNING id`, [account_id, max_tokens]);
-    return rows.length;
+    return rows.map((row) => row.id);
 };

package/dist/auth/audit_emitter.d.ts

@@ -11,7 +11,8 @@
  * 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:
+ * These methods cover every fan-out shape the auth domain needs
+ * (`add_listener` and `listener_count` manage the listener chain):
  *
  * - `emit(ctx, input)` — fire-and-forget pool write. Pushes the in-flight
  *   promise onto `ctx.pending_effects` for post-response flushing. Errors are
@@ -22,49 +23,71 @@
  *   `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.
+ *   request context (ad-hoc maintenance scripts). Writes, then notifies.
  * - `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 registered listener; per-listener throws
- *   are isolated.
+ *   the query layer, or the offer-expiry rows `auth/cleanup.ts` writes in
+ *   its sweep transaction). Runs every registered listener; per-listener
+ *   throws are isolated.
+ *
+ * ## When listeners hear about a row
+ *
+ * `emit` writes the row at once, on the pool, whatever its outcome — the write
+ * is outside the request's transaction, so it survives a rollback. Listener
+ * fan-out is a separate step, and it depends on the outcome:
+ *
+ * - A **failure** row is announced as soon as it is written. It records an
+ *   attempt, which happened whether or not the request's transaction commits.
+ * - A **success** row is announced only after the request's transaction
+ *   commits, and never when the handler throws: the fan-out is queued on
+ *   `ctx.post_commit_effects` and awaits the write. A success row reports a
+ *   state change, and the listeners act on it — the revocation listeners close
+ *   connections, the audit stream broadcasts it. Announced before the commit,
+ *   a close could run while the revoked credential still reads as valid, and a
+ *   rolled-back revocation would close connections anyway.
+ *
+ * A success row emitted by a handler that later throws is still in the table —
+ * the write is outside the transaction — but is never announced.
+ *
+ * The Rust spine reaches the same order by writing a success row inside the
+ * transaction and queueing its fan-out behind the commit.
  *
  * Listeners are a documented registration seam — `create_app_server`
  * registers additional listeners via `add_listener` 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 register listeners directly on
- * the emitter they return from `audit_factory` for setups that don't pass
- * through `create_app_server`.
+ * built (the factory-managed audit-log SSE, per-endpoint WS auth guards, any
+ * `extra_audit_handlers` on a `WsEndpointSpec`) before the first request
+ * runs. Consumers can also register listeners directly on the emitter they
+ * return from `audit_factory` for setups that don't pass through
+ * `create_app_server`.
  *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { Uuid } from '@fuzdev/fuz_util/id.ts';
 import type { Db } from '../db/db.js';
+import { type EmitAfterCommitContext } from '../http/pending_effects.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.
+ * Per-request context required by `AuditEmitter.emit` — the request's two
+ * side-effect queues. The bound emitter carries its own `log` reference
+ * inside the closure, so per-call contexts don't need one.
+ *
+ * The write is eager: the bound emitter fires the pool write immediately and
+ * pushes the in-flight `Promise<void>` onto `pending_effects`. Deferring it
+ * would only delay forensic visibility, since a pool-routed write is already
+ * rollback-resilient. A success row's listener fan-out goes on
+ * `post_commit_effects` instead (module doc, "When listeners hear about a
+ * row").
  *
- * Audit emits are eager by default: the bound emitter fires the
- * pool write immediately and pushes the in-flight `Promise<void>` here.
- * Attempt/failure audits never go through `emit_after_commit` —
- * pool-routed writes are already rollback-resilient because they run
- * outside the request transaction, so deferring them would only delay
- * forensic visibility without any safety benefit. The exception is a
- * **success-only** event paired with a state mutation (the
- * `db_admin_row_delete` emit in `http/db_routes.ts`): there the caller
- * wraps the emit in `emit_after_commit` so the trail can't claim a
- * mutation whose transaction failed at COMMIT.
+ * One success-only event also defers its *write*: the `db_admin_row_delete`
+ * emit in `http/db_routes.ts` wraps the whole emit in `emit_after_commit`, so
+ * the trail can't claim a mutation whose transaction failed at COMMIT.
  *
  * Both `RouteContext` and `ActionContext` structurally satisfy this
- * shape (they each carry `pending_effects`), so handlers pass `route`
- * / `ctx` directly.
+ * shape, so handlers pass `route` / `ctx` directly.
  */
-export interface AuditEmitterContext {
+export interface AuditEmitterContext extends EmitAfterCommitContext {
     pending_effects: Array<Promise<void>>;
 }
 /**
@@ -87,8 +110,10 @@ export interface AuditEmitter {
      *
      * 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`).
+     * Errors are logged, never thrown. A written row fans out to every
+     * listener on the chain (`notify`): a failure row as soon as it is
+     * written, a success row from `ctx.post_commit_effects` — after the
+     * request's transaction commits, and never when the handler throws.
      *
      * Returns `void` deliberately — the in-flight promise is already on
      * `ctx.pending_effects`, and exposing it would tempt callers to `await`
@@ -98,6 +123,7 @@ export interface AuditEmitter {
      *
      * @mutates `audit_log` table - inserts the row via the captured pool
      * @mutates `ctx.pending_effects` - appends the in-flight settled promise
+     * @mutates `ctx.post_commit_effects` - appends a success row's listener fan-out
      */
     emit<T extends string>(ctx: AuditEmitterContext, input: AuditLogInput<T>): void;
     /**
@@ -116,13 +142,18 @@ export interface AuditEmitter {
         outcome?: 'success' | 'failure';
     }): void;
     /**
-     * Awaitable pool write for code paths without a `pending_effects` queue.
+     * Awaitable pool write for code paths without a request context.
+     *
+     * Writes, then notifies the listeners, whatever the outcome — there is no
+     * request transaction to order the fan-out against. Errors are logged and
+     * swallowed (resolved void), so callers can sequence writes with
+     * `await audit.emit_pool(...)` without try/catch boilerplate.
      *
-     * 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.
+     * Not for a success audit paired with a state mutation: the pool write
+     * can't roll back with the state, and a swallowed error leaves the
+     * mutation unaudited. Write those in the mutation's transaction
+     * (`query_audit_log` against the tx) and `notify` after the commit — the
+     * shape `auth/cleanup.ts`'s offer sweep and `query_accept_offer` use.
      *
      * @mutates `audit_log` table - inserts the row via the captured pool
      */
@@ -138,11 +169,11 @@ export interface AuditEmitter {
     notify(event: AuditLogEvent): void;
     /**
      * Register an audit-event listener. Append-only — listeners fire in
-     * registration order on every successful `emit` / `emit_pool` and on
+     * registration order for every row `emit` / `emit_pool` wrote and on
      * every `notify`.
      *
      * `create_app_server` registers the factory-managed audit-log SSE
-     * listener and per-endpoint WS auth guards / logout closers here so
+     * listener and per-endpoint WS auth guards here so
      * SSE + WS fan-out compose on top of the consumer's `on_audit_event`
      * callback without shallow-copying `AppDeps`. Consumers can also
      * register listeners directly for setups that don't run through
@@ -164,15 +195,13 @@ export type AuditEmitFn = <T extends string>(ctx: AuditEmitterContext, input: Au
 /**
  * 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.
+ * uses this to record `emit` invocations against external markers on a
+ * frozen emitter, whose slots can't be patched after construction.
  *
  * 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.
+ * the wrap — the decorator 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`. */
@@ -198,8 +227,7 @@ export interface CreateAuditEmitterOptions {
      * 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`.
+     * Leave unset in production — it is a test instrumentation seam.
      */
     emit_decorator?: EmitDecorator;
 }

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;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;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,+EAA+E;IAC/E,cAAc,IAAI,MAAM,CAAC;CACzB;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,YAuFzE,CAAC"}
+{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAqB,KAAK,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IAClE,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;;;;;;;;;;;;;;;;;;;OAmBG;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;;;;;;;;;;;;;;;OAeG;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;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,+EAA+E;IAC/E,cAAc,IAAI,MAAM,CAAC;CACzB;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;;;;;;;;;;GAUG;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;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YA4GzE,CAAC"}