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

package/dist/adapters/node.js

@@ -874,9 +874,16 @@ class NodeWebSocketConnection {
             },
             onClose: (code, reason) => {
                 if (this.readyState === WS_READY_STATE.OPEN) {
-                    // Echo close per RFC 6455 §5.5.1.
+                    // Echo close per RFC 6455 §5.5.1 ("SHOULD use the same status code").
+                    // A peer that closed with an *empty* payload surfaces as the 1005
+                    // sentinel, which §7.4.1 forbids on the wire — echoing it produced a
+                    // CLOSE(1005) that a conforming peer (and this framework's own
+                    // decoder) must reject with 1002. An empty close is answered with an
+                    // empty close.
                     this.readyState = WS_READY_STATE.CLOSING;
-                    this._writeFrame(WS_OPCODE.CLOSE, encodeClosePayload(code, reason));
+                    this._writeFrame(WS_OPCODE.CLOSE, code === WS_CLOSE_CODE.NO_STATUS_RECEIVED
+                        ? new Uint8Array(0)
+                        : encodeClosePayload(code, reason));
                 }
                 this.readyState = WS_READY_STATE.CLOSED;
                 this._fireClose(code, reason);

package/dist/auto-ban.d.ts

@@ -11,7 +11,7 @@
  * The middleware is dependency-free and runtime-portable. It observes outgoing
  * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
  * status produced by *any* later middleware or handler, not just its own) and
- * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * enforces the ban in {@link "./types.js".Hooks.preBody}. The ban state
  * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
  * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
  * implementation for multi-instance deployments.
@@ -19,7 +19,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * One client's auto-ban bookkeeping. A record tracks the current strike count
  * inside the rolling strike window, when that window expires, the timestamp the
@@ -128,8 +128,22 @@ export interface AutoBanOptions {
      * Derive the client identity from `ctx`, or `undefined` to skip the request
      * (fail-open — never banned, never counted). Defaults to the proxy-header
      * resolver when {@link trustProxyHeaders} is set.
+     *
+     * Called first in `preBody`, where the gate is immune to mount order (see
+     * {@link IdentityGateContext}). If it returns `undefined` there, it is called
+     * again in `beforeHandle` — by then `session()` and other `beforeHandle` layers
+     * have populated `ctx.state`, so a generator keyed on a resolved session works
+     * rather than silently disabling the ban. Requests enforced by that second
+     * attempt are order-sensitive again, because `beforeHandle` is the phase a
+     * `responseCache()` hit short-circuits; key off headers, params or query where
+     * you can and the `preBody` pass handles it. Returning `undefined` from *both*
+     * still skips the request.
+     *
+     * `ctx.body` is not available in either phase — `preBody` runs before parsing,
+     * and the type reflects that. Derive the key from the request line, headers, or
+     * state instead.
      */
-    keyGenerator?: (ctx: BaseContext<any, any>) => string | undefined;
+    keyGenerator?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Read `X-Forwarded-For` / `X-Real-IP` in the default key generator. Off by
      * default because those headers are client-spoofable unless every request
@@ -152,6 +166,32 @@ export interface AutoBanOptions {
      * [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * What to do when the default key generator cannot resolve a forwarded
+     * identity — the request carried no `X-Forwarded-For`, or a chain shorter than
+     * {@link trustedHops} declares.
+     *
+     * - `"peer"` (default) — fall back to the immediate TCP peer address, in its
+     *   own `peer:` keyspace. The peer cannot be spoofed, and a request that
+     *   skipped the declared proxy chain came *from* that peer, so strikes are
+     *   attributed to the real origin of the traffic.
+     * - `"skip"` — never count and never ban such a request.
+     *
+     * `"peer"` is the default because `"skip"` is a silent bypass: an attacker who
+     * can reach the origin directly gets unlimited strikes simply by omitting a
+     * header. Choose `"skip"` only when unresolved requests are known-benign and
+     * arrive from a shared address — for instance a load balancer that does not
+     * always set `X-Forwarded-For`, where every such request would otherwise share
+     * the balancer's single `peer:` bucket and a few `401`s could ban the lot.
+     * Prefer fixing the proxy configuration over choosing `"skip"`.
+     *
+     * Ignored when {@link keyGenerator} is supplied — a custom generator owns its
+     * own unresolved-identity posture, and returning `undefined` from it still
+     * means skip.
+     *
+     * @since 1.0.0-rc.8
+     */
+    onUnresolvedIdentity?: "peer" | "skip";
     /** Pluggable ban store. Default: a shared in-memory store keyed by `groupId`. */
     store?: AutoBanStore;
     /**
@@ -201,8 +241,12 @@ export declare class MemoryAutoBanStore implements AutoBanStore {
  * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
  * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
  * a misconfiguration can never collapse every caller into one shared bucket and
- * ban the whole world at once. A request the key generator cannot attribute is
- * skipped (never counted, never banned).
+ * ban the whole world at once. When the default generator cannot resolve a
+ * forwarded identity — no `X-Forwarded-For`, or a chain shorter than
+ * {@link AutoBanOptions.trustedHops} declares — strikes are attributed to the
+ * unspoofable TCP peer instead of being discarded; see
+ * {@link AutoBanOptions.onUnresolvedIdentity}. A custom `keyGenerator` that
+ * returns `undefined` still skips the request.
  *
  * @example
  * ```ts

package/dist/auto-ban.js

@@ -11,7 +11,7 @@
  * The middleware is dependency-free and runtime-portable. It observes outgoing
  * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
  * status produced by *any* later middleware or handler, not just its own) and
- * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * enforces the ban in {@link "./types.js".Hooks.preBody}. The ban state
  * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
  * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
  * implementation for multi-instance deployments.
@@ -20,7 +20,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError, TooManyRequestsError } from "./errors.js";
-import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
+import { readRemoteAddress, resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 const DEFAULT_WINDOW_MS = 10 * 60_000;
 const DEFAULT_MAX_STRIKES = 5;
 const DEFAULT_BAN_MS = 15 * 60_000;
@@ -90,9 +90,32 @@ function assertPositiveInteger(name, value) {
  * trusted proxy hops from the right of `X-Forwarded-For` (falling back to
  * `X-Real-IP`). Reading the right side keeps the key spoof-resistant — see
  * {@link resolveForwardedClientIp}.
+ *
+ * When the forwarded chain cannot satisfy the declaration,
+ * {@link resolveForwardedClientIp} returns `undefined` — correct for *identity*,
+ * because such a request never traversed the declared topology. For *abuse
+ * accounting* that answer used to mean "skip", which handed an attacker unlimited
+ * strikes for free: reach the origin directly, past the CDN that appends the
+ * header, and every failed credential attempt went uncounted.
+ *
+ * So the fallback is the immediate TCP peer, prefixed to keep it in its own
+ * keyspace. The peer address cannot be spoofed — it is the socket actually
+ * talking to the adapter — and in exactly the direct-to-origin case that
+ * produced the bypass, the peer *is* the attacker, so accounting becomes precise
+ * rather than absent. Set `onUnresolvedIdentity: "skip"` to restore the previous
+ * behaviour; see {@link AutoBanOptions.onUnresolvedIdentity} for when that is
+ * the right call.
  */
-function forwardedKey(hops) {
-    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
+function forwardedKey(hops, peerFallback) {
+    return (ctx) => {
+        const forwarded = resolveForwardedClientIp(ctx.request, hops);
+        if (forwarded !== undefined)
+            return forwarded;
+        if (!peerFallback)
+            return undefined;
+        const peer = readRemoteAddress(ctx);
+        return peer === undefined ? undefined : `peer:${peer}`;
+    };
 }
 /**
  * Adaptive, escalating, decaying auto-ban middleware (fail2ban-style). Counts
@@ -103,8 +126,12 @@ function forwardedKey(hops) {
  * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
  * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
  * a misconfiguration can never collapse every caller into one shared bucket and
- * ban the whole world at once. A request the key generator cannot attribute is
- * skipped (never counted, never banned).
+ * ban the whole world at once. When the default generator cannot resolve a
+ * forwarded identity — no `X-Forwarded-For`, or a chain shorter than
+ * {@link AutoBanOptions.trustedHops} declares — strikes are attributed to the
+ * unspoofable TCP peer instead of being discarded; see
+ * {@link AutoBanOptions.onUnresolvedIdentity}. A custom `keyGenerator` that
+ * returns `undefined` still skips the request.
  *
  * @example
  * ```ts
@@ -150,12 +177,16 @@ export function autoBan(opts = {}) {
     }
     const watch = new Set(watchStatuses);
     const hops = resolveForwardedTrust("autoBan()", opts);
+    const onUnresolved = opts.onUnresolvedIdentity ?? "peer";
+    if (onUnresolved !== "peer" && onUnresolved !== "skip") {
+        throw new Error(`autoBan(): onUnresolvedIdentity must be "peer" or "skip"; got ${String(onUnresolved)}.`);
+    }
     let keyOf;
     if (opts.keyGenerator) {
         keyOf = opts.keyGenerator;
     }
     else if (hops !== undefined) {
-        keyOf = forwardedKey(hops);
+        keyOf = forwardedKey(hops, onUnresolved === "peer");
     }
     else {
         throw new Error("autoBan(): provide keyGenerator, trustedHops, or set trustProxyHeaders so clients can be identified; " +
@@ -175,23 +206,40 @@ export function autoBan(opts = {}) {
         store = shared;
     }
     const prefix = `${groupId}:`;
-    return {
-        async beforeHandle(ctx) {
-            const identity = keyOf(ctx);
-            if (identity === undefined)
-                return undefined;
-            const key = `${prefix}${identity}`;
-            const state = ctx.state;
-            state[STATE_KEY] = key;
-            const record = await store.get(key);
-            const now = Date.now();
-            if (record && record.bannedUntilMs > now) {
-                state[STATE_REJECTED] = true;
-                if (banStatus === 403)
-                    throw new ForbiddenError(message);
-                const retry = Math.ceil((record.bannedUntilMs - now) / 1000);
-                throw new TooManyRequestsError(retryAfter ? retry : undefined);
-            }
+    /**
+     * Resolve the identity, stash the key for `onSend`, and reject an active ban.
+     *
+     * Shared by the `preBody` gate and the `beforeHandle` fallback below so both
+     * phases enforce identically. Returns `true` once an identity was found, so
+     * the fallback knows whether `preBody` already handled the request.
+     */
+    const enforce = async (ctx) => {
+        const identity = keyOf(ctx);
+        if (identity === undefined)
+            return false;
+        const key = `${prefix}${identity}`;
+        const state = ctx.state;
+        state[STATE_KEY] = key;
+        const record = await store.get(key);
+        const now = Date.now();
+        if (record && record.bannedUntilMs > now) {
+            state[STATE_REJECTED] = true;
+            if (banStatus === 403)
+                throw new ForbiddenError(message);
+            const retry = Math.ceil((record.bannedUntilMs - now) / 1000);
+            throw new TooManyRequestsError(retryAfter ? retry : undefined);
+        }
+        return true;
+    };
+    const hooks = {
+        // `preBody`, not `beforeHandle`: the ban check must not be preemptable by an
+        // earlier `beforeHandle` middleware that short-circuits — a
+        // `responseCache()` HIT mounted above it would serve a banned client the
+        // cached body, so the ban would only ever apply to uncached routes.
+        // `preBody` always runs before any `beforeHandle`. Strike accounting stays in
+        // `onSend`, which observes the final status either way.
+        async preBody(ctx) {
+            await enforce(ctx);
             return undefined;
         },
         async onSend(res, ctx) {
@@ -227,4 +275,31 @@ export function autoBan(opts = {}) {
             return undefined;
         },
     };
+    // A custom `keyGenerator` may legitimately be unable to answer in `preBody` —
+    // typically because it reads state a `beforeHandle` layer resolves, such as
+    // `session()`. Without a second attempt that request gets no identity, so
+    // `onSend` finds no key and records no strike: the ban silently never arms.
+    // That is a worse failure than the ordering hazard the phase move closed, so
+    // retry in `beforeHandle` when, and only when, `preBody` came up empty.
+    //
+    // The default forwarded resolver never needs this — `onUnresolvedIdentity`
+    // already falls back to the TCP peer — so the hook is registered only for a
+    // custom generator and the common path pays nothing.
+    //
+    // Residual, deliberately accepted: a request enforced by this fallback IS
+    // order-sensitive again, because `beforeHandle` is the phase a
+    // `responseCache()` hit short-circuits. It applies solely to requests whose
+    // identity could not be resolved earlier, and enforcing late beats not
+    // enforcing at all. Resolve identity from headers/params/query where you can
+    // and `preBody` handles it, immune to mount order.
+    if (opts.keyGenerator) {
+        hooks.beforeHandle = async (ctx) => {
+            const state = ctx.state;
+            if (state[STATE_KEY] !== undefined)
+                return undefined; // preBody had it
+            await enforce(ctx);
+            return undefined;
+        };
+    }
+    return hooks;
 }

package/dist/bot-guard.d.ts

@@ -35,7 +35,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Pluggable DNS resolver used to verify declared crawlers. The default
  * implementation lazily imports `node:dns/promises`; provide your own on
@@ -150,7 +150,7 @@ export interface BotGuardOptions {
     /**
      * Custom client-IP resolver. Overrides {@link BotGuardOptions.trustProxyHeaders}.
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Custom DNS resolver for crawler verification. Defaults to a lazy
      * `node:dns/promises`-backed resolver.

package/dist/bot-guard.js

@@ -260,7 +260,12 @@ export function botGuard(opts = {}) {
             throw new ForbiddenError(message);
     };
     return {
-        async beforeHandle(ctx) {
+        // `preBody`, not `beforeHandle`: a bot gate that short-circuits from
+        // `beforeHandle` loses to any earlier `beforeHandle` middleware that returns
+        // a Response first — a `responseCache()` HIT mounted above it would hand a
+        // blocked scraper the cached body. `preBody` always precedes `beforeHandle`,
+        // so the gate holds regardless of mount order.
+        async preBody(ctx) {
             const ua = ctx.request.headers.get("user-agent") ?? "";
             // Allowlist wins over every other rule.
             if (allowed.length > 0 && matchesUserAgent(ua, allowed))

package/dist/geo-block.d.ts

@@ -24,7 +24,7 @@
  * @module
  * @since 0.37.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Why a request was (or would have been) blocked by {@link geoBlock}.
  *
@@ -57,7 +57,7 @@ export interface GeoBlockDecision {
  *
  * @since 0.37.0
  */
-export type CountryFromContext = (ctx: BaseContext<any, any>) => string | undefined | null | Promise<string | undefined | null>;
+export type CountryFromContext = (ctx: IdentityGateContext) => string | undefined | null | Promise<string | undefined | null>;
 /**
  * Operator-supplied IP → country lookup (e.g. a MaxMind reader). Return
  * `undefined`/`null`/`""` when the IP cannot be mapped to a country.
@@ -110,7 +110,7 @@ export interface GeoBlockOptions {
      * default Daloy fails closed because Web-standard `Request` objects do not
      * expose the peer address. Ignored when `resolveCountry` is used.
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Read `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Defaults
      * to `false` because those headers are client-spoofable unless every

package/dist/geo-block.js

@@ -107,7 +107,13 @@ export function geoBlock(opts) {
     const hops = resolveForwardedTrust("geoBlock()", opts);
     const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
     return {
-        async beforeHandle(ctx) {
+        // Runs in `preBody`, not `beforeHandle`. A `beforeHandle` hook that returns
+        // a Response ends the chain, so a country gate in that phase is preempted by
+        // any earlier `beforeHandle` middleware that short-circuits — a
+        // `responseCache()` HIT above it would serve a denied country the cached
+        // body. `preBody` always precedes `beforeHandle`, which makes the gate
+        // immune to mount order. See {@link geoBlock}'s security note.
+        async preBody(ctx) {
             let ip;
             let rawCountry;
             if (resolveCountry) {

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:

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,20 +226,69 @@ 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 }));
@@ -252,6 +342,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;
@@ -291,6 +382,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();

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:91539bfb-7f26-5f45-8628-f7951991c7ca",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-29T20:03:05.244Z",
+    "timestamp": "2026-07-30T16:25:43.763Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.7"
+        "version": "1.0.0-rc.8"
       }
     ],
     "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.8",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.7",
+      "version": "1.0.0-rc.8",
       "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.8",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.7",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.8",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.7",
+        "version": "1.0.0-rc.8",
         "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.8",
       "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.8",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.8-91539bfb-7f26-5f45-8628-f7951991c7ca",
   "creationInfo": {
-    "created": "2026-07-29T20:03:05.244Z",
+    "created": "2026-07-30T16:25:43.763Z",
     "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.8",
       "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.8"
         }
       ]
     }

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

package/dist/waf.js

@@ -188,15 +188,32 @@ const MAX_DECODE_PASSES = 2;
  */
 const CONTROL_CHAR_PROBE = /[\u0000-\u0008\u000e-\u001f\u007f]/;
 const CONTROL_CHAR_GLOBAL = /[\u0000-\u0008\u000e-\u001f\u007f]/g;
+/**
+ * Non-ASCII probe used to skip {@link String.prototype.normalize} on the pure
+ * ASCII hot path. Fullwidth Latin (U+FF01–U+FF5E), compatibility ideographs,
+ * and other NFKC-collapsible code points only appear when this matches.
+ *
+ * Hoisted so the hot path neither re-creates the RegExp nor pays a
+ * literal-evaluation cost per inspected value.
+ */
+const NON_ASCII_PROBE = /[^\x00-\x7F]/;
 /**
  * Expand a single inbound string into the variants the WAF should scan.
  *
  * Includes the raw value, up to {@link MAX_DECODE_PASSES} percent-decodes,
  * a `+`→space form (URLSearchParams parity), a SQL-comment-stripped
  * form so comment-split keywords (e.g. OR wrapped in block comments) score
- * the same as the whitespace-separated form, and a control-character→space
+ * the same as the whitespace-separated form, a control-character→space
  * form so embedded NUL / escape bytes cannot split keywords past the
- * whitespace-anchored signatures (e.g. `1'%00OR%001=1` → `1' OR 1=1`).
+ * whitespace-anchored signatures (e.g. `1'%00OR%001=1` → `1' OR 1=1`), and
+ * an NFKC-normalized form so fullwidth / compatibility-homoglyph keywords
+ * (e.g. `ｕｎｉｏｎ ｓｅｌｅｃｔ`) score the same as their ASCII counterparts.
+ *
+ * The NFKC fold is applied to the decode chain *before* the `+` / comment /
+ * control-character passes, and its output joins that chain, so the transforms
+ * **compose**: a payload mixing homoglyphs with comment- or NUL-splitting
+ * (`＇%00ＯＲ%00＇１＇＝＇１`) still converges on the ASCII form the signatures
+ * anchor on. Closing each evasion only in isolation leaves the combination open.
  *
  * Scanning variants is pure defense-in-depth: the handler still receives
  * whatever the framework's single-decode path produced. Each variant is
@@ -228,6 +245,25 @@ function inspectionVariants(value, maxValueLength) {
     }
     // Snapshot before secondary transforms so we only expand the decode chain.
     const decodedChain = out.slice();
+    // Fold compatibility characters FIRST, and extend the chain with the folded
+    // forms, so the secondary transforms below run on them too. Order matters:
+    // pushing the NFKC form after the loop (or without extending `decodedChain`)
+    // leaves each evasion closed only in isolation, and composing two of them
+    // reopens the hole — `＇%00ＯＲ%00＇１＇＝＇１` folds to a NUL-split ASCII
+    // tautology that the control-char pass would catch, and control-strips to a
+    // fullwidth tautology that the fold would catch, but neither variant is ever
+    // subjected to the other transform. Extending the chain makes the passes
+    // compose, so any combination of fold + decode + comment/control/`+`
+    // splitting converges on the same ASCII form the signatures anchor on.
+    for (const v of out.slice()) {
+        if (NON_ASCII_PROBE.test(v)) {
+            const nfkc = v.normalize("NFKC");
+            if (nfkc !== v) {
+                push(nfkc);
+                decodedChain.push(nfkc);
+            }
+        }
+    }
     for (const v of decodedChain) {
         if (v.includes("+"))
             push(v.replace(/\+/g, " "));

package/dist/websocket.d.ts

@@ -20,13 +20,24 @@ export declare const WS_OPCODE: {
     readonly PING: 9;
     readonly PONG: 10;
 };
-/** Common RFC 6455 / IANA close codes. */
+/**
+ * Common RFC 6455 / IANA close codes.
+ *
+ * `NO_STATUS_RECEIVED` (1005) and `ABNORMAL_CLOSURE` (1006) are **receive-only
+ * sentinels**: RFC 6455 §7.4.1 reserves them for reporting a local condition to
+ * the application and forbids them in a CLOSE frame on the wire. Passing either
+ * to `close()` or {@link encodeClosePayload} throws
+ * {@link WebSocketProtocolError} — to close with no status code, send an empty
+ * payload instead.
+ */
 export declare const WS_CLOSE_CODE: {
     readonly NORMAL_CLOSURE: 1000;
     readonly GOING_AWAY: 1001;
     readonly PROTOCOL_ERROR: 1002;
     readonly UNSUPPORTED_DATA: 1003;
+    /** Receive-only sentinel — never send this on the wire. */
     readonly NO_STATUS_RECEIVED: 1005;
+    /** Receive-only sentinel — never send this on the wire. */
     readonly ABNORMAL_CLOSURE: 1006;
     readonly INVALID_PAYLOAD: 1007;
     readonly POLICY_VIOLATION: 1008;
@@ -479,13 +490,37 @@ export declare function encodeFrame(opts: {
     payload?: Uint8Array;
     mask?: boolean;
 }): Uint8Array;
+/**
+ * Whether `code` may legally appear in a CLOSE frame on the wire per
+ * RFC 6455 §7.1.6 / §7.4.
+ *
+ * Valid: `1000`–`1014` from the registered range, minus the three codes
+ * §7.4.1 reserves for local reporting only (`1004` unassigned, `1005`
+ * "no status received", `1006` "abnormal closure"), plus the `3000`–`4999`
+ * library/application range. Everything else — `0`–`999`, `1015`+, and all of
+ * `2000`–`2999` — is a protocol violation.
+ *
+ * Used on both sides of the codec so the framework can never *emit* a code it
+ * would reject on receipt.
+ *
+ * @param code - Candidate close status code.
+ * @returns `true` when the code is legal in a wire CLOSE frame.
+ * @since 1.0.0-rc.8
+ */
+export declare function isValidWireCloseCode(code: number): boolean;
 /**
  * Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason).
  *
- * @param code - RFC 6455 close status code, written big-endian.
+ * @param code - RFC 6455 close status code, written big-endian. Must be legal
+ *   on the wire — see {@link isValidWireCloseCode}. To close with *no* status
+ *   code, send an empty payload rather than passing `1005`.
  * @param reason - Optional human-readable reason. Defaults to `""`.
  * @returns The 2+N byte close payload.
- * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes.
+ * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes, or
+ *   when `code` is not valid on the wire. Validating here as well as in
+ *   {@link decodeClosePayload} keeps the codec symmetric: without it the
+ *   framework could emit a frame its own decoder — and any conforming peer —
+ *   must reject with `1002`.
  */
 export declare function encodeClosePayload(code: number, reason?: string): Uint8Array;
 /**
@@ -493,8 +528,16 @@ export declare function encodeClosePayload(code: number, reason?: string): Uint8
  *
  * @param payload - Unmasked close-frame payload bytes.
  * @returns The close `code` and decoded UTF-8 `reason`.
- * @throws WebSocketProtocolError when the payload is exactly 1 byte or the
- *   reason is not valid UTF-8.
+ * @throws WebSocketProtocolError when the payload is exactly 1 byte, the
+ *   reason is not valid UTF-8, or the status code is not valid on the wire —
+ *   see {@link isValidWireCloseCode}. Without this check an endpoint would
+ *   echo an attacker-supplied invalid code (e.g. 999) back in its own CLOSE
+ *   frame instead of failing the connection with a 1002 protocol error.
+ *
+ * Note the asymmetry in the empty-payload case: a peer that closes with no
+ * status code yields the `1005` *sentinel*, which is deliberately not legal to
+ * send back. An endpoint echoing that close must reply with an empty payload,
+ * not with `1005`.
  */
 export declare function decodeClosePayload(payload: Uint8Array): {
     code: number;

package/dist/websocket.js

@@ -53,13 +53,24 @@ export const WS_OPCODE = {
     PING: 0x9,
     PONG: 0xa,
 };
-/** Common RFC 6455 / IANA close codes. */
+/**
+ * Common RFC 6455 / IANA close codes.
+ *
+ * `NO_STATUS_RECEIVED` (1005) and `ABNORMAL_CLOSURE` (1006) are **receive-only
+ * sentinels**: RFC 6455 §7.4.1 reserves them for reporting a local condition to
+ * the application and forbids them in a CLOSE frame on the wire. Passing either
+ * to `close()` or {@link encodeClosePayload} throws
+ * {@link WebSocketProtocolError} — to close with no status code, send an empty
+ * payload instead.
+ */
 export const WS_CLOSE_CODE = {
     NORMAL_CLOSURE: 1000,
     GOING_AWAY: 1001,
     PROTOCOL_ERROR: 1002,
     UNSUPPORTED_DATA: 1003,
+    /** Receive-only sentinel — never send this on the wire. */
     NO_STATUS_RECEIVED: 1005,
+    /** Receive-only sentinel — never send this on the wire. */
     ABNORMAL_CLOSURE: 1006,
     INVALID_PAYLOAD: 1007,
     POLICY_VIOLATION: 1008,
@@ -667,15 +678,45 @@ export function encodeFrame(opts) {
     }
     return out;
 }
+/**
+ * Whether `code` may legally appear in a CLOSE frame on the wire per
+ * RFC 6455 §7.1.6 / §7.4.
+ *
+ * Valid: `1000`–`1014` from the registered range, minus the three codes
+ * §7.4.1 reserves for local reporting only (`1004` unassigned, `1005`
+ * "no status received", `1006` "abnormal closure"), plus the `3000`–`4999`
+ * library/application range. Everything else — `0`–`999`, `1015`+, and all of
+ * `2000`–`2999` — is a protocol violation.
+ *
+ * Used on both sides of the codec so the framework can never *emit* a code it
+ * would reject on receipt.
+ *
+ * @param code - Candidate close status code.
+ * @returns `true` when the code is legal in a wire CLOSE frame.
+ * @since 1.0.0-rc.8
+ */
+export function isValidWireCloseCode(code) {
+    return ((code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) ||
+        (code >= 3000 && code <= 4999));
+}
 /**
  * Encode a CLOSE frame payload (`uint16 code` + optional UTF-8 reason).
  *
- * @param code - RFC 6455 close status code, written big-endian.
+ * @param code - RFC 6455 close status code, written big-endian. Must be legal
+ *   on the wire — see {@link isValidWireCloseCode}. To close with *no* status
+ *   code, send an empty payload rather than passing `1005`.
  * @param reason - Optional human-readable reason. Defaults to `""`.
  * @returns The 2+N byte close payload.
- * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes.
+ * @throws WebSocketProtocolError when the encoded reason exceeds 123 bytes, or
+ *   when `code` is not valid on the wire. Validating here as well as in
+ *   {@link decodeClosePayload} keeps the codec symmetric: without it the
+ *   framework could emit a frame its own decoder — and any conforming peer —
+ *   must reject with `1002`.
  */
 export function encodeClosePayload(code, reason = "") {
+    if (!isValidWireCloseCode(code)) {
+        throw new WebSocketProtocolError(`Invalid close status code ${code}`);
+    }
     const reasonBytes = enc.encode(reason);
     if (reasonBytes.length > WS_MAX_CONTROL_PAYLOAD - 2) {
         throw new WebSocketProtocolError("Close reason exceeds 123 bytes");
@@ -691,8 +732,16 @@ export function encodeClosePayload(code, reason = "") {
  *
  * @param payload - Unmasked close-frame payload bytes.
  * @returns The close `code` and decoded UTF-8 `reason`.
- * @throws WebSocketProtocolError when the payload is exactly 1 byte or the
- *   reason is not valid UTF-8.
+ * @throws WebSocketProtocolError when the payload is exactly 1 byte, the
+ *   reason is not valid UTF-8, or the status code is not valid on the wire —
+ *   see {@link isValidWireCloseCode}. Without this check an endpoint would
+ *   echo an attacker-supplied invalid code (e.g. 999) back in its own CLOSE
+ *   frame instead of failing the connection with a 1002 protocol error.
+ *
+ * Note the asymmetry in the empty-payload case: a peer that closes with no
+ * status code yields the `1005` *sentinel*, which is deliberately not legal to
+ * send back. An endpoint echoing that close must reply with an empty payload,
+ * not with `1005`.
  */
 export function decodeClosePayload(payload) {
     if (payload.length === 0)
@@ -700,6 +749,9 @@ export function decodeClosePayload(payload) {
     if (payload.length === 1)
         throw new WebSocketProtocolError("Close payload must be empty or ≥2 bytes");
     const code = (payload[0] << 8) | payload[1];
+    if (!isValidWireCloseCode(code)) {
+        throw new WebSocketProtocolError(`Invalid close status code ${code}`);
+    }
     const reason = new TextDecoder("utf-8", { fatal: true }).decode(payload.subarray(2));
     return { code, reason };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-rc.7",
-  "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.",
+  "version": "1.0.0-rc.8",
+  "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 \u2014 distributed via pnpm.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -258,7 +258,7 @@
     "red-team:live": "node --import tsx red-team-live/run.ts",
     "coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=90 --test-coverage-functions=90 tests/**/*.test.ts",
     "coverage:branches": "tsc -p tsconfig.coverage.json && node --test --experimental-test-coverage --test-coverage-include='dist-coverage/src/**' --test-coverage-branches=92 dist-coverage/tests/**/*.test.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.typetest.json && tsc -p tests/tsconfig.json --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.typetest.json && tsc -p tests/tsconfig.json --noEmit && tsc -p red-team-live/tsconfig.json --noEmit",
     "typecheck:tests": "tsc -p tests/tsconfig.json --noEmit",
     "format": "prettier --write .",
     "gen:openapi": "node --import tsx scripts/dump-openapi.ts",
@@ -297,10 +297,12 @@
     "verify:sbom": "node --import tsx scripts/verify-sbom.ts",
     "verify:breaking-changes": "node --import tsx scripts/verify-breaking-changes.ts",
     "verify:docs-links": "node --import tsx scripts/verify-docs-links.ts",
+    "verify:jsr-packaging": "npx --yes jsr publish --dry-run --allow-dirty",
     "scan:staged-secrets": "node --import tsx scripts/scan-staged-secrets.ts",
     "hooks:install": "node --import tsx scripts/install-git-hooks.ts",
     "audit": "pnpm audit --prod",
-    "prepublishOnly": "pnpm build && pnpm gen:sbom"
+    "prepublishOnly": "pnpm build && pnpm gen:sbom",
+    "typecheck:red-team-live": "tsc -p red-team-live/tsconfig.json --noEmit"
   },
   "files": [
     "dist",