cartethyia 2.7.9 → 2.8.1

package/src/network/egress/factory.ts

@@ -0,0 +1,191 @@
+/**
+ * `ValidatedNetworkBindingFactory` — one binding point for every validated
+ * egress capability: fetch, profile-fetch, HTTP/2 bidi, WebSocket, and
+ * one-shot DNS+SSRF resolution.
+ *
+ * Direct egress resolves and validates *every* DNS answer for the hostname,
+ * pins the chosen public address, and keeps TLS SNI pointed at the validated
+ * hostname — so a rebind between check and connect cannot retarget the socket,
+ * and the certificate still validates against the name the caller asked for.
+ * Pooled egress reuses the selected tenant pool's CONNECT/SOCKS tunnel and
+ * accounts the tunnel's bytes to that pool, exactly as `fetch` does.
+ */
+import { GatewayError } from "../../protocol/gateway-error";
+import type { SsrfPolicy } from "../../config/network";
+import { createValidatedFetch, type ValidatedFetch } from "./fetch";
+import { isAddressAllowed, resolveAndValidateOnce, type ValidatedDestination } from "../ssrf";
+import { tlsProfileOf, type TlsProfile } from "./tls-profile";
+import { assertBidiTarget, dialDirect, dialThroughPool } from "./dial";
+import { openBidiStream } from "./bidi-session";
+import { connectValidatedWebSocket } from "./ws";
+import type { ValidatedOutboundWebSocket, ValidatedOutboundHttp2Bidi } from "../../providers/provider-contracts";
+import { PoolBindingError, type PoolAgent } from "../pool/agent";
+import type { PoolAgentResolver } from "../pool/resolver";
+
+export class ValidatedNetworkBindingFactory {
+  private readonly directFetch: ValidatedFetch;
+  /**
+   * One `ValidatedFetch` per resolved pool agent. Building the closure (dialer,
+   * relay setup, redirect loop) on every request through a pool was pure
+   * churn; keying by the agent object means a released agent is naturally
+   * collected (new builds mint a new agent) so no explicit invalidation is
+   * needed.
+   */
+  private readonly pooledFetchCache = new WeakMap<PoolAgent, ValidatedFetch>();
+  /** Default TLS ClientHello profile for direct https dials. */
+  private readonly tlsProfile: TlsProfile;
+
+  constructor(
+    private readonly policy: SsrfPolicy = {},
+    fetchFn?: typeof fetch,
+    private readonly poolResolver?: PoolAgentResolver,
+    tlsProfile: TlsProfile = "default",
+  ) {
+    this.directFetch = createValidatedFetch({
+      policy,
+      ...(fetchFn ? { fetchFn } : {}),
+      tlsProfile,
+    });
+    this.tlsProfile = tlsProfile;
+  }
+
+  /**
+   * One-shot DNS resolution + SSRF validation for direct egress targets:
+   * every resolved address (all families, not just the first answer) must
+   * pass the SSRF policy, and the validated destination pins the address so
+   * the subsequent socket cannot be re-pointed at a private/link-local host
+   * by a DNS rebind between check and connect.
+   */
+  resolve(hostname: string, signal: AbortSignal, port = 443): Promise<ValidatedDestination> {
+    return resolveAndValidateOnce(hostname, this.policy, signal, port);
+  }
+
+  /**
+   * Without `networkPoolId` (or when no pool resolver is configured), dispatch
+   * through validated direct egress. With one, route through that pool's
+   * validated agent. A pool configuration failure is returned to the caller;
+   * configured egress is never silently replaced with direct traffic.
+   */
+  fetch(networkPoolId?: string, tenantId?: string): ValidatedFetch {
+    if (!networkPoolId || !this.poolResolver || !tenantId) return this.directFetch;
+    const { poolResolver, policy } = this;
+    return async (input, init) => {
+      try {
+        const agent = await poolResolver.resolveAgent(networkPoolId, tenantId);
+        let validated = this.pooledFetchCache.get(agent);
+        if (validated === undefined) {
+          validated = createValidatedFetch({ policy, agent });
+          this.pooledFetchCache.set(agent, validated);
+        }
+        return await validated(input, init);
+      } catch (error) {
+        if (error instanceof PoolBindingError) {
+          throw new GatewayError(
+            "proxy_pool_unhealthy",
+            503,
+            "Configured proxy pool could not be established (request {requestId}). This bridge looks shaky — repair or reroute 🔧",
+            { poolId: networkPoolId, reason: error.message.slice(0, 200) },
+            "network",
+          );
+        }
+        throw error;
+      }
+    };
+  }
+
+  webSocket(networkPoolId?: string, tenantId?: string): ValidatedOutboundWebSocket {
+    return async (url, headers, signal) => {
+      if (url.protocol !== "wss:") {
+        throw new GatewayError("invalid_request", 400, "validated WebSocket egress requires wss (request {requestId}). Check the shape of what you sent — then resend 🪞");
+      }
+      if (url.username || url.password || url.hash || (url.port !== "" && url.port !== "443")) {
+        throw new GatewayError("invalid_request", 400, "invalid validated WebSocket target (request {requestId}). Check the shape of what you sent — then resend 🪞");
+      }
+      const hostname = url.hostname;
+      if (!hostname) throw new GatewayError("invalid_request", 400, "WebSocket target hostname is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
+      const destination = await this.resolve(hostname, signal, 443);
+      if (!isAddressAllowed(destination.resolvedAddress, this.policy)) {
+        throw new GatewayError("invalid_request", 400, "unsafe upstream address rejected (request {requestId}). Check the shape of what you sent — then resend 🪞");
+      }
+      let agent: PoolAgent | undefined;
+      if (networkPoolId || tenantId) {
+        if (!networkPoolId || !tenantId || !this.poolResolver) {
+          throw new GatewayError("proxy_pool_unhealthy", 503, "configured WebSocket proxy pool could not be established (request {requestId}). This bridge looks shaky — repair or reroute 🔧");
+        }
+        try {
+          agent = await this.poolResolver.resolveAgent(networkPoolId, tenantId);
+        } catch (error) {
+          if (error instanceof PoolBindingError) {
+            throw new GatewayError("proxy_pool_unhealthy", 503, "configured WebSocket proxy pool could not be established (request {requestId}). This bridge looks shaky — repair or reroute 🔧");
+          }
+          throw error;
+        }
+      }
+      return connectValidatedWebSocket(url, headers, signal, destination, agent);
+    };
+  }
+
+  /**
+   * Validated bidirectional HTTP/2 egress for one writable streaming request.
+   *
+   * Direct egress resolves and validates *every* DNS answer for the hostname,
+   * pins the chosen public address, and keeps TLS SNI pointed at the validated
+   * hostname — so a rebind between check and connect cannot retarget the socket,
+   * and the certificate still validates against the name the caller asked for.
+   * Pooled egress reuses the selected tenant pool's CONNECT/SOCKS tunnel and
+   * accounts the tunnel's bytes to that pool, exactly as `fetch` does.
+   *
+   * Credentials in the authority, fragments, non-443 ports, IP literals, and
+   * hostnames outside `allowHostname` are refused before anything is dialed: a
+   * bidi stream carries the account credential for its whole lifetime, so the
+   * target is checked once here rather than trusted to each caller.
+   */
+  http2Bidi(networkPoolId?: string, tenantId?: string): ValidatedOutboundHttp2Bidi {
+    return async (url, headers, options) => {
+      assertBidiTarget(url);
+      const { hostname } = url;
+      if (options?.allowHostname !== undefined && !options.allowHostname(hostname)) {
+        throw new GatewayError("invalid_request", 400, "HTTP/2 target host is not allowlisted (request {requestId}). All roads blocked — time to find a new route 🗺️");
+      }
+      const signal = options?.signal ?? AbortSignal.timeout(15_000);
+      const profile = tlsProfileOf(this.tlsProfile);
+      // Validation runs on every new connection, not once per capability: a
+      // long-lived Run is re-opened after a session dies, and a hostname that
+      // resolved safely the first time is not safe the twentieth.
+      const destination = await this.resolve(hostname, signal, 443);
+      if (!isAddressAllowed(destination.resolvedAddress, this.policy)) {
+        throw new GatewayError("invalid_request", 400, "unsafe upstream address rejected (request {requestId}). All roads blocked — time to find a new route 🗺️");
+      }
+      // Mirrors `fetch`: no pool selected (or none configured) means validated
+      // *direct* egress, which is already resolved and SSRF-checked above.
+      // Requiring a pool whenever a tenant id was supplied made bidi-only
+      // providers (Cursor) unreachable on every install without a pool, even
+      // though the equivalent `fetch` path dials direct there.
+      if (networkPoolId !== undefined || tenantId !== undefined) {
+        if (networkPoolId === undefined || tenantId === undefined || this.poolResolver === undefined) {
+          const socket = await dialDirect(destination, signal, profile);
+          return openBidiStream(socket, url, headers, options ?? {});
+        }
+        let agent: PoolAgent;
+        try {
+          agent = await this.poolResolver.resolveAgent(networkPoolId, tenantId);
+        } catch (error) {
+          if (error instanceof PoolBindingError) {
+            throw new GatewayError(
+              "proxy_pool_unhealthy",
+              503,
+              "Configured proxy pool could not be established (request {requestId}). This bridge looks shaky — repair or reroute 🔧",
+              { poolId: networkPoolId, reason: error.message.slice(0, 200) },
+              "network",
+            );
+          }
+          throw error;
+        }
+        const socket = await dialThroughPool(agent, hostname, signal, profile);
+        return openBidiStream(socket, url, headers, options ?? {});
+      }
+      const socket = await dialDirect(destination, signal, profile);
+      return openBidiStream(socket, url, headers, options ?? {});
+    };
+  }
+}

package/src/network/{outbound-fetch.ts → egress/fetch.ts}

@@ -1,14 +1,77 @@
 // Validated fetch: SSRF-guarded outbound fetch with optional pool-agent support.
-import { GatewayError } from "../protocol/gateway-error";
+import { GatewayError } from "../../protocol/gateway-error";
 import { request as httpRequest, Agent as HttpAgent } from "node:http";
 import { request as httpsRequest, Agent as HttpsAgent } from "node:https";
 import { Agent as UndiciAgent, fetch as undiciFetch, type UndiciRequestInit } from "undici";
 import { SocksProxyAgent } from "socks-proxy-agent";
-import { resolveAllAddresses, validateResolvedAddresses } from "./ssrf";
-import type { SsrfPolicy } from "../config/network";
-import { isProxyAgentPair, type ProxyAgentPair } from "./pool/agent";
-import { metrics } from "../observability/metrics";
-import { trackNetworkCall } from "../observability/performance-metrics";
+import { resolveAllAddresses, validateResolvedAddresses } from "../ssrf";
+import type { SsrfPolicy } from "../../config/network";
+import { isProxyAgentPair, type ProxyAgentPair } from "../pool/agent";
+import { metrics } from "../../observability/metrics";
+import { trackNetworkCall } from "../../observability/performance-metrics";
+import { nodeTlsOptions, tlsProfileOf, type TlsProfile, type TlsProfileConfig } from "./tls-profile";
+
+/**
+ * Keep-alive socket lifetime for outbound direct dials.
+ *
+ * Some upstream edges (accelerated hosting, CDN front doors) drop idle or
+ * silently-errored keep-alive connections without sending a TCP RST. undici
+ * keeps those dead sockets in its pool — the default `keepAliveMaxTimeout`
+ * is 600s, and an upstream `Keep-Alive` header can push it even higher — so a
+ * retry reuses a poisoned socket and hangs until the connect timeout. Capping
+ * the TTL (both fields) keeps a dead socket from being reused; a fresh dial
+ * is also replayed once when a pooled socket dies before response headers.
+ */
+export const DEFAULT_KEEPALIVE_TIMEOUT_MS = 4_000;
+/** Fresh-socket retry agent: keep-alive effectively disabled (1 ms). */
+const FRESH_SOCKET_KEEPALIVE_TIMEOUT_MS = 1;
+
+/** Error codes that prove a pooled keep-alive socket died mid-flight. */
+const STALE_SOCKET_ERROR_CODES: ReadonlySet<string> = new Set([
+  "UND_ERR_SOCKET",
+  "ECONNRESET",
+  "EPIPE",
+  "UND_ERR_HEADERS_TIMEOUT",
+]);
+
+/** Error codes that prove the host itself is unreachable — never a stale socket. */
+const NON_STALE_SOCKET_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_INVALID_ARG",
+]);
+
+/** Message fragments that prove the other side closed a pooled connection. */
+const STALE_SOCKET_ERROR_SUBSTRINGS: readonly string[] = [
+  "other side closed",
+  "socket hang up",
+];
+
+/** True when `error` proves a pooled keep-alive socket died before headers. */
+export function isStaleSocketError(error: unknown): boolean {
+  if (!(error instanceof Error) || error.name === "AbortError") return false;
+  const cause = (error as { cause?: unknown }).cause;
+  const code =
+    (cause !== null && typeof cause === "object" && "code" in cause
+      ? (cause as { code?: unknown }).code
+      : undefined) ?? (error as { code?: unknown }).code;
+  if (typeof code === "string") {
+    if (NON_STALE_SOCKET_ERROR_CODES.has(code)) return false;
+    if (STALE_SOCKET_ERROR_CODES.has(code)) return true;
+  }
+  const message = `${error.message} ${cause instanceof Error ? cause.message : ""}`.toLowerCase();
+  return STALE_SOCKET_ERROR_SUBSTRINGS.some((fragment) => message.includes(fragment));
+}
+
+/** True when the request body can be safely replayed (not a locked stream). */
+function isBodyReplaySafe(body: BodyInit | null | undefined): boolean {
+  if (body === null || body === undefined) return true;
+  return !(typeof body === "object" && "locked" in body && body.locked === true);
+}
 // Validated fetch — single egress with ProxyAgent support
 interface ValidatedFetchOptions {
   readonly fetchFn?: typeof fetch;
@@ -27,6 +90,18 @@ interface ValidatedFetchOptions {
    * Defaults to undici's fetch; injectable for offline tests.
    */
   readonly socksFetch?: (input: RequestInfo | URL, init?: UndiciRequestInit) => Promise<Response>;
+  /**
+   * TLS ClientHello profile for direct https dials. `"default"` (or absent)
+   * keeps the runtime's own TLS stack; a named profile (see `tls-profile.ts`)
+   * dials through a Node https agent configured with that profile's OpenSSL
+   * options, so the wire fingerprint matches the impersonated client.
+   */
+  readonly tlsProfile?: TlsProfile;
+  /**
+   * CA bundle for profile dials (`https.Agent({ ca })`). Defaults to the
+   * system store; set it to trust a private/custom CA.
+   */
+  readonly ca?: string | Buffer | Array<string | Buffer>;
 }
 export type ValidatedFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
@@ -91,7 +166,7 @@ function socksDispatcherFor(agent: SocksProxyAgent): UndiciAgent {
   let dispatcher = socksDispatcherCache.get(agent);
   if (!dispatcher) {
     dispatcher = new UndiciAgent({
-      connect: async (opts) => {
+      connect: async (opts: Record<string, unknown>) => {
         const o = opts as {
           hostname?: string;
           port?: number | string;
@@ -108,14 +183,63 @@ function socksDispatcherFor(agent: SocksProxyAgent): UndiciAgent {
           } as never,
         );
       },
-    });
+      // Cap the pooled socket lifetime so a silently-dropped keep-alive
+      // connection is not reused by a later request.
+      keepAliveTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+      keepAliveMaxTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+    } as unknown as ConstructorParameters<typeof UndiciAgent>[0]);
     socksDispatcherCache.set(agent, dispatcher);
   }
   return dispatcher;
 }
 
 /**
- * One dial, always through `fetch`.
+ * A Node `https` agent whose connections are dialed with a chosen TLS profile.
+ *
+ * The agent's `createConnection` is the only knob that reaches the ClientHello
+ * through OpenSSL: it lets `tls.connect` run with the profile's cipher list,
+ * TLS 1.3 suite order, ALPN, and version bounds. Used only when a profile is
+ * requested; the runtime-native fetch stays the default for everything else.
+ */
+export function createProfileAgent(profile: TlsProfileConfig, ca?: string | Buffer | Array<string | Buffer>): HttpsAgent {
+  // Straight option passthrough — no custom `createConnection`. Bun's
+  // Node-compat layer ignores a user-supplied `createConnection` on the agent
+  // (verified live 2026-11-11: the dial failed with ERR_SOCKET_CLOSED and no
+  // ClientHello reached the sniffer), but it honors the standard TLS options
+  // on the agent itself — `ALPNProtocols` switched the ALPN extension and
+  // `ciphers` narrowed the offered suite list in capture. The request path
+  // stays the plain https client with the profile's fingerprint.
+  return new HttpsAgent({
+    ...nodeTlsOptions(profile),
+    ...(ca === undefined ? {} : { ca }),
+  } as unknown as HttpsAgent);
+}
+
+/**
+ * A shared undici dispatcher whose keep-alive socket lifetime is capped.
+ *
+ * Direct dials go through the runtime's own fetch; when a socks dispatcher is
+ * in play (pool egress) the same TTL cap applies. A fresh-socket dispatcher
+ * (`keepAliveTimeout: 1ms`) backs the stale-socket replay so a retry never
+ * reuses the poisoned connection.
+ */
+let directDispatcherCache: { agent: UndiciAgent; fresh: UndiciAgent } | undefined;
+function directDispatchers(): { agent: UndiciAgent; fresh: UndiciAgent } {
+  directDispatcherCache ??= {
+    agent: new UndiciAgent({
+      keepAliveTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+      keepAliveMaxTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+    } as unknown as ConstructorParameters<typeof UndiciAgent>[0]),
+    fresh: new UndiciAgent({
+      keepAliveTimeout: FRESH_SOCKET_KEEPALIVE_TIMEOUT_MS,
+      keepAliveMaxTimeout: FRESH_SOCKET_KEEPALIVE_TIMEOUT_MS,
+    } as unknown as ConstructorParameters<typeof UndiciAgent>[0]),
+  };
+  return directDispatcherCache;
+}
+
+/**
+ * Dial one request, always through `fetch`.
  *
  * The runtime's own fetch (Bun/Undici) is the transport the clients this
  * gateway impersonates actually use, and several upstreams meter per client
@@ -141,6 +265,7 @@ async function dial(
   proxyUrl: string | undefined,
   dispatcher?: UndiciAgent,
   socksFetch: (input: RequestInfo | URL, init?: UndiciRequestInit) => Promise<Response> = undiciFetch,
+  freshSocket = false,
 ): Promise<Response> {
   const headers = new Headers(init.headers);
   const rawBody = init.body;
@@ -157,13 +282,16 @@ async function dial(
     return await socksFetch(url, {
       ...init,
       headers,
-      dispatcher,
+      dispatcher: freshSocket ? directDispatchers().fresh : dispatcher,
     });
   }
   return await fetchFn(url, {
     ...init,
     headers,
     ...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
+    // Fresh-socket replay uses the capped undici dispatcher directly so a
+    // retry never reuses the pooled connection that just died.
+    ...(freshSocket ? { dispatcher: directDispatchers().fresh } : {}),
   });
 }
 
@@ -177,7 +305,7 @@ async function dial(
  * after the SSRF resolve/validate pass and only when no pool/relay agent owns
  * the dial, so the security boundary is unchanged.
  */
-function nodeDial(url: URL, init: RequestInit): Promise<Response> {
+function nodeDial(url: URL, init: RequestInit, agent?: HttpsAgent): Promise<Response> {
   return new Promise((resolve, reject) => {
     const mod = url.protocol === "http:" ? httpRequest : httpsRequest;
     const headers: Record<string, string> = {};
@@ -195,8 +323,10 @@ function nodeDial(url: URL, init: RequestInit): Promise<Response> {
       payload = body;
     } else if (body instanceof Uint8Array) {
       payload = Buffer.from(body);
+    } else if (body instanceof ArrayBuffer) {
+      payload = Buffer.from(new Uint8Array(body));
     } else if (body !== null && body !== undefined) {
-      reject(new TypeError("nodeDial only supports string/Buffer/Uint8Array bodies"));
+      reject(new TypeError("nodeDial only supports string/Buffer/Uint8Array/ArrayBuffer bodies"));
       return;
     }
     if (payload !== undefined) headers["content-length"] = String(payload.byteLength);
@@ -205,20 +335,30 @@ function nodeDial(url: URL, init: RequestInit): Promise<Response> {
       {
         method: (init.method ?? "GET").toUpperCase(),
         headers,
+        ...(agent === undefined ? {} : { agent }),
         ...(init.signal === undefined ? {} : { signal: init.signal as AbortSignal }),
       },
       (res) => {
-        const chunks: Buffer[] = [];
-        res.on("data", (c: Buffer) => chunks.push(c));
-        res.on("end", () => {
-          resolve(
-            new Response(Buffer.concat(chunks), {
-              status: res.statusCode ?? 200,
-              ...(res.statusMessage === undefined ? {} : { statusText: res.statusMessage }),
-              headers: res.headers as unknown as HeadersInit,
-            }),
-          );
+        // The response body is bridged into a web stream so callers can
+        // consume it incrementally (SSE chat streams) instead of buffering
+        // the entire payload before resolving.
+        const bodyStream = new ReadableStream<Uint8Array>({
+          start(controller) {
+            res.on("data", (c: Buffer) => controller.enqueue(new Uint8Array(c)));
+            res.on("end", () => controller.close());
+            res.on("error", (err: Error) => controller.error(err));
+          },
+          cancel() {
+            res.destroy();
+          },
         });
+        resolve(
+          new Response(bodyStream, {
+            status: res.statusCode ?? 200,
+            ...(res.statusMessage === undefined ? {} : { statusText: res.statusMessage }),
+            headers: res.headers as unknown as HeadersInit,
+          }),
+        );
       },
     );
     req.on("error", reject);
@@ -304,15 +444,41 @@ export function createValidatedFetch(options: ValidatedFetchOptions = {}): Valid
       } else {
         const method = (requestInit.method ?? "GET").toUpperCase();
         const hasBody = requestInit.body !== undefined && requestInit.body !== null;
-        // The runtime fetch cannot carry a body on GET/HEAD, but Qoder's
-        // model-list endpoint requires a signed GET body. When no pool/relay
-        // owns the dial and no injected test fetch is present, dial through the
-        // Node http(s) client (post SSRF validation). Every other case keeps
-        // the existing fetch path.
-        if ((method === "GET" || method === "HEAD") && hasBody && !socksAgent && options.fetchFn === undefined) {
+        const profile = tlsProfileOf(options.tlsProfile ?? "default");
+        // A TLS profile request is a *custom ClientHello* dial: it goes
+        // through a Node https agent configured with the profile's OpenSSL
+        // options, so the wire fingerprint matches the impersonated client.
+        // This path is direct-only (never a pool/relay dial) and rejects
+        // bodies on GET/HEAD like the runtime fetch does — that shape is
+        // still handled by `nodeDial` below.
+        if (profile !== undefined && !socksAgent && configuredAgent === undefined) {
+          response = await nodeDial(url, requestInit, createProfileAgent(profile, options.ca));
+        } else if ((method === "GET" || method === "HEAD") && hasBody && !socksAgent && options.fetchFn === undefined) {
+          // The runtime fetch cannot carry a body on GET/HEAD, but Qoder's
+          // model-list endpoint requires a signed GET body. When no pool/relay
+          // owns the dial and no injected test fetch is present, dial through the
+          // Node http(s) client (post SSRF validation). Every other case keeps
+          // the existing fetch path.
           response = await nodeDial(url, requestInit);
         } else {
-          response = await dial(url, requestInit, fetchFn, proxyUrl, socksAgent ? socksDispatcherFor(socksAgent) : undefined, socksFetch);
+          try {
+            response = await dial(url, requestInit, fetchFn, proxyUrl, socksAgent ? socksDispatcherFor(socksAgent) : undefined, socksFetch);
+          } catch (error) {
+            // A pooled keep-alive socket that died before response headers is
+            // replayed once on a fresh socket. Only errors that *prove* the
+            // socket died qualify; a bare fetch failure (or an abort, or a
+            // locked body) is never replayed — the upstream may already hold
+            // that request and a replay would deliver it twice.
+            if (
+              !requestInit.signal?.aborted &&
+              isBodyReplaySafe(requestInit.body) &&
+              isStaleSocketError(error)
+            ) {
+              response = await dial(url, requestInit, fetchFn, proxyUrl, socksAgent ? socksDispatcherFor(socksAgent) : undefined, socksFetch, true);
+            } else {
+              throw error;
+            }
+          }
         }
       }
       if (response.status < 300 || response.status >= 400) {

package/src/network/egress/tls-profile.ts

@@ -0,0 +1,123 @@
+/**
+ * TLS client-profile registry — "ClientHello/custom" egress support.
+ *
+ * The runtime's own TLS (Bun/BoringSSL) has a fixed ClientHello shape, which
+ * is fine when the client we impersonate is itself Bun — Qoder's desktop
+ * worker runs on Bun and its captured ClientHello (2026-11-11, `api2.qoder.sh`
+ * hijack) matches Bun's default byte-for-byte. But when an upstream meters per
+ * transport fingerprint, the egress layer must be able to dial with a *chosen*
+ * TLS profile instead of the runtime default.
+ *
+ * Node's `tls`/`https` stack (OpenSSL) honors `ciphers`, `ciphersuites`,
+ * `ALPNProtocols`, and `minVersion`/`maxVersion`, and Bun's Node-compat layer
+ * forwards those options into its own handshake — verified live (2026-11-11):
+ * an `https.Agent({ ALPNProtocols: ["h2"] })` changes the ALPN extension, and
+ * `ciphers` changes the offered cipher list. So a profile is real: it is the
+ * set of OpenSSL options that reproduce a target client's ClientHello.
+ *
+ * Profiles are pure data + one helper. They never open sockets; the dial
+ * paths (`outbound-fetch.ts`, `pool/resolver.ts`) apply them.
+ */
+
+/**
+ * One re-playable TLS fingerprint.
+ *
+ * `ciphers` names the TLS 1.2 suite list in OpenSSL order (the order the
+ * ClientHello advertises); `ciphersuites` names the TLS 1.3 suites in order.
+ * `alpn` is the ALPN list in preference order. When a field is absent the
+ * dial path leaves the runtime default in place for that knob.
+ */
+export interface TlsProfileConfig {
+  /** Stable id used to look the profile up (e.g. `"qoder-app"`). */
+  readonly id: string;
+  /** Human description; not sent on the wire. */
+  readonly label: string;
+  /** OpenSSL TLS 1.2 cipher list, client order. */
+  readonly ciphers?: string;
+  /** OpenSSL TLS 1.3 cipher-suites list, client order. */
+  readonly ciphersuites?: string;
+  /** ALPN protocols in preference order. */
+  readonly alpn?: readonly string[];
+  /** OpenSSL/Node TLS version floor (`"TLSv1.2"` / `"TLSv1.3"`). */
+  readonly minVersion?: string;
+  /** OpenSSL/Node TLS version ceiling (`"TLSv1.3"`). */
+  readonly maxVersion?: string;
+}
+
+/** Profile selector accepted by egress options. `"default"` = runtime default. */
+export type TlsProfile = "default" | string;
+
+/**
+ * The Qoder Desktop 0.5.7 chat fingerprint, from the live ClientHello capture
+ * (`documentation/research/qoder/2026-11-11-qoder-desktop-0.5.7-chat-surface-evidence.md`
+ * §9, `hijack/conn.log`): 18 suites in this exact order, ALPN `http/1.1`
+ * only, TLS 1.2–1.3. This is the profile to dial with when an upstream expects
+ * the Qoder desktop client's transport identity.
+ */
+export const QODER_APP_TLS_PROFILE: TlsProfileConfig = {
+  id: "qoder-app",
+  label: "Qoder Desktop 0.5.7 (Bun/1.4.x worker) COSY chat",
+  // TLS 1.3 suites, client order (capture: 1301 1302 1303).
+  ciphersuites:
+    "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256",
+  // TLS 1.2 suites, client order (capture: c02f c02b c030 c02c c027 cca9
+  // cca8 c009 c013 c00a c014 009c 009d 002f 0035).
+  ciphers:
+    "ECDHE-RSA-AES128-GCM-SHA256:" +
+    "ECDHE-ECDSA-AES128-GCM-SHA256:" +
+    "ECDHE-RSA-AES256-GCM-SHA384:" +
+    "ECDHE-ECDSA-AES256-GCM-SHA384:" +
+    "ECDHE-RSA-AES128-CBC-SHA256:" +
+    "ECDHE-ECDSA-CHACHA20-POLY1305:" +
+    "ECDHE-RSA-CHACHA20-POLY1305:" +
+    "ECDHE-ECDSA-AES128-CBC-SHA:" +
+    "ECDHE-RSA-AES128-CBC-SHA:" +
+    "ECDHE-ECDSA-AES256-CBC-SHA:" +
+    "ECDHE-RSA-AES256-CBC-SHA:" +
+    "AES128-GCM-SHA256:" +
+    "AES256-GCM-SHA384:" +
+    "AES128-CBC-SHA:" +
+    "AES256-CBC-SHA",
+  alpn: ["http/1.1"],
+  minVersion: "TLSv1.2",
+  maxVersion: "TLSv1.3",
+};
+
+/** Built-in profiles by id. */
+export const TLS_PROFILES: Readonly<Record<string, TlsProfileConfig>> = {
+  [QODER_APP_TLS_PROFILE.id]: QODER_APP_TLS_PROFILE,
+};
+
+/** Resolves a selector to a concrete profile; `"default"`/unknown → `undefined`. */
+export function tlsProfileOf(profile: TlsProfile): TlsProfileConfig | undefined {
+  if (profile === undefined || profile === "default") return undefined;
+  return TLS_PROFILES[profile];
+}
+
+export interface NodeTlsOptions {
+  ciphers?: string;
+  ciphersuites?: string;
+  ALPNProtocols?: readonly string[];
+  minVersion?: string;
+  maxVersion?: string;
+}
+
+/**
+ * Maps a profile to the `tls`/`https` option set. `alpn` is included by
+ * default; pass `includeAlpn: false` for transports that fix their own ALPN
+ * (HTTP/2 bidi always negotiates `h2`).
+ */
+export function nodeTlsOptions(
+  profile: TlsProfileConfig,
+  includeAlpn = true,
+): NodeTlsOptions {
+  const out: NodeTlsOptions = {};
+  if (profile.ciphers !== undefined) out.ciphers = profile.ciphers;
+  if (profile.ciphersuites !== undefined) out.ciphersuites = profile.ciphersuites;
+  if (includeAlpn && profile.alpn !== undefined && profile.alpn.length > 0) {
+    out.ALPNProtocols = [...profile.alpn];
+  }
+  if (profile.minVersion !== undefined) out.minVersion = profile.minVersion;
+  if (profile.maxVersion !== undefined) out.maxVersion = profile.maxVersion;
+  return out;
+}