@daloyjs/core 1.0.0-rc.4 → 1.0.0-rc.5

package/dist/adapters/node.js

@@ -4,8 +4,10 @@
  */
 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, } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
+import { BadRequestError } from "../errors.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
+import { setConnInfo } from "../conn-info.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
 /**
  * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
@@ -85,11 +87,23 @@ export function serve(app, opts = {}) {
         server.on("upgrade", (req, socket, head) => {
             wsSockets.add(socket);
             socket.on("close", () => wsSockets.delete(socket));
-            void handleUpgrade(app, req, socket, head, trustProxy);
+            // Safety net: a rejection here would otherwise be unhandled and, under
+            // the production crash-on-unhandledRejection posture, kill the process
+            // from a single malformed upgrade request.
+            handleUpgrade(app, req, socket, head, trustProxy).catch((err) => {
+                app.log.error({ err }, "WebSocket upgrade failed");
+                try {
+                    writeUpgradeError(socket, 400, "Bad Request");
+                }
+                catch {
+                    /* socket already closed */
+                }
+                socket.destroy();
+            });
         });
     }
-    const port = opts.port ?? 3000;
-    server.listen(port, opts.hostname ?? "0.0.0.0");
+    const requestedPort = opts.port ?? 3000;
+    server.listen(requestedPort, opts.hostname ?? "0.0.0.0");
     // Kill idle keep-alive sockets immediately when draining begins.
     // In-flight requests keep their socket because Node's
     // `closeIdleConnections()` is a no-op for sockets with an in-flight request.
@@ -115,7 +129,16 @@ export function serve(app, opts = {}) {
         process.once("SIGTERM", () => onSignal("SIGTERM"));
         process.once("SIGINT", () => onSignal("SIGINT"));
     }
-    return { server, port, close };
+    return {
+        server,
+        get port() {
+            const address = server.address();
+            return address !== null && typeof address === "object"
+                ? address.port
+                : requestedPort;
+        },
+        close,
+    };
 }
 /**
  * Default pre-buffer ceiling for the Node adapter. 256 KiB is a compromise:
@@ -135,6 +158,14 @@ function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
         writeAdapterError(res, e);
         return;
     }
+    // Fulfil the conn-info contract: the immediate TCP peer, so
+    // `getConnInfo` / `resolveClientIp` / `behindProxy` and WAF client-IP
+    // attribution work on Node. Never derived from spoofable headers.
+    setConnInfo(request, {
+        remoteAddress: req.socket.remoteAddress,
+        remotePort: req.socket.remotePort,
+        tls: req.socket.encrypted === true,
+    });
     attachClientCertificate(req, request);
     const responseOrPromise = app.fetch(request);
     if (responseOrPromise instanceof Promise) {
@@ -279,12 +310,15 @@ function writeMethodRefused(res) {
 }
 function writeAdapterError(res, e) {
     if (!res.headersSent) {
-        res.statusCode = 500;
+        const clientError = e instanceof BadRequestError;
+        res.statusCode = clientError ? 400 : 500;
         res.setHeader("content-type", "application/problem+json");
         res.end(JSON.stringify({
-            type: "https://daloyjs.dev/errors/internal",
-            title: "Internal Server Error",
-            status: 500,
+            type: clientError
+                ? "https://daloyjs.dev/errors/bad-request"
+                : "https://daloyjs.dev/errors/internal",
+            title: clientError ? "Bad Request" : "Internal Server Error",
+            status: clientError ? 400 : 500,
         }));
     }
     else {
@@ -307,9 +341,11 @@ function writeAdapterError(res, e) {
  * - `instanceof Request` holds (prototype chain is re-rooted onto
  *   `Request.prototype`), and every WHATWG method/getter is overridden here,
  *   so nothing hits undici's brand-checked prototype accessors.
- * - `signal` is an inert per-instance `AbortSignal`. This matches the real
- *   adapter behaviour today: the Node adapter never wires socket aborts into
- *   the request signal, so the signal never fires in either implementation.
+ * - `signal` is a lazily-created per-instance `AbortSignal`. The framework
+ *   aborts it (via the {@link DALOY_REQUEST_ABORT} hook) when the request
+ *   exceeds `requestTimeoutMs`, so a handler that forwards `ctx.request.signal`
+ *   to downstream `fetch`/DB calls sees them cancel on timeout. It is still NOT
+ *   wired to client socket-disconnect — that teardown never fires the signal.
  * - Passing this object directly to `fetch()` is not supported (undici
  *   brand-checks its input) — forward with `request.clone()` instead, which
  *   returns a real `Request`. This mirrors @hono/node-server's shim.
@@ -327,7 +363,7 @@ class LightRequest {
     #headers;
     #bodyBytes;
     #real;
-    #signal;
+    #controller;
     constructor(url, method, headers, bodyBytes) {
         this.#url = url;
         this.#method = method;
@@ -355,10 +391,22 @@ class LightRequest {
         return this.#headers;
     }
     get signal() {
-        // Inert, lazily created: the Node adapter has never wired socket
-        // teardown into the request signal, so a never-firing signal is
-        // behaviourally identical to the one a real `Request` would carry.
-        return (this.#signal ??= new AbortController().signal);
+        // Lazily created so only handlers that actually read `signal` pay for the
+        // controller. The framework aborts it via the DALOY_REQUEST_ABORT hook
+        // below when the request exceeds `requestTimeoutMs`; client
+        // socket-disconnect is not wired into it.
+        return (this.#controller ??= new AbortController()).signal;
+    }
+    /**
+     * Framework abort hook ({@link DALOY_REQUEST_ABORT}). Invoked by the core on
+     * request timeout so `ctx.request.signal` fires for cooperative teardown.
+     * A no-op when no handler ever read `signal` — there is no controller to
+     * abort and nothing observing it.
+     *
+     * @param reason - Abort reason surfaced on `signal.reason` (a `TimeoutError`).
+     */
+    [DALOY_REQUEST_ABORT](reason) {
+        this.#controller?.abort(reason);
     }
     get body() {
         return this.#materialize().body;
@@ -506,6 +554,13 @@ function toWebRequest(req, trustProxy, bufferedBody) {
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
     const url = `${proto}://${host}${normalizeRequestTarget(req.url)}`;
+    // Reject malformed Host / request-target combinations at the adapter
+    // boundary instead of letting the invalid URL propagate as a 500 later.
+    // URL.canParse applies WHATWG validation without allocating and immediately
+    // discarding a URL object on every request.
+    if (!URL.canParse(url)) {
+        throw new BadRequestError("Invalid request target or Host header");
+    }
     // Build headers from `rawHeaders` (a flat [k0,v0,k1,v1,...] array) instead
     // of the parsed `req.headers` object. This matches @hono/node-server's
     // `newHeadersFromIncoming`: one `new Headers([[k,v],...])` constructor
@@ -578,7 +633,21 @@ function normalizeRequestTarget(target) {
 }
 function sendWebResponse(res, out) {
     out.statusCode = res.status;
-    res.headers.forEach((v, k) => out.setHeader(k, v));
+    // `Headers.forEach` yields each `Set-Cookie` as a separate callback while
+    // `ServerResponse.setHeader` overwrites repeated keys — copying naively
+    // keeps only the LAST cookie (e.g. dropping the session cookie when
+    // `csrf()` also sets its token cookie). Collect them via `getSetCookie()`
+    // and set the array once so every cookie reaches the wire.
+    let hasSetCookie = false;
+    res.headers.forEach((v, k) => {
+        if (k === "set-cookie") {
+            hasSetCookie = true;
+            return;
+        }
+        out.setHeader(k, v);
+    });
+    if (hasSetCookie)
+        out.setHeader("set-cookie", res.headers.getSetCookie());
     // Fast-path: response was produced by serializeResult and carries the raw
     // body bytes via the DALOY_RAW_BODY Symbol. Skip arrayBuffer() and the
     // reader-loop microtask churn entirely for buffer-backed responses.
@@ -661,7 +730,18 @@ async function handleUpgrade(app, req, socket, head, trustProxy) {
         : undefined;
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
-    const url = new URL(`${proto}://${host}${req.url ?? "/"}`);
+    // A malformed `Host` header (e.g. containing a space) reaches this point:
+    // Node's HTTP parser accepts it and fires `upgrade`, but WHATWG URL
+    // parsing throws. Reject it as the client error it is instead of letting
+    // the throw escape the adapter.
+    let url;
+    try {
+        url = new URL(`${proto}://${host}${req.url ?? "/"}`);
+    }
+    catch {
+        writeUpgradeError(socket, 400, "Bad Request");
+        return;
+    }
     const match = app.webSocketRoutes.find(url.pathname);
     if (!match) {
         writeUpgradeError(socket, 404, "Not Found");
@@ -682,6 +762,11 @@ async function handleUpgrade(app, req, socket, head, trustProxy) {
         method: "GET",
         headers,
     });
+    setConnInfo(request, {
+        remoteAddress: req.socket.remoteAddress,
+        remotePort: req.socket.remotePort,
+        tls: req.socket.encrypted === true,
+    });
     const ctx = {
         request,
         params: match.params,

package/dist/app.d.ts

@@ -78,7 +78,12 @@ export interface AppOptions {
     bodyLimitBytes?: number;
     /** Reject requests whose Content-Type isn't in this allowlist (when a body schema is declared). */
     allowedContentTypes?: string[];
-    /** Per-request timeout in ms (handler + hooks). Default: 30000. Set 0 to disable. */
+    /**
+     * Per-request timeout in ms (handler + hooks). Default: 30000. Set 0 to
+     * disable. On timeout the framework aborts `ctx.request.signal` (cooperative
+     * cancellation of downstream I/O) and responds `408`; see
+     * {@link RequestTimeoutError}. It does not forcibly stop CPU-bound work.
+     */
     requestTimeoutMs?: number;
     /**
      * Maximum number of distinct request header fields accepted before the
@@ -771,6 +776,23 @@ export declare const DALOY_RAW_BODY: unique symbol;
  * so first-party adapters can opt in; not part of the userland API surface.
  */
 export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
+/**
+ * Internal Symbol an adapter sets (on its request shim) to expose the request's
+ * abort hook: a `(reason: unknown) => void` that aborts the `AbortController`
+ * backing `request.signal`. The core invokes it when a request exceeds
+ * {@link AppOptions.requestTimeoutMs} so a handler that forwarded
+ * `ctx.request.signal` to downstream I/O (`fetch`, a DB driver) sees those
+ * calls cancel — cooperative teardown, since single-threaded JS cannot preempt
+ * a running handler.
+ *
+ * The hook is invoked as a method on the request (`this` stays bound to the
+ * shim) so it can reach the shim's private controller. Absent on runtimes
+ * whose `Request.signal` is managed by the platform (Bun / Deno / Workers) and
+ * on direct `app.fetch()` callers, where {@link abortRequest} is a safe no-op
+ * and the timeout still resolves as a `408`. Module-public so first-party
+ * adapters can opt in; not part of the userland API surface.
+ */
+export declare const DALOY_REQUEST_ABORT: unique symbol;
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -1687,8 +1709,8 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * "draining" signal); then the app waits up to `timeoutMs` for in-flight
      * requests to settle; finally, {@link App.onClose} cleanups run.
      *
-     * Both Node and Bun adapters call this automatically on `SIGINT` / `SIGTERM`.
-     * Call it manually from custom runtimes or integration tests.
+     * The Node, Bun, and Deno adapters call this automatically on `SIGINT` /
+     * `SIGTERM`. Call it manually from custom runtimes or integration tests.
      *
      * @param timeoutMs - Maximum time (ms) to wait for inflight requests. Default: `10_000`.
      * @param reason - Optional human-readable reason forwarded to listeners.

package/dist/app.js

@@ -1,8 +1,8 @@
 import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
-import { readBodyLimited, safeJsonParseLimited, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
-import { createLogger, noopLogger } from "./logger.js";
+import { readBodyLimited, safeJsonParseLimited, randomId, assertInboundHeaderGuards, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
+import { createLogger, noopLogger, sanitizeUrlForLog } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { isSchemaValidatedResponse } from "./internal-response.js";
 import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
@@ -196,6 +196,23 @@ export const DALOY_RAW_BODY = Symbol.for("daloyjs.response.rawBody");
  * so first-party adapters can opt in; not part of the userland API surface.
  */
 export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
+/**
+ * Internal Symbol an adapter sets (on its request shim) to expose the request's
+ * abort hook: a `(reason: unknown) => void` that aborts the `AbortController`
+ * backing `request.signal`. The core invokes it when a request exceeds
+ * {@link AppOptions.requestTimeoutMs} so a handler that forwarded
+ * `ctx.request.signal` to downstream I/O (`fetch`, a DB driver) sees those
+ * calls cancel — cooperative teardown, since single-threaded JS cannot preempt
+ * a running handler.
+ *
+ * The hook is invoked as a method on the request (`this` stays bound to the
+ * shim) so it can reach the shim's private controller. Absent on runtimes
+ * whose `Request.signal` is managed by the platform (Bun / Deno / Workers) and
+ * on direct `app.fetch()` callers, where {@link abortRequest} is a safe no-op
+ * and the timeout still resolves as a `408`. Module-public so first-party
+ * adapters can opt in; not part of the userland API surface.
+ */
+export const DALOY_REQUEST_ABORT = Symbol.for("daloyjs.request.abort");
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -1701,6 +1718,7 @@ export class App {
         }));
         this._coldPathHooksCache = undefined;
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
             path,
@@ -1711,7 +1729,7 @@ export class App {
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1821,6 +1839,7 @@ export class App {
                 `to acknowledge that this probe is reachable without credentials.`);
         }
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
             path,
@@ -1831,7 +1850,7 @@ export class App {
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1895,6 +1914,7 @@ export class App {
         }
         const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const buckets = rateLimitConfig ? new Map() : null;
+        const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         const log = this.log;
         // Only log report bodies when explicitly enabled. In
         // production this is opt-in; in development the body is included by
@@ -1908,7 +1928,7 @@ export class App {
             summary: "CSP / Reporting API violation receiver",
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request);
+                    const key = healthRouteKey(request, trustProxyHeaders);
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1944,7 +1964,7 @@ export class App {
                 if (parsed === undefined) {
                     throw new BadRequestError("Invalid JSON report body");
                 }
-                const ip = healthRouteKey(request);
+                const ip = healthRouteKey(request, trustProxyHeaders);
                 const userAgent = request.headers.get("user-agent");
                 try {
                     if (opts.onReport) {
@@ -2385,7 +2405,11 @@ export class App {
             : baseLog.child({
                 requestId,
                 method: request.method,
-                url: request.url,
+                // Never bind the raw request URL: query strings commonly carry
+                // OAuth codes, API keys, and signed-URL tokens. sanitizeUrlForLog
+                // keeps origin+path and redacts sensitive query values so 4xx/5xx
+                // lines cannot become a credential sink under the field name `url`.
+                url: sanitizeUrlForLog(request.url),
             });
         const stripFingerprint = this.options.stripServerHeaders !== false;
         let ctx;
@@ -2394,9 +2418,10 @@ export class App {
         let activeResponseHook = globalHooks.onResponse;
         let activeSendHook = globalHooks.onSend;
         try {
-            assertNoDuplicateSingletonHeaders(request.headers);
-            assertNoReservedInternalHeaders(request.headers);
-            assertHeaderCountWithinLimit(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
+            // Singleton-duplicate + reserved-prefix + header-count cap share ONE
+            // Headers.forEach walk (assertInboundHeaderGuards) instead of a
+            // three-Headers.get() pass plus a separate walk.
+            assertInboundHeaderGuards(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
             this.assertTrustProxyConfigured(request);
             this.assertBootGuards();
             if (globalHooks.onRequest !== undefined) {
@@ -2862,8 +2887,8 @@ export class App {
      * "draining" signal); then the app waits up to `timeoutMs` for in-flight
      * requests to settle; finally, {@link App.onClose} cleanups run.
      *
-     * Both Node and Bun adapters call this automatically on `SIGINT` / `SIGTERM`.
-     * Call it manually from custom runtimes or integration tests.
+     * The Node, Bun, and Deno adapters call this automatically on `SIGINT` /
+     * `SIGTERM`. Call it manually from custom runtimes or integration tests.
      *
      * @param timeoutMs - Maximum time (ms) to wait for inflight requests. Default: `10_000`.
      * @param reason - Optional human-readable reason forwarded to listeners.
@@ -2954,14 +2979,30 @@ function joinPath(a, b) {
     const joined = `${left}${right}`;
     return joined === "" ? "/" : joined;
 }
-function healthRouteKey(request) {
-    // The probe rate limit deliberately does NOT honour `X-Forwarded-For` —
-    // health probes typically arrive directly from a sidecar / orchestrator,
-    // so even apps that trust forwarded headers should not let an attacker
-    // bypass the per-IP cap by spoofing the header. Fall back to a constant
-    // key when no proxy header is available (single shared bucket).
+/**
+ * Rate-limit / attribution key for built-in observability routes
+ * (`/healthz`, `/readyz`, `/metrics`, CSP report).
+ *
+ * Secure default: a single shared `"global"` bucket. Spoofable platform
+ * headers (`X-Real-IP`, `Fly-Client-IP`) are only read when the app has an
+ * explicit trusted-proxy posture (`trustProxy: true` or `behindProxy` set).
+ * `X-Forwarded-For` is never used here — probes and scrapers often hit the
+ * process directly, and a free-form XFF chain would let an attacker rotate
+ * identities to bypass the cap.
+ *
+ * @param request - Inbound request.
+ * @param trustProxyHeaders - When true, platform client-IP headers may be used.
+ * @returns A stable string key for the in-memory rate-limit map.
+ */
+function healthRouteKey(request, trustProxyHeaders) {
+    if (!trustProxyHeaders)
+        return "global";
     return request.headers.get("x-real-ip") ?? request.headers.get("fly-client-ip") ?? "global";
 }
+/** True when the app declared a trusted reverse-proxy posture. */
+function appTrustsProxyHeaders(options) {
+    return options.trustProxy === true || options.behindProxy !== undefined;
+}
 function corsOriginAllowsFromHooks(layers) {
     const allows = [];
     for (const hooks of layers) {
@@ -3335,34 +3376,32 @@ function scalarConfigurationWithPreferredAuth(configuration, schemes) {
 }
 function finalizeResponse(res, ctx, hooks, stripFingerprint = true) {
     let final = res;
-    const finish = (f) => {
-        if (stripFingerprint) {
-            f.headers.delete("server");
-            f.headers.delete("x-powered-by");
-        }
-        if (hooks.onResponse !== undefined) {
-            const onResponseResult = hooks.onResponse(f);
-            if (isPromiseLike(onResponseResult)) {
-                return onResponseResult.then(() => f);
-            }
-        }
-        return f;
-    };
     if (hooks.onSend !== undefined) {
         const sentResult = hooks.onSend(res, ctx);
         if (isPromiseLike(sentResult)) {
             return sentResult.then((sent) => {
                 if (sent instanceof Response)
                     final = sent;
-                return finish(final);
+                return finishFinalize(final, hooks, stripFingerprint);
             });
         }
-        else {
-            if (sentResult instanceof Response)
-                final = sentResult;
+        if (sentResult instanceof Response)
+            final = sentResult;
+    }
+    return finishFinalize(final, hooks, stripFingerprint);
+}
+function finishFinalize(res, hooks, stripFingerprint) {
+    if (stripFingerprint) {
+        res.headers.delete("server");
+        res.headers.delete("x-powered-by");
+    }
+    if (hooks.onResponse !== undefined) {
+        const onResponseResult = hooks.onResponse(res);
+        if (isPromiseLike(onResponseResult)) {
+            return onResponseResult.then(() => res);
         }
     }
-    return finish(final);
+    return res;
 }
 function isPromiseLike(value) {
     return value !== null && typeof value === "object" && typeof value.then === "function";
@@ -3991,11 +4030,46 @@ function runHandler(def, ctx, requestTimeoutMs) {
     if (requestTimeoutMs === 0 || !isPromiseLike(result)) {
         return result;
     }
-    return withTimeout(result, requestTimeoutMs);
+    return withTimeout(result, requestTimeoutMs, ctx.request);
 }
-function withTimeout(p, ms) {
+/**
+ * Fire an adapter's request abort hook (see {@link DALOY_REQUEST_ABORT}) if the
+ * request shim exposes one. Called as a method so `this` stays bound to the
+ * request. A no-op when the hook is absent (platform-managed `Request.signal`
+ * or a direct `app.fetch()` caller), so the caller must not depend on the
+ * signal actually firing.
+ *
+ * @param request - The in-flight request whose signal should be aborted.
+ * @param reason - Abort reason surfaced on `request.signal.reason`.
+ */
+function abortRequest(request, reason) {
+    const hooked = request;
+    hooked[DALOY_REQUEST_ABORT]?.(reason);
+}
+/**
+ * Race a handler promise against the per-request timeout.
+ *
+ * On timeout the request's {@link DALOY_REQUEST_ABORT} hook is fired first —
+ * aborting `request.signal` with a `TimeoutError` `DOMException` (the same
+ * reason shape as `AbortSignal.timeout()`) so cooperative downstream I/O the
+ * handler forwarded the signal to unwinds — and then the returned promise
+ * rejects with a {@link RequestTimeoutError} so the client receives a `408`.
+ * The handler promise itself keeps a rejection handler attached, so a late
+ * settle (including the `AbortError` from the work it just cancelled) never
+ * surfaces as an unhandled rejection.
+ *
+ * @typeParam T - The handler's resolved value type.
+ * @param p - The handler (or hook chain) promise to bound.
+ * @param ms - Timeout in milliseconds; assumed non-zero by the caller.
+ * @param request - The in-flight request, used to fire the abort hook.
+ * @returns A promise that settles with the handler result or a 408 timeout.
+ */
+function withTimeout(p, ms, request) {
     return new Promise((resolve, reject) => {
-        const t = setTimeout(() => reject(new RequestTimeoutError(ms)), ms);
+        const t = setTimeout(() => {
+            abortRequest(request, new DOMException(`Request exceeded ${ms}ms`, "TimeoutError"));
+            reject(new RequestTimeoutError(ms));
+        }, ms);
         p.then((v) => {
             clearTimeout(t);
             resolve(v);

package/dist/bot-guard.js

@@ -76,8 +76,14 @@ function matchesUserAgent(ua, patterns) {
             if (pattern && lower.includes(pattern.toLowerCase()))
                 return true;
         }
-        else if (pattern.test(ua)) {
-            return true;
+        else {
+            // Reset lastIndex so caller-supplied /g or /y regexes cannot flip-flop
+            // between match and miss across requests (intermittent allowlist bypass).
+            pattern.lastIndex = 0;
+            const hit = pattern.test(ua);
+            pattern.lastIndex = 0;
+            if (hit)
+                return true;
         }
     }
     return false;
@@ -225,12 +231,28 @@ export function botGuard(opts = {}) {
     };
     const writeCache = (key, verified) => {
         const now = Date.now();
+        // Move this key to the newest insertion slot on every (re)write. Eviction
+        // below is therefore FIFO over WRITE-recency (Map preserves insertion
+        // order), not true LRU: cache *reads* on the verification path do not
+        // reorder entries, so a frequently-read-but-never-rewritten key can still
+        // be evicted. That is intentional — reordering on read would add a Map
+        // delete+set to the hot lookup path for no security benefit.
+        if (cache.has(key))
+            cache.delete(key);
         cache.set(key, { verified, expiresMs: now + cacheTtlMs });
         if (cache.size > cacheMax) {
             for (const [k, v] of cache)
                 if (v.expiresMs <= now)
                     cache.delete(k);
         }
+        // Still over the cap after pruning expired entries: evict the
+        // oldest-written live keys (front of insertion order) until within cacheMax.
+        while (cache.size > cacheMax) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
     };
     const reject = (event) => {
         opts.onBlock?.(event);
@@ -252,7 +274,12 @@ export function botGuard(opts = {}) {
                 reject({ reason: "blocked-user-agent", userAgent: ua });
                 return undefined;
             }
-            const rule = verifiedBots.find((r) => r.userAgent.test(ua));
+            const rule = verifiedBots.find((r) => {
+                r.userAgent.lastIndex = 0;
+                const hit = r.userAgent.test(ua);
+                r.userAgent.lastIndex = 0;
+                return hit;
+            });
             if (!rule)
                 return undefined;
             const ip = resolveIp(ctx);