@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/lib/opaque-proxy-tunnel.ts

@@ -0,0 +1,217 @@
+/**
+ * Single-route opaque proxy tunnel. The desktop upstream dialer retains its
+ * own fixed-target TLS contract.
+ * Shares OpenCodex's MIT SOCKS handshake; the caller owns all post-establishment
+ * cancellation and socket cleanup. Never replay or implicitly retry directly.
+ */
+import net, { type Socket } from 'node:net';
+import tls from 'node:tls';
+import { socks5Handshake, socks5Credentials, Socks5HandshakeError } from './socks5-handshake';
+
+interface RouteEndpoint { host: string; port: number }
+type RouteCredentials = { username?: undefined; password?: undefined } | { username: string; password: string };
+type PlainProxy = { kind?: 'http'; proxyCa?: never };
+type SecureProxy = { kind: 'https'; proxyCa?: string };
+type SocksProxy = { kind: 'socks5' | 'socks5h'; proxyCa?: never };
+export type OpaqueProxyRoute = RouteEndpoint & RouteCredentials & (PlainProxy | SecureProxy | SocksProxy);
+export interface OpaqueTunnelOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxHeaderBytes?: number;
+}
+interface AttemptOptions {
+  signal?: AbortSignal;
+  timeoutMs: number;
+  maxHeaderBytes: number;
+}
+export class TunnelError extends Error {
+  override readonly name = 'TunnelError';
+  readonly code: string;
+  readonly status?: number;
+  constructor(code: string, message: string, { status }: { status?: number } = {}) {
+    super(message); this.code = code; this.status = status;
+  }
+}
+const aborted = () => new TunnelError('ABORTED', 'Tunnel establishment cancelled');
+
+function validateAuthority(authority: string): string {
+  if (typeof authority !== 'string' || !/^(?:\[[0-9a-fA-F:]+\]|[a-zA-Z0-9._-]+):[0-9]+$/.test(authority)) {
+    throw new TunnelError('TARGET', 'An explicit host:port authority is required');
+  }
+  const port = Number(authority.slice(authority.lastIndexOf(':') + 1));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new TunnelError('TARGET', 'Invalid target port');
+  return authority;
+}
+
+function validateOptions(p: OpaqueProxyRoute, timeoutMs: number, maxHeaderBytes: number): void {
+  if (!p || Array.isArray(p) || typeof p.host !== 'string' || !p.host || /[\s/@]/.test(p.host)
+    || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535
+    || !['http', 'https', 'socks5', 'socks5h'].includes(p.kind ?? 'http')) throw new TunnelError('CONFIG', 'Invalid proxy route');
+  if ((p.username === undefined) !== (p.password === undefined)
+    || (p.username !== undefined && (typeof p.username !== 'string' || typeof p.password !== 'string'
+      || (!p.kind?.startsWith('socks') && p.username.includes(':')) || Buffer.byteLength(p.username + p.password) > 4096))) throw new TunnelError('CONFIG', 'Invalid proxy credentials');
+  if ((p.kind ?? 'http').startsWith('socks') && p.username !== undefined
+    && (Buffer.byteLength(p.username) > 255 || Buffer.byteLength(p.password) > 255)) throw new TunnelError('CONFIG', 'SOCKS credentials must each fit in 255 UTF-8 bytes');
+  if (p.proxyCa !== undefined && p.kind !== 'https') throw new TunnelError('CONFIG', 'Proxy TLS settings require HTTPS proxy');
+  if (p.proxyCa !== undefined && typeof p.proxyCa !== 'string') throw new TunnelError('CONFIG', 'Invalid proxy CA');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000
+    || !Number.isSafeInteger(maxHeaderBytes) || maxHeaderBytes < 64 || maxHeaderBytes > 65536) {
+    throw new TunnelError('CONFIG', 'Invalid deadline or header limit');
+  }
+}
+
+function connectOne(authority: string, proxy: OpaqueProxyRoute, { signal, timeoutMs, maxHeaderBytes }: AttemptOptions): Promise<Socket> {
+  if (proxy.kind === 'socks5' || proxy.kind === 'socks5h') return connectSocks(authority, proxy, { signal, timeoutMs, maxHeaderBytes });
+  return new Promise<Socket>((resolve, reject) => {
+    if (signal?.aborted) return reject(aborted());
+    const secure = proxy.kind === 'https';
+    const identity = proxy.host;
+    const tlsOptions: tls.ConnectionOptions & { allowHalfOpen: boolean } = {
+      host: proxy.host, port: proxy.port, allowHalfOpen: true,
+      servername: net.isIP(identity) ? undefined : identity, ca: proxy.proxyCa,
+      checkServerIdentity: (_name, cert) => tls.checkServerIdentity(identity, cert),
+      rejectUnauthorized: true, ALPNProtocols: ['http/1.1'],
+    };
+    const socket = secure
+      ? tls.connect(tlsOptions)
+      : net.createConnection({ host: proxy.host, port: proxy.port, allowHalfOpen: true });
+    // Keep a defensive observer across the promise-to-owner handoff. Errors still
+    // settle the establishment promise or are handled by the relay after handoff.
+    socket.on('error', () => {});
+    let pending: Buffer = Buffer.alloc(0); let settled = false, tlsReady = !secure;
+    const connectedEvent = secure ? 'secureConnect' : 'connect';
+    const cleanup = () => {
+      clearTimeout(timer); signal?.removeEventListener('abort', onAbort);
+      socket.removeListener(connectedEvent, onConnect); socket.removeListener('data', onData);
+      socket.removeListener('error', onError); socket.removeListener('end', onEnd); socket.removeListener('close', onClose);
+    };
+    const fail = (error: Error) => {
+      if (settled) return; settled = true; cleanup(); socket.destroy(); reject(error);
+    };
+    const onAbort = () => fail(aborted());
+    const establishmentFailure = (code: string, message: string) => fail(new TunnelError(code, message));
+    const onError = () => {
+      if (secure && !tlsReady) {
+        fail(new TunnelError('PROXY_TLS', 'HTTPS proxy establishment failed'));
+      } else establishmentFailure('TRANSPORT', 'HTTP proxy connection failed');
+    };
+    const onEnd = () => establishmentFailure('EARLY_CLOSE', 'HTTP proxy closed before establishing the tunnel');
+    const onClose = onEnd;
+    const onConnect = () => {
+      tlsReady = true;
+      const auth = proxy.username === undefined ? '' : `Proxy-Authorization: Basic ${Buffer.from(`${proxy.username}:${proxy.password}`).toString('base64')}\r\n`;
+      socket.write(`CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n${auth}\r\n`);
+    };
+    const onData = (chunk: Buffer) => {
+      pending = Buffer.concat([pending, chunk]);
+      const lineEnd = pending.indexOf('\r\n');
+      if (lineEnd >= 0) {
+        const firstLine = pending.subarray(0, lineEnd).toString('latin1');
+        const firstStatus = /^HTTP\/1\.[01] ([0-9]{3})(?: [\t\x20-\x7e\x80-\xff]*)?$/.exec(firstLine);
+        if (!firstStatus) return fail(new TunnelError('PROTOCOL', 'Invalid HTTP proxy status line'));
+        const status = Number(firstStatus[1]);
+        if (status < 200 || status >= 300) return fail(new TunnelError('REFUSED', 'HTTP proxy refused CONNECT', { status }));
+      }
+      const end = pending.indexOf('\r\n\r\n');
+      if (end < 0) {
+        if (pending.length > maxHeaderBytes) fail(new TunnelError('PROTOCOL', 'HTTP proxy response headers exceed limit'));
+        return;
+      }
+      if (end + 4 > maxHeaderBytes) return fail(new TunnelError('PROTOCOL', 'HTTP proxy response headers exceed limit'));
+      const lines = pending.subarray(0, end).toString('latin1').split('\r\n');
+      const statusLine = lines[0];
+      const match = /^HTTP\/1\.[01] ([0-9]{3})(?: [^\r\n]*)?$/.exec(statusLine);
+      if (!match) return fail(new TunnelError('PROTOCOL', 'Invalid HTTP proxy status line'));
+      const status = Number(match[1]);
+      if (lines.slice(1).some(line => !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+:[\t\x20-\x7e\x80-\xff]*$/.test(line))) {
+        return fail(new TunnelError('PROTOCOL', 'Invalid HTTP proxy response header'));
+      }
+      if (status < 200 || status >= 300) return fail(new TunnelError('REFUSED', 'HTTP proxy refused CONNECT', { status }));
+      settled = true; socket.pause(); cleanup();
+      const head = pending.subarray(end + 4);
+      if (head.length) socket.unshift(head);
+      resolve(socket);
+    };
+    const timer = setTimeout(() => establishmentFailure('TIMEOUT', 'HTTP proxy establishment deadline exceeded'), timeoutMs);
+    socket.once(connectedEvent, onConnect); socket.on('data', onData);
+    socket.once('error', onError); socket.once('end', onEnd); socket.once('close', onClose);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+}
+
+// The bounded socket reader owns setup cancellation and preserves queued bytes.
+// Framing uses the existing
+// MIT socks5-handshake module; neither shared framing nor its DNS policy changes.
+async function connectSocks(authority: string, proxy: OpaqueProxyRoute, { signal, timeoutMs }: AttemptOptions): Promise<Socket> {
+  if (signal?.aborted) throw aborted();
+  const socket = net.createConnection({ host: proxy.host, port: proxy.port, allowHalfOpen: true });
+  socket.on('error', () => {});
+  let buffer: Buffer = Buffer.alloc(0), failure: Error | undefined;
+  let waiting: { length: number; resolve: () => void; reject: (error: Error) => void } | undefined;
+  const fail = (error: Error) => { if (failure) return; failure = error; const current = waiting; waiting = undefined; current?.reject(error); socket.destroy(); };
+  const transportError = (code: string, message: string) => fail(new TunnelError(code, message));
+  const onData = (chunk: Buffer) => {
+    // Consume at most the bytes needed by a bounded handshake read, then pause.
+    // A valid CONNECT reply can share a packet with arbitrary early target data;
+    // that remainder is not a malformed/oversized handshake and must survive.
+    socket.pause();
+    buffer = Buffer.concat([buffer, chunk]);
+    if (waiting && buffer.length >= waiting.length) { const current = waiting; waiting = undefined; current.resolve(); }
+    else if (waiting) socket.resume();
+  };
+  const onError = () => transportError('TRANSPORT', 'SOCKS proxy connection failed');
+  const onClose = () => transportError('EARLY_CLOSE', 'SOCKS proxy closed before tunnel establishment');
+  const onAbort = () => fail(aborted());
+  const timer = setTimeout(() => transportError('TIMEOUT', 'SOCKS establishment deadline exceeded'), timeoutMs);
+  socket.on('data', onData); socket.once('error', onError); socket.once('end', onClose); socket.once('close', onClose);
+  socket.pause();
+  signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) onAbort();
+  const reader = {
+    write(bytes: Uint8Array): void { if (failure) throw failure; socket.write(bytes); },
+    async readExact(length: number): Promise<Buffer> {
+      if (failure) throw failure;
+      if (!Number.isSafeInteger(length) || length < 0 || length > 1024) throw new TunnelError('PROTOCOL', 'Invalid handshake read size');
+      if (buffer.length < length) await new Promise<void>((resolve, reject) => {
+        if (waiting) { reject(new TunnelError('PROTOCOL', 'Concurrent handshake read')); return; }
+        waiting = { length, resolve, reject };
+        socket.resume();
+      });
+      if (failure) throw failure;
+      const result = buffer.subarray(0, length); buffer = buffer.subarray(length); return result;
+    },
+  };
+  try {
+    const credentialsUrl = new URL('socks5://fixture.invalid');
+    if (proxy.username !== undefined) { credentialsUrl.username = encodeURIComponent(proxy.username); credentialsUrl.password = encodeURIComponent(proxy.password); }
+    const colon = authority.lastIndexOf(':');
+    const target = { host: authority.slice(0, colon).replace(/^\[|\]$/g, ''), port: Number(authority.slice(colon + 1)) };
+    await socks5Handshake(reader, target, socks5Credentials(credentialsUrl), signal);
+    if (failure) throw failure;
+    if (signal?.aborted || socket.destroyed) throw aborted();
+    socket.pause(); if (buffer.length) socket.unshift(buffer); buffer = Buffer.alloc(0);
+    return socket;
+  } catch (error) {
+    socket.destroy();
+    if (error instanceof Socks5HandshakeError) throw new TunnelError('SOCKS_REFUSED', 'SOCKS authentication, policy, or protocol refusal');
+    throw error;
+  } finally {
+    clearTimeout(timer); signal?.removeEventListener('abort', onAbort);
+    socket.removeListener('data', onData); socket.removeListener('error', onError);
+    socket.removeListener('end', onClose); socket.removeListener('close', onClose);
+  }
+}
+
+/** Establish only. There is no application data, implicit DIRECT, or replay here.
+ * HTTP/HTTPS CONNECT and SOCKS5/SOCKS5h yield an opaque raw target tunnel.
+ */
+export async function dialTunnel(authority: string, proxy: OpaqueProxyRoute, options: OpaqueTunnelOptions = {}): Promise<Socket> {
+  const { signal, timeoutMs = 10000, maxHeaderBytes = 65536 } = options;
+  validateAuthority(authority);
+  validateOptions(proxy, timeoutMs, maxHeaderBytes);
+  if (signal?.aborted) throw aborted();
+  // Snapshot the selected route. No alternate proxy or direct fallback exists.
+  const socket = await connectOne(authority, { ...proxy }, { signal, timeoutMs, maxHeaderBytes });
+  if (signal?.aborted || socket.destroyed) { socket.destroy(); throw aborted(); }
+  return socket;
+}

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/redact.ts

@@ -7,7 +7,7 @@ export const REDACTED_SECRET = "[REDACTED]";
  * credentials over an unsafe channel (e.g. plaintext non-loopback HTTP) rather than
  * re-deriving a narrower local list.
  */
-export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
+export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
 
 /**
  * Colon-labelled credential headers echoed back inside an error body
@@ -40,7 +40,7 @@ export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cook
 // Every letter position also accepts \u0001, the placeholder the fold emits for
 // an unresolved HTML named reference: `authorⅈzation` is the label with one
 // character we cannot name, and that is still the label.
-const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
+const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
 
 const CREDENTIAL_HEADER_LABEL = CREDENTIAL_HEADER_LABEL_RAW
   .replace(/(?<![\[\\])([A-Za-z])(?![\]\-])/g, "[$1\u0001]");

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();
   });
 }
 

package/src/lib/socks5-handshake.ts

@@ -0,0 +1,112 @@
+/**
+ * The SOCKS5 handshake both raw outbound transports share: method negotiation
+ * (RFC 1928), the optional RFC 1929 username/password subnegotiation, and the
+ * CONNECT exchange.
+ *
+ * `src/lib/socks5-fetch.ts` (the HTTP tunnel) and
+ * `src/lib/desktop-upstream-tunnel.ts` (the native desktop relay's raw
+ * dial) each own their socket, their timeouts, and what happens after CONNECT;
+ * this module only frames bytes through the reader each hands it, so a
+ * credentialed `socks5://` proxy URL authenticates identically whether the caller
+ * is a fetch or a raw WebSocket upgrade. When the URL carries credentials the
+ * greeting offers NO-AUTH alongside USER-PASS, which keeps an unauthenticated
+ * proxy working for a caller that configured more than it needed.
+ */
+
+export class Socks5HandshakeError extends Error {
+  override readonly name = "Socks5HandshakeError";
+}
+
+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;
+
+/** RFC 1929 credentials decoded from the proxy URL, each bounded to one length byte. */
+export interface Socks5Credentials {
+  username?: Uint8Array;
+  password?: Uint8Array;
+}
+
+export function socks5Credentials(proxy: URL): Socks5Credentials {
+  if (!proxy.username && !proxy.password) return {};
+  let username: string;
+  let password: string;
+  try {
+    username = decodeURIComponent(proxy.username);
+    password = decodeURIComponent(proxy.password);
+  } catch {
+    throw new Socks5HandshakeError("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 Socks5HandshakeError("SOCKS5 proxy credentials must each fit in 255 UTF-8 bytes");
+  }
+  return { username: usernameBytes, password: passwordBytes };
+}
+
+/**
+ * The slice of a transport's socket reader the handshake needs: exact-length reads
+ * that reject on close, on error, or on the transport's own timeout, plus writes.
+ * Bytes read past a step stay queued in the transport's reader; the handshake never
+ * touches the socket itself.
+ */
+export interface Socks5HandshakeReader {
+  write(bytes: Uint8Array): void;
+  readExact(bytes: number, signal?: AbortSignal): Promise<Uint8Array>;
+}
+
+export interface Socks5Target {
+  host: string;
+  port: number;
+}
+
+/** Negotiate methods, authenticate when the proxy picks USER-PASS, and CONNECT to `target`. */
+export async function socks5Handshake(
+  reader: Socks5HandshakeReader,
+  target: Socks5Target,
+  credentials: Socks5Credentials,
+  signal?: AbortSignal,
+): Promise<void> {
+  const hostBytes = Buffer.from(target.host, "utf8");
+  if (hostBytes.byteLength > 255) throw new Socks5HandshakeError("SOCKS5 target hostname is too long");
+  const methods = credentials.username ? [SOCKS5_NO_AUTH, SOCKS5_USER_PASS] : [SOCKS5_NO_AUTH];
+  reader.write(Buffer.from([SOCKS5_VERSION, methods.length, ...methods]));
+  const greeting = await reader.readExact(2, signal);
+  if (greeting[0] !== SOCKS5_VERSION) throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid greeting");
+  if (greeting[1] === SOCKS5_USER_PASS && credentials.username && credentials.password) {
+    reader.write(Buffer.from([
+      0x01,
+      credentials.username.byteLength,
+      ...credentials.username,
+      credentials.password.byteLength,
+      ...credentials.password,
+    ]));
+    const auth = await reader.readExact(2, signal);
+    if (auth[0] !== 0x01 || auth[1] !== 0x00) throw new Socks5HandshakeError("SOCKS5 proxy authentication failed");
+  } else if (greeting[1] !== SOCKS5_NO_AUTH) {
+    throw new Socks5HandshakeError("SOCKS5 proxy does not accept an offered authentication method");
+  }
+
+  reader.write(Buffer.from([
+    SOCKS5_VERSION,
+    SOCKS5_CONNECT,
+    0x00,
+    SOCKS5_DOMAIN,
+    hostBytes.byteLength,
+    ...hostBytes,
+    target.port >> 8,
+    target.port & 0xff,
+  ]));
+  const reply = await reader.readExact(4, signal);
+  if (reply[0] !== SOCKS5_VERSION) throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid connect response");
+  if (reply[1] !== SOCKS5_SUCCESS) throw new Socks5HandshakeError(`SOCKS5 proxy refused the connection (code ${reply[1]})`);
+  if (reply[2] !== 0x00 || ![0x01, SOCKS5_DOMAIN, 0x04].includes(reply[3]!)) {
+    throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid address type or reserved byte");
+  }
+  const addressLength = reply[3] === 0x01 ? 4 : reply[3] === SOCKS5_DOMAIN ? (await reader.readExact(1, signal))[0]! : 16;
+  await reader.readExact(addressLength + 2, signal);
+}

package/src/lib/translator-budget.ts

@@ -1,3 +1,5 @@
+import { isNonReplayableResponse, markResponseNonReplayable } from "./upstream-retry";
+
 export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
 export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
 export const TRANSLATOR_MAX_SSE_EVENT_BYTES = 32 * 1024 * 1024;
@@ -410,5 +412,9 @@ export function finalizeTranslatorBudgetResponse(response: Response, budget: Tra
   });
   if (signal?.aborted) finalize();
   else signal?.addEventListener("abort", finalize, { once: true });
-  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+  const finalizedResponse = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+  // The rebuild above drops identity markers. A refusal that must not be replayed
+  // stays non-replayable through accounting finalization.
+  if (isNonReplayableResponse(response)) markResponseNonReplayable(finalizedResponse);
+  return finalizedResponse;
 }

package/src/oauth/account-quota-rank.ts

@@ -96,7 +96,7 @@ function headroomOf(provider: string, accountId: string, requestedModelId?: stri
   const family = classifyModelFamilyForQuota(provider, requestedModelId);
   if (family) {
     const percents = (quota.customWindows ?? [])
-      .filter(window => windowMatchesFamily(window.label, family))
+      .filter(window => window.modelId === undefined && windowMatchesFamily(window.label, family))
       .map(window => window.percent)
       .filter((value): value is number => typeof value === "number");
     if (percents.length === 0) return null;
@@ -106,7 +106,7 @@ function headroomOf(provider: string, accountId: string, requestedModelId?: stri
     quota.fiveHourPercent,
     quota.weeklyPercent,
     quota.monthlyPercent,
-    ...(quota.customWindows ?? []).map(window => window.percent),
+    ...(quota.customWindows ?? []).filter(window => window.modelId === undefined).map(window => window.percent),
   ].filter((value): value is number => typeof value === "number");
   if (percents.length === 0) return null;
   return 100 - Math.max(...percents);
@@ -140,6 +140,73 @@ export function isAccountQuotaExhausted(
   return headroom !== null && headroom <= 0;
 }
 
+/**
+ * Earliest future reset timestamp (in ms) for the relevant quota window, or null if unknown.
+ * Prefers weekly reset when multiple windows exist so expiring allowance is consumed first.
+ */
+export function accountResetTimestamp(
+  provider: string,
+  accountId: string,
+  requestedModelId?: string | null,
+  now = Date.now(),
+): number | null {
+  const quota = getCachedProviderAccountQuota(provider, accountId);
+  if (!quota) return null;
+  const family = classifyModelFamilyForQuota(provider, requestedModelId);
+  const windows = (quota.customWindows ?? []).filter(w => !family || windowMatchesFamily(w.label, family));
+  const weekly = windows.find(w => /week/i.test(w.label));
+  let rawReset = weekly?.resetAt ?? quota.weeklyResetAt;
+  if (rawReset === undefined && provider !== "google-antigravity" && provider !== "anthropic") {
+    // Providers without a weekly cadence: prefer an explicitly 5h-labeled window before
+    // falling back to first-window order.
+    const fiveHour = windows.find(w => /5h|five/i.test(w.label)) ?? windows[0];
+    rawReset = fiveHour?.resetAt ?? quota.fiveHourResetAt;
+  } else if (rawReset === undefined) {
+    rawReset = windows[0]?.resetAt ?? quota.fiveHourResetAt;
+  }
+  if (typeof rawReset !== "number" || !Number.isFinite(rawReset)) return null;
+  const ms = rawReset < 1e11 ? rawReset * 1000 : rawReset;
+  return ms > now ? ms : null;
+}
+
+/**
+ * Rank candidates by soonest reset timestamp first among healthy accounts.
+ * Accounts whose quota will reset earliest get priority so allowances do not expire unused.
+ *
+ * When a passive provider has incomplete quota evidence (some ring members with no
+ * cached record), reset timestamps are unreliable: an unknown account converts to
+ * Infinity and always loses to a known near-exhausted one. Fall back to headroom
+ * order instead of inventing a reset ordering.
+ */
+export function rankAccountsByResetFirst(
+  provider: string,
+  ring: readonly string[],
+  requestedModelId?: string | null,
+  now = Date.now(),
+  accounts?: ReadonlyMap<string, ProviderAccount>,
+): string[] {
+  if (ring.length < 2) return [...ring];
+  const ranked = rankAccountsByHeadroom(provider, ring, requestedModelId, accounts);
+  const healthy = ranked.filter(id => !isAccountQuotaExhausted(provider, id, requestedModelId, accounts?.get(id)));
+  if (healthy.length < 2) return ranked;
+  if (
+    hasPassiveAccountQuota(provider)
+    && !ring.every(id => headroomOf(provider, id, requestedModelId, accounts?.get(id)) !== null)
+  ) return ranked;
+
+  const withReset = healthy.map((id, index) => ({
+    id,
+    resetAt: accountResetTimestamp(provider, id, requestedModelId, now) ?? Number.POSITIVE_INFINITY,
+    headroom: headroomOf(provider, id, requestedModelId, accounts?.get(id)) ?? 0,
+    index,
+  }));
+
+  withReset.sort((a, b) => (a.resetAt - b.resetAt) || (b.headroom - a.headroom) || (a.index - b.index));
+  const sortedHealthy = withReset.map(r => r.id);
+  const exhausted = ranked.filter(id => isAccountQuotaExhausted(provider, id, requestedModelId, accounts?.get(id)));
+  return [...sortedHealthy, ...exhausted];
+}
+
 /**
  * Order candidates best-first.
  *