@fuzdev/fuz_app 0.106.1 → 0.107.0

package/dist/auth/auth_guard_resolver.js

@@ -1,56 +1,90 @@
 /**
  * Auth guard resolver for the route spec system.
  *
- * Maps the four-axis `RouteAuth` (`account` / `actor` / `roles` /
- * `credential_types`) to two-phase middleware sets that
+ * Maps the five-axis `RouteAuth` (`account` / `actor` / `roles` /
+ * `credential_types` / `required_scope`) to two-phase middleware sets that
  * `apply_route_specs` weaves into the per-route pipeline:
  *
- * - `pre_validation` runs before input validation. `require_auth` lands
- *   here whenever `auth.account === 'required'` or `auth.actor ===
- *   'required'` (per registry-time invariant 3, `actor: 'required'`
- *   today implies a credential — accountless actors are out of scope
- *   for v1). Pre-validation 401 fires before any body parsing so
- *   unauthenticated callers never see route-shape information from
- *   parse failures.
- * - `post_authorization` runs after the dispatcher's authorization
- *   phase has populated `RequestContext`. `require_role(roles)` fires
- *   whenever `auth.roles?.length`. `require_credential_types(types)`
- *   fires whenever `auth.credential_types?.length`.
+ * - `pre_authorization` runs before the authorization phase, and holds every
+ *   gate that reads only what the auth middleware already set: `require_auth`
+ *   whenever `auth.account === 'required'` or `auth.actor === 'required'`
+ *   (per registry-time invariant 3, `actor: 'required'` today implies a
+ *   credential — accountless actors are out of scope for v1),
+ *   `require_credential_types(types)` whenever `auth.credential_types?.length`,
+ *   and the token-scope guard whenever `auth.required_scope` names a capability.
+ *   All three fire before any body parsing, so a caller they refuse never sees
+ *   route-shape information — and before the authorization phase, so a wrong
+ *   channel costs no actor resolution.
+ * - `post_authorization` runs after the dispatcher's authorization phase has
+ *   populated `RequestContext`, and holds the one gate that needs it:
+ *   `require_role(roles)`, whenever `auth.roles?.length`, reads
+ *   `c.var.request_context.role_grants`.
+ *
+ * The resulting order — credential presence, then credential type, then scope,
+ * then role — is the spine's canonical coarse-to-fine ordering, the same one
+ * `check_action_auth_post_authorization` runs for actions. A route declaring
+ * both a credential gate and a surface gate therefore answers with the
+ * coarser fact ("this channel may never call me") rather than the finer one
+ * ("your token is scoped"), on both dispatch surfaces alike.
  *
  * Public routes (`auth.account === 'none' && auth.actor === 'none'`)
  * yield empty guard arrays. `'optional'` axes contribute no
- * pre-validation 401; the authorization phase sets `RequestContext`
+ * pre-authorization 401; the authorization phase sets `RequestContext`
  * to whatever the credential supports and the post-authorization
  * gates decide whether the actor's role_grants / credential type match.
  *
  * @module
  */
-import { require_auth, require_credential_types, require_role } from './request_context.js';
+import { require_auth, require_credential_types, require_role, require_token_scope } from './request_context.js';
+import { is_public_auth } from '../http/auth_shape.js';
 /**
  * Standard auth guard resolver for fuz_app.
  *
- * Reads each axis of the four-axis `RouteAuth` shape and emits the
- * corresponding middleware:
+ * Reads each axis of the `RouteAuth` shape and emits the corresponding
+ * middleware:
  *
- * - `account === 'required'` or `actor === 'required'` → pre-validation `require_auth`
+ * - `account === 'required'` or `actor === 'required'` → pre-authorization `require_auth`
+ * - `credential_types?.length` → pre-authorization `require_credential_types(types)`
+ * - `required_scope` → pre-authorization `require_token_scope(capability)`
  * - `roles?.length` → post-authorization `require_role(roles)` (multi-role any-of)
- * - `credential_types?.length` → post-authorization `require_credential_types(types)`
  *
- * Multiple post-authorization guards run in declaration order: credential
- * type check first (since failing it implies the request can never
- * resolve a usable identity), role check second.
+ * Guards run in declaration order, which is the coarse-to-fine order above:
+ * presence first (an anonymous caller holds neither a credential type nor a
+ * scope to check), then the channel, then the scope, then the role — the last
+ * being the only one that needs the resolved `RequestContext`.
+ *
+ * @throws Error if `auth.required_scope` is not a well-formed capability string
+ *   (via `require_token_scope`) — `RouteAuth` types it as a plain string to keep
+ *   `http/` free of an `auth/` import, so this is where the value is checked.
+ *   The check is on *shape*, not membership: the vocabulary is deliberately open
+ *   so a consumer can name its own surface, and a `surface:` name decides
+ *   nothing (rule 3 is all-or-nothing), so the closed set would only have been
+ *   a spelling check on a diagnostic string. fuz_app's own declarations are
+ *   pinned to the surfaces it actually mounts by the surface census.
+ * @throws Error if `auth.required_scope` sits on an unrestricted route
+ *   (`account: 'none' && actor: 'none'`). The same holder reaches that route
+ *   by dropping the credential, so the guard reads as a control and enforces
+ *   nothing — the shape `compile_action_registry` refuses on an `ActionSpec`
+ *   for the same reason. Extends `RouteAuth`'s leaf invariant, which the
+ *   route pipeline never parses.
  */
 export const fuz_auth_guard_resolver = (auth) => {
-    const pre_validation = [];
+    const pre_authorization = [];
     const post_authorization = [];
     if (auth.account === 'required' || auth.actor === 'required') {
-        pre_validation.push(require_auth);
+        pre_authorization.push(require_auth);
     }
     if (auth.credential_types?.length) {
-        post_authorization.push(require_credential_types(auth.credential_types));
+        pre_authorization.push(require_credential_types(auth.credential_types));
+    }
+    if (auth.required_scope !== undefined) {
+        if (is_public_auth(auth)) {
+            throw new Error(`auth.required_scope "${auth.required_scope}" on an unrestricted route (account: 'none', actor: 'none') — the same holder reaches it by dropping the credential, so the guard would enforce nothing. Gate the route on a credential, or drop the field.`);
+        }
+        pre_authorization.push(require_token_scope(auth.required_scope));
     }
     if (auth.roles?.length) {
         post_authorization.push(require_role(auth.roles));
     }
-    return { pre_validation, post_authorization };
+    return { pre_authorization, post_authorization };
 };

package/dist/auth/bearer_auth.d.ts

@@ -23,7 +23,7 @@ import { type RateLimiter } from '../rate_limiter.js';
  *
  * Soft-fails for invalid, expired, or empty tokens — calls `next()` without
  * setting account identity, letting downstream auth enforcement (the RPC
- * dispatcher's pre-validation / post-authorization auth gates or
+ * dispatcher's pre-authorization / post-authorization auth gates or
  * `require_auth`) return a consistent JSON-RPC or route-level error. This
  * avoids leaking token-specific diagnostics
  * (`invalid_token`, `account_not_found`) that could aid enumeration attacks,

package/dist/auth/bearer_auth.js

@@ -26,7 +26,7 @@ import { rate_limit_exceeded_response } from '../rate_limiter.js';
  *
  * Soft-fails for invalid, expired, or empty tokens — calls `next()` without
  * setting account identity, letting downstream auth enforcement (the RPC
- * dispatcher's pre-validation / post-authorization auth gates or
+ * dispatcher's pre-authorization / post-authorization auth gates or
  * `require_auth`) return a consistent JSON-RPC or route-level error. This
  * avoids leaking token-specific diagnostics
  * (`invalid_token`, `account_not_found`) that could aid enumeration attacks,

package/dist/auth/middleware.js

@@ -53,7 +53,7 @@ export const create_auth_middleware_specs = async (deps, options) => {
             // Bearer middleware soft-fails for invalid/expired tokens (calls next()
             // without setting context). Only 429 is a hard-fail from this layer.
             // Auth enforcement (401/403) happens downstream — the RPC dispatcher's
-            // pre-validation / post-authorization auth gates, or `require_auth` /
+            // pre-authorization / post-authorization auth gates, or `require_auth` /
             // `require_role` on REST — producing consistent JSON-RPC or
             // route-level errors.
             errors: { 429: RateLimitError }

package/dist/auth/request_context.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,KAAK,EAEV,KAAK,SAAS,EACd,MAAM,qBAAqB,CAAC;AAY7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AASrD,OAAO,EAIN,KAAK,YAAY,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAIN,oBAAoB,EACpB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC9B;AAED,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,cAAc,GAAG,IAEjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAAI,GAAG,OAAO,KAAG,cAQpD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IAC1D,KAAK,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GACpB,KAAK,cAAc,GAAG,IAAI,EAC1B,MAAM,MAAM,EACZ,MAAK,IAAiB,KACpB,OACoF,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAC3B,KAAK,cAAc,GAAG,IAAI,EAC1B,MAAM,MAAM,EACZ,UAAU,MAAM,GAAG,IAAI,EACvB,MAAK,IAAiB,KACpB,OAKF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,cAAc,GAAG,IAAI,EAC1B,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,UAAU,MAAM,GAAG,IAAI,EACvB,MAAK,IAAiB,KACpB,OAMF,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GACjC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACvF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,MAAM,GAAG,SAAS,KACjC,OAAO,CAAC,wBAAwB,CAclC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,KAAK,MAAM,EACX,4BAAuC,KACrC,iBAgCF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,0BAA0B,GAAI,GAAG,OAAO,EAAE,SAAS,YAAY,KAAG,QAAQ,GAAG,IAMzF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,iBAK1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,aAAa,CAAC,MAAM,CAAC,KAAG,iBAW3D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GACpC,kBAAkB,aAAa,CAAC,MAAM,CAAC,KACrC,iBAiBF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,cAAc,EACnB,MAAM,SAAS,KACb,OAAO,CAAC,cAAc,CAQxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,UAAU,MAAM,KACd,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAUpC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAI/B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GACjC;IAAE,KAAK,EAAE,OAAO,oBAAoB,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACtF;IAAE,KAAK,EAAE,OAAO,0BAA0B,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,OAAO,0BAA0B,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,OAAO,sBAAsB,CAAA;CAAE,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,eAAe,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,GACpD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,IAAI,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,YAAY,MAAM,GAAG,IAAI,EACzB,MAAM,SAAS,EACf,cAAc,MAAM,GAAG,SAAS,KAC9B,OAAO,CAAC,mBAAmB,CAwC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,KACb,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAoB5D,CAAC"}
+{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"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"}

package/dist/auth/request_context.js

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