@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/auth/request_context.d.ts

@@ -1,5 +1,5 @@
 /**
- * Request context middleware and permit checking helpers.
+ * Request context middleware and role_grant checking helpers.
  *
  * Two-phase identity resolution:
  *
@@ -7,50 +7,49 @@
  *    `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 type { Context, MiddlewareHandler } from 'hono';
-import { z } from 'zod';
 import type { Logger } from '@fuzdev/fuz_util/log.js';
-import { type Account, type Actor, type Permit } from './account_schema.js';
+import { type Account, type Actor, type RoleGrant } from './account_schema.js';
 import type { QueryDeps } from '../db/query_deps.js';
-import type { ActionAuth } from '../actions/action_spec.js';
-import type { RouteAuth, RouteSpec } from '../http/route_spec.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import { type RouteAuth } from '../http/auth_shape.js';
 import { ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_ACCOUNT, ERROR_ACCOUNT_VANISHED } from '../http/error_schemas.js';
 /**
  * The resolved identity context for an authenticated request.
  *
  * `actor` is null on account-grain routes (no `acting` field on input,
  * no `role` / `keeper` auth) — those handlers don't trigger actor
- * resolution. `permits` is empty in that case. Permit checks
+ * resolution. `role_grants` is empty in that case. Role grant checks
  * (`has_role`, `has_scoped_role`, `has_any_scoped_role`) are
  * null-tolerant on `RequestContext | null`; they additionally treat
- * `actor: null` as "no permits" so callers don't have to narrow.
+ * `actor: null` as "no role_grants" so callers don't have to narrow.
  *
  * Multi-actor invariant: when populated, `actor.account_id === account.id`.
  * `build_request_context` enforces this; the dispatcher's authorization
@@ -59,7 +58,7 @@ import { ERROR_ACTOR_REQUIRED, ERROR_ACTOR_NOT_ON_ACCOUNT, ERROR_NO_ACTORS_ON_AC
 export interface RequestContext {
     account: Account;
     actor: Actor | null;
-    permits: Array<Permit>;
+    role_grants: Array<RoleGrant>;
 }
 /** Hono context variable name for the request context. */
 export declare const REQUEST_CONTEXT_KEY = "request_context";
@@ -96,39 +95,20 @@ export declare const require_request_context: (c: Context) => RequestContext;
 /**
  * Request context narrowed to a resolved acting actor.
  *
- * Returned by `require_request_actor` for handlers whose route resolves
- * an actor — actions with `auth: 'keeper' | {role}` or with input that
- * declares `acting?: ActingActor`. Lets handlers drop the `auth.actor!`
- * non-null assertion that was masking the dispatcher invariant.
+ * Used by handlers bound through `rpc_action` against an actor-implying
+ * spec (`auth.actor === 'required'`) — the binder's conditional return
+ * type tightens `ctx.auth` to this shape because the dispatcher's
+ * authorization phase always resolves an actor before the handler runs.
+ * The biconditional `actor !== 'none' ⟺ input declares acting?: ActingActor`
+ * is enforced at registry time.
  */
 export interface RequestActorContext extends RequestContext {
     actor: Actor;
 }
 /**
- * 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 declare const require_request_auth: (auth: RequestContext | null) => RequestContext;
-/**
- * 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 declare const require_request_actor: (auth: RequestContext | null) => RequestActorContext;
-/**
- * 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.
@@ -137,15 +117,15 @@ export declare const require_request_actor: (auth: RequestContext | null) => Req
  * @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 declare const has_role: (ctx: RequestContext | null, role: string, now?: Date) => boolean;
 /**
- * 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
@@ -153,26 +133,27 @@ export declare const has_role: (ctx: RequestContext | null, role: string, now?:
  * 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 declare const has_scoped_role: (ctx: RequestContext | null, role: string, scope_id: string | null, now?: Date) => boolean;
 /**
- * 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`.
@@ -181,7 +162,7 @@ export declare const has_scoped_role: (ctx: RequestContext | null, role: string,
  * @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 declare const has_any_scoped_role: (ctx: RequestContext | null, roles: ReadonlyArray<string>, scope_id: string | null, now?: Date) => boolean;
 /**
@@ -234,7 +215,7 @@ export declare const resolve_acting_actor: (deps: QueryDeps, account_id: string,
  * 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.
@@ -255,38 +236,68 @@ export declare const create_request_context_middleware: (deps: QueryDeps, log: L
  */
 export declare const require_auth: MiddlewareHandler;
 /**
- * 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 declare const require_role: (role: string) => MiddlewareHandler;
+export declare const require_role: (roles: ReadonlyArray<string>) => MiddlewareHandler;
 /**
- * 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 declare const require_credential_types: (credential_types: ReadonlyArray<string>) => MiddlewareHandler;
+/**
+ * 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 declare const refresh_permits: (ctx: RequestContext, deps: QueryDeps) => Promise<RequestContext>;
+export declare const refresh_role_grants: (ctx: RequestContext, deps: QueryDeps) => Promise<RequestContext>;
 /**
  * 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
@@ -303,13 +314,13 @@ export declare const refresh_permits: (ctx: RequestContext, deps: QueryDeps) =>
  */
 export declare const build_request_context: (deps: QueryDeps, account_id: string, actor_id: string) => Promise<RequestActorContext | null>;
 /**
- * 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
@@ -321,41 +332,6 @@ export declare const build_request_context: (deps: QueryDeps, account_id: string
  * @returns an account-only request context, or `null` if the account is missing
  */
 export declare const build_account_context: (deps: QueryDeps, account_id: string) => Promise<RequestContext | null>;
-/**
- * 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 declare const is_actor_implying_auth: (auth: RouteAuth | ActionAuth) => boolean;
-/**
- * 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 declare const input_schema_declares_acting: (schema: z.ZodType) => boolean;
 /**
  * Resolution-failure shape returned by `apply_authorization_phase`. Each
  * transport binds this to the appropriate wire shape — REST emits the body
@@ -381,73 +357,84 @@ export type AuthorizationFailureBody = {
     error: typeof ERROR_ACCOUNT_VANISHED;
 };
 /**
- * A `(status, body)` pair the caller binds to a transport-shaped response.
- * `status` is narrowed to the two values the auth phase emits — Hono's
- * `c.json` status overload accepts the literals directly, and downstream
- * binders avoid casts they would otherwise need against a `number`.
+ * Result of the authorization phase. Pure data — the auth domain stops
+ * short of touching the Hono context or producing a `Response` so HTTP
+ * RPC, WS, and REST each bind the same shape to their wire surface.
+ *
+ * - **`{ok: true, request_context}`** — `request_context` is non-null on
+ *   resolved (actor-bound or account-only) outcomes; `null` for public
+ *   actions (`{account: 'none', actor: 'none'}`) and for genuine anonymous
+ *   access on an `'optional'` axis. Public and unauthenticated collapse
+ *   to the same null `request_context`; every transport already treated
+ *   them identically.
+ * - **`{ok: false, status, body}`** — 400/500 failure. `status` is
+ *   narrowed to the two values the auth phase emits, so Hono's `c.json`
+ *   status overload accepts the literals directly. The 500 reasons stay
+ *   distinct in `body`: `no_actors_on_account` (signup invariant
+ *   violation); `account_vanished` (torn read after resolve).
  */
-export interface AuthorizationFailure {
+export type AuthorizationResult = {
+    ok: true;
+    request_context: RequestContext | null;
+} | {
+    ok: false;
     status: 400 | 500;
     body: AuthorizationFailureBody;
-}
+};
 /**
- * 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 declare const apply_authorization_phase: (deps: QueryDeps, c: Context, needs_actor: boolean, acting_value: string | undefined) => Promise<AuthorizationFailure | void>;
+export declare const apply_authorization_phase: (deps: QueryDeps, account_id: string | null, auth: RouteAuth, acting_value: string | undefined) => Promise<AuthorizationResult>;
 /**
  * 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 declare const create_fuz_authorization_handler: (deps: QueryDeps) => ((c: Context, spec: RouteSpec) => Promise<Response | void>);
 //# sourceMappingURL=request_context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"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"}