@fuzdev/fuz_app 0.106.0 → 0.107.0

package/dist/actions/CLAUDE.md

@@ -29,14 +29,16 @@ Canonical source of truth. Three concrete kinds discriminate on `kind`:
 - `remote_notification` — `auth: null`, `side_effects: true`, `output: z.ZodVoid`, `async: true`.
 - `local_call` — `auth: null`, `side_effects` arbitrary, `output` arbitrary, `async` boolean.
 
-`RouteAuth` is the flat record `{account, actor, roles?, credential_types?}`
-from `http/auth_shape.ts` — same shape governs `RouteSpec.auth` so the four
-axes drive one auth surface across REST and SAES. Cross-axis invariants:
-roles imply `actor: 'required'`; `account: 'none'` implies `actor: 'none'`
-(no accountless actors in v1); the unrestricted leaf
+`RouteAuth` is the flat record
+`{account, actor, roles?, credential_types?, required_scope?}` from
+`http/auth_shape.ts` — same shape governs `RouteSpec.auth` so one auth
+surface drives REST and SAES. Cross-axis invariants: roles imply
+`actor: 'required'`; `account: 'none'` implies `actor: 'none'` (no
+accountless actors in v1); the unrestricted leaf
 (`account: 'none', actor: 'none'`) cannot declare roles or credential
 gates. The biconditional `actor !== 'none' ⟺ input declares acting?: ActingActor`
 is enforced at registration time via `assert_route_auth_acting_biconditional`.
+`required_scope` is the one axis actions cannot use — see §Registry compile.
 
 Optional fields:
 
@@ -73,14 +75,14 @@ non-`remote_notification` kind.
 ## Registry compile (`actions/compile_action_registry.ts`)
 
 `compile_action_registry` is the shared registration loop called by both
-`create_rpc_endpoint` and `register_action_ws`. Validates four
-registry-time invariants and returns the `Map<method, RpcAction>` the
-dispatchers use:
+`create_rpc_endpoint` and `register_action_ws`. Validates these checks in
+order and returns the `Map<method, RpcAction>` the dispatchers use:
 
-1. **Auth-shape biconditional** — `actor !== 'none' ⟺ input declares acting?: ActingActor` (via `assert_route_auth_acting_biconditional`).
-2. **Rate-limit account axis** — `rate_limit: 'account' | 'both'` requires `auth.account === 'required'`.
-3. **JSON-RPC §4.2 wire validity** — `request_response` specs with a handler may not use `z.null()` for input (use `z.void()` for nullary).
-4. **Unique method names** across the array.
+- **Auth-shape biconditional** — `actor !== 'none' ⟺ input declares acting?: ActingActor` (via `assert_route_auth_acting_biconditional`).
+- **No `auth.required_scope`** — the slot is route-spec-only; nothing mounts a guard from it on an action, so declaring it would be a control that silently does nothing. Narrowed tokens are gated per method by the scope check in `perform_action`, which derives the `rpc:<method>` capability from `spec.method` rather than trusting a hand-written one.
+- **Rate-limit account axis** — `rate_limit: 'account' | 'both'` requires `auth.account === 'required'`.
+- **JSON-RPC §4.2 wire validity** — `request_response` specs with a handler may not use `z.null()` for input (use `z.void()` for nullary).
+- **Unique method names** across the array.
 
 Only `request_response` specs with a handler reach the dispatch map;
 `remote_notification` / handler-less specs (e.g. WS `cancel`) stay
@@ -174,7 +176,25 @@ and `FrontendActionHandlers`.
 Derives transport-specific specs from action specs. HTTP-specific concerns
 (path, handler, errors) come from options, not the action spec.
 
-- `create_action_route_spec(spec, options)` — one action → one `RouteSpec`. HTTP method defaults by `side_effects` (`true` → POST, `false` → GET; override via `options.http_method`). `route.auth` is `spec.auth` verbatim. `transaction: spec.side_effects`. Throws if `spec.auth` is null.
+- `create_action_route_spec(spec, options)` — one action → one `RouteSpec`. HTTP method defaults by `side_effects` (`true` → POST, `false` → GET; override via `options.http_method`). `route.auth` is `spec.auth` plus a derived `required_scope`. `transaction: spec.side_effects`. Throws if `spec.auth` is null.
+
+**The bridge carries the token-scope gate across.** A bridged route runs
+`options.handler` through the REST pipeline and never reaches
+`perform_action`, so the dispatcher's per-method scope check cannot fire on it
+— leaving a bearer-reachable surface a **narrowed** token walks through, which
+is what the RPC-only rule exists to prevent. So the derived spec declares
+`auth.required_scope: 'rpc:<method>'` and `fuz_auth_guard_resolver` mounts the
+refusal ahead of the role gate. Per-method rather than a blanket refusal
+because a bridged route _has_ a method identity, which the non-RPC surfaces
+the RPC-only rule covers do not.
+
+Bridge something with no request/response shape — an SSE stream, a file
+download — and the whole-surface rule applies instead: pass `options.auth` with
+`required_scope: 'surface:<name>'`, naming your own surface (the vocabulary is
+open on the identifier). An `options.auth` that omits `required_scope` still
+gets the derived one; public actions get none (the guard would enforce
+nothing). fuz_app mounts no bridged routes itself; this is consumer-facing.
+
 - `create_action_event_spec(spec, {channel?})` — one notification action → one `EventSpec` for SSE surface + `create_validated_broadcaster`. Throws on non-`remote_notification` kind.
 - `derive_http_method(side_effects)` — exported for custom bridges.
 
@@ -190,11 +210,10 @@ The HTTP RPC dispatcher is a thin shim around `perform_action`
 parsing, GET vs POST split, `c.json` binding); the
 auth/validation/dispatch pipeline is shared with the WebSocket dispatcher.
 
-**Phase order: 401 → 400 → 403 → handler.** Validate first, authorize
-after. Trade-off: an unauthorized caller sees the validation step. The
-alternative ordering (403-before-400) was rejected because
-defense-in-depth via attack-surface obscurity is illusory when the surface
-is published in `library.json` codegen anyway.
+**Phase order: 401 → authz → 403 → 400 → handler.** Authorize first,
+validate after — a caller the authority gates refuse never learns the
+action's input shape, and the coarse authority facts settle before the fine
+ones. Matches the Rust spine, which validates handler-side.
 
 Shim responsibilities (per-request):
 
@@ -267,12 +286,12 @@ The transport-agnostic post-parse pipeline. Each transport assembles a
 `perform_action(input, deps)`, and binds the discriminated
 `PerformActionResult` to its wire shape.
 
-Pipeline (401 → 400 → 403 → handler):
+Pipeline (401 → authz → 403 → 400 → handler):
 
-1. Pre-validation auth (401)
-2. Validate params (400) — `spec.input.safeParse` with `z.void()` / `?? {}` rules
-3. Authorization phase — `apply_authorization_phase` against `account_id` + `validated_input.acting`. Test escape hatch via `preset.request_context`
-4. Post-authorization auth (403) — credential-type gate first, role gate second
+1. Pre-authorization auth (401)
+2. Authorization phase — `apply_authorization_phase` against `account_id` + `read_acting(auth, raw_params)`, which takes the selector off the raw params (malformed reads as omitted) since validation now runs later. Test escape hatch via `preset.request_context`
+3. Post-authorization auth (403) — credential-type gate, then token scope, then role
+4. Validate params (400) — `spec.input.safeParse` with `z.void()` / `?? {}` rules
 5. Rate limit (429) — throttle-requests semantics
 6. Dispatch + DEV output validation + error normalization — `spec.side_effects` picks transaction vs pool. `ThrownJsonrpcError` preserves code + data; generic throws become `internal_error`
 

package/dist/actions/action_bridge.d.ts

@@ -10,7 +10,7 @@
 import type { z } from 'zod';
 import type { ActionSpec, ActionSideEffects } from './action_spec.js';
 import type { RouteSpec, RouteMethod, RouteHandler } from '../http/route_spec.js';
-import type { RouteAuth } from '../http/auth_shape.js';
+import { type RouteAuth } from '../http/auth_shape.js';
 import type { EventSpec } from '../realtime/sse.js';
 import type { RouteErrorSchemas } from '../http/error_schemas.js';
 /** Options for deriving a `RouteSpec` from an `ActionSpec`. */
@@ -25,8 +25,17 @@ export interface ActionRouteOptions {
     http_method?: RouteMethod;
     /**
      * Override the route's auth shape — defaults to the action spec's `auth`
-     * (the canonical four-axis shape from `http/auth_shape.ts` is shared
-     * verbatim between action specs and route specs, so no mapping is needed).
+     * (the canonical shape from `http/auth_shape.ts` is shared verbatim between
+     * action specs and route specs, so no mapping is needed).
+     *
+     * The bridge fills in `required_scope` on whichever shape it ends up with,
+     * so an override still gets the token-scope gate; declare `required_scope`
+     * here to name a different capability (e.g. `surface:<name>` when the
+     * bridged route is a stream rather than a request/response call — see the
+     * token-scope note on `create_action_route_spec`).
+     *
+     * Overriding to *widen* (admitting a credential the action's own gate
+     * refused) makes this route the consumer's to audit, not the spine's.
      */
     auth?: RouteAuth;
     /** Handler-specific error schemas (HTTP status code → Zod schema). Transport-specific — not on ActionSpec. */
@@ -49,6 +58,28 @@ export declare const derive_http_method: (side_effects: ActionSideEffects) => Ro
  * on the options, not the action spec. Action specs define the contract;
  * transport concerns like HTTP error codes are added at the bridge layer.
  *
+ * **The bridge carries the token-scope gate across for you.** A bridged route
+ * runs `options.handler` through the REST pipeline and never reaches
+ * `perform_action`, so the dispatcher's per-method scope check cannot fire on
+ * it — which would leave a bearer-reachable route that a **narrowed** api token
+ * walks straight through. So the derived spec declares
+ * `auth.required_scope: 'rpc:<method>'`, and `fuz_auth_guard_resolver` mounts
+ * the same refusal ahead of the role gate. A token that lists the method
+ * reaches the bridged route; one that doesn't gets the 403 it would have gotten
+ * over RPC.
+ *
+ * Per-method rather than rule 3's blanket refusal because a bridged route
+ * *has* a method identity — which is exactly what the non-RPC surfaces rule 3
+ * covers (the db browser, a bare-hash read, a stream) do not, and why that rule
+ * is all-or-nothing there. **Bridge something with no request/response shape —
+ * an SSE stream, a file download — and rule 3's reasoning applies instead**:
+ * pass `options.auth` with `required_scope: 'surface:<name>'`, naming your own
+ * surface. See `docs/security.md` §Token scoping.
+ *
+ * Skipped for a public action (`account: 'none', actor: 'none'`), where the
+ * same holder reaches the route by dropping the credential, so the guard would
+ * enforce nothing — the shape `fuz_auth_guard_resolver` refuses outright.
+ *
  * @param spec - the action spec (must have non-null `auth`)
  * @param options - HTTP-specific options (path, handler, optional overrides)
  * @returns a `RouteSpec` ready for `apply_route_specs`

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

@@ -1 +1 @@
-{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAqBF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,SAcF,CAAC"}
+{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SA4BF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,SAcF,CAAC"}

package/dist/actions/action_bridge.js

@@ -7,6 +7,8 @@
  *
  * @module
  */
+import { token_scope_method_capability } from '../auth/token_scope.js';
+import { is_public_auth } from '../http/auth_shape.js';
 /** Derive the default HTTP method from side effects. */
 export const derive_http_method = (side_effects) => {
     return side_effects ? 'POST' : 'GET';
@@ -22,6 +24,28 @@ export const derive_http_method = (side_effects) => {
  * on the options, not the action spec. Action specs define the contract;
  * transport concerns like HTTP error codes are added at the bridge layer.
  *
+ * **The bridge carries the token-scope gate across for you.** A bridged route
+ * runs `options.handler` through the REST pipeline and never reaches
+ * `perform_action`, so the dispatcher's per-method scope check cannot fire on
+ * it — which would leave a bearer-reachable route that a **narrowed** api token
+ * walks straight through. So the derived spec declares
+ * `auth.required_scope: 'rpc:<method>'`, and `fuz_auth_guard_resolver` mounts
+ * the same refusal ahead of the role gate. A token that lists the method
+ * reaches the bridged route; one that doesn't gets the 403 it would have gotten
+ * over RPC.
+ *
+ * Per-method rather than rule 3's blanket refusal because a bridged route
+ * *has* a method identity — which is exactly what the non-RPC surfaces rule 3
+ * covers (the db browser, a bare-hash read, a stream) do not, and why that rule
+ * is all-or-nothing there. **Bridge something with no request/response shape —
+ * an SSE stream, a file download — and rule 3's reasoning applies instead**:
+ * pass `options.auth` with `required_scope: 'surface:<name>'`, naming your own
+ * surface. See `docs/security.md` §Token scoping.
+ *
+ * Skipped for a public action (`account: 'none', actor: 'none'`), where the
+ * same holder reaches the route by dropping the credential, so the guard would
+ * enforce nothing — the shape `fuz_auth_guard_resolver` refuses outright.
+ *
  * @param spec - the action spec (must have non-null `auth`)
  * @param options - HTTP-specific options (path, handler, optional overrides)
  * @returns a `RouteSpec` ready for `apply_route_specs`
@@ -32,10 +56,17 @@ export const create_action_route_spec = (spec, options) => {
     if (spec.auth === null) {
         throw new Error(`Cannot derive route spec from action '${spec.method}': auth is null (only request_response actions with non-null auth can become routes)`);
     }
+    const auth = options.auth ?? spec.auth;
+    // Carry the dispatcher's per-method scope gate across — see the token-scope
+    // note above. An explicit capability wins; a public route has no credential
+    // to narrow, and the resolver rejects the gate on that shape anyway.
+    const derives_scope_gate = auth.required_scope === undefined && !is_public_auth(auth);
     return {
         method: options.http_method ?? derive_http_method(spec.side_effects),
         path: options.path,
-        auth: options.auth ?? spec.auth,
+        auth: derives_scope_gate
+            ? { ...auth, required_scope: token_scope_method_capability(spec.method) }
+            : auth,
         handler: options.handler,
         description: spec.description,
         ...(options.params ? { params: options.params } : {}),

package/dist/actions/action_rpc.d.ts

@@ -122,7 +122,7 @@ export type ActionHandler<TInput = any, TOutput = any> = (input: TInput, ctx: Ac
  * `ActionContext` narrowed to a non-null `RequestContext`.
  *
  * Used by handlers whose spec declares `auth.account === 'required'`
- * (with `auth.actor === 'none'`) — the dispatcher's pre-validation 401
+ * (with `auth.actor === 'none'`) — the dispatcher's pre-authorization 401
  * gate guarantees `request_context` is populated before the handler
  * runs, but the actor slot stays null because no `acting` resolution
  * happened. Selected automatically by `rpc_action`'s conditional return
@@ -263,13 +263,14 @@ export interface CreateRpcEndpointOptions {
  * 1. **Parse envelope** — POST: JSON body as `JsonrpcRequest`. GET: `method`
  *    and `params` from query string.
  * 2. **Lookup method** — find the `RpcAction` by method name.
- * 3. **Pre-validation auth** — short-circuit `unauthenticated` when no
- *    account is on the request, before input validation runs.
+ * 3. **Pre-authorization auth** — short-circuit `unauthenticated` when no
+ *    account is on the request, before any later phase runs.
  * 4. **Authorization phase** — resolve the acting actor (when the action's
  *    auth requires role_grants or its input declares `acting?: ActingActor`)
  *    and build the request context. Runs before input validation so
  *    role-grant-grain auth checks return 403 before 400 invalid_params;
- *    `acting` is read from raw params via a string typeguard.
+ *    `acting` is read from raw params by `read_acting`, which parses it as
+ *    a UUID and treats anything else as omitted.
  * 5. **Post-authorization auth** — enforce role / keeper requirements
  *    against the request context.
  * 6. **Validate params** — parse input against the action's `input` schema.

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

@@ -1 +1 @@
-{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAGN,KAAK,gBAAgB,EAErB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;;OAKG;IACH,EAAE,EAAE,EAAE,CAAC;IACP;;;;;OAKG;IACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;OAKG;IACH,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IACrE,IAAI,EAAE,cAAc,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CAC5D,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,KAClB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IACtE,IAAI,EAAE,mBAAmB,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CAC7D,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,kBAAkB,KACnB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,yBAAyB,IAAI;IACrE,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;CACtB,SAAS,CAAC,UAAU,CAAC,GACnB,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GACrE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,GAC9C,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GACpE,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,cAAc,CAAC,KAAK,CAAC,KAC5B,SAGD,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjD;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CA2MtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -92,13 +92,14 @@ const jsonrpc_error_envelope = (id, error) => ({
  * 1. **Parse envelope** — POST: JSON body as `JsonrpcRequest`. GET: `method`
  *    and `params` from query string.
  * 2. **Lookup method** — find the `RpcAction` by method name.
- * 3. **Pre-validation auth** — short-circuit `unauthenticated` when no
- *    account is on the request, before input validation runs.
+ * 3. **Pre-authorization auth** — short-circuit `unauthenticated` when no
+ *    account is on the request, before any later phase runs.
  * 4. **Authorization phase** — resolve the acting actor (when the action's
  *    auth requires role_grants or its input declares `acting?: ActingActor`)
  *    and build the request context. Runs before input validation so
  *    role-grant-grain auth checks return 403 before 400 invalid_params;
- *    `acting` is read from raw params via a string typeguard.
+ *    `acting` is read from raw params by `read_acting`, which parses it as
+ *    a UUID and treats anything else as omitted.
  * 5. **Post-authorization auth** — enforce role / keeper requirements
  *    against the request context.
  * 6. **Validate params** — parse input against the action's `input` schema.

package/dist/actions/action_spec.d.ts

@@ -38,13 +38,16 @@ export declare const ActionSpec: z.ZodObject<{
         backend: "backend";
     }>;
     /**
-     * The four-axis auth shape (canonical schema in `http/auth_shape.ts`).
+     * The flat auth shape (canonical schema in `http/auth_shape.ts`).
      * `null` for `remote_notification` and `local_call` — those don't
      * dispatch through the request/response auth gate.
      *
      * See `http/auth_shape.ts` for the design rationale (orthogonal
      * authentication / account-resolution / actor-resolution / role-and-
-     * credential authorization axes).
+     * credential authorization axes). `required_scope` is the one field an
+     * action may not set — `compile_action_registry` rejects it, since
+     * nothing on the RPC path mounts a guard from it; the dispatcher derives
+     * the same `rpc:<method>` capability from `spec.method` instead.
      */
     auth: z.ZodNullable<z.ZodObject<{
         account: z.ZodEnum<{
@@ -59,6 +62,7 @@ export declare const ActionSpec: z.ZodObject<{
         }>;
         roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        required_scope: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     side_effects: z.ZodBoolean;
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
@@ -142,6 +146,7 @@ export declare const RequestResponseActionSpec: z.ZodObject<{
         }>;
         roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        required_scope: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     async: z.ZodDefault<z.ZodLiteral<true>>;
 }, z.core.$strict>;
@@ -228,6 +233,7 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
         }>;
         roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        required_scope: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     async: z.ZodDefault<z.ZodLiteral<true>>;
 }, z.core.$strict>, z.ZodObject<{

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

@@ -1 +1 @@
-{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;IAItB;;;;;;;;OAQG;;;;;;;;;;;;;;;;;;;;IAOH;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;;;;;;;;;;;;OAmBG;;;;;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;IAItB;;;;;;;;;;;OAWG;;;;;;;;;;;;;;;;;;;;;IAOH;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;;;;;;;;;;;;OAmBG;;;;;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/actions/action_spec.js

@@ -21,13 +21,16 @@ export const ActionSpec = z.strictObject({
     kind: ActionKind,
     initiator: ActionInitiator,
     /**
-     * The four-axis auth shape (canonical schema in `http/auth_shape.ts`).
+     * The flat auth shape (canonical schema in `http/auth_shape.ts`).
      * `null` for `remote_notification` and `local_call` — those don't
      * dispatch through the request/response auth gate.
      *
      * See `http/auth_shape.ts` for the design rationale (orthogonal
      * authentication / account-resolution / actor-resolution / role-and-
-     * credential authorization axes).
+     * credential authorization axes). `required_scope` is the one field an
+     * action may not set — `compile_action_registry` rejects it, since
+     * nothing on the RPC path mounts a guard from it; the dispatcher derives
+     * the same `rpc:<method>` capability from `spec.method` instead.
      */
     auth: RouteAuth.nullable(),
     side_effects: ActionSideEffects,

package/dist/actions/compile_action_registry.d.ts

@@ -3,21 +3,33 @@
  *
  * `create_rpc_endpoint` (HTTP RPC) and `register_action_ws` (WebSocket)
  * both build a `Map<method, RpcAction>` from a list of action specs and
- * gate the build on the same registry-time invariants:
+ * gate the build on the same checks, in this order (named rather than
+ * numbered — "registry-time invariant N" elsewhere in the codebase refers to
+ * the `RouteAuth` cross-axis set in `http/auth_shape.ts`, a different list):
  *
- * 1. **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
- *    in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
- *    acting?: ActingActor`. Fires for every spec with non-null auth.
- * 2. **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
- *    requires `auth.account === 'required'`; without an account on the
- *    request there is no key for the per-account bucket.
- * 3. **JSON-RPC §4.2 wire validity** — `request_response` specs whose
- *    handler will reach the dispatch map must not use `z.null()` for
- *    input (the wire format forbids `"params": null`; use `z.void()`
- *    for parameterless methods).
- * 4. **Duplicate method names** — JSON-RPC keys on `method`, so every
- *    spec in the array must declare a unique `method` regardless of
- *    kind / handler presence.
+ * - **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
+ *   in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
+ *   acting?: ActingActor` (that set's invariant 2). Fires for every spec with
+ *   non-null auth.
+ * - **No `auth.required_scope` on an action** — `ActionSpec.auth` is the same
+ *   `RouteAuth` a route spec carries, so the field parses here, but only
+ *   `apply_route_specs` mounts a guard from it and `perform_action` never
+ *   reads it. Declaring it on an action would be a security control that
+ *   silently does nothing, which is the exact shape token scoping was built
+ *   to refuse. Rejected loudly instead; actions are governed by the
+ *   per-method scope gate inside `perform_action`, which derives the same
+ *   `rpc:<method>` capability from `spec.method` rather than trusting a
+ *   hand-written one.
+ * - **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
+ *   requires `auth.account === 'required'`; without an account on the
+ *   request there is no key for the per-account bucket.
+ * - **JSON-RPC §4.2 wire validity** — `request_response` specs whose
+ *   handler will reach the dispatch map must not use `z.null()` for
+ *   input (the wire format forbids `"params": null`; use `z.void()`
+ *   for parameterless methods).
+ * - **Duplicate method names** — JSON-RPC keys on `method`, so every
+ *   spec in the array must declare a unique `method` regardless of
+ *   kind / handler presence.
  *
  * Pre-consolidation each dispatcher inlined these checks; the comment
  * in `actions/register_action_ws.ts` literally said "mirrors the HTTP RPC

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

@@ -1 +1 @@
-{"version":3,"file":"compile_action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/compile_action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,aAAa,CAAC,MAAM,CAAC,EAC9B,WAAW,MAAM,KACf,2BAwCF,CAAC"}
+{"version":3,"file":"compile_action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/compile_action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,aAAa,CAAC,MAAM,CAAC,EAC9B,WAAW,MAAM,KACf,2BA6CF,CAAC"}

package/dist/actions/compile_action_registry.js

@@ -3,21 +3,33 @@
  *
  * `create_rpc_endpoint` (HTTP RPC) and `register_action_ws` (WebSocket)
  * both build a `Map<method, RpcAction>` from a list of action specs and
- * gate the build on the same registry-time invariants:
+ * gate the build on the same checks, in this order (named rather than
+ * numbered — "registry-time invariant N" elsewhere in the codebase refers to
+ * the `RouteAuth` cross-axis set in `http/auth_shape.ts`, a different list):
  *
- * 1. **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
- *    in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
- *    acting?: ActingActor`. Fires for every spec with non-null auth.
- * 2. **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
- *    requires `auth.account === 'required'`; without an account on the
- *    request there is no key for the per-account bucket.
- * 3. **JSON-RPC §4.2 wire validity** — `request_response` specs whose
- *    handler will reach the dispatch map must not use `z.null()` for
- *    input (the wire format forbids `"params": null`; use `z.void()`
- *    for parameterless methods).
- * 4. **Duplicate method names** — JSON-RPC keys on `method`, so every
- *    spec in the array must declare a unique `method` regardless of
- *    kind / handler presence.
+ * - **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
+ *   in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
+ *   acting?: ActingActor` (that set's invariant 2). Fires for every spec with
+ *   non-null auth.
+ * - **No `auth.required_scope` on an action** — `ActionSpec.auth` is the same
+ *   `RouteAuth` a route spec carries, so the field parses here, but only
+ *   `apply_route_specs` mounts a guard from it and `perform_action` never
+ *   reads it. Declaring it on an action would be a security control that
+ *   silently does nothing, which is the exact shape token scoping was built
+ *   to refuse. Rejected loudly instead; actions are governed by the
+ *   per-method scope gate inside `perform_action`, which derives the same
+ *   `rpc:<method>` capability from `spec.method` rather than trusting a
+ *   hand-written one.
+ * - **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
+ *   requires `auth.account === 'required'`; without an account on the
+ *   request there is no key for the per-account bucket.
+ * - **JSON-RPC §4.2 wire validity** — `request_response` specs whose
+ *   handler will reach the dispatch map must not use `z.null()` for
+ *   input (the wire format forbids `"params": null`; use `z.void()`
+ *   for parameterless methods).
+ * - **Duplicate method names** — JSON-RPC keys on `method`, so every
+ *   spec in the array must declare a unique `method` regardless of
+ *   kind / handler presence.
  *
  * Pre-consolidation each dispatcher inlined these checks; the comment
  * in `actions/register_action_ws.ts` literally said "mirrors the HTTP RPC
@@ -50,6 +62,9 @@ export const compile_action_registry = (actions, ctx_label) => {
         // per the spec union means `kind === 'request_response'`).
         if (spec.auth !== null) {
             assert_route_auth_acting_biconditional(spec.auth, { input: spec.input }, ctx);
+            if (spec.auth.required_scope !== undefined) {
+                throw new Error(`${ctx} declares auth.required_scope: '${spec.auth.required_scope}' — that slot is for route specs only. Actions dispatch through the RPC endpoint, where a narrowed token is gated per method by the scope check in perform_action, which derives the capability from the method name. Remove the field.`);
+            }
             if ((spec.rate_limit === 'account' || spec.rate_limit === 'both') &&
                 spec.auth.account !== 'required') {
                 throw new Error(`${ctx} declares rate_limit: '${spec.rate_limit}' but auth.account !== 'required' — no account guaranteed for account-keyed limiting. Use 'ip' or set auth.account: 'required'.`);

package/dist/actions/perform_action.d.ts

@@ -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** —
@@ -140,10 +150,10 @@ export type PerformActionResult = {
  * 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 declare const perform_action: (input: PerformActionInput, deps: PerformActionDeps) => Promise<PerformActionResult>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"perform_action.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/perform_action.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"perform_action.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/perform_action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAGtC,OAAO,EAEN,KAAK,gBAAgB,EAErB,KAAK,kBAAkB,EACvB,MAAM,oBAAoB,CAAC;AAc5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAgC,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAGN,KAAK,UAAU,EACf,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,MAAM,EAAE,SAAS,CAAC;IAClB,mGAAmG;IACnG,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,yDAAyD;IACzD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uEAAuE;IACvE,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC;;;;;OAKG;IACH,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,MAAM,EAAE,WAAW,CAAC;IACpB,sFAAsF;IACtF,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,uDAAuD;IACvD,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,eAAe,EAAE,cAAc,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,gGAAgG;IAChG,EAAE,EAAE,EAAE,CAAC;IACP;;;OAGG;IACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;OAGG;IACH,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C,uEAAuE;IACvE,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC9B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAC1B,OAAO,kBAAkB,EACzB,MAAM,iBAAiB,KACrB,OAAO,CAAC,mBAAmB,CA+K7B,CAAC;AAuHF;;;GAGG;AACH,eAAO,MAAM,iCAAiC,GAC7C,IAAI,gBAAgB,EACpB,QAAQ,mBAAmB,KACzB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,gBAAgB,CAAA;CAAE,GAAG,CAC9C;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAMnD,CAAC"}