@fuzdev/fuz_app 0.106.0 → 0.107.0

package/dist/actions/perform_action.js

@@ -5,22 +5,32 @@
  * `perform_action` runs the post-parse pipeline that every action-spec
  * handler must traverse:
  *
- * 1. **Pre-validation auth (401)** — short-circuits unauthenticated callers
- *    on `'required'` axes before input validation runs, so callers never
- *    see `invalid_params` for methods with required input.
- * 2. **Validate params (400)** — `spec.input.safeParse(raw_params)` with
- *    `z.void()` / `?? {}` rules. The validated input lands inside the
- *    function so the authorization phase reads `acting` as a typed Zod
- *    field.
- * 3. **Authorization phase** — when `auth.actor !== 'none'` (or
+ * 1. **Pre-authorization auth (401)** — short-circuits unauthenticated callers
+ *    on `'required'` axes.
+ * 2. **Authorization phase** — when `auth.actor !== 'none'` (or
  *    `auth.account !== 'none' && actor === 'none'`), resolves the actor
  *    via `apply_authorization_phase` against the supplied `account_id`
- *    plus `validated_input.acting`. Failures fold into a JSON-RPC error
- *    envelope. The test-harness escape hatch lives in the caller — pass
+ *    plus the request's `acting` selector, read off the raw params by
+ *    `read_acting`. Failures fold into a JSON-RPC error envelope. The
+ *    test-harness escape hatch lives in the caller — pass
  *    `preset.request_context` to skip the live phase and use a pre-baked
  *    context instead.
- * 4. **Post-authorization auth (403)** — gates `auth.credential_types` and
- *    `auth.roles` against the resolved context.
+ * 3. **Post-authorization auth (403)** — gates `auth.credential_types`,
+ *    the credential's `token_scope`, and `auth.roles` against the resolved
+ *    context.
+ * 4. **Validate params (400)** — `spec.input.safeParse(raw_params)` with
+ *    `z.void()` / `?? {}` rules. Runs **after** the authority gates: a
+ *    400 describing the action's input shape to a caller those gates
+ *    refuse would confirm the method exists and describe how to call it,
+ *    to a channel that should have learned nothing. Coarse authority
+ *    facts before fine ones, and no shape disclosure before authority is
+ *    settled — the same argument that puts the credential gate ahead of
+ *    the scope gate. The cost: a malformed request from an *authenticated*
+ *    caller now pays for the authorization phase's actor + role_grant reads
+ *    before being rejected, where validation used to turn it away first.
+ *    Not a new DoS lever — the same caller reaches that work anyway by
+ *    sending well-formed params — but it does remove a cheap-rejection path
+ *    that buggy clients used to hit.
  * 5. **Rate limit (429)** — per-action IP / account throttling, throttle-
  *    requests semantics (every invocation records, regardless of outcome).
  * 6. **Dispatch + DEV-only output validation + error normalization** —
@@ -45,50 +55,39 @@ import { dispatch_with_post_commit_rollback } from '../http/pending_effects.js';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { jsonrpc_error_messages, jsonrpc_error_code_to_http_status, http_status_to_jsonrpc_error_code, JSONRPC_ERROR_CODES, dev_only } from '../http/jsonrpc_errors.js';
 import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_TOKEN_SCOPE_REQUIRED } from '../http/error_schemas.js';
-import { is_public_auth } from '../http/auth_shape.js';
-import { token_scope_admits_method } from '../auth/token_scope.js';
+import { is_public_auth, needs_actor, parse_acting } from '../http/auth_shape.js';
+import { token_scope_admits_method, token_scope_method_capability } from '../auth/token_scope.js';
 /**
  * The shared dispatch core. Pure data — no Hono context, no socket. Each
  * transport calls into this with pre-parsed inputs and binds the result
  * to its wire shape.
  *
- * Phase order: 401 → 400 → 403 → handler. On the test-preset path the
- * dispatcher skips the live authorization phase and uses the supplied
- * pre-baked context for post-authorization checks; pre-validation 401
- * still fires when the harness omits `account_id`.
+ * Phase order: 401 → authz → 403 → 400 → handler. On the test-preset path
+ * the dispatcher skips the live authorization phase and uses the supplied
+ * pre-baked context for post-authorization checks; the 401 still fires when
+ * the harness omits `account_id`.
  */
 export const perform_action = async (input, deps) => {
     const { action, raw_params, request_id: id, account_id, credential_type, token_scope, client_ip, signal, notify, connection_id, request_client, preset } = input;
     const { db, pending_effects, post_commit_effects, log, action_ip_rate_limiter, action_account_rate_limiter } = deps;
     const { spec, handler } = action;
     const action_auth = spec.auth;
-    // step 1: pre-validation auth — 401 short-circuit before input validation.
-    const pre = check_action_auth_pre_validation(action_auth, account_id);
+    // step 1: pre-authorization auth — 401 short-circuit.
+    const pre = check_action_auth_pre_authorization(action_auth, account_id);
     if (pre)
         return error_result(pre);
-    // step 2: validate params. JSON-RPC 2.0 §4.2 forbids `params: null`;
-    // registration sites reject `z.null()` inputs. Empty-body convention
-    // (`raw_params ?? {}`) lets all-optional-object methods omit `params`.
-    const params = is_void_schema(spec.input) ? raw_params : (raw_params ?? {});
-    const parse_result = spec.input.safeParse(params);
-    if (!parse_result.success) {
-        return error_result(jsonrpc_error_messages.invalid_params('invalid params', dev_only({ issues: parse_result.error.issues })));
-    }
-    const validated_input = parse_result.data;
-    // step 3: authorization phase. `acting` reads off the typed Zod field
-    // validated in step 2. Per registry-time invariant 2,
-    // `auth.actor !== 'none' ⟺ input declares acting?: ActingActor` — so
-    // the typed read is safe whenever the dispatcher needs it.
+    // step 2: authorization phase. `acting` reads off the raw params rather
+    // than a validated field, because validation now runs after the authority
+    // gates. Per registry-time invariant 2,
+    // `auth.actor !== 'none' ⟺ input declares acting?: ActingActor` — so the
+    // selector is present on exactly the specs that need it, and step 4 is
+    // what rejects a malformed one.
     let request_context = null;
     if (preset !== undefined) {
         request_context = preset.request_context;
     }
     else if (!is_public_auth(action_auth)) {
-        const validated_with_acting = validated_input;
-        const acting_value = validated_with_acting && typeof validated_with_acting.acting === 'string'
-            ? validated_with_acting.acting
-            : undefined;
-        const result = await apply_authorization_phase({ db }, account_id, action_auth, acting_value);
+        const result = await apply_authorization_phase({ db }, account_id, action_auth, read_acting(action_auth, raw_params));
         if (!result.ok) {
             const { error: reason, ...rest } = result.body;
             const code = http_status_to_jsonrpc_error_code(result.status);
@@ -102,10 +101,19 @@ export const perform_action = async (input, deps) => {
         // unauthenticated-optional axis; the handler sees null in either case.
         request_context = result.request_context;
     }
-    // step 4: post-authorization auth — credential gate first, role gate second.
+    // step 3: post-authorization auth — credential gate, then scope, then role.
     const post = check_action_auth_post_authorization(action_auth, request_context, credential_type, action.spec.method, token_scope);
     if (post)
         return error_result(post);
+    // step 4: validate params. JSON-RPC 2.0 §4.2 forbids `params: null`;
+    // registration sites reject `z.null()` inputs. Empty-body convention
+    // (`raw_params ?? {}`) lets all-optional-object methods omit `params`.
+    const params = is_void_schema(spec.input) ? raw_params : (raw_params ?? {});
+    const parse_result = spec.input.safeParse(params);
+    if (!parse_result.success) {
+        return error_result(jsonrpc_error_messages.invalid_params('invalid params', dev_only({ issues: parse_result.error.issues })));
+    }
+    const validated_input = parse_result.data;
     // step 5: rate limit — throttle-requests semantics (record on every
     // invocation, no success-reset). Same limiters shared with the WS
     // dispatcher so an attacker can't switch transports to bypass the budget.
@@ -203,16 +211,33 @@ const rate_limited_result = (retry_after) => {
     };
 };
 /**
- * Pre-validation auth gate — fires before input validation so missing
- * credentials short-circuit with `unauthenticated` instead of leaking
- * a `invalid_params` error for methods with required input.
+ * Read the `acting` actor selector off the raw params for the authorization
+ * phase.
+ *
+ * Consulted only when the spec declares an actor axis; `parse_acting` owns
+ * what counts as a selector and why a malformed one reads as omitted.
+ *
+ * @param auth - the spec's auth shape; no actor axis means no selector
+ * @param raw_params - the request's unvalidated params
+ * @returns the actor id, or `undefined` when absent, malformed, or unwanted
+ */
+const read_acting = (auth, raw_params) => {
+    if (!needs_actor(auth))
+        return undefined;
+    if (typeof raw_params !== 'object' || raw_params === null)
+        return undefined;
+    return parse_acting(raw_params.acting);
+};
+/**
+ * Pre-authorization auth gate — fires before the authorization phase so
+ * missing credentials short-circuit with `unauthenticated`.
  *
  * 401 fires when `auth.account === 'required'` (or `auth.actor === 'required'`,
  * since registry-time invariant 3 forbids accountless actors in v1) and
  * no account is on the request. `'optional'` axes pass through — the
  * authorization phase decides based on whatever the credential supports.
  */
-const check_action_auth_pre_validation = (auth, account_id) => {
+const check_action_auth_pre_authorization = (auth, account_id) => {
     if (auth.account === 'required' || auth.actor === 'required') {
         if (account_id == null) {
             // Carry the reason on `error.data.reason` (symmetric with the 403
@@ -264,7 +289,7 @@ const check_action_auth_post_authorization = (auth, request_context, credential_
     if (token_scope && !token_scope_admits_method(token_scope, method)) {
         return jsonrpc_error_messages.forbidden('forbidden', {
             reason: ERROR_TOKEN_SCOPE_REQUIRED,
-            required_scope: `rpc:${method}`
+            required_scope: token_scope_method_capability(method)
         });
     }
     if (auth.roles?.length) {

package/dist/actions/register_action_ws.d.ts

@@ -174,10 +174,10 @@ export interface RegisterActionWsResult {
  * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
  *   Exception: `cancel` notifications abort the matching pending request's
  *   `ctx.signal` before bubbling out.
- * - Per-message dispatch goes through `perform_action`: pre-validation
- *   auth (401) → input validation (400) → authorization phase →
- *   post-authorization auth (403) → rate limit (429) → handler (with
- *   transaction wrap iff `spec.side_effects: true`) → DEV output validation.
+ * - Per-message dispatch goes through `perform_action`: pre-authorization
+ *   auth (401) → authorization phase → post-authorization auth (403) →
+ *   input validation (400) → rate limit (429) → handler (with transaction
+ *   wrap iff `spec.side_effects: true`) → DEV output validation.
  * - Authorization phase runs **per message** — role_grant changes during a
  *   connection lifetime are picked up on the next message without any
  *   in-place refresh. Authentication invalidation closes the socket via

package/dist/actions/register_action_ws.js

@@ -53,10 +53,10 @@ export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
  * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
  *   Exception: `cancel` notifications abort the matching pending request's
  *   `ctx.signal` before bubbling out.
- * - Per-message dispatch goes through `perform_action`: pre-validation
- *   auth (401) → input validation (400) → authorization phase →
- *   post-authorization auth (403) → rate limit (429) → handler (with
- *   transaction wrap iff `spec.side_effects: true`) → DEV output validation.
+ * - Per-message dispatch goes through `perform_action`: pre-authorization
+ *   auth (401) → authorization phase → post-authorization auth (403) →
+ *   input validation (400) → rate limit (429) → handler (with transaction
+ *   wrap iff `spec.side_effects: true`) → DEV output validation.
  * - Authorization phase runs **per message** — role_grant changes during a
  *   connection lifetime are picked up on the next message without any
  *   in-place refresh. Authentication invalidation closes the socket via
@@ -98,7 +98,7 @@ export const register_action_ws = (options) => {
     // scoped token that could upgrade would observe far more than it was
     // granted.
     async (c, next) => {
-        const denied = token_scope_surface_denial(c, 'ws_upgrade');
+        const denied = token_scope_surface_denial(c, 'surface:ws_upgrade');
         if (denied)
             return denied;
         return next();

package/dist/actions/register_ws_endpoint.d.ts

@@ -7,12 +7,18 @@
  * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
  *    before the upgrade handshake runs.
  * 2. `require_auth` — reject unauthenticated upgrades.
- * 3. **Authorization phase** — resolve the acting actor against the
+ * 3. `require_token_scope('surface:ws_upgrade')` — rule 3: a narrowed token
+ *    cannot hold a socket. Mounted here, ahead of the role guard, so a
+ *    narrowed token is told about its scope rather than about a role it
+ *    also lacks. `register_action_ws` repeats the check on its own route
+ *    chain, which is what covers consumers mounting it directly; the
+ *    earlier answer wins when both are wired.
+ * 4. **Authorization phase** — resolve the acting actor against the
  *    authenticated account plus an optional `?acting=<uuid>` query string,
  *    and build the `RequestContext` that per-message dispatch reads.
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
- * 4. Optional `require_role(required_roles)` — for endpoints gated to a
+ * 5. Optional `require_role(required_roles)` — for endpoints gated to a
  *    non-empty any-of set of roles.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
@@ -43,14 +49,16 @@ export interface RegisterWsEndpointOptions extends RegisterActionWsOptions {
 }
 /**
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
- * + auth + actor resolution + optional role) and JSON-RPC dispatch.
+ * + auth + token scope + actor resolution + optional role) and JSON-RPC
+ * dispatch.
  *
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  *
- * @mutates options.app - applies origin/auth/authorization/role middleware via `app.use`,
- *   then registers the `GET path` route via the inner `register_action_ws`
+ * @mutates options.app - applies origin/auth/scope/authorization/role middleware
+ *   via `app.use`, then registers the `GET path` route via the inner
+ *   `register_action_ws`
  */
 export declare const register_ws_endpoint: (options: RegisterWsEndpointOptions) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

package/dist/actions/register_ws_endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAmBF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAoBF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -7,12 +7,18 @@
  * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
  *    before the upgrade handshake runs.
  * 2. `require_auth` — reject unauthenticated upgrades.
- * 3. **Authorization phase** — resolve the acting actor against the
+ * 3. `require_token_scope('surface:ws_upgrade')` — rule 3: a narrowed token
+ *    cannot hold a socket. Mounted here, ahead of the role guard, so a
+ *    narrowed token is told about its scope rather than about a role it
+ *    also lacks. `register_action_ws` repeats the check on its own route
+ *    chain, which is what covers consumers mounting it directly; the
+ *    earlier answer wins when both are wired.
+ * 4. **Authorization phase** — resolve the acting actor against the
  *    authenticated account plus an optional `?acting=<uuid>` query string,
  *    and build the `RequestContext` that per-message dispatch reads.
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
- * 4. Optional `require_role(required_roles)` — for endpoints gated to a
+ * 5. Optional `require_role(required_roles)` — for endpoints gated to a
  *    non-empty any-of set of roles.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
@@ -21,7 +27,7 @@
  * @module
  */
 import { Logger } from '@fuzdev/fuz_util/log.ts';
-import { apply_authorization_phase, REQUEST_CONTEXT_KEY, require_auth, require_role } from '../auth/request_context.js';
+import { apply_authorization_phase, REQUEST_CONTEXT_KEY, require_auth, require_role, require_token_scope } from '../auth/request_context.js';
 import { verify_request_source } from '../http/origin.js';
 import { ACCOUNT_ID_KEY, TEST_CONTEXT_PRESET_KEY } from '../hono_context.js';
 import { register_action_ws } from './register_action_ws.js';
@@ -67,19 +73,22 @@ const create_ws_authorization_middleware = (db) => {
 };
 /**
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
- * + auth + actor resolution + optional role) and JSON-RPC dispatch.
+ * + auth + token scope + actor resolution + optional role) and JSON-RPC
+ * dispatch.
  *
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  *
- * @mutates options.app - applies origin/auth/authorization/role middleware via `app.use`,
- *   then registers the `GET path` route via the inner `register_action_ws`
+ * @mutates options.app - applies origin/auth/scope/authorization/role middleware
+ *   via `app.use`, then registers the `GET path` route via the inner
+ *   `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
     const { app, path, allowed_origins, db, required_roles, log = new Logger('[ws]'), ...rest } = options;
     app.use(path, verify_request_source(allowed_origins));
     app.use(path, require_auth);
+    app.use(path, require_token_scope('surface:ws_upgrade'));
     app.use(path, create_ws_authorization_middleware(db));
     if (required_roles?.length) {
         app.use(path, require_role(required_roles));

package/dist/auth/CLAUDE.md

@@ -61,6 +61,7 @@ Convention — `*_schema.ts` is Zod-only; `*_ddl.ts` holds DDL strings.
 - `auth/scope_kind_schema.ts` — `ScopeKindName`, `create_scope_kind_schema` (open registry, no builtins).
 - `auth/credential_type_schema.ts` — `CredentialTypeName`, `CREDENTIAL_TYPE_SESSION` / `_API_TOKEN` / `_DAEMON_TOKEN`, `create_credential_type_schema`.
 - `auth/grant_path_schema.ts` — `GrantPathName`, `GRANT_PATH_ADMIN` / `_SELF_SERVICE` / `_SYSTEM` / `_BOOTSTRAP`, `create_grant_path_schema`.
+- `auth/token_scope.ts` — per-credential authority narrowing stored on `api_token.scope`: `TokenScope` / `TokenScopeInput` + constructors, `parse_stored_token_scope` (fail-closed), `token_scope_admits_method` / `_non_rpc`, and the `<section>:<id>` capability vocabulary `RouteAuth.required_scope` is written in (`parse_token_scope_capability`, `token_scope_admits_capability`, `token_scope_denied_body`, `TOKEN_SURFACES`). Not an open registry — see ../../../docs/security.md §Token scoping for why the identifier half is deliberately unregistered.
 - `auth/auth_ddl.ts` — `CREATE TABLE` / index / seed strings for the core identity tables.
 - `auth/audit_log_schema.ts` — `AUDIT_EVENT_TYPES` (27 builtins), `AuditEventType` / `AuditEventTypeName`, `audit_metadata_schemas`, `AuditLogEvent`, `AuditLogInput`, `AuditLogConfig`, `create_audit_log_config`.
 - `auth/audit_log_ddl.ts` — `audit_log` table DDL with `seq BIGSERIAL` for cursor-based gap fill (BIGSERIAL converges with the Rust spine; `create_db` registers a `pg.types` int8 parser so `seq` still reads as a JS number).
@@ -123,7 +124,7 @@ they track the same config. Sample via `get_*`; `reset_*` are test-only.
 - `auth/bootstrap_routes.ts` — `POST /bootstrap` + `check_bootstrap_status`; `BootstrapStatus` runtime ref.
 - `auth/signup_routes.ts` — `POST /signup` (open or invite-gated).
 - `auth/audit_log_routes.ts` — optional `GET /audit/stream` (SSE); list/history are on the RPC surface.
-- `auth/auth_guard_resolver.ts` — `fuz_auth_guard_resolver` injected into `apply_route_specs` so the framework stays auth-agnostic.
+- `auth/auth_guard_resolver.ts` — `fuz_auth_guard_resolver` injected into `apply_route_specs` so the framework stays auth-agnostic. Maps each `RouteAuth` axis to a guard and is the single site every route spec traverses, so it also carries the two invariants the schema can't (a `required_scope` that isn't a well-formed capability, and one on an unrestricted route).
 
 **Hono-free route shapes.** Each cookie/SSE-coupled route module has a sibling
 `*_route_schema.ts` (`account_route_schema.ts`, `signup_route_schema.ts`,
@@ -158,7 +159,7 @@ Everything else listed under §RPC action surfaces.
 ### Middleware
 
 - `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token`.
-- `auth/request_context.ts` — `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role`), guards (`require_auth`, `require_role`, `require_credential_types`), `refresh_role_grants`.
+- `auth/request_context.ts` — `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role`), guards (`require_auth`, `require_role`, `require_credential_types`, `require_token_scope`), `token_scope_surface_denial` (the direct-call form, for surfaces that aren't route specs), `refresh_role_grants`.
 - `auth/session_middleware.ts` — `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap).
 - `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context).
 - `auth/daemon_token_middleware.ts` — `start_daemon_token_rotation` + `create_daemon_token_middleware(state, deps, log)` (atomic file write, soft-fail validation, keeper account resolution). Soft-fails — discards the credential (pass-through, no own 401/503) on **every** non-success path: browser context (`Origin`/`Referer` present), malformed/invalid token, and valid-token-but-no-keeper all `next()` through to the dispatcher's `credential_type_required` (403) gate, mirroring the bearer guard and the Rust spine's `resolve.rs`. Daemon tokens are loopback-only, so browser context never arises in practice — the discard is defense-in-depth.
@@ -274,12 +275,15 @@ Sets `c.var.account_id` + `CREDENTIAL_TYPE_KEY` on a valid credential.
 Account-only — never loads actor or role_grants, never populates
 `REQUEST_CONTEXT_KEY`.
 
-**Authorization runs after input validation**, matching the dispatcher's
-401 → 400 → 403 phase order (see `http/CLAUDE.md` §Validation pipeline).
-When the route's input declares `acting?: ActingActor` or its auth requires
-role_grants, the authorization phase calls `resolve_acting_actor` over the
-validated `acting` value and builds an actor-bound `RequestContext`.
-Account-grain routes run with `RequestContext.actor: null`.
+**Authorization runs before input validation**, matching the dispatcher's
+401 → authz → 403 → 400 phase order (see `http/CLAUDE.md` §Validation
+pipeline). When the route's input declares `acting?: ActingActor` or its auth
+requires role_grants, the authorization phase calls `resolve_acting_actor` over
+the `acting` selector — the validated query value on GETs, read off the raw
+body on mutations — and builds an actor-bound `RequestContext`. A malformed
+selector reads as omitted (it only ever picks among actors the account already
+owns, and input validation rejects it a step later). Account-grain routes run
+with `RequestContext.actor: null`.
 
 `apply_authorization_phase` is pure data — returns `AuthorizationResult`
 (`{ok: true, request_context: RequestContext | null} | {ok: false, status, body}`)
@@ -399,7 +403,10 @@ Keeper is not a dedicated guard — it's a composable `RouteAuth` shape:
 `{account: 'required', actor: 'required', roles: ['keeper'], credential_types: ['daemon_token']}`.
 The two-part check is `require_credential_types(['daemon_token'])` (403
 `ERROR_CREDENTIAL_TYPE_REQUIRED`) followed by `require_role(['keeper'])`
-(403 `ERROR_INSUFFICIENT_PERMISSIONS`). Same scope-aware semantics mirrored
+(403 `ERROR_INSUFFICIENT_PERMISSIONS`) — the channel gate lands
+pre-authorization and the role gate post-authorization, so a non-daemon
+credential is refused before the route resolves an actor for it. Same
+scope-aware semantics mirrored
 in the HTTP RPC dispatcher (`actions/action_rpc.ts`), the WS dispatcher
 (`actions/register_action_ws.ts`), and the admin bypasses inside
 `auth/role_grant_offer_actions.ts`.

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB;;kBAA0C,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,gBAAe,MAAkC,KAC/C,IAAI,CAAC,SAAS,EAAE,SAAS,CAQ1B,CAAC"}
+{"version":3,"file":"audit_log_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB;;kBAA0C,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,gBAAe,MAAkC,KAC/C,IAAI,CAAC,SAAS,EAAE,SAAS,CAkB1B,CAAC"}

package/dist/auth/audit_log_route_schema.js

@@ -28,7 +28,17 @@ export const DEFAULT_AUDIT_STREAM_ROLE = 'admin';
 export const create_audit_log_route_shape = (required_role = DEFAULT_AUDIT_STREAM_ROLE) => ({
     method: 'GET',
     path: '/audit/stream',
-    auth: { account: 'required', actor: 'required', roles: [required_role] },
+    auth: {
+        account: 'required',
+        actor: 'required',
+        roles: [required_role],
+        // Rule 3 — a narrowed token holds no audit feed. Same reasoning as the
+        // WS upgrade: this is a long-lived server→client stream whose contents
+        // are decided by the account's role, not by any per-message scope
+        // check, so there is no point after open at which a narrowing could
+        // apply.
+        required_scope: 'surface:audit_stream'
+    },
     description: 'Subscribe to realtime audit log events',
     query: AuditStreamQuery,
     input: z.null(),

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAuB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAQ3E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;QAC1F,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CAiC5F,CAAC"}
+{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAuB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;QAC1F,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CA4B5F,CAAC"}

package/dist/auth/audit_log_routes.js

@@ -13,7 +13,7 @@
  */
 import { create_audit_log_route_shape } from './audit_log_route_schema.js';
 import { create_sse_response } from '../realtime/sse.js';
-import { AUTH_SESSION_TOKEN_HASH_KEY, require_request_context, token_scope_surface_denial } from './request_context.js';
+import { AUTH_SESSION_TOKEN_HASH_KEY, require_request_context } from './request_context.js';
 import { AUDIT_LOG_CHANNEL } from '../realtime/sse_auth_guard.js';
 /**
  * Create the optional audit-log SSE route spec.
@@ -32,14 +32,9 @@ export const create_audit_log_route_specs = (options) => {
         {
             ...create_audit_log_route_shape(options.required_role),
             handler: (c) => {
-                // Rule 3 — a narrowed token holds no audit feed. Same reasoning as
-                // the WS upgrade: this is a long-lived server→client stream whose
-                // contents are decided by the account's role, not by any
-                // per-message scope check, so there is no point after open at
-                // which a narrowing could apply.
-                const denied = token_scope_surface_denial(c, 'audit_stream');
-                if (denied)
-                    return denied;
+                // Rule 3 is declared on the route shape's `auth.required_scope`,
+                // so a narrowed token is refused ahead of the role gate rather
+                // than here.
                 const ctx = require_request_context(c);
                 // scope = session hash (capped → tabs-per-session limit and
                 // session-specific `session_revoke` close). groups = [account_id]

package/dist/auth/auth_guard_resolver.d.ts

@@ -1,25 +1,35 @@
 /**
  * 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.
  *
@@ -29,16 +39,33 @@ import type { AuthGuardResolver } from '../http/route_spec.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 declare const fuz_auth_guard_resolver: AuthGuardResolver;
 //# sourceMappingURL=auth_guard_resolver.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth_guard_resolver.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/auth_guard_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAerC,CAAC"}
+{"version":3,"file":"auth_guard_resolver.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/auth_guard_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AASH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAuBrC,CAAC"}