@grest-ts/http 0.0.67 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grest-ts/http",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "type": "module",
   "license": "MIT",
   "description": "HTTP server and client library for Node.js and browser",
@@ -61,16 +61,16 @@
     "find-my-way": "^9.4.0"
   },
   "peerDependencies": {
-    "@grest-ts/common": "0.0.67",
-    "@grest-ts/context": "0.0.67",
-    "@grest-ts/discovery": "0.0.67",
-    "@grest-ts/locator": "0.0.67",
-    "@grest-ts/logger": "0.0.67",
-    "@grest-ts/metrics": "0.0.67",
-    "@grest-ts/schema": "0.0.67",
-    "@grest-ts/trace": "0.0.67"
+    "@grest-ts/common": "0.0.68",
+    "@grest-ts/context": "0.0.68",
+    "@grest-ts/discovery": "0.0.68",
+    "@grest-ts/locator": "0.0.68",
+    "@grest-ts/logger": "0.0.68",
+    "@grest-ts/metrics": "0.0.68",
+    "@grest-ts/schema": "0.0.68",
+    "@grest-ts/trace": "0.0.68"
   },
   "devDependencies": {
-    "@grest-ts/testkit": "0.0.67"
+    "@grest-ts/testkit": "0.0.68"
   }
 }

package/src/_dedupCheck.ts

@@ -12,7 +12,7 @@
 const __KEY = Symbol.for("grest-ts:dedup:@grest-ts/http");
 const __slot = globalThis as Record<symbol, unknown>;
 const __existing = __slot[__KEY] as { path: string; version: string } | undefined;
-const __here = { path: import.meta.url, version: "0.0.67" };
+const __here = { path: import.meta.url, version: "0.0.68" };
 // Same path + same version means the same physical package is being
 // re-evaluated by a different ESM runner (e.g. vitest projects share one
 // process but each project has its own module cache). That isn't a true

package/src/client/GGHttpSchema.createClient.node.ts

@@ -4,7 +4,8 @@
  * The import stays dynamic so discovery remains an optional integration, not a
  * hard dependency of @grest-ts/http.
  */
-import {_registerDiscoveryUrlResolver} from "./GGHttpSchema.createClient"
+import {_registerDiscoveryUrlResolver, _registerNodeDefaultTransport} from "./GGHttpSchema.createClient"
+import {nodeDefaultTransport} from "./nodeConnectionTransport.node"
 
 export const discoveryUrlResolver = async (apiName: string): Promise<string> => {
     const {GG_DISCOVERY} = await import('@grest-ts/discovery')
@@ -12,3 +13,4 @@ export const discoveryUrlResolver = async (apiName: string): Promise<string> =>
 }
 
 _registerDiscoveryUrlResolver(discoveryUrlResolver)
+_registerNodeDefaultTransport(nodeDefaultTransport)

package/src/client/GGHttpSchema.createClient.ts

@@ -1,6 +1,7 @@
 import {ANY_ERROR, ERROR, GGContractApiDefinition, GGContractClient, GGContractExecutor, GGContractImplementation, GGPromise, OK, SERVER_ERROR} from "@grest-ts/schema"
 import {ClientHttpRouteToRpcTransformClientCodec, GGHttpCodec, GGHttpSchema} from "../schema/GGHttpSchema";
 import {isBrowser} from "@grest-ts/common";
+import type {GGConnectionSettings} from "@grest-ts/context";
 
 
 declare module "../schema/GGHttpSchema" {
@@ -30,6 +31,8 @@ export type GGHttpTransport = (
         body: string | FormData | undefined
         signal: AbortSignal
         credentials?: "omit" | "same-origin" | "include"
+        /** Transport-level dial settings (e.g. TLS pin) contributed by middleware and/or client config. */
+        connectionSettings?: GGConnectionSettings
     }
 ) => Promise<Response>
 
@@ -51,6 +54,12 @@ export interface GGHttpClientConfig {
      * just the schema-built path.
      */
     transport?: GGHttpTransport
+    /**
+     * Connection settings (e.g. TLS pin) fixed for this client's lifetime — the direct
+     * alternative to a `GGConnectionSettingsKey` middleware. Node-only: setting this on a
+     * browser client throws when a request is issued (the browser can't access the TLS layer).
+     */
+    connectionSettings?: GGConnectionSettings
 }
 
 /**
@@ -65,6 +74,18 @@ export function _registerDiscoveryUrlResolver(resolver: (apiName: string) => Pro
     discoveryUrlResolver = resolver
 }
 
+/**
+ * Node-only default transport (pinned-TLS dialing). Attached by the node entry via
+ * ./GGHttpSchema.createClient.node; node-only because it imports `node:https`/`node:tls`.
+ * When registered it replaces `defaultFetchTransport` as the default (an explicit
+ * `config.transport` still wins). It falls back to `fetch` when no TLS pin is set.
+ */
+let nodeDefaultTransport: GGHttpTransport | undefined
+
+export function _registerNodeDefaultTransport(transport: GGHttpTransport): void {
+    nodeDefaultTransport = transport
+}
+
 GGHttpSchema.prototype.createClient = function <TContract extends GGContractApiDefinition>(
     this: GGHttpSchema<TContract>,
     config?: GGHttpClientConfig
@@ -84,7 +105,7 @@ export function createClient<TContract extends GGContractApiDefinition>(
     // A custom transport implies "I take over the wire layer" — discovery is
     // off the table (the transport knows how to find the target), and the
     // default base URL becomes "" so the transport sees just the request path.
-    const transport: GGHttpTransport = config.transport ?? defaultFetchTransport;
+    const transport: GGHttpTransport = config.transport ?? nodeDefaultTransport ?? defaultFetchTransport;
     if (config.transport && config.url === undefined) {
         config.url = "";
     }
@@ -129,6 +150,14 @@ export function createClient<TContract extends GGContractApiDefinition>(
                 // ---------------------------------------------
                 // Execution
                 const fetchRequest = await wireFormat.createRequest(validatedInput);
+
+                const connectionSettings = config.connectionSettings || fetchRequest.connectionSettings
+                    ? {...config.connectionSettings, ...fetchRequest.connectionSettings}
+                    : undefined;
+                if (connectionSettings && isBrowser() && Object.keys(connectionSettings).length > 0) {
+                    throw new SERVER_ERROR({displayMessage: "connectionSettings (e.g. TLS pinning) is node-only — the browser can't access the TLS layer, so it can't honor them."});
+                }
+
                 const controller = new AbortController();
                 const timeoutId = setTimeout(() => controller.abort(), config.timeout);
                 const wireResponse = await transport(baseUrl + fetchRequest.url, {
@@ -136,7 +165,8 @@ export function createClient<TContract extends GGContractApiDefinition>(
                     signal: controller.signal,
                     headers: fetchRequest.headers,
                     body: fetchRequest.body,
-                    credentials: config.credentials
+                    credentials: config.credentials,
+                    connectionSettings
                 }).finally(() => clearTimeout(timeoutId));
                 const resData = await wireFormat.parseResponse(wireResponse);
 

package/src/client/nodeConnectionTransport.node.test.ts

@@ -0,0 +1,320 @@
+import {describe, it, expect, beforeAll, afterAll, afterEach, vi} from 'vitest'
+import https from 'node:https'
+import {execFileSync} from 'node:child_process'
+import {mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+import {X509Certificate} from 'node:crypto'
+import {GGContractClass, IsObject, IsString, SERVER_ERROR} from '@grest-ts/schema'
+import {GGContext, type GGConnectionSettings} from '@grest-ts/context'
+import {GGHttpSchema} from '../schema/GGHttpSchema'
+import {GGRpc} from '../rpc/GGHttpRouteRPC'
+import {createClient} from './GGHttpSchema.createClient'
+import {GGConnectionSettingsKey} from '../schema/GGConnectionSettingsKey'
+import {invalidateTlsPinAgent} from './nodeConnectionTransport.node'
+// Side-effect import: registers nodeDefaultTransport as the default for url-less node clients.
+import './GGHttpSchema.createClient.node'
+
+const PingContract = new GGContractClass("PinnedTlsTestApi", {
+    ping: {
+        input: IsObject({msg: IsString}),
+        success: IsObject({msg: IsString}),
+        errors: [SERVER_ERROR],
+    },
+})
+
+const CONN = new GGConnectionSettingsKey("pinnedTlsTestConn")
+
+// Mirror the request boundary: the runtime establishes one context per request, the app sets
+// the key inside it. We do the same here — one scope per simulated operation, never per call.
+function inScope<R>(settings: GGConnectionSettings, fn: () => R): R {
+    const ctx = new GGContext("test-req")
+    ctx.set(CONN, settings)
+    return ctx.run(fn)
+}
+
+const PingApi = new GGHttpSchema({
+    contract: PingContract,
+    pathPrefix: "api/ping",
+    routes: {ping: GGRpc.POST("ping")},
+    use: [CONN],
+})
+
+interface TestServer {
+    port: number
+    fingerprint256: string
+    reqCount: () => number
+    connCount: () => number
+    close: () => Promise<void>
+}
+
+function openssl(...args: string[]): void {
+    execFileSync("openssl", args, {stdio: "ignore"})
+}
+
+function genCert(dir: string, name: string): {cert: string; key: string} {
+    const certPath = join(dir, `${name}.cert.pem`)
+    const keyPath = join(dir, `${name}.key.pem`)
+    openssl("req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1", "-keyout", keyPath, "-out", certPath, "-subj", `/CN=${name}`)
+    return {cert: readFileSync(certPath, "utf8"), key: readFileSync(keyPath, "utf8")}
+}
+
+interface TestCa {keyPath: string; crtPath: string; crt: string}
+
+function genCa(dir: string, name: string): TestCa {
+    const keyPath = join(dir, `${name}.ca.key`)
+    const crtPath = join(dir, `${name}.ca.crt`)
+    openssl("req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1", "-keyout", keyPath, "-out", crtPath, "-subj", `/CN=${name}-ca`)
+    return {keyPath, crtPath, crt: readFileSync(crtPath, "utf8")}
+}
+
+function genSignedCert(dir: string, name: string, ca: TestCa, sanIp?: string): {cert: string; key: string} {
+    const keyPath = join(dir, `${name}.key`)
+    const csrPath = join(dir, `${name}.csr`)
+    const crtPath = join(dir, `${name}.crt`)
+    openssl("req", "-newkey", "rsa:2048", "-nodes", "-keyout", keyPath, "-out", csrPath, "-subj", `/CN=${name}`)
+    const args = ["x509", "-req", "-in", csrPath, "-CA", ca.crtPath, "-CAkey", ca.keyPath, "-CAcreateserial", "-days", "1", "-out", crtPath]
+    if (sanIp) {
+        const extPath = join(dir, `${name}.ext`)
+        writeFileSync(extPath, `subjectAltName=IP:${sanIp}\n`)
+        args.push("-extfile", extPath)
+    }
+    openssl(...args)
+    return {cert: readFileSync(crtPath, "utf8"), key: readFileSync(keyPath, "utf8")}
+}
+
+async function startServer(cert: string, key: string, replyMsg: string, extra: https.ServerOptions = {}): Promise<TestServer> {
+    let reqCount = 0
+    let connCount = 0
+    const server = https.createServer({cert, key, ...extra}, (_req, res) => {
+        reqCount++
+        res.writeHead(200, {"content-type": "application/json"})
+        res.end(JSON.stringify({success: true, type: "OK", data: {msg: replyMsg}}))
+    })
+    server.on("connection", () => { connCount++ })
+    await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve))
+    const port = (server.address() as {port: number}).port
+    return {
+        port,
+        fingerprint256: new X509Certificate(cert).fingerprint256,
+        reqCount: () => reqCount,
+        connCount: () => connCount,
+        close: () => new Promise<void>(resolve => server.close(() => resolve())),
+    }
+}
+
+describe('pinned-TLS node transport', () => {
+
+    let dir: string
+    let serverA: TestServer
+    let serverB: TestServer
+
+    beforeAll(async () => {
+        dir = mkdtempSync(join(tmpdir(), "gg-pin-"))
+        const a = genCert(dir, "serverA")
+        const b = genCert(dir, "serverB")
+        serverA = await startServer(a.cert, a.key, "from-A")
+        serverB = await startServer(b.cert, b.key, "from-B")
+    })
+
+    afterAll(async () => {
+        await serverA?.close()
+        await serverB?.close()
+        if (dir) rmSync(dir, {recursive: true, force: true})
+    })
+
+    afterEach(() => {
+        vi.unstubAllGlobals()
+    })
+
+    it('accepts a server whose cert fingerprint matches the pin', async () => {
+        const client = createClient(PingApi, {url: ""})
+        const res = await inScope(
+            {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: serverA.fingerprint256}},
+            () => client.ping({msg: "hi"}),
+        )
+        expect(res.msg).toBe("from-A")
+    })
+
+    it('rejects a fingerprint mismatch before any request bytes flow', async () => {
+        const before = serverA.reqCount()
+        const client = createClient(PingApi, {url: ""})
+        const bogus = "a".repeat(64)
+        const res = await inScope(
+            {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: bogus}},
+            () => client.ping({msg: "hi"}).asResult(),
+        )
+        expect(res.success).toBe(false)
+        expect(res).toBeInstanceOf(SERVER_ERROR)
+        if (res instanceof SERVER_ERROR) {
+            // fetch surfaces a connector failure as `TypeError: fetch failed` with the real cause attached.
+            const original = res.getDebugContext()?.originalError as (Error & {cause?: Error}) | undefined
+            const chain = `${original?.message ?? ""} ${original?.cause?.message ?? ""}`
+            expect(chain).toMatch(/fingerprint mismatch/i)
+        }
+        expect(serverA.reqCount()).toBe(before)
+    })
+
+    it('isolates concurrent ops in separate context scopes — no cross-context bleed', async () => {
+        const client = createClient(PingApi, {url: ""})
+        const callA = inScope(
+            {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: serverA.fingerprint256}},
+            () => client.ping({msg: "a"}),
+        )
+        const callB = inScope(
+            {host: "127.0.0.1", port: serverB.port, tlsPin: {fingerprint256: serverB.fingerprint256}},
+            () => client.ping({msg: "b"}),
+        )
+        const [resA, resB] = await Promise.all([callA, callB])
+        expect(resA.msg).toBe("from-A")
+        expect(resB.msg).toBe("from-B")
+    })
+
+    it('reuses a pooled connection per fingerprint; invalidate forces a fresh one', async () => {
+        // Dedicated server with a fresh fingerprint — the agent cache is module-global, so a
+        // fingerprint dialed by another test would already have a pooled socket.
+        const c = genCert(dir, "serverC")
+        const serverC = await startServer(c.cert, c.key, "from-C")
+        try {
+            const client = createClient(PingApi, {url: ""})
+            const pin = {host: "127.0.0.1", port: serverC.port, tlsPin: {fingerprint256: serverC.fingerprint256}}
+            await inScope(pin, () => client.ping({msg: "1"}))
+            await new Promise(r => setTimeout(r, 150))   // let undici return the socket to the pool
+            const afterFirst = serverC.connCount()
+            await inScope(pin, () => client.ping({msg: "2"}))
+            expect(serverC.connCount()).toBe(afterFirst)   // same fingerprint → pooled socket reused
+
+            invalidateTlsPinAgent(serverC.fingerprint256)
+            await inScope(pin, () => client.ping({msg: "3"}))
+            expect(serverC.connCount()).toBe(afterFirst + 1)   // fresh agent → new connection
+        } finally {
+            await serverC.close()
+        }
+    })
+
+    it('pins via client config (connectionSettings) — no context key needed', async () => {
+        const PublicApi = new GGHttpSchema({
+            contract: PingContract,
+            pathPrefix: "api/ping",
+            routes: {ping: GGRpc.POST("ping")},
+        })
+        const client = createClient(PublicApi, {
+            url: "",
+            connectionSettings: {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: serverA.fingerprint256}},
+        })
+        const res = await client.ping({msg: "hi"})
+        expect(res.msg).toBe("from-A")
+    })
+
+    it('middleware overlays client config — the .set() pin wins', async () => {
+        const client = createClient(PingApi, {
+            url: "",
+            // config defaults to server A, but the in-scope pin targets server B and must win.
+            connectionSettings: {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: serverA.fingerprint256}},
+        })
+        const res = await inScope(
+            {host: "127.0.0.1", port: serverB.port, tlsPin: {fingerprint256: serverB.fingerprint256}},
+            () => client.ping({msg: "hi"}),
+        )
+        expect(res.msg).toBe("from-B")
+    })
+
+    it('falls back to fetch when no pin is set', async () => {
+        const fetchSpy = vi.fn(async () => new Response(
+            JSON.stringify({success: true, type: "OK", data: {msg: "fetched"}}),
+            {status: 200, headers: {"content-type": "application/json"}},
+        ))
+        vi.stubGlobal("fetch", fetchSpy)
+        const client = createClient(PingApi, {url: "http://example.test"})
+        const res = await client.ping({msg: "hi"})
+        expect(res.msg).toBe("fetched")
+        expect(fetchSpy).toHaveBeenCalledOnce()
+    })
+
+    it('throws in the browser when settings are present, but not when absent', async () => {
+        vi.stubGlobal("window", {document: {}})
+
+        const pinnedClient = createClient(PingApi, {
+            url: "",
+            connectionSettings: {host: "127.0.0.1", port: serverA.port, tlsPin: {fingerprint256: serverA.fingerprint256}},
+        })
+        const res = await pinnedClient.ping({msg: "hi"}).asResult()
+        expect(res.success).toBe(false)
+        if (res instanceof SERVER_ERROR) {
+            expect(res.context?.displayMessage ?? "").toMatch(/node-only/i)
+        }
+
+        // No settings set → behaves like a normal fetch client even in the browser.
+        const fetchSpy = vi.fn(async () => new Response(
+            JSON.stringify({success: true, type: "OK", data: {msg: "fetched"}}),
+            {status: 200, headers: {"content-type": "application/json"}},
+        ))
+        vi.stubGlobal("fetch", fetchSpy)
+        const plainClient = createClient(PingApi, {url: "http://example.test"})
+        const ok = await plainClient.ping({msg: "hi"})
+        expect(ok.msg).toBe("fetched")
+    })
+})
+
+describe('connection settings — custom CA & mTLS', () => {
+
+    let dir: string
+    let srvCa: TestCa
+    let server: {cert: string; key: string}
+    let clientPem: {cert: string; key: string}
+    let caServer: TestServer
+    let mtlsServer: TestServer
+
+    beforeAll(async () => {
+        dir = mkdtempSync(join(tmpdir(), "gg-tls-"))
+        srvCa = genCa(dir, "srv")
+        server = genSignedCert(dir, "server", srvCa, "127.0.0.1")   // SAN so hostname verification passes
+        const clientCa = genCa(dir, "client")
+        clientPem = genSignedCert(dir, "clientcert", clientCa)
+        caServer = await startServer(server.cert, server.key, "from-ca-server")
+        mtlsServer = await startServer(server.cert, server.key, "from-mtls-server", {
+            requestCert: true,
+            rejectUnauthorized: true,
+            ca: clientCa.crt,   // verify the client cert against this CA
+        })
+    })
+
+    afterAll(async () => {
+        await caServer?.close()
+        await mtlsServer?.close()
+        if (dir) rmSync(dir, {recursive: true, force: true})
+    })
+
+    it('verifies the server against a custom ca', async () => {
+        const client = createClient(PingApi, {
+            url: "",
+            connectionSettings: {host: "127.0.0.1", port: caServer.port, ca: srvCa.crt},
+        })
+        const res = await client.ping({msg: "hi"})
+        expect(res.msg).toBe("from-ca-server")
+    })
+
+    it('rejects a server signed by an untrusted ca (no ca provided)', async () => {
+        const client = createClient(PingApi, {url: `https://127.0.0.1:${caServer.port}`})
+        const res = await client.ping({msg: "hi"}).asResult()
+        expect(res.success).toBe(false)
+    })
+
+    it('presents a client certificate for mTLS', async () => {
+        const client = createClient(PingApi, {
+            url: "",
+            connectionSettings: {host: "127.0.0.1", port: mtlsServer.port, ca: srvCa.crt, clientCert: clientPem},
+        })
+        const res = await client.ping({msg: "hi"})
+        expect(res.msg).toBe("from-mtls-server")
+    })
+
+    it('mTLS server rejects a client with no certificate', async () => {
+        const client = createClient(PingApi, {
+            url: "",
+            connectionSettings: {host: "127.0.0.1", port: mtlsServer.port, ca: srvCa.crt},
+        })
+        const res = await client.ping({msg: "hi"}).asResult()
+        expect(res.success).toBe(false)
+    })
+})

package/src/client/nodeConnectionTransport.node.ts

@@ -0,0 +1,181 @@
+import {createHash} from "node:crypto"
+import type {TLSSocket} from "node:tls"
+import {Agent, buildConnector, type Dispatcher} from "undici"
+import type {GGConnectionSettings} from "@grest-ts/context"
+import type {GGHttpTransport} from "./GGHttpSchema.createClient"
+
+/**
+ * Node default transport: ordinary `fetch`, dialing through an undici dispatcher built from the
+ * request's connection settings. `fetch` keeps the wire correct (real Response/headers/streaming,
+ * FormData, abort, redirects); the dispatcher is the one node-only seam. When no settings call for
+ * a custom dispatcher it's plain `fetch` — identical to the browser path.
+ */
+
+const DEFAULT_MAX_AGENTS = 2048
+const DEFAULT_IDLE_TTL_MS = 5 * 60_000
+const DEFAULT_SWEEP_INTERVAL_MS = 60_000
+
+function normalizeFingerprint(input: string): string {
+    return input.replace(/:/g, "").toLowerCase()
+}
+
+/** Which settings shape the TLS connection (and therefore the dispatcher). */
+function needsDispatcher(s: GGConnectionSettings): boolean {
+    return !!(s.tlsPin || s.ca || s.clientCert)
+}
+
+/** tls.connect options shared by both the pinned and the standard connector. */
+function connectOptions(s: GGConnectionSettings) {
+    return {
+        ca: s.ca,
+        cert: s.clientCert?.cert,
+        key: s.clientCert?.key,
+        passphrase: s.clientCert?.passphrase,
+    }
+}
+
+/**
+ * Build the undici Agent for a set of TLS settings.
+ *  - tlsPin → self-signed pinning: `rejectUnauthorized: false` (skip the CA chain — the fingerprint
+ *    replaces it) + verify the peer cert's fingerprint once connected, destroying the socket on
+ *    mismatch before any request bytes flow. A resumed TLS session doesn't re-send the cert and
+ *    proves knowledge of the original master secret, so the re-check is safely skipped.
+ *    `rejectUnauthorized: false` WITHOUT the fingerprint check is a full MITM hole.
+ *  - otherwise → standard verification, optionally against a custom `ca` and presenting a
+ *    `clientCert` for mTLS.
+ */
+function buildAgent(s: GGConnectionSettings): Agent {
+    const connect = connectOptions(s)
+    const pin = s.tlsPin
+    if (!pin) {
+        return new Agent({connect})
+    }
+    const expected = normalizeFingerprint(pin.fingerprint256)
+    if (!/^[0-9a-f]{64}$/.test(expected)) {
+        throw new Error(`pinned TLS: fingerprint must be 64 hex chars (got "${pin.fingerprint256}")`)
+    }
+    const baseConnector = buildConnector({...connect, rejectUnauthorized: false, servername: pin.servername})
+    return new Agent({
+        connect(opts, cb) {
+            baseConnector(opts, (err, socket) => {
+                if (err) return cb(err, null)
+                const tls = socket as TLSSocket
+                if (typeof tls.getPeerX509Certificate !== "function") {
+                    socket.destroy()
+                    return cb(new Error("pinned TLS requires an https target"), null)
+                }
+                if (!tls.isSessionReused()) {
+                    const raw = tls.getPeerX509Certificate()?.fingerprint256
+                    const actual = raw ? normalizeFingerprint(raw) : undefined
+                    if (actual !== expected) {
+                        tls.destroy()
+                        return cb(new Error(`pinned TLS: cert fingerprint mismatch — expected ${expected}, got ${actual ?? "<none>"}`), null)
+                    }
+                }
+                cb(null, socket)
+            })
+        },
+    })
+}
+
+/**
+ * Stable key per distinct TLS config, so each pools its own connections. Pin-only (the common,
+ * high-frequency case) keys off the cheap fingerprint; CA/mTLS hash the (larger) PEM material.
+ */
+function agentKey(s: GGConnectionSettings): string {
+    const pin = s.tlsPin ? `${normalizeFingerprint(s.tlsPin.fingerprint256)}|${s.tlsPin.servername ?? ""}` : ""
+    if (!s.ca && !s.clientCert) return `pin:${pin}`
+    return "tls:" + createHash("sha256").update(JSON.stringify([
+        pin,
+        s.ca ?? null,
+        s.clientCert?.cert ?? null,
+        s.clientCert?.key ?? null,
+        s.clientCert?.passphrase ?? null,
+    ])).digest("hex")
+}
+
+// One Agent per distinct TLS config. Pinned fingerprints rotate per server start, so those entries
+// are per-server-run; invalidate() drops them after a restart, and the LRU cap + idle TTL bound the
+// map for long-lived multi-target processes that never invalidate.
+class TlsAgentCache {
+
+    private readonly agents = new Map<string, {agent: Agent; fingerprint?: string; lastUsed: number}>()
+    private readonly sweepTimer: NodeJS.Timeout
+
+    constructor() {
+        this.sweepTimer = setInterval(() => this.sweepIdle(), DEFAULT_SWEEP_INTERVAL_MS)
+        this.sweepTimer.unref()
+    }
+
+    get(settings: GGConnectionSettings): Agent {
+        const key = agentKey(settings)
+        const existing = this.agents.get(key)
+        if (existing) {
+            existing.lastUsed = Date.now()
+            this.agents.delete(key)
+            this.agents.set(key, existing)
+            return existing.agent
+        }
+        const agent = buildAgent(settings)
+        const fingerprint = settings.tlsPin ? normalizeFingerprint(settings.tlsPin.fingerprint256) : undefined
+        this.agents.set(key, {agent, fingerprint, lastUsed: Date.now()})
+        while (this.agents.size > DEFAULT_MAX_AGENTS) {
+            const lru = this.agents.keys().next().value
+            if (lru === undefined) break
+            this.drop(lru)
+        }
+        return agent
+    }
+
+    invalidateFingerprint(fingerprint: string): void {
+        const fp = normalizeFingerprint(fingerprint)
+        for (const [key, entry] of this.agents) {
+            if (entry.fingerprint === fp) this.drop(key)
+        }
+    }
+
+    private sweepIdle(): void {
+        const cutoff = Date.now() - DEFAULT_IDLE_TTL_MS
+        for (const [key, entry] of this.agents) {
+            if (entry.lastUsed < cutoff) this.drop(key)
+        }
+    }
+
+    private drop(key: string): void {
+        const existing = this.agents.get(key)
+        if (!existing) return
+        // close() drains in-flight requests then closes idle sockets; destroy() is the hard fallback.
+        existing.agent.close().catch(() => existing.agent.destroy())
+        this.agents.delete(key)
+    }
+}
+
+const AGENT_CACHE = new TlsAgentCache()
+
+/** Drop the pooled dispatcher(s) for a pinned fingerprint so stale sockets don't linger after a restart. */
+export function invalidateTlsPinAgent(fingerprint256: string): void {
+    AGENT_CACHE.invalidateFingerprint(fingerprint256)
+}
+
+/**
+ * Map connection settings onto an undici dispatcher — the single extensibility seam. Future
+ * settings (proxy → ProxyAgent, http2 → allowH2, …) add a branch here, with no change to the
+ * transport or the middleware hook.
+ */
+function dispatcherFor(settings: GGConnectionSettings): Dispatcher | undefined {
+    if (needsDispatcher(settings)) return AGENT_CACHE.get(settings)
+    return undefined
+}
+
+/** url is path-only for a url-less client; settings.host (when set) supplies the origin. */
+function dialUrl(url: string, settings: GGConnectionSettings): string {
+    if (!settings.host) return url
+    const port = settings.port ? `:${settings.port}` : ""
+    return `https://${settings.host}${port}${url}`
+}
+
+export const nodeDefaultTransport: GGHttpTransport = (url, init) => {
+    const {connectionSettings = {}, ...rest} = init
+    const dispatcher = dispatcherFor(connectionSettings)
+    return fetch(dialUrl(url, connectionSettings), {...rest, dispatcher} as RequestInit & {dispatcher?: Dispatcher})
+}