@fuzdev/fuz_app 0.106.0 → 0.107.0

package/dist/http/error_schemas.d.ts

@@ -189,6 +189,25 @@ export declare const CredentialTypeRequiredError: z.ZodObject<{
     required_credential_types: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;
 export type CredentialTypeRequiredError = z.infer<typeof CredentialTypeRequiredError>;
+/**
+ * Token-scope error — returned by the `require_token_scope` guard (and its
+ * direct-call twin `token_scope_surface_denial`) when a **narrowed** api token
+ * reaches a capability its scope does not admit. See
+ * `docs/security.md` §Token scoping.
+ *
+ * `required_scope` carries the capability string the route demands, verbatim
+ * from its `auth.required_scope` — `surface:audit_stream` for a non-RPC
+ * surface, `rpc:<method>` for a bridged action — matching the Rust
+ * `token_scope_surface_denied_response` and the dispatcher's own per-method
+ * denial. Third in the family with `PermissionError` and
+ * `CredentialTypeRequiredError` — each names what the route demanded rather
+ * than what the caller holds.
+ */
+export declare const TokenScopeRequiredError: z.ZodObject<{
+    error: z.ZodLiteral<"token_scope_required">;
+    required_scope: z.ZodString;
+}, z.core.$loose>;
+export type TokenScopeRequiredError = z.infer<typeof TokenScopeRequiredError>;
 /** Rate limit error — returned when a rate limiter rejects the request. */
 export declare const RateLimitError: z.ZodObject<{
     error: z.ZodLiteral<"rate_limit_exceeded">;
@@ -275,12 +294,16 @@ export type RateLimitKey = z.infer<typeof RateLimitKey>;
  * Derivation rules under the new flat-record auth shape:
  * - **Has input / params / query schema**: 400 (`ValidationError`).
  * - **`auth.account === 'required'`** or **`auth.actor === 'required'`**: 401
- *   (`ApiError`) — pre-validation 401 fires when the credential isn't there.
+ *   (`ApiError`) — pre-authorization 401 fires when the credential isn't there.
  *   `'optional'` does not derive 401.
  * - **`auth.roles?.length`**: 403 (`PermissionError` carrying `required_roles`).
  * - **`auth.credential_types?.length`**: 403 (`CredentialTypeRequiredError`
  *   carrying `required_credential_types` — symmetric with `PermissionError`).
  *   Today the only credential gate is keeper; future gates reuse the literal.
+ * - **`auth.required_scope`**: 403 (`TokenScopeRequiredError` carrying
+ *   `required_scope`) — the refusal `require_token_scope` emits.
+ *   A route declaring more than one of these three gates derives the union
+ *   of their shapes, since any of them can be the one that answers.
  * - **`auth.actor !== 'none'`** (`'optional'` or `'required'`): extends 400
  *   with `ActorRequiredError` / `ActorNotOnAccountError` and adds 500 union
  *   of `NoActorsOnAccountError` / `AccountVanishedError`. The dispatcher's

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

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

package/dist/http/error_schemas.js

@@ -195,6 +195,24 @@ export const CredentialTypeRequiredError = z.looseObject({
     error: z.literal(ERROR_CREDENTIAL_TYPE_REQUIRED),
     required_credential_types: z.array(z.string()).readonly()
 });
+/**
+ * Token-scope error — returned by the `require_token_scope` guard (and its
+ * direct-call twin `token_scope_surface_denial`) when a **narrowed** api token
+ * reaches a capability its scope does not admit. See
+ * `docs/security.md` §Token scoping.
+ *
+ * `required_scope` carries the capability string the route demands, verbatim
+ * from its `auth.required_scope` — `surface:audit_stream` for a non-RPC
+ * surface, `rpc:<method>` for a bridged action — matching the Rust
+ * `token_scope_surface_denied_response` and the dispatcher's own per-method
+ * denial. Third in the family with `PermissionError` and
+ * `CredentialTypeRequiredError` — each names what the route demanded rather
+ * than what the caller holds.
+ */
+export const TokenScopeRequiredError = z.looseObject({
+    error: z.literal(ERROR_TOKEN_SCOPE_REQUIRED),
+    required_scope: z.string()
+});
 /** Rate limit error — returned when a rate limiter rejects the request. */
 export const RateLimitError = z.looseObject({
     error: z.literal(ERROR_RATE_LIMIT_EXCEEDED),
@@ -262,27 +280,31 @@ export const derive_error_schemas = ({ auth, has_input = false, has_params = fal
     else if (has_validation) {
         errors[400] = ValidationError;
     }
-    // 401 fires when the dispatcher's pre-validation gate rejects an
+    // 401 fires when the dispatcher's pre-authorization gate rejects an
     // unauthenticated caller — `account === 'required'` (no credential) or
     // `actor === 'required'` (no credential to resolve an actor against,
     // per registry-time invariant 3 forbidding accountless actors in v1).
     if (auth.account === 'required' || auth.actor === 'required') {
         errors[401] = ApiError;
     }
-    // 403 fires when `auth.roles` or `auth.credential_types` rejects a
-    // resolved request context. With both axes set, the 403 body could be
-    // either shape — emit the union so DEV-mode error-schema validation
-    // accepts whichever the dispatcher produced.
-    const has_role_gate = !!auth.roles?.length;
-    const has_credential_gate = !!auth.credential_types?.length;
-    if (has_role_gate && has_credential_gate) {
-        errors[403] = z.union([PermissionError, CredentialTypeRequiredError]);
-    }
-    else if (has_role_gate) {
-        errors[403] = PermissionError;
+    // 403 fires from any of three gates: the token-scope refusal
+    // (`auth.required_scope`, pre-authorization), the credential-type gate, and
+    // the role gate (both post-authorization). A route can declare any
+    // combination, so collect the shapes its gates can emit — in the order they
+    // fire — and union them when there's more than one, so DEV-mode
+    // error-schema validation accepts whichever the pipeline produced.
+    const forbidden_shapes = [];
+    if (auth.required_scope !== undefined)
+        forbidden_shapes.push(TokenScopeRequiredError);
+    if (auth.credential_types?.length)
+        forbidden_shapes.push(CredentialTypeRequiredError);
+    if (auth.roles?.length)
+        forbidden_shapes.push(PermissionError);
+    if (forbidden_shapes.length === 1) {
+        errors[403] = forbidden_shapes[0];
     }
-    else if (has_credential_gate) {
-        errors[403] = CredentialTypeRequiredError;
+    else if (forbidden_shapes.length > 1) {
+        errors[403] = z.union(forbidden_shapes);
     }
     if (rate_limit) {
         errors[429] = RateLimitError;

package/dist/http/route_spec.d.ts

@@ -22,14 +22,20 @@ import { type RouteAuth } from './auth_shape.js';
 /**
  * Two-phase auth guard set returned by `AuthGuardResolver`.
  *
- * `pre_validation` runs before input validation — 401 checks live here
- * so unauthenticated callers never see route-shape information from
- * input parsing failures. `post_authorization` runs after the
- * authorization phase has populated `RequestContext` — role / keeper
- * checks live here because they read `c.var.request_context.role_grants`.
+ * `pre_authorization` runs before the authorization phase — the 401 check
+ * and the rule-3 token-scope refusal live here, so a caller either one turns
+ * away never reaches the actor resolution or the route's body.
+ * `post_authorization` runs after the authorization phase has populated
+ * `RequestContext` — credential / role checks live here because they read
+ * `c.var.request_context.role_grants`.
+ *
+ * Both phases run ahead of body validation, which is why neither is named
+ * for it: route-shape information stays behind every authority gate. The
+ * names say which side of the authorization phase a guard sits on, the only
+ * axis that still distinguishes them.
  */
 export interface AuthGuards {
-    pre_validation: Array<MiddlewareHandler>;
+    pre_authorization: Array<MiddlewareHandler>;
     post_authorization: Array<MiddlewareHandler>;
 }
 /**
@@ -41,12 +47,13 @@ export interface AuthGuards {
  */
 export type AuthGuardResolver = (auth: RouteAuth) => AuthGuards;
 /**
- * Per-route authorization phase. Runs after pre-validation auth guards
- * AND input validation; resolves the acting actor (when `auth.actor !== 'none'`)
- * by reading `c.var.validated_input.acting` and sets the request context on
- * the Hono context. Per-route order in `apply_route_specs`: params → query
- * → pre-validation auth (401) → input validation (400) → authorization
- * phase → post-authorization auth (403) → handler.
+ * Per-route authorization phase. Runs after the pre-authorization auth guards
+ * and before input validation; resolves the acting actor (when `auth.actor !==
+ * 'none'`) from the `acting` selector — `c.var.validated_query.acting` on GETs,
+ * read off the raw body on mutations — and sets the request context on the Hono
+ * context. Per-route order in `apply_route_specs`: params → query →
+ * pre-authorization auth (401 + rule-3 scope) → authorization phase →
+ * post-authorization auth (403) → input validation (400) → handler.
  *
  * Returns a `Response` to short-circuit (resolution failure → 400 / 500),
  * or `void` to continue. The http framework stays auth-agnostic — fuz_app
@@ -221,19 +228,15 @@ export declare const apply_middleware_specs: (app: Hono, specs: Array<Middleware
  * validation, wraps with error catch layer (catches `ThrownJsonrpcError`
  * and generic errors), and registers the route.
  *
- * Per-route middleware order: params → query → pre-validation auth
- * guards (401) → input validation (400) → authorization phase →
- * post-authorization auth guards (403) → handler. The 401 check runs
- * before any body parsing so unauthenticated callers never see
- * route-shape information from parse failures. Input validation runs
- * before the authorization phase (validate first, authorize after) so
- * the authorization phase reads `c.var.validated_input.acting` as a
- * typed Zod field instead of pre-parsing the raw body. Role /
- * credential-type denials still surface 403 last; trade-off is that
- * authenticated-but-unauthorized callers can distinguish 400
- * (validation) from 403 (authorization), a defense-in-depth concession
- * deemed acceptable because the route surface is public via
- * spec/codegen JSON.
+ * Per-route middleware order: params → query → pre-authorization auth
+ * guards (401 + rule-3 scope) → authorization phase →
+ * post-authorization auth guards (403) → input validation (400) →
+ * handler. Body validation runs behind every authority gate, so a caller
+ * any of them refuse never sees route-shape information from a parse
+ * failure — a 400 there would confirm the route exists and describe how
+ * to call it. Params and query still validate first (they address the
+ * route rather than carry its payload, and the authorization phase reads
+ * `acting` off the query on GETs).
  *
  * Each handler receives a `RouteContext` with:
  * - `db`: transaction-scoped when `RouteSpec.transaction` is true; pool-level otherwise
@@ -248,7 +251,7 @@ export declare const apply_middleware_specs: (app: Hono, specs: Array<Middleware
  * `input` only — `ActionSpec` has no `query` shape.
  *
  * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`
- * @param authorize - optional authorization phase; runs after input validation
+ * @param authorize - optional authorization phase; runs after the pre-authorization guards and before the post-authorization guards
  * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
  * @throws Error if two specs share the same `method` + `path` (each combination must be unique), or if any spec violates the actor-acting biconditional

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

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

package/dist/http/route_spec.js

@@ -266,19 +266,15 @@ const build_rest_error_body = (err) => {
  * validation, wraps with error catch layer (catches `ThrownJsonrpcError`
  * and generic errors), and registers the route.
  *
- * Per-route middleware order: params → query → pre-validation auth
- * guards (401) → input validation (400) → authorization phase →
- * post-authorization auth guards (403) → handler. The 401 check runs
- * before any body parsing so unauthenticated callers never see
- * route-shape information from parse failures. Input validation runs
- * before the authorization phase (validate first, authorize after) so
- * the authorization phase reads `c.var.validated_input.acting` as a
- * typed Zod field instead of pre-parsing the raw body. Role /
- * credential-type denials still surface 403 last; trade-off is that
- * authenticated-but-unauthorized callers can distinguish 400
- * (validation) from 403 (authorization), a defense-in-depth concession
- * deemed acceptable because the route surface is public via
- * spec/codegen JSON.
+ * Per-route middleware order: params → query → pre-authorization auth
+ * guards (401 + rule-3 scope) → authorization phase →
+ * post-authorization auth guards (403) → input validation (400) →
+ * handler. Body validation runs behind every authority gate, so a caller
+ * any of them refuse never sees route-shape information from a parse
+ * failure — a 400 there would confirm the route exists and describe how
+ * to call it. Params and query still validate first (they address the
+ * route rather than carry its payload, and the authorization phase reads
+ * `acting` off the query on GETs).
  *
  * Each handler receives a `RouteContext` with:
  * - `db`: transaction-scoped when `RouteSpec.transaction` is true; pool-level otherwise
@@ -293,7 +289,7 @@ const build_rest_error_body = (err) => {
  * `input` only — `ActionSpec` has no `query` shape.
  *
  * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`
- * @param authorize - optional authorization phase; runs after input validation
+ * @param authorize - optional authorization phase; runs after the pre-authorization guards and before the post-authorization guards
  * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
  * @throws Error if two specs share the same `method` + `path` (each combination must be unique), or if any spec violates the actor-acting biconditional
@@ -307,7 +303,7 @@ export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, auth
         }
         registered.add(route_key);
         assert_route_auth_acting_biconditional(spec.auth, { input: spec.input, query: spec.query }, `Route "${route_key}"`);
-        const { pre_validation: pre_validation_guards, post_authorization: post_authorization_guards } = resolve_auth_guards(spec.auth);
+        const { pre_authorization: pre_authorization_guards, post_authorization: post_authorization_guards } = resolve_auth_guards(spec.auth);
         const params_validation = create_params_validation(spec.params);
         const query_validation = create_query_validation(spec.query);
         const input_validation = create_input_validation(spec.input, spec.method);
@@ -344,7 +340,7 @@ export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, auth
         handler = wrap_output_validation(handler, spec.output, merged_errors, log);
         // Step 3: error catch layer
         handler = wrap_error_catch(handler, log);
-        app.on(spec.method, [spec.path], ...params_validation, ...query_validation, ...pre_validation_guards, ...input_validation, ...authorization, ...post_authorization_guards, handler);
+        app.on(spec.method, [spec.path], ...params_validation, ...query_validation, ...pre_authorization_guards, ...authorization, ...post_authorization_guards, ...input_validation, handler);
     }
 };
 /**

package/dist/http/surface_query.d.ts

@@ -8,7 +8,7 @@
  * `filter_keeper_routes`) group the new flat-record `RouteAuth` shape into
  * the legacy categorical buckets (`'authenticated'`, `'role'`, `'keeper'`)
  * for adversarial test runners and the surface explorer. The buckets are
- * derived views over the four axes (`account`, `actor`, `roles`,
+ * derived views over the authority axes (`account`, `actor`, `roles`,
  * `credential_types`) — see `http/auth_shape.ts` for the canonical shape.
  *
  * @module
@@ -65,7 +65,7 @@ export declare const format_route_key: (route: AppSurfaceRoute) => string;
 /**
  * Summarize route auth distribution across the surface.
  *
- * Categorical view over the four-axis flat record. Multi-role specs
+ * Categorical view over the flat auth record. Multi-role specs
  * contribute one count per role they admit.
  *
  * @returns counts by auth category, with role counts broken out by role name

package/dist/http/surface_query.js

@@ -8,7 +8,7 @@
  * `filter_keeper_routes`) group the new flat-record `RouteAuth` shape into
  * the legacy categorical buckets (`'authenticated'`, `'role'`, `'keeper'`)
  * for adversarial test runners and the surface explorer. The buckets are
- * derived views over the four axes (`account`, `actor`, `roles`,
+ * derived views over the authority axes (`account`, `actor`, `roles`,
  * `credential_types`) — see `http/auth_shape.ts` for the canonical shape.
  *
  * @module
@@ -87,7 +87,7 @@ export const format_route_key = (route) => `${route.method} ${route.path}`;
 /**
  * Summarize route auth distribution across the surface.
  *
- * Categorical view over the four-axis flat record. Multi-role specs
+ * Categorical view over the flat auth record. Multi-role specs
  * contribute one count per role they admit.
  *
  * @returns counts by auth category, with role counts broken out by role name

package/dist/server/serve_fact_route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAgBtD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6DjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SAwCF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6DjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA0CF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -93,7 +93,7 @@ import { join } from 'node:path';
 import { FactHashSchema } from '@fuzdev/fuz_util/hash_schemas.ts';
 import { Uuid } from '@fuzdev/fuz_util/id.ts';
 import { z } from 'zod';
-import { build_request_context, get_request_context, has_role, token_scope_surface_denial } from '../auth/request_context.js';
+import { build_request_context, get_request_context, has_role } from '../auth/request_context.js';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 import { ActingActor } from '../http/auth_shape.js';
 import { ACCOUNT_ID_KEY } from '../hono_context.js';
@@ -320,7 +320,17 @@ export const create_serve_fact_route_spec = (options) => {
     return {
         method: 'GET',
         path: '/api/facts/:hash',
-        auth: { account: 'required', actor: 'required', roles: [ROLE_ADMIN] },
+        auth: {
+            account: 'required',
+            actor: 'required',
+            roles: [ROLE_ADMIN],
+            // Rule 3 — a narrowed token gets no bare-hash read. This route
+            // serves *any* stored fact by hash with no per-reference cell check
+            // (that is the per-cell route's job), so it is the broad capability
+            // of the pair; gating it keeps a narrowed token to the cell-scoped
+            // route its RPC methods can justify.
+            required_scope: 'surface:fact_bare'
+        },
         description: 'Serve content-addressed fact bytes by bare hash — admin only. Non-admin reads go through GET /api/cells/:cell_id/facts/:hash (per-reference).',
         params: bare_hash_params_schema,
         // `actor: 'required'` (implied by the admin role gate) needs the
@@ -334,14 +344,6 @@ export const create_serve_fact_route_spec = (options) => {
         errors: params_400_error,
         handler: async (c, route) => {
             const { hash } = get_route_params(c);
-            // Rule 3 — a narrowed token gets no bare-hash read. This route serves
-            // *any* stored fact by hash with no per-reference cell check (that is
-            // the per-cell route's job), so it is the broad capability of the
-            // pair; gating it keeps a narrowed token to the cell-scoped route its
-            // RPC methods can justify.
-            const denied = token_scope_surface_denial(c, 'fact_bare');
-            if (denied)
-                return denied;
             // Defense-in-depth: the auth phase already gated this on the admin
             // role, but re-check the resolved context so a mounting/auth-shape
             // regression fails closed instead of serving by bare hash.

package/dist/testing/CLAUDE.md

@@ -1346,6 +1346,42 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   complete action list plus its own spec. Daemon-token-gated like its siblings;
   the Rust mirror is `fuz_testing::create_testing_action_manifest_action_spec`.
 
+### Token-scope surface parity — `cross_backend/token_scope_surface.ts`
+
+`describe_token_scope_surface_cross_tests({setup_test, capabilities, rpc_path?,
+sse_path?})` — the `surface:<name>` twin of the conformance slate's
+`token_scope_cases`, which cover only the `rpc:<method>` arm. Token scoping's
+RPC-only rule (_a narrowed api token reaches no non-RPC surface_) is the
+load-bearing half of the design and had **no** cross-impl gate: the schema gate
+can't see it (no column), the action-manifest gate can't see it (no method), and
+the spec-derived suites can't see it (REST routes, off the declared RPC surface).
+
+Mints a narrowed bearer through the production `account_token_create` path and
+fires it at the two surfaces whose denial **body** is observable over plain
+HTTP — the audit SSE stream (`capabilities.sse`) and the admin-only bare-hash
+fact read (`capabilities.fact_serving`) — asserting the exact flat
+`{error: 'token_scope_required', required_scope: 'surface:<name>'}` both spines
+contract on (`token_scope_denied_body` ↔
+`fuz_auth::token_scope_surface_denied_response`).
+
+The fifth case is the one with no prior pin anywhere: **scope outranks role**. A
+narrowed token on an account that _also_ lacks the gating role must hear
+`token_scope_required`, not `insufficient_permissions` — the observable the
+TS↔Rust ordering divergence produced before both spines converged on running the
+surface gate ahead of the role gate. Every other scoped-token probe uses the
+keeper's token, whose account holds the role, so both orderings look identical
+there; that is why the divergence survived as long as it did. Verified to
+discriminate: dropping the route's `required_scope` turns it into a 403
+`insufficient_permissions` + `required_roles`, exactly the pre-convergence shape.
+
+Two non-vacuity controls: the narrowed token must still reach the RPC method it
+_does_ name, and a full bearer must get past the scope gate on the same route.
+The WS upgrade is deliberately omitted — `create_ws_transport` threads cookies,
+not bearer headers, and a refused upgrade's body isn't readable, so it can't
+serve a body-parity gate (its per-spine coverage stays in the two surface
+censuses). Cross-process only; fuz_app's own wiring is
+`src/test/cross_backend/token_scope_surface.cross.test.ts`.
+
 ### Origin verification parity — `cross_backend/origin.ts`
 
 `describe_origin_cross_tests({setup_test, capabilities, rpc_path?})` — the
@@ -1396,9 +1432,9 @@ read) it fires three principals over real HTTP: **anonymous** → 401, **session
 proving the daemon-token gate that fences each backdoor action holds end-to-end
 on the real dispatcher (the spec-derived `describe_rpc_attack_surface_tests`
 never enumerates them because they're off the declared surface). Each method is
-sent with **valid** params so the session/bearer cases clear the 400
-input-validation phase and reach the 403 credential gate (order is
-401 → 400 → 403); the handler never runs. Cited property: `docs/security.md`
+sent with **valid** params so each case varies only the credential (validation
+runs after the gates — order is 401 → authz → 403 → 400); the handler never
+runs. Cited property: `docs/security.md`
 §Test Backdoor Actions. Cross-process only (the `_testing_*` actions are
 mounted on the spawned binary, not the in-process app — like the ws/sse
 suites); ungated, since every cross backend that uses

package/dist/testing/cross_backend/conformance_case.js

@@ -141,7 +141,7 @@ export const ConformanceCaseExpectation = z.strictObject({
         description: 'Expected error reason — pass the IMPORTED `ERROR_*` constant from ' +
             '`http/error_schemas.ts`, never a string literal. Asserted against the RPC ' +
             '`error.data.reason` (when the denial carries one) or the REST flat-body ' +
-            '`error` field. The pre-validation 401 carries `data.reason` too; a denial ' +
+            '`error` field. The pre-authorization 401 carries `data.reason` too; a denial ' +
             'that genuinely omits it falls back to the `status` assertion to pin the class.'
     }),
     fields: z

package/dist/testing/cross_backend/testing_backdoor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing_backdoor.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_backdoor.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA2D9B,OAAO,KAAK,EAAE,wBAAwB,EAAe,MAAM,YAAY,CAAC;AAqExE,kEAAkE;AAClE,MAAM,MAAM,+BAA+B,GAAG,wBAAwB,CAAC;AAEvE,eAAO,MAAM,qCAAqC,GACjD,SAAS,+BAA+B,KACtC,IAiCF,CAAC"}
+{"version":3,"file":"testing_backdoor.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_backdoor.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA4D9B,OAAO,KAAK,EAAE,wBAAwB,EAAe,MAAM,YAAY,CAAC;AAqExE,kEAAkE;AAClE,MAAM,MAAM,+BAA+B,GAAG,wBAAwB,CAAC;AAEvE,eAAO,MAAM,qCAAqC,GACjD,SAAS,+BAA+B,KACtC,IAiCF,CAAC"}

package/dist/testing/cross_backend/testing_backdoor.js

@@ -19,7 +19,7 @@ import '../assert_dev_env.js';
  *
  * For every backdoor method, three principals:
  *
- * - **anonymous** (no credential) → `401` (pre-validation auth refuses an
+ * - **anonymous** (no credential) → `401` (pre-authorization auth refuses an
  *   account-less caller before anything else).
  * - **session** (the keeper's browser-context cookie) → `403`
  *   `credential_type_required` — a session cookie, even one carrying the
@@ -28,10 +28,11 @@ import '../assert_dev_env.js';
  *   `credential_type_required` — same ceiling; an api token cannot reach
  *   keeper operations.
  *
- * Each method is sent with **valid** params so the session/bearer cases
- * clear the dispatcher's input-validation (400) phase and actually reach the
- * post-authorization credential gate (the order is 401 → 400 → 403); the
- * handler never runs (the gate refuses first), so the writes never execute.
+ * Each method is sent with **valid** params so each case varies only the
+ * credential. (Validation runs after the gates — the order is 401 → authz →
+ * 403 → 400 — so the shapes are belt-and-suspenders here rather than load-
+ * bearing.) The handler never runs (the gate refuses first), so the writes
+ * never execute.
  *
  * Complements the spec-level gate check (which pins that each spec *declares*
  * `credential_types: ['daemon_token']`) and the surface-absence invariant

package/dist/testing/cross_backend/token_scope_surface.d.ts

@@ -0,0 +1,9 @@
+import '../assert_dev_env.js';
+import type { RpcPathCrossSuiteOptions } from './setup.js';
+/** Options for the token-scope surface parity suite. */
+export interface TokenScopeSurfaceCrossTestOptions extends RpcPathCrossSuiteOptions {
+    /** Audit-log SSE path. Default `/api/admin/audit/stream`. */
+    readonly sse_path?: string;
+}
+export declare const describe_token_scope_surface_cross_tests: (options: TokenScopeSurfaceCrossTestOptions) => void;
+//# sourceMappingURL=token_scope_surface.d.ts.map

package/dist/testing/cross_backend/token_scope_surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token_scope_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/token_scope_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAiE9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAkB3D,wDAAwD;AACxD,MAAM,WAAW,iCAAkC,SAAQ,wBAAwB;IAClF,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2DD,eAAO,MAAM,wCAAwC,GACpD,SAAS,iCAAiC,KACxC,IAwHF,CAAC"}