troxy-cli 1.29.2 → 1.29.4

package/src/tests/interceptor.test.js

@@ -0,0 +1,559 @@
+// Layer 2's actual TCP/TLS listener. Design principle from the plan doc:
+// "interception is used only where nothing gentler works" - a host NOT on
+// the intercept allowlist is a pure blind byte tunnel (this file's plaintext
+// never sees it at all), and even an allowlisted host's traffic only gets
+// re-addressed to Troxy for the one specific route configured in
+// providers.js - everything else on that same host relays to the real
+// destination untouched. The pure header/parsing helpers are unit-tested in
+// isolation; the actual CONNECT+TLS+relay behavior is proven with real
+// sockets and a real TLS handshake, not mocked - verified directly via a
+// standalone smoke test before writing this file that Node's
+// `createConnection` socket-injection pattern actually works, since this
+// entire design leans on it.
+
+import { describe, it, after } from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import tls from 'node:tls';
+import http from 'node:http';
+import https from 'node:https';
+import { format } from 'node:util';
+
+import {
+  parseConnectTarget,
+  buildTroxyForwardHeaders,
+  buildRelayHeaders,
+  createInterceptor,
+} from '../interceptor.js';
+import { generateCA, generateLeaf } from '../tls-ca.js';
+
+describe('parseConnectTarget', () => {
+  it('splits host:port', () => {
+    assert.deepEqual(parseConnectTarget('api.anthropic.com:443'), { host: 'api.anthropic.com', port: 443 });
+  });
+
+  it('defaults to port 443 when none is given', () => {
+    assert.deepEqual(parseConnectTarget('api.anthropic.com'), { host: 'api.anthropic.com', port: 443 });
+  });
+
+  it('falls back to 443 on an unparseable port instead of NaN', () => {
+    assert.deepEqual(parseConnectTarget('api.anthropic.com:notaport'), { host: 'api.anthropic.com', port: 443 });
+  });
+});
+
+describe('buildTroxyForwardHeaders', () => {
+  it('translates the client\'s own Authorization into X-Troxy-Upstream-Authorization, ' +
+     'and sets Authorization to the Troxy key instead', () => {
+    const headers = buildTroxyForwardHeaders(
+      { authorization: 'Bearer sk-ant-oat01-realtoken', 'content-type': 'application/json' },
+      'txy-the-troxy-key',
+    );
+    assert.equal(headers.authorization, 'Bearer txy-the-troxy-key');
+    assert.equal(headers['x-troxy-upstream-authorization'], 'Bearer sk-ant-oat01-realtoken');
+    assert.equal(headers['content-type'], 'application/json');
+  });
+
+  it('omits x-troxy-upstream-authorization entirely when the client sent no credential', () => {
+    const headers = buildTroxyForwardHeaders({ 'content-type': 'application/json' }, 'txy-key');
+    assert.equal(headers['x-troxy-upstream-authorization'], undefined);
+    assert.equal(headers.authorization, 'Bearer txy-key');
+  });
+
+  it('drops hop-by-hop / connection-level headers that only made sense on the inbound leg', () => {
+    const headers = buildTroxyForwardHeaders(
+      { host: 'api.anthropic.com', connection: 'keep-alive', 'content-length': '123', authorization: 'Bearer x' },
+      'txy-key',
+    );
+    assert.equal(headers.host, undefined);
+    assert.equal(headers.connection, undefined);
+    assert.equal(headers['content-length'], undefined);
+  });
+});
+
+describe('buildRelayHeaders', () => {
+  it('preserves the client\'s own Authorization unmodified - this path talks to the ' +
+     'real host directly, not Troxy, so the client\'s real credential must go through as-is', () => {
+    const headers = buildRelayHeaders({ authorization: 'Bearer sk-ant-oat01-realtoken', accept: 'application/json' });
+    assert.equal(headers.authorization, 'Bearer sk-ant-oat01-realtoken');
+    assert.equal(headers.accept, 'application/json');
+  });
+
+  it('still drops host/connection - those are meaningless on a fresh outbound connection', () => {
+    const headers = buildRelayHeaders({ host: 'api.anthropic.com', connection: 'keep-alive' });
+    assert.equal(headers.host, undefined);
+    assert.equal(headers.connection, undefined);
+  });
+});
+
+// --- Integration: real sockets, real TLS, no mocks ---------------------
+
+function connectThroughProxy(proxyPort, targetHost, targetPort) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(proxyPort, '127.0.0.1', () => {
+      socket.write(`CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\nHost: ${targetHost}:${targetPort}\r\n\r\n`);
+    });
+    let buf = '';
+    function onData(chunk) {
+      buf += chunk.toString('latin1');
+      const idx = buf.indexOf('\r\n\r\n');
+      if (idx === -1) return;
+      socket.removeListener('data', onData);
+      if (buf.startsWith('HTTP/1.1 200')) resolve(socket);
+      else reject(new Error('CONNECT failed: ' + buf.slice(0, idx)));
+    }
+    socket.on('data', onData);
+    socket.on('error', reject);
+  });
+}
+
+function httpsOverConnectedSocket(rawSocket, { servername, ca, method = 'GET', path = '/', headers = {}, body = '' }) {
+  return new Promise((resolve, reject) => {
+    const tlsSocket = tls.connect({ socket: rawSocket, servername, ca, rejectUnauthorized: !!ca });
+    tlsSocket.on('error', reject);
+    tlsSocket.on('secureConnect', () => {
+      const req = https.request({ method, path, headers, createConnection: () => tlsSocket }, (res) => {
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => resolve({ statusCode: res.statusCode, headers: res.headers, body: Buffer.concat(chunks).toString() }));
+      });
+      req.on('error', reject);
+      req.end(body);
+    });
+  });
+}
+
+/** A plain TLS server standing in for a real destination (Anthropic, or a
+ * non-allowlisted host) - presents ITS OWN certificate, never Troxy's,
+ * so a blind-tunnel test can prove the client's TLS really terminates
+ * there and not at the interceptor. */
+function startStubTlsServer(certPem, keyPem, handler) {
+  return new Promise((resolve) => {
+    const server = tls.createServer({ cert: certPem, key: keyPem }, (socket) => {
+      http.createServer(handler).emit('connection', socket);
+    });
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+// Every stub server in these tests actually listens on 127.0.0.1, but
+// CONNECT targets use real-looking hostnames (api.anthropic.com,
+// example.com) to exercise the interceptor's real allowlist/SNI/cert logic
+// faithfully. In production, _relayToRealHost/_blindTunnel's real DNS
+// resolution is exactly correct - this override only exists so a test can
+// point that same hostname at a local stub instead of the real internet.
+const LOOPBACK_LOOKUP = (hostname, options, callback) => {
+  if (typeof options === 'function') { callback = options; options = {}; }
+  // Node's autoSelectFamily (Happy Eyeballs, on by default) calls lookup
+  // with {all: true} and expects an array of {address, family} back, not
+  // the single (err, address, family) shape - confirmed directly against
+  // a real https.request before relying on it. Handle both.
+  if (options.all) {
+    callback(null, [{ address: '127.0.0.1', family: 4 }]);
+  } else {
+    callback(null, '127.0.0.1', 4);
+  }
+};
+
+function startStubHttpServer(handler) {
+  return new Promise((resolve) => {
+    const server = http.createServer(handler);
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+describe('createInterceptor - integration, real sockets', () => {
+  const openServers = [];
+  after(() => { for (const s of openServers) { try { s.close(); } catch {} } });
+
+  it('negotiates ALPN down to http/1.1 when the client offers h2 first - found live: ' +
+     'the real desktop app aborted every handshake with ECONNRESET when the server ' +
+     'declared no ALPN protocols at all, since the real api.anthropic.com speaks HTTP/2 ' +
+     'and a strict client can refuse to proceed without an explicit protocol match', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => undefined,
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', 443);
+    const alpnProtocol = await new Promise((resolve, reject) => {
+      const tlsSocket = tls.connect({
+        socket: rawSocket, servername: 'api.anthropic.com', ca: [ca.certPem],
+        ALPNProtocols: ['h2', 'http/1.1'], // same offer order a real HTTP/2-capable client makes
+      });
+      tlsSocket.once('secureConnect', () => { resolve(tlsSocket.alpnProtocol); tlsSocket.destroy(); });
+      tlsSocket.once('error', reject);
+    });
+
+    assert.equal(alpnProtocol, 'http/1.1',
+      'the interceptor only ever speaks HTTP/1.1 internally - it must negotiate that explicitly, not leave ALPN unresolved');
+  });
+
+  it('an allowlisted host + matching route gets re-addressed to Troxy, ' +
+     'with the credential header translated', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const troxyRequests = [];
+    const troxyServer = await startStubHttpServer((req, res) => {
+      const chunks = [];
+      req.on('data', c => chunks.push(c));
+      req.on('end', () => {
+        troxyRequests.push({ method: req.method, url: req.url, headers: req.headers, body: Buffer.concat(chunks).toString() });
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end('{"ok":true,"from":"troxy"}');
+      });
+    });
+    openServers.push(troxyServer);
+    const troxyPort = troxyServer.address().port;
+
+    const logLines = [];
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: (host, method, path) => {
+        if (host === 'api.anthropic.com' && method === 'POST' && path.split('?')[0] === '/v1/messages') {
+          return { upstream: `http://127.0.0.1:${troxyPort}/v1/messages` };
+        }
+        return undefined;
+      },
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      troxyConnectTimeoutMs: 1000,
+      log: (fmt, ...args) => logLines.push(format(fmt, ...args)),
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', 443);
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'api.anthropic.com', ca: [ca.certPem],
+      method: 'POST', path: '/v1/messages?beta=true',
+      headers: { authorization: 'Bearer sk-ant-oat01-realtoken', 'content-type': 'application/json' },
+      body: '{"model":"claude-sonnet-5"}',
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, '{"ok":true,"from":"troxy"}');
+    assert.equal(troxyRequests.length, 1);
+    assert.equal(troxyRequests[0].headers.authorization, 'Bearer txy-test-key');
+    assert.ok(
+      logLines.some(l => l.includes('routed') && l.includes('/v1/messages?beta=true') && l.includes('200')),
+      // Previously this success path logged nothing at all - a live test
+      // had no way to tell "silently worked" apart from "silently never
+      // ran" without checking the dashboard for a decision_source row.
+      `expected a "routed ... to troxy" confirmation log line, got: ${JSON.stringify(logLines)}`,
+    );
+    assert.equal(troxyRequests[0].headers['x-troxy-upstream-authorization'], 'Bearer sk-ant-oat01-realtoken');
+    assert.equal(troxyRequests[0].body, '{"model":"claude-sonnet-5"}');
+  });
+
+  it('an allowlisted host but a path with NO configured route relays straight to the ' +
+     'real host, with the client\'s own credential untouched - not everything on an ' +
+     'intercepted host goes through Troxy', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const realRequests = [];
+    const realServer = await startStubTlsServer(leaf.certPem, leaf.keyPem, (req, res) => {
+      realRequests.push({ url: req.url, headers: req.headers });
+      res.writeHead(200, {});
+      res.end('real-anthropic-response');
+    });
+    openServers.push(realServer);
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => undefined, // nothing configured - simulates e.g. GET /api/oauth/account/settings
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      lookup: LOOPBACK_LOOKUP,
+      ca: [ca.certPem], // the interceptor's OWN outbound trust for reaching the stub "real host"
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', realServer.address().port);
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'api.anthropic.com', ca: [ca.certPem],
+      method: 'GET', path: '/api/oauth/account/settings',
+      headers: { authorization: 'Bearer sk-ant-oat01-realtoken' },
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, 'real-anthropic-response');
+    assert.equal(realRequests[0].headers.authorization, 'Bearer sk-ant-oat01-realtoken',
+      'the client\'s own credential must reach the real host unmodified');
+  });
+
+  it('a host NOT on the intercept allowlist is a blind tunnel - the client\'s TLS ' +
+     'terminates at the REAL destination\'s own certificate, never at Troxy\'s', async () => {
+    // A completely unrelated CA/cert pair, standing in for a real site the
+    // interceptor was never told to intercept - if this succeeds, the
+    // client's TLS handshake happened end-to-end with THIS cert, proving
+    // the interceptor never touched the encrypted bytes at all. Scoped to
+    // example.com, not the default api.anthropic.com - generateCA's
+    // nameConstraints default stands in for TROXY's own CA specifically;
+    // a genuinely unrelated real-world site's CA has no such restriction
+    // at all, so forcing this one to actually permit example.com is what
+    // makes it a faithful stand-in, not an accidental second exercise of
+    // the same restriction this test isn't about.
+    const otherCa = generateCA('unrelated', ['example.com']);
+    const otherLeaf = generateLeaf(otherCa.certPem, otherCa.keyPem, ['example.com']);
+    const targetServer = await startStubTlsServer(otherLeaf.certPem, otherLeaf.keyPem, (req, res) => {
+      res.writeHead(200, {});
+      res.end('untouched-by-troxy');
+    });
+    openServers.push(targetServer);
+
+    const troxyCa = generateCA('test-host'); // the interceptor's own CA - irrelevant here
+    const troxyLeaf = generateLeaf(troxyCa.certPem, troxyCa.keyPem, ['api.anthropic.com']);
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'], // example.com is deliberately NOT on this list
+      routeResolver: () => undefined,
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: troxyLeaf.certPem, leafKeyPem: troxyLeaf.keyPem }),
+      lookup: LOOPBACK_LOOKUP,
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'example.com', targetServer.address().port);
+    // Trusting only the TARGET's own CA (not Troxy's) - if the interceptor
+    // tried to terminate this with its own leaf instead of tunneling, this
+    // handshake would fail outright.
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'example.com', ca: [otherCa.certPem], path: '/',
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, 'untouched-by-troxy');
+  });
+
+  it('fail-open: Troxy upstream unreachable falls back to relaying the intercepted ' +
+     'request directly to the real host instead of erroring the client\'s request', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const realServer = await startStubTlsServer(leaf.certPem, leaf.keyPem, (req, res) => {
+      res.writeHead(200, {});
+      res.end('real-anthropic-fallback-response');
+    });
+    openServers.push(realServer);
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: (host, method, path) =>
+        (path.split('?')[0] === '/v1/messages') ? { upstream: 'http://127.0.0.1:1/v1/messages' } : undefined, // port 1: nothing listens, connection refused fast
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      troxyConnectTimeoutMs: 500,
+      lookup: LOOPBACK_LOOKUP,
+      ca: [ca.certPem],
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', realServer.address().port);
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'api.anthropic.com', ca: [ca.certPem],
+      method: 'POST', path: '/v1/messages',
+      headers: { authorization: 'Bearer sk-ant-oat01-realtoken' }, body: '{}',
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, 'real-anthropic-fallback-response',
+      'a dead Troxy upstream must not break the user\'s actual Claude Code usage');
+  });
+
+  it('a slow-but-connected Troxy response is NOT treated as fail-open, even well past the ' +
+     'connect-timeout budget - found live: a real model response commonly takes several ' +
+     'real seconds of time-to-first-token, which is not an outage signal', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const troxyServer = await startStubHttpServer((req, res) => {
+      // Deliberately much longer than the tiny connect-timeout below, but
+      // well under the response-timeout - simulates a real model actually
+      // thinking, not Troxy being down.
+      setTimeout(() => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end('{"ok":true,"from":"troxy","slow":true}');
+      }, 300);
+    });
+    openServers.push(troxyServer);
+    const troxyPort = troxyServer.address().port;
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => ({ upstream: `http://127.0.0.1:${troxyPort}/v1/messages` }),
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      troxyConnectTimeoutMs: 50,   // connecting to a local stub is near-instant either way
+      troxyResponseTimeoutMs: 5000, // generous enough to outlast the stub's 300ms "thinking"
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', 443);
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'api.anthropic.com', ca: [ca.certPem],
+      method: 'POST', path: '/v1/messages',
+      headers: { authorization: 'Bearer sk-ant-oat01-realtoken' }, body: '{}',
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, '{"ok":true,"from":"troxy","slow":true}',
+      'a slow-but-reachable Troxy response must still be served, not abandoned for a direct fallback');
+  });
+
+  it('reusing a keep-alive connection to Troxy across many requests does not leak ' +
+     '"timeout" listeners on the socket - found live: MaxListenersExceededWarning after ' +
+     'about 11 real requests, since socket.setTimeout(ms, cb) adds a NEW listener every ' +
+     'call without removing the last one', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    const troxyServer = await startStubHttpServer((req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end('{"ok":true}');
+    });
+    openServers.push(troxyServer);
+    const troxyPort = troxyServer.address().port;
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => ({ upstream: `http://127.0.0.1:${troxyPort}/v1/messages` }),
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      troxyConnectTimeoutMs: 1000,
+      troxyResponseTimeoutMs: 2000,
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    // Forces real connection reuse on the interceptor's own OUTBOUND leg to
+    // Troxy deterministically, rather than depending on whatever this Node
+    // version's ambient global-agent keepAlive default happens to be (it
+    // varies by version; production hits this exact path either way once a
+    // real client sends enough sequential requests). Each iteration below
+    // is its own separate CLIENT connection (same proven pattern as every
+    // other test in this file) - what matters for this leak is only
+    // whether the INTERCEPTOR's own request to Troxy reuses a socket
+    // across those, which depends solely on the shared global agent.
+    const originalKeepAlive = http.globalAgent.keepAlive;
+    http.globalAgent.keepAlive = true;
+    const warnings = [];
+    const onWarning = (w) => warnings.push(w);
+    process.on('warning', onWarning);
+
+    try {
+      // One more than Node's default MaxListeners (10) - exactly the shape
+      // that surfaced this live.
+      for (let i = 0; i < 11; i++) {
+        const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', 443);
+        const result = await httpsOverConnectedSocket(rawSocket, {
+          servername: 'api.anthropic.com', ca: [ca.certPem],
+          method: 'POST', path: '/v1/messages',
+          headers: { authorization: 'Bearer x' }, body: '{}',
+        });
+        assert.equal(result.statusCode, 200);
+      }
+      await new Promise((r) => setImmediate(r)); // let any deferred 'warning' emission surface
+    } finally {
+      process.removeListener('warning', onWarning);
+      http.globalAgent.keepAlive = originalKeepAlive;
+      // Forcing keepAlive above made the interceptor's outbound leg to the
+      // stub Troxy server pool real, reused sockets on the GLOBAL agent -
+      // restoring keepAlive alone does not close those already-pooled
+      // sockets. Left open, they're handles Node won't exit on, which is
+      // invisible locally (the process exits anyway once the whole suite's
+      // other activity winds down) but hangs `node --test` indefinitely in
+      // CI once this is the last real activity in the run - found live
+      // 2026-09-08, Node 18 in GitHub Actions timed out at 5 minutes with
+      // no further output after this suite's last test finished, while
+      // Node 20/22 happened not to hang on the exact same code (a timing/
+      // GC difference between versions, not a reason to trust either).
+      http.globalAgent.destroy();
+    }
+
+    const leakWarnings = warnings.filter(w => w.name === 'MaxListenersExceededWarning' && /timeout/i.test(w.message));
+    assert.equal(leakWarnings.length, 0,
+      `expected no listener-leak warning, got: ${leakWarnings.map(w => w.message).join('; ')}`);
+  });
+
+  it('a Troxy upstream that connects but then genuinely hangs past troxyResponseTimeoutMs ' +
+     'still fails open eventually - the post-connect backstop is not "never time out"', async () => {
+    const ca = generateCA('test-host');
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+
+    // Accepts the connection but never responds at all - a genuine hang,
+    // not normal model latency.
+    const troxyServer = await startStubHttpServer(() => {});
+    openServers.push(troxyServer);
+    const troxyPort = troxyServer.address().port;
+
+    const realServer = await startStubTlsServer(leaf.certPem, leaf.keyPem, (req, res) => {
+      res.writeHead(200, {});
+      res.end('real-anthropic-fallback-after-hang');
+    });
+    openServers.push(realServer);
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => ({ upstream: `http://127.0.0.1:${troxyPort}/v1/messages` }),
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => ({ leafCertPem: leaf.certPem, leafKeyPem: leaf.keyPem }),
+      troxyConnectTimeoutMs: 500,
+      troxyResponseTimeoutMs: 300, // short only so the test doesn't wait 55s for real
+      lookup: LOOPBACK_LOOKUP,
+      ca: [ca.certPem],
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', realServer.address().port);
+    const result = await httpsOverConnectedSocket(rawSocket, {
+      servername: 'api.anthropic.com', ca: [ca.certPem],
+      method: 'POST', path: '/v1/messages',
+      headers: { authorization: 'Bearer sk-ant-oat01-realtoken' }, body: '{}',
+    });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, 'real-anthropic-fallback-after-hang');
+  });
+
+  it('fail-open: unhealthy/missing certs tunnel the allowlisted host too, instead of throwing', async () => {
+    const ca = generateCA('test-host'); // used only to sign the stub target's cert
+    const leaf = generateLeaf(ca.certPem, ca.keyPem, ['api.anthropic.com']);
+    const realServer = await startStubTlsServer(leaf.certPem, leaf.keyPem, (req, res) => {
+      res.writeHead(200, {});
+      res.end('tunneled-because-cert-unhealthy');
+    });
+    openServers.push(realServer);
+
+    const interceptor = createInterceptor({
+      interceptHosts: ['api.anthropic.com'],
+      routeResolver: () => ({ upstream: 'http://127.0.0.1:1/v1/messages' }),
+      getTroxyKey: () => 'txy-test-key',
+      getCerts: () => null, // simulates a missing/corrupt/expired cert with no healthy fallback
+      lookup: LOOPBACK_LOOKUP,
+    });
+    await new Promise(r => interceptor.listen(0, '127.0.0.1', r));
+    openServers.push(interceptor);
+
+    const rawSocket = await connectThroughProxy(interceptor.address().port, 'api.anthropic.com', realServer.address().port);
+    // Trusting the TARGET's cert directly, same as the blind-tunnel test -
+    // if the interceptor tried to terminate anyway despite getCerts()
+    // returning null, this would fail since it has nothing valid to present.
+    const result = await httpsOverConnectedSocket(rawSocket, { servername: 'api.anthropic.com', ca: [ca.certPem], path: '/' });
+
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body, 'tunneled-because-cert-unhealthy');
+  });
+});

package/src/tests/providers.test.js

@@ -0,0 +1,78 @@
+// The single source of truth for which hosts the local interceptor ever
+// terminates TLS for, and where an intercepted request gets re-addressed
+// to. Only 'anthropic' is enabled in Phase 1 - openai_codex/cursor are
+// declared but disabled, so Phase 2/3 becomes a data change later, not a
+// rewrite (see the plan doc). The critical property this file's tests
+// guard: a disabled provider must NEVER contribute to the live intercept
+// allowlist - that's the guardrail against a Phase-2 stub silently
+// widening what gets MITM'd before it's actually ready.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { PROVIDERS, enabledProviders, interceptHostsFor, troxyRouteFor } from '../providers.js';
+
+describe('PROVIDERS', () => {
+  it('anthropic is enabled in Phase 1', () => {
+    const anthropic = PROVIDERS.find(p => p.id === 'anthropic');
+    assert.equal(anthropic.enabled, true);
+    assert.deepEqual(anthropic.interceptHosts, ['api.anthropic.com']);
+  });
+
+  it('codex and cursor are declared but NOT enabled - Phase 1 is Anthropic only', () => {
+    const codex = PROVIDERS.find(p => p.id === 'openai_codex');
+    const cursor = PROVIDERS.find(p => p.id === 'cursor');
+    assert.equal(codex.enabled, false);
+    assert.equal(cursor.enabled, false);
+  });
+});
+
+describe('enabledProviders', () => {
+  it('returns only providers with enabled: true', () => {
+    const providers = enabledProviders();
+    assert.ok(providers.every(p => p.enabled === true));
+    assert.ok(providers.some(p => p.id === 'anthropic'));
+    assert.ok(!providers.some(p => p.id === 'openai_codex'));
+    assert.ok(!providers.some(p => p.id === 'cursor'));
+  });
+});
+
+describe('interceptHostsFor', () => {
+  it('an enabled-only provider list yields exactly api.anthropic.com in Phase 1', () => {
+    assert.deepEqual(interceptHostsFor(enabledProviders()), ['api.anthropic.com']);
+  });
+
+  it('a disabled provider passed in explicitly contributes nothing - ' +
+     'enabling it later must be a deliberate PROVIDERS edit, not automatic', () => {
+    const cursor = PROVIDERS.find(p => p.id === 'cursor');
+    assert.deepEqual(interceptHostsFor([cursor]), []);
+  });
+
+  it('empty input yields an empty allowlist, not an error', () => {
+    assert.deepEqual(interceptHostsFor([]), []);
+  });
+});
+
+describe('troxyRouteFor', () => {
+  it('matches the configured /v1/messages route for api.anthropic.com', () => {
+    const route = troxyRouteFor(enabledProviders(), 'api.anthropic.com', 'POST', '/v1/messages');
+    assert.ok(route, 'expected a route match');
+    assert.equal(route.upstream, 'https://proxy.troxy.io/v1/messages');
+  });
+
+  it('returns undefined for a path on an intercepted host that has no configured route ' +
+     '(e.g. /api/oauth/account/settings) - the interceptor must relay these verbatim, not proxy them', () => {
+    const route = troxyRouteFor(enabledProviders(), 'api.anthropic.com', 'GET', '/api/oauth/account/settings');
+    assert.equal(route, undefined);
+  });
+
+  it('returns undefined for a host that is not on the intercept allowlist at all', () => {
+    const route = troxyRouteFor(enabledProviders(), 'evil.example.com', 'POST', '/v1/messages');
+    assert.equal(route, undefined);
+  });
+
+  it('is case-insensitive and query-string-agnostic on the path match', () => {
+    const route = troxyRouteFor(enabledProviders(), 'api.anthropic.com', 'post', '/v1/messages?beta=true');
+    assert.ok(route, 'expected a route match despite lowercase method and a query string');
+  });
+});