@fuzdev/fuz_app 0.104.0 → 0.106.0

package/dist/auth/session_queries.d.ts

@@ -8,7 +8,7 @@
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { QueryDeps } from '../db/query_deps.js';
-import type { AuthSession } from './account_schema.js';
+import type { AuthSession, SessionId } from './account_schema.js';
 /** Session lifetime in milliseconds (30 days). */
 export declare const AUTH_SESSION_LIFETIME_MS: number;
 /** Extend session when it has less than this remaining (1 day in ms). */
@@ -16,10 +16,13 @@ export declare const AUTH_SESSION_EXTEND_THRESHOLD_MS: number;
 /**
  * Hash a session token to its storage key using blake3.
  *
+ * The sole minting point for `SessionId` — `hash_blake3` returns bare hex, so
+ * the brand is applied here, where the value gains its meaning.
+ *
  * @param token - the raw session token
  * @returns hex-encoded blake3 hash
  */
-export declare const hash_session_token: (token: string) => string;
+export declare const hash_session_token: (token: string) => SessionId;
 /**
  * Generate a cryptographically random session token.
  *
@@ -103,8 +106,15 @@ export declare const query_session_list_for_account: (deps: QueryDeps, account_i
  * - `POST /bootstrap` and `POST /signup` manage their own transactions
  *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
  *
- * The transaction ensures the INSERT + enforce_limit pair is atomic —
- * concurrent session creation cannot interleave between the two statements.
+ * The transaction makes one creator's INSERT + enforce_limit pair atomic, but it
+ * does **not** serialize concurrent creators. Under Read Committed, two
+ * transactions can't see each other's uncommitted session row, so each computes
+ * its `OFFSET` eviction against a stale count, each preserves its own row, and
+ * 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.
  *
  * @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,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/auth/session_queries.js

@@ -15,6 +15,9 @@ export const AUTH_SESSION_EXTEND_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 /**
  * Hash a session token to its storage key using blake3.
  *
+ * The sole minting point for `SessionId` — `hash_blake3` returns bare hex, so
+ * the brand is applied here, where the value gains its meaning.
+ *
  * @param token - the raw session token
  * @returns hex-encoded blake3 hash
  */
@@ -42,7 +45,7 @@ export const query_create_session = async (deps, token_hash, account_id, expires
     await deps.db.query(`INSERT INTO auth_session (id, account_id, expires_at) VALUES ($1, $2, $3)`, [
         token_hash,
         account_id,
-        expires_at.toISOString(),
+        expires_at.toISOString()
     ]);
 };
 /**
@@ -133,8 +136,15 @@ export const query_session_list_for_account = async (deps, account_id, limit = 5
  * - `POST /bootstrap` and `POST /signup` manage their own transactions
  *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
  *
- * The transaction ensures the INSERT + enforce_limit pair is atomic —
- * concurrent session creation cannot interleave between the two statements.
+ * The transaction makes one creator's INSERT + enforce_limit pair atomic, but it
+ * does **not** serialize concurrent creators. Under Read Committed, two
+ * transactions can't see each other's uncommitted session row, so each computes
+ * its `OFFSET` eviction against a stale count, each preserves its own row, and
+ * 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.
  *
  * @param deps - query dependencies (must be transaction-scoped)
  * @param account_id - the account to enforce the limit for

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

@@ -1 +1 @@
-{"version":3,"file":"signup_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAKtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAQrD,wHAAwH;AACxH,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAIvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,WAAW,uBAAuB;IACvC,iFAAiF;IACjF,2BAA2B,EAAE,OAAO,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,uBAAuB,KAC9B,IAAI,CAAC,SAAS,EAAE,SAAS,CAgB1B,CAAC"}
+{"version":3,"file":"signup_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQvD,wHAAwH;AACxH,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAIvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,WAAW,uBAAuB;IACvC,iFAAiF;IACjF,2BAA2B,EAAE,OAAO,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,uBAAuB,KAC9B,IAAI,CAAC,SAAS,EAAE,SAAS,CAgB1B,CAAC"}

package/dist/auth/signup_route_schema.js

@@ -15,12 +15,12 @@ import { z } from 'zod';
 import { Uuid } from '@fuzdev/fuz_util/id.ts';
 import { Username, Email } from '../primitive_schemas.js';
 import { Password } from './password.js';
-import { ERROR_NO_MATCHING_INVITE, ERROR_SIGNUP_CONFLICT, ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY, } from '../http/error_schemas.js';
+import { ERROR_NO_MATCHING_INVITE, ERROR_SIGNUP_CONFLICT, ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY } from '../http/error_schemas.js';
 /** Input for `POST /signup`. `email` is optional (absent or `null` = no email) and must match any referenced invite. */
 export const SignupInput = z.strictObject({
     username: Username,
     password: Password,
-    email: Email.nullish(),
+    email: Email.nullish()
 });
 /**
  * Output for `POST /signup`.
@@ -32,7 +32,7 @@ export const SignupInput = z.strictObject({
 export const SignupOutput = z.strictObject({
     ok: z.literal(true),
     account: z.strictObject({ id: Uuid, username: Username }),
-    actor: z.strictObject({ id: Uuid }),
+    actor: z.strictObject({ id: Uuid })
 });
 /**
  * The `POST /signup` route shape minus its handler — pure hono-free data.
@@ -51,9 +51,9 @@ export const create_signup_route_shape = (options) => ({
     rate_limit: options.signup_account_rate_limited ? 'both' : 'ip',
     errors: {
         400: z.looseObject({
-            error: z.enum([ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY]),
+            error: z.enum([ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY])
         }),
         403: z.looseObject({ error: z.literal(ERROR_NO_MATCHING_INVITE) }),
-        409: z.looseObject({ error: z.literal(ERROR_SIGNUP_CONFLICT) }),
-    },
+        409: z.looseObject({ error: z.literal(ERROR_SIGNUP_CONFLICT) })
+    }
 });

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,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;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,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"}

package/dist/auth/signup_routes.js

@@ -10,7 +10,7 @@
 import { create_session_and_set_cookie } from './session_middleware.js';
 import { query_create_account_with_actor } from './account_queries.js';
 import { query_app_settings_load } from './app_settings_queries.js';
-import { query_invite_find_unclaimed_match_for_update, query_invite_claim_unscoped, } from './invite_queries.js';
+import { query_invite_find_unclaimed_match_for_update, query_invite_claim_unscoped } from './invite_queries.js';
 import { create_signup_route_shape } from './signup_route_schema.js';
 import { get_route_input } from '../http/route_spec.js';
 import { get_client_ip } from '../http/client_ip.js';
@@ -55,11 +55,11 @@ 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, 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({
-                signup_account_rate_limited: signup_account_rate_limiter !== null,
+                signup_account_rate_limited: signup_account_rate_limiter !== null
             }),
             handler: async (c, route) => {
                 // Per-IP rate limit check (before any work). 429 stays fast.
@@ -112,8 +112,8 @@ export const create_signup_route_specs = (deps, options) => {
                             reason,
                             ...(invite && { invite_id: invite.id }),
                             ...(email != null && { email }),
-                            ...(open_signup && { open_signup: true }),
-                        },
+                            ...(open_signup && { open_signup: true })
+                        }
                     });
                 };
                 let result;
@@ -136,7 +136,7 @@ export const create_signup_route_specs = (deps, options) => {
                         const { account, actor } = await query_create_account_with_actor(tx_deps, {
                             username,
                             password_hash,
-                            email,
+                            email
                         });
                         if (invite) {
                             // Guaranteed to succeed: FOR UPDATE held the row
@@ -150,7 +150,7 @@ export const create_signup_route_specs = (deps, options) => {
                             deps: tx_deps,
                             c,
                             account_id: account.id,
-                            session_options,
+                            session_options
                         });
                         return { account, actor };
                     });
@@ -194,15 +194,15 @@ export const create_signup_route_specs = (deps, options) => {
                     event_type: 'signup',
                     account_id: result.account.id,
                     ip: get_client_ip(c),
-                    metadata: invite ? { invite_id: invite.id, username } : { open_signup: true, username },
+                    metadata: invite ? { invite_id: invite.id, username } : { open_signup: true, username }
                 });
                 return c.json({
                     ok: true,
                     account: { id: result.account.id, username: result.account.username },
-                    actor: { id: result.actor.id },
+                    actor: { id: result.actor.id }
                 });
-            },
-        },
+            }
+        }
     ];
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"standard_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/standard_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAKzE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,yBAAyB,CAI9E,CAAC"}
+{"version":3,"file":"standard_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/standard_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAK3E;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,yBAAyB,CAI9E,CAAC"}

package/dist/auth/standard_action_specs.js

@@ -32,5 +32,5 @@ import { all_account_action_specs } from './account_action_specs.js';
 export const all_standard_action_specs = [
     ...all_admin_action_specs,
     ...all_role_grant_offer_action_specs,
-    ...all_account_action_specs,
+    ...all_account_action_specs
 ];

package/dist/auth/standard_rpc_actions.d.ts

@@ -21,7 +21,7 @@
 import { type AdminActionOptions } from './admin_actions.js';
 import { type RoleGrantOfferActionOptions } from './role_grant_offer_actions.js';
 import { type AccountActionOptions } from './account_actions.js';
-import type { RouteFactoryDeps } from './deps.js';
+import type { ActionFactoryDeps } from './deps.js';
 import type { NotificationSender } from './role_grant_offer_notifications.js';
 import type { RpcAction } from '../actions/action_rpc.js';
 /**
@@ -38,12 +38,12 @@ export interface StandardRpcActionsOptions extends AdminActionOptions, RoleGrant
 /**
  * Dependencies for `create_standard_rpc_actions`.
  *
- * Stack-standard `RouteFactoryDeps` slice (`log`, `audit`) plus an optional
+ * Stack-standard `ActionFactoryDeps` (`log`, `audit`) plus an optional
  * `notification_sender` consumed only by the role-grant-offer sub-factory
  * for WS fan-out. Admin and account sub-factories ignore
  * `notification_sender`.
  */
-export interface StandardRpcActionsDeps extends Pick<RouteFactoryDeps, 'log' | 'audit'> {
+export interface StandardRpcActionsDeps extends ActionFactoryDeps {
     notification_sender?: NotificationSender | null;
 }
 /**
@@ -54,7 +54,7 @@ export interface StandardRpcActionsDeps extends Pick<RouteFactoryDeps, 'log' | '
  * and `create_account_actions(deps, {max_tokens})`. The shared `roles`
  * option flows to admin + role-grant-offer.
  *
- * @param deps - `StandardRpcActionsDeps` (`log`, `audit` from `RouteFactoryDeps`; optional `notification_sender` for WS fan-out)
+ * @param deps - `StandardRpcActionsDeps` (`log`, `audit` from `ActionFactoryDeps`; optional `notification_sender` for WS fan-out)
  * @param options - role schema, role-grant-offer config, account config
  * @returns RPC actions to pass as `rpc_endpoints` or spread into `create_rpc_endpoint`
  */

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

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

package/dist/auth/standard_rpc_actions.js

@@ -19,7 +19,7 @@
  * @module
  */
 import { create_admin_actions } from './admin_actions.js';
-import { create_role_grant_offer_actions, } from './role_grant_offer_actions.js';
+import { create_role_grant_offer_actions } from './role_grant_offer_actions.js';
 import { create_account_actions } from './account_actions.js';
 /**
  * Build the combined admin + role-grant-offer + account RPC action set.
@@ -29,12 +29,12 @@ import { create_account_actions } from './account_actions.js';
  * and `create_account_actions(deps, {max_tokens})`. The shared `roles`
  * option flows to admin + role-grant-offer.
  *
- * @param deps - `StandardRpcActionsDeps` (`log`, `audit` from `RouteFactoryDeps`; optional `notification_sender` for WS fan-out)
+ * @param deps - `StandardRpcActionsDeps` (`log`, `audit` from `ActionFactoryDeps`; optional `notification_sender` for WS fan-out)
  * @param options - role schema, role-grant-offer config, account config
  * @returns RPC actions to pass as `rpc_endpoints` or spread into `create_rpc_endpoint`
  */
 export const create_standard_rpc_actions = (deps, options = {}) => [
     ...create_admin_actions(deps, options),
     ...create_role_grant_offer_actions(deps, options),
-    ...create_account_actions(deps, options),
+    ...create_account_actions(deps, options)
 ];

package/dist/auth/token_scope.d.ts

@@ -0,0 +1,155 @@
+/**
+ * `TokenScope` — the per-credential authority narrowing stored on
+ * `api_token.scope`.
+ *
+ * Twin of the Rust spine's `fuz_auth::token_scope`. The stored document is the
+ * wire contract; both spines read the same `api_token.scope` JSONB, so the
+ * `kind` strings, the field names, and the version constant must match exactly.
+ *
+ * ## The whole vocabulary
+ *
+ * Two variants, and three rules:
+ *
+ * 1. **`full` must be spelled at mint.** `account_token_create` takes a required
+ *    `scope`, the column is `NOT NULL`, and session / daemon-token credentials
+ *    resolve to `full` by construction. There is no absent state — which is the
+ *    whole point. The 2026-02 `scope` column stored `full` / `read` / `write`
+ *    and nothing enforced them; the reason that was worse than nothing is that
+ *    the absent/unenforced case was indistinguishable from a decision.
+ * 2. **`methods` denies every method it does not list.** An empty list is legal
+ *    and renders the token inert for RPC — unlike an empty `credential_types`
+ *    allowlist, which is rejected because it renders an *action* unreachable.
+ * 3. **A narrowed token is RPC-only.** `methods` denies every non-RPC spine
+ *    surface outright — the db-admin browser, the bare-hash fact read, the
+ *    audit SSE stream, and the WS upgrade. See `token_scope_admits_non_rpc`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Current `TokenScope` document version. Must match the Rust `TOKEN_SCOPE_VERSION`. */
+export declare const TOKEN_SCOPE_VERSION = 1;
+/**
+ * Serialized-document cap. Matches the Rust `MAX_TOKEN_SCOPE_BYTES` and
+ * fuz_forge's `MAX_POLICY_BYTES`.
+ */
+export declare const MAX_TOKEN_SCOPE_BYTES: number;
+/**
+ * The stored `api_token.scope` document.
+ *
+ * `grandfathered` is a fact about the *row* — the `api_token_scope` migration
+ * wrote it; no minter chose it — that only the token list cares about. The
+ * enforcement path never branches on it, which is what stops "grandfathered"
+ * from becoming a third authority level.
+ *
+ * Strict on both arms so a v2 document carrying a grant arm a v1 reader doesn't
+ * understand is refused rather than parsed as permissively-narrower-than-stored.
+ * The discriminated union also refuses the contradiction
+ * `{kind: 'full', methods: [...]}`.
+ */
+export declare const TokenScope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"full">;
+    grandfathered: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"methods">;
+    methods: z.ZodArray<z.ZodString>;
+    grandfathered: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "kind">;
+export type TokenScope = z.infer<typeof TokenScope>;
+/**
+ * The `scope` input accepted by `account_token_create` — the stored shape minus
+ * the row-owned fields.
+ *
+ * A minter cannot set `version` or `grandfathered`: the first is stamped by
+ * `token_scope_full` / `token_scope_methods`, and the second is the migration's
+ * mark for tokens that predate scoping. Letting a caller forge `grandfathered`
+ * would turn a tracked debt into a laundered one.
+ */
+export declare const TokenScopeInput: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"full">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"methods">;
+    methods: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export type TokenScopeInput = z.infer<typeof TokenScopeInput>;
+/** A deliberately-minted full-authority scope. */
+export declare const token_scope_full: () => TokenScope;
+/** A narrowed scope over `methods`. */
+export declare const token_scope_methods: (methods: Array<string>) => TokenScope;
+/** Build the stored scope from a mint-time input. */
+export declare const token_scope_from_input: (input: TokenScopeInput) => TokenScope;
+/**
+ * Does `scope` admit dispatching `method`?
+ *
+ * Consulted by `perform_action` between the credential gate and the role gate.
+ */
+export declare const token_scope_admits_method: (scope: TokenScope, method: string) => boolean;
+/**
+ * Does `scope` admit a non-RPC spine surface?
+ *
+ * **Rule 3, and it is the load-bearing one.** A method-name allowlist alone
+ * would have been a false promise: the db-admin browser serves paginated rows of
+ * any `public` table (including `account.password_hash`, `auth_session`, and
+ * `api_token`) plus row `DELETE`, gated on a global role a bearer credential
+ * satisfies. A token whose UI badge read "scoped to `cell_get`" could still
+ * delete an account row.
+ *
+ * So a narrowed token reaches no non-RPC surface at all. Strictly more
+ * restrictive than naming each surface, no vocabulary to maintain, and one
+ * sentence a user can hold: *a scoped token is RPC-only*.
+ */
+export declare const token_scope_admits_non_rpc: (scope: TokenScope) => boolean;
+/** Surfaces gated by rule 3. Capability strings match the Rust `TokenSurface`. */
+export declare const TOKEN_SURFACE_CAPABILITIES: {
+    readonly db_admin: "surface:db_admin";
+    readonly fact_bare: "surface:fact_bare";
+    readonly audit_stream: "surface:audit_stream";
+    readonly ws_upgrade: "surface:ws_upgrade";
+};
+export type TokenSurface = keyof typeof TOKEN_SURFACE_CAPABILITIES;
+/**
+ * Build the flat denial body a non-RPC surface returns when a narrowed token
+ * reaches it: `{error: 'token_scope_required', required_scope: 'surface:<name>'}`
+ * at 403.
+ *
+ * One shape for every surface, matching the Rust
+ * `token_scope_surface_denied_response`. These are REST-ish routes whose
+ * sibling denials are already flat, so the JSON-RPC envelope stays with the
+ * dispatcher's per-method gate and stops there.
+ */
+export declare const token_scope_surface_denied_body: (surface: TokenSurface) => {
+    error: "token_scope_required";
+    required_scope: string;
+};
+/** Stable label for the token list / UI. */
+export declare const token_scope_label: (scope: TokenScope) => string;
+/**
+ * Parse a stored document, enforcing the size cap and the schema.
+ *
+ * **Fail-closed**: returns `null` on an unreadable document, and every caller on
+ * the enforcement path treats `null` as "refuse the credential" rather than
+ * "allow everything". fuz_forge's hydrate path deliberately widens on a DB blip
+ * — safe there only because a role gate still applies. Here the scope *is* the
+ * gate, so widening on a parse failure would hand a narrowed token full
+ * authority exactly when something is already wrong.
+ */
+export declare const parse_token_scope: (raw: string) => TokenScope | null;
+/**
+ * Serialize for storage, enforcing the size cap.
+ *
+ * Throws on an over-cap document — the mint path maps that to a 400, matching
+ * the Rust side's `TokenScopeError::TooLarge`.
+ */
+export declare const serialize_token_scope: (scope: TokenScope) => string;
+/**
+ * Read a stored `api_token.scope` value back into a `TokenScope`, or `null`
+ * when the document is unreadable.
+ *
+ * The DB driver may hand `scope` back already-parsed (JSONB → object) or as
+ * text depending on backend, so both are normalized here rather than at each
+ * call site. Lives here rather than beside the queries so the pure scope module
+ * owns every parse — and so mocking the query module doesn't drag this along.
+ */
+export declare const parse_stored_token_scope: (value: unknown) => TokenScope | null;
+//# sourceMappingURL=token_scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"token_scope.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/token_scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAW,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;4BAYrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;4BAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,QAAO,UAGlC,CAAC;AAEH,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,SAAS,KAAK,CAAC,MAAM,CAAC,KAAG,UAI3D,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,GAAI,OAAO,eAAe,KAAG,UACgB,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,UAAU,EAAE,QAAQ,MAAM,KAAG,OACtB,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,UAAU,KAAG,OAAgC,CAAC;AAEhG,kFAAkF;AAClF,eAAO,MAAM,0BAA0B;;;;;CAK7B,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,0BAA0B,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC3C,SAAS,YAAY,KACnB;IAAE,KAAK,EAAE,sBAAsB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAGxD,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAAU,KAAG,MAGrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,UAAU,GAAG,IAU5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,UAAU,KAAG,MAQzD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,UAAU,GAAG,IAQtE,CAAC"}

package/dist/auth/token_scope.js

@@ -0,0 +1,190 @@
+/**
+ * `TokenScope` — the per-credential authority narrowing stored on
+ * `api_token.scope`.
+ *
+ * Twin of the Rust spine's `fuz_auth::token_scope`. The stored document is the
+ * wire contract; both spines read the same `api_token.scope` JSONB, so the
+ * `kind` strings, the field names, and the version constant must match exactly.
+ *
+ * ## The whole vocabulary
+ *
+ * Two variants, and three rules:
+ *
+ * 1. **`full` must be spelled at mint.** `account_token_create` takes a required
+ *    `scope`, the column is `NOT NULL`, and session / daemon-token credentials
+ *    resolve to `full` by construction. There is no absent state — which is the
+ *    whole point. The 2026-02 `scope` column stored `full` / `read` / `write`
+ *    and nothing enforced them; the reason that was worse than nothing is that
+ *    the absent/unenforced case was indistinguishable from a decision.
+ * 2. **`methods` denies every method it does not list.** An empty list is legal
+ *    and renders the token inert for RPC — unlike an empty `credential_types`
+ *    allowlist, which is rejected because it renders an *action* unreachable.
+ * 3. **A narrowed token is RPC-only.** `methods` denies every non-RPC spine
+ *    surface outright — the db-admin browser, the bare-hash fact read, the
+ *    audit SSE stream, and the WS upgrade. See `token_scope_admits_non_rpc`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Current `TokenScope` document version. Must match the Rust `TOKEN_SCOPE_VERSION`. */
+export const TOKEN_SCOPE_VERSION = 1;
+/**
+ * Serialized-document cap. Matches the Rust `MAX_TOKEN_SCOPE_BYTES` and
+ * fuz_forge's `MAX_POLICY_BYTES`.
+ */
+export const MAX_TOKEN_SCOPE_BYTES = 4 * 1024;
+/**
+ * The stored `api_token.scope` document.
+ *
+ * `grandfathered` is a fact about the *row* — the `api_token_scope` migration
+ * wrote it; no minter chose it — that only the token list cares about. The
+ * enforcement path never branches on it, which is what stops "grandfathered"
+ * from becoming a third authority level.
+ *
+ * Strict on both arms so a v2 document carrying a grant arm a v1 reader doesn't
+ * understand is refused rather than parsed as permissively-narrower-than-stored.
+ * The discriminated union also refuses the contradiction
+ * `{kind: 'full', methods: [...]}`.
+ */
+export const TokenScope = z.discriminatedUnion('kind', [
+    z.strictObject({
+        version: z.literal(TOKEN_SCOPE_VERSION),
+        kind: z.literal('full'),
+        grandfathered: z.boolean().optional()
+    }),
+    z.strictObject({
+        version: z.literal(TOKEN_SCOPE_VERSION),
+        kind: z.literal('methods'),
+        methods: z.array(z.string()),
+        grandfathered: z.boolean().optional()
+    })
+]);
+/**
+ * The `scope` input accepted by `account_token_create` — the stored shape minus
+ * the row-owned fields.
+ *
+ * A minter cannot set `version` or `grandfathered`: the first is stamped by
+ * `token_scope_full` / `token_scope_methods`, and the second is the migration's
+ * mark for tokens that predate scoping. Letting a caller forge `grandfathered`
+ * would turn a tracked debt into a laundered one.
+ */
+export const TokenScopeInput = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('full') }),
+    z.strictObject({ kind: z.literal('methods'), methods: z.array(z.string()) })
+]);
+/** A deliberately-minted full-authority scope. */
+export const token_scope_full = () => ({
+    version: TOKEN_SCOPE_VERSION,
+    kind: 'full'
+});
+/** A narrowed scope over `methods`. */
+export const token_scope_methods = (methods) => ({
+    version: TOKEN_SCOPE_VERSION,
+    kind: 'methods',
+    methods
+});
+/** Build the stored scope from a mint-time input. */
+export const token_scope_from_input = (input) => input.kind === 'full' ? token_scope_full() : token_scope_methods(input.methods);
+/**
+ * Does `scope` admit dispatching `method`?
+ *
+ * Consulted by `perform_action` between the credential gate and the role gate.
+ */
+export const token_scope_admits_method = (scope, method) => scope.kind === 'full' || scope.methods.includes(method);
+/**
+ * Does `scope` admit a non-RPC spine surface?
+ *
+ * **Rule 3, and it is the load-bearing one.** A method-name allowlist alone
+ * would have been a false promise: the db-admin browser serves paginated rows of
+ * any `public` table (including `account.password_hash`, `auth_session`, and
+ * `api_token`) plus row `DELETE`, gated on a global role a bearer credential
+ * satisfies. A token whose UI badge read "scoped to `cell_get`" could still
+ * delete an account row.
+ *
+ * So a narrowed token reaches no non-RPC surface at all. Strictly more
+ * restrictive than naming each surface, no vocabulary to maintain, and one
+ * sentence a user can hold: *a scoped token is RPC-only*.
+ */
+export const token_scope_admits_non_rpc = (scope) => scope.kind === 'full';
+/** Surfaces gated by rule 3. Capability strings match the Rust `TokenSurface`. */
+export const TOKEN_SURFACE_CAPABILITIES = {
+    db_admin: 'surface:db_admin',
+    fact_bare: 'surface:fact_bare',
+    audit_stream: 'surface:audit_stream',
+    ws_upgrade: 'surface:ws_upgrade'
+};
+/**
+ * Build the flat denial body a non-RPC surface returns when a narrowed token
+ * reaches it: `{error: 'token_scope_required', required_scope: 'surface:<name>'}`
+ * at 403.
+ *
+ * One shape for every surface, matching the Rust
+ * `token_scope_surface_denied_response`. These are REST-ish routes whose
+ * sibling denials are already flat, so the JSON-RPC envelope stays with the
+ * dispatcher's per-method gate and stops there.
+ */
+export const token_scope_surface_denied_body = (surface) => ({
+    error: 'token_scope_required',
+    required_scope: TOKEN_SURFACE_CAPABILITIES[surface]
+});
+/** Stable label for the token list / UI. */
+export const token_scope_label = (scope) => {
+    if (scope.kind === 'full')
+        return scope.grandfathered ? 'full (grandfathered)' : 'full';
+    return `${scope.methods.length} methods`;
+};
+/**
+ * Parse a stored document, enforcing the size cap and the schema.
+ *
+ * **Fail-closed**: returns `null` on an unreadable document, and every caller on
+ * the enforcement path treats `null` as "refuse the credential" rather than
+ * "allow everything". fuz_forge's hydrate path deliberately widens on a DB blip
+ * — safe there only because a role gate still applies. Here the scope *is* the
+ * gate, so widening on a parse failure would hand a narrowed token full
+ * authority exactly when something is already wrong.
+ */
+export const parse_token_scope = (raw) => {
+    if (raw.length > MAX_TOKEN_SCOPE_BYTES)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const parsed = TokenScope.safeParse(value);
+    return parsed.success ? parsed.data : null;
+};
+/**
+ * Serialize for storage, enforcing the size cap.
+ *
+ * Throws on an over-cap document — the mint path maps that to a 400, matching
+ * the Rust side's `TokenScopeError::TooLarge`.
+ */
+export const serialize_token_scope = (scope) => {
+    const json = JSON.stringify(scope);
+    if (json.length > MAX_TOKEN_SCOPE_BYTES) {
+        throw new Error(`token scope document is ${json.length} bytes, exceeding the ${MAX_TOKEN_SCOPE_BYTES} byte cap`);
+    }
+    return json;
+};
+/**
+ * Read a stored `api_token.scope` value back into a `TokenScope`, or `null`
+ * when the document is unreadable.
+ *
+ * The DB driver may hand `scope` back already-parsed (JSONB → object) or as
+ * text depending on backend, so both are normalized here rather than at each
+ * call site. Lives here rather than beside the queries so the pure scope module
+ * owns every parse — and so mocking the query module doesn't drag this along.
+ */
+export const parse_stored_token_scope = (value) => {
+    if (typeof value === 'string')
+        return parse_token_scope(value);
+    // `JSON.stringify(undefined)` returns `undefined`, not a string — so a row
+    // missing the column entirely must be caught here rather than reaching
+    // `parse_token_scope` and throwing on `.length`. Absent is *unreadable*,
+    // which is fail-closed: the caller refuses the credential.
+    const json = JSON.stringify(value);
+    return json === undefined ? null : parse_token_scope(json);
+};