@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/http/proxy.d.ts

@@ -54,23 +54,70 @@ export type ParsedProxy = {
  * @throws Error on invalid IP, invalid CIDR network, or NaN/negative/over-range prefix
  */
 export declare const parse_proxy_entry: (entry: string) => ParsedProxy;
+/**
+ * Strict IP validity check.
+ *
+ * Defense in depth around Hono's `hono/utils/ipaddr` helpers, which are
+ * lax in two ways:
+ *
+ * 1. `distinctRemoteAddr` classifies anything-with-a-colon as `'IPv6'`,
+ *    including `'host:port'`, `'attacker:controlled'`, `'203.0.113.1:8080'`.
+ * 2. `convertIPv6ToBinary` silently accepts malformed forms like
+ *    `'[::1]:8080'` and `'::1\n'`, parsing them as inconsistent binary
+ *    values that would still serve as distinct rate-limit keys for an
+ *    attacker rotating the suffix.
+ *
+ * Strict validation here is two-layered: a character-set pre-filter
+ * (`IP_LITERAL_CHARS`), then a round-trip through `convertIPv*ToBinary`
+ * to confirm the input parses cleanly. Either layer alone has holes;
+ * together they reject every input form we've seen Hono mis-handle.
+ *
+ * Used as the security primitive for any code path that takes an IP
+ * string from an untrusted source (XFF, query params) and uses it as a
+ * key (rate limiting, audit subject) or compares it against trusted
+ * proxies via CIDR (where the latent throw would otherwise bubble out).
+ *
+ * @returns the address family on success, `undefined` if the string is
+ *          not a strictly-valid IP
+ */
+export declare const validate_ip_strict: (ip: string) => "IPv4" | "IPv6" | undefined;
 /**
  * Check whether `ip` matches any entry in the trusted proxy list.
  *
  * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ * Uses `validate_ip_strict` to reject malformed input — without strict
+ * validation, Hono's lax `distinctRemoteAddr` would let an entry like
+ * `'203.0.113.1:8080'` (false-positive `'IPv6'`) reach
+ * `convertIPv6ToBinary` in the CIDR-match branch and throw.
  */
 export declare const is_trusted_ip: (ip: string, proxies: Array<ParsedProxy>) => boolean;
 /**
  * Resolve the real client IP from an `X-Forwarded-For` header value.
  *
- * Walks right-to-left, skipping trusted proxy entries. The first
- * non-trusted entry is the client IP. If all entries are trusted,
- * returns the leftmost entry. All entries are normalized before
- * matching and in the returned value.
+ * Walks right-to-left, skipping trusted proxy entries AND any entry
+ * that fails strict IP validation (`validate_ip_strict`). The first
+ * untrusted, strictly-valid entry is the client IP. If every walked
+ * entry is trusted or malformed, returns the leftmost strictly-valid
+ * (trusted) entry (likely-misconfigured all-trusted case) or
+ * `undefined` (everything was malformed — middleware falls back to
+ * the connection IP). All entries are normalized before matching and
+ * in the returned value.
+ *
+ * Skipping malformed entries is the rate-limit-key fix for the
+ * "attacker controls XFF and the proxy passes it through" surface —
+ * without the skip, an attacker could rotate arbitrary strings (incl.
+ * `'attacker:controlled'`, which Hono's lax `distinctRemoteAddr`
+ * misclassifies as IPv6) as XFF values to get fresh per-IP rate-limit
+ * buckets. Tradeoff: legitimate non-standard proxies that include
+ * ports in XFF entries (e.g. `203.0.113.1:8080`) also fail strict
+ * validation, so those entries get skipped and the rate-limit bucket
+ * collapses to the proxy's connection IP (one bucket for everyone
+ * behind that proxy). Standard proxies (nginx, cloud LBs) don't
+ * include ports.
  *
  * @param forwarded_for - the `X-Forwarded-For` header value
  * @param proxies - parsed trusted proxy entries
- * @returns the normalized client IP, or `undefined` if the header is empty
+ * @returns the normalized client IP, or `undefined` if the header is empty / all entries malformed
  */
 export declare const resolve_client_ip: (forwarded_for: string, proxies: Array<ParsedProxy>) => string | undefined;
 /**

package/dist/http/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AAiBF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SAiBX,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AA2BF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,MAAM,GAAG,SAWjE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SA0BX,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}

package/dist/http/proxy.js

@@ -91,14 +91,70 @@ const cidr_contains = (ip_binary, network, prefix, total_bits) => {
     const shift = BigInt(total_bits - prefix);
     return ip_binary >> shift === network >> shift;
 };
+/**
+ * Allowed character set for a bare IP literal.
+ *
+ * Covers the union of IPv4 (digits + `.`), IPv6 (hex digits + `:`), and
+ * IPv4-mapped IPv6 forms (`::ffff:127.0.0.1`). Anything outside this
+ * set — brackets, whitespace, control bytes, letters g-z — disqualifies
+ * the input regardless of what Hono's parser does with it.
+ */
+const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
+/**
+ * Strict IP validity check.
+ *
+ * Defense in depth around Hono's `hono/utils/ipaddr` helpers, which are
+ * lax in two ways:
+ *
+ * 1. `distinctRemoteAddr` classifies anything-with-a-colon as `'IPv6'`,
+ *    including `'host:port'`, `'attacker:controlled'`, `'203.0.113.1:8080'`.
+ * 2. `convertIPv6ToBinary` silently accepts malformed forms like
+ *    `'[::1]:8080'` and `'::1\n'`, parsing them as inconsistent binary
+ *    values that would still serve as distinct rate-limit keys for an
+ *    attacker rotating the suffix.
+ *
+ * Strict validation here is two-layered: a character-set pre-filter
+ * (`IP_LITERAL_CHARS`), then a round-trip through `convertIPv*ToBinary`
+ * to confirm the input parses cleanly. Either layer alone has holes;
+ * together they reject every input form we've seen Hono mis-handle.
+ *
+ * Used as the security primitive for any code path that takes an IP
+ * string from an untrusted source (XFF, query params) and uses it as a
+ * key (rate limiting, audit subject) or compares it against trusted
+ * proxies via CIDR (where the latent throw would otherwise bubble out).
+ *
+ * @returns the address family on success, `undefined` if the string is
+ *          not a strictly-valid IP
+ */
+export const validate_ip_strict = (ip) => {
+    if (!IP_LITERAL_CHARS.test(ip))
+        return undefined;
+    const type = distinctRemoteAddr(ip);
+    if (!type)
+        return undefined;
+    try {
+        if (type === 'IPv4')
+            convertIPv4ToBinary(ip);
+        else
+            convertIPv6ToBinary(ip);
+        return type;
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
  * Check whether `ip` matches any entry in the trusted proxy list.
  *
  * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ * Uses `validate_ip_strict` to reject malformed input — without strict
+ * validation, Hono's lax `distinctRemoteAddr` would let an entry like
+ * `'203.0.113.1:8080'` (false-positive `'IPv6'`) reach
+ * `convertIPv6ToBinary` in the CIDR-match branch and throw.
  */
 export const is_trusted_ip = (ip, proxies) => {
     const normalized = normalize_ip(ip);
-    const address_type = distinctRemoteAddr(normalized);
+    const address_type = validate_ip_strict(normalized);
     if (!address_type)
         return false;
     for (const proxy of proxies) {
@@ -121,22 +177,33 @@ export const is_trusted_ip = (ip, proxies) => {
     }
     return false;
 };
-// NOTE: some non-standard proxies include ports in XFF entries (e.g.
-// 203.0.113.1:8080). The entry fails distinctRemoteAddr and is treated as
-// untrusted (safe default), but rate limiting keys on the port-suffixed
-// string instead of the bare IP. Low risk — nginx and cloud LBs don't
-// include ports.
 /**
  * Resolve the real client IP from an `X-Forwarded-For` header value.
  *
- * Walks right-to-left, skipping trusted proxy entries. The first
- * non-trusted entry is the client IP. If all entries are trusted,
- * returns the leftmost entry. All entries are normalized before
- * matching and in the returned value.
+ * Walks right-to-left, skipping trusted proxy entries AND any entry
+ * that fails strict IP validation (`validate_ip_strict`). The first
+ * untrusted, strictly-valid entry is the client IP. If every walked
+ * entry is trusted or malformed, returns the leftmost strictly-valid
+ * (trusted) entry (likely-misconfigured all-trusted case) or
+ * `undefined` (everything was malformed — middleware falls back to
+ * the connection IP). All entries are normalized before matching and
+ * in the returned value.
+ *
+ * Skipping malformed entries is the rate-limit-key fix for the
+ * "attacker controls XFF and the proxy passes it through" surface —
+ * without the skip, an attacker could rotate arbitrary strings (incl.
+ * `'attacker:controlled'`, which Hono's lax `distinctRemoteAddr`
+ * misclassifies as IPv6) as XFF values to get fresh per-IP rate-limit
+ * buckets. Tradeoff: legitimate non-standard proxies that include
+ * ports in XFF entries (e.g. `203.0.113.1:8080`) also fail strict
+ * validation, so those entries get skipped and the rate-limit bucket
+ * collapses to the proxy's connection IP (one bucket for everyone
+ * behind that proxy). Standard proxies (nginx, cloud LBs) don't
+ * include ports.
  *
  * @param forwarded_for - the `X-Forwarded-For` header value
  * @param proxies - parsed trusted proxy entries
- * @returns the normalized client IP, or `undefined` if the header is empty
+ * @returns the normalized client IP, or `undefined` if the header is empty / all entries malformed
  */
 export const resolve_client_ip = (forwarded_for, proxies) => {
     const entries = [];
@@ -147,15 +214,26 @@ export const resolve_client_ip = (forwarded_for, proxies) => {
     }
     if (entries.length === 0)
         return undefined;
-    // Walk from right to left, skip trusted proxies
+    // Walk from right to left, skip trusted proxies and malformed entries.
+    // Returning a malformed entry as the client IP would let an attacker
+    // who controls XFF poison the per-IP rate-limit key.
     for (let i = entries.length - 1; i >= 0; i--) {
         const entry = entries[i];
+        if (!validate_ip_strict(entry))
+            continue;
         if (!is_trusted_ip(entry, proxies)) {
             return entry;
         }
     }
-    // All entries are trusted — return leftmost (edge case, likely misconfigured)
-    return entries[0];
+    // Every entry was trusted or malformed. Prefer the leftmost
+    // strictly-valid (trusted) entry — the misconfiguration warn in
+    // the middleware fires on it. If none, fall through to undefined
+    // and let the middleware fall back to the connection IP.
+    for (const entry of entries) {
+        if (validate_ip_strict(entry))
+            return entry;
+    }
+    return undefined;
 };
 /**
  * Create a Hono middleware that resolves the client IP from trusted proxies.

package/dist/http/route_spec.d.ts

@@ -18,22 +18,7 @@ import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { Db } from '../db/db.js';
 import { type RouteErrorSchemas, type RateLimitKey } from './error_schemas.js';
 import type { MiddlewareSpec } from './middleware_spec.js';
-/**
- * Auth requirement for a route — `none`, `authenticated`, a specific role, or `keeper`.
- *
- * `{type: 'none'}` means the route is open to all clients — including non-browser
- * callers (CLI, API tokens, scripts). No session or auth middleware guards are applied.
- */
-export type RouteAuth = {
-    type: 'none';
-} | {
-    type: 'authenticated';
-} | {
-    type: 'role';
-    role: string;
-} | {
-    type: 'keeper';
-};
+import { type RouteAuth } from './auth_shape.js';
 /**
  * Two-phase auth guard set returned by `AuthGuardResolver`.
  *
@@ -41,7 +26,7 @@ export type RouteAuth = {
  * so unauthenticated callers never see route-shape information from
  * input parsing failures. `post_authorization` runs after the
  * authorization phase has populated `RequestContext` — role / keeper
- * checks live here because they read `c.var.request_context.permits`.
+ * checks live here because they read `c.var.request_context.role_grants`.
  */
 export interface AuthGuards {
     pre_validation: Array<MiddlewareHandler>;
@@ -52,17 +37,16 @@ export interface AuthGuards {
  *
  * Injected into `apply_route_specs` to decouple route registration
  * from auth-specific middleware. See `fuz_auth_guard_resolver` in
- * `auth/route_guards.ts` for the standard implementation.
+ * `auth/auth_guard_resolver.ts` for the standard implementation.
  */
 export type AuthGuardResolver = (auth: RouteAuth) => AuthGuards;
 /**
- * Per-route authorization phase. Runs after the pre-validation auth guards
- * and before input validation; resolves the acting actor (when the route's
- * input declares `acting?: ActingActor` or auth requires permits) and sets
- * the request context on the Hono context. Per-route order in
- * `apply_route_specs`: params → query → pre-validation auth (401) →
- * authorization → post-authorization auth (403) → input validation →
- * handler.
+ * Per-route authorization phase. Runs after pre-validation auth guards
+ * AND input validation; resolves the acting actor (when `auth.actor !== 'none'`)
+ * by reading `c.var.validated_input.acting` and sets the request context on
+ * the Hono context. Per-route order in `apply_route_specs`: params → query
+ * → pre-validation auth (401) → input validation (400) → authorization
+ * phase → post-authorization auth (403) → handler.
  *
  * Returns a `Response` to short-circuit (resolution failure → 400 / 500),
  * or `void` to continue. The http framework stays auth-agnostic — fuz_app
@@ -70,37 +54,46 @@ export type AuthGuardResolver = (auth: RouteAuth) => AuthGuards;
  * `auth/request_context.ts`.
  */
 export type AuthorizationHandler = (c: Context, spec: RouteSpec) => Promise<Response | void>;
-/**
- * Predicate that decides whether a route is "acting-aware" — i.e. whether
- * the dispatcher's authorization phase may emit `actor_required` /
- * `actor_not_on_account` (400) or `no_actors_on_account` /
- * `account_vanished` (500) on this spec. When the predicate returns true
- * the merged error schema is widened to accept those shapes so DEV-mode
- * `wrap_output_validation` doesn't reject them.
- *
- * Computed at the call site because the canonical "input declares
- * `acting?: ActingActor`" check lives in `auth/request_context.ts` (it
- * uses reference equality with the canonical `ActingActor` schema). The
- * `http/` framework receives the predicate via this callback so it stays
- * auth-agnostic. See `http/CLAUDE.md` § Three-layer error-schema merge.
- */
-export type IsActingAware = (spec: Pick<RouteSpec, 'auth' | 'input'>) => boolean;
 /** HTTP methods supported by route specs. */
 export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 /**
  * Per-request deps provided by the framework to route handlers.
+ *
+ * Audit writes and other rollback-resilient fire-and-forget calls run
+ * through `AppDeps.audit.emit(ctx, input)` (see `auth/audit_emitter.ts`),
+ * which captures the pool inside its closure — handlers can never
+ * accidentally write audits against the request transaction.
+ *
+ * Routes whose body manages its own transaction (signup, bootstrap)
+ * declare `transaction: false` on the spec, which makes `route.db` the
+ * pool — they reach for it directly.
  */
 export interface RouteContext {
-    /** Transaction-scoped for mutations, pool-level for reads. */
+    /**
+     * Transaction-scoped when `RouteSpec.transaction` is true (the default
+     * for non-GET); pool-level otherwise.
+     */
     db: Db;
-    /** Always pool-level — for fire-and-forget effects that must outlive the transaction. */
-    background_db: Db;
-    /** Fire-and-forget side effects — push here for post-response flushing. */
+    /**
+     * Eager fire-and-forget queue — push the in-flight `Promise<void>` for
+     * pool writes already running (audit emits, session touch, api-token
+     * usage tracking). The flush middleware drains via
+     * `flush_pending_effects` after the handler returns.
+     */
     pending_effects: Array<Promise<void>>;
+    /**
+     * Deferred post-commit thunks — do not push directly; reach for
+     * `emit_after_commit(ctx, fn)` from `pending_effects.ts`. The flush
+     * middleware invokes each thunk after the handler (and any wrapping
+     * `db.transaction`) returns, closing the microtask-ordering window
+     * that an eager `Promise.resolve().then(fn)` leaves open inside the
+     * transaction.
+     */
+    post_commit_effects: Array<() => void | Promise<void>>;
 }
 /**
  * Route handler function — receives the Hono context and a `RouteContext`
- * with per-request deps (db, background_db, pending_effects).
+ * with per-request deps (db, pending_effects).
  *
  * TypeScript allows fewer params, so handlers that don't need `route`
  * can use `(c) => ...` without changes.
@@ -164,27 +157,39 @@ export interface RouteSpec {
 /**
  * Get validated input from the Hono context.
  *
- * Call after the input validation middleware has run. The type parameter
- * should match the route's `input` schema.
+ * Call after the input validation middleware has run. Pass the route's
+ * `input` Zod schema to infer the typed shape directly:
+ *
+ * ```ts
+ * const input = get_route_input(c, my_route_spec.input);
+ * ```
+ *
+ * Or pass an explicit type argument when the schema isn't in scope:
+ *
+ * ```ts
+ * const input = get_route_input<MyInput>(c);
+ * ```
  */
-export declare const get_route_input: <T>(c: Context) => T;
+export declare function get_route_input<S extends z.ZodType>(c: Context, schema: S): z.infer<S>;
+export declare function get_route_input<T = unknown>(c: Context): T;
 /**
  * Get validated URL path params from the Hono context.
  *
- * Call after the params validation middleware has run. The type parameter
- * should match the route's `params` schema.
- *
- * TODO derive `T` from the route spec so the type parameter isn't manually
- * specified — same applies to `get_route_input` / `get_route_query`.
+ * Call after the params validation middleware has run. Pass the route's
+ * `params` schema to infer the typed shape, or supply an explicit type
+ * argument. See `get_route_input` for the two call shapes.
  */
-export declare const get_route_params: <T>(c: Context) => T;
+export declare function get_route_params<S extends z.ZodType>(c: Context, schema: S): z.infer<S>;
+export declare function get_route_params<T = unknown>(c: Context): T;
 /**
  * Get validated URL query params from the Hono context.
  *
- * Call after the query validation middleware has run. The type parameter
- * should match the route's `query` schema.
+ * Call after the query validation middleware has run. Pass the route's
+ * `query` schema to infer the typed shape, or supply an explicit type
+ * argument. See `get_route_input` for the two call shapes.
  */
-export declare const get_route_query: <T>(c: Context) => T;
+export declare function get_route_query<S extends z.ZodType>(c: Context, schema: S): z.infer<S>;
+export declare function get_route_query<T = unknown>(c: Context): T;
 /**
  * Apply named middleware specs to a Hono app.
  *
@@ -202,29 +207,38 @@ export declare const apply_middleware_specs: (app: Hono, specs: Array<Middleware
  * and generic errors), and registers the route.
  *
  * Per-route middleware order: params → query → pre-validation auth
- * guards (401) → authorization phase → post-authorization auth guards
- * (403) → input validation → handler. The 401 check runs before any
- * body parsing so unauthenticated callers never see route-shape
- * information from parse failures. The authorization phase runs before
- * input validation (matches the RPC dispatcher's order) so role /
- * keeper denials surface 403 before 400 invalid_params; it extracts
- * `acting` from raw query (GET) or pre-parsed JSON body (POST/PUT/...)
- * — Hono caches the parsed body internally so the subsequent input-
- * validation step does not re-parse. The role / keeper guards consume
- * the `RequestContext` populated by the authorization phase.
+ * guards (401) → input validation (400) → authorization phase →
+ * post-authorization auth guards (403) → handler. The 401 check runs
+ * before any body parsing so unauthenticated callers never see
+ * route-shape information from parse failures. Input validation runs
+ * before the authorization phase (validate first, authorize after) so
+ * the authorization phase reads `c.var.validated_input.acting` as a
+ * typed Zod field instead of pre-parsing the raw body. Role /
+ * credential-type denials still surface 403 last; trade-off is that
+ * authenticated-but-unauthorized callers can distinguish 400
+ * (validation) from 403 (authorization), a defense-in-depth concession
+ * deemed acceptable because the route surface is public via
+ * spec/codegen JSON.
  *
  * Each handler receives a `RouteContext` with:
- * - `db`: transaction-scoped (for non-GET) or pool-level (for GET)
- * - `background_db`: always pool-level
- * - `pending_effects`: fire-and-forget effect queue
- *
- * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/route_guards.ts`
- * @param authorize - optional authorization phase; runs between guards and input validation
+ * - `db`: transaction-scoped when `RouteSpec.transaction` is true; pool-level otherwise
+ * - `pending_effects`: eager fire-and-forget pool-write queue
+ * - `post_commit_effects`: deferred-thunk queue (push via `emit_after_commit`)
+ *
+ * Also enforces registry-time invariant 2 from the auth-shape design:
+ * `auth.actor !== 'none' ⟺ input or query declares acting?: ActingActor`.
+ * REST is bi-located (GETs declare `acting` on `query`, mutations on
+ * `input`), so the check passes both slots; the action-dispatcher
+ * registries (`compile_action_registry`) share the same helper with
+ * `input` only — `ActionSpec` has no `query` shape.
+ *
+ * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`
+ * @param authorize - optional authorization phase; runs after input validation
  * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
- * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique), or if any spec violates the actor-acting biconditional
  */
-export declare const apply_route_specs: (app: Hono, specs: Array<RouteSpec>, resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db, authorize?: AuthorizationHandler, is_acting_aware?: IsActingAware) => void;
+export declare const apply_route_specs: (app: Hono, specs: Array<RouteSpec>, resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db, authorize?: AuthorizationHandler) => void;
 /**
  * Prepend a prefix to all route spec paths.
  *

package/dist/http/route_spec.d.ts.map

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