@daloyjs/core 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/idempotency.d.ts

@@ -164,17 +164,71 @@ export interface IdempotencyOptions {
      * unauthenticated idempotent writes). Returning a stable per-user id is
      * preferable to the raw credential when tokens rotate between retries.
      *
+     * **Supply this whenever `Authorization` is not per-user.** The default assumes
+     * that header names one caller. If it is shared — a per-tenant API key, a
+     * service token, a gateway credential — with end users distinguished some other
+     * way (a session cookie, a subject claim your app reads), then the default
+     * partitions per *tenant* and every user inside one tenant shares a namespace.
+     * A caller who knows another's `Idempotency-Key` can then replay their stored
+     * response. This is not detectable from the header alone, which is why it is
+     * your call rather than a framework guard: a resolvable-but-coarse scope looks
+     * identical to a correctly per-user one. The cookie-only case *is* guarded —
+     * see {@link allowUnscopedCallers}.
+     *
+     * Independently of scoping, a replay never re-issues `Set-Cookie`, so a coarse
+     * namespace cannot escalate from disclosing a response body into handing over a
+     * live session.
+     *
      * @since 0.40.0
      */
     scope?: (ctx: BaseContext<any, any>) => string | undefined | Promise<string | undefined>;
+    /**
+     * Accept callers the default {@link scope} resolver cannot identify, letting
+     * them share one idempotency namespace. Default `false`.
+     *
+     * The guard this disables exists because a cookie-authenticated request
+     * carries no `Authorization` header, so the default resolver returns
+     * `undefined` and the namespace collapses. The retry fingerprint (method +
+     * path + body) is then all that separates two users — and two users
+     * submitting the same payload fingerprint identically, so one replays the
+     * other's stored response (CWE-524). Rather than share the namespace
+     * silently, a cookie-bearing request with no resolvable scope throws with an
+     * actionable message.
+     *
+     * Set this to `true` only when unscoped callers are genuinely interchangeable
+     * — a public, unauthenticated idempotent write where no response body is
+     * caller-specific. Supplying {@link scope} is almost always the right answer
+     * instead. A custom `scope` bypasses the guard entirely, including when it
+     * returns `undefined`, because an explicit resolver owns its own posture.
+     *
+     * @since 1.0.0-rc.8
+     */
+    allowUnscopedCallers?: boolean;
 }
 /**
  * In-memory {@link IdempotencyStore}. Suitable for tests and single-process
- * deployments. Expired records are dropped on access; the map is opportunistically
- * pruned so it cannot grow without bound.
+ * deployments. Expired records are dropped on access.
+ *
+ * Growth is bounded by {@link maxEntries}: an expiry sweep runs first, and if the
+ * store is still at the cap the oldest surviving record is evicted. The sweep
+ * alone is not a bound — it only drops records that have *expired*, so a stream
+ * of unique keys inside the TTL grew the map linearly no matter how often it ran,
+ * with each entry pinning a stored response body.
+ *
+ * Evicting a live record can only cost exactly-once semantics for a retry that
+ * arrives after the eviction — it re-executes rather than replaying. That is the
+ * right trade against unbounded memory, but it is a reason to supply a shared
+ * (e.g. Redis) store for any deployment where the key volume approaches the cap.
  */
 export declare class MemoryIdempotencyStore implements IdempotencyStore {
     private readonly map;
+    private readonly maxEntries;
+    /**
+     * @param maxEntries - Maximum live records retained. Must be a positive
+     *   integer. Default {@link DEFAULT_MAX_IDEMPOTENCY_ENTRIES} (10 000).
+     * @throws Error when `maxEntries` is not a positive integer.
+     */
+    constructor(maxEntries?: number);
     /**
      * @inheritDoc
      * `_ttlMs` is part of the {@link IdempotencyStore} contract but unused here:
@@ -192,6 +246,19 @@ export declare class MemoryIdempotencyStore implements IdempotencyStore {
     /** Test helper. Number of stored records (including expired). */
     size(): number;
 }
+/**
+ * Internal Symbol stamped on the hooks {@link idempotency} returns, so `App`'s
+ * boot guards can see where a stored-response replay sits in a route's effective
+ * hook chain.
+ *
+ * A replay is returned from `beforeHandle` and ends the hook chain, which means
+ * anything enforcing from the *same* phase but mounted later never runs. That is
+ * how a `rateLimit()` behind a replay stops counting. The marker lets the boot
+ * path refuse that order rather than leave the limiter silently infinite.
+ *
+ * @internal
+ */
+export declare const IDEMPOTENCY_HOOK_MARKER: unique symbol;
 /**
  * Idempotency-key middleware. Mount it ahead of the routes that need
  * exactly-once semantics under retries (typically the payment / write

package/dist/idempotency.js

@@ -55,13 +55,44 @@ export function _resetSharedIdempotencyStoresForTests() {
     SHARED_IDEMPOTENCY_STORES.clear();
 }
 // ---------- Default store ----------
+/**
+ * Default cap on live records held by {@link MemoryIdempotencyStore}.
+ *
+ * Each record can hold a base64 response body up to
+ * {@link IdempotencyOptions.maxResponseBytes} (1 MiB by default), so the cap is
+ * what actually bounds this store's footprint. Matches the size at which the
+ * store already attempted an expiry sweep.
+ */
+const DEFAULT_MAX_IDEMPOTENCY_ENTRIES = 10_000;
 /**
  * In-memory {@link IdempotencyStore}. Suitable for tests and single-process
- * deployments. Expired records are dropped on access; the map is opportunistically
- * pruned so it cannot grow without bound.
+ * deployments. Expired records are dropped on access.
+ *
+ * Growth is bounded by {@link maxEntries}: an expiry sweep runs first, and if the
+ * store is still at the cap the oldest surviving record is evicted. The sweep
+ * alone is not a bound — it only drops records that have *expired*, so a stream
+ * of unique keys inside the TTL grew the map linearly no matter how often it ran,
+ * with each entry pinning a stored response body.
+ *
+ * Evicting a live record can only cost exactly-once semantics for a retry that
+ * arrives after the eviction — it re-executes rather than replaying. That is the
+ * right trade against unbounded memory, but it is a reason to supply a shared
+ * (e.g. Redis) store for any deployment where the key volume approaches the cap.
  */
 export class MemoryIdempotencyStore {
     map = new Map();
+    maxEntries;
+    /**
+     * @param maxEntries - Maximum live records retained. Must be a positive
+     *   integer. Default {@link DEFAULT_MAX_IDEMPOTENCY_ENTRIES} (10 000).
+     * @throws Error when `maxEntries` is not a positive integer.
+     */
+    constructor(maxEntries = DEFAULT_MAX_IDEMPOTENCY_ENTRIES) {
+        if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+            throw new Error(`MemoryIdempotencyStore: maxEntries must be a positive integer; got ${String(maxEntries)}.`);
+        }
+        this.maxEntries = maxEntries;
+    }
     /**
      * @inheritDoc
      * `_ttlMs` is part of the {@link IdempotencyStore} contract but unused here:
@@ -71,9 +102,19 @@ export class MemoryIdempotencyStore {
         const existing = this.read(key);
         if (existing)
             return existing;
-        this.map.set(key, record);
-        if (this.map.size > 10_000)
+        if (this.map.size >= this.maxEntries) {
             this.prune();
+            // Still full: every record is live, so drop the oldest. `Map` iterates in
+            // insertion order, and `complete()` overwrites in place rather than
+            // re-inserting, so the first key is the least recently reserved.
+            while (this.map.size >= this.maxEntries) {
+                const oldest = this.map.keys().next();
+                if (oldest.done)
+                    break;
+                this.map.delete(oldest.value);
+            }
+        }
+        this.map.set(key, record);
         return null;
     }
     /** @inheritDoc */
@@ -185,25 +226,87 @@ function validateKey(key, headerName, maxLen) {
         throw new BadRequestError(`${headerName} header contains invalid characters.`);
     }
 }
+/**
+ * Response headers that must never be stored for replay.
+ *
+ * `set-cookie` is the security-critical entry. A stored response was replayed
+ * with every header the original produced, so a `Set-Cookie` issued to the first
+ * caller was re-issued to whoever replayed the record. Combined with any
+ * coarse-scoped namespace (a shared tenant `Authorization`, or an explicit
+ * `allowUnscopedCallers: true`) that promotes a body disclosure into handing over
+ * a live session — account takeover rather than data leakage. Even for a
+ * correctly scoped, genuinely same-caller retry it is wrong: the replay would
+ * resurrect a cookie the handler set once, silently rolling back a session
+ * rotation performed at login or on a privilege change.
+ *
+ * Unlike `responseCache()`, which refuses to store a `Set-Cookie` response at
+ * all, idempotency strips and stores: declining to store would release the
+ * reservation and let a retry re-execute the handler, which for a payment or
+ * order endpoint is the double-charge this middleware exists to prevent.
+ * Stripping keeps exactly-once semantics and drops only the header that must not
+ * be replayed.
+ *
+ * The remainder are hop-by-hop or per-request fields (RFC 9110 §7.6.1) that
+ * describe the one connection or the one request that populated the record;
+ * replaying `x-request-id` in particular hands every later caller a correlation
+ * id belonging to someone else's request.
+ */
+const NEVER_REPLAYED_HEADERS = new Set([
+    "set-cookie",
+    "set-cookie2",
+    "age",
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "x-request-id",
+]);
 async function captureResponse(res, maxBytes) {
     const buf = new Uint8Array(await res.clone().arrayBuffer());
     if (buf.byteLength > maxBytes)
         return null;
     const headers = [];
     res.headers.forEach((value, name) => {
-        headers.push([name, value]);
+        // Filter on capture, not on replay, so a credential never reaches the store
+        // in the first place — a shared (Redis) store would otherwise persist one
+        // caller's session cookie for the whole TTL.
+        if (!NEVER_REPLAYED_HEADERS.has(name.toLowerCase()))
+            headers.push([name, value]);
     });
     return { status: res.status, headers, body: buf.byteLength ? bytesToBase64(buf) : "" };
 }
 function buildReplayResponse(stored, replayHeaderName) {
     const headers = new Headers();
-    for (const [name, value] of stored.headers)
+    for (const [name, value] of stored.headers) {
+        // Filtered on capture already; re-checked here so a record written by an
+        // older build — or by any other writer sharing the same Redis store — cannot
+        // replay a credential either.
+        if (NEVER_REPLAYED_HEADERS.has(name.toLowerCase()))
+            continue;
         headers.set(name, value);
+    }
     headers.set(replayHeaderName, "true");
     const body = stored.body ? base64ToBytes(stored.body) : null;
     return markSchemaValidatedResponse(new Response(body, { status: stored.status, headers }));
 }
 // ---------- Middleware ----------
+/**
+ * Internal Symbol stamped on the hooks {@link idempotency} returns, so `App`'s
+ * boot guards can see where a stored-response replay sits in a route's effective
+ * hook chain.
+ *
+ * A replay is returned from `beforeHandle` and ends the hook chain, which means
+ * anything enforcing from the *same* phase but mounted later never runs. That is
+ * how a `rateLimit()` behind a replay stops counting. The marker lets the boot
+ * path refuse that order rather than leave the limiter silently infinite.
+ *
+ * @internal
+ */
+export const IDEMPOTENCY_HOOK_MARKER = Symbol.for("daloyjs.idempotency.hook");
 /**
  * Idempotency-key middleware. Mount it ahead of the routes that need
  * exactly-once semantics under retries (typically the payment / write
@@ -252,6 +355,7 @@ export function idempotency(opts = {}) {
     const replayHeaderName = (opts.replayHeaderName ?? "idempotency-replayed").toLowerCase();
     const methods = new Set((opts.methods ?? ["POST", "PUT", "PATCH", "DELETE"]).map((m) => m.toUpperCase()));
     const requireKey = opts.requireKey === true;
+    const allowUnscopedCallers = opts.allowUnscopedCallers === true;
     const cacheableStatus = opts.cacheableStatus ?? ((status) => status < 500);
     const ttlMs = ttlSeconds * 1_000;
     let store;
@@ -270,7 +374,7 @@ export function idempotency(opts = {}) {
         store = new MemoryIdempotencyStore();
     }
     const keyPrefix = opts.groupId ? `${opts.groupId}:` : "";
-    return {
+    const hooks = {
         async beforeHandle(ctx) {
             const method = ctx.request.method.toUpperCase();
             if (!methods.has(method))
@@ -291,6 +395,44 @@ export function idempotency(opts = {}) {
             const scopeRaw = opts.scope
                 ? await opts.scope(ctx)
                 : (ctx.request.headers.get("authorization") ?? undefined);
+            // A credentialed request the default resolver cannot see is the dangerous
+            // case: cookie-session auth sends no `Authorization`, so `scopeRaw` is
+            // undefined, the namespace collapses to the shared one, and the retry
+            // fingerprint (method + path + body) becomes the only thing separating two
+            // users. Two users legitimately submit the same payload fingerprint
+            // identically — so client B replays client A's stored response, which is
+            // exactly the CWE-524 disclosure `scope` exists to prevent.
+            //
+            // Fail loudly rather than share the namespace. This mirrors
+            // `responseCache()`, which treats `Cookie` as a credential alongside
+            // `Authorization` for the same reason. Only fires when a cookie is present
+            // *and* nothing resolved, so the documented bearer-token path is untouched
+            // and a genuinely anonymous caller still shares the unscoped namespace.
+            //
+            // Deliberately NOT widened to "any cookie-bearing request". A resolvable
+            // scope can still be too coarse — a per-tenant API key with
+            // cookie-identified end users partitions per tenant while every user inside
+            // one shares a namespace — but that is indistinguishable from the far more
+            // common shape of a *per-user* bearer token arriving alongside incidental
+            // browser cookies (analytics, consent, CSRF), where the default is already
+            // correct. Keying the guard on the cookie's presence rejects that setup with
+            // a 500, so the check stays where the default is provably useless rather
+            // than merely possibly coarse. Callers whose `Authorization` is shared
+            // across users must pass `scope` — see the TSDoc on
+            // {@link IdempotencyOptions.scope}. Independently of scoping, `Set-Cookie`
+            // is never stored or replayed (see {@link NEVER_REPLAYED_HEADERS}), so a
+            // coarse namespace cannot escalate into handing over a live session.
+            if (!opts.scope &&
+                scopeRaw === undefined &&
+                !allowUnscopedCallers &&
+                ctx.request.headers.has("cookie")) {
+                throw new Error("idempotency(): cannot determine the calling principal for a cookie-bearing request. " +
+                    "The default scope reads the Authorization header, which this request does not carry, " +
+                    "so every cookie-authenticated caller would share one idempotency namespace and could " +
+                    "replay another caller's stored response (CWE-524). Pass " +
+                    "`scope: (ctx) => ctx.state.session?.id` (or another stable per-caller id), or set " +
+                    "`allowUnscopedCallers: true` if these callers are genuinely interchangeable.");
+            }
             const scopeTag = scopeRaw ? `${await sha256Hex(scopeRaw)}:` : "";
             const storeKey = `${keyPrefix}${scopeTag}${key}`;
             const now = Date.now();
@@ -354,6 +496,8 @@ export function idempotency(opts = {}) {
             return undefined;
         },
     };
+    hooks[IDEMPOTENCY_HOOK_MARKER] = true;
+    return hooks;
 }
 function isPromiseLike(value) {
     return (value !== null &&

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DA
 export type { SubdomainsOptions, SubdomainsResult } from "./subdomains.js";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
 export type { DependencyHooks, DependencyOptions } from "./dependency.js";
-export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, PreBodyContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.js";
+export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, PreBodyContext, IdentityGateContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.js";
 export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, RequestHeaderFieldsTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.js";
 export type { ProblemDetails, ProblemRenderOptions, HttpErrorOptions } from "./errors.js";
 export type { StandardSchemaV1 } from "./schema.js";
@@ -101,5 +101,5 @@ export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACI
 export type { OtelTracingOptions, TracingAttributes, TracingAttributeValue, TracingSpan, TracingStartSpanOptions, TracingTracer, } from "./tracing.js";
 export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
 export type { TenancyOptions, TenantResolver, TenantScopeOptions, SubdomainTenantOptions, PathPrefixTenantOptions, ClaimTenantOptions, UnresolvedStatus, InvalidStatus, } from "./tenancy.js";
-export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
+export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, isValidWireCloseCode, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
 export type { WebSocketConnection, WebSocketContext, WebSocketHandler, WebSocketMeta, WebSocketRouteEntry, NormalizedWebSocketOptions, WebSocketBeforeUpgrade, HandshakeResult, ParsedFrame, MessageEvent as WebSocketMessageEvent, FrameSinkEvents, } from "./websocket.js";

package/dist/index.js

@@ -51,4 +51,4 @@ export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATI
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
 export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
-export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
+export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, isValidWireCloseCode, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";

package/dist/ip-reputation.d.ts

@@ -44,7 +44,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * A pluggable source of abusive IP / CIDR entries. Implementations return the
  * raw list each refresh; parsing, validation, and de-duplication are handled by
@@ -105,7 +105,7 @@ export interface IpReputationOptions {
      * Custom client-IP resolver. Overrides {@link IpReputationOptions.trustProxyHeaders}.
      * Defaults to failing open (no IP → not blocked).
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Trust `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Only
      * enable behind a trusted proxy that overwrites these headers.

package/dist/ip-reputation.js

@@ -222,7 +222,12 @@ export function ipReputation(opts) {
     const ready = opts.loadOnStart === false ? Promise.resolve() : refresh();
     return {
         hooks: {
-            beforeHandle(ctx) {
+            // `preBody`, not `beforeHandle`: a denylist gate that short-circuits from
+            // `beforeHandle` is preempted by any earlier `beforeHandle` middleware that
+            // returns a Response first — a `responseCache()` HIT mounted above it would
+            // serve a denylisted address the cached body. `preBody` always runs first,
+            // so the feed holds regardless of mount order.
+            preBody(ctx) {
                 const ip = resolveIp(ctx);
                 if (!ip)
                     return undefined; // fail-open on unresolved IP

package/dist/ip-restriction.d.ts

@@ -7,7 +7,7 @@
  *
  * @since 0.19.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Options for {@link ipRestriction}. At least one of `allow` or `deny` must
  * be provided; supplying both runs deny-first then allow-otherwise (deny
@@ -36,7 +36,7 @@ export interface IpRestrictionOptions {
      * Provide a function to read adapter connection metadata or a trusted
      * custom header (e.g. a CDN-specific identifier).
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Read `X-Forwarded-For` / `X-Real-IP` in the default resolver. Defaults
      * to `false` because those headers are client-spoofable unless every
@@ -101,7 +101,7 @@ export interface IpMatcher {
  *
  * @param opts Allow/deny lists plus IP-resolution options; see
  *   {@link IpRestrictionOptions}. Deny matches always win over allow.
- * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ * @returns A {@link Hooks} object whose `preBody` hook enforces the lists,
  *   failing closed (403) when the client IP cannot be resolved or parsed.
  * @throws Error at setup time when neither `allow` nor `deny` is provided,
  *   or when a pattern is not a valid IP/CIDR.

package/dist/ip-restriction.js

@@ -29,7 +29,7 @@ import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js"
  *
  * @param opts Allow/deny lists plus IP-resolution options; see
  *   {@link IpRestrictionOptions}. Deny matches always win over allow.
- * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ * @returns A {@link Hooks} object whose `preBody` hook enforces the lists,
  *   failing closed (403) when the client IP cannot be resolved or parsed.
  * @throws Error at setup time when neither `allow` nor `deny` is provided,
  *   or when a pattern is not a valid IP/CIDR.
@@ -45,7 +45,12 @@ export function ipRestriction(opts) {
     const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
     const message = opts.message ?? "IP address not permitted";
     return {
-        beforeHandle(ctx) {
+        // `preBody`, not `beforeHandle`: a gate that returns a Response from
+        // `beforeHandle` can be preempted by any earlier `beforeHandle` middleware
+        // that short-circuits first — a `responseCache()` HIT mounted above it would
+        // serve a deny-listed address the cached body. `preBody` always runs first,
+        // so the allow/deny lists hold regardless of mount order.
+        preBody(ctx) {
             const raw = resolveIp(ctx);
             if (!raw)
                 throw new ForbiddenError(message);

package/dist/mcp.d.ts

@@ -35,32 +35,24 @@ export declare const MCP_PROTOCOL_VERSIONS: readonly string[];
  *
  * @since 1.0.0
  */
-export declare const MCP_META_KEYS: Readonly<{
-    /** Protocol version for this request. Required on every modern request. */
+export declare const MCP_META_KEYS: {
     readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
-    /** Self-reported client name/version. Advisory only; never a security input. */
     readonly clientInfo: "io.modelcontextprotocol/clientInfo";
-    /** Client capabilities relevant to this request. Required on every modern request. */
     readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
-    /** Minimum log level the server should emit for this request. */
     readonly logLevel: "io.modelcontextprotocol/logLevel";
-    /** Self-reported server name/version, returned in each modern result's `_meta`. */
     readonly serverInfo: "io.modelcontextprotocol/serverInfo";
-}>;
+};
 /**
  * JSON-RPC error codes defined by the MCP specification in its reserved
  * `-32020`..`-32099` sub-range.
  *
  * @since 1.0.0
  */
-export declare const MCP_ERROR_CODES: Readonly<{
-    /** HTTP headers disagree with the request body, or a required header is missing. */
+export declare const MCP_ERROR_CODES: {
     readonly headerMismatch: -32020;
-    /** The request needs a client capability the client did not declare. */
     readonly missingRequiredClientCapability: -32021;
-    /** The requested protocol version is not implemented by this server. */
     readonly unsupportedProtocolVersion: -32022;
-}>;
+};
 /**
  * Default maximum accepted JSON-RPC request body for a DaloyJS MCP endpoint.
  * The cap is intentionally small because MCP calls should carry parameters,

package/dist/safe-redirect.js

@@ -69,6 +69,17 @@ const ALLOWED_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 // response-splitting via the `Location` header.
 // eslint-disable-next-line no-control-regex
 const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f-\u009f]/;
+// Reject *percent-encoded* C0 controls and DEL (`%00`-`%1F`, `%7F`) that arrive
+// as literal text in the target (e.g. a still-encoded query value passed
+// straight through). `CONTROL_CHAR_RE` only sees decoded characters, so an
+// encoded tab would otherwise be written verbatim into the `Location` header.
+// Per WHATWG URL that stays same-origin, but legacy WebKit stacks strip
+// decoded tabs/newlines and can re-interpret `/%09/host` as protocol-relative
+// — the trick behind historical Safari open-redirect CVEs. The range is
+// deliberately narrow: UTF-8 continuation bytes live in `%80`-`%BF`, so
+// legitimate percent-encoded non-ASCII paths (e.g. `/s%C3%A9arch`) are
+// unaffected.
+const ENCODED_CONTROL_CHAR_RE = /%(?:0[0-9a-f]|1[0-9a-f]|7f)/i;
 // Any code point above U+00FF (outside Latin-1). Such characters cannot be
 // written to a `Location` header — which is serialized as an ISO-8859-1
 // ByteString, so `Headers.set` throws a raw `TypeError` — and they cover the
@@ -91,6 +102,14 @@ function classify(target, allowedPaths, allowedOrigins) {
     if (CONTROL_CHAR_RE.test(target)) {
         return { ok: false, reason: "invalid-control-characters" };
     }
+    // Encoded control characters (`%09`, `%00`, …) arriving as literal text:
+    // spec-compliant browsers keep `/%09/host` same-origin, but legacy WebKit
+    // strips decoded tabs/newlines and can fold it into an origin-escaping
+    // protocol-relative URL. Refuse rather than rely on every user agent
+    // parsing it the WHATWG way.
+    if (ENCODED_CONTROL_CHAR_RE.test(target)) {
+        return { ok: false, reason: "invalid-control-characters" };
+    }
     // Protocol-relative (`//evil.com`) is the classic open-redirect bypass.
     if (target.startsWith("//"))
         return { ok: false, reason: "protocol-relative" };

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:01ee81d6-1bb6-55ca-b05e-3e30279d9f5c",
+  "serialNumber": "urn:uuid:85b1efae-7e9c-5b6d-8081-af5e65efa14a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-29T20:03:05.244Z",
+    "timestamp": "2026-08-01T11:35:20.075Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.7"
+        "version": "1.0.0-rc.9"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.7",
+      "version": "1.0.0-rc.9",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.7",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.9",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.7",
+        "version": "1.0.0-rc.9",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.7",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-rc.7",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.7-01ee81d6-1bb6-55ca-b05e-3e30279d9f5c",
+  "name": "@daloyjs/core-1.0.0-rc.9",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.9-85b1efae-7e9c-5b6d-8081-af5e65efa14a",
   "creationInfo": {
-    "created": "2026-07-29T20:03:05.244Z",
+    "created": "2026-08-01T11:35:20.075Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.7",
+      "versionInfo": "1.0.0-rc.9",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.7"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.9"
         }
       ]
     }

package/dist/types.d.ts

@@ -305,6 +305,37 @@ export interface PreBodyContext<P extends string = string> {
         headers: Headers;
     };
 }
+/**
+ * Context handed to the caller-supplied resolvers of the network-identity
+ * access-control gates — `geoBlock`, `ipRestriction`, `botGuard`, `autoBan` and
+ * `ipReputation`.
+ *
+ * Those gates enforce from {@link Hooks.preBody} so a `responseCache()` hit
+ * cannot preempt them (see SECURITY.md, "Hook phase decides what a
+ * short-circuiting middleware can preempt"). Their callbacks therefore run
+ * before body I/O and before *any* `beforeHandle` middleware, which means:
+ *
+ * - `body` is always `undefined` — nothing has been parsed yet.
+ * - `state` holds only what `onRequest` / an earlier `preBody` layer put there.
+ *   In particular it does **not** hold anything `session()` or another
+ *   `beforeHandle` layer resolves.
+ *
+ * The alias exists so that is a compile error instead of a runtime surprise.
+ * Typing these callbacks on the full {@link BaseContext} — whose `body` widens
+ * to `any` — let `(ctx) => ctx.body.email` type-check and then silently evaluate
+ * to `undefined` at run time. The consequence differed per gate and two of the
+ * five failed *silently*: `ipReputation` fails open on an unresolved IP, and
+ * `autoBan` stopped recording strikes altogether because it never got an
+ * identity to attribute them to.
+ *
+ * Resolve identity from `request` (headers, URL), `params`, `query`, or state a
+ * `preBody` layer set. If a value genuinely requires the parsed body, it cannot
+ * be a `preBody` gate input — see {@link "./auto-ban.js".AutoBanOptions.keyGenerator},
+ * which falls back to a later phase for exactly that case.
+ *
+ * @since 1.0.0-rc.8
+ */
+export type IdentityGateContext = PreBodyContext<any>;
 /**
  * Lifecycle hooks fired around request handling. Hooks compose pipeline-style
  * — the global hooks (`AppOptions.hooks`) run first, then group hooks added