@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/auth/permit_queries.js

@@ -49,24 +49,34 @@ export const query_grant_permit = async (deps, input) => {
     return assert_row(existing, 'idempotent permit grant');
 };
 /**
- * Look up the role of an active permit, constrained to a specific actor.
+ * Look up the role of an active permit (constrained to a specific
+ * actor) plus the actor's `account_id`.
  *
  * Used by admin routes to inspect the permit's role before acting
  * (e.g., enforcing `web_grantable` on revoke). The actor constraint
  * mirrors `query_revoke_permit` so IDOR protection is consistent:
  * a caller can only see permits belonging to the target actor.
  *
+ * The JOIN to `actor` collapses what used to be a second
+ * `query_actor_by_id` round-trip in the revoke handler into one read,
+ * which closes the small TOCTOU window where the actor row could be
+ * deleted between the IDOR check and the actor lookup. The `account_id`
+ * is needed by the audit envelope's `target_account_id` field and the
+ * SSE/WS socket-close fan-out targeting.
+ *
  * Returns `null` if the permit is not found, already revoked, or
  * belongs to a different actor.
  *
  * @param deps - query dependencies
  * @param permit_id - the permit id to look up
  * @param actor_id - the actor that must own the permit
- * @returns `{role}` on a match, or `null`
+ * @returns `{role, account_id}` on a match, or `null`
  */
 export const query_permit_find_active_role_for_actor = async (deps, permit_id, actor_id) => {
-    const row = await deps.db.query_one(`SELECT role FROM permit
-		 WHERE id = $1 AND actor_id = $2 AND revoked_at IS NULL`, [permit_id, actor_id]);
+    const row = await deps.db.query_one(`SELECT permit.role, actor.account_id
+		   FROM permit
+		   JOIN actor ON actor.id = permit.actor_id
+		  WHERE permit.id = $1 AND permit.actor_id = $2 AND permit.revoked_at IS NULL`, [permit_id, actor_id]);
     return row ?? null;
 };
 /**
@@ -206,16 +216,17 @@ export const query_permit_find_account_id_for_role = async (deps, role) => {
  * @mutates `permit_offer` table - stamps `superseded_at` on every pending row at `scope_id`
  */
 export const query_permit_revoke_for_scope = async (deps, scope_id, revoked_by, reason) => {
-    // Revoke every active permit at the scope. CTE pulls `account_id` via a
-    // join on `actor` so callers fan out `permit_revoke` notifications without
-    // an extra round-trip.
+    // Revoke every active permit at the scope. CTE returns `actor_id` directly
+    // from the permit row (drives `target_actor_id` audit envelopes); a join
+    // against `actor` resolves `account_id` for `target_account_id`
+    // + WS/SSE socket-close fan-out, all in one round-trip.
     const revoked = await deps.db.query(`WITH updated AS (
 			UPDATE permit
 			SET revoked_at = NOW(), revoked_by = $2, revoked_reason = $3
 			WHERE scope_id = $1 AND revoked_at IS NULL
 			RETURNING id, role, scope_id, actor_id
 		)
-		SELECT u.id AS permit_id, u.role, u.scope_id, a.account_id
+		SELECT u.id AS permit_id, u.role, u.scope_id, u.actor_id, a.account_id
 		FROM updated u
 		JOIN actor a ON a.id = u.actor_id`, [scope_id, revoked_by ?? null, reason ?? null]);
     // Supersede every pending offer at the scope — tuple-matched or orphan,

package/dist/auth/request_context.d.ts

@@ -1,24 +1,64 @@
 /**
  * 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 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 { QueryDeps } from '../db/query_deps.js';
-/** The resolved identity context for an authenticated request. */
+import type { ActionAuth } from '../actions/action_spec.js';
+import type { RouteAuth, RouteSpec } from '../http/route_spec.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
+ * (`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.
+ *
+ * Multi-actor invariant: when populated, `actor.account_id === account.id`.
+ * `build_request_context` enforces this; the dispatcher's authorization
+ * phase rejects with `actor_not_on_account` before reaching the handler.
+ */
 export interface RequestContext {
     account: Account;
-    actor: Actor;
+    actor: Actor | null;
     permits: Array<Permit>;
 }
 /** Hono context variable name for the request context. */
@@ -43,53 +83,184 @@ export declare const get_request_context: (c: Context) => RequestContext | null;
 /**
  * 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 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.
+ */
+export interface RequestActorContext extends RequestContext {
+    actor: Actor;
+}
+/**
+ * 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 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).
+ * 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 declare const has_role: (ctx: RequestContext, role: string, now?: Date) => boolean;
+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`.
+ *
+ * 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 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`
+ * 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 declare const has_any_scoped_role: (ctx: RequestContext | null, roles: ReadonlyArray<string>, scope_id: string | null, now?: Date) => boolean;
+/**
+ * Result of `resolve_acting_actor` — either an actor id or a structured
+ * error the caller maps to an HTTP response.
+ */
+export type ResolveActingActorResult = {
+    ok: true;
+    actor_id: string;
+} | {
+    ok: false;
+    reason: 'no_actors';
+} | {
+    ok: false;
+    reason: 'actor_required';
+    available: Array<{
+        id: string;
+        name: string;
+    }>;
+} | {
+    ok: false;
+    reason: 'actor_not_on_account';
+};
+/**
+ * Resolve the acting actor for an authenticated request.
+ *
+ * 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:
+ *
+ * - `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 declare const resolve_acting_actor: (deps: QueryDeps, account_id: string, acting_actor_id: string | undefined) => Promise<ResolveActingActorResult>;
 /**
- * Create middleware that builds the request context from a session cookie.
+ * Create middleware that authenticates the account from a session cookie.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 declare const create_request_context_middleware: (deps: QueryDeps, log: Logger, session_context_key?: string) => MiddlewareHandler;
 /**
  * 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 declare const require_auth: MiddlewareHandler;
 /**
  * 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
  */
@@ -102,24 +273,181 @@ export declare const require_role: (role: string) => MiddlewareHandler;
  * 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 declare const refresh_permits: (ctx: RequestContext, deps: QueryDeps) => Promise<RequestContext>;
 /**
- * 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.
+ *
+ * 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
+ * @param actor_id - the actor this request acts as
+ * @returns a request context, or `null` if account/actor not found or mismatched
+ */
+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
+ * 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.
  *
- * 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.
+ * 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 a request context, or `null` if account/actor not found
+ * @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
+ * directly via `c.json(body, status)`; the RPC dispatcher folds it into a
+ * JSON-RPC error envelope `{jsonrpc, id, error: {code, message, data}}`.
+ *
+ * The auth phase deliberately stops short of constructing a `Response` so
+ * the same failure flows through every transport without the auth-domain
+ * code knowing about JSON-RPC. See `fuz_app/CLAUDE.md` § Cleanest
+ * architecture takes priority for the rationale.
+ */
+export type AuthorizationFailureBody = {
+    error: typeof ERROR_ACTOR_REQUIRED;
+    available: Array<{
+        id: string;
+        name: string;
+    }>;
+} | {
+    error: typeof ERROR_ACTOR_NOT_ON_ACCOUNT;
+} | {
+    error: typeof ERROR_NO_ACTORS_ON_ACCOUNT;
+} | {
+    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`.
+ */
+export interface AuthorizationFailure {
+    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
+ */
+export declare const apply_authorization_phase: (deps: QueryDeps, c: Context, needs_actor: boolean, acting_value: string | undefined) => Promise<AuthorizationFailure | void>;
+/**
+ * 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 declare const build_request_context: (deps: QueryDeps, account_id: string) => Promise<RequestContext | null>;
+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":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,OAAO,EAAE,KAAK,KAAK,EAAoB,KAAK,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAQ5F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAOnD,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,cAAc,GAAG,IAEjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAAI,GAAG,OAAO,KAAG,cAMpD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,cAAc,EAAE,MAAM,MAAM,EAAE,MAAK,IAAiB,KAAG,OAChB,CAAC;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,KAAK,MAAM,EACX,4BAAuC,KACrC,iBA6CF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,iBAM1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,iBAW3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC3B,KAAK,cAAc,EACnB,MAAM,SAAS,KACb,OAAO,CAAC,cAAc,CAGxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAS/B,CAAC"}
+{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"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"}