@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/auth/request_context.js

@@ -1,22 +1,47 @@
 /**
  * Request context middleware and permit checking helpers.
  *
- * Builds `{ account, actor, permits }` from a session cookie
- * for every authenticated request. Downstream handlers check
- * permits, never flags.
+ * Two-phase identity resolution:
  *
- * `build_request_context` is the shared helper used by session,
- * bearer, and daemon token middleware to resolve account → actor → permits.
- * `refresh_permits` reloads permits on an existing context.
+ * 1. **Authentication (middleware)** — `create_request_context_middleware`,
+ *    `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
+ *    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
+ *    (`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}`
+ *    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
+ * is resolved and their handlers see a `RequestContext` with
+ * `actor: null` + empty `permits`. 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.
  *
  * @module
  */
-import { is_permit_active } from './account_schema.js';
+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 { hash_session_token, session_touch_fire_and_forget, query_session_get_valid, } from './session_queries.js';
-import { query_actor_by_account, query_account_by_id } from './account_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 { AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
-import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, } from '../http/error_schemas.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';
 /** Hono context variable name for the request context. */
 export const REQUEST_CONTEXT_KEY = 'request_context';
 /**
@@ -41,18 +66,51 @@ export const get_request_context = (c) => {
 /**
  * Get the request context, throwing if unauthenticated.
  *
- * Use in route handlers where auth middleware guarantees a context exists
- * (i.e., routes with `auth: {type: 'authenticated'}` or stricter).
- * Prefer this over `get_request_context(c)!` for explicit error handling.
+ * Use in route handlers where the dispatcher's authorization phase guarantees
+ * a context exists (i.e., routes with `auth: {type: 'authenticated'}` or
+ * stricter). Prefer this over `get_request_context(c)!` for explicit error
+ * handling.
  *
  * @param c - the Hono context
  * @returns the request context (never null)
- * @throws Error if no request context is set (middleware misconfiguration)
+ * @throws Error if no request context is set (dispatcher misconfiguration)
  */
 export const require_request_context = (c) => {
     const ctx = get_request_context(c);
     if (!ctx) {
-        throw new Error('require_request_context: no request context — is auth middleware applied?');
+        throw new Error('require_request_context: no request context — is the dispatcher authorization phase wired?');
+    }
+    return ctx;
+};
+/**
+ * Narrow `RequestContext | null` to a non-null context (auth invariant).
+ *
+ * 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;
 };
@@ -60,63 +118,151 @@ export const require_request_context = (c) => {
  * Check if a request context has an active permit for a given role.
  *
  * Checks the permits 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.
+ * `has_role(auth, ADMIN) || has_scoped_role(auth, role, scope)`).
  *
- * @param ctx - the request context
+ * @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
  */
-export const has_role = (ctx, role, now = new Date()) => ctx.permits.some((p) => p.role === role && is_permit_active(p, now));
+export const has_role = (ctx, role, now = new Date()) => ctx?.permits.some((p) => p.role === role && is_permit_active(p, now)) ?? false;
+/**
+ * Whether the request context holds an active permit for `role` at `scope_id`.
+ *
+ * Walks the in-memory `ctx.permits` 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
+ * 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
+ * a transactional re-check inside the UPDATE/INSERT, which neither style
+ * 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.
+ *
+ * `scope_id` semantics: in-memory `permit.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.
+ *
+ * @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
+ */
+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));
+};
+/**
+ * Whether the request context holds an active permit 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`.
+ *
+ * @param ctx - the request context, or `null` for unauthenticated callers
+ * @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
+ */
+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));
+};
 /**
- * Create middleware that builds the request context from a session cookie.
+ * Resolve the acting actor for an authenticated request.
  *
- * Reads the session identity (set by session middleware), looks up
- * the `auth_session`, loads account + actor + active permits, and
- * sets the `RequestContext` on the Hono context.
+ * Called from the route-spec / RPC dispatcher's authorization phase
+ * with the authenticated account id and the validated `acting` value
+ * (from the request payload). Applies the uniform resolution rules:
  *
- * If the session is invalid or the account is not found, the context
- * is set to `null` (unauthenticated). No 401 is returned — use
- * `require_role` or `require_auth` for enforcement.
+ * - `acting_actor_id` omitted + 1 actor → use it.
+ * - `acting_actor_id` omitted + 0 actors → `no_actors` (defensive —
+ *   signup / bootstrap always create an actor in the same tx, so this
+ *   is a server error).
+ * - `acting_actor_id` omitted + multiple actors → `actor_required` with
+ *   the available list so the client can prompt; never pick silently.
+ * - `acting_actor_id` present + matches an actor on the account → use it.
+ * - `acting_actor_id` present + does not match → `actor_not_on_account`.
+ *   The available list is intentionally not echoed in this branch (treat
+ *   as opaque rejection).
+ *
+ * @param deps - query dependencies
+ * @param account_id - the authenticated account
+ * @param acting_actor_id - the requested acting actor id, or `undefined`
+ */
+export const resolve_acting_actor = async (deps, account_id, acting_actor_id) => {
+    const actors = await query_actors_by_account(deps, account_id);
+    if (actors.length === 0)
+        return { ok: false, reason: 'no_actors' };
+    if (acting_actor_id == null) {
+        if (actors.length === 1)
+            return { ok: true, actor_id: actors[0].id };
+        return {
+            ok: false,
+            reason: 'actor_required',
+            available: actors.map((a) => ({ id: a.id, name: a.name })),
+        };
+    }
+    const match = actors.find((a) => a.id === acting_actor_id);
+    if (!match)
+        return { ok: false, reason: 'actor_not_on_account' };
+    return { ok: true, actor_id: match.id };
+};
+/**
+ * Create middleware that authenticates the account from a session cookie.
+ *
+ * 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;
+ * `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.
+ *
+ * Invalid / missing session leaves all keys null and calls `next()` —
+ * `require_auth` / `require_role` enforce.
  *
  * @param deps - query dependencies (pool-level db for middleware)
  * @param log - the logger instance
  * @param session_context_key - the Hono context key where session middleware stored the session token
- * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, `AUTH_SESSION_TOKEN_HASH_KEY`, and `AUTH_API_TOKEN_ID_KEY`
+ * @mutates Hono context - sets `ACCOUNT_ID_KEY`, `CREDENTIAL_TYPE_KEY`, `AUTH_SESSION_TOKEN_HASH_KEY`, and `AUTH_API_TOKEN_ID_KEY`
  */
 export const create_request_context_middleware = (deps, log, session_context_key = 'auth_session_id') => {
     return async (c, next) => {
+        c.set(REQUEST_CONTEXT_KEY, null);
+        c.set(ACCOUNT_ID_KEY, null);
+        c.set(CREDENTIAL_TYPE_KEY, null);
+        c.set(AUTH_SESSION_TOKEN_HASH_KEY, null);
+        c.set(AUTH_API_TOKEN_ID_KEY, null);
         const session_token = c.get(session_context_key) ?? null;
         if (!session_token) {
-            c.set(REQUEST_CONTEXT_KEY, null);
-            c.set(CREDENTIAL_TYPE_KEY, null);
-            c.set(AUTH_SESSION_TOKEN_HASH_KEY, null);
-            c.set(AUTH_API_TOKEN_ID_KEY, null);
             await next();
             return;
         }
         const token_hash = hash_session_token(session_token);
         const session = await query_session_get_valid(deps, token_hash);
         if (!session) {
-            c.set(REQUEST_CONTEXT_KEY, null);
-            c.set(CREDENTIAL_TYPE_KEY, null);
-            c.set(AUTH_SESSION_TOKEN_HASH_KEY, null);
-            c.set(AUTH_API_TOKEN_ID_KEY, null);
             await next();
             return;
         }
-        const ctx = await build_request_context(deps, session.account_id);
-        if (!ctx) {
-            c.set(REQUEST_CONTEXT_KEY, null);
-            c.set(CREDENTIAL_TYPE_KEY, null);
-            c.set(AUTH_SESSION_TOKEN_HASH_KEY, null);
-            c.set(AUTH_API_TOKEN_ID_KEY, null);
-            await next();
-            return;
-        }
-        c.set(REQUEST_CONTEXT_KEY, ctx);
+        c.set(ACCOUNT_ID_KEY, session.account_id);
         c.set(CREDENTIAL_TYPE_KEY, 'session');
         c.set(AUTH_SESSION_TOKEN_HASH_KEY, token_hash);
-        c.set(AUTH_API_TOKEN_ID_KEY, null);
         // Touch session (fire-and-forget, don't block the request)
         void session_touch_fire_and_forget(deps, token_hash, c.var.pending_effects, log);
         await next();
@@ -125,11 +271,10 @@ export const create_request_context_middleware = (deps, log, session_context_key
 /**
  * Middleware that requires authentication.
  *
- * Returns 401 if no request context is set.
+ * Returns 401 if the auth middleware did not set `c.var.auth_account_id`.
  */
 export const require_auth = async (c, next) => {
-    const ctx = get_request_context(c);
-    if (!ctx) {
+    if (c.get(ACCOUNT_ID_KEY) == null) {
         return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
     }
     await next();
@@ -137,17 +282,20 @@ export const require_auth = async (c, next) => {
 /**
  * Create middleware that requires a specific role.
  *
- * Returns 401 if unauthenticated, 403 if the role is missing.
+ * 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
  */
 export const require_role = (role) => {
     return async (c, next) => {
-        const ctx = get_request_context(c);
-        if (!ctx) {
+        if (c.get(ACCOUNT_ID_KEY) == null) {
             return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
         }
-        if (!has_role(ctx, role)) {
+        const ctx = get_request_context(c);
+        if (!ctx || !has_role(ctx, role)) {
             return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_role: role }, 403);
         }
         await next();
@@ -161,35 +309,269 @@ export const require_role = (role) => {
  * or after receiving a revocation signal.
  *
  * Returns a new `RequestContext` with updated permits — the original
- * context is not mutated, making concurrent calls safe.
+ * context is not mutated, making concurrent calls safe. Throws when
+ * `ctx.actor` is null; account-grain contexts have no permits to refresh.
  *
  * @param ctx - the request context to refresh
  * @param deps - query dependencies
  * @returns a new `RequestContext` with fresh permits
+ * @throws Error when called on an account-grain context (`actor: null`)
  */
 export const refresh_permits = async (ctx, deps) => {
+    if (!ctx.actor) {
+        throw new Error('refresh_permits: account-grain context has no actor / permits to refresh');
+    }
     const permits = await query_permit_find_active_for_actor(deps, ctx.actor.id);
     return { ...ctx, permits };
 };
 /**
- * Build a full `RequestContext` from an account id.
+ * 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.
+ * 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
+ * actor doesn't belong to the supplied account.
  *
- * Shared helper used by session, bearer, and daemon token middleware,
- * as well as WebSocket upgrade handlers. Does the account → actor → permits
- * lookup pipeline and returns the composed context, or `null` if
- * the account or actor is not found.
+ * Called by the route-spec / RPC dispatcher's authorization phase for
+ * routes that need an acting actor; account-grain routes use
+ * `build_account_context` instead.
  *
  * @param deps - query dependencies
  * @param account_id - the account to build context for
- * @returns a request context, or `null` if account/actor not found
+ * @param actor_id - the actor this request acts as
+ * @returns a request context, or `null` if account/actor not found or mismatched
  */
-export const build_request_context = async (deps, account_id) => {
+export const build_request_context = async (deps, account_id, actor_id) => {
     const account = await query_account_by_id(deps, account_id);
     if (!account)
         return null;
-    const actor = await query_actor_by_account(deps, account.id);
+    const actor = await query_actor_by_id(deps, actor_id);
     if (!actor)
         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 };
 };
+/**
+ * Build an account-only `RequestContext` (no actor, no permits) 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
+ * routes; the cost is one extra `query_account_by_id` per request.
+ *
+ * Returns `null` when the account row is missing (e.g. deleted between
+ * the auth middleware's session lookup and the dispatcher) — caller
+ * surfaces that as a 500 since it represents a torn read.
+ *
+ * @param deps - query dependencies
+ * @param account_id - the account to build context for
+ * @returns an account-only request context, or `null` if the account is missing
+ */
+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;
+};
+/**
+ * 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
+ */
+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 } };
+            }
+            return { status: 500, body: { error: ERROR_NO_ACTORS_ON_ACCOUNT } };
+        }
+        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;
+    }
+    const ctx = await build_account_context(deps, account_id);
+    if (!ctx)
+        return { status: 500, body: { error: ERROR_ACCOUNT_VANISHED } };
+    c.set(REQUEST_CONTEXT_KEY, 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.
+ */
+export const create_fuz_authorization_handler = (deps) => {
+    return async (c, spec) => {
+        if (spec.auth.type === 'none')
+            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)
+            return;
+        return c.json(failure.body, failure.status);
+    };
+};
+/**
+ * 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.
+ */
+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 });
+    }
+    return undefined;
+};

package/dist/auth/route_guards.d.ts

@@ -1,7 +1,13 @@
 /**
  * Auth guard resolver for the route spec system.
  *
- * Maps `RouteAuth` discriminants to auth middleware handlers.
+ * Maps `RouteAuth` discriminants to two-phase auth middleware sets.
+ * `pre_validation` carries the 401 check (`require_auth`) so
+ * unauthenticated callers never see route-shape information from input
+ * parse failures. `post_authorization` carries the 403 role / keeper
+ * checks because they read the `RequestContext` populated by the
+ * dispatcher's authorization phase.
+ *
  * Injected into `apply_route_specs` to decouple the generic HTTP
  * framework (`http/route_spec.ts`) from auth-specific middleware.
  *
@@ -13,9 +19,9 @@ import type { AuthGuardResolver } from '../http/route_spec.js';
  *
  * Maps `RouteAuth` to middleware:
  * - `none` → no guards
- * - `authenticated` → `require_auth`
- * - `role` → `require_role(role)`
- * - `keeper` → `require_keeper`
+ * - `authenticated` → pre-validation `require_auth`
+ * - `role` → pre-validation `require_auth` + post-authorization `require_role(role)`
+ * - `keeper` → pre-validation `require_auth` + post-authorization `require_keeper`
  */
 export declare const fuz_auth_guard_resolver: AuthGuardResolver;
 //# sourceMappingURL=route_guards.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"route_guards.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/route_guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAWrC,CAAC"}
+{"version":3,"file":"route_guards.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/route_guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAWrC,CAAC"}