@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/lib/errors.ts

@@ -18,6 +18,13 @@ export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
  */
 export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
 export const SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE = "spend_ledger_storage_unavailable";
+/**
+ * Wire code for the undeclared-tool guard's deterministic refusal. Endpoint translators
+ * read it to keep the refusal non-retryable instead of folding it into the transient
+ * upstream-error class. Declared here rather than in the guard module because the shared
+ * envelope formatter decides whether the identity survives serialization.
+ */
+export const UNDECLARED_TOOL_CALL_ERROR_CODE = "undeclared_tool_call";
 
 /** First nonblank string across the canonical upstream error paths, in priority order. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {

package/src/lib/json-byte-size.ts

@@ -1,5 +1,36 @@
 import { TRANSLATOR_MAX_TURN_BYTES, TranslatorBudgetExceededError } from "./translator-budget";
 
+/** Count one JSON string formed from parts without joining, serializing or encoding it. */
+export function jsonStringPartsUtf8Bytes(parts: readonly string[], limit = TRANSLATOR_MAX_TURN_BYTES): number {
+  let bytes = 0;
+  let highSurrogate = false;
+  const add = (count: number) => {
+    if (count > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    bytes += count;
+  };
+  add(2); // The joined string has one pair of JSON quotes.
+  for (const text of parts) {
+    if (text.length > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    for (let i = 0; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (highSurrogate) {
+        highSurrogate = false;
+        if (code >= 0xdc00 && code <= 0xdfff) { add(4); continue; }
+        add(6);
+      }
+      if (code >= 0xd800 && code <= 0xdbff) highSurrogate = true;
+      else if (code === 0x22 || code === 0x5c || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) add(2);
+      else if (code < 0x20) add(6);
+      else if (code < 0x80) add(1);
+      else if (code < 0x800) add(2);
+      else if (code >= 0xdc00 && code <= 0xdfff) add(6);
+      else add(3);
+    }
+  }
+  if (highSurrogate) add(6);
+  return bytes;
+}
+
 /** Measure plain JSON data without allocating its serialized string or UTF-8 copy. */
 export function jsonUtf8Bytes(value: unknown, limit = TRANSLATOR_MAX_TURN_BYTES): number {
   let bytes = 0;

package/src/lib/local-internal-call-capability.ts

@@ -0,0 +1,55 @@
+/**
+ * Process-local internal-call capability.
+ *
+ * Some requests ARE the proxy itself talking to its own data plane: the advisor sidecar's
+ * loopback consultation is the first user. Such a request must be recognized as INTERNAL without
+ * trusting anything the client controls. A client-supplied header value is not evidence — any
+ * external caller can send it — and neither is the peer address: a public listener reached
+ * through Docker, WSL, a tunnel, or port forwarding can present as loopback on the last hop, as
+ * the local-management attestation notes.
+ *
+ * The authority is therefore process-owned: a 256-bit random value minted once per process, kept
+ * in memory only. It is never written to config or disk, never logged, never returned by the
+ * management API, never placed in usage or request metadata, and never forwarded upstream. A new
+ * process mints a new value, so a token captured from an older process is worthless. Comparison
+ * is timing-safe and shape-checked, reusing the same secret shape as the local attestation
+ * module.
+ *
+ * The same primitive is what the vision-describe fence would need for the same reason; wiring
+ * that surface is deliberately left out of this change (recorded as a pre-existing analogous
+ * issue) so the change stays scoped.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+/** Header an internal sidecar presents on its own loopback request. */
+export const ADVISOR_INTERNAL_CAPABILITY_HEADER = "x-opencodex-advisor-internal";
+
+let processCapability: string | null = null;
+
+/**
+ * The current process's internal-call capability. Minted lazily on first use (one random draw,
+ * no I/O), so an install that never enables the advisor never generates one.
+ */
+export function internalCallCapability(): string {
+  if (processCapability === null) processCapability = randomBytes(32).toString("base64url");
+  return processCapability;
+}
+
+/** Test seam: install a deterministic value, or `null` to force a fresh mint. */
+export function setInternalCallCapabilityForTests(value: string | null): void {
+  processCapability = value;
+}
+
+/**
+ * True only when the supplied header value IS this process's capability. Shape-checked first so
+ * a malformed value cannot reach the comparison, then compared in constant time.
+ */
+export function isInternalCallCapability(supplied: string | null | undefined): boolean {
+  if (typeof supplied !== "string" || !isLocalAttestationSecret(supplied)) return false;
+  if (processCapability === null) return false;
+  const expected = processCapability;
+  const suppliedBytes = Buffer.from(supplied);
+  const expectedBytes = Buffer.from(expected);
+  return suppliedBytes.length === expectedBytes.length && timingSafeEqual(suppliedBytes, expectedBytes);
+}

package/src/lib/optional-shutdown-hooks.ts

@@ -70,5 +70,40 @@ export function runOptionalShutdownHooks(): void {
 /** Test-only reset so an isolated lifecycle test does not inherit registrations. */
 export function resetOptionalShutdownHooksForTests(): void {
   hooks.clear();
+  drainStartHooks.clear();
+  drainStartHooksRan = false;
   hooksRan = false;
 }
+
+const drainStartHooks = new Map<string, ShutdownHook>();
+let drainStartHooksRan = false;
+
+/**
+ * Register work that must run the moment a drain begins, before in-flight turns are awaited.
+ * The service health sentinel (#6671) uses it: a deliberate stop whose drain stalls must stay a
+ * stop, so the sentinel is withdrawn before the drain can look unresponsive. Same contract as
+ * {@link registerOptionalShutdownHook}: keyed, synchronous, best-effort, detachable.
+ */
+export function registerDrainStartHook(key: string, hook: ShutdownHook): () => void {
+  drainStartHooks.set(key, hook);
+  return () => {
+    if (drainStartHooks.get(key) === hook) drainStartHooks.delete(key);
+  };
+}
+
+/** Run every drain-start hook. Never throws. */
+export function runDrainStartHooks(): void {
+  drainStartHooksRan = true;
+  for (const [key, hook] of [...drainStartHooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(`[shutdown] drain-start hook "${key}" failed:`, err instanceof Error ? err.message : err);
+    }
+  }
+}
+
+/** Whether a drain has begun in this process; work that must not start mid-drain checks this. */
+export function didRunDrainStartHooks(): boolean {
+  return drainStartHooksRan;
+}

package/src/lib/outbound-credential-registry.ts

@@ -0,0 +1,210 @@
+/**
+ * Process-local record of credential values this process has handed to an upstream.
+ *
+ * Upstream diagnostics (error codes, request ids) are provider-controlled. A gateway can echo a
+ * credential it received back into those fields, and a credential with no recognizable format slips
+ * past pattern redaction. Configured credentials are read directly at capture time (see
+ * server/configured-credentials); this registry adds the values that only exist at send time, such
+ * as a client-forwarded bearer or a plugin-added header.
+ *
+ * Two tiers keep ordinary traffic from disabling diagnostics. Values of credential-named headers are
+ * strict: they match at any length, and once one is evicted coverage is incomplete for the rest of
+ * the process, so callers fail closed. Every other header value is best effort: it matches only at
+ * eight characters or more and its eviction never disables diagnostics, so per-turn metadata cannot
+ * exhaust anything that matters. Correlation ids (request ids, trace context) are left out of the
+ * best-effort tier because a gateway legitimately echoes them as its request id; a configured header
+ * of that name is still covered by the configured set. Values are held in memory only: nothing here
+ * is serialized, persisted or exposed.
+ */
+import { SENSITIVE_KEY_PATTERN } from "./redact";
+
+/** Containment only for credentials long enough that a diagnostic cannot contain one by chance. */
+export const CREDENTIAL_SUBSTRING_MIN_LENGTH = 8;
+const CREDENTIAL_HEADER_NAME = /api[-_]?key|secret|passw|credential|auth|(?:^|[-_])token$/i;
+const CORRELATION_HEADER_NAME = /^(?:x-(?:client-)?request-id|request-id|traceparent|tracestate)$/i;
+const AUTH_SCHEMES = new Set(["bearer", "basic", "token", "digest", "apikey", "api-key", "key", "sso-key", "negotiate", "dpop"]);
+const TOKEN_CHAR = /[!#$%&'*+.^_`|~0-9A-Za-z-]/;
+const BASIC_BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const PRINTABLE_USER_PASS = /^[\x20-\x7e]*:[\x20-\x7e]*$/;
+
+/** True for a header (or config field) name whose value is a credential by its name. */
+export function isCredentialName(name: string): boolean {
+  return SENSITIVE_KEY_PATTERN.test(name) || CREDENTIAL_HEADER_NAME.test(name);
+}
+
+/**
+ * Values of RFC 9110 auth-params (token BWS "=" BWS ( token / quoted-string )), cookie pairs and
+ * other name=value pairs, in one linear pass: every character is visited a bounded number of times,
+ * so a long header value cannot stall the event loop.
+ */
+function parameterValues(value: string): string[] {
+  const out: string[] = [];
+  const n = value.length;
+  let unclosedFrom = n; // no closing quote exists for any opening quote at or after this index
+  let i = 0;
+  while (i < n) {
+    if (!TOKEN_CHAR.test(value[i]!)) { i++; continue; }
+    while (i < n && TOKEN_CHAR.test(value[i]!)) i++;
+    let j = i;
+    while (j < n && (value[j] === " " || value[j] === "\t")) j++;
+    if (value[j] !== "=") { i = j; continue; }
+    j++;
+    while (j < n && (value[j] === " " || value[j] === "\t")) j++;
+    if (value[j] === "\"") {
+      let k = j + 1;
+      let text = "";
+      let closed = false;
+      if (j < unclosedFrom) {
+        while (k < n) {
+          const char = value[k]!;
+          if (char === "\\" && k + 1 < n) { text += value[k + 1]; k += 2; continue; }
+          if (char === "\"") { closed = true; break; }
+          text += char;
+          k++;
+        }
+      }
+      if (closed) {
+        if (text) out.push(text);
+        i = k + 1;
+      } else {
+        unclosedFrom = Math.min(unclosedFrom, j);
+        i = j + 1;
+      }
+      continue;
+    }
+    const start = j;
+    while (j < n && !/[\s,;"]/.test(value[j]!)) j++;
+    const raw = value.slice(start, j);
+    if (raw && !/^=+$/.test(raw)) out.push(raw);
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * The whole value plus every part a server could authenticate with on its own: tokens split on
+ * whitespace, commas and semicolons with auth scheme words dropped, the value of each name=value
+ * parameter (cookies, digest; whitespace around "=" and quoted strings with escapes are parsed
+ * first, before any splitting), and both halves of a standard Basic credential.
+ */
+export function credentialComponents(value: string): string[] {
+  const whole = value.trim();
+  if (!whole) return [];
+  const out = new Set([whole]);
+  for (const param of parameterValues(whole)) out.add(param);
+  let previous: string | undefined;
+  for (const part of whole.split(/[\s,;]+/)) {
+    if (!part) continue;
+    const lower = part.toLowerCase();
+    if (AUTH_SCHEMES.has(lower)) { previous = lower; continue; }
+    out.add(part);
+    if (previous === "basic" && BASIC_BASE64.test(part)) {
+      const decoded = Buffer.from(part, "base64").toString("utf8");
+      if (PRINTABLE_USER_PASS.test(decoded) && Buffer.from(decoded, "utf8").toString("base64").replace(/=+$/, "") === part.replace(/=+$/, "")) {
+        const colon = decoded.indexOf(":");
+        out.add(decoded.slice(0, colon));
+        out.add(decoded.slice(colon + 1));
+      }
+    }
+    previous = undefined;
+  }
+  out.delete("");
+  return [...out];
+}
+
+/** Exact equality at any length at or above minLength; containment for values of 8+ characters. */
+export function credentialSetMatches(values: Iterable<string>, has: (value: string) => boolean, value: string, minLength = 1): boolean {
+  if (value.length >= minLength && has(value)) return true;
+  for (const secret of values) {
+    if (secret.length >= Math.max(minLength, CREDENTIAL_SUBSTRING_MIN_LENGTH) && value.includes(secret)) return true;
+  }
+  return false;
+}
+
+export interface OutboundCredentialRegistryOptions {
+  maxEntries?: number;
+  maxBytes?: number;
+  maxValueBytes?: number;
+}
+
+/** Bounded LRU of values; eviction marks it incomplete. */
+class BoundedValueSet {
+  readonly values = new Map<string, number>();
+  private totalBytes = 0;
+  complete = true;
+  constructor(private readonly maxEntries: number, private readonly maxBytes: number, private readonly maxValueBytes: number) {}
+
+  add(value: string): void {
+    if (!value) return;
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes > this.maxValueBytes) {
+      this.complete = false;
+      return;
+    }
+    if (this.values.has(value)) {
+      this.values.delete(value);
+      this.values.set(value, bytes);
+      return;
+    }
+    this.values.set(value, bytes);
+    this.totalBytes += bytes;
+    while (this.values.size > this.maxEntries || this.totalBytes > this.maxBytes) {
+      const oldest = this.values.keys().next().value as string;
+      this.totalBytes -= this.values.get(oldest)!;
+      this.values.delete(oldest);
+      this.complete = false;
+    }
+  }
+
+  matches(value: string, minLength: number): boolean {
+    return credentialSetMatches(this.values.keys(), candidate => this.values.has(candidate), value, minLength);
+  }
+}
+
+export class OutboundCredentialRegistry {
+  private readonly strict: BoundedValueSet;
+  private readonly observed: BoundedValueSet;
+
+  constructor(options: OutboundCredentialRegistryOptions = {}) {
+    const entries = options.maxEntries ?? 4096;
+    const bytes = options.maxBytes ?? 1 << 20;
+    const valueBytes = options.maxValueBytes ?? 16_384;
+    this.strict = new BoundedValueSet(entries, bytes, valueBytes);
+    this.observed = new BoundedValueSet(entries, bytes, valueBytes);
+  }
+
+  /** Record the components of every value in headers that are about to be sent. */
+  remember(headers: HeadersInit | Headers | undefined): void {
+    if (!headers) return;
+    new Headers(headers).forEach((value, name) => {
+      const strict = isCredentialName(name);
+      if (!strict && CORRELATION_HEADER_NAME.test(name)) return;
+      const tier = strict ? this.strict : this.observed;
+      for (const part of credentialComponents(value)) tier.add(part);
+    });
+  }
+
+  /** True when value repeats a recorded credential (strict at any length, best effort at 8+). */
+  matches(value: string): boolean {
+    return this.strict.matches(value, 1) || this.observed.matches(value, CREDENTIAL_SUBSTRING_MIN_LENGTH);
+  }
+
+  /** False once a credential-named value was dropped; callers must then fail closed. */
+  complete(): boolean {
+    return this.strict.complete;
+  }
+}
+
+let active = new OutboundCredentialRegistry();
+
+/** The registry fed by the HTTP executor boundary and the Codex WebSocket dial. */
+export function outboundCredentials(): OutboundCredentialRegistry {
+  return active;
+}
+
+/** Swap the active registry for sequential in-file tests; returns the restore function. */
+export function setOutboundCredentialRegistryForTests(registry: OutboundCredentialRegistry): () => void {
+  const previous = active;
+  active = registry;
+  return () => { active = previous; };
+}

package/src/lib/package-tree-integrity.ts

@@ -68,7 +68,7 @@ export interface PackageTreeIntegrityOptions {
 }
 
 export type ObservePackageTree = () => PackageTreeObservation | null;
-export type PackageTreeRuntimeInstall = "bun" | "mise" | "npm" | "pnpm" | "source";
+export type PackageTreeRuntimeInstall = "bun" | "mise" | "npm" | "pnpm" | "source" | "standalone";
 
 const packageManifestUrl = new URL("../../package.json", import.meta.url);
 
@@ -323,7 +323,7 @@ export function createRuntimePackageTreeIntegrityGuard(
   now: () => number = Date.now,
   options: PackageTreeIntegrityOptions = {},
   ): PackageTreeIntegrityGuard {
-    if (installer === "source" || isStandaloneBinary()) {
+    if (installer === "source" || installer === "standalone" || isStandaloneBinary()) {
       return { status: () => ({ ok: true }), dispose: () => {} };
     }
     // The restart replacement spawns process.execPath, the bundled Bun in an npm install. Read it

package/src/lib/passive-read.ts

@@ -0,0 +1,35 @@
+/**
+ * A passive management read: it shows what this process already knows and does not make it act on
+ * providers, accounts, processes or files (#6959).
+ *
+ * The Remote Link management relay runs every Child read inside this scope
+ * (`src/server/index/link-management.ts`), so a Child can show its Home's state without changing
+ * it or making it act. Inside the scope:
+ *
+ * - model discovery yields no routed models (`fetchAllModels`, the management model rows): it would
+ *   reach provider upstreams, refresh Codex entitlements and persist a pending provider's initial
+ *   model selection;
+ * - provider quota and the Codex account list are served from what the Home has observed, with no
+ *   probe, token refresh, native-main claim or publication into routing evidence;
+ * - the startup-health diagnostic, the Codex runtime version probes and the bundled-catalog refresh
+ *   are not started, so no process runs and no runtime record is written;
+ * - a native-main fence raised for unknown service ownership is reported, not re-inspected;
+ * - config-directory and credential-file hardening and malformed-file backups are skipped;
+ * - memory-budget enforcement demotes only stores registered as `passiveEvictable` (eviction that
+ *   only releases memory: the usage caches), never a continuation spill or a replay snapshot.
+ *
+ * The Home's own dashboard and traffic keep those caches current. A passive read may still join
+ * work the Home already started; that work keeps the Home's scope and its writes are the Home's.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const passive = new AsyncLocalStorage<true>();
+
+/** Run a management read passively, including everything it awaits or schedules. */
+export function runPassiveRead<T>(run: () => Promise<T>): Promise<T> {
+  return passive.run(true, run);
+}
+
+export function isPassiveRead(): boolean {
+  return passive.getStore() === true;
+}

package/src/lib/shadow-call.ts

@@ -81,19 +81,58 @@ export function shadowCallTargetsIntersect(
     && target.modelId.startsWith(source.modelId);
 }
 
+/**
+ * Preserve explicit user turns and spawned children before either intercept site.
+ * HTTP provenance is `x-codex-turn-metadata` or `x-openai-subagent: collab_spawn`.
+ * `x-openai-subagent` is connection-level on both transports: a child session opens
+ * its own connection, so a `collab_spawn` upgrade header still names every frame.
+ * Turn metadata is per-frame on WebSocket (`CODEX_WS_FRAME_HEADERS`): only the frame's
+ * `client_metadata["x-codex-turn-metadata"]` describes this turn, because the
+ * upgrade's copy can describe an earlier user or helper turn.
+ * `request_kind: "turn"` alone is not user provenance (#1684). Maintenance
+ * markers such as `x-openai-subagent: compact`/`review` and metadata naming
+ * `memory_consolidation` remain eligible helpers, subject to memory routing.
+ * Missing/malformed metadata retains the legacy opt-in source-prefix behavior.
+ */
+export function shadowCallPreservesSelectedModel(
+  body: unknown,
+  headers: Headers,
+  transport?: "websocket",
+): boolean {
+  if (headers.get("x-openai-subagent") === "collab_spawn") return true;
+  let metadata: unknown = headers.get("x-codex-turn-metadata");
+  if (transport === "websocket") {
+    const client = body && typeof body === "object" && !Array.isArray(body)
+      ? (body as Record<string, unknown>).client_metadata : undefined;
+    metadata = client && typeof client === "object" && !Array.isArray(client)
+      && Object.hasOwn(client, "x-codex-turn-metadata")
+      ? (client as Record<string, unknown>)["x-codex-turn-metadata"] : undefined;
+  }
+  if (typeof metadata !== "string") return false;
+  try {
+    const parsed: unknown = JSON.parse(metadata);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+    const turn = parsed as Record<string, unknown>;
+    return turn.subagent_kind === "thread_spawn"
+      || (turn.request_kind === "turn" && turn.thread_source === "user");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Decide whether a matching source model should use the opt-in intercept.
  *
  * Before Codex 0.147.0 this checked x-codex-turn-metadata and exempted
  * request_kind "turn". Codex 0.147.0 can label background helper calls as
- * "turn", causing them to bypass the intercept (#1684). The fix is to
- * intercept every configured shadow source model regardless of request kind.
+ * "turn", causing them to bypass the intercept (#1684). Request kind alone
+ * cannot exempt a configured source model: callers first preserve explicit
+ * user/child provenance with `shadowCallPreservesSelectedModel` (#6921).
  * A replacement intersecting the same provider+model source set remains a
  * no-op because rewriting it would only create self-interception (#2706).
  *
- * Callers skip this check entirely for spawned sub-agent turns
- * (`isThreadSpawnRequest`): `gpt-6-luna` is both the helper slug and a default
- * sub-agent model, and an explicitly spawned child must keep the model it chose.
+ * `gpt-6-luna` is both the helper slug and a selectable user/sub-agent model;
+ * explicit user turns and spawned children must keep the model they chose.
  */
 export function shouldInterceptShadowCall(
   modelId: string,

package/src/lib/socks5-fetch.ts

@@ -1,6 +1,7 @@
 import net, { type Socket } from "node:net";
 import tls, { type TLSSocket } from "node:tls";
 import { classifyContentCoding, isNullBodyStatus } from "./http-response-semantics";
+import { socks5Credentials, socks5Handshake, Socks5HandshakeError } from "./socks5-handshake";
 
 const DEFAULT_SOCKS5_PORT = 1080;
 const SOCKS5_CONNECT_TIMEOUT_MS = 30_000;
@@ -10,11 +11,6 @@ const MAX_BODY_SLICE_BYTES = 64 * 1024;
 const MAX_DECODED_BODY_BYTES = 32 * 1024 * 1024;
 const MAX_STREAM_DECODE_EXPANSION_RATIO = 128;
 const SOCKS5_VERSION = 0x05;
-const SOCKS5_NO_AUTH = 0x00;
-const SOCKS5_USER_PASS = 0x02;
-const SOCKS5_CONNECT = 0x01;
-const SOCKS5_DOMAIN = 0x03;
-const SOCKS5_SUCCESS = 0x00;
 const CRLF = Buffer.from("\r\n");
 const HEADER_END = Buffer.from("\r\n\r\n");
 
@@ -22,24 +18,6 @@ export class Socks5FetchError extends Error {
   override readonly name = "Socks5FetchError";
 }
 
-function proxyCredentials(proxy: URL): { username?: Uint8Array; password?: Uint8Array } {
-  if (!proxy.username && !proxy.password) return {};
-  let username: string;
-  let password: string;
-  try {
-    username = decodeURIComponent(proxy.username);
-    password = decodeURIComponent(proxy.password);
-  } catch {
-    throw new Socks5FetchError("SOCKS5 proxy credentials contain invalid percent encoding");
-  }
-  const usernameBytes = new TextEncoder().encode(username);
-  const passwordBytes = new TextEncoder().encode(password);
-  if (usernameBytes.byteLength > 255 || passwordBytes.byteLength > 255) {
-    throw new Socks5FetchError("SOCKS5 proxy credentials must each fit in 255 UTF-8 bytes");
-  }
-  return { username: usernameBytes, password: passwordBytes };
-}
-
 function validateProxy(proxy: string): URL {
   let parsed: URL;
   try {
@@ -55,7 +33,10 @@ function validateProxy(proxy: string): URL {
     throw new Socks5FetchError("SOCKS5 proxy port is invalid");
   }
   if (parsed.search || parsed.hash) throw new Socks5FetchError("SOCKS5 proxy URL must not contain a query or fragment");
-  proxyCredentials(parsed);
+  try { socks5Credentials(parsed); } catch (error) {
+    if (error instanceof Socks5HandshakeError) throw new Socks5FetchError(error.message);
+    throw error;
+  }
   return parsed;
 }
 
@@ -130,6 +111,14 @@ class SocketReader {
     socket.resume();
   }
 
+  write(bytes: Uint8Array): void {
+    this.socket.write(bytes);
+  }
+
+  readExact(bytes: number, signal?: AbortSignal): Promise<Buffer> {
+    return this.read(bytes, signal);
+  }
+
   private readonly onData = (chunk: Buffer | string): void => {
     const value = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
     if (this.anyWaiters.length > 0) {
@@ -263,7 +252,7 @@ class SocketReader {
 
 async function socks5Connect(proxy: string, target: URL, signal?: AbortSignal): Promise<Socket> {
   const parsedProxy = validateProxy(proxy);
-  const credentials = proxyCredentials(parsedProxy);
+  const credentials = socks5Credentials(parsedProxy);
   const proxyHost = parsedProxy.hostname.replace(/^\[|\]$/g, "");
   const socket = await connectSocket(proxyHost, Number(parsedProxy.port) || DEFAULT_SOCKS5_PORT, signal);
   socket.setTimeout(SOCKS5_CONNECT_TIMEOUT_MS, () => {
@@ -271,49 +260,12 @@ async function socks5Connect(proxy: string, target: URL, signal?: AbortSignal):
   });
   const reader = new SocketReader(socket);
   try {
-    const methods = credentials.username ? Buffer.from([SOCKS5_NO_AUTH, SOCKS5_USER_PASS]) : Buffer.from([SOCKS5_NO_AUTH]);
-    socket.write(Buffer.from([SOCKS5_VERSION, methods.byteLength, ...methods]));
-    const greeting = await reader.read(2, signal);
-    if (greeting[0] !== SOCKS5_VERSION) throw new Socks5FetchError("SOCKS5 proxy returned an invalid greeting");
-    if (greeting[1] === SOCKS5_USER_PASS && credentials.username && credentials.password) {
-      socket.write(Buffer.from([
-        0x01,
-        credentials.username.byteLength,
-        ...credentials.username,
-        credentials.password.byteLength,
-        ...credentials.password,
-      ]));
-      const auth = await reader.read(2, signal);
-      if (auth[0] !== 0x01 || auth[1] !== 0x00) throw new Socks5FetchError("SOCKS5 proxy authentication failed");
-    } else if (greeting[1] !== SOCKS5_NO_AUTH) {
-      throw new Socks5FetchError("SOCKS5 proxy does not accept an offered authentication method");
-    }
-
-    const hostname = new TextEncoder().encode(target.hostname);
-    if (hostname.byteLength > 255) throw new Socks5FetchError("SOCKS5 target hostname is too long");
-    const port = targetPort(target);
-    socket.write(Buffer.from([
-      SOCKS5_VERSION,
-      SOCKS5_CONNECT,
-      0x00,
-      SOCKS5_DOMAIN,
-      hostname.byteLength,
-      ...hostname,
-      port >> 8,
-      port & 0xff,
-    ]));
-    const reply = await reader.read(4, signal);
-    if (reply[0] !== SOCKS5_VERSION) throw new Socks5FetchError("SOCKS5 proxy returned an invalid connect response");
-    if (reply[1] !== SOCKS5_SUCCESS) throw new Socks5FetchError(`SOCKS5 proxy refused the connection (code ${reply[1]})`);
-    if (reply[2] !== 0x00 || ![0x01, SOCKS5_DOMAIN, 0x04].includes(reply[3]!)) {
-      throw new Socks5FetchError("SOCKS5 proxy returned an invalid address type or reserved byte");
-    }
-    const addressLength = reply[3] === 0x01 ? 4 : reply[3] === SOCKS5_DOMAIN ? (await reader.read(1, signal))[0]! : 16;
-    await reader.read(addressLength + 2, signal);
+    await socks5Handshake(reader, { host: target.hostname, port: targetPort(target) }, credentials, signal);
     socket.setTimeout(0);
     return socket;
   } catch (error) {
     socket.destroy();
+    if (error instanceof Socks5HandshakeError) throw new Socks5FetchError(error.message);
     throw error;
   } finally {
     reader.dispose();
@@ -341,25 +293,50 @@ function requestHeaders(request: Request, target: URL): { text: string; chunked:
 
 async function secureSocket(socket: Socket, target: URL, signal: AbortSignal): Promise<TLSSocket> {
   return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      socket.destroy();
+      reject(signal.reason instanceof Error ? signal.reason : new Error("The operation was aborted"));
+      return;
+    }
     const tlsSocket = tls.connect({
       socket,
       servername: target.hostname,
       rejectUnauthorized: true,
     });
-    const onAbort = () => {
+    let settled = false;
+    // Absolute deadline: a peer sending occasional TLS bytes must not extend the handshake.
+    const timer = setTimeout(() => {
+      fail(new Socks5FetchError("SOCKS5 TLS handshake timed out"));
+    }, SOCKS5_CONNECT_TIMEOUT_MS);
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      tlsSocket.removeListener("secureConnect", onSecureConnect);
+      tlsSocket.removeListener("error", onError);
+      tlsSocket.removeListener("close", onClose);
+    };
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      // No error argument: pending event observers must not receive a second error.
       tlsSocket.destroy();
-      reject(signal.reason instanceof Error ? signal.reason : new Error("The operation was aborted"));
+      reject(error);
     };
+    const onAbort = () => fail(signal.reason instanceof Error ? signal.reason : new Error("The operation was aborted"));
+    const onError = (error: Error) => fail(error);
+    const onClose = () => fail(new Socks5FetchError("SOCKS5 upstream closed during TLS handshake"));
     const onSecureConnect = () => {
-      signal.removeEventListener("abort", onAbort);
+      if (settled) return;
+      settled = true;
+      cleanup();
       resolve(tlsSocket);
     };
     tlsSocket.once("secureConnect", onSecureConnect);
-    tlsSocket.once("error", error => {
-      signal.removeEventListener("abort", onAbort);
-      reject(error);
-    });
+    tlsSocket.once("error", onError);
+    tlsSocket.once("close", onClose);
     signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
   });
 }