@daloyjs/core 0.43.0 → 1.0.0-beta.0

package/README.md

@@ -498,7 +498,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is in **public preview** (`0.x`). The public API may still change between minor versions; deprecations will get at least one minor cycle once `1.0.0` ships. The framework is already in use for production trials.
+DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.0`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 

package/dist/adapters/node.d.ts

@@ -8,7 +8,17 @@ import type { App } from "../app.js";
 export interface NodeServerOptions {
     port?: number;
     hostname?: string;
-    /** Connection-level timeout in ms. Default: 30000. */
+    /**
+     * Connection-level timeout in ms, applied to BOTH `headersTimeout` and
+     * `requestTimeout`. A client that has not finished sending its request
+     * headers (or whole request) within this window is hung up on with `408`.
+     * This is the slowloris / slow-header defense: the adapter also lowers
+     * Node's `connectionsCheckingInterval` to a fraction of this value so the
+     * timeout is actually *enforced* near when it elapses, rather than only at
+     * Node's default 30s sweep (which would let a stalled or byte-trickling
+     * connection hold a socket open far past the configured timeout). Set `0`
+     * to disable timeouts entirely. Default: 30000.
+     */
     connectionTimeoutMs?: number;
     /** Drain timeout for graceful shutdown. Default: 10000. */
     shutdownTimeoutMs?: number;

package/dist/adapters/node.js

@@ -13,7 +13,23 @@ export function serve(app, opts = {}) {
     const bufferedBodyMaxBytes = typeof opts.bufferedBodyMaxBytes === "number" && opts.bufferedBodyMaxBytes >= 0
         ? opts.bufferedBodyMaxBytes
         : DEFAULT_BUFFERED_BODY_MAX_BYTES;
-    const server = createServer({ maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024 }, (req, res) => {
+    const connectionTimeoutMs = opts.connectionTimeoutMs ?? 30_000;
+    // Node only *enforces* `headersTimeout` / `requestTimeout` when its periodic
+    // connection checker runs, and that checker's default interval is 30s. With
+    // the default interval a slowloris that never completes its headers — idle
+    // OR trickling a byte at a time — survives until the next 30s sweep, far
+    // past the configured timeout, holding a socket open the whole time. Polling
+    // at a fraction of the timeout (bounded to [1s, 5s]) makes the configured
+    // timeout actually honored, so a stalled connection is reaped with `408`
+    // close to when it should be. Skipped only when timeouts are disabled
+    // (`connectionTimeoutMs: 0`), where there is nothing to reap.
+    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) => {
         // 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;
@@ -33,8 +49,8 @@ export function serve(app, opts = {}) {
         }
         dispatchToApp(app, req, res, trustProxy, undefined);
     });
-    server.requestTimeout = opts.connectionTimeoutMs ?? 30_000;
-    server.headersTimeout = opts.connectionTimeoutMs ?? 30_000;
+    server.requestTimeout = connectionTimeoutMs;
+    server.headersTimeout = connectionTimeoutMs;
     server.keepAliveTimeout = 5_000;
     // Native parser-level header-count cap. Drops header-count floods (the
     // "HTTP/2 Bomb" amplification dimension) before they become a Request.

package/dist/fetch-guard.d.ts

@@ -52,18 +52,21 @@
  * its **own** DNS lookup when it opens the socket. An attacker that
  * controls a TTL=0 record can return a public IP at validation time and
  * a `127.0.0.1` / `169.254.169.254` at connect time, slipping past the
- * library-level check. This residual TOCTOU window cannot be closed at
- * the `fetch()` boundary without injecting a custom HTTP dispatcher
- * (e.g. `undici.Agent({ connect: { lookup } })`) — and Daloy
- * deliberately ships **zero** runtime dependencies, so we do not bundle
- * `undici`. To fully close the window:
- *
+ * library-level check. To close the window:
+ *
+ *  0. **Built-in, `http:` only** (recommended for cloud-metadata defense):
+ *     set {@link FetchGuardOptions.pinDns} `: true`. On Node, `http:`
+ *     requests are then dispatched through `node:http` with the socket
+ *     pinned to the validated IP (and the original `Host` header
+ *     preserved), so there is no connect-time re-resolution to rebind.
+ *     `https:` is not pinned by this knob — see its docs — so the items
+ *     below still matter for TLS upstreams.
  *  1. **Operator-side** (recommended): block egress to RFC1918 /
  *     loopback / link-local at the VPC / firewall layer. This neutralises
  *     the rebinding even if the application is naïve.
- *  2. **Caller-side, Node only**: install `undici` and pass a custom
- *     `fetch` that wires a dispatcher with a pinned-IP `connect.lookup`,
- *     e.g.
+ *  2. **Caller-side, Node only** (covers `https:` too): install `undici`
+ *     and pass a custom `fetch` that wires a dispatcher with a pinned-IP
+ *     `connect.lookup`, e.g.
  *     ```ts
  *     import { Agent, fetch as undiciFetch } from "undici";
  *     import * as dns from "node:dns/promises";
@@ -177,6 +180,41 @@ export interface FetchGuardOptions {
      * without `--allow-net`) or to enforce an in-memory test fixture.
      */
     resolve?: (hostname: string) => Promise<readonly string[]>;
+    /**
+     * Close the residual DNS-rebinding (TOCTOU) window for **`http:`** requests
+     * by connecting the socket to the exact IP that was validated, instead of
+     * letting the underlying client re-resolve the hostname at connect time.
+     *
+     * When `true` (default `false`), a request to a hostname that resolves to a
+     * validated address is dispatched through Node's built-in `node:http` with
+     * the connection pinned to that address and the original `Host` header
+     * preserved — so virtual-host routing still works while an attacker's
+     * TTL=0 rebinding to `127.0.0.1` / `169.254.169.254` can no longer take
+     * effect between validation and connect.
+     *
+     * **Scope and caveats** (read before enabling):
+     *
+     * - **`http:` only.** `https:` is intentionally NOT pinned here: pinning a
+     *   TLS connection to an IP while keeping hostname-based SNI / certificate
+     *   validation needs more machinery than this knob provides, so `https:`
+     *   requests fall through to the normal validated-then-fetch path and retain
+     *   the documented TOCTOU caveat. The prime rebinding target — cloud
+     *   metadata at `http://169.254.169.254` — is `http:`, so this still closes
+     *   the highest-value vector.
+     * - **Node only.** It uses `node:http`; on runtimes without it (Workers,
+     *   some edge sandboxes) an `http:` pinned dispatch throws a clear error so
+     *   the misconfiguration is loud rather than a silent no-op.
+     * - **Bypasses `options.fetch`** for the pinned `http:` path (it must own the
+     *   socket), and negotiates no response compression (`Accept-Encoding:
+     *   identity`) so body semantics match a plain `fetch`.
+     *
+     * Requests to a literal-IP host or an `allowHosts` entry are never pinned
+     * (the former already connects to an exact IP; the latter is an explicit
+     * operator trust). Default `false`.
+     *
+     * @since 0.44.0
+     */
+    pinDns?: boolean;
 }
 /**
  * Wrap `fetch` with an SSRF-hardened guard. The returned function has

package/dist/fetch-guard.js

@@ -52,18 +52,21 @@
  * its **own** DNS lookup when it opens the socket. An attacker that
  * controls a TTL=0 record can return a public IP at validation time and
  * a `127.0.0.1` / `169.254.169.254` at connect time, slipping past the
- * library-level check. This residual TOCTOU window cannot be closed at
- * the `fetch()` boundary without injecting a custom HTTP dispatcher
- * (e.g. `undici.Agent({ connect: { lookup } })`) — and Daloy
- * deliberately ships **zero** runtime dependencies, so we do not bundle
- * `undici`. To fully close the window:
+ * library-level check. To close the window:
  *
+ *  0. **Built-in, `http:` only** (recommended for cloud-metadata defense):
+ *     set {@link FetchGuardOptions.pinDns} `: true`. On Node, `http:`
+ *     requests are then dispatched through `node:http` with the socket
+ *     pinned to the validated IP (and the original `Host` header
+ *     preserved), so there is no connect-time re-resolution to rebind.
+ *     `https:` is not pinned by this knob — see its docs — so the items
+ *     below still matter for TLS upstreams.
  *  1. **Operator-side** (recommended): block egress to RFC1918 /
  *     loopback / link-local at the VPC / firewall layer. This neutralises
  *     the rebinding even if the application is naïve.
- *  2. **Caller-side, Node only**: install `undici` and pass a custom
- *     `fetch` that wires a dispatcher with a pinned-IP `connect.lookup`,
- *     e.g.
+ *  2. **Caller-side, Node only** (covers `https:` too): install `undici`
+ *     and pass a custom `fetch` that wires a dispatcher with a pinned-IP
+ *     `connect.lookup`, e.g.
  *     ```ts
  *     import { Agent, fetch as undiciFetch } from "undici";
  *     import * as dns from "node:dns/promises";
@@ -175,6 +178,7 @@ export function fetchGuard(options = {}) {
         throw new Error("fetchGuard(): no global fetch available; pass options.fetch.");
     }
     const resolveFn = options.resolve ?? createDefaultResolver();
+    const pinDns = options.pinDns === true;
     for (const c of ALWAYS_DENY)
         hardDenyMatchers.push(compileCidrMatcher(c));
     for (const c of options.denyAddresses ?? [])
@@ -206,6 +210,17 @@ export function fetchGuard(options = {}) {
             return true;
         return !softDenyMatchers.some((m) => matchesMatcher(parsed, m));
     }
+    /**
+     * Validate a URL's destination against the deny/allow policy.
+     *
+     * @returns the single validated IP the connection should be **pinned** to
+     *   (the first resolved address), or `null` when pinning does not apply —
+     *   the host is an `allowHosts` entry (explicit operator trust) or already a
+     *   literal IP (the socket connects to that exact address, so there is no
+     *   re-resolution window to close).
+     * @throws {SsrfBlockedError} when the protocol, host, or any resolved
+     *   address is not permitted.
+     */
     async function validateUrl(url) {
         const proto = url.protocol.toLowerCase();
         if (!allowProtocols.has(proto)) {
@@ -217,13 +232,13 @@ export function fetchGuard(options = {}) {
             throw new SsrfBlockedError(url.toString(), "invalid-url");
         }
         if (allowHosts.has(hostname.toLowerCase()))
-            return;
+            return null;
         const literal = parseIp(hostname);
         if (literal) {
             if (!isAddressAllowed(literal)) {
                 throw new SsrfBlockedError(url.toString(), "address-not-allowed", hostname);
             }
-            return;
+            return null;
         }
         let addrs;
         try {
@@ -244,6 +259,7 @@ export function fetchGuard(options = {}) {
                 throw new SsrfBlockedError(url.toString(), "address-not-allowed", a);
             }
         }
+        return addrs[0];
     }
     const guarded = async (input, init) => {
         let request = new Request(input, init);
@@ -258,10 +274,17 @@ export function fetchGuard(options = {}) {
             throw new SsrfBlockedError(String(input), "invalid-url");
         }
         for (let hop = 0;; hop++) {
-            await validateUrl(currentUrl);
+            const pinnedIp = await validateUrl(currentUrl);
             const dispatchInit = { redirect: "manual" };
             const dispatchReq = new Request(request, dispatchInit);
-            const res = await baseFetch(dispatchReq);
+            // When DNS pinning is enabled, dispatch `http:` requests through a
+            // socket bound to the exact validated IP so the underlying client cannot
+            // re-resolve the hostname to an internal address between validation and
+            // connect (DNS-rebinding TOCTOU). `https:` keeps the normal path — see
+            // the `pinDns` option docs for why.
+            const res = pinDns && pinnedIp !== null && currentUrl.protocol === "http:"
+                ? await pinnedHttpFetch(dispatchReq, pinnedIp)
+                : await baseFetch(dispatchReq);
             if (!isRedirect(res.status))
                 return res;
             if (userRedirect === "error") {
@@ -307,6 +330,85 @@ export function fetchGuard(options = {}) {
 function isRedirect(status) {
     return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
 }
+/**
+ * Dispatch an `http:` request with the TCP connection **pinned** to a single,
+ * already-validated IP address — closing the DNS-rebinding (TOCTOU) window that
+ * exists when the underlying `fetch` re-resolves the hostname at connect time.
+ *
+ * Uses Node's built-in `node:http` (no runtime dependency) so the `Host` header
+ * can be set to the original authority — preserving virtual-host routing while
+ * the socket targets `ip`, never a re-resolved address. The response body is
+ * streamed (not buffered) so large downloads keep the same memory profile as a
+ * plain `fetch`. `Accept-Encoding: identity` is forced so the returned body is
+ * not silently left compressed (Node's `http` does not auto-decode).
+ *
+ * @param req - The request to dispatch (its URL supplies the path + `Host`).
+ * @param ip - The validated address to connect to.
+ * @returns A web {@link Response} mirroring the upstream reply.
+ * @throws when `node:http` is unavailable (non-Node runtime) or the socket errors.
+ */
+async function pinnedHttpFetch(req, ip) {
+    let httpRequest;
+    let toWeb;
+    try {
+        ({ request: httpRequest } = await import("node:http"));
+        ({ toWeb } = (await import("node:stream")).Readable);
+    }
+    catch {
+        throw new Error("fetchGuard({ pinDns: true }): node:http is unavailable on this runtime; " +
+            "DNS pinning for http: requires Node. Disable pinDns or run on Node.");
+    }
+    const url = new URL(req.url);
+    const headers = {};
+    req.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    // Preserve the original authority so virtual-host routing still works even
+    // though the socket connects to a raw IP.
+    headers["host"] = url.host;
+    // Do not negotiate compression: node:http won't auto-decode it, and a
+    // silently-compressed body would break `res.text()` / `res.json()` callers.
+    headers["accept-encoding"] = "identity";
+    const method = req.method.toUpperCase();
+    const bodyBytes = method === "GET" || method === "HEAD" ? undefined : new Uint8Array(await req.arrayBuffer());
+    return await new Promise((resolve, reject) => {
+        const clientReq = httpRequest({
+            host: ip,
+            port: url.port ? Number(url.port) : 80,
+            method,
+            path: `${url.pathname}${url.search}`,
+            headers,
+        }, (res) => {
+            const responseHeaders = new Headers();
+            for (const [key, value] of Object.entries(res.headers)) {
+                if (Array.isArray(value)) {
+                    for (const v of value)
+                        responseHeaders.append(key, v);
+                }
+                else if (typeof value === "string") {
+                    responseHeaders.set(key, value);
+                }
+            }
+            const status = res.statusCode ?? 502;
+            // 204/304 and HEAD responses must carry a null body per the spec.
+            const nullBody = status === 204 || status === 304 || method === "HEAD";
+            if (nullBody) {
+                res.resume(); // drain so the socket can be released
+                resolve(new Response(null, { status, statusText: res.statusMessage, headers: responseHeaders }));
+                return;
+            }
+            resolve(new Response(toWeb(res), {
+                status,
+                statusText: res.statusMessage,
+                headers: responseHeaders,
+            }));
+        });
+        clientReq.on("error", reject);
+        if (bodyBytes && bodyBytes.byteLength > 0)
+            clientReq.write(bodyBytes);
+        clientReq.end();
+    });
+}
 function stripBodyHeaders(headers) {
     const out = new Headers(headers);
     out.delete("content-length");

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:66a4adf1-88f7-56e9-a00f-95633f473b23",
+  "serialNumber": "urn:uuid:24c97016-8019-52fa-bf46-65a4325559ec",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-20T12:10:13.811Z",
+    "timestamp": "2026-06-21T08:21:23.570Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.43.0"
+        "version": "1.0.0-beta.0"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.43.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.0",
       "name": "@daloyjs/core",
-      "version": "0.43.0",
+      "version": "1.0.0-beta.0",
       "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@0.43.0",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-beta.0",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.43.0",
+        "tagId": "swidtag--daloyjs-core-1.0.0-beta.0",
         "name": "@daloyjs/core",
-        "version": "0.43.0",
+        "version": "1.0.0-beta.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.43.0",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-beta.0",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-0.43.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.43.0-66a4adf1-88f7-56e9-a00f-95633f473b23",
+  "name": "@daloyjs/core-1.0.0-beta.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.0-24c97016-8019-52fa-bf46-65a4325559ec",
   "creationInfo": {
-    "created": "2026-06-20T12:10:13.811Z",
+    "created": "2026-06-21T08:21:23.570Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.43.0",
+      "versionInfo": "1.0.0-beta.0",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@0.43.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-beta.0"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.43.0",
+  "version": "1.0.0-beta.0",
   "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.",
   "type": "module",
   "publishConfig": {
@@ -241,7 +241,8 @@
     "example": "node --import tsx examples/basic.ts",
     "bench": "node --import tsx bench/router.bench.ts",
     "test": "node --import tsx --test tests/**/*.test.ts",
-    "test:red-team": "node --import tsx --test tests/red-team-attacks.test.ts tests/red-team-attacks-2.test.ts tests/red-team-attacks-3.test.ts tests/red-team-attacks-4.test.ts tests/red-team-attacks-5.test.ts tests/red-team-attacks-6.test.ts tests/red-team-attacks-7.test.ts",
+    "test:red-team": "node --import tsx --test tests/red-team-attacks.test.ts tests/red-team-attacks-2.test.ts tests/red-team-attacks-3.test.ts tests/red-team-attacks-4.test.ts tests/red-team-attacks-5.test.ts tests/red-team-attacks-6.test.ts tests/red-team-attacks-7.test.ts tests/red-team-attacks-8.test.ts tests/red-team-attacks-9.test.ts tests/red-team-attacks-10.test.ts",
+    "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",