@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/auth/request_context.js

@@ -1,5 +1,5 @@
 /**
- * Request context middleware and permit checking helpers.
+ * Request context middleware and role_grant checking helpers.
  *
  * Two-phase identity resolution:
  *
@@ -7,41 +7,40 @@
  *    `bearer_auth`, and `daemon_token_middleware` validate the credential
  *    (session cookie, bearer token, daemon token) and set `c.var.account_id`
  *    + `c.var.credential_type` on the Hono context. They do not resolve
- *    an acting actor or load permits; `REQUEST_CONTEXT_KEY` stays null at
+ *    an acting actor or load role_grants; `REQUEST_CONTEXT_KEY` stays null at
  *    this stage, so account-grain identity is the only thing known.
  * 2. **Authorization (route-spec wrapper / RPC dispatcher)** — after input
  *    validation, the per-route layer inspects the route. If the input
  *    schema declared `acting?: ActingActor` (reference equality with the
- *    canonical `ActingActor` schema) or the auth requires permits
+ *    canonical `ActingActor` schema) or the auth requires role_grants
  *    (`role` / `keeper`), `apply_authorization_phase` resolves the actor
  *    against `c.var.account_id` plus the validated `acting` value via
- *    `resolve_acting_actor`, builds the `{account, actor, permits}`
+ *    `resolve_acting_actor`, builds the `{account, actor, role_grants}`
  *    context via `build_request_context`, and sets it on
  *    `REQUEST_CONTEXT_KEY` before auth guards fire. Authenticated routes
  *    that don't need an actor still get an account-only context via
  *    `build_account_context` so handler signatures stay uniform.
  *
  * Account-grain operations (logout, password_change, account_verify,
- * etc.) declare neither `acting` nor permit-requiring auth, so no actor
+ * etc.) declare neither `acting` nor role_grant-requiring auth, so no actor
  * is resolved and their handlers see a `RequestContext` with
- * `actor: null` + empty `permits`. They never trigger `actor_required`,
+ * `actor: null` + empty `role_grants`. They never trigger `actor_required`,
  * which is what makes multi-actor logout work without first picking a
  * persona.
  *
- * `build_request_context` loads `account → actor → permits` and verifies
- * the `actor.account_id === account.id` binding. `refresh_permits`
- * reloads permits on an existing context.
+ * `build_request_context` loads `account → actor → role_grants` and verifies
+ * the `actor.account_id === account.id` binding. `refresh_role_grants`
+ * reloads role_grants on an existing context.
  *
  * @module
  */
-import { z } from 'zod';
-import { zod_unwrap_to_object } from '@fuzdev/fuz_util/zod.js';
-import { ActingActor, is_permit_active, } from './account_schema.js';
+import { is_role_grant_active } from './account_schema.js';
 import { hash_session_token, session_touch_fire_and_forget, query_session_get_valid, } from './session_queries.js';
 import { query_account_by_id, query_actor_by_id, query_actors_by_account, } from './account_queries.js';
-import { query_permit_find_active_for_actor } from './permit_queries.js';
-import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CACHED_REQUEST_BODY_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY, } from '../hono_context.js';
-import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_ACCOUNT, ERROR_ACCOUNT_VANISHED, } from '../http/error_schemas.js';
+import { query_role_grant_find_active_for_actor } from './role_grant_queries.js';
+import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY, } from '../hono_context.js';
+import { is_public_auth, needs_actor } from '../http/auth_shape.js';
+import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_ACCOUNT, ERROR_ACCOUNT_VANISHED, } from '../http/error_schemas.js';
 /** Hono context variable name for the request context. */
 export const REQUEST_CONTEXT_KEY = 'request_context';
 /**
@@ -83,41 +82,9 @@ export const require_request_context = (c) => {
     return ctx;
 };
 /**
- * Narrow `RequestContext | null` to a non-null context (auth invariant).
+ * Check if a request context has an active role_grant for a given role.
  *
- * Use in RPC action handlers whose spec is non-public — the dispatcher's
- * pre-validation auth gate has already short-circuited unauthenticated
- * callers, so `ctx.auth` is non-null by the time the handler runs.
- *
- * @throws Error when called from a public-auth handler (programmer error)
- */
-export const require_request_auth = (auth) => {
-    if (!auth) {
-        throw new Error('require_request_auth: no auth — is this handler bound to a non-public action spec?');
-    }
-    return auth;
-};
-/**
- * Narrow `RequestContext | null` to `RequestActorContext` (actor invariant).
- *
- * Use in RPC action handlers whose spec declares `auth: 'keeper' | {role}`
- * or whose input declares `acting?: ActingActor` — the dispatcher's
- * authorization phase resolves an actor before the handler runs. Replaces
- * the `ctx.auth!.actor!.id` chain that the type system can't otherwise see.
- *
- * @throws Error when the handler runs without actor resolution (programmer error)
- */
-export const require_request_actor = (auth) => {
-    const ctx = require_request_auth(auth);
-    if (!ctx.actor) {
-        throw new Error('require_request_actor: no actor — is this handler bound to an actor-implying spec (keeper/role) or one whose input declares `acting`?');
-    }
-    return ctx;
-};
-/**
- * Check if a request context has an active permit for a given role.
- *
- * Checks the permits already loaded in the context (no DB query).
+ * Checks the role_grants already loaded in the context (no DB query).
  * Null-tolerant — `null` ctx (unauthenticated) returns `false`. Symmetric
  * with `has_scoped_role` / `has_any_scoped_role` so the three helpers
  * compose freely in the same predicate (e.g.
@@ -126,15 +93,15 @@ export const require_request_actor = (auth) => {
  * @param ctx - the request context, or `null` for unauthenticated callers
  * @param role - the role to check
  * @param now - current time (defaults to `new Date()`, pass for testability and hot-path efficiency)
- * @returns `true` if the actor has an active permit for the role
+ * @returns `true` if the actor has an active role_grant for the role
  */
-export const has_role = (ctx, role, now = new Date()) => ctx?.permits.some((p) => p.role === role && is_permit_active(p, now)) ?? false;
+export const has_role = (ctx, role, now = new Date()) => ctx?.role_grants.some((p) => p.role === role && is_role_grant_active(p, now)) ?? false;
 /**
- * Whether the request context holds an active permit for `role` at `scope_id`.
+ * Whether the request context holds an active role_grant for `role` at `scope_id`.
  *
- * Walks the in-memory `ctx.permits` snapshot loaded once per request by
+ * Walks the in-memory `ctx.role_grants` snapshot loaded once per request by
  * the route-spec / RPC dispatcher's authorization phase (when the route
- * declares `acting?: ActingActor` or has permit-requiring auth); zero DB
+ * declares `acting?: ActingActor` or has role_grant-requiring auth); zero DB
  * roundtrip per check. The "freshness" framing of a SQL re-query is
  * illusory because the race window is between predicate and the actual
  * mutation, not predicate and authorization load. Closing that race needs
@@ -142,30 +109,31 @@ export const has_role = (ctx, role, now = new Date()) => ctx?.permits.some((p) =
  * provides.
  *
  * Null-tolerant — `null` ctx (unauthenticated) and account-grain
- * contexts (`actor: null`, empty `permits`) both return `false`. Same
- * convention as `has_role`; lets the helper drop into `auth: 'public'`
- * or account-grain handlers without a manual narrow. See `cell_authorize`
- * for the resource-side analog.
+ * contexts (`actor: null`, empty `role_grants`) both return `false`. Same
+ * convention as `has_role`; lets the helper drop into public
+ * (`{account: 'none', actor: 'none'}`) and account-grain
+ * (`{account: 'required', actor: 'none'}`) handlers without a manual
+ * narrow. See `cell_authorize` for the resource-side analog.
  *
- * `scope_id` semantics: in-memory `permit.scope_id` is `string | null`, so
+ * `scope_id` semantics: in-memory `role_grant.scope_id` is `string | null`, so
  * JS `===` matches the SQL `IS NOT DISTINCT FROM` semantics exactly:
  *
- * - `scope_id === null` matches global permits (`scope_id IS NULL`).
- * - `scope_id === '<uuid>'` matches permits bound to that exact scope.
+ * - `scope_id === null` matches global role_grants (`scope_id IS NULL`).
+ * - `scope_id === '<uuid>'` matches role_grants bound to that exact scope.
  *
  * @param ctx - the request context, or `null` for unauthenticated callers
  * @param role - the role to check
  * @param scope_id - the scope to check (`null` for global)
  * @param now - current time (defaults to `new Date()`, pass for testability and hot-path efficiency)
- * @returns `true` iff the actor holds an active permit for the role at the requested scope
+ * @returns `true` iff the actor holds an active role_grant for the role at the requested scope
  */
 export const has_scoped_role = (ctx, role, scope_id, now = new Date()) => {
     if (!ctx)
         return false;
-    return ctx.permits.some((p) => p.role === role && p.scope_id === scope_id && is_permit_active(p, now));
+    return ctx.role_grants.some((p) => p.role === role && p.scope_id === scope_id && is_role_grant_active(p, now));
 };
 /**
- * Whether the request context holds an active permit for any role in `roles`
+ * Whether the request context holds an active role_grant for any role in `roles`
  * at `scope_id`. Empty `roles` short-circuits to `false` — documents intent
  * at the call site ("zero roles trivially admit no-one"). Same scope and
  * null-tolerance semantics as `has_scoped_role`.
@@ -174,14 +142,14 @@ export const has_scoped_role = (ctx, role, scope_id, now = new Date()) => {
  * @param roles - the roles that would admit the caller (any-of)
  * @param scope_id - the scope to check (`null` for global)
  * @param now - current time (defaults to `new Date()`, pass for testability)
- * @returns `true` iff the actor holds an active permit for any role in `roles` at the requested scope
+ * @returns `true` iff the actor holds an active role_grant for any role in `roles` at the requested scope
  */
 export const has_any_scoped_role = (ctx, roles, scope_id, now = new Date()) => {
     if (!ctx)
         return false;
     if (roles.length === 0)
         return false;
-    return ctx.permits.some((p) => roles.includes(p.role) && p.scope_id === scope_id && is_permit_active(p, now));
+    return ctx.role_grants.some((p) => roles.includes(p.role) && p.scope_id === scope_id && is_role_grant_active(p, now));
 };
 /**
  * Resolve the acting actor for an authenticated request.
@@ -229,7 +197,7 @@ export const resolve_acting_actor = async (deps, account_id, acting_actor_id) =>
  * Reads the session identity (set by session middleware), looks up the
  * `auth_session`, and on a valid session sets `c.var.auth_account_id`,
  * `CREDENTIAL_TYPE_KEY = 'session'`, and `AUTH_SESSION_TOKEN_HASH_KEY`.
- * Touches the session (fire-and-forget). Does not load actor or permits;
+ * Touches the session (fire-and-forget). Does not load actor or role_grants;
  * `REQUEST_CONTEXT_KEY` is left null — the route-spec / RPC dispatcher
  * authorization phase resolves the acting actor and builds the full
  * `RequestContext` when the route needs one.
@@ -280,55 +248,99 @@ export const require_auth = async (c, next) => {
     await next();
 };
 /**
- * Create middleware that requires a specific role.
- *
- * Returns 401 if unauthenticated, 403 if the role is missing. Reads
- * `REQUEST_CONTEXT_KEY` because role-gated routes always run the
- * dispatcher's authorization phase before this guard (the phase sets the
- * actor-bound `RequestContext`).
- *
- * @param role - the required role
+ * Create middleware that requires the actor to hold any of the given
+ * roles globally (`scope_id IS NULL`).
+ *
+ * Returns 401 if unauthenticated, 403 if none of the roles are present.
+ * Reads `REQUEST_CONTEXT_KEY` because role-gated routes always run the
+ * dispatcher's authorization phase before this guard (the phase sets
+ * the actor-bound `RequestContext`).
+ *
+ * Uses `has_any_scoped_role(ctx, roles, null)` so the gate matches
+ * **global / unscoped role_grants only**. A scoped role_grant
+ * (`{role: 'admin', scope_id: <some uuid>}`) does not unlock route-spec
+ * gates that are inherently global. The same scope-aware check is
+ * mirrored in `actions/action_rpc.ts` (HTTP RPC dispatcher) and
+ * `actions/register_action_ws.ts` (WS dispatcher) so all three
+ * transports agree.
+ *
+ * Multi-role disjunction (any-of) lets `auth.roles: ['admin', 'steward']`
+ * specs translate to one middleware that admits either role. Single-role
+ * routes pass `[role_name]`; the array shape is uniform.
+ *
+ * @param roles - the roles to admit (any-of)
  */
-export const require_role = (role) => {
+export const require_role = (roles) => {
     return async (c, next) => {
         if (c.get(ACCOUNT_ID_KEY) == null) {
             return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
         }
         const ctx = get_request_context(c);
-        if (!ctx || !has_role(ctx, role)) {
-            return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_role: role }, 403);
+        if (!ctx || !has_any_scoped_role(ctx, roles, null)) {
+            return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_roles: roles }, 403);
         }
         await next();
     };
 };
 /**
- * Reload active permits from the database, returning a new request context.
+ * Create middleware that requires the request's `credential_type` to be
+ * one of the given values.
+ *
+ * Returns 401 if unauthenticated, 403 with
+ * `ERROR_CREDENTIAL_TYPE_REQUIRED` + `required_credential_types` echoing
+ * the spec's allowlist when the wire-side credential isn't in it.
+ * Body shape is symmetric with the role gate (`ERROR_INSUFFICIENT_PERMISSIONS` +
+ * `required_roles`) and matches what the RPC dispatcher's post-auth
+ * gate emits for the same condition. Today's only credential gate is
+ * keeper (`['daemon_token']`); future gates (`agent_token`,
+ * `group_actor_token`) reuse this literal and label themselves through
+ * the array.
+ *
+ * @param credential_types - allowed credential types (any-of)
+ */
+export const require_credential_types = (credential_types) => {
+    return async (c, next) => {
+        if (c.get(ACCOUNT_ID_KEY) == null) {
+            return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
+        }
+        const credential_type = c.get(CREDENTIAL_TYPE_KEY) ?? null;
+        if (!credential_type || !credential_types.includes(credential_type)) {
+            return c.json({
+                error: ERROR_CREDENTIAL_TYPE_REQUIRED,
+                required_credential_types: credential_types,
+            }, 403);
+        }
+        await next();
+    };
+};
+/**
+ * Reload active role_grants from the database, returning a new request context.
  *
- * Useful for long-lived WebSocket connections where permits may change
+ * Useful for long-lived WebSocket connections where role_grants may change
  * (grant or revoke) during the connection lifetime. Call periodically
  * or after receiving a revocation signal.
  *
- * Returns a new `RequestContext` with updated permits — the original
+ * Returns a new `RequestContext` with updated role_grants — the original
  * context is not mutated, making concurrent calls safe. Throws when
- * `ctx.actor` is null; account-grain contexts have no permits to refresh.
+ * `ctx.actor` is null; account-grain contexts have no role_grants to refresh.
  *
  * @param ctx - the request context to refresh
  * @param deps - query dependencies
- * @returns a new `RequestContext` with fresh permits
+ * @returns a new `RequestContext` with fresh role_grants
  * @throws Error when called on an account-grain context (`actor: null`)
  */
-export const refresh_permits = async (ctx, deps) => {
+export const refresh_role_grants = async (ctx, deps) => {
     if (!ctx.actor) {
-        throw new Error('refresh_permits: account-grain context has no actor / permits to refresh');
+        throw new Error('refresh_role_grants: account-grain context has no actor / role_grants to refresh');
     }
-    const permits = await query_permit_find_active_for_actor(deps, ctx.actor.id);
-    return { ...ctx, permits };
+    const role_grants = await query_role_grant_find_active_for_actor(deps, ctx.actor.id);
+    return { ...ctx, role_grants };
 };
 /**
  * Build a full `RequestContext` from an account id and an explicit
  * actor id (already resolved via `resolve_acting_actor`).
  *
- * Loads `account` + the named `actor` + the actor's active permits.
+ * Loads `account` + the named `actor` + the actor's active role_grants.
  * Verifies the `actor.account_id === account.id` binding so downstream
  * handlers can trust `ctx.actor.account_id === ctx.account.id`. Returns
  * `null` when the account is missing, the actor is missing, or the
@@ -352,17 +364,17 @@ export const build_request_context = async (deps, account_id, actor_id) => {
         return null;
     if (actor.account_id !== account.id)
         return null;
-    const permits = await query_permit_find_active_for_actor(deps, actor.id);
-    return { account, actor, permits };
+    const role_grants = await query_role_grant_find_active_for_actor(deps, actor.id);
+    return { account, actor, role_grants };
 };
 /**
- * Build an account-only `RequestContext` (no actor, no permits) from
+ * Build an account-only `RequestContext` (no actor, no role_grants) from
  * an account id.
  *
  * Used by the dispatcher's authorization phase for authenticated routes
  * that don't need an acting actor — account-grain operations (logout,
  * password change, account self-service). Lets handlers read
- * `auth.account.id` / `auth.account.username` uniformly with permit-bound
+ * `auth.account.id` / `auth.account.username` uniformly with role_grant-bound
  * routes; the cost is one extra `query_account_by_id` per request.
  *
  * Returns `null` when the account row is missing (e.g. deleted between
@@ -377,201 +389,145 @@ export const build_account_context = async (deps, account_id) => {
     const account = await query_account_by_id(deps, account_id);
     if (!account)
         return null;
-    return { account, actor: null, permits: [] };
-};
-/**
- * Whether the supplied auth descriptor implies an acting actor must be
- * resolved (i.e., permit-requiring auth: `'role'` or `'keeper'`).
- *
- * The dispatcher's authorization phase uses this to decide whether to
- * walk the actor list when the input schema doesn't already declare
- * `acting?: ActingActor`. Accepts either auth shape — the route-spec
- * `RouteAuth` (`{type: 'role' | 'keeper' | ...}`) or the action-spec
- * `ActionAuth` (`'keeper' | {role}`) — so HTTP and RPC dispatchers share
- * one source of truth for the "permit-bound" rule.
- */
-export const is_actor_implying_auth = (auth) => {
-    if (typeof auth === 'string')
-        return auth === 'keeper';
-    if ('type' in auth)
-        return auth.type === 'role' || auth.type === 'keeper';
-    return 'role' in auth;
-};
-/**
- * Whether an input schema declares the canonical `acting?: ActingActor`
- * field. Reference-equality on the exported `ActingActor` schema —
- * consumer schemas with unrelated `acting` fields don't trip this check.
- *
- * Peels through Zod wrappers (`optional`, `nullable`, `default`,
- * `transform`, `pipe`, `prefault`) via `zod_unwrap_to_object` so a spec
- * authored as `z.optional(z.strictObject({acting: ActingActor}))` or
- * `z.strictObject({acting: ActingActor}).default({})` still trips the
- * predicate. The wrapper-tolerant lookup is defense-in-depth — the
- * canonical shape is the un-wrapped `z.strictObject({acting: ActingActor})`,
- * but variant B in `~/dev/grimoire/lore/fuz_app/TODO_PUBLIC_AUTH_PHASE.md`
- * makes this predicate authorization-correctness load-bearing for
- * `auth: 'public'` actions, so missing a wrapper-bound declaration
- * would silently skip actor resolution. The reference-equality check
- * on `ActingActor` keeps consumer schemas with unrelated `acting`
- * fields from tripping the predicate even after the wrapper peel.
- *
- * The dispatcher's authorization phase uses this to decide whether to
- * pull the actor id from validated input (so multi-actor users can pick
- * a persona on actor-needing routes).
- */
-export const input_schema_declares_acting = (schema) => {
-    const obj = zod_unwrap_to_object(schema);
-    if (!obj)
-        return false;
-    return obj.shape.acting === ActingActor;
+    return { account, actor: null, role_grants: [] };
 };
 /**
- * Apply the dispatcher's authorization phase. Shared by the route-spec
- * wrapper and the RPC dispatcher.
- *
- * - When `c.var.auth_account_id` is `null`, returns `void` so the
- *   downstream auth guard can fire 401 (less-helpful than `actor_required`
- *   for the unauthenticated case).
- * - When `needs_actor` is true, resolves the actor against the account
- *   plus the supplied `acting` value, then builds the full
- *   `{account, actor, permits}` context.
- * - When `needs_actor` is false, builds an account-only context so
- *   handler signatures stay uniform across the surface.
- *
- * On resolution failure returns an `AuthorizationFailure` (`{status, body}`)
- * the caller wraps in a transport-appropriate response. Three 500 branches
- * are kept distinct so the wire shape names what actually went wrong:
- *
- * - 500 `ERROR_NO_ACTORS_ON_ACCOUNT` — `resolve_acting_actor` returned
- *   `no_actors`. The actor enumeration succeeded and came back empty;
- *   signup / bootstrap should have created one in the same transaction,
- *   so this is a real corruption signal.
- * - 500 `ERROR_ACCOUNT_VANISHED` — `build_request_context` /
- *   `build_account_context` returned null after a successful
- *   `resolve_acting_actor`. The account or actor row was deleted between
- *   the credential check and authorization (torn read race), or — in
- *   the `build_request_context` actor↔account mismatch sub-branch — the
- *   binding flipped under us. Reachability of the mismatch sub-branch in
- *   production is essentially zero (`resolve_acting_actor` already
- *   verified the actor was on this account, and `actor.account_id` only
- *   changes via row-level edits no production path makes), so collapsing
- *   that case into the torn-read shape costs nothing.
- *
- * Other failure paths: 400 `ERROR_ACTOR_REQUIRED` / `ERROR_ACTOR_NOT_ON_ACCOUNT`.
- * Returns `undefined` on success.
- *
- * @mutates Hono context - sets `REQUEST_CONTEXT_KEY` on success
+ * Apply the dispatcher's authorization phase against the flat-record
+ * `RouteAuth` shape. Shared by the route-spec wrapper, the HTTP RPC
+ * dispatcher, and the per-message WS dispatcher. Phase order:
+ * pre-validation 401 → input validation 400 → authorization phase →
+ * post-authorization 403.
+ *
+ * Pure data — the function does not touch a Hono context. Each transport
+ * passes `account_id` (extracted from its own credential surface) and
+ * binds the returned `AuthorizationResult` to its wire shape. The REST
+ * pipeline additionally writes `REQUEST_CONTEXT_KEY` on `c` for downstream
+ * `require_role` / `require_credential_types` middleware that still reads
+ * the resolved context off the Hono context.
+ *
+ * Branching by `auth.account` × `auth.actor`:
+ *
+ * - Both `'none'` → `{ok: true, request_context: null}`. Public actions
+ *   never see a `RequestContext`.
+ * - `account_id == null` on any non-public route → same null
+ *   `request_context`. The `'required'` callers were already rejected at
+ *   the pre-validation gate in the dispatcher; only genuine anonymous
+ *   access on an `'optional'` axis lands here.
+ * - `actor === 'none'` → builds account-only context via
+ *   `build_account_context`. Null lookup → `account_vanished` 500 failure.
+ * - `actor === 'required'` → resolves the actor from `acting_value` (or
+ *   single-actor account); failures map to 400 / 500.
+ * - `actor === 'optional'` → same as `'required'` except multi-actor
+ *   accounts without an `acting` value fall back to account-only context
+ *   (no `actor_required` 400). Bad `acting` ids still 400.
+ *
+ * 500 branches stay distinct: `ERROR_NO_ACTORS_ON_ACCOUNT` (signup
+ * invariant violation), `ERROR_ACCOUNT_VANISHED` (torn read after
+ * resolve).
  */
-export const apply_authorization_phase = async (deps, c, needs_actor, acting_value) => {
-    // Test escape hatch: when a harness pre-populates `REQUEST_CONTEXT_KEY`
-    // it must also flag `TEST_CONTEXT_PRESET_KEY = true` (set by
-    // `create_test_app_from_specs` / `create_fake_hono_context` / per-test
-    // middleware). Production middleware never sets this flag, so future
-    // production code that consults `REQUEST_CONTEXT_KEY` cannot silently
-    // bypass the live build the way an implicit presence probe would.
-    if (c.get(TEST_CONTEXT_PRESET_KEY))
-        return;
-    const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
-    if (account_id == null)
-        return; // auth guard handles 401
-    if (needs_actor) {
-        const acting = await resolve_acting_actor(deps, account_id, acting_value);
-        if (!acting.ok) {
-            if (acting.reason === 'actor_required') {
-                return {
-                    status: 400,
-                    body: { error: ERROR_ACTOR_REQUIRED, available: acting.available },
-                };
-            }
-            if (acting.reason === 'actor_not_on_account') {
-                return { status: 400, body: { error: ERROR_ACTOR_NOT_ON_ACCOUNT } };
+export const apply_authorization_phase = async (deps, account_id, auth, acting_value) => {
+    if (is_public_auth(auth))
+        return { ok: true, request_context: null };
+    if (account_id == null) {
+        // Optional-auth route hit without a credential — leave `RequestContext`
+        // null so the handler can branch on it. `'required'` callers already
+        // got rejected at the pre-validation gate.
+        return { ok: true, request_context: null };
+    }
+    if (!needs_actor(auth)) {
+        const ctx = await build_account_context(deps, account_id);
+        if (!ctx)
+            return { ok: false, status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
+        return { ok: true, request_context: ctx };
+    }
+    // actor 'required' or 'optional' — resolve.
+    const acting = await resolve_acting_actor(deps, account_id, acting_value);
+    if (!acting.ok) {
+        if (acting.reason === 'actor_required') {
+            if (auth.actor === 'optional') {
+                // Multi-actor account, no pick — fall back to account-only context.
+                const ctx = await build_account_context(deps, account_id);
+                if (!ctx)
+                    return { ok: false, status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
+                return { ok: true, request_context: ctx };
             }
-            return { status: 500, body: { error: ERROR_NO_ACTORS_ON_ACCOUNT } };
+            return {
+                ok: false,
+                status: 400,
+                body: { error: ERROR_ACTOR_REQUIRED, available: acting.available },
+            };
         }
-        const ctx = await build_request_context(deps, account_id, acting.actor_id);
-        if (!ctx)
-            return { status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
-        c.set(REQUEST_CONTEXT_KEY, ctx);
-        return;
+        if (acting.reason === 'actor_not_on_account') {
+            return { ok: false, status: 400, body: { error: ERROR_ACTOR_NOT_ON_ACCOUNT } };
+        }
+        return { ok: false, status: 500, body: { error: ERROR_NO_ACTORS_ON_ACCOUNT } };
     }
-    const ctx = await build_account_context(deps, account_id);
+    const ctx = await build_request_context(deps, account_id, acting.actor_id);
     if (!ctx)
-        return { status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
-    c.set(REQUEST_CONTEXT_KEY, ctx);
+        return { ok: false, status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
+    return { ok: true, request_context: ctx };
 };
 /**
  * Create the route-spec authorization handler used by `apply_route_specs`.
  *
- * Decides whether the route needs actor resolution from `spec.auth` plus
- * `spec.input` introspection, extracts the raw `acting` value (string
- * typeguard, no schema validation), and delegates to
- * `apply_authorization_phase`. Public routes (`auth.type === 'none'`) skip
- * the phase entirely; their handlers see no `RequestContext`.
- *
- * Authorization runs before input validation (matches the RPC dispatcher's
- * order). For GET routes `acting` comes from the URL query string; for
- * mutating methods it comes from a pre-parse of the JSON body. The pre-
- * parse result lands on `c.var.cached_request_body` so the subsequent
- * `create_input_validation` step reads the parsed value from there
- * without re-running `JSON.parse` — explicit cache, independent of
- * Hono's internal `bodyCache` behavior. A malformed body fails the
- * pre-parse silently (`acting` treated as undefined, cache flagged
- * `{ok: false}`) and is then rejected with `ERROR_INVALID_JSON_BODY`
- * by the input-validation step that reads the failure flag — producing
- * the same final response as if the validation step had parsed first.
+ * Reads `acting` off `c.var.validated_input` (or `c.var.validated_query`
+ * for GET routes) — input validation runs first, so the authorization
+ * phase consumes the typed Zod field instead of pre-parsing the body.
+ * Public routes (`auth.account === 'none' && auth.actor === 'none'`)
+ * skip the phase entirely.
+ *
+ * Per registry-time invariant 2, `auth.actor !== 'none'` ⟺ the input
+ * (or query) schema declares `acting?: ActingActor` — so reading from
+ * `c.var.validated_input.acting` / `c.var.validated_query.acting` is
+ * type-safe.
+ *
+ * Resolved contexts land on `REQUEST_CONTEXT_KEY` so the post-authorization
+ * REST middleware (`require_role`, `require_credential_types`) reads the
+ * actor-bound context off `c.var`. The HTTP RPC and WS dispatchers consume
+ * the `apply_authorization_phase` outcome directly without round-tripping
+ * through `c.var`.
  */
 export const create_fuz_authorization_handler = (deps) => {
     return async (c, spec) => {
-        if (spec.auth.type === 'none')
+        // Test escape hatch: harnesses that pre-populate `REQUEST_CONTEXT_KEY`
+        // flag `TEST_CONTEXT_PRESET_KEY = true` so the authorization phase
+        // trusts the supplied context instead of running DB-backed resolution.
+        // Production middleware never sets this flag.
+        if (c.get(TEST_CONTEXT_PRESET_KEY))
             return;
-        const declares_acting = input_schema_declares_acting(spec.input);
-        const needs_actor = is_actor_implying_auth(spec.auth) || declares_acting;
-        let acting_value;
-        if (declares_acting) {
-            const raw_acting = await read_raw_acting(c, spec.method);
-            acting_value = typeof raw_acting === 'string' ? raw_acting : undefined;
-        }
-        const failure = await apply_authorization_phase(deps, c, needs_actor, acting_value);
-        if (!failure)
+        if (is_public_auth(spec.auth))
             return;
-        return c.json(failure.body, failure.status);
+        const acting_value = needs_actor(spec.auth) ? extract_validated_acting(c) : undefined;
+        const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
+        const result = await apply_authorization_phase(deps, account_id, spec.auth, acting_value);
+        if (!result.ok)
+            return c.json(result.body, result.status);
+        if (result.request_context !== null) {
+            c.set(REQUEST_CONTEXT_KEY, result.request_context);
+        }
+        // `request_context: null` — public action or unauthenticated optional axis.
+        // Leave `REQUEST_CONTEXT_KEY` null; downstream `require_role` /
+        // `require_credential_types` enforce.
+        return;
     };
 };
 /**
- * Extract the raw `acting` value from a request before input validation
- * has run. Returns `undefined` on parse failure or non-object body; the
- * downstream input-validation step then rejects malformed bodies with
- * `ERROR_INVALID_JSON_BODY`.
- *
- * Writes the parse result to `c.var.cached_request_body` so the
- * input-validation step does not re-run `JSON.parse` on the same Hono-
- * cached body text. Hono's internal `bodyCache` keeps the body text
- * alive across multiple `c.req.json()` calls, but each call still
- * re-parses — caching the parsed value here decouples our pipeline
- * from that undocumented detail (and saves the second parse).
- *
- * Three cache states:
- *
- * - GET (early return) — no cache write; the input-validation step is
- *   a no-op for GET so nothing reads the cache anyway.
- * - Successful parse (any JSON value) — `{ok: true, body}`. The
- *   input-validation step reads `body` and runs the non-object check
- *   itself.
- * - Parse failure — `{ok: false}`. The input-validation step short-
- *   circuits with `ERROR_INVALID_JSON_BODY` without re-parsing.
+ * Read `acting` off the validated input (or validated query) on the Hono
+ * context. Input/query validation runs before the authorization phase,
+ * so this reads a typed Zod field — not the raw body.
+ *
+ * Returns `undefined` when `validated_input` / `validated_query` isn't
+ * set or doesn't carry `acting`. Per registry-time invariant 2, the
+ * dispatcher only calls this when `auth.actor !== 'none'`, which by
+ * the biconditional means the input schema declares
+ * `acting?: ActingActor`.
  */
-const read_raw_acting = async (c, method) => {
-    if (method === 'GET')
-        return c.req.query('acting');
-    try {
-        const body = await c.req.json();
-        c.set(CACHED_REQUEST_BODY_KEY, { ok: true, body });
-        if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
-            return body.acting;
-        }
-    }
-    catch {
-        c.set(CACHED_REQUEST_BODY_KEY, { ok: false });
-    }
+const extract_validated_acting = (c) => {
+    const validated_input = c.get('validated_input');
+    if (validated_input && typeof validated_input.acting === 'string')
+        return validated_input.acting;
+    const validated_query = c.get('validated_query');
+    if (validated_query && typeof validated_query.acting === 'string')
+        return validated_query.acting;
     return undefined;
 };