@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/actions/CLAUDE.md

@@ -65,8 +65,10 @@ the dispatcher's per-action rate-limit hook. Same hook fires on the HTTP
 RPC dispatcher (`create_rpc_endpoint`) and the WebSocket dispatcher
 (`register_action_ws`) — one budget per action, not per transport.
 `'ip'` keys on the resolved client IP; `'account'` keys on
-`request_context.actor.id` (post-auth) and is rejected at registration
-when paired with `auth: 'public'` (no actor to key on); `'both'` runs
+`request_context.account.id` (post-auth, account-grain — every
+authenticated action has an account regardless of whether an actor was
+resolved) and is rejected at registration when paired with
+`auth: 'public'` (no account to key on); `'both'` runs
 both checks. **Throttle-requests semantics** — every invocation records,
 regardless of outcome (different from REST login's throttle-failures
 that resets on success). The motivating threat is admin mutation oracles
@@ -233,15 +235,20 @@ route specs on the same path (GET + POST) that share one internal
 dispatcher. Per-action auth lives inside the dispatcher; the outer routes
 use `auth: {type: 'none'}` and `transaction: false`.
 
-Dispatcher phase order (POST; GET differs only at step 1):
+Dispatcher phase order (POST; GET differs only at step 1). Mirrors the
+REST authorization order in `http/route_spec.ts` so HTTP RPC and REST
+fail with the same priority (401 → 403 → 400 → handler):
 
 1. **Parse envelope** — POST body as `JsonrpcRequest` (parse errors → JSON-RPC `parse_error` 400). GET reads `method`, `id`, `params` from query string; missing `method`/`id` → 400 `invalid_request`. Integer `id` normalization: `?id=42` matches `{id: 42}`.
 2. **Lookup method** — `Map<method, RpcAction>`. Unknown method → `method_not_found`. Duplicate methods throw at construction.
 3. **GET read restriction** — GET is rejected for `side_effects: true` actions (`invalid_request` with "must use POST").
-4. **Auth check** — via `check_action_auth(spec.auth, request_context, credential_type)`. `keeper` requires `credential_type === 'daemon_token'` AND `has_role(request_context, 'keeper')` — the `has_role` alone is insufficient, session/bearer cannot elevate. `{role}` uses `has_role`. Failure → `unauthenticated` / `forbidden`.
-5. **Validate params** — `spec.input.safeParse(raw_params ?? null-if-null-schema)`. Failure → `invalid_params` with `{issues}`.
-6. **Dispatch** — `spec.side_effects` picks transaction (`route.db.transaction(tx => execute(tx))`) vs pool (`route.db`). Handler throws roll back the transaction — the catch sits outside the transaction boundary.
-7. **DEV-only output validation** — `spec.output.safeParse(output)` runs only under `DEV` (from `esm-env`). On mismatch: `log.error(...)`, return response unchanged; never throws, never mutates status.
+4. **Pre-validation auth** — `check_action_auth_pre_validation(spec.auth, account_id)`. Short-circuits with `unauthenticated` (-32001 / 401) when `auth !== 'public'` and no `ACCOUNT_ID_KEY` is on the request. Fires before input validation so unauthenticated callers don't leak `invalid_params` for methods with required input. Public actions skip the rest of the auth path.
+5. **Authorization phase** — for non-public actions, when `is_actor_implying_auth(spec.auth)` (`'keeper'` or `{role}`) or `input_schema_declares_acting(spec.input)` (the input has the canonical `acting?: ActingActor` field), `apply_authorization_phase` resolves the actor against `c.var.account_id` plus the raw `acting` string read off `params` (no schema validation yet), builds the `{account, actor, permits}` `RequestContext`, and sets `REQUEST_CONTEXT_KEY`. Authenticated-but-actor-less routes still build an account-only context via `build_account_context`. Resolution failures come back as `AuthorizationFailure` (`{status, body}`) — the auth domain stops short of producing a `Response` so each transport binds it. The RPC dispatcher folds the failure into a JSON-RPC envelope: `error.code` from `http_status_to_jsonrpc_error_code(failure.status)` (400 → `invalid_params` for `actor_required` / `actor_not_on_account`, 500 → `internal_error` for `no_actors_on_account` and `account_vanished`), `error.message` from the reason string, and `error.data: {reason, ...rest}` flattens any diagnostic fields (e.g. `available[]` for `actor_required`). The two 500 reasons are kept distinct: `no_actors_on_account` names a signup invariant violation (the actor enumeration succeeded and came back empty); `account_vanished` names a torn-read race (the account or actor row was deleted between credential validation and the dispatcher's follow-up `build_request_context` / `build_account_context` step). REST emits the same `body` directly via `c.json(body, status)` so its surface stays consistent with other middleware-emitted plain bodies. See `../auth/CLAUDE.md` § Middleware and the root `../../../CLAUDE.md` § Cleanest architecture takes priority for the rationale.
+6. **Post-authorization auth** — `check_action_auth_post_authorization(spec.auth, request_context, credential_type)`. `keeper` requires `credential_type === 'daemon_token'` AND `has_role(request_context, 'keeper')` — the `has_role` alone is insufficient, session/bearer cannot elevate; failure attaches `{reason: ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, credential_type}` under `error.data`. `{role}` uses `has_role`; failure attaches `{reason: ERROR_INSUFFICIENT_PERMISSIONS, required_role}`. Both surface as `forbidden` (-32002 / 403). `'authenticated'` already cleared step 4.
+7. **Validate params** — `spec.input.safeParse(params)` where `params` is `raw_params` for `z.void()` schemas, otherwise `raw_params ?? {}` (HTTP convention: empty body = empty object). Registration rejects `z.null()` inputs because JSON-RPC 2.0 §4.2 forbids `params: null`. Failure → `invalid_params` with `{issues}`.
+8. **Rate limit** — `spec.rate_limit` (`'ip' | 'account' | 'both'`); shared limiter pair with the WS dispatcher. Throttle-requests semantics — every invocation records, regardless of outcome. Account-keyed limiting bills `request_context.account.id` (every authenticated action has one). Failure → `rate_limited` (-32006 / 429) with `{retry_after}`.
+9. **Dispatch** — `spec.side_effects` picks transaction (`route.db.transaction(tx => execute(tx))`) vs pool (`route.db`). Handler throws roll back the transaction — the catch sits outside the transaction boundary.
+10. **DEV-only output validation** — `spec.output.safeParse(output)` runs only under `DEV` (from `esm-env`). On mismatch: `log.error(...)`, return response unchanged; never throws, never mutates status.
 
 Error paths: `ThrownJsonrpcError` (duck-typed via `err instanceof Error &&
 typeof err.code === 'number'`) preserves code + data verbatim, status via
@@ -284,9 +291,9 @@ Use this at every spec → handler binding site so handler-type errors
 surface at the factory call instead of at runtime:
 
 ```ts
-export const create_admin_actions = (deps, options) => [
-	rpc_action(admin_account_list_action_spec, account_list_handler),
-	rpc_action(admin_session_revoke_all_action_spec, session_revoke_all_handler),
+export const create_account_actions = (deps, options) => [
+	rpc_action(account_verify_action_spec, verify_handler),
+	rpc_action(account_session_list_action_spec, session_list_handler),
 	// …
 ];
 ```
@@ -297,9 +304,57 @@ handlers close over factory-captured deps (`log`, `on_audit_event`,
 `options.app_settings`, `options.max_tokens`), so per-pair typing via
 `rpc_action()` is the right shape here: the binding happens at
 construction time and the handler keeps its closure. Applied across
-`admin_actions.ts` + `permit_offer_actions.ts` + `account_actions.ts`
-— each pairs a spec imported from its `*_action_specs.ts` sibling with
-a closure-bound handler.
+`account_actions.ts` for the account-grain self-service surface (auth:
+`'authenticated'`, no `acting` in input — the dispatcher does not
+resolve an actor); the actor-implying registries (`admin_actions.ts`,
+`permit_offer_actions.ts`, `self_service_role_actions.ts`) use the
+`rpc_actor_action` variant below.
+
+### `rpc_actor_action(spec, handler)` — actor-narrowed variant
+
+Sibling factory for handlers whose dispatcher always resolves an acting
+actor — actions with `auth: 'keeper' | {role}` or input that declares
+`acting?: ActingActor`. The dispatcher's authorization phase populates
+`ctx.auth` with a non-null `RequestActorContext` before any of these
+handlers runs, so `rpc_actor_action`'s handler signature types
+`ctx: ActionActorContext` (with `auth: RequestActorContext`) and the
+handler body skips the `require_request_actor(ctx.auth)` narrowing
+call:
+
+```ts
+rpc_actor_action(permit_revoke_action_spec, async (input, ctx) => {
+	// ctx.auth is RequestActorContext — no narrowing needed.
+	const revoker_id = ctx.auth.actor.id;
+	// …
+});
+```
+
+The runtime binding is identical to `rpc_action` — both register the
+same `RpcAction` shape on the action map. The change is compile-time
+only: forgetting the actor narrowing on an actor-implying action used
+to require either an `auth.actor!` non-null assertion or a
+`require_request_actor` call; `rpc_actor_action` lets the type
+reflect what the dispatcher already guarantees, which closes the bug
+class where the narrowing call is missed and the handler is left
+operating against a possibly-null actor.
+
+Applied uniformly across the actor-implying registries: every handler
+in `admin_actions.ts` (all eleven specs declare `auth: {role: 'admin'}`
+
+- `acting: ActingActor` on input, so the dispatcher always resolves an
+  actor — list-style handlers that don't read `ctx.auth.actor` still bind
+  through `rpc_actor_action` for type-uniformity), every handler in
+  `permit_offer_actions.ts` (every spec there declares
+  `acting: ActingActor`), and the single `self_service_role_set` handler
+  in `self_service_role_actions.ts`. The rule is "actor-implying spec →
+  `rpc_actor_action`" regardless of whether the handler body reads
+  `ctx.auth.actor` — the dispatcher's runtime guarantee is what the type
+  should reflect, and uniform binding keeps a future handler that does
+  need the actor from accidentally landing on the looser binder.
+  Account-grain handlers in `account_actions.ts` keep `rpc_action`:
+  their auth is `'authenticated'`, their inputs don't declare `acting`,
+  so the dispatcher genuinely runs in `needs_actor: false` mode and
+  `ctx.auth.actor` is null.
 
 ## Transports (`transports.ts`, `transports_http.ts`, `transports_ws.ts`, `transports_ws_backend.ts`)
 

package/dist/actions/action_codegen.d.ts

@@ -154,6 +154,19 @@ export declare const to_action_spec_output_identifier: (method: string) => strin
  * follows so wrappers no longer pre-register imports a per-spec emit might
  * not actually use.
  *
+ * **Optional-input detection.** The emitted parameter is `input?:` (caller
+ * may omit the argument) when either (a) the schema accepts `undefined` —
+ * `z.optional(z.strictObject(...))` and similar wrappers — or (b) the
+ * schema accepts the empty object `{}` — `z.strictObject({acting:
+ActingActor})` and other all-optional-fields strict objects. The second
+ * probe mirrors the dispatcher's HTTP convention (`raw_params ?? {}` for
+ * non-`z.void()` schemas in `actions/action_rpc.ts` / `http/route_spec.ts`):
+ * if a request with no params reaches the handler, this is the value the
+ * schema is asked to validate. A schema with required fields fails both
+ * probes and stays `input:` (required at the typed surface). Refinements
+ * and transforms run as part of `safeParse`, so their accept/reject
+ * decisions feed into the optional/required choice naturally.
+ *
  * @param options.sync_returns_value - When true (default), sync `local_call`
  *   methods return the output value directly; when false they're wrapped in
  *   `Result<{value, error}>` like async methods. Set to `false` if your

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

@@ -1 +1 @@
-{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAGxE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,kCAAmC,CAAC;AAExE,8FAA8F;AAC9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,oBACrC,CAAC;AAEjC,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IA6BtD;;;;OAIG;IACH,KAAK,IAAI,MAAM;IAIf,WAAW,IAAI,OAAO;IAItB,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,0FAA0F;IAC1F,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAiDb;AAED,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,sGAAsG;AACtG,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,mBAAkB,MAAiC,KACjD,MAkBF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,EACtB,UAAU;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,KAC/D,MA2BF,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC;AAG/D,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAiC,CAAC;AAC7F,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAC9C,eAAO,MAAM,gCAAgC,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,eAAe,EACrB,SAAS,aAAa,EACtB,UAAU;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,KACjE,MA+BF,CAAC;AA0CF,yFAAyF;AACzF,MAAM,MAAM,oBAAoB,GAC7B,KAAK,GACL,kBAAkB,GAClB,qBAAqB,GACrB,YAAY,GACZ,UAAU,GACV,SAAS,GACT,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,CAAC;AAEf,0CAA0C;AAC1C,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,oBAAoB,CAUzE,CAAC;AAsCH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,IAAI,CAAC,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KACtF,MAiFF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC7C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,SAAS;IACR,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC;IAC9C,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAMF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,aAAa,EACtB,UAAU;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAC,KAC5D,MAcF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAkCF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MA0DF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GACvC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KAC5F,MA0CF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,6BAA6B,GACzC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAmCF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC7C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KACvE,MA+BF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAwCF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oCAAoC,GAChD,SAAS,aAAa,EACtB,UAAU;IACT,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,KACC,MAqBF,CAAC;AAMF;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,0BAA0B,GACtC,SAAS,aAAa,CAAC,UAAU,CAAC,EAClC,SAAS,aAAa,KACpB;IACF,YAAY,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IAChD,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CA6B1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9B,KAAG,MAYH,CAAC"}
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAGxE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,kCAAmC,CAAC;AAExE,8FAA8F;AAC9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,oBACrC,CAAC;AAEjC,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IA6BtD;;;;OAIG;IACH,KAAK,IAAI,MAAM;IAIf,WAAW,IAAI,OAAO;IAItB,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,0FAA0F;IAC1F,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAiDb;AAED,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,sGAAsG;AACtG,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,mBAAkB,MAAiC,KACjD,MAkBF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,EACtB,UAAU;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,KAC/D,MA2BF,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC;AAG/D,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAiC,CAAC;AAC7F,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAC9C,eAAO,MAAM,gCAAgC,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,eAAe,EACrB,SAAS,aAAa,EACtB,UAAU;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,KACjE,MAiCF,CAAC;AA0CF,yFAAyF;AACzF,MAAM,MAAM,oBAAoB,GAC7B,KAAK,GACL,kBAAkB,GAClB,qBAAqB,GACrB,YAAY,GACZ,UAAU,GACV,SAAS,GACT,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,CAAC;AAEf,0CAA0C;AAC1C,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,oBAAoB,CAUzE,CAAC;AAsCH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,IAAI,CAAC,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KACtF,MAiFF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC7C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,SAAS;IACR,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC;IAC9C,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAMF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,aAAa,EACtB,UAAU;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAC,KAC5D,MAcF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAkCF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MA0DF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GACvC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KAC5F,MA0CF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,6BAA6B,GACzC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAmCF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC7C,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAC,KACvE,MA+BF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,aAAa,CAAC,eAAe,CAAC,EACrC,SAAS,aAAa,EACtB,UAAU;IACT,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IACjD,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC,KACC,MAwCF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oCAAoC,GAChD,SAAS,aAAa,EACtB,UAAU;IACT,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,KACC,MAqBF,CAAC;AAMF;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,0BAA0B,GACtC,SAAS,aAAa,CAAC,UAAU,CAAC,EAClC,SAAS,aAAa,KACpB;IACF,YAAY,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC;IAChD,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CA6B1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9B,KAAG,MAYH,CAAC"}

package/dist/actions/action_codegen.js

@@ -330,6 +330,19 @@ export const to_action_spec_output_identifier = (method) => `${to_action_spec_id
  * follows so wrappers no longer pre-register imports a per-spec emit might
  * not actually use.
  *
+ * **Optional-input detection.** The emitted parameter is `input?:` (caller
+ * may omit the argument) when either (a) the schema accepts `undefined` —
+ * `z.optional(z.strictObject(...))` and similar wrappers — or (b) the
+ * schema accepts the empty object `{}` — `z.strictObject({acting:
+ActingActor})` and other all-optional-fields strict objects. The second
+ * probe mirrors the dispatcher's HTTP convention (`raw_params ?? {}` for
+ * non-`z.void()` schemas in `actions/action_rpc.ts` / `http/route_spec.ts`):
+ * if a request with no params reaches the handler, this is the value the
+ * schema is asked to validate. A schema with required fields fails both
+ * probes and stays `input:` (required at the typed surface). Refinements
+ * and transforms run as part of `safeParse`, so their accept/reject
+ * decisions feed into the optional/required choice naturally.
+ *
  * @param options.sync_returns_value - When true (default), sync `local_call`
  *   methods return the output value directly; when false they're wrapped in
  *   `Result<{value, error}>` like async methods. Set to `false` if your
@@ -343,8 +356,9 @@ export const generate_actions_api_method_signature = (spec, imports, options) =>
     const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
     const innermost_type_name = zod_get_base_type(spec.input);
     const has_input = innermost_type_name !== 'null' && innermost_type_name !== 'void';
+    const input_optional = has_input && (spec.input.safeParse(undefined).success || spec.input.safeParse({}).success);
     const input_param = has_input
-        ? `input${spec.input.safeParse(undefined).success ? '?' : ''}: ActionInputs['${spec.method}']`
+        ? `input${input_optional ? '?' : ''}: ActionInputs['${spec.method}']`
         : 'input?: void';
     if (has_input)
         imports.add_type(collections_path, 'ActionInputs');

package/dist/actions/action_rpc.d.ts

@@ -15,7 +15,7 @@ import { z } from 'zod';
 import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { RequestResponseActionSpec } from './action_spec.js';
 import { type RouteSpec } from '../http/route_spec.js';
-import { type RequestContext } from '../auth/request_context.js';
+import { type RequestActorContext, type RequestContext } from '../auth/request_context.js';
 import type { Db } from '../db/db.js';
 import { type JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { RateLimiter } from '../rate_limiter.js';
@@ -72,6 +72,24 @@ export interface ActionContext {
  * Returns the output value (serialized to JSON by the wrapper).
  */
 export type ActionHandler<TInput = any, TOutput = any> = (input: TInput, ctx: ActionContext) => TOutput | Promise<TOutput>;
+/**
+ * `ActionContext` narrowed to a resolved acting actor.
+ *
+ * Returned to handlers bound via `rpc_actor_action` — the dispatcher's
+ * authorization phase has already run for actor-implying auth or
+ * `acting`-declaring inputs, so `ctx.auth.actor` is non-null and the
+ * handler skips the `require_request_actor(ctx.auth)` narrowing call.
+ */
+export interface ActionActorContext extends Omit<ActionContext, 'auth'> {
+    auth: RequestActorContext;
+}
+/**
+ * Handler function for an RPC action whose dispatcher always resolves an
+ * acting actor (`auth: 'keeper' | {role}` or input declaring
+ * `acting?: ActingActor`). Mirrors `ActionHandler` but tightens the
+ * `ctx.auth` slot to the non-null `RequestActorContext`.
+ */
+export type ActorActionHandler<TInput = any, TOutput = any> = (input: TInput, ctx: ActionActorContext) => TOutput | Promise<TOutput>;
 /**
  * An RPC action — combines an action spec with its handler.
  *
@@ -101,6 +119,30 @@ export interface RpcAction {
  * at the registration site is the right fit.
  */
 export declare const rpc_action: <TSpec extends RequestResponseActionSpec>(spec: TSpec, handler: ActionHandler<z.infer<TSpec["input"]>, z.infer<TSpec["output"]>>) => RpcAction;
+/**
+ * Variant of `rpc_action` for handlers whose spec always resolves an
+ * acting actor — actions with `auth: 'keeper' | {role}` or inputs that
+ * declare `acting?: ActingActor`. The dispatcher's authorization phase
+ * runs before the handler, populates `ctx.auth` with a non-null
+ * `RequestActorContext`, and `rpc_actor_action` reflects that
+ * guarantee in the handler signature so the handler body skips the
+ * `require_request_actor(ctx.auth)` narrowing call (and the bug class
+ * where forgetting that call fails open against a `null` actor).
+ *
+ * The runtime binding is identical to `rpc_action` — both register the
+ * same `RpcAction` shape on the action map. Only the compile-time
+ * handler signature differs.
+ *
+ * @example
+ * ```ts
+ * rpc_actor_action(permit_revoke_action_spec, async (input, ctx) => {
+ *   // ctx.auth is RequestActorContext — no require_request_actor() needed.
+ *   const revoker_id = ctx.auth.actor.id;
+ *   // ...
+ * });
+ * ```
+ */
+export declare const rpc_actor_action: <TSpec extends RequestResponseActionSpec>(spec: TSpec, handler: ActorActionHandler<z.infer<TSpec["input"]>, z.infer<TSpec["output"]>>) => RpcAction;
 /** Options for `create_rpc_endpoint`. */
 export interface CreateRpcEndpointOptions {
     /** Mount path for the endpoint (e.g., `/api/rpc`). */
@@ -118,10 +160,12 @@ export interface CreateRpcEndpointOptions {
      */
     action_ip_rate_limiter?: RateLimiter | null;
     /**
-     * Per-actor rate limiter consulted for actions whose spec declares
+     * Per-account rate limiter consulted for actions whose spec declares
      * `rate_limit: 'account'` or `'both'`. Keyed on
-     * `request_context.actor.id`. `null` disables the account check.
-     * Same limiter is shared with the WebSocket action dispatcher.
+     * `request_context.account.id` (account-grain — billed to the
+     * authenticated account regardless of which actor was resolved).
+     * `null` disables the account check. Same limiter is shared with the
+     * WebSocket action dispatcher.
      */
     action_account_rate_limiter?: RateLimiter | null;
 }
@@ -134,9 +178,18 @@ 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. **Auth check** — verify identity against the action's `auth` requirement.
- * 4. **Validate params** — parse input against the action's `input` schema.
- * 5. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
+ * 3. **Pre-validation auth** — short-circuit `unauthenticated` when no
+ *    account is on the request, before input validation runs.
+ * 4. **Authorization phase** — resolve the acting actor (when the action's
+ *    auth requires permits or its input declares `acting?: ActingActor`)
+ *    and build the request context. Runs before input validation so
+ *    permit-grain auth checks return 403 before 400 invalid_params;
+ *    `acting` is read from raw params via a string typeguard.
+ * 5. **Post-authorization auth** — enforce role / keeper requirements
+ *    against the request context.
+ * 6. **Validate params** — parse input against the action's `input` schema.
+ * 7. **Rate limit** — per-action IP / account throttling.
+ * 8. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
  *    construct `ActionContext`, call handler, return JSON-RPC response.
  *
  * GET is restricted to `side_effects: false` actions (cacheable reads).

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":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;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;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,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;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjD;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAkTtF,CAAC"}
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"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"}

package/dist/actions/action_rpc.js

@@ -15,11 +15,11 @@ import { z } from 'zod';
 import { DEV } from 'esm-env';
 import {} from '../http/route_spec.js';
 import { get_client_ip } from '../http/proxy.js';
-import { get_request_context, has_role } from '../auth/request_context.js';
-import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { apply_authorization_phase, get_request_context, has_role, input_schema_declares_acting, is_actor_implying_auth, } from '../auth/request_context.js';
+import { ACCOUNT_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
 import { is_null_schema, is_void_schema } from '../http/schema_helpers.js';
 import { JSONRPC_VERSION, JsonrpcRequest, } from '../http/jsonrpc.js';
-import { jsonrpc_error_messages, jsonrpc_error_code_to_http_status, JSONRPC_ERROR_CODES, } from '../http/jsonrpc_errors.js';
+import { jsonrpc_error_messages, jsonrpc_error_code_to_http_status, http_status_to_jsonrpc_error_code, JSONRPC_ERROR_CODES, } from '../http/jsonrpc_errors.js';
 import { ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } from '../http/error_schemas.js';
 /**
  * Pair a spec with a handler while preserving per-method input/output types.
@@ -43,22 +43,68 @@ export const rpc_action = (spec, handler) => ({
     spec,
     handler: handler,
 });
+/**
+ * Variant of `rpc_action` for handlers whose spec always resolves an
+ * acting actor — actions with `auth: 'keeper' | {role}` or inputs that
+ * declare `acting?: ActingActor`. The dispatcher's authorization phase
+ * runs before the handler, populates `ctx.auth` with a non-null
+ * `RequestActorContext`, and `rpc_actor_action` reflects that
+ * guarantee in the handler signature so the handler body skips the
+ * `require_request_actor(ctx.auth)` narrowing call (and the bug class
+ * where forgetting that call fails open against a `null` actor).
+ *
+ * The runtime binding is identical to `rpc_action` — both register the
+ * same `RpcAction` shape on the action map. Only the compile-time
+ * handler signature differs.
+ *
+ * @example
+ * ```ts
+ * rpc_actor_action(permit_revoke_action_spec, async (input, ctx) => {
+ *   // ctx.auth is RequestActorContext — no require_request_actor() needed.
+ *   const revoker_id = ctx.auth.actor.id;
+ *   // ...
+ * });
+ * ```
+ */
+export const rpc_actor_action = (spec, handler) => ({
+    spec,
+    handler: handler,
+});
 const jsonrpc_error_response = (id, error) => ({
     jsonrpc: JSONRPC_VERSION,
     id,
     error,
 });
 /**
- * Check auth for an action spec against the request context.
+ * 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.
  *
- * @returns a JSON-RPC error object if auth fails, or `null` if authorized
+ * Reads `c.var.auth_account_id` (set by the auth middleware). Returns
+ * `unauthenticated` when `auth !== 'public'` and no account is on the
+ * request. Role / keeper checks are deferred until after the
+ * authorization phase populates the request context — see
+ * `check_action_auth_post_authorization`.
+ *
+ * @returns a JSON-RPC error object if no account is on the request, or `null`
  */
-const check_action_auth = (auth, request_context, credential_type) => {
+const check_action_auth_pre_validation = (auth, account_id) => {
     if (auth === 'public')
         return null;
-    if (!request_context)
+    if (account_id == null)
         return jsonrpc_error_messages.unauthenticated();
-    if (auth === 'authenticated')
+    return null;
+};
+/**
+ * Post-authorization auth gate — fires after the dispatcher's authorization
+ * phase has populated `REQUEST_CONTEXT_KEY` with the resolved actor +
+ * permits. Enforces `role` and `keeper` requirements; `'public'` and
+ * `'authenticated'` already cleared the pre-validation gate.
+ *
+ * @returns a JSON-RPC error object if permit / credential check fails, or `null`
+ */
+const check_action_auth_post_authorization = (auth, request_context, credential_type) => {
+    if (auth === 'public' || auth === 'authenticated')
         return null;
     if (auth === 'keeper') {
         // keeper requires daemon_token credential type AND the keeper role.
@@ -94,9 +140,18 @@ const check_action_auth = (auth, request_context, credential_type) => {
  * 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. **Auth check** — verify identity against the action's `auth` requirement.
- * 4. **Validate params** — parse input against the action's `input` schema.
- * 5. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
+ * 3. **Pre-validation auth** — short-circuit `unauthenticated` when no
+ *    account is on the request, before input validation runs.
+ * 4. **Authorization phase** — resolve the acting actor (when the action's
+ *    auth requires permits or its input declares `acting?: ActingActor`)
+ *    and build the request context. Runs before input validation so
+ *    permit-grain auth checks return 403 before 400 invalid_params;
+ *    `acting` is read from raw params via a string typeguard.
+ * 5. **Post-authorization auth** — enforce role / keeper requirements
+ *    against the request context.
+ * 6. **Validate params** — parse input against the action's `input` schema.
+ * 7. **Rate limit** — per-action IP / account throttling.
+ * 8. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
  *    construct `ActionContext`, call handler, return JSON-RPC response.
  *
  * GET is restricted to `side_effects: false` actions (cacheable reads).
@@ -115,7 +170,6 @@ const check_action_auth = (auth, request_context, credential_type) => {
  */
 export const create_rpc_endpoint = (options) => {
     const { path: endpoint_path, actions, log, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
-    // build action lookup map
     const action_map = new Map();
     for (const action of actions) {
         if (action_map.has(action.spec.method)) {
@@ -151,20 +205,98 @@ export const create_rpc_endpoint = (options) => {
             }));
             return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_request));
         }
-        // step 3: auth check
+        // step 3: pre-validation auth — short-circuit with `unauthenticated`
+        // when no account is on the request before input validation runs,
+        // so callers without credentials don't see `invalid_params` for
+        // methods with required input.
+        const action_auth = action.spec.auth;
+        const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
+        const pre_validation_auth_error = check_action_auth_pre_validation(action_auth, account_id);
+        if (pre_validation_auth_error) {
+            const error = jsonrpc_error_response(id, pre_validation_auth_error);
+            return c.json(error, jsonrpc_error_code_to_http_status(pre_validation_auth_error.code));
+        }
+        // step 4: authorization phase — resolves the acting actor and
+        // builds the request context. Runs before input validation so
+        // permit-grain auth checks (`role` / `keeper`) surface 403
+        // before 400 invalid_params. `acting` is read from raw params
+        // (string typeguard) so multi-actor callers can still pick a
+        // persona without paying for full validation up front; an
+        // invalid `acting` shape will be rejected by step 5's input
+        // validation if it survives the authorization probe.
+        //
+        // Resolution failures come back as `{status, body}` so this
+        // dispatcher can fold them into a JSON-RPC error envelope —
+        // REST emits the same `body` directly. The reason string lands
+        // on `error.message` and `error.data.reason`; remaining
+        // diagnostic fields (e.g. `available[]` for `actor_required`)
+        // flatten under `error.data` so wire callers see structured
+        // data instead of a status-coded synthetic envelope.
+        if (action_auth !== 'public') {
+            const declares_acting = input_schema_declares_acting(action.spec.input);
+            const needs_actor = is_actor_implying_auth(action_auth) || declares_acting;
+            const raw_acting = declares_acting && typeof raw_params === 'object' && raw_params !== null
+                ? raw_params.acting
+                : undefined;
+            const acting_value = typeof raw_acting === 'string' ? raw_acting : undefined;
+            const failure = await apply_authorization_phase({ db: route.db }, c, needs_actor, acting_value);
+            if (failure) {
+                // `error.code` comes from `http_status_to_jsonrpc_error_code(failure.status)` so the
+                // wire shape stays uniform with every other JSON-RPC failure path. The 400 mapping
+                // lands on `invalid_params` even though `actor_required` / `actor_not_on_account`
+                // are not strictly "params malformed" failures — the alternative would be inventing
+                // a JSON-RPC code outside the http-status mapping just for these two reasons. The
+                // slight semantic mismatch is acceptable because consumers key on
+                // `error.data.reason`, never on `error.code` (the in-tree consumers — zzz, tx,
+                // visiones, mageguild — never match on the actor reason strings via `error.code`).
+                // The 500 mapping (`internal_error`) for `no_actors_on_account` / `account_vanished`
+                // is on-the-nose.
+                const { error: reason, ...rest } = failure.body;
+                const code = http_status_to_jsonrpc_error_code(failure.status);
+                const error = jsonrpc_error_response(id, {
+                    code,
+                    message: reason,
+                    data: { reason, ...rest },
+                });
+                return c.json(error, failure.status);
+            }
+        }
+        // step 5: post-authorization auth — gate role / keeper requirements
+        // against the request context populated by the authorization phase.
         const request_context = get_request_context(c);
         const credential_type = c.get(CREDENTIAL_TYPE_KEY) ?? null;
-        const auth_error = check_action_auth(action.spec.auth, request_context, credential_type);
-        if (auth_error) {
-            const error = jsonrpc_error_response(id, auth_error);
-            return c.json(error, jsonrpc_error_code_to_http_status(auth_error.code));
+        const post_authorization_auth_error = check_action_auth_post_authorization(action_auth, request_context, credential_type);
+        if (post_authorization_auth_error) {
+            const error = jsonrpc_error_response(id, post_authorization_auth_error);
+            return c.json(error, jsonrpc_error_code_to_http_status(post_authorization_auth_error.code));
+        }
+        // step 6: validate params
+        // Missing `params` on the envelope maps to `undefined` for `z.void()`
+        // input schemas and `{}` for object inputs (matches HTTP's "empty
+        // body = empty object" convention so callers of all-optional-object
+        // RPC methods can omit `params` on the wire). JSON-RPC 2.0 §4.2
+        // forbids `params: null`, so `z.void()` is the spec-correct schema
+        // for parameterless methods — registration above rejects `z.null()`
+        // inputs to keep this branch from having to consider that legacy
+        // shape. When `raw_params` is present it flows through unchanged so
+        // contract-violating shapes still fail validation.
+        const params = is_void_schema(action.spec.input) ? raw_params : (raw_params ?? {});
+        const parse_result = action.spec.input.safeParse(params);
+        if (!parse_result.success) {
+            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params('invalid params', {
+                issues: parse_result.error.issues,
+            }));
+            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_params));
         }
-        // step 3.5: rate limit — throttle-requests semantics (record on every
+        // step 7: rate limit — throttle-requests semantics (record on every
         // invocation, no success-reset). Suits admin mutation oracles where
         // the *successful* call is the threat. Different from REST login's
         // throttle-failures pattern that resets on success. Silent partial
         // enforcement: a key is checked iff its bucket's limiter is wired —
         // `rate_limit: 'both'` with only one limiter set runs only that side.
+        // Account-keyed limiting bills the authenticated account: every
+        // authenticated action has `request_context.account.id`, regardless
+        // of whether an actor was resolved.
         const rate_limit = action.spec.rate_limit;
         const client_ip = get_client_ip(c);
         if (rate_limit) {
@@ -182,34 +314,16 @@ export const create_rpc_endpoint = (options) => {
                     return reject(result.retry_after);
             }
             if (account_check) {
-                const result = action_account_rate_limiter.check(request_context.actor.id);
+                const result = action_account_rate_limiter.check(request_context.account.id);
                 if (!result.allowed)
                     return reject(result.retry_after);
             }
             if (ip_check)
                 action_ip_rate_limiter.record(client_ip);
             if (account_check)
-                action_account_rate_limiter.record(request_context.actor.id);
-        }
-        // step 4: validate params
-        // Missing `params` on the envelope maps to `undefined` for `z.void()`
-        // input schemas and `{}` for object inputs (matches HTTP's "empty
-        // body = empty object" convention so callers of all-optional-object
-        // RPC methods can omit `params` on the wire). JSON-RPC 2.0 §4.2
-        // forbids `params: null`, so `z.void()` is the spec-correct schema
-        // for parameterless methods — registration above rejects `z.null()`
-        // inputs to keep this branch from having to consider that legacy
-        // shape. When `raw_params` is present it flows through unchanged so
-        // contract-violating shapes still fail validation.
-        const params = is_void_schema(action.spec.input) ? raw_params : (raw_params ?? {});
-        const parse_result = action.spec.input.safeParse(params);
-        if (!parse_result.success) {
-            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params('invalid params', {
-                issues: parse_result.error.issues,
-            }));
-            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_params));
+                action_account_rate_limiter.record(request_context.account.id);
         }
-        // step 5: dispatch — transaction for mutations, pool for reads
+        // step 8: dispatch — transaction for mutations, pool for reads
         const use_transaction = action.spec.side_effects;
         const notify = (notify_method, _notify_params) => {
             if (DEV) {
@@ -251,13 +365,13 @@ export const create_rpc_endpoint = (options) => {
             // Duck-type check: Error with numeric `code` signals a JSON-RPC error.
             // Avoids instanceof which fails when consumers throw their own ThrownJsonrpcError
             // (structurally identical but different class identity, e.g. zzz's copy).
-            if (err instanceof Error && typeof err.code === 'number') {
-                const code = err.code;
-                const data = err.data;
+            const error_like = err;
+            if (err instanceof Error && typeof error_like.code === 'number') {
+                const code = error_like.code;
                 const status = jsonrpc_error_code_to_http_status(code);
                 const error_json = { code, message: err.message };
-                if (data !== undefined)
-                    error_json.data = data;
+                if (error_like.data !== undefined)
+                    error_json.data = error_like.data;
                 return c.json(jsonrpc_error_response(id, error_json), status);
             }
             // generic error

package/dist/actions/register_action_ws.d.ts

@@ -23,8 +23,8 @@
  * The consumer is responsible for rejecting unauthenticated upgrades *before*
  * routing to this handler (fuz_app's `require_auth` middleware, or
  * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
- * `get_request_context(c)` is treated as guaranteed non-null and per-action
- * auth is enforced on each message.
+ * `require_request_context(c)` enforces the dispatcher invariant and
+ * per-action auth is enforced on each message.
  *
  * @module
  */
@@ -150,9 +150,9 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
      */
     action_ip_rate_limiter?: RateLimiter | null;
     /**
-     * Per-actor rate limiter consulted for actions whose spec declares
+     * Per-account rate limiter consulted for actions whose spec declares
      * `rate_limit: 'account'` or `'both'`. Keyed on
-     * `request_context.actor.id`. `null` (or omitted) disables the
+     * `request_context.account.id`. `null` (or omitted) disables the
      * account check. Same limiter is shared with the HTTP RPC dispatcher.
      */
     action_account_rate_limiter?: RateLimiter | null;