@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/auth/deps.d.ts

@@ -13,6 +13,7 @@ import type { Keyring } from './keyring.js';
 import type { PasswordHashDeps } from './password.js';
 import type { Db } from '../db/db.js';
 import type { AuditEmitter } from './audit_emitter.js';
+import type { ConnectionCloser, RealtimeCloser } from '../actions/connection_closer.js';
 /**
  * Stateless capabilities bundle for fuz_app backends.
  *
@@ -24,7 +25,7 @@ export interface AppDeps {
      * Hardened secret-file read — used for the bootstrap token (the file that
      * mints the keeper account). Production wiring passes the runtime's
      * `read_secure_file` (`FsSecureReadDeps`), which rejects symlinks,
-     * group/other-accessible modes, and oversized files; both the boot-time
+     * non-regular files, group/other-accessible modes, and oversized files; both the boot-time
      * availability probe and the request-time read go through this one
      * capability so the probe can never be laxer than the read it gates.
      */
@@ -47,6 +48,16 @@ export interface AppDeps {
      * context.
      */
     audit: AuditEmitter;
+    /**
+     * Closes live connections — WebSocket and SSE — when a credential is
+     * revoked. Every revocation handler queues its close on this
+     * (`queue_connection_close`), so it must reach every transport of the
+     * backend: `create_app_backend` creates it empty, and `create_app_server`
+     * adds each WebSocket transport it mounts and its audit stream registry. A
+     * transport mounted by hand is added through the `connection_closer`
+     * option of `register_ws_endpoint` / `create_audit_log_sse`.
+     */
+    connection_closer: RealtimeCloser;
     /**
      * Optional content-addressed byte store. Present only on backends that
      * serve binary content (facts) — minimal consumers leave it unset. The
@@ -78,4 +89,21 @@ export interface ActionFactoryDeps {
     /** Bound audit emitter for fire-and-forget audit writes. */
     audit: AuditEmitter;
 }
+/**
+ * Capabilities for the action factories whose handlers end credentials —
+ * `create_account_actions`, `create_admin_actions`, and the
+ * `create_standard_rpc_actions` bundle over them. `ActionFactoryDeps` plus
+ * the closer their revocations close live connections through. `AppDeps`
+ * and `RouteFactoryDeps` satisfy it structurally.
+ */
+export interface RevokingActionFactoryDeps extends ActionFactoryDeps {
+    /**
+     * Closes the live connections of a revoked credential, after the
+     * revocation commits. Required rather than optional: a revocation that
+     * closes nothing leaves an open WebSocket or SSE stream running on a dead
+     * credential. A backend with no live-connection surface passes
+     * `noop_connection_closer`.
+     */
+    connection_closer: ConnectionCloser;
+}
 //# sourceMappingURL=deps.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yBAAyB;IACzB,EAAE,EAAE,EAAE,CAAC;IACP,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,YAAY,CAAC;CACpB"}
+{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yBAAyB;IACzB,EAAE,EAAE,EAAE,CAAC;IACP,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;;;OAQG;IACH,iBAAiB,EAAE,cAAc,CAAC;IAClC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IACnE;;;;;;OAMG;IACH,iBAAiB,EAAE,gBAAgB,CAAC;CACpC"}

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

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA+BH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA6K5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA+BH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA0M5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -237,6 +237,33 @@ export const auth_migrations = [
         up: async (db) => {
             await db.query('ALTER TABLE auth_session DROP COLUMN IF EXISTS last_seen_at');
         }
+    },
+    // The expiry-audit stamp that makes the offer sweep idempotent.
+    //
+    // An expired pending offer has no terminal state — expiry is computed from
+    // `expires_at`, never written — so without a stamp every
+    // `cleanup_expired_role_grant_offers` run re-audited every expired offer.
+    // The sweep now claims rows by setting `expire_audited_at` in the same
+    // transaction as their `role_grant_offer_expire` audit rows, so each expiry
+    // is audited exactly once and concurrent sweeps claim disjoint rows.
+    //
+    // Not a lifecycle state: the column stays out of the
+    // `role_grant_offer_single_terminal` CHECK and the pending predicate, and
+    // off the wire. A re-offer of a stamped row clears it (the create upsert),
+    // so the refreshed offer's own expiry is audited too. The partial index
+    // serves exactly the sweep's claim predicate.
+    {
+        name: 'role_grant_offer_expire_audited_at',
+        up: async (db) => {
+            await db.query('ALTER TABLE role_grant_offer ADD COLUMN IF NOT EXISTS expire_audited_at TIMESTAMPTZ NULL');
+            await db.query(`CREATE INDEX IF NOT EXISTS role_grant_offer_expire_sweep
+  ON role_grant_offer (expires_at)
+  WHERE accepted_at IS NULL
+    AND declined_at IS NULL
+    AND retracted_at IS NULL
+    AND superseded_at IS NULL
+    AND expire_audited_at IS NULL`);
+        }
     }
 ];
 /** Pre-composed migration namespace for auth tables. */

package/dist/auth/resolved_auth.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The account-grain credential a request resolved to, and the re-check a
+ * long-lived connection runs on it once it is registered.
+ *
+ * The auth middleware chain (daemon token → session cookie → bearer) resolves a
+ * credential and leaves it on the Hono context as separate keys.
+ * `ResolvedAuth` is that credential gathered into one value
+ * (`get_resolved_auth`), so the connections that outlive their request — a
+ * WebSocket, an SSE stream — can carry it past the handshake and re-read it
+ * with `revalidate_resolved_auth`.
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import type { QueryDeps } from '../db/query_deps.js';
+import { type CredentialType } from '../hono_context.js';
+/**
+ * An authenticated request's credential, account-grain — no actor.
+ *
+ * `token_hash` is set for a session, `api_token_id` for an API token, and both
+ * are `null` for a daemon token. The twin of the Rust spine's `ResolvedAuth`,
+ * which carries the account row and token scope as well; here those stay on
+ * the Hono context.
+ */
+export interface ResolvedAuth {
+    /** The authenticated account. */
+    account_id: string;
+    /** How the request was authenticated. */
+    credential_type: CredentialType;
+    /** Blake3 hash of the session token, or `null` for non-session credentials. */
+    token_hash: string | null;
+    /** `api_token.id` for a bearer credential, else `null`. */
+    api_token_id: string | null;
+}
+/**
+ * Gather the credential the auth middleware resolved for this request.
+ *
+ * Reads the keys the session, bearer, and daemon-token middleware set and
+ * keeps only the one that belongs to the winning credential type — a daemon
+ * token overrides a session cookie sent alongside it without clearing that
+ * session's hash, so the hash is carried for a session credential alone.
+ *
+ * @param c - the request context, after the auth middleware chain
+ * @returns the resolved credential, or `null` for an unauthenticated request
+ */
+export declare const get_resolved_auth: (c: Context) => ResolvedAuth | null;
+/**
+ * Re-check that a resolved credential still authenticates: `true` when it
+ * does, `false` when it has been revoked, has expired, or its account is gone.
+ *
+ * For a connection that outlives its request — a WebSocket, an SSE stream —
+ * and is authorized once, at open. Such a connection is closed on revocation
+ * by identity, but only once it is *registered*; between the credential read
+ * and the registration a revocation closes nothing. So the opener registers
+ * first (un-admitted — `BackendWebsocketTransport.register_pending` /
+ * `SubscriberRegistry.subscribe_pending`), then calls this, then admits. A
+ * revocation that committed before this read is seen by it; one whose close
+ * ran after the registration found the pending entry.
+ *
+ * That needs each statement here to see everything committed before it
+ * started, so `deps.db` must be the pool-level `Db` (autocommit) or a
+ * `READ COMMITTED` transaction — never a `REPEATABLE READ` / `SERIALIZABLE`
+ * transaction opened before the registration, whose snapshot would predate
+ * it.
+ *
+ * What is re-read, per credential — each through the same predicate the
+ * resolve path used, so the two cannot disagree about what "valid" means (the
+ * session and account legs call the middleware's own queries; the token leg
+ * shares its `WHERE` fragment):
+ *
+ * - **Session** — the `auth_session` row still exists, is unexpired, and
+ *   belongs to the resolved account.
+ * - **API token** — the `api_token` row still exists, is unexpired, and
+ *   belongs to the resolved account (by id; the raw token is not kept).
+ * - **Daemon token** — nothing of its own. The token has no row, and no
+ *   revocation event: rotation closes no connection, so there is no close an
+ *   opening connection could have missed. Its keeper account is still
+ *   re-read.
+ * - **Every credential** — the account row still exists and is not
+ *   soft-deleted.
+ *
+ * It re-checks the **credential**, not what a revocation chose to close: a
+ * `logout` closes every connection of the account but deletes only its own
+ * session, so another session's connection opening concurrently passes this
+ * check and is refused only if that account-wide close found its pending
+ * registration — the same two outcomes an already-open connection has.
+ *
+ * **No side effects.** Unlike the bearer middleware this never touches
+ * `api_token.last_used_at` / `last_used_ip` — re-checking a credential is not
+ * using it — and it writes nothing else.
+ *
+ * A `ResolvedAuth` whose credential type lacks its own key (a session with no
+ * `token_hash`, a bearer with no `api_token_id`) is a shape the middleware
+ * never builds; it is answered `false`.
+ *
+ * The twin of the Rust spine's `revalidate_resolved_auth`.
+ *
+ * @param deps - query dependencies; the pool-level `Db`, not a snapshot transaction
+ * @param resolved - the credential the request authenticated with
+ * @returns whether the credential still authenticates
+ * @throws Error propagated from the database. The caller must fail closed — an
+ *   unchecked credential is not a valid one.
+ */
+export declare const revalidate_resolved_auth: (deps: QueryDeps, resolved: ResolvedAuth) => Promise<boolean>;
+//# sourceMappingURL=resolved_auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolved_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/resolved_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,oBAAoB,CAAC;AAM5B;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,eAAe,EAAE,cAAc,CAAC;IAChC,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2DAA2D;IAC3D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,OAAO,KAAG,YAAY,GAAG,IAU7D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,YAAY,KACpB,OAAO,CAAC,OAAO,CAsBjB,CAAC"}

package/dist/auth/resolved_auth.js

@@ -0,0 +1,124 @@
+/**
+ * The account-grain credential a request resolved to, and the re-check a
+ * long-lived connection runs on it once it is registered.
+ *
+ * The auth middleware chain (daemon token → session cookie → bearer) resolves a
+ * credential and leaves it on the Hono context as separate keys.
+ * `ResolvedAuth` is that credential gathered into one value
+ * (`get_resolved_auth`), so the connections that outlive their request — a
+ * WebSocket, an SSE stream — can carry it past the handshake and re-read it
+ * with `revalidate_resolved_auth`.
+ *
+ * @module
+ */
+import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { query_account_by_id } from './account_queries.js';
+import { query_api_token_live_account } from './api_token_queries.js';
+import { AUTH_SESSION_TOKEN_HASH_KEY } from './request_context.js';
+import { query_session_get_valid } from './session_queries.js';
+/**
+ * Gather the credential the auth middleware resolved for this request.
+ *
+ * Reads the keys the session, bearer, and daemon-token middleware set and
+ * keeps only the one that belongs to the winning credential type — a daemon
+ * token overrides a session cookie sent alongside it without clearing that
+ * session's hash, so the hash is carried for a session credential alone.
+ *
+ * @param c - the request context, after the auth middleware chain
+ * @returns the resolved credential, or `null` for an unauthenticated request
+ */
+export const get_resolved_auth = (c) => {
+    const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
+    const credential_type = c.get(CREDENTIAL_TYPE_KEY) ?? null;
+    if (account_id === null || credential_type === null)
+        return null;
+    return {
+        account_id,
+        credential_type,
+        token_hash: credential_type === 'session' ? (c.get(AUTH_SESSION_TOKEN_HASH_KEY) ?? null) : null,
+        api_token_id: credential_type === 'api_token' ? (c.get(AUTH_API_TOKEN_ID_KEY) ?? null) : null
+    };
+};
+/**
+ * Re-check that a resolved credential still authenticates: `true` when it
+ * does, `false` when it has been revoked, has expired, or its account is gone.
+ *
+ * For a connection that outlives its request — a WebSocket, an SSE stream —
+ * and is authorized once, at open. Such a connection is closed on revocation
+ * by identity, but only once it is *registered*; between the credential read
+ * and the registration a revocation closes nothing. So the opener registers
+ * first (un-admitted — `BackendWebsocketTransport.register_pending` /
+ * `SubscriberRegistry.subscribe_pending`), then calls this, then admits. A
+ * revocation that committed before this read is seen by it; one whose close
+ * ran after the registration found the pending entry.
+ *
+ * That needs each statement here to see everything committed before it
+ * started, so `deps.db` must be the pool-level `Db` (autocommit) or a
+ * `READ COMMITTED` transaction — never a `REPEATABLE READ` / `SERIALIZABLE`
+ * transaction opened before the registration, whose snapshot would predate
+ * it.
+ *
+ * What is re-read, per credential — each through the same predicate the
+ * resolve path used, so the two cannot disagree about what "valid" means (the
+ * session and account legs call the middleware's own queries; the token leg
+ * shares its `WHERE` fragment):
+ *
+ * - **Session** — the `auth_session` row still exists, is unexpired, and
+ *   belongs to the resolved account.
+ * - **API token** — the `api_token` row still exists, is unexpired, and
+ *   belongs to the resolved account (by id; the raw token is not kept).
+ * - **Daemon token** — nothing of its own. The token has no row, and no
+ *   revocation event: rotation closes no connection, so there is no close an
+ *   opening connection could have missed. Its keeper account is still
+ *   re-read.
+ * - **Every credential** — the account row still exists and is not
+ *   soft-deleted.
+ *
+ * It re-checks the **credential**, not what a revocation chose to close: a
+ * `logout` closes every connection of the account but deletes only its own
+ * session, so another session's connection opening concurrently passes this
+ * check and is refused only if that account-wide close found its pending
+ * registration — the same two outcomes an already-open connection has.
+ *
+ * **No side effects.** Unlike the bearer middleware this never touches
+ * `api_token.last_used_at` / `last_used_ip` — re-checking a credential is not
+ * using it — and it writes nothing else.
+ *
+ * A `ResolvedAuth` whose credential type lacks its own key (a session with no
+ * `token_hash`, a bearer with no `api_token_id`) is a shape the middleware
+ * never builds; it is answered `false`.
+ *
+ * The twin of the Rust spine's `revalidate_resolved_auth`.
+ *
+ * @param deps - query dependencies; the pool-level `Db`, not a snapshot transaction
+ * @param resolved - the credential the request authenticated with
+ * @returns whether the credential still authenticates
+ * @throws Error propagated from the database. The caller must fail closed — an
+ *   unchecked credential is not a valid one.
+ */
+export const revalidate_resolved_auth = async (deps, resolved) => {
+    const { account_id } = resolved;
+    let credential_is_live;
+    switch (resolved.credential_type) {
+        case 'session': {
+            if (resolved.token_hash === null)
+                return false;
+            const session = await query_session_get_valid(deps, resolved.token_hash);
+            credential_is_live = session?.account_id === account_id;
+            break;
+        }
+        case 'api_token': {
+            if (resolved.api_token_id === null)
+                return false;
+            const owner = await query_api_token_live_account(deps, resolved.api_token_id);
+            credential_is_live = owner === account_id;
+            break;
+        }
+        case 'daemon_token':
+            credential_is_live = true;
+            break;
+    }
+    if (!credential_is_live)
+        return false;
+    return (await query_account_by_id(deps, account_id)) !== undefined;
+};

package/dist/auth/role_grant_offer_ddl.d.ts

@@ -27,13 +27,15 @@ export declare const ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN = "GLOBAL";
  * The full `role_grant_offer` column set, named explicitly so a row read
  * fails loud on schema drift (see `ACCOUNT_COLUMNS` in
  * `auth/account_queries.ts` for the outage class). Column order follows
- * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below.
+ * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below, with
+ * `expire_audited_at` last — the appended `role_grant_offer_expire_audited_at`
+ * migration adds it after the frozen `CREATE TABLE`.
  *
  * Lives here rather than in `auth/role_grant_offer_queries.ts` because two
  * query modules project this table — see the placement rule in
  * `db/sql_columns.ts`.
  */
-export declare const ROLE_GRANT_OFFER_COLUMNS: readonly ["id", "from_actor_id", "to_account_id", "to_actor_id", "role", "scope_kind", "scope_id", "message", "created_at", "expires_at", "accepted_at", "declined_at", "decline_reason", "retracted_at", "superseded_at", "resulting_role_grant_id"];
+export declare const ROLE_GRANT_OFFER_COLUMNS: readonly ["id", "from_actor_id", "to_account_id", "to_actor_id", "role", "scope_kind", "scope_id", "message", "created_at", "expires_at", "accepted_at", "declined_at", "decline_reason", "retracted_at", "superseded_at", "resulting_role_grant_id", "expire_audited_at"];
 /**
  * The `role_grant_offer` timestamp override, by row qualifier (`''` bare,
  * `o` for the history JOIN, `u` for the `updated` CTE's outer select). Lives

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

@@ -1 +1 @@
-{"version":3,"file":"role_grant_offer_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,mHAAmH;AACnH,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,WAAW,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,uPAiBmB,CAAC;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,8DAOhC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,QAMI,CAAC;AAEtD,eAAO,MAAM,uBAAuB,qzCAkClC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,2XAYpB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,kOAMX,CAAC"}
+{"version":3,"file":"role_grant_offer_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,mHAAmH;AACnH,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,WAAW,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,4QAkBmB,CAAC;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,8DAQhC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,QAMI,CAAC;AAKtD,eAAO,MAAM,uBAAuB,qzCAkClC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,2XAYpB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,kOAMX,CAAC"}

package/dist/auth/role_grant_offer_ddl.js

@@ -28,7 +28,9 @@ export const ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN = 'GLOBAL';
  * The full `role_grant_offer` column set, named explicitly so a row read
  * fails loud on schema drift (see `ACCOUNT_COLUMNS` in
  * `auth/account_queries.ts` for the outage class). Column order follows
- * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below.
+ * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below, with
+ * `expire_audited_at` last — the appended `role_grant_offer_expire_audited_at`
+ * migration adds it after the frozen `CREATE TABLE`.
  *
  * Lives here rather than in `auth/role_grant_offer_queries.ts` because two
  * query modules project this table — see the placement rule in
@@ -50,7 +52,8 @@ export const ROLE_GRANT_OFFER_COLUMNS = [
     'decline_reason',
     'retracted_at',
     'superseded_at',
-    'resulting_role_grant_id'
+    'resulting_role_grant_id',
+    'expire_audited_at'
 ];
 /**
  * The `role_grant_offer` timestamp override, by row qualifier (`''` bare,
@@ -68,7 +71,8 @@ export const role_grant_offer_expr = iso8601_timestamp_expr(ROLE_GRANT_OFFER_COL
     'accepted_at',
     'declined_at',
     'retracted_at',
-    'superseded_at'
+    'superseded_at',
+    'expire_audited_at'
 ]);
 /**
  * Outer `SELECT` over an `updated` CTE of `role_grant_offer` rows, joining
@@ -81,6 +85,9 @@ export const role_grant_offer_expr = iso8601_timestamp_expr(ROLE_GRANT_OFFER_COL
 export const ROLE_GRANT_OFFER_WITH_GRANTOR_SELECT = `SELECT ${qualify_columns(ROLE_GRANT_OFFER_COLUMNS, 'u', role_grant_offer_expr('u'))}, grantor.account_id AS from_account_id
 		FROM updated u
 		JOIN actor grantor ON grantor.id = u.from_actor_id`;
+// Frozen v1 body — `expire_audited_at` is added by the appended
+// `role_grant_offer_expire_audited_at` migration (with its partial sweep
+// index), so a fresh bootstrap and an old deployed DB converge on one shape.
 export const ROLE_GRANT_OFFER_SCHEMA = `
 CREATE TABLE IF NOT EXISTS role_grant_offer (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

package/dist/auth/role_grant_offer_queries.d.ts

@@ -112,7 +112,9 @@ export declare class RoleGrantOfferActorAccountMismatchError extends Error {
  * `(to_account, role, scope)` while pending upserts the existing row,
  * refreshing `message` and `expires_at` (and `to_actor_id` — supplying
  * a different `to_actor_id` on re-offer narrows the existing row to the
- * named actor; supplying null widens it back to account-grain). A
+ * named actor; supplying null widens it back to account-grain) and clearing
+ * `expire_audited_at`, so a re-offer of an expired, already-audited row gets
+ * its own `role_grant_offer_expire` when the refreshed expiry passes. A
  * different grantor offering the same `(to_account, role, scope)` creates
  * a distinct row — multiple pending grantors coexist. After a terminal
  * state, a re-offer is a fresh INSERT.
@@ -176,7 +178,7 @@ export declare const query_role_grant_offer_retract: (deps: QueryDeps, offer_id:
  *
  * Expired offers are filtered server-side (`expires_at > NOW()`) so the
  * inbox never surfaces a row that can no longer be accepted. The periodic
- * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) audits each expiry once.
  */
 export declare const query_role_grant_offer_list: (deps: QueryDeps, to_account_id: string) => Promise<Array<RoleGrantOffer>>;
 /**
@@ -191,12 +193,19 @@ export declare const query_role_grant_offer_history_for_account: (deps: QueryDep
  */
 export declare const query_role_grant_offer_find_pending: (deps: QueryDeps, offer_id: string) => Promise<RoleGrantOffer | null>;
 /**
- * Return pending offers whose `expires_at` has passed.
+ * Claim the pending offers whose `expires_at` has passed and whose expiry has
+ * not been audited yet, stamping `expire_audited_at` on each, and return them
+ * soonest-expiry first.
  *
- * Callers fire `role_grant_offer_expire` audit events for each row. The schema
- * does not tombstone the row, so callers are responsible for their own
- * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
- * already exists for the offer id).
+ * The stamp is the sweep's idempotency: a claimed row never matches again, so
+ * each expiry is audited exactly once. It must share a transaction with the
+ * caller's `role_grant_offer_expire` audit inserts — committed together, or
+ * rolled back together so the next sweep retries. Concurrent sweeps claim
+ * disjoint rows: a row another sweep has stamped but not committed blocks on
+ * its row lock, then fails the re-checked `expire_audited_at IS NULL`.
+ * `cleanup_expired_role_grant_offers` is the caller.
+ *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each claimed row
  */
 export declare const query_role_grant_offer_sweep_expired: (deps: QueryDeps) => Promise<Array<RoleGrantOffer>>;
 /** Input for `query_accept_offer`. */

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

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

package/dist/auth/role_grant_offer_queries.js

@@ -118,7 +118,9 @@ export class RoleGrantOfferActorAccountMismatchError extends Error {
  * `(to_account, role, scope)` while pending upserts the existing row,
  * refreshing `message` and `expires_at` (and `to_actor_id` — supplying
  * a different `to_actor_id` on re-offer narrows the existing row to the
- * named actor; supplying null widens it back to account-grain). A
+ * named actor; supplying null widens it back to account-grain) and clearing
+ * `expire_audited_at`, so a re-offer of an expired, already-audited row gets
+ * its own `role_grant_offer_expire` when the refreshed expiry passes. A
  * different grantor offering the same `(to_account, role, scope)` creates
  * a distinct row — multiple pending grantors coexist. After a terminal
  * state, a re-offer is a fresh INSERT.
@@ -170,7 +172,8 @@ export const query_role_grant_offer_create = async (deps, input) => {
 		 DO UPDATE SET
 			 to_actor_id = EXCLUDED.to_actor_id,
 			 message = EXCLUDED.message,
-			 expires_at = EXCLUDED.expires_at
+			 expires_at = EXCLUDED.expires_at,
+			 expire_audited_at = NULL
 		 RETURNING ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))}`, [
         input.from_actor_id,
         input.to_account_id,
@@ -269,7 +272,7 @@ const resolve_terminal_or_missing = async (deps, offer_id, scope) => {
  *
  * Expired offers are filtered server-side (`expires_at > NOW()`) so the
  * inbox never surfaces a row that can no longer be accepted. The periodic
- * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) audits each expiry once.
  */
 export const query_role_grant_offer_list = async (deps, to_account_id) => {
     return deps.db.query(`SELECT ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))} FROM role_grant_offer
@@ -308,21 +311,36 @@ export const query_role_grant_offer_find_pending = async (deps, offer_id) => {
     return row ?? null;
 };
 /**
- * Return pending offers whose `expires_at` has passed.
+ * Claim the pending offers whose `expires_at` has passed and whose expiry has
+ * not been audited yet, stamping `expire_audited_at` on each, and return them
+ * soonest-expiry first.
  *
- * Callers fire `role_grant_offer_expire` audit events for each row. The schema
- * does not tombstone the row, so callers are responsible for their own
- * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
- * already exists for the offer id).
+ * The stamp is the sweep's idempotency: a claimed row never matches again, so
+ * each expiry is audited exactly once. It must share a transaction with the
+ * caller's `role_grant_offer_expire` audit inserts — committed together, or
+ * rolled back together so the next sweep retries. Concurrent sweeps claim
+ * disjoint rows: a row another sweep has stamped but not committed blocks on
+ * its row lock, then fails the re-checked `expire_audited_at IS NULL`.
+ * `cleanup_expired_role_grant_offers` is the caller.
+ *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each claimed row
  */
 export const query_role_grant_offer_sweep_expired = async (deps) => {
-    return deps.db.query(`SELECT ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))} FROM role_grant_offer
-		 WHERE accepted_at IS NULL
-		   AND declined_at IS NULL
-		   AND retracted_at IS NULL
-		   AND superseded_at IS NULL
-		   AND expires_at <= NOW()
-		 ORDER BY role_grant_offer.expires_at ASC`);
+    return deps.db.query(`WITH claimed AS (
+			UPDATE role_grant_offer
+			SET expire_audited_at = NOW()
+			WHERE accepted_at IS NULL
+			  AND declined_at IS NULL
+			  AND retracted_at IS NULL
+			  AND superseded_at IS NULL
+			  AND expires_at <= NOW()
+			  AND expire_audited_at IS NULL
+			-- raw columns; the outer select formats them
+			RETURNING ${columns_sql(ROLE_GRANT_OFFER_COLUMNS)}
+		)
+		SELECT ${qualify_columns(ROLE_GRANT_OFFER_COLUMNS, 'c', role_grant_offer_expr('c'))}
+		FROM claimed c
+		ORDER BY c.expires_at ASC, c.id ASC`);
 };
 /**
  * Whether `grantor_actor_id` holds an active **global** `admin` on an active

package/dist/auth/role_grant_offer_schema.d.ts

@@ -60,6 +60,15 @@ export interface RoleGrantOffer {
      */
     superseded_at: string | null;
     resulting_role_grant_id: Uuid | null;
+    /**
+     * When the expiry sweep audited this offer's `role_grant_offer_expire` —
+     * the claim stamp `query_role_grant_offer_sweep_expired` sets in the same
+     * transaction as the audit row, so each expiry is audited once. Not a
+     * lifecycle state (an expired offer is still pending by the terminal
+     * columns) and server-only: `to_role_grant_offer_json` drops it, and the
+     * strict `RoleGrantOfferJson` would reject it. A re-offer clears it.
+     */
+    expire_audited_at: string | null;
 }
 /**
  * A superseded offer row annotated with the grantor's `account_id`.

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

@@ -1 +1 @@
-{"version":3,"file":"role_grant_offer_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAI9C,mEAAmE;AACnE,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,+BAA+B,QAA2B,CAAC;AAExE,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,IAAI,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACtD,eAAe,EAAE,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACzC,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;kBAoD4D,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,GAAI,OAAO,cAAc,KAAG,kBAiB/D,CAAC"}
+{"version":3,"file":"role_grant_offer_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAI9C,mEAAmE;AACnE,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,+BAA+B,QAA2B,CAAC;AAExE,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,IAAI,GAAG,IAAI,CAAC;IACrC;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACtD,eAAe,EAAE,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACzC,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;kBAoD4D,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,GAAI,OAAO,cAAc,KAAG,kBAiB/D,CAAC"}

package/dist/auth/session_middleware.d.ts

@@ -62,7 +62,14 @@ export interface CreateSessionAndSetCookieOptions {
  * persists the session row, optionally enforces a per-account session limit,
  * and sets the signed cookie.
  *
+ * The cap deletes the sessions it evicts, but not the connections they
+ * opened. A caller that passes `max_sessions` closes the returned sessions'
+ * connections once its transaction commits — `queue_connection_close` with a
+ * `session` target, as `POST /login` does. A caller that mints for an account
+ * created in the same transaction (signup, bootstrap) evicts nothing.
+ *
+ * @returns the token hashes of the sessions the cap evicted, empty without a cap
  * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
  */
-export declare const create_session_and_set_cookie: (options: CreateSessionAndSetCookieOptions) => Promise<void>;
+export declare const create_session_and_set_cookie: (options: CreateSessionAndSetCookieOptions) => Promise<Array<string>>;
 //# sourceMappingURL=session_middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAGvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACN,KAAK,cAAc,EAKnB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAcF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,CAAC,EAAE,OAAO,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}
+{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAGvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACN,KAAK,cAAc,EAKnB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAcF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,CAAC,EAAE,OAAO,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAavB,CAAC"}

package/dist/auth/session_middleware.js

@@ -70,6 +70,13 @@ export const create_session_middleware = (keyring, options) => {
  * persists the session row, optionally enforces a per-account session limit,
  * and sets the signed cookie.
  *
+ * The cap deletes the sessions it evicts, but not the connections they
+ * opened. A caller that passes `max_sessions` closes the returned sessions'
+ * connections once its transaction commits — `queue_connection_close` with a
+ * `session` target, as `POST /login` does. A caller that mints for an account
+ * created in the same transaction (signup, bootstrap) evicts nothing.
+ *
+ * @returns the token hashes of the sessions the cap evicted, empty without a cap
  * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
  */
 export const create_session_and_set_cookie = async (options) => {
@@ -78,9 +85,8 @@ export const create_session_and_set_cookie = async (options) => {
     const token_hash = hash_session_token(session_token);
     const expires_at = new Date(Date.now() + AUTH_SESSION_LIFETIME_MS);
     await query_create_session(deps, token_hash, account_id, expires_at);
-    if (max_sessions != null) {
-        await query_session_enforce_limit(deps, account_id, max_sessions);
-    }
+    const evicted = max_sessions != null ? await query_session_enforce_limit(deps, account_id, max_sessions) : [];
     const cookie_value = await create_session_cookie_value(keyring, session_token, session_options);
     set_session_cookie(c, cookie_value, session_options);
+    return evicted;
 };