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

package/dist/adapters/node.js

@@ -4,7 +4,7 @@
  */
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, DALOY_REQUEST_BODY_SOLICIT, } from "../app.js";
 import { BadRequestError } from "../errors.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { setConnInfo } from "../conn-info.js";
@@ -34,15 +34,12 @@ export function serve(app, opts = {}) {
     const connectionsCheckingInterval = connectionTimeoutMs > 0
         ? Math.max(1_000, Math.min(5_000, Math.floor(connectionTimeoutMs / 2)))
         : undefined;
-    const server = createServer({
-        maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024,
-        ...(connectionsCheckingInterval !== undefined ? { connectionsCheckingInterval } : {}),
-    }, (req, res) => {
+    const handleRequest = (req, res, onBodyPull) => {
         // GET/HEAD: no body work, dispatch directly. Keep this first so the GET
         // hot path doesn't pay for any of the buffering bookkeeping below.
         const method = req.method;
         if (method === "GET" || method === "HEAD" || method === undefined) {
-            dispatchToApp(app, req, res, trustProxy, undefined);
+            dispatchToApp(app, req, res, trustProxy, undefined, onBodyPull);
             return;
         }
         // Refuse Fetch-forbidden methods (CONNECT/TRACE/TRACK) before building a
@@ -61,10 +58,60 @@ export function serve(app, opts = {}) {
         const cl = req.headers["content-length"];
         const n = cl ? Number(cl) : NaN;
         if (Number.isFinite(n) && n >= 0 && n <= bufferedBodyMaxBytes) {
-            bufferRequestBody(req, n).then((bytes) => dispatchToApp(app, req, res, trustProxy, bytes), (e) => writeAdapterError(res, e));
+            bufferRequestBody(req, n).then((bytes) => dispatchToApp(app, req, res, trustProxy, bytes, onBodyPull), (e) => writeAdapterError(res, e));
             return;
         }
-        dispatchToApp(app, req, res, trustProxy, undefined);
+        dispatchToApp(app, req, res, trustProxy, undefined, onBodyPull);
+    };
+    const server = createServer({
+        maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024,
+        ...(connectionsCheckingInterval !== undefined ? { connectionsCheckingInterval } : {}),
+    }, handleRequest);
+    // `Expect: 100-continue`: hold the interim response until the framework
+    // actually reaches for the body.
+    //
+    // Node's default is to answer `100 Continue` for anyone who asks, which
+    // solicits a body the framework may be about to refuse outright. A route with
+    // a request-body schema and a declared `Content-Length` over `bodyLimitBytes`
+    // is rejected by `readBodyLimited` *before* it reads a byte, so the interim
+    // `100` invited megabytes that could only ever be discarded — measured as
+    // `100` then `413` on the wire.
+    //
+    // Deferring to the first actual read makes the framework's own read decision
+    // the predicate, and that is what keeps this honest. An earlier attempt
+    // refused at header time against `bodyLimitBytes` directly, but that limit is
+    // only enforced where a body is *parsed*, so a route that declares no body
+    // schema never applies it: the same request answered `413` with `Expect` and
+    // `200` without it. `Expect` is a hint about when to send the body (RFC 9110
+    // §10.1.1), so it must never change the outcome — only when the client
+    // learns it. Keying off the read keeps the two paths in agreement by
+    // construction rather than by test coverage.
+    server.on("checkContinue", (req, res) => {
+        const cl = req.headers["content-length"];
+        const n = cl ? Number(cl) : NaN;
+        if (Number.isFinite(n) && n >= 0 && n <= bufferedBodyMaxBytes) {
+            // Small declared body: `handleRequest` buffers it eagerly, before dispatch,
+            // so there is no later read to key off. It is also under the buffer cap,
+            // so soliciting it immediately costs nothing worth deferring.
+            res.writeContinue();
+            handleRequest(req, res);
+            return;
+        }
+        // Streaming path (no `Content-Length`, or one above the buffer cap): answer
+        // the interim `100` the first time the framework pulls the body stream.
+        //
+        // The socket's own `resume` event is deliberately NOT the trigger. Node also
+        // resumes the stream on a microtask when it drains a body nobody read, which
+        // races the response: measured, that fired the `100` even for a request whose
+        // body was never wanted, and beat the `413` to the wire. The consumer's first
+        // `pull` is the only signal that means "the framework wants these bytes".
+        let sent = false;
+        handleRequest(req, res, () => {
+            if (sent || res.headersSent || res.writableEnded)
+                return;
+            sent = true;
+            res.writeContinue();
+        });
     });
     server.requestTimeout = connectionTimeoutMs;
     server.headersTimeout = connectionTimeoutMs;
@@ -148,10 +195,10 @@ export function serve(app, opts = {}) {
  * on body size remains `App.bodyLimitBytes`.
  */
 const DEFAULT_BUFFERED_BODY_MAX_BYTES = 256 * 1024;
-function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
+function dispatchToApp(app, req, res, trustProxy, bufferedBody, onBodyPull) {
     let request;
     try {
-        request = toWebRequest(req, trustProxy, bufferedBody);
+        request = toWebRequest(req, trustProxy, bufferedBody, onBodyPull);
     }
     catch (e) {
         writeAdapterError(res, e);
@@ -537,7 +584,11 @@ Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
 // construction for requests dispatched through this shim. Set once on the
 // prototype: zero per-request cost.
 LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
-function toWebRequest(req, trustProxy, bufferedBody) {
+function toWebRequest(req, trustProxy, bufferedBody, onBodyPull) {
+    // `onBodyPull` is attached to the finished Request below rather than wrapping
+    // the body stream: undici pulls a streaming body during `new Request(...)`,
+    // so a stream-level hook fired at construction — before the framework had
+    // decided anything — and re-solicited bodies it went on to refuse.
     const reqHeaders = req.headers;
     const forwardedHost = trustProxy ? firstHeader(reqHeaders["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? reqHeaders.host ?? "localhost";
@@ -588,12 +639,16 @@ function toWebRequest(req, trustProxy, bufferedBody) {
         req2[DALOY_REQUEST_RAW_BODY] = bufferedBody;
         return req2;
     }
-    return new Request(url, {
+    const streamed = new Request(url, {
         method,
         headers,
         body: Readable.toWeb(req),
         duplex: "half",
     });
+    if (onBodyPull !== undefined) {
+        streamed[DALOY_REQUEST_BODY_SOLICIT] = onBodyPull;
+    }
+    return streamed;
 }
 function firstHeader(v) {
     if (v === undefined)
@@ -874,9 +929,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/app.d.ts

@@ -793,6 +793,31 @@ export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
  * adapters can opt in; not part of the userland API surface.
  */
 export declare const DALOY_REQUEST_ABORT: unique symbol;
+/**
+ * Internal Symbol an adapter may set to a callback that the framework invokes
+ * immediately before it reads the request body — and only once it has decided
+ * the body is both wanted and within {@link AppOptions.bodyLimitBytes}.
+ *
+ * It exists for `Expect: 100-continue`. Node answers the interim `100` to
+ * anyone who asks, which solicits a body the framework may be about to refuse:
+ * a route with a body schema and a declared `Content-Length` over the limit is
+ * rejected before a byte is read, so the `100` invited megabytes that could
+ * only be discarded. The adapter defers its `writeContinue()` into this hook so
+ * the invitation tracks the framework's own decision.
+ *
+ * The framework's read decision has to be the trigger, because it is the only
+ * thing that makes the outcome independent of the `Expect` header. `Expect` is
+ * a hint about *when* to send the body (RFC 9110 §10.1.1); refusing at header
+ * time against `bodyLimitBytes` instead looks equivalent but is not, since that
+ * limit is only applied where a body is parsed — a route declaring no body
+ * schema never applies it, so the same request answered `413` with `Expect` and
+ * `200` without.
+ *
+ * Adapter-facing only; userland code should not depend on it.
+ *
+ * @since 1.0.0-rc.9
+ */
+export declare const DALOY_REQUEST_BODY_SOLICIT: unique symbol;
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node

package/dist/app.js

@@ -136,6 +136,8 @@ const MCP_ROUTE_MARKER = Symbol.for("daloyjs.mcp.route");
  */
 const RESPONSE_CACHE_HOOK_MARKER = Symbol.for("daloyjs.response-cache.hook");
 const TENANCY_HOOK_MARKER = Symbol.for("daloyjs.tenancy.hook");
+const IDEMPOTENCY_HOOK_MARKER = Symbol.for("daloyjs.idempotency.hook");
+const EARLY_REJECTION_MARKER = Symbol.for("daloyjs.middleware.earlyRejectionHooks");
 /**
  * Apply a topology-aware security preset on top of caller-supplied
  * options. Returns a new options object where preset defaults fill in
@@ -222,6 +224,31 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  * adapters can opt in; not part of the userland API surface.
  */
 export const DALOY_REQUEST_ABORT = Symbol.for("daloyjs.request.abort");
+/**
+ * Internal Symbol an adapter may set to a callback that the framework invokes
+ * immediately before it reads the request body — and only once it has decided
+ * the body is both wanted and within {@link AppOptions.bodyLimitBytes}.
+ *
+ * It exists for `Expect: 100-continue`. Node answers the interim `100` to
+ * anyone who asks, which solicits a body the framework may be about to refuse:
+ * a route with a body schema and a declared `Content-Length` over the limit is
+ * rejected before a byte is read, so the `100` invited megabytes that could
+ * only be discarded. The adapter defers its `writeContinue()` into this hook so
+ * the invitation tracks the framework's own decision.
+ *
+ * The framework's read decision has to be the trigger, because it is the only
+ * thing that makes the outcome independent of the `Expect` header. `Expect` is
+ * a hint about *when* to send the body (RFC 9110 §10.1.1); refusing at header
+ * time against `bodyLimitBytes` instead looks equivalent but is not, since that
+ * limit is only applied where a body is parsed — a route declaring no body
+ * schema never applies it, so the same request answered `413` with `Expect` and
+ * `200` without.
+ *
+ * Adapter-facing only; userland code should not depend on it.
+ *
+ * @since 1.0.0-rc.9
+ */
+export const DALOY_REQUEST_BODY_SOLICIT = Symbol.for("daloyjs.request.bodySolicit");
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -1028,6 +1055,29 @@ export class App {
             this.bootGuard.error = err;
             throw err;
         }
+        // Guard 3b: a stored-response layer mounted ahead of a request budget.
+        // `responseCache()` and `idempotency()` both answer from `beforeHandle` and
+        // end the hook chain, and `rateLimit()` / `loginThrottle()` enforce from that
+        // same phase — so a limiter mounted behind either one never counts the
+        // requests it serves. Measured: `rateLimit({ max: 2 })` behind a cache or a
+        // replay admitted six of six. The budget silently becomes infinite for
+        // exactly the traffic that repeats most, which is what the limit was written
+        // for. Same shape as the responseCache-ahead-of-gates finding, and the reason
+        // the five network-identity gates moved to `preBody`; `rateLimit` cannot
+        // follow them there because its `keyGenerator` is caller-supplied and may
+        // read `ctx.state`, so the unsafe order is refused instead.
+        const replayBeforeBudget = this.routeSecurityMarkers.find((r) => r.replayBeforeBudget !== null);
+        if (replayBeforeBudget !== undefined && this.bootGuard.error === undefined) {
+            this.bootGuard.error = new Error(`Route ${replayBeforeBudget.method} ${replayBeforeBudget.path} runs ` +
+                `${replayBeforeBudget.replayBeforeBudget} before rateLimit() / loginThrottle() in its ` +
+                `effective hook chain. Both act from beforeHandle, so a cache hit or an idempotent ` +
+                `replay returns a response and ends the chain before the limiter counts the request — ` +
+                `the declared budget is never spent on repeat traffic and is effectively unlimited. ` +
+                `Register rateLimit() first — as a global hook (new App({ hooks: rateLimit(...) })) or ` +
+                `an earlier app.use(...) — so every request is counted before a stored response can ` +
+                `short-circuit it. See https://daloyjs.dev/docs/security/boot-guards.`);
+            throw this.bootGuard.error;
+        }
         // Guard 4: session() + state-changing route without csrf().
         if (this.options.csrf === "off")
             return;
@@ -3185,6 +3235,12 @@ function securityMarkersFromHooks(layers) {
     // to tell whether the cache reads state before tenancy has written it.
     let cacheIndex = -1;
     let tenancyIndex = -1;
+    // First stored-response layer of either kind, and the first request-budget
+    // layer. Only the earliest of each matters: if any replay precedes any budget
+    // hook, that budget is preemptable.
+    let replayIndex = -1;
+    let replayName = "";
+    let budgetIndex = -1;
     for (let i = 0; i < layers.length; i++) {
         const record = layers[i];
         if (record[SESSION_HOOK_MARKER] === true)
@@ -3197,12 +3253,25 @@ function securityMarkersFromHooks(layers) {
             cacheIndex = i;
         if (tenancyIndex === -1 && record[TENANCY_HOOK_MARKER] === true)
             tenancyIndex = i;
+        if (replayIndex === -1) {
+            if (record[RESPONSE_CACHE_HOOK_MARKER] === true) {
+                replayIndex = i;
+                replayName = "responseCache()";
+            }
+            else if (record[IDEMPOTENCY_HOOK_MARKER] === true) {
+                replayIndex = i;
+                replayName = "idempotency()";
+            }
+        }
+        if (budgetIndex === -1 && Array.isArray(record[EARLY_REJECTION_MARKER]))
+            budgetIndex = i;
     }
     return {
         hasSession,
         hasCsrf,
         hasAuth,
         cacheBeforeTenancy: cacheIndex !== -1 && tenancyIndex !== -1 && cacheIndex < tenancyIndex,
+        replayBeforeBudget: replayIndex !== -1 && budgetIndex !== -1 && replayIndex < budgetIndex ? replayName : null,
     };
 }
 function isStateChangingMethod(method) {
@@ -3718,6 +3787,21 @@ function validateContext(ctx, def, opts) {
         if (!allowed.some((a) => ct.includes(a))) {
             throw new UnsupportedMediaTypeError(ct || "(none)", allowed);
         }
+        // Refuse an over-limit *declared* length here, before soliciting the body.
+        // `readBodyLimited` already makes the identical check on the identical
+        // boundary, so this changes no outcome — it is load-bearing purely for
+        // ordering, so that an adapter deferring `Expect: 100-continue` (see
+        // {@link DALOY_REQUEST_BODY_SOLICIT}) never invites bytes this request was
+        // always going to be refused for. Kept below the content-type check so a
+        // wrong media type still answers `415` rather than `413`, as before.
+        const declared = request.headers.get("content-length");
+        if (declared !== null) {
+            const declaredBytes = Number(declared);
+            if (Number.isFinite(declaredBytes) && declaredBytes > opts.bodyLimitBytes) {
+                throw new PayloadTooLargeError(opts.bodyLimitBytes);
+            }
+        }
+        request[DALOY_REQUEST_BODY_SOLICIT]?.();
         const raw = readBody(request, ct, opts.bodyLimitBytes, opts.multipart, opts.jsonMaxKeys, opts.jsonMaxDepth);
         if (isPromiseLike(raw))
             return raw.then(validateBodyAndFinish);

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) {