@fuzdev/fuz_app 0.106.1 → 0.108.0

package/dist/auth/migrations.js

@@ -186,6 +186,30 @@ export const auth_migrations = [
 				  WHERE scope IS NULL`);
             await db.query('ALTER TABLE api_token ALTER COLUMN scope SET NOT NULL');
         }
+    },
+    // Index the column every bearer request looks up.
+    //
+    // `full_auth_schema` indexes `api_token(account_id)` and nothing else, so
+    // `query_validate_api_token`'s `WHERE token_hash = $1` — the lookup on the
+    // hot path of *every* bearer-authenticated request, valid or not — has been
+    // a sequential scan since the table shipped. The asymmetry is accidental:
+    // `auth_session` gets the same access pattern for free because its session
+    // hash *is* the primary key.
+    //
+    // UNIQUE rather than a plain index, because both spines resolve a token with
+    // an at-most-one read (`query_one` / `query_opt`). Two rows sharing a hash
+    // would mean the two impls could silently disagree about which credential
+    // answered; the constraint makes that unrepresentable instead of merely
+    // improbable.
+    //
+    // The name must match the Rust twin's `api_token_hash_unique_index` byte for
+    // byte or the `_testing_migration_tracker` parity gate fails and the
+    // swap-freely invariant breaks.
+    {
+        name: 'api_token_hash_unique_index',
+        up: async (db) => {
+            await db.query('CREATE UNIQUE INDEX IF NOT EXISTS idx_api_token_hash ON api_token(token_hash)');
+        }
     }
 ];
 /** Pre-composed migration namespace for auth tables. */

package/dist/auth/request_context.d.ts

@@ -38,7 +38,6 @@ import type { Context, MiddlewareHandler } from 'hono';
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { type Account, type Actor, type RoleGrant } from './account_schema.js';
 import type { QueryDeps } from '../db/query_deps.js';
-import { type TokenSurface } from './token_scope.js';
 import type { RouteSpec } from '../http/route_spec.js';
 import { type RouteAuth } from '../http/auth_shape.js';
 import { ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_ACCOUNT, ERROR_ACCOUNT_VANISHED } from '../http/error_schemas.js';
@@ -231,22 +230,48 @@ export declare const resolve_acting_actor: (deps: QueryDeps, account_id: string,
  */
 export declare const create_request_context_middleware: (deps: QueryDeps, log: Logger, session_context_key?: string) => MiddlewareHandler;
 /**
- * Refuse a non-RPC spine surface to a narrowed token — **rule 3**, in one place.
- *
- * Called by every surface rule 3 covers: the bare-hash fact read, the audit SSE
- * stream, and the WS upgrade (as pre-upgrade middleware, since
- * `upgradeWebSocket`'s callback cannot produce a denial).
- *
- * An unset `TOKEN_SCOPE_KEY` is the anonymous caller, who holds no credential to
- * narrow, so it passes. Sharing that branch is the point — hand-rolled per
- * surface it is one `&&` from either refusing every anonymous read or admitting
- * an authenticated caller whose middleware forgot to set the key.
+ * Refuse a non-RPC surface to a narrowed token — rule 3, for callers that are
+ * not route specs. Under the Rust twin's name
+ * (`token_scope_surface_denied_response`).
+ *
+ * The WS upgrade is the spine's one such caller: `upgradeWebSocket`'s callback
+ * must return `WSEvents` and so cannot produce a denial, which is why the gate
+ * runs as pre-upgrade middleware calling this rather than as a route-spec
+ * declaration. A consumer hand-rolling its own upgrade is in the same position
+ * and reaches for the same function.
+ *
+ * Takes the whole capability string, not a bare surface name — one spelling
+ * across route-spec declarations and direct calls alike, and the twin of the
+ * Rust signature. It needs no parse: the surface arm's identifier is pure label,
+ * since rule 3 never asks *which* surface. And it is deliberately not narrowed
+ * to the spine's four — the name decides nothing, so there is nothing for a
+ * closed set to protect, while a consumer surface would have nothing to pass.
+ * fuz_app's own uses are pinned two ways by the surface census: the exact call
+ * site, and the scan asserting every `'surface:<name>'` literal in `src/lib`
+ * names a surface the spine actually mounts.
  *
  * @param c - the request context, after the auth middleware chain
- * @param surface - the surface being gated; names itself in the denial
+ * @param capability - the `surface:<name>` this route demands; names itself in the denial
  * @returns the 403 to return, or `null` when the caller may proceed
  */
-export declare const token_scope_surface_denial: (c: Context, surface: TokenSurface) => Response | null;
+export declare const token_scope_surface_denial: (c: Context, capability: string) => Response | null;
+/**
+ * Create middleware refusing a route to a credential whose scope does not admit
+ * `capability`.
+ *
+ * The route-spec form, mounted by `fuz_auth_guard_resolver` from
+ * `auth.required_scope`. Lands in the `pre_authorization` phase, so a narrowed
+ * token is told about its scope rather than about the role it also lacks — and
+ * learns nothing about the route's input shape on the way.
+ *
+ * Parses at construction, so a malformed capability is a registration-time
+ * throw rather than a guard that mounts and reports nonsense.
+ *
+ * @param capability - the capability string this route demands, e.g. `surface:audit_stream`
+ * @returns middleware that 403s a credential whose scope lacks it
+ * @throws Error if `capability` is not a well-formed `rpc:<method>` / `surface:<name>` string
+ */
+export declare const require_token_scope: (capability: string) => MiddlewareHandler;
 /**
  * Middleware that requires authentication.
  *
@@ -284,6 +309,12 @@ export declare const require_role: (roles: ReadonlyArray<string>) => MiddlewareH
  * Returns 401 if unauthenticated, 403 with
  * `ERROR_CREDENTIAL_TYPE_REQUIRED` + `required_credential_types` echoing
  * the spec's allowlist when the wire-side credential isn't in it.
+ *
+ * Reads only `ACCOUNT_ID_KEY` + `CREDENTIAL_TYPE_KEY`, both set by the auth
+ * middleware — never the resolved `RequestContext`. That is why
+ * `fuz_auth_guard_resolver` mounts it in the `pre_authorization` phase: a
+ * wrong channel is refused before the route resolves an actor for it, so the
+ * denial costs no DB work and discloses no account state.
  * Body shape is symmetric with the role gate (`ERROR_INSUFFICIENT_PERMISSIONS` +
  * `required_roles`) and matches what the RPC dispatcher's post-auth
  * gate emits for the same condition. Today's only credential gate is
@@ -403,8 +434,8 @@ export type AuthorizationResult = {
  * Apply the dispatcher's authorization phase against the flat-record
  * `RouteAuth` shape. Shared by the route-spec wrapper, the HTTP RPC
  * dispatcher, and the per-message WS dispatcher. Phase order:
- * pre-validation 401 → input validation 400 → authorization phase →
- * post-authorization 403.
+ * pre-authorization 401 → authorization phase → post-authorization 403 →
+ * input validation 400.
  *
  * Pure data — the function does not touch a Hono context. Each transport
  * passes `account_id` (extracted from its own credential surface) and
@@ -419,7 +450,7 @@ export type AuthorizationResult = {
  *   never see a `RequestContext`.
  * - `account_id == null` on any non-public route → same null
  *   `request_context`. The `'required'` callers were already rejected at
- *   the pre-validation gate in the dispatcher; only genuine anonymous
+ *   the pre-authorization gate in the dispatcher; only genuine anonymous
  *   access on an `'optional'` axis lands here.
  * - `actor === 'none'` → builds account-only context via
  *   `build_account_context`. Null lookup → `account_vanished` 500 failure.
@@ -437,16 +468,15 @@ export declare const apply_authorization_phase: (deps: QueryDeps, account_id: st
 /**
  * Create the route-spec authorization handler used by `apply_route_specs`.
  *
- * Reads `acting` off `c.var.validated_input` (or `c.var.validated_query`
- * for GET routes) — input validation runs first, so the authorization
- * phase consumes the typed Zod field instead of pre-parsing the body.
- * Public routes (`auth.account === 'none' && auth.actor === 'none'`)
- * skip the phase entirely.
+ * Reads the `acting` selector via `read_route_acting` — `c.var.validated_query`
+ * on GETs, the raw body on mutations, since input validation now runs after
+ * the authority gates. Public routes (`auth.account === 'none' &&
+ * auth.actor === 'none'`) skip the phase entirely.
  *
  * Per registry-time invariant 2, `auth.actor !== 'none'` ⟺ the input
- * (or query) schema declares `acting?: ActingActor` — so reading from
- * `c.var.validated_input.acting` / `c.var.validated_query.acting` is
- * type-safe.
+ * (or query) schema declares `acting?: ActingActor` — so the selector is
+ * present on exactly the specs that read it, and input validation is what
+ * rejects a malformed one.
  *
  * Resolved contexts land on `REQUEST_CONTEXT_KEY` so the post-authorization
  * REST middleware (`require_role`, `require_credential_types`) reads the

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

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

package/dist/auth/request_context.js

@@ -39,8 +39,9 @@ import { hash_session_token, session_touch_fire_and_forget, query_session_get_va
 import { query_account_by_id, query_actor_by_id, query_active_actors_by_account } from './account_queries.js';
 import { query_role_grant_find_active_for_actor } from './role_grant_queries.js';
 import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY, TOKEN_SCOPE_KEY, TEST_CONTEXT_PRESET_KEY } from '../hono_context.js';
-import { token_scope_admits_non_rpc, token_scope_full, token_scope_surface_denied_body } from './token_scope.js';
-import { is_public_auth, needs_actor } from '../http/auth_shape.js';
+import { parse_token_scope_capability, token_scope_admits_capability, token_scope_denied_body, token_scope_full } from './token_scope.js';
+import { is_public_auth, needs_actor, parse_acting } from '../http/auth_shape.js';
+import { is_null_schema } from '../http/schema_helpers.js';
 import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_ACCOUNT, ERROR_ACCOUNT_VANISHED } from '../http/error_schemas.js';
 /** Hono context variable name for the request context. */
 export const REQUEST_CONTEXT_KEY = 'request_context';
@@ -240,27 +241,78 @@ export const create_request_context_middleware = (deps, log, session_context_key
     };
 };
 /**
- * Refuse a non-RPC spine surface to a narrowed token — **rule 3**, in one place.
+ * Refuse a capability the calling credential's scope does not admit.
  *
- * Called by every surface rule 3 covers: the bare-hash fact read, the audit SSE
- * stream, and the WS upgrade (as pre-upgrade middleware, since
- * `upgradeWebSocket`'s callback cannot produce a denial).
+ * The decision every token-scope gate outside the action dispatcher shares.
+ * Private because the two exported forms below are the whole surface: a route
+ * spec declares `auth.required_scope` and gets `require_token_scope`; anything
+ * that is not a route spec calls `token_scope_surface_denial`.
  *
  * An unset `TOKEN_SCOPE_KEY` is the anonymous caller, who holds no credential to
  * narrow, so it passes. Sharing that branch is the point — hand-rolled per
  * surface it is one `&&` from either refusing every anonymous read or admitting
  * an authenticated caller whose middleware forgot to set the key.
+ */
+const token_scope_denial = (c, capability) => {
+    const scope = c.get(TOKEN_SCOPE_KEY);
+    if (scope && !token_scope_admits_capability(scope, capability)) {
+        return c.json(token_scope_denied_body(capability.capability), 403);
+    }
+    return null;
+};
+/**
+ * Refuse a non-RPC surface to a narrowed token — rule 3, for callers that are
+ * not route specs. Under the Rust twin's name
+ * (`token_scope_surface_denied_response`).
+ *
+ * The WS upgrade is the spine's one such caller: `upgradeWebSocket`'s callback
+ * must return `WSEvents` and so cannot produce a denial, which is why the gate
+ * runs as pre-upgrade middleware calling this rather than as a route-spec
+ * declaration. A consumer hand-rolling its own upgrade is in the same position
+ * and reaches for the same function.
+ *
+ * Takes the whole capability string, not a bare surface name — one spelling
+ * across route-spec declarations and direct calls alike, and the twin of the
+ * Rust signature. It needs no parse: the surface arm's identifier is pure label,
+ * since rule 3 never asks *which* surface. And it is deliberately not narrowed
+ * to the spine's four — the name decides nothing, so there is nothing for a
+ * closed set to protect, while a consumer surface would have nothing to pass.
+ * fuz_app's own uses are pinned two ways by the surface census: the exact call
+ * site, and the scan asserting every `'surface:<name>'` literal in `src/lib`
+ * names a surface the spine actually mounts.
  *
  * @param c - the request context, after the auth middleware chain
- * @param surface - the surface being gated; names itself in the denial
+ * @param capability - the `surface:<name>` this route demands; names itself in the denial
  * @returns the 403 to return, or `null` when the caller may proceed
  */
-export const token_scope_surface_denial = (c, surface) => {
-    const scope = c.get(TOKEN_SCOPE_KEY);
-    if (scope && !token_scope_admits_non_rpc(scope)) {
-        return c.json(token_scope_surface_denied_body(surface), 403);
+export const token_scope_surface_denial = (c, capability) => token_scope_denial(c, { kind: 'surface', capability });
+/**
+ * Create middleware refusing a route to a credential whose scope does not admit
+ * `capability`.
+ *
+ * The route-spec form, mounted by `fuz_auth_guard_resolver` from
+ * `auth.required_scope`. Lands in the `pre_authorization` phase, so a narrowed
+ * token is told about its scope rather than about the role it also lacks — and
+ * learns nothing about the route's input shape on the way.
+ *
+ * Parses at construction, so a malformed capability is a registration-time
+ * throw rather than a guard that mounts and reports nonsense.
+ *
+ * @param capability - the capability string this route demands, e.g. `surface:audit_stream`
+ * @returns middleware that 403s a credential whose scope lacks it
+ * @throws Error if `capability` is not a well-formed `rpc:<method>` / `surface:<name>` string
+ */
+export const require_token_scope = (capability) => {
+    const parsed = parse_token_scope_capability(capability);
+    if (parsed === null) {
+        throw new Error(`auth.required_scope "${capability}" is not a valid token-scope capability \u2014 expected 'rpc:<method>' or 'surface:<name>', where a surface name is lowercase letters and underscores`);
     }
-    return null;
+    return async (c, next) => {
+        const denied = token_scope_denial(c, parsed);
+        if (denied)
+            return denied;
+        await next();
+    };
 };
 /**
  * Middleware that requires authentication.
@@ -315,6 +367,12 @@ export const require_role = (roles) => {
  * Returns 401 if unauthenticated, 403 with
  * `ERROR_CREDENTIAL_TYPE_REQUIRED` + `required_credential_types` echoing
  * the spec's allowlist when the wire-side credential isn't in it.
+ *
+ * Reads only `ACCOUNT_ID_KEY` + `CREDENTIAL_TYPE_KEY`, both set by the auth
+ * middleware — never the resolved `RequestContext`. That is why
+ * `fuz_auth_guard_resolver` mounts it in the `pre_authorization` phase: a
+ * wrong channel is refused before the route resolves an actor for it, so the
+ * denial costs no DB work and discloses no account state.
  * Body shape is symmetric with the role gate (`ERROR_INSUFFICIENT_PERMISSIONS` +
  * `required_roles`) and matches what the RPC dispatcher's post-auth
  * gate emits for the same condition. Today's only credential gate is
@@ -421,8 +479,8 @@ export const build_account_context = async (deps, account_id) => {
  * Apply the dispatcher's authorization phase against the flat-record
  * `RouteAuth` shape. Shared by the route-spec wrapper, the HTTP RPC
  * dispatcher, and the per-message WS dispatcher. Phase order:
- * pre-validation 401 → input validation 400 → authorization phase →
- * post-authorization 403.
+ * pre-authorization 401 → authorization phase → post-authorization 403 →
+ * input validation 400.
  *
  * Pure data — the function does not touch a Hono context. Each transport
  * passes `account_id` (extracted from its own credential surface) and
@@ -437,7 +495,7 @@ export const build_account_context = async (deps, account_id) => {
  *   never see a `RequestContext`.
  * - `account_id == null` on any non-public route → same null
  *   `request_context`. The `'required'` callers were already rejected at
- *   the pre-validation gate in the dispatcher; only genuine anonymous
+ *   the pre-authorization gate in the dispatcher; only genuine anonymous
  *   access on an `'optional'` axis lands here.
  * - `actor === 'none'` → builds account-only context via
  *   `build_account_context`. Null lookup → `account_vanished` 500 failure.
@@ -457,7 +515,7 @@ export const apply_authorization_phase = async (deps, account_id, auth, acting_v
     if (account_id == null) {
         // Optional-auth route hit without a credential — leave `RequestContext`
         // null so the handler can branch on it. `'required'` callers already
-        // got rejected at the pre-validation gate.
+        // got rejected at the pre-authorization gate.
         return { ok: true, request_context: null };
     }
     if (!needs_actor(auth)) {
@@ -496,16 +554,15 @@ export const apply_authorization_phase = async (deps, account_id, auth, acting_v
 /**
  * Create the route-spec authorization handler used by `apply_route_specs`.
  *
- * Reads `acting` off `c.var.validated_input` (or `c.var.validated_query`
- * for GET routes) — input validation runs first, so the authorization
- * phase consumes the typed Zod field instead of pre-parsing the body.
- * Public routes (`auth.account === 'none' && auth.actor === 'none'`)
- * skip the phase entirely.
+ * Reads the `acting` selector via `read_route_acting` — `c.var.validated_query`
+ * on GETs, the raw body on mutations, since input validation now runs after
+ * the authority gates. Public routes (`auth.account === 'none' &&
+ * auth.actor === 'none'`) skip the phase entirely.
  *
  * Per registry-time invariant 2, `auth.actor !== 'none'` ⟺ the input
- * (or query) schema declares `acting?: ActingActor` — so reading from
- * `c.var.validated_input.acting` / `c.var.validated_query.acting` is
- * type-safe.
+ * (or query) schema declares `acting?: ActingActor` — so the selector is
+ * present on exactly the specs that read it, and input validation is what
+ * rejects a malformed one.
  *
  * Resolved contexts land on `REQUEST_CONTEXT_KEY` so the post-authorization
  * REST middleware (`require_role`, `require_credential_types`) reads the
@@ -523,7 +580,7 @@ export const create_fuz_authorization_handler = (deps) => {
             return;
         if (is_public_auth(spec.auth))
             return;
-        const acting_value = needs_actor(spec.auth) ? extract_validated_acting(c) : undefined;
+        const acting_value = needs_actor(spec.auth) ? await read_route_acting(c, spec) : undefined;
         const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
         const result = await apply_authorization_phase(deps, account_id, spec.auth, acting_value);
         if (!result.ok)
@@ -538,22 +595,43 @@ export const create_fuz_authorization_handler = (deps) => {
     };
 };
 /**
- * Read `acting` off the validated input (or validated query) on the Hono
- * context. Input/query validation runs before the authorization phase,
- * so this reads a typed Zod field — not the raw body.
- *
- * Returns `undefined` when `validated_input` / `validated_query` isn't
- * set or doesn't carry `acting`. Per registry-time invariant 2, the
- * dispatcher only calls this when `auth.actor !== 'none'`, which by
- * the biconditional means the input schema declares
- * `acting?: ActingActor`.
+ * Read the `acting` actor selector for the authorization phase.
+ *
+ * REST is bi-located: GETs declare `acting` on `query`, mutations on `input`.
+ * Query validation still runs ahead of the authorization phase, so the GET
+ * half reads a typed Zod field. Input validation now runs *after* the
+ * authority gates (nothing about a route's body shape reaches a caller those
+ * gates refuse), so the mutation half reads the raw body instead.
+ *
+ * The raw read mirrors `create_input_validation`'s own skip conditions exactly
+ * — GETs and null-input specs — so this never parses a body the route itself
+ * would have left alone. That matters for the routes carrying raw bytes rather
+ * than JSON (git smart-HTTP, binary uploads): they declare `input: z.null()`,
+ * so their stream reaches the handler untouched, and they carry `acting` on
+ * `query` regardless.
+ *
+ * `parse_acting` owns what counts as a selector and why a malformed one reads
+ * as omitted.
+ *
+ * @param c - the request context, after query validation
+ * @param spec - the route being dispatched; decides where `acting` can live
+ * @returns the actor id, or `undefined` when absent, malformed, or unreadable
  */
-const extract_validated_acting = (c) => {
-    const validated_input = c.get('validated_input');
-    if (validated_input && typeof validated_input.acting === 'string')
-        return validated_input.acting;
+const read_route_acting = async (c, spec) => {
     const validated_query = c.get('validated_query');
     if (validated_query && typeof validated_query.acting === 'string')
         return validated_query.acting;
-    return undefined;
+    if (spec.method === 'GET' || is_null_schema(spec.input))
+        return undefined;
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        // Malformed body — input validation answers with the 400.
+        return undefined;
+    }
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    return parse_acting(body.acting);
 };

package/dist/auth/session_queries.d.ts

@@ -113,8 +113,19 @@ export declare const query_session_list_for_account: (deps: QueryDeps, account_i
  * both commit above `max_sessions`. A transaction is necessary here but not
  * sufficient. Closing this needs one serialization point per
  * `(account_id, credential_kind)` — a locked parent row or a transaction-scoped
- * advisory lock — taken before count/evict/insert, plus a stable tie-breaker
- * alongside `created_at` so the survivors are deterministic.
+ * advisory lock — taken before count/evict/insert.
+ *
+ * Ordering is `created_at DESC, id DESC`. The `id` leg is a **stability**
+ * tie-breaker, not a recency one: `created_at` defaults to `NOW()`, the
+ * *transaction* timestamp, so two sessions born in one transaction — or in two
+ * transactions that started in the same microsecond — tie, and an untied
+ * `OFFSET` may keep a different set on two evaluations of the same rows. `id` is
+ * the blake3 token hash, so the tie-break is arbitrary but deterministic; it
+ * makes the survivors reproducible, it does not make the row just inserted a
+ * guaranteed survivor. Only the serialization point above does that.
+ *
+ * Expired-but-unreaped rows count toward the cap (the predicate is `account_id`
+ * alone). Matches the Rust twin `query_session_enforce_limit`.
  *
  * @param deps - query dependencies (must be transaction-scoped)
  * @param account_id - the account to enforce the limit for

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

@@ -1 +1 @@
-{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAElE,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,SAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CASnD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}
+{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAElE,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,SAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CASnD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}

package/dist/auth/session_queries.js

@@ -143,8 +143,19 @@ export const query_session_list_for_account = async (deps, account_id, limit = 5
  * both commit above `max_sessions`. A transaction is necessary here but not
  * sufficient. Closing this needs one serialization point per
  * `(account_id, credential_kind)` — a locked parent row or a transaction-scoped
- * advisory lock — taken before count/evict/insert, plus a stable tie-breaker
- * alongside `created_at` so the survivors are deterministic.
+ * advisory lock — taken before count/evict/insert.
+ *
+ * Ordering is `created_at DESC, id DESC`. The `id` leg is a **stability**
+ * tie-breaker, not a recency one: `created_at` defaults to `NOW()`, the
+ * *transaction* timestamp, so two sessions born in one transaction — or in two
+ * transactions that started in the same microsecond — tie, and an untied
+ * `OFFSET` may keep a different set on two evaluations of the same rows. `id` is
+ * the blake3 token hash, so the tie-break is arbitrary but deterministic; it
+ * makes the survivors reproducible, it does not make the row just inserted a
+ * guaranteed survivor. Only the serialization point above does that.
+ *
+ * Expired-but-unreaped rows count toward the cap (the predicate is `account_id`
+ * alone). Matches the Rust twin `query_session_enforce_limit`.
  *
  * @param deps - query dependencies (must be transaction-scoped)
  * @param account_id - the account to enforce the limit for
@@ -157,7 +168,7 @@ export const query_session_enforce_limit = async (deps, account_id, max_sessions
 		 WHERE id IN (
 		   SELECT id FROM auth_session
 		   WHERE account_id = $1
-		   ORDER BY created_at DESC
+		   ORDER BY created_at DESC, id DESC
 		   OFFSET $2
 		 ) RETURNING id`, [account_id, max_sessions]);
     return rows.length;

package/dist/auth/signup_routes.d.ts

@@ -36,6 +36,16 @@ export declare const DEFAULT_SIGNUP_FAIL_JITTER_MS = 25;
  * Per-factory configuration for signup route specs.
  */
 export interface SignupRouteOptions extends AuthSessionRouteOptions {
+    /**
+     * Rate limiter for signup attempts, keyed by client IP. Pass `null` to
+     * disable. Its own instance, not login's: signup failures bound username
+     * *enumeration* (the 403/409 split), not credential guessing, and an
+     * open-signup deployment lets any unauthenticated caller spend this budget
+     * — which must not cost anyone their login attempts. Never refunded on
+     * success (see `RateLimiter.reset`). Mirrors the Rust spine's
+     * `signup_ip_rate_limiter`.
+     */
+    signup_ip_rate_limiter: RateLimiter | null;
     /** Rate limiter for signup attempts, keyed by submitted username. Pass `null` to disable. */
     signup_account_rate_limiter: RateLimiter | null;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAQhD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CA4KjB,CAAC"}
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAQhD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE;;;;;;;;OAQG;IACH,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAgLjB,CAAC"}

package/dist/auth/signup_routes.js

@@ -55,7 +55,7 @@ const signup_fail_delay = (floor_ms, jitter_ms) => {
  */
 export const create_signup_route_specs = (deps, options) => {
     const { keyring, password } = deps;
-    const { session_options, ip_rate_limiter, signup_account_rate_limiter, signup_fail_floor_ms = DEFAULT_SIGNUP_FAIL_FLOOR_MS, signup_fail_jitter_ms = DEFAULT_SIGNUP_FAIL_JITTER_MS } = options;
+    const { session_options, signup_ip_rate_limiter, signup_account_rate_limiter, signup_fail_floor_ms = DEFAULT_SIGNUP_FAIL_FLOOR_MS, signup_fail_jitter_ms = DEFAULT_SIGNUP_FAIL_JITTER_MS } = options;
     return [
         {
             ...create_signup_route_shape({
@@ -63,9 +63,9 @@ export const create_signup_route_specs = (deps, options) => {
             }),
             handler: async (c, route) => {
                 // Per-IP rate limit check (before any work). 429 stays fast.
-                const ip = ip_rate_limiter ? get_client_ip(c) : null;
-                if (ip_rate_limiter && ip) {
-                    const check = ip_rate_limiter.check(ip);
+                const ip = signup_ip_rate_limiter ? get_client_ip(c) : null;
+                if (signup_ip_rate_limiter && ip) {
+                    const check = signup_ip_rate_limiter.check(ip);
                     if (!check.allowed) {
                         return rate_limit_exceeded_response(c, check.retry_after);
                     }
@@ -157,8 +157,8 @@ export const create_signup_route_specs = (deps, options) => {
                 }
                 catch (e) {
                     if (e instanceof NoMatchingInviteError) {
-                        if (ip_rate_limiter && ip)
-                            ip_rate_limiter.record(ip);
+                        if (signup_ip_rate_limiter && ip)
+                            signup_ip_rate_limiter.record(ip);
                         if (signup_account_rate_limiter)
                             signup_account_rate_limiter.record(account_key);
                         emit_failure_audit('no_match');
@@ -167,8 +167,8 @@ export const create_signup_route_specs = (deps, options) => {
                     }
                     // Unique constraint violation: username or email already exists.
                     if (is_pg_unique_violation(e)) {
-                        if (ip_rate_limiter && ip)
-                            ip_rate_limiter.record(ip);
+                        if (signup_ip_rate_limiter && ip)
+                            signup_ip_rate_limiter.record(ip);
                         if (signup_account_rate_limiter)
                             signup_account_rate_limiter.record(account_key);
                         emit_failure_audit('signup_conflict');
@@ -185,9 +185,12 @@ export const create_signup_route_specs = (deps, options) => {
                     emit_failure_audit('internal_error');
                     throw e;
                 }
-                // Reset rate limiters on success
-                if (ip_rate_limiter && ip)
-                    ip_rate_limiter.reset(ip);
+                // Clear the account-grain bucket only — the IP aggregate stands.
+                // This is the cheapest version of the spray path `RateLimiter.reset`
+                // describes: where login at least costs the attacker a credential,
+                // an open-signup deployment let an *unauthenticated* caller zero a
+                // shared IP budget by creating throwaway accounts, and the
+                // per-account limiter never applies to the attacker's own signups.
                 if (signup_account_rate_limiter)
                     signup_account_rate_limiter.reset(account_key);
                 deps.audit.emit(route, {