@fuzdev/fuz_app 0.106.1 → 0.108.0

package/dist/auth/token_scope.d.ts

@@ -88,37 +88,125 @@ export declare const token_scope_admits_method: (scope: TokenScope, method: stri
 /**
  * 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.
+ * **A narrowed token reaches no non-RPC surface at all** — the load-bearing
+ * half of token scoping, and what "rule 3" names wherever this module's
+ * callers and the Rust twin use that shorthand. See `docs/security.md`
+ * §Token scoping.
  *
- * 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*.
+ * 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.
+ *
+ * Denying every non-RPC surface outright is strictly more restrictive than
+ * naming each one, keeps no vocabulary to maintain, and fits in 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";
+/**
+ * The non-RPC surfaces the **spine itself** mounts (rule 3). Twin of the Rust
+ * `TokenSurface` enum, name for name.
+ *
+ * Not a registry a consumer registers into. `RouteAuth.required_scope` accepts
+ * any well-formed `surface:<name>` (see `parse_token_scope_capability`), so a
+ * consumer names its own non-RPC surface without an upstream release. This
+ * tuple is what the *spine* may declare, and what its surface census iterates
+ * — the closure is a check on fuz_app's own routes, not a vocabulary consumers
+ * have to ask permission to extend.
+ *
+ * A surface name never decides anything: rule 3 is all-or-nothing
+ * (`token_scope_admits_non_rpc`), so the name only labels *which* surface
+ * refused, in the `required_scope` a denial reports. That is the same field
+ * whose `rpc:<method>` arm has always carried arbitrary consumer method names.
+ */
+export declare const TOKEN_SURFACES: readonly ["db_admin", "fact_bare", "audit_stream", "ws_upgrade"];
+export type TokenSurface = (typeof TOKEN_SURFACES)[number];
+/**
+ * Is `value` one of the surfaces the spine mounts?
+ *
+ * Membership, not well-formedness — `parse_token_scope_capability` is the format
+ * check the guard resolver runs on a declaration, and it is deliberately looser.
+ * Used where the *spine's* own surfaces are the question: the direct-call denial
+ * helpers, and the census assertion that fuz_app declares no surface it doesn't
+ * mount.
+ */
+export declare const is_token_surface: (value: string) => value is TokenSurface;
+/**
+ * Name format for the identifier half of a capability string. Mirrors
+ * `RoleName` / `CredentialTypeName` / `ScopeKindName`.
+ *
+ * Applied to the `surface:` arm only. The `rpc:` arm's identifier is an action
+ * method name, whose vocabulary belongs to `ActionSpec` (and includes shapes
+ * like `peer/ping` this regex would refuse) — the capability parser checks it
+ * is non-empty and leaves the rest to the registry that owns it.
+ */
+export declare const TOKEN_SURFACE_NAME_REGEX: RegExp;
+/**
+ * The capability string an action method is refused under: `rpc:<method>`.
+ *
+ * Exported because two sites *compute* one — the dispatcher's per-method gate
+ * and the REST bridge, which must agree — where a `surface:` capability is
+ * always written as a literal on a route spec, so nothing computes one.
+ */
+export declare const token_scope_method_capability: (method: string) => string;
+/**
+ * A parsed `required_scope` capability — what a route demands of the calling
+ * credential's `TokenScope`.
+ *
+ * `capability` is the wire string verbatim, carried rather than re-derived so a
+ * denial reports exactly what the route declared. The arms are asymmetric on
+ * purpose, and the asymmetry is the whole design: the `rpc:` identifier is
+ * **consumed by a predicate** (`token_scope_admits_method`), so it is kept; the
+ * `surface:` identifier is **pure label**, because rule 3 is all-or-nothing
+ * (`token_scope_admits_non_rpc` never looks at which surface). That is why one
+ * half of the vocabulary needs no registry.
+ */
+export type TokenScopeCapability = {
+    kind: 'rpc';
+    capability: string;
+    method: string;
+} | {
+    kind: 'surface';
+    capability: string;
 };
-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.
+ * Parse a capability string into the question it asks, or `null` when it is
+ * not a capability at all.
+ *
+ * Callers turn `null` into a registration-time throw: `RouteAuth.required_scope`
+ * is typed as a plain string so `http/` needs no `auth/` import, and this is the
+ * single point where that string becomes a mounted guard, so it is where the
+ * value gets checked. Refusing an unknown prefix is what keeps the `surface:`
+ * namespace fuz_app's own — a route cannot mint an `rpc:`-looking capability out
+ * of a surface gate, which would put a method name in front of a whole-surface
+ * refusal.
+ *
+ * @param value - the declared capability string, e.g. `surface:audit_stream`
+ * @returns the parsed capability, or `null` on an unknown prefix / empty or malformed identifier
+ */
+export declare const parse_token_scope_capability: (value: string) => TokenScopeCapability | null;
+/**
+ * Does `scope` admit `capability`?
+ *
+ * The one place the two arms of the vocabulary meet their two predicates, so a
+ * `surface:` capability can never be answered by a method-list membership test
+ * (which would let a narrowed token onto a surface by listing a method named
+ * after it) and an `rpc:` capability can never be answered by rule 3 (which
+ * would refuse a token the method it was minted for).
+ */
+export declare const token_scope_admits_capability: (scope: TokenScope, capability: TokenScopeCapability) => boolean;
+/**
+ * Build the flat denial body a non-RPC route returns when a narrowed token
+ * reaches a capability it lacks:
+ * `{error: 'token_scope_required', required_scope: '<section>:<id>'}` at 403.
  *
- * One shape for every surface, matching the Rust
+ * One shape for every capability, 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) => {
+export declare const token_scope_denied_body: (capability: string) => {
     error: "token_scope_required";
     required_scope: string;
 };

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,UAAU,KAAG,OAAgC,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,kEAAmE,CAAC;AAC/F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,YACA,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,QAAgC,CAAC;AAQtE;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,QAAQ,MAAM,KAAG,MAC3B,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GAAI,OAAO,MAAM,KAAG,oBAAoB,GAAG,IAUnF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,OAAO,UAAU,EACjB,YAAY,oBAAoB,KAC9B,OAGkC,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,YAAY,MAAM,KAChB;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

@@ -94,38 +94,123 @@ export const token_scope_admits_method = (scope, method) => scope.kind === 'full
 /**
  * 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.
+ * **A narrowed token reaches no non-RPC surface at all** — the load-bearing
+ * half of token scoping, and what "rule 3" names wherever this module's
+ * callers and the Rust twin use that shorthand. See `docs/security.md`
+ * §Token scoping.
  *
- * 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*.
+ * 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.
+ *
+ * Denying every non-RPC surface outright is strictly more restrictive than
+ * naming each one, keeps no vocabulary to maintain, and fits in 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'
+/**
+ * The non-RPC surfaces the **spine itself** mounts (rule 3). Twin of the Rust
+ * `TokenSurface` enum, name for name.
+ *
+ * Not a registry a consumer registers into. `RouteAuth.required_scope` accepts
+ * any well-formed `surface:<name>` (see `parse_token_scope_capability`), so a
+ * consumer names its own non-RPC surface without an upstream release. This
+ * tuple is what the *spine* may declare, and what its surface census iterates
+ * — the closure is a check on fuz_app's own routes, not a vocabulary consumers
+ * have to ask permission to extend.
+ *
+ * A surface name never decides anything: rule 3 is all-or-nothing
+ * (`token_scope_admits_non_rpc`), so the name only labels *which* surface
+ * refused, in the `required_scope` a denial reports. That is the same field
+ * whose `rpc:<method>` arm has always carried arbitrary consumer method names.
+ */
+export const TOKEN_SURFACES = ['db_admin', 'fact_bare', 'audit_stream', 'ws_upgrade'];
+/**
+ * Is `value` one of the surfaces the spine mounts?
+ *
+ * Membership, not well-formedness — `parse_token_scope_capability` is the format
+ * check the guard resolver runs on a declaration, and it is deliberately looser.
+ * Used where the *spine's* own surfaces are the question: the direct-call denial
+ * helpers, and the census assertion that fuz_app declares no surface it doesn't
+ * mount.
+ */
+export const is_token_surface = (value) => TOKEN_SURFACES.includes(value);
+/**
+ * Name format for the identifier half of a capability string. Mirrors
+ * `RoleName` / `CredentialTypeName` / `ScopeKindName`.
+ *
+ * Applied to the `surface:` arm only. The `rpc:` arm's identifier is an action
+ * method name, whose vocabulary belongs to `ActionSpec` (and includes shapes
+ * like `peer/ping` this regex would refuse) — the capability parser checks it
+ * is non-empty and leaves the rest to the registry that owns it.
+ */
+export const TOKEN_SURFACE_NAME_REGEX = /^[a-z][a-z_]*[a-z]$|^[a-z]$/;
+// Capability-string prefixes. Private: `token_scope_method_capability` builds
+// the one capability anything computes, and `parse_token_scope_capability` reads
+// one back, so nothing outside this module concatenates these itself.
+const CAPABILITY_RPC_PREFIX = 'rpc:';
+const CAPABILITY_SURFACE_PREFIX = 'surface:';
+/**
+ * The capability string an action method is refused under: `rpc:<method>`.
+ *
+ * Exported because two sites *compute* one — the dispatcher's per-method gate
+ * and the REST bridge, which must agree — where a `surface:` capability is
+ * always written as a literal on a route spec, so nothing computes one.
+ */
+export const token_scope_method_capability = (method) => `${CAPABILITY_RPC_PREFIX}${method}`;
+/**
+ * Parse a capability string into the question it asks, or `null` when it is
+ * not a capability at all.
+ *
+ * Callers turn `null` into a registration-time throw: `RouteAuth.required_scope`
+ * is typed as a plain string so `http/` needs no `auth/` import, and this is the
+ * single point where that string becomes a mounted guard, so it is where the
+ * value gets checked. Refusing an unknown prefix is what keeps the `surface:`
+ * namespace fuz_app's own — a route cannot mint an `rpc:`-looking capability out
+ * of a surface gate, which would put a method name in front of a whole-surface
+ * refusal.
+ *
+ * @param value - the declared capability string, e.g. `surface:audit_stream`
+ * @returns the parsed capability, or `null` on an unknown prefix / empty or malformed identifier
+ */
+export const parse_token_scope_capability = (value) => {
+    if (value.startsWith(CAPABILITY_RPC_PREFIX)) {
+        const method = value.slice(CAPABILITY_RPC_PREFIX.length);
+        return method.length > 0 ? { kind: 'rpc', capability: value, method } : null;
+    }
+    if (value.startsWith(CAPABILITY_SURFACE_PREFIX)) {
+        const surface = value.slice(CAPABILITY_SURFACE_PREFIX.length);
+        return TOKEN_SURFACE_NAME_REGEX.test(surface) ? { kind: 'surface', capability: value } : null;
+    }
+    return null;
 };
 /**
- * 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.
+ * Does `scope` admit `capability`?
+ *
+ * The one place the two arms of the vocabulary meet their two predicates, so a
+ * `surface:` capability can never be answered by a method-list membership test
+ * (which would let a narrowed token onto a surface by listing a method named
+ * after it) and an `rpc:` capability can never be answered by rule 3 (which
+ * would refuse a token the method it was minted for).
+ */
+export const token_scope_admits_capability = (scope, capability) => capability.kind === 'rpc'
+    ? token_scope_admits_method(scope, capability.method)
+    : token_scope_admits_non_rpc(scope);
+/**
+ * Build the flat denial body a non-RPC route returns when a narrowed token
+ * reaches a capability it lacks:
+ * `{error: 'token_scope_required', required_scope: '<section>:<id>'}` at 403.
  *
- * One shape for every surface, matching the Rust
+ * One shape for every capability, 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) => ({
+export const token_scope_denied_body = (capability) => ({
     error: 'token_scope_required',
-    required_scope: TOKEN_SURFACE_CAPABILITIES[surface]
+    required_scope: capability
 });
 /** Stable label for the token list / UI. */
 export const token_scope_label = (scope) => {

package/dist/http/CLAUDE.md

@@ -43,7 +43,7 @@ consumers.
 
 - `method` — `'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'`
 - `path` — Hono path (supports `:param` segments)
-- `auth: RouteAuth` — flat record `{account, actor, roles?, credential_types?}` from `http/auth_shape.ts`. Each axis is `'none' | 'optional' | 'required'`. Same shape governs `ActionSpec.auth` (see `actions/CLAUDE.md`).
+- `auth: RouteAuth` — flat record `{account, actor, roles?, credential_types?, required_scope?}` from `http/auth_shape.ts`. `account` / `actor` are `'none' | 'optional' | 'required'`. `required_scope` names the capability a narrowed api token's scope must admit — `surface:<name>` (a non-RPC surface, refused to every narrowed token) or `rpc:<method>` (one action method) — and is route-spec-only: `compile_action_registry` rejects it on an `ActionSpec`, where the dispatcher derives the same capability from `spec.method`. Otherwise the same shape governs `ActionSpec.auth` (see `actions/CLAUDE.md`).
 - `handler: RouteHandler` — `(c: Context, route: RouteContext) => Response | Promise<Response>`
 - `description` — free-text, surfaced in `AppSurface`
 - `params?: z.ZodObject` — strict-object schema for URL path params
@@ -97,20 +97,22 @@ wrapper). See `auth/signup_routes.ts`.
 
 1. **Params validation** — `spec.params` → `validated_params` context var; mismatch returns 400 `ERROR_INVALID_ROUTE_PARAMS` with Zod `issues`
 2. **Query validation** — `spec.query` → `validated_query`; mismatch returns 400 `ERROR_INVALID_QUERY_PARAMS`
-3. **Pre-validation auth guards** — `require_auth` (401 `ERROR_AUTHENTICATION_REQUIRED`) when `auth.account === 'required'` or `auth.actor === 'required'`. Fires before any body parsing so unauthenticated callers never see route-shape information from input parse failures. The `AuthGuardResolver` (e.g. `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`) returns this set as `pre_validation: Array<MiddlewareHandler>`.
-4. **Input validation** — JSON body parsed + validated; mismatch returns 400 `ERROR_INVALID_JSON_BODY` (not JSON) or `ERROR_INVALID_REQUEST_BODY` (schema failure with `issues`). Skipped on GET and `z.null()` inputs. The validated input lands on `c.var.validated_input` so the authorization phase reads `acting` as a typed Zod field.
-5. **Authorization phase** — when `spec.auth.actor !== 'none'`, resolves the acting actor against `c.var.account_id` (set by the auth middleware) plus `validated_input.acting` (or `validated_query.acting` for GET routes), builds `RequestContext` via `build_request_context`, and sets `REQUEST_CONTEXT_KEY`. When `auth.account !== 'none' && auth.actor === 'none'`, an account-only context is built. Resolution failures return 400 `ERROR_ACTOR_REQUIRED` (with `available[]`) or `ERROR_ACTOR_NOT_ON_ACCOUNT` (or 500 `ERROR_NO_ACTORS_ON_ACCOUNT` on signup-invariant violation, 500 `ERROR_ACCOUNT_VANISHED` on torn account/actor reads after a successful resolve). Public routes (`account: 'none' && actor: 'none'`) skip this phase entirely.
-6. **Post-authorization auth guards** — `require_credential_types(types)` (403 `ERROR_CREDENTIAL_TYPE_REQUIRED` with `required_credential_types: ReadonlyArray<string>`) fires first when `auth.credential_types?.length`; `require_role(roles)` (403 `ERROR_INSUFFICIENT_PERMISSIONS` with `required_roles: ReadonlyArray<string>`) fires next when `auth.roles?.length`. Both read `REQUEST_CONTEXT_KEY` populated by step 5. Multi-role specs admit any-of via `has_any_scoped_role(ctx, roles, null)`.
+3. **Pre-authorization auth guards** — every gate that reads only what the auth middleware set, in coarse-to-fine order: `require_auth` (401 `ERROR_AUTHENTICATION_REQUIRED`) when `auth.account === 'required'` or `auth.actor === 'required'`; `require_credential_types(types)` (403 `ERROR_CREDENTIAL_TYPE_REQUIRED` with `required_credential_types: ReadonlyArray<string>`) when `auth.credential_types?.length`; `require_token_scope(capability)` (403 `ERROR_TOKEN_SCOPE_REQUIRED` with `required_scope`, the token-scope refusal) when `auth.required_scope` names a capability. All fire before any body parsing — so a caller they refuse never sees route-shape information from input parse failures — and before actor resolution, so a wrong channel costs no DB work and never learns account state (e.g. that the account is multi-actor). The `AuthGuardResolver` (e.g. `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`) returns this set as `pre_authorization: Array<MiddlewareHandler>`.
+4. **Authorization phase** — when `spec.auth.actor !== 'none'`, resolves the acting actor against `c.var.account_id` (set by the auth middleware) plus the `acting` selector (`validated_query.acting` on GETs; read off the raw body on mutations, since body validation now runs after the gates), builds `RequestContext` via `build_request_context`, and sets `REQUEST_CONTEXT_KEY`. When `auth.account !== 'none' && auth.actor === 'none'`, an account-only context is built. Resolution failures return 400 `ERROR_ACTOR_REQUIRED` (with `available[]`) or `ERROR_ACTOR_NOT_ON_ACCOUNT` (or 500 `ERROR_NO_ACTORS_ON_ACCOUNT` on signup-invariant violation, 500 `ERROR_ACCOUNT_VANISHED` on torn account/actor reads after a successful resolve). Public routes (`account: 'none' && actor: 'none'`) skip this phase entirely.
+5. **Post-authorization auth guards** — `require_role(roles)` (403 `ERROR_INSUFFICIENT_PERMISSIONS` with `required_roles: ReadonlyArray<string>`) when `auth.roles?.length`. The only gate in this phase, because it is the only one that reads `REQUEST_CONTEXT_KEY` (populated by step 4) rather than the auth middleware's own context vars. Multi-role specs admit any-of via `has_any_scoped_role(ctx, roles, null)`.
+6. **Input validation** — JSON body parsed + validated; mismatch returns 400 `ERROR_INVALID_JSON_BODY` (not JSON) or `ERROR_INVALID_REQUEST_BODY` (schema failure with `issues`). Skipped on GET and `z.null()` inputs. The validated input lands on `c.var.validated_input`.
 7. **Handler** — wrapped in transaction when `use_transaction` (see above), receives `RouteContext`
 8. **DEV-only output + error validation** — wraps the handler (see below)
 9. **Error catch** — catches `ThrownJsonrpcError` → maps to HTTP status + the flat REST `ApiError` body (`{error: <reason>, message?, ...rest_data}`); catches generic `Error` → 500 `{error: 'internal_error', message?}` (message only in DEV). The reason string comes from `err.data.reason` when set (consumer-supplied canonical reason override) or from `jsonrpc_error_code_to_name(err.code)` (e.g. `-32003 → 'not_found'`). The flat shape matches what middleware and direct handlers emit — REST callers see one envelope across every emit site, while the JSON-RPC dispatcher keeps its own `{jsonrpc, id, error: {code, message, data}}` envelope on the RPC mount.
 
-**Ordering: 401 → 400 → 403 → handler.** Mirrors the RPC dispatcher
-(`actions/action_rpc.ts`) so HTTP RPC and REST fail with the same priority.
-The alternative (403-before-400) was rejected because defense-in-depth via
-attack-surface obscurity is illusory when the surface is published in
-`library.json` codegen anyway. The trade-off is that an
-authenticated-but-unauthorized caller can distinguish 400 from 403.
+**Ordering: 401 → authz → 403 → 400 → handler.** Mirrors the RPC dispatcher
+(`actions/action_rpc.ts`) so HTTP RPC and REST fail with the same priority, and
+matches the Rust spine, which validates handler-side. Body validation runs last
+so a caller the authority gates refuse learns nothing about the route's input
+shape — a 400 would confirm the route exists and describe how to call it.
+Params and query still validate first: they are part of addressing the route,
+not of its payload, and the authorization phase reads `acting` off the query on
+GETs.
 
 Duplicate `method path` pairs throw at registration.
 
@@ -501,6 +503,16 @@ Param schemas use `VALID_SQL_IDENTIFIER` regex, and every table name gets
 `assert_valid_sql_identifier()` before string-interpolating into SQL —
 the identifier validation is the only reason the interpolation is safe.
 
+**Do not widen the auth on these specs.** They serve paginated rows of any
+`public` table — `account.password_hash`, `auth_session`, `api_token` — plus
+row `DELETE`. `credential_types: ['daemon_token']` is what keeps every bearer
+credential out, and it's why the specs need no `auth.required_scope`: a daemon
+token resolves to `full` by construction, so no narrowed token can reach them
+(see ../../../docs/security.md §Token scoping). Re-auth them to a role a bearer
+satisfies and both controls are gone at once — the token's scope stops
+applying and the credential gate stops firing. A consumer that does this owns
+the surface census for it.
+
 Interfaces exported for consumer use: `TableInfo`, `TableWithCount`,
 `PrimaryKeyInfo`, `ColumnInfo`, `DbRouteOptions`.
 

package/dist/http/auth_shape.d.ts

@@ -1,5 +1,5 @@
 /**
- * Canonical four-axis auth shape for action specs and route specs.
+ * Canonical auth shape for action specs and route specs.
  *
  * Replaces the discriminated `'public' | 'authenticated' | 'keeper' | {role}`
  * literal that conflated authentication, account resolution, actor resolution,
@@ -11,6 +11,9 @@
  * - `roles` — disjunction of permitted roles (any-of); absent = no role check.
  * - `credential_types` — restricts the credential channel (e.g. daemon_token);
  *   absent = any authenticated credential.
+ * - `required_scope` — the capability an api token's scope must admit to reach
+ *   this route (`rpc:<method>` or `surface:<name>`); route specs only,
+ *   absent = no scope gate.
  *
  * The same shape governs both `ActionSpec.auth` (in `actions/action_spec.ts`)
  * and `RouteSpec.auth` (in `http/route_spec.ts`). The canonical schema
@@ -52,6 +55,27 @@ import { z } from 'zod';
  */
 export declare const ActingActor: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
 export type ActingActor = z.infer<typeof ActingActor>;
+/**
+ * Read an `acting` selector out of an unvalidated value.
+ *
+ * The authorization phase runs **before** input validation on both dispatchers
+ * (see `http/CLAUDE.md` §Validation pipeline), so it reads the selector raw.
+ *
+ * **A malformed selector reads as omitted, not as an error.** Safe because
+ * `acting` only ever picks among actors the resolved account already owns — a
+ * value that names nothing grants nothing — and because the typed input schema
+ * rejects it a step later, so the caller still gets a 400. Refusing here
+ * instead would put an input-shape complaint ahead of the authority gates,
+ * which is the ordering this pipeline exists to avoid.
+ *
+ * Both callers pass through here so that rule has one home: the action
+ * dispatcher's `read_acting` and the REST authorization handler's
+ * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`.
+ *
+ * @param value - the raw `acting` field, from params / query / body
+ * @returns the actor id, or `undefined` when absent or malformed
+ */
+export declare const parse_acting: (value: unknown) => string | undefined;
 /**
  * Per-axis auth state — names the dispatcher's behavior on `account` and
  * `actor` independently:
@@ -73,7 +97,7 @@ export declare const AuthAxisState: z.ZodEnum<{
 }>;
 export type AuthAxisState = z.infer<typeof AuthAxisState>;
 /**
- * The canonical four-axis auth shape used by both `ActionSpec.auth` and
+ * The canonical auth shape used by both `ActionSpec.auth` and
  * `RouteSpec.auth`.
  *
  * Cross-axis registry invariants enforced via `.superRefine`:
@@ -85,7 +109,11 @@ export type AuthAxisState = z.infer<typeof AuthAxisState>;
  *    is invalid in v1. The credential resolver always binds account before
  *    actor today; agent-token / group-actor credentials will lift this.
  * 4. **Unrestricted is leaf.** `account === 'none' && actor === 'none'`
- *    ⟹ no `roles`, no `credential_types` (nothing left to gate).
+ *    ⟹ no `roles`, no `credential_types` (nothing left to gate). The same
+ *    rule covers `required_scope`, but enforcing it needs the capability
+ *    vocabulary from `auth/`, so it lives with the other `required_scope`
+ *    check in `fuz_auth_guard_resolver` — which is also the only site every
+ *    route spec traverses, since the route pipeline never parses this schema.
  *
  * Invariant 2 — the `actor !== 'none' ⟺ input or query declares
  * acting?: ActingActor` biconditional — needs introspection of the
@@ -106,6 +134,33 @@ export declare const RouteAuth: z.ZodObject<{
     }>;
     roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    /**
+     * The capability a **narrowed** api token's scope must admit to reach this
+     * route, in the `<section>:<id>` vocabulary a denial reports back as
+     * `required_scope`:
+     *
+     * - `surface:<name>` — a non-RPC surface, refused to every narrowed token
+     *   whatever its method list says (token scoping's rule that a narrowed
+     *   token is RPC-only). `surface:audit_stream` and `surface:fact_bare` are
+     *   the spine's; a consumer names its own without registering it.
+     * - `rpc:<method>` — one action method, refused unless the token lists it.
+     *   What a route bridged from an `ActionSpec` declares: it carries the
+     *   method's identity but never reaches the dispatcher's per-method gate.
+     *
+     * Declaring it makes the guard resolver mount the refusal ahead of the role
+     * gate, instead of the route hand-rolling the check in its handler (which
+     * the auth phase has already role-gated by then, so a narrowed token whose
+     * account lacks the role would be told about the role rather than about the
+     * scope).
+     *
+     * Opt-in rather than blanket: the account REST routes cross no boundary, and
+     * the RPC endpoint runs its own per-method check inside the dispatcher — and
+     * both are route specs too.
+     *
+     * Typed as a plain string here to keep `http/` from importing `auth/`; the
+     * resolver parses it at registration and throws on a malformed one.
+     */
+    required_scope: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type RouteAuth = z.infer<typeof RouteAuth>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;kBA6CnB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}
+{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;IAMpB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;;kBAyCF,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}

package/dist/http/auth_shape.js

@@ -1,5 +1,5 @@
 /**
- * Canonical four-axis auth shape for action specs and route specs.
+ * Canonical auth shape for action specs and route specs.
  *
  * Replaces the discriminated `'public' | 'authenticated' | 'keeper' | {role}`
  * literal that conflated authentication, account resolution, actor resolution,
@@ -11,6 +11,9 @@
  * - `roles` — disjunction of permitted roles (any-of); absent = no role check.
  * - `credential_types` — restricts the credential channel (e.g. daemon_token);
  *   absent = any authenticated credential.
+ * - `required_scope` — the capability an api token's scope must admit to reach
+ *   this route (`rpc:<method>` or `surface:<name>`); route specs only,
+ *   absent = no scope gate.
  *
  * The same shape governs both `ActionSpec.auth` (in `actions/action_spec.ts`)
  * and `RouteSpec.auth` (in `http/route_spec.ts`). The canonical schema
@@ -55,6 +58,30 @@ import { zod_unwrap_to_object } from '@fuzdev/fuz_util/zod.ts';
 export const ActingActor = Uuid.optional().meta({
     description: 'Actor on the authenticated account that this request acts as. Omit on single-actor accounts; required on multi-actor.'
 });
+/**
+ * Read an `acting` selector out of an unvalidated value.
+ *
+ * The authorization phase runs **before** input validation on both dispatchers
+ * (see `http/CLAUDE.md` §Validation pipeline), so it reads the selector raw.
+ *
+ * **A malformed selector reads as omitted, not as an error.** Safe because
+ * `acting` only ever picks among actors the resolved account already owns — a
+ * value that names nothing grants nothing — and because the typed input schema
+ * rejects it a step later, so the caller still gets a 400. Refusing here
+ * instead would put an input-shape complaint ahead of the authority gates,
+ * which is the ordering this pipeline exists to avoid.
+ *
+ * Both callers pass through here so that rule has one home: the action
+ * dispatcher's `read_acting` and the REST authorization handler's
+ * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`.
+ *
+ * @param value - the raw `acting` field, from params / query / body
+ * @returns the actor id, or `undefined` when absent or malformed
+ */
+export const parse_acting = (value) => {
+    const parsed = ActingActor.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+};
 /**
  * Per-axis auth state — names the dispatcher's behavior on `account` and
  * `actor` independently:
@@ -71,7 +98,7 @@ export const ActingActor = Uuid.optional().meta({
  */
 export const AuthAxisState = z.enum(['none', 'optional', 'required']);
 /**
- * The canonical four-axis auth shape used by both `ActionSpec.auth` and
+ * The canonical auth shape used by both `ActionSpec.auth` and
  * `RouteSpec.auth`.
  *
  * Cross-axis registry invariants enforced via `.superRefine`:
@@ -83,7 +110,11 @@ export const AuthAxisState = z.enum(['none', 'optional', 'required']);
  *    is invalid in v1. The credential resolver always binds account before
  *    actor today; agent-token / group-actor credentials will lift this.
  * 4. **Unrestricted is leaf.** `account === 'none' && actor === 'none'`
- *    ⟹ no `roles`, no `credential_types` (nothing left to gate).
+ *    ⟹ no `roles`, no `credential_types` (nothing left to gate). The same
+ *    rule covers `required_scope`, but enforcing it needs the capability
+ *    vocabulary from `auth/`, so it lives with the other `required_scope`
+ *    check in `fuz_auth_guard_resolver` — which is also the only site every
+ *    route spec traverses, since the route pipeline never parses this schema.
  *
  * Invariant 2 — the `actor !== 'none' ⟺ input or query declares
  * acting?: ActingActor` biconditional — needs introspection of the
@@ -96,7 +127,34 @@ export const RouteAuth = z
     account: AuthAxisState,
     actor: AuthAxisState,
     roles: z.array(z.string()).readonly().optional(),
-    credential_types: z.array(z.string()).readonly().optional()
+    credential_types: z.array(z.string()).readonly().optional(),
+    /**
+     * The capability a **narrowed** api token's scope must admit to reach this
+     * route, in the `<section>:<id>` vocabulary a denial reports back as
+     * `required_scope`:
+     *
+     * - `surface:<name>` — a non-RPC surface, refused to every narrowed token
+     *   whatever its method list says (token scoping's rule that a narrowed
+     *   token is RPC-only). `surface:audit_stream` and `surface:fact_bare` are
+     *   the spine's; a consumer names its own without registering it.
+     * - `rpc:<method>` — one action method, refused unless the token lists it.
+     *   What a route bridged from an `ActionSpec` declares: it carries the
+     *   method's identity but never reaches the dispatcher's per-method gate.
+     *
+     * Declaring it makes the guard resolver mount the refusal ahead of the role
+     * gate, instead of the route hand-rolling the check in its handler (which
+     * the auth phase has already role-gated by then, so a narrowed token whose
+     * account lacks the role would be told about the role rather than about the
+     * scope).
+     *
+     * Opt-in rather than blanket: the account REST routes cross no boundary, and
+     * the RPC endpoint runs its own per-method check inside the dispatcher — and
+     * both are route specs too.
+     *
+     * Typed as a plain string here to keep `http/` from importing `auth/`; the
+     * resolver parses it at registration and throws on a malformed one.
+     */
+    required_scope: z.string().optional()
 })
     .superRefine((value, ctx) => {
     // invariant 1: roles imply actor
@@ -133,7 +191,7 @@ export const RouteAuth = z
         }
     }
 });
-// --- Predicates over the four-axis shape ---
+// --- Predicates over the flat-record shape ---
 //
 // Pure derived reads of `RouteAuth`. Live here so every consumer that
 // branches on the shape (the dispatcher's authorization phase, route