troxy-cli 1.29.3 → 1.29.5

package/src/interceptor.js

@@ -0,0 +1,419 @@
+/**
+ * The local interceptor - Layer 2 of the Live Model Policy Enforcement
+ * plan. Runs inside `troxy daemon` (see daemon.js), listening on loopback
+ * only. Handles HTTP CONNECT the way any forward proxy does:
+ *
+ *  - A host NOT in `interceptHosts` is a pure blind byte tunnel. This code
+ *    never sees its plaintext, never parses it, makes no network call of
+ *    its own - just net.connect + pipe() in both directions. This is the
+ *    hot path for everything Claude Code (and anything it spawns) talks to
+ *    that isn't the one host this feature cares about.
+ *  - An allowlisted host gets its TLS terminated with a leaf signed by the
+ *    local, name-constrained CA (tls-ca.js), fed into a real Node
+ *    http.Server instance via `.emit('connection', tlsSocket)` so Node's
+ *    own battle-tested HTTP/1.1 parsing handles the request, not a
+ *    hand-rolled one. Only the ONE configured route (providers.js) gets
+ *    re-addressed to Troxy; every other path on that same host relays to
+ *    the real destination untouched, same as a non-allowlisted host would.
+ *
+ * Fail-open, required by the plan (found the hard way tonight - a dead
+ * local proxy broke Claude Code outright until manually reverted):
+ *  - getCerts() returning null (missing/corrupt/expired) -> tunnel the
+ *    allowlisted host too, exactly like a non-allowlisted one. Coverage is
+ *    lost; the user's Claude Code is not.
+ *  - Troxy upstream unreachable or slow past troxyConnectTimeoutMs -> the
+ *    matched request falls back to relaying directly to the real host,
+ *    with the client's own original credentials, instead of erroring.
+ *  - No Troxy key available -> same fallback, without even attempting Troxy.
+ */
+import net from 'node:net';
+import tls from 'node:tls';
+import http from 'node:http';
+import https from 'node:https';
+
+// Found live 2026-09-08, first real terminal validation of this whole
+// mechanism: a real `claude` process opens a burst of ~15 concurrent
+// connections through the interceptor at startup (telemetry, mcp-registry
+// pagination, oauth/account/settings, bootstrap, the real /v1/messages
+// call, etc.), all landing on this single daemon process's event loop at
+// once. A cold Node https.request to proxy.troxy.io in isolation completes
+// in ~150-350ms (measured directly), comfortably inside 1.5s - but under
+// that real startup burst, the specific connection carrying the actual
+// message reliably missed the 1.5s budget and fell open, so every message
+// in a fresh terminal session silently bypassed Troxy. Verified live: the
+// SAME session's second and later messages, once the startup burst has
+// settled, connect and route correctly well within 1.5s - this is a
+// startup-burst problem, not a genuinely slow or unreachable Troxy.
+// Widened for headroom under that real burst; still bounded, so a
+// genuinely dead Troxy backend still fails open within a few seconds, not
+// hangs indefinitely.
+const DEFAULT_TROXY_CONNECT_TIMEOUT_MS = 5000;
+// Once the TCP/TLS connection to Troxy is actually established, Troxy
+// itself is reachable - any further wait is the model genuinely thinking,
+// not an outage. Found live: a real Claude Code/Desktop request (full
+// system prompt, tool definitions, history) commonly takes several
+// seconds of time-to-first-token, which blew straight past the old single
+// 1.5s budget on every real message, so the interceptor fell back to a
+// direct call every single time and never actually reached policy
+// enforcement in practice. Falling back at that point buys the user
+// nothing anyway - Anthropic direct would show the same latency - so this
+// is a generous absolute backstop against Troxy hanging post-connect, not
+// a value meant to trigger in the normal case.
+const DEFAULT_TROXY_RESPONSE_TIMEOUT_MS = 55_000;
+
+export function parseConnectTarget(url) {
+  const idx = url.lastIndexOf(':');
+  if (idx === -1) return { host: url, port: 443 };
+  const host = url.slice(0, idx);
+  const port = parseInt(url.slice(idx + 1), 10);
+  return { host, port: Number.isFinite(port) ? port : 443 };
+}
+
+// Headers that only made sense on the leg that already terminated here -
+// meaningless (or wrong) to forward on either outbound leg.
+const _HOP_BY_HOP_HEADERS = new Set(['host', 'connection', 'content-length', 'transfer-encoding']);
+
+/** 'desktop' | 'terminal' | null. Verified live 2026-09-11 against two real
+ * captured user-agents from this same machine: terminal sends
+ * "claude-cli/2.1.236 (external, cli)", desktop sends "claude-cli/2.1.260
+ * (external, claude-desktop, agent-sdk/0.3.260)" - the literal substring
+ * "claude-desktop" is the one stable, explicit signal found; everything
+ * else in the string (version numbers) will drift across releases. null
+ * (never a guess) when the client sends no recognizable claude-cli
+ * user-agent at all - some other tool on this port, or a future format
+ * change this hasn't been updated for. */
+export function detectSurface(incomingHeaders) {
+  const ua = incomingHeaders['user-agent'] || '';
+  if (!/^claude-cli\//.test(ua)) return null;
+  return ua.includes('claude-desktop') ? 'desktop' : 'terminal';
+}
+
+/** Headers for the leg going to Troxy: the client's own Authorization (an
+ * Anthropic API key or OAuth token) is never sent to Troxy as-is - it
+ * rides the side channel app.py already knows how to consume
+ * (X-Troxy-Upstream-Authorization), while Authorization itself becomes the
+ * Troxy key, matching how app.py authenticates every other proxied call. */
+export function buildTroxyForwardHeaders(incomingHeaders, troxyKey) {
+  const headers = {};
+  for (const [k, v] of Object.entries(incomingHeaders)) {
+    if (_HOP_BY_HOP_HEADERS.has(k) || k === 'authorization' || k === 'accept-encoding') continue;
+    headers[k] = v;
+  }
+  if (incomingHeaders.authorization) {
+    headers['x-troxy-upstream-authorization'] = incomingHeaders.authorization;
+  }
+  const surface = detectSurface(incomingHeaders);
+  if (surface) headers['x-troxy-surface'] = surface;
+  headers.authorization = `Bearer ${troxyKey}`;
+  return headers;
+}
+
+/** Headers for the leg going straight to the real host (no Troxy route
+ * matched, or Troxy was unreachable): the client's own credential passes
+ * through completely unmodified - this is not a Troxy-authenticated call
+ * at all, just a transparent relay. */
+export function buildRelayHeaders(incomingHeaders) {
+  const headers = {};
+  for (const [k, v] of Object.entries(incomingHeaders)) {
+    if (_HOP_BY_HOP_HEADERS.has(k)) continue;
+    headers[k] = v;
+  }
+  return headers;
+}
+
+function _drainBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+function _relayToRealHost(host, port, req, res, body, log, lookup, ca) {
+  const upstreamReq = https.request({
+    method: req.method,
+    hostname: host,
+    port,
+    path: req.url,
+    headers: buildRelayHeaders(req.headers),
+    ...(lookup ? { lookup } : {}),
+    ...(ca ? { ca } : {}), // test-only override; production always uses Node's real trust store
+  }, (upstreamRes) => {
+    res.writeHead(upstreamRes.statusCode, upstreamRes.headers);
+    upstreamRes.pipe(res);
+  });
+  upstreamReq.on('error', (err) => {
+    log('relay to real host %s failed: %s', host, err.message);
+    if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'troxy interceptor: could not reach ' + host }));
+  });
+  upstreamReq.end(body);
+}
+
+// http.request/https.request chosen per the configured upstream's own
+// protocol - a test stub commonly uses plain http on loopback, production
+// always uses https://proxy.troxy.io. Re-dispatch here so both work
+// without the caller needing to know which.
+function _clientForProtocol(url) {
+  return url.startsWith('https:') ? https : http;
+}
+
+/** Attempts the Troxy-routed leg; resolves true if it fully served the
+ * response, false if it failed/timed out and the caller should fail open
+ * to _relayToRealHost instead. Never writes to `res` on a false
+ * resolution, so the caller can safely hand off afterward.
+ *
+ * Two separate deadlines, not one: `connectTimeoutMs` bounds how long we
+ * wait to establish the TCP/TLS connection to Troxy at all (a real
+ * unreachability signal - fail open fast). `responseTimeoutMs` is a much
+ * longer backstop that only starts once that connection is up, covering
+ * the wait for the model's own response (which can legitimately take
+ * several real seconds and has nothing to do with whether Troxy is
+ * healthy). */
+function _relayToTroxy(route, req, res, body, troxyKey, connectTimeoutMs, responseTimeoutMs, log) {
+  return new Promise((resolve) => {
+    const url = new URL(route.upstream);
+    const qsIdx = req.url.indexOf('?');
+    const search = qsIdx === -1 ? '' : req.url.slice(qsIdx);
+    let settled = false;
+    let connected = false;
+    let connectTimer = null;
+    // The socket to Troxy is very likely reused across many requests
+    // (Node's default agent keeps connections alive) - `socket.setTimeout`
+    // adds a NEW 'timeout' listener each call without removing the last
+    // one, so leaving this armed after settling leaks a listener onto a
+    // long-lived socket every single request (confirmed live:
+    // MaxListenersExceededWarning after ~11 real requests). Track exactly
+    // what we armed so it can always be torn down on settle, regardless of
+    // which branch settled it.
+    let timedSocket = null;
+    let responseTimeoutHandler = null;
+
+    const disarmResponseTimeout = () => {
+      if (timedSocket && responseTimeoutHandler) {
+        timedSocket.removeListener('timeout', responseTimeoutHandler);
+        timedSocket.setTimeout(0); // clear the idle timer so a reused socket starts clean for its next request
+      }
+      timedSocket = null;
+      responseTimeoutHandler = null;
+    };
+
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      disarmResponseTimeout();
+      resolve(result);
+    };
+
+    const upstreamReq = _clientForProtocol(route.upstream).request({
+      method: req.method,
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'http:' ? 80 : 443),
+      path: url.pathname + search,
+      headers: buildTroxyForwardHeaders(req.headers, troxyKey),
+    }, (upstreamRes) => {
+      if (settled) return; // already failed open on a timeout; drop this late arrival
+      settled = true;
+      clearTimeout(connectTimer);
+      disarmResponseTimeout();
+      // The only positive confirmation a real request was actually policy-
+      // evaluated by Troxy rather than relayed/fallen-open - previously
+      // this path logged nothing at all on success, so a live test had no
+      // way to tell "silently worked" apart from "silently never ran".
+      log('routed %s to troxy (%s) -> %d', req.url, route.upstream, upstreamRes.statusCode);
+      res.writeHead(upstreamRes.statusCode, upstreamRes.headers);
+      upstreamRes.pipe(res);
+      upstreamRes.on('end', () => resolve(true));
+      upstreamRes.on('error', () => resolve(true)); // response already started; not a fail-open case anymore
+    });
+
+    connectTimer = setTimeout(() => {
+      if (connected) return; // connection-phase deadline no longer applies once connected
+      upstreamReq.destroy();
+      settle(false);
+    }, connectTimeoutMs);
+    connectTimer.unref?.();
+
+    upstreamReq.on('socket', (socket) => {
+      const onConnected = () => {
+        connected = true;
+        clearTimeout(connectTimer);
+        if (settled) return; // response (or an error) already arrived before the connect event did
+        // Post-connect backstop: Troxy is reachable, so only a genuine
+        // hang (not normal model latency) should still fail open here.
+        responseTimeoutHandler = () => {
+          upstreamReq.destroy();
+          settle(false);
+        };
+        timedSocket = socket;
+        socket.setTimeout(responseTimeoutMs, responseTimeoutHandler);
+      };
+      if (!socket.connecting) onConnected(); // already connected (e.g. a reused keep-alive socket)
+      else socket.once(url.protocol === 'https:' ? 'secureConnect' : 'connect', onConnected);
+    });
+
+    upstreamReq.on('error', () => settle(false));
+    upstreamReq.end(body);
+  });
+}
+
+async function _handleInterceptedRequest(req, res, { routeResolver, getTroxyKey, troxyConnectTimeoutMs, troxyResponseTimeoutMs, log, lookup, ca }) {
+  const targetHost = req.socket._troxyTargetHost;
+  const targetPort = req.socket._troxyTargetPort || 443;
+  let body;
+  try {
+    body = await _drainBody(req);
+  } catch (err) {
+    log('failed to read intercepted request body: %s', err.message);
+    res.writeHead(400);
+    res.end();
+    return;
+  }
+
+  const route = routeResolver(targetHost, req.method, req.url);
+  if (route) {
+    const troxyKey = getTroxyKey();
+    if (troxyKey) {
+      const served = await _relayToTroxy(route, req, res, body, troxyKey, troxyConnectTimeoutMs, troxyResponseTimeoutMs, log);
+      if (served) return;
+      log('troxy upstream unreachable, failing open: relaying %s directly to %s', req.url, targetHost);
+    } else {
+      log('no troxy key available, failing open: relaying %s directly to %s', req.url, targetHost);
+    }
+  }
+
+  _relayToRealHost(targetHost, targetPort, req, res, body, log, lookup, ca);
+}
+
+function _blindTunnel(host, port, clientSocket, head, log, lookup) {
+  const upstream = net.connect({ host, port, ...(lookup ? { lookup } : {}) });
+  upstream.on('connect', () => {
+    if (head && head.length) upstream.write(head);
+    clientSocket.pipe(upstream);
+    upstream.pipe(clientSocket);
+  });
+  upstream.on('error', (err) => { log('blind tunnel to %s failed: %s', host, err.message); clientSocket.destroy(); });
+  clientSocket.on('error', () => upstream.destroy());
+  clientSocket.on('close', () => upstream.destroy());
+  upstream.on('close', () => clientSocket.destroy());
+}
+
+/**
+ * Creates the interceptor as an http.Server (not yet listening - call
+ * .listen() on it, same as any Node server). Options:
+ *  - interceptHosts: string[] - hosts to terminate TLS for; everything
+ *    else is a blind tunnel.
+ *  - routeResolver: (host, method, path) => {upstream} | undefined -
+ *    normally providers.js's troxyRouteFor bound to the enabled providers.
+ *  - getTroxyKey: () => string | null - called fresh per request, not
+ *    cached, so a key rotation takes effect without a daemon restart.
+ *  - getCerts: () => {leafCertPem, leafKeyPem} | null - null means
+ *    unhealthy; the interceptor tunnels the allowlisted host too rather
+ *    than fail.
+ *  - troxyConnectTimeoutMs: fail-open budget for reaching Troxy at all
+ *    (TCP+TLS connect) - real unreachability. troxyResponseTimeoutMs: a
+ *    much longer backstop that only starts once connected, covering the
+ *    model's own response time (not an outage signal - see _relayToTroxy).
+ *  - log: (fmt, ...args) => void
+ *  - lookup: optional custom DNS resolver, Node's standard (hostname,
+ *    options, callback) => void shape - passed straight through to the
+ *    outbound net.connect/https.request calls that reach a real target
+ *    host. Never needed in production (real DNS is exactly right there);
+ *    exists so tests can redirect a real hostname like api.anthropic.com
+ *    to a local stub server without touching production code paths.
+ *  - ca: optional extra trusted CA(s) for _relayToRealHost's own outbound
+ *    TLS verification of the real target host. Never needed in production
+ *    (Node's real trust store already trusts api.anthropic.com's real
+ *    cert) - exists only so a test's local stub server, presenting a
+ *    self-signed test cert, can be trusted without weakening what
+ *    production actually verifies against.
+ */
+export function createInterceptor({
+  interceptHosts,
+  routeResolver,
+  getTroxyKey,
+  getCerts,
+  troxyConnectTimeoutMs = DEFAULT_TROXY_CONNECT_TIMEOUT_MS,
+  troxyResponseTimeoutMs = DEFAULT_TROXY_RESPONSE_TIMEOUT_MS,
+  log = () => {},
+  lookup,
+  ca,
+}) {
+  const interceptedServer = http.createServer((req, res) => {
+    _handleInterceptedRequest(req, res, { routeResolver, getTroxyKey, troxyConnectTimeoutMs, troxyResponseTimeoutMs, log, lookup, ca })
+      .catch((err) => {
+        log('unexpected error handling intercepted request: %s', err.stack || err.message);
+        try { if (!res.headersSent) res.writeHead(502); res.end(); } catch {}
+      });
+  });
+  interceptedServer.on('clientError', (err, socket) => { try { socket.destroy(); } catch {} });
+  // Errors on individual TLS-terminated connections must never escape as
+  // uncaught 'error' events on the server itself (a single bad handshake
+  // must not take the whole interceptor down).
+  interceptedServer.on('error', (err) => log('intercepted-server error: %s', err.message));
+
+  const proxyServer = http.createServer((req, res) => {
+    res.writeHead(400, { 'content-type': 'text/plain' });
+    res.end('troxy interceptor: only CONNECT is supported\n');
+  });
+  proxyServer.on('clientError', (err, socket) => { try { socket.end('HTTP/1.1 400 Bad Request\r\n\r\n'); } catch {} });
+
+  proxyServer.on('connect', (req, clientSocket, head) => {
+    clientSocket.on('error', () => {}); // a reset/closed client connection is routine, not a crash
+    const { host, port } = parseConnectTarget(req.url);
+
+    try {
+      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+    } catch {
+      return; // client already gone
+    }
+
+    if (!interceptHosts.includes(host)) {
+      _blindTunnel(host, port, clientSocket, head, log, lookup);
+      return;
+    }
+
+    const certs = getCerts();
+    if (!certs) {
+      log('certificates unhealthy - tunneling %s instead of intercepting', host);
+      _blindTunnel(host, port, clientSocket, head, log, lookup);
+      return;
+    }
+
+    let tlsSocket;
+    try {
+      tlsSocket = new tls.TLSSocket(clientSocket, {
+        isServer: true,
+        cert: certs.leafCertPem,
+        key: certs.leafKeyPem,
+        // The real api.anthropic.com speaks HTTP/2, and a client that
+        // offers ALPN (Chromium's network stack - what the desktop app's
+        // Code tab actually uses, not Node's own https client - does this
+        // strictly) can abort the handshake outright if the server doesn't
+        // declare a protocol it's willing to accept, surfacing here as a
+        // bare ECONNRESET during the handshake rather than a clean TLS
+        // alert. This server only ever speaks HTTP/1.1 (interceptedServer
+        // is a plain http.Server fed via emit('connection', ...)), so
+        // declare exactly that - found live, a real client aborted every
+        // single connection attempt without this.
+        ALPNProtocols: ['http/1.1'],
+      });
+    } catch (err) {
+      log('failed to start TLS termination for %s: %s', host, err.message);
+      clientSocket.destroy();
+      return;
+    }
+    tlsSocket.on('error', (err) => {
+      log('tls handshake failed for %s: %s', host, err.message);
+      try { clientSocket.destroy(); } catch {}
+    });
+    tlsSocket._troxyTargetHost = host;
+    tlsSocket._troxyTargetPort = port;
+    if (head && head.length) tlsSocket.unshift(head);
+    interceptedServer.emit('connection', tlsSocket);
+  });
+
+  return proxyServer;
+}

package/src/providers.js

@@ -0,0 +1,84 @@
+/**
+ * The single source of truth for which hosts the local interceptor
+ * (interceptor.js) ever terminates TLS for, and where an intercepted
+ * request gets re-addressed to. Everything else - every other host the
+ * client talks to, and every path on an intercepted host that has no
+ * route here - passes through as a blind byte tunnel, never parsed, never
+ * visible to this codebase at all.
+ *
+ * Phase 1 (see the plan doc) is Anthropic only. openai_codex/cursor are
+ * declared here, disabled, purely so Phase 2/3 is a data change to this
+ * file later, not a rewrite of the interceptor or the CA logic - the
+ * provider's real divergence (Codex signs with CODEX_CA_CERTIFICATE, not
+ * NODE_EXTRA_CA_CERTS, since it's Rust-based) is already captured as a
+ * field, not hardcoded control flow, even though it isn't wired to
+ * anything yet. Do not flip `enabled` on either without first doing that
+ * phase's own hands-on verification - see the plan's Phase 2/3 section for
+ * exactly what's still unverified about each.
+ */
+
+export const PROVIDERS = [
+  {
+    id: 'anthropic',
+    name: 'Claude (Code + Desktop)',
+    enabled: true,
+    interceptHosts: ['api.anthropic.com'],
+    troxyRoutes: [
+      { method: 'POST', path: '/v1/messages', upstream: 'https://proxy.troxy.io/v1/messages' },
+    ],
+    envKeys: { proxy: 'HTTPS_PROXY', ca: 'NODE_EXTRA_CA_CERTS' },
+  },
+  {
+    id: 'openai_codex',
+    name: 'Codex CLI',
+    enabled: false, // Phase 2 - not wired up. See plan doc: no official network-config
+                     // doc exists for Codex, and whether its TLS stack enforces
+                     // nameConstraints the way OpenSSL does is unverified.
+    interceptHosts: ['api.openai.com'],
+    troxyRoutes: [],
+    envKeys: { proxy: 'HTTPS_PROXY', ca: 'CODEX_CA_CERTIFICATE' },
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    enabled: false, // Phase 3 - not wired up, shape genuinely unknown. See plan doc:
+                     // Cursor routes ALL traffic through its own backend even with
+                     // BYOK, so this would need to intercept api2.cursor.sh (Cursor
+                     // itself), not a model provider - a materially different,
+                     // unverified scope. Needs its own hands-on test before design.
+    interceptHosts: [],
+    troxyRoutes: [],
+    envKeys: {},
+  },
+];
+
+export function enabledProviders() {
+  return PROVIDERS.filter(p => p.enabled);
+}
+
+/** Every host any of the given providers' TLS should be terminated for -
+ * the interceptor's live allowlist. Anything not in this list is a blind
+ * tunnel, unconditionally. */
+export function interceptHostsFor(providers) {
+  return providers.flatMap(p => p.interceptHosts || []);
+}
+
+/** The Troxy route to re-address an intercepted request to, or undefined
+ * if this host+method+path has no configured route - in which case the
+ * interceptor relays it to the real host verbatim instead of proxying it
+ * (e.g. api.anthropic.com's own /api/oauth/account/settings, which has
+ * nothing to do with policy enforcement and must reach Anthropic
+ * unmodified). Case-insensitive on method; ignores any query string on
+ * the incoming path since a route is keyed on the path alone. */
+export function troxyRouteFor(providers, host, method, requestPath) {
+  const pathOnly = requestPath.split('?')[0];
+  for (const provider of providers) {
+    if (!(provider.interceptHosts || []).includes(host)) continue;
+    for (const route of provider.troxyRoutes || []) {
+      if (route.method.toUpperCase() === method.toUpperCase() && route.path === pathOnly) {
+        return route;
+      }
+    }
+  }
+  return undefined;
+}