@volter/twin-world 0.1.0

package/src/redirect-proxy.ts

@@ -0,0 +1,437 @@
+// The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
+// redirection works", tier 1). A local TLS-terminating forward proxy that maps vendor API hosts
+// (api.stripe.com, api.github.com, …) → the world's twin services, so an UNMODIFIED `gh`/`stripe`/
+// `curl`/app — anything that honors HTTPS_PROXY + a CA bundle env — transparently lands in the twins
+// with no per-tool config.
+//
+// Mechanism:
+//   - The host→twin table is reused from `@volter/twin/inject` (`VENDOR_HOSTS` + `readMap` +
+//     `resolveTwin`) so this proxy and the Node injector never drift. No vendor names live here.
+//   - A throwaway, session-scoped CA (per instance dir) signs per-host leaf certs on the fly. The CA
+//     is trusted ONLY via the per-shell env (`NODE_EXTRA_CA_CERTS`, `CURL_CA_BUNDLE`, …) that
+//     `activate`/`shell` export — never installed system-wide. `down` drops it.
+//   - On CONNECT to a matched vendor host, the proxy MITM-terminates TLS (leaf cert for that SNI) and
+//     forwards the decrypted request to the twin over plain HTTP. CONNECT to any OTHER host is blind-
+//     tunneled to the real origin untouched, so non-vendor traffic in the shell still works normally.
+//
+// Cert tooling: we shell out to `openssl` (already a dev prerequisite; node:crypto can generate keys
+// but cannot mint X.509 certs without a third-party lib). This keeps world-runtime dependency-light.
+import { spawnSync } from 'node:child_process';
+import { Socket, connect as netConnect, createServer as createNetServer } from 'node:net';
+import { createServer as createHttpsServer } from 'node:https';
+import type { Server as HttpsServer } from 'node:https';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { request as httpRequest } from 'node:http';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+
+/** The slice of `@volter/twin/inject` we reuse for the host→twin table (so we never re-encode the
+ * vendor host predicates here — they stay one source of truth with the Node injector). */
+type InjectModule = {
+  readMap(env: Record<string, string | undefined>): Record<string, string>;
+  resolveTwin(host: string, map: Record<string, string>): { vendor: string; origin: string } | null;
+  VENDOR_HOSTS: Record<string, (host: string) => boolean>;
+  restore(): void;
+};
+
+let injectCache: InjectModule | null = null;
+
+/** Lazily load the injector's host→twin table. Loading the CJS auto-installs its http/fetch patches
+ * as a side effect; we immediately `restore()` so requiring it here is inert (we only want the data
+ * + pure functions, not to patch THIS process). Not exported: no importer outside this file uses it
+ * directly (external callers go through `proxyTargetFor`/`activeVendorMap`). */
+function loadInject(): InjectModule {
+  if (injectCache) return injectCache;
+  const require = createRequire(import.meta.url);
+  const mod = require('@volter/twin/inject') as InjectModule;
+  try { mod.restore(); } catch { /* nothing was installed */ }
+  injectCache = mod;
+  return mod;
+}
+
+/** Resolve which twin origin (if any) a vendor host maps to, given the world env (which carries the
+ * `*_TWIN_URL` vars). Returns null for hosts the world doesn't twin — those are tunneled untouched. */
+export function proxyTargetFor(hostname: string, env: Record<string, string | undefined>): { vendor: string; origin: string } | null {
+  const inject = loadInject();
+  return inject.resolveTwin(hostname, inject.readMap(env));
+}
+
+/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
+export function activeVendorMap(env: Record<string, string | undefined>): Record<string, string> {
+  return loadInject().readMap(env);
+}
+
+function strictEgressEnabled(env: Record<string, string | undefined>): boolean {
+  return env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+}
+
+function isLocalOrPrivateHost(hostname: string): boolean {
+  const h = String(hostname || '').toLowerCase();
+  if (!h) return true;
+  if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.test')) return true;
+  if (h === '0.0.0.0' || h === '127.0.0.1' || h === '::1' || h === '[::1]') return true;
+  if (/^127\./.test(h)) return true;
+  if (/^10\./.test(h)) return true;
+  if (/^192\.168\./.test(h)) return true;
+  const match = h.match(/^172\.(\d+)\./);
+  if (match) {
+    const n = Number(match[1]);
+    if (n >= 16 && n <= 31) return true;
+  }
+  return false;
+}
+
+function shouldBlockUntwinned(hostname: string, env: Record<string, string | undefined>): boolean {
+  return strictEgressEnabled(env) && !isLocalOrPrivateHost(hostname) && !proxyTargetFor(hostname, env);
+}
+
+// --- session-scoped CA + on-the-fly leaf certs (via openssl) ---------------------------------
+
+// Not exported: no importer outside this file references the type by name (`ensureCa`/`leafCertFor`
+// callers rely on inference).
+type CaPaths = { dir: string; caKey: string; caCert: string };
+
+function caPaths(tlsDir: string): CaPaths {
+  return { dir: tlsDir, caKey: join(tlsDir, 'ca-key.pem'), caCert: join(tlsDir, 'ca-cert.pem') };
+}
+
+export function opensslAvailable(): boolean {
+  // TEST-ONLY seam (TWIN-64): forces "openssl unavailable" deterministically. A PATH-shim (fake
+  // `openssl` on PATH) doesn't reliably work here because `spawnSync('openssl', …)` below is called
+  // with no explicit `env`, and some runtimes resolve the executable against a PATH snapshotted at
+  // process start rather than a same-process `process.env.PATH` mutation made mid-test. Never set
+  // this env var in real usage.
+  if (process.env.VOLTER_TEST_NO_OPENSSL === '1') return false;
+  const r = spawnSync('openssl', ['version'], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+function runOpenssl(args: string[]): string {
+  const r = spawnSync('openssl', args, { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`openssl ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`);
+  return r.stdout;
+}
+
+/** Generate (once) a throwaway CA in `tlsDir`. Idempotent: reuses an existing CA so a re-activate in
+ * the same world trusts the same cert. Session/project-scoped — it lives under the instance dir and
+ * is removed by `tearDownCa` on `down`. */
+export function ensureCa(tlsDir: string): CaPaths {
+  if (!opensslAvailable()) {
+    throw new Error('openssl not found — the TLS redirect proxy needs openssl to mint a session CA. Install openssl, or use per-CLI endpoint env (cliRedirect) instead.');
+  }
+  const paths = caPaths(tlsDir);
+  if (existsSync(paths.caKey) && existsSync(paths.caCert)) return paths;
+  mkdirSync(tlsDir, { recursive: true });
+  runOpenssl(['genrsa', '-out', paths.caKey, '2048']);
+  runOpenssl([
+    'req', '-x509', '-new', '-nodes', '-key', paths.caKey,
+    '-sha256', '-days', '3650', '-out', paths.caCert,
+    '-subj', '/CN=volter-world session CA/O=volter-world',
+  ]);
+  return paths;
+}
+
+/** Remove the session CA + any minted leaf certs. Called on `down` so the trusted CA never outlives
+ * the world (it was only ever trusted via the per-shell env, never system-wide). */
+export function tearDownCa(tlsDir: string): void {
+  leafCache.clear();
+  rmSync(tlsDir, { recursive: true, force: true });
+}
+
+const leafCache = new Map<string, { key: string; cert: string }>();
+
+/** Mint (and cache) a leaf cert for `host`, signed by the session CA. SAN = the host so the client
+ * accepts it for that SNI. */
+export function leafCertFor(host: string, ca: CaPaths): { key: string; cert: string } {
+  const cached = leafCache.get(host);
+  if (cached) return cached;
+  const safe = host.replace(/[^A-Za-z0-9._-]/g, '_');
+  const keyPath = join(ca.dir, `leaf-${safe}-key.pem`);
+  const csrPath = join(ca.dir, `leaf-${safe}.csr`);
+  const certPath = join(ca.dir, `leaf-${safe}.pem`);
+  const extPath = join(ca.dir, `leaf-${safe}.ext`);
+  runOpenssl(['genrsa', '-out', keyPath, '2048']);
+  runOpenssl(['req', '-new', '-key', keyPath, '-out', csrPath, '-subj', `/CN=${host}`]);
+  writeFileSync(extPath, `subjectAltName=DNS:${host}\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n`);
+  runOpenssl([
+    // 397 days, NOT the CA's 3650: macOS's system verifier (used by Go — `gh`, and any Go/Swift
+    // client) rejects a LEAF cert valid >398 days as "certificate is not standards compliant"
+    // (CA/Browser-Forum max). The session CA itself is exempt and stays long-lived.
+    'x509', '-req', '-in', csrPath, '-CA', ca.caCert, '-CAkey', ca.caKey,
+    '-CAcreateserial', '-out', certPath, '-days', '397', '-sha256', '-extfile', extPath,
+  ]);
+  const minted = { key: readFileSync(keyPath, 'utf8'), cert: readFileSync(certPath, 'utf8') };
+  leafCache.set(host, minted);
+  return minted;
+}
+
+// --- the proxy server ------------------------------------------------------------------------
+
+// Neither type below is exported: `startRedirectProxy` is the only consumer of these names outside
+// this file, and its callers (runtime.ts) rely on inference (`Awaited<ReturnType<typeof
+// startRedirectProxy>>`) rather than importing the type names.
+type RedirectProxyOptions = {
+  /** The world env — supplies the `*_TWIN_URL` host→twin map. */
+  env?: Record<string, string | undefined>;
+  /** Optional dynamic env source. Used by the detached world daemon while services are still adding
+   * `*_TWIN_URL` vars during `up`; each proxied request resolves against the latest file-backed env. */
+  envLoader?: () => Record<string, string | undefined>;
+  /** Where the session CA + leaf certs live (instance dir/tls). */
+  tlsDir: string;
+  /** Listen host (default 127.0.0.1) and port (default 0 = ephemeral). */
+  host?: string;
+  port?: number;
+};
+
+type RedirectProxyHandle = {
+  port: number;
+  host: string;
+  caCertPath: string;
+  url: string;
+  /** The cert-trust + proxy env an activate/shell session exports to route through this proxy. */
+  proxyEnv(): Record<string, string>;
+  close(): Promise<void>;
+};
+
+/** Forward a single decrypted (or plain-HTTP) request to the resolved twin origin and pipe the
+ * response back. The twin speaks plain HTTP locally, so we strip TLS here and re-issue http. */
+function forwardToTwin(origin: string, clientReq: IncomingMessage, clientRes: ServerResponse): void {
+  let target: URL;
+  try {
+    target = new URL(origin);
+  } catch {
+    clientRes.writeHead(502); clientRes.end('bad twin origin'); return;
+  }
+  const headers = { ...clientReq.headers };
+  delete headers['proxy-connection'];
+  delete headers['accept-encoding'];
+  const upstream = httpRequest(
+    {
+      protocol: 'http:',
+      hostname: target.hostname,
+      port: target.port || 80,
+      method: clientReq.method,
+      path: clientReq.url,
+      headers,
+    },
+    (upRes) => {
+      clientRes.writeHead(upRes.statusCode ?? 502, upRes.headers);
+      upRes.pipe(clientRes);
+    },
+  );
+  upstream.on('error', (err) => { clientRes.writeHead(502); clientRes.end(`twin unreachable: ${err.message}`); });
+  clientReq.pipe(upstream);
+}
+
+/** Start the ambient redirect proxy. Returns a handle with the listen port + the env to export.
+ * - Plain `http://` proxied requests to a vendor host → forwarded to the twin.
+ * - `CONNECT host:443` to a vendor host → MITM-terminated with a session-signed leaf, decrypted, and
+ *   forwarded to the twin. CONNECT to any other host → blind-tunneled to the real origin untouched. */
+export async function startRedirectProxy(options: RedirectProxyOptions): Promise<RedirectProxyHandle> {
+  const host = options.host ?? '127.0.0.1';
+  const currentEnv = (): Record<string, string | undefined> => options.envLoader?.() ?? options.env ?? {};
+  const ca = ensureCa(options.tlsDir);
+  // Track raw client/upstream sockets so close() can forcibly drop tunnels (a blind tunnel to a slow
+  // or real upstream would otherwise keep the server from closing).
+  const openSockets = new Set<Socket>();
+
+  // The MITM TLS endpoint(s): a REAL listening https server PER vendor host (loopback, ephemeral
+  // port), each pinned to that host's leaf cert as its default cert. On CONNECT to a vendor host we
+  // tunnel the client's raw bytes to the matching per-host server, which terminates TLS and forwards
+  // the decrypted request to the resolved twin. (A single SNICallback server is the textbook design,
+  // but Node-compatible SNICallback isn't honored on Bun — so we bind one server per host instead,
+  // which works on both runtimes. Hosts are few and known from the world's vendor map.)
+  const tlsServers = new Map<string, HttpsServer>();
+  const tlsPorts = new Map<string, number>();
+  const ensureHostServer = async (vendorHost: string): Promise<number> => {
+    const existing = tlsPorts.get(vendorHost);
+    if (existing) return existing;
+    const leaf = leafCertFor(vendorHost, ca);
+    const hostServer = createHttpsServer(
+      { key: leaf.key, cert: leaf.cert },
+      (req: IncomingMessage, res: ServerResponse) => {
+        const hostHeader = (req.headers.host ?? vendorHost).split(':')[0] ?? vendorHost;
+        const env = currentEnv();
+        const twin = proxyTargetFor(hostHeader, env) ?? proxyTargetFor(vendorHost, env);
+        if (!twin) { res.writeHead(502); res.end('no twin for host'); return; }
+        forwardToTwin(twin.origin, req, res);
+      },
+    );
+    await new Promise<void>((r, reject) => { hostServer.once('error', reject); hostServer.listen(0, '127.0.0.1', () => r()); });
+    const a = hostServer.address();
+    const p = typeof a === 'object' && a ? a.port : 0;
+    tlsServers.set(vendorHost, hostServer);
+    tlsPorts.set(vendorHost, p);
+    return p;
+  };
+
+  const server = createNetServer((clientSocket: Socket) => {
+    openSockets.add(clientSocket);
+    clientSocket.on('close', () => openSockets.delete(clientSocket));
+    clientSocket.on('error', () => clientSocket.destroy());
+
+    let buffered = Buffer.alloc(0);
+    const onData = (chunk: Buffer) => {
+      buffered = Buffer.concat([buffered, chunk]);
+      const headerEnd = buffered.indexOf('\r\n\r\n');
+      if (headerEnd === -1) return;
+      clientSocket.removeListener('data', onData);
+
+      const headerBytes = buffered.subarray(0, headerEnd + 4);
+      const head = buffered.subarray(headerEnd + 4);
+      const headerText = headerBytes.toString('latin1');
+      const [requestLine = '', ...headerLines] = headerText.split('\r\n');
+      const [method = '', urlStr = '', version = 'HTTP/1.1'] = requestLine.split(' ');
+      const headers: Record<string, string> = {};
+      for (const line of headerLines) {
+        if (!line) continue;
+        const idx = line.indexOf(':');
+        if (idx === -1) continue;
+        headers[line.slice(0, idx).toLowerCase()] = line.slice(idx + 1).trim();
+      }
+
+      if (method.toUpperCase() === 'CONNECT') {
+        handleConnect(urlStr, clientSocket, head);
+        return;
+      }
+
+      handlePlainProxyRequest(method, urlStr, version, headers, clientSocket, head);
+    };
+    clientSocket.on('data', onData);
+  });
+
+  const writeResponse = (socket: Socket, status: string, body: string): void => {
+    socket.write(`${status}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`);
+    socket.end();
+  };
+
+  const forwardRawHttp = (
+    origin: URL,
+    method: string,
+    path: string,
+    version: string,
+    headers: Record<string, string>,
+    socket: Socket,
+    head: Buffer,
+  ): void => {
+    const upstream = netConnect(Number(origin.port || 80), origin.hostname, () => {
+      const outHeaders = { ...headers };
+      delete outHeaders['proxy-connection'];
+      delete outHeaders['accept-encoding'];
+      upstream.write(`${method} ${path} ${version}\r\n`);
+      for (const [name, value] of Object.entries(outHeaders)) upstream.write(`${name}: ${value}\r\n`);
+      upstream.write('\r\n');
+      if (head.length) upstream.write(head);
+      socket.pipe(upstream);
+      upstream.pipe(socket);
+    });
+    openSockets.add(upstream);
+    upstream.on('close', () => openSockets.delete(upstream));
+    upstream.on('error', (err) => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', `upstream error: ${err.message}\n`));
+  };
+
+  const handlePlainProxyRequest = (
+    method: string,
+    urlStr: string,
+    version: string,
+    headers: Record<string, string>,
+    socket: Socket,
+    head: Buffer,
+  ): void => {
+    try {
+      const u = new URL(urlStr);
+      const twin = proxyTargetFor(u.hostname, currentEnv());
+      const path = u.pathname + u.search;
+      if (twin) {
+        const target = new URL(twin.origin);
+        forwardRawHttp(target, method, path, version, headers, socket, head);
+        return;
+      }
+      if (shouldBlockUntwinned(u.hostname, currentEnv())) {
+        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', `blocked untwinned external request to ${u.hostname}\n`);
+        return;
+      }
+      // Non-vendor: plain pass-through to the real host.
+      forwardRawHttp(new URL(`${u.protocol}//${u.host}`), method, path, version, headers, socket, head);
+    } catch {
+      writeResponse(socket, 'HTTP/1.1 400 Bad Request', 'bad request\n');
+    }
+  };
+
+  const handleConnect = (urlStr: string, clientSocket: Socket, head: Buffer): void => {
+    const [connectHost, connectPortRaw] = urlStr.split(':');
+    const connectPort = Number(connectPortRaw || 443);
+    const twin = connectHost ? proxyTargetFor(connectHost, currentEnv()) : null;
+    const tunnel = (destPort: number, destHost: string): void => {
+      const upstream = netConnect(destPort, destHost, () => {
+        clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        if (head && head.length) upstream.write(head);
+        upstream.pipe(clientSocket);
+        clientSocket.pipe(upstream);
+      });
+      openSockets.add(upstream);
+      upstream.on('close', () => openSockets.delete(upstream));
+      upstream.on('error', () => clientSocket.destroy());
+    };
+    // MITM vendor hosts → tunnel to the per-host listening https server (terminates TLS, forwards to
+    // the twin). Non-vendor hosts → blind-tunnel to the REAL origin, untouched.
+    if (twin && connectHost) {
+      ensureHostServer(connectHost)
+        .then((port) => tunnel(port, '127.0.0.1'))
+        .catch(() => clientSocket.destroy());
+    } else if (connectHost && shouldBlockUntwinned(connectHost, currentEnv())) {
+      clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\nblocked untwinned external request\r\n');
+      clientSocket.destroy();
+    } else {
+      tunnel(connectPort, connectHost!);
+    }
+  };
+
+  await new Promise<void>((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, host, () => resolveListen());
+  });
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : (options.port ?? 0);
+  const url = `http://${host}:${port}`;
+
+  return {
+    port,
+    host,
+    caCertPath: ca.caCert,
+    url,
+    proxyEnv: () => proxyEnvFor(url, ca.caCert),
+    close: () =>
+      new Promise<void>((resolveClose) => {
+        // Forcibly drop any in-flight tunnels/keep-alive sockets so close() can't hang on a blind
+        // tunnel to a slow/real upstream.
+        for (const s of openSockets) { try { s.destroy(); } catch { /* ignore */ } }
+        openSockets.clear();
+        for (const hostServer of tlsServers.values()) {
+          try { (hostServer as unknown as { closeAllConnections?: () => void }).closeAllConnections?.(); } catch { /* ignore */ }
+          try { hostServer.close(); } catch { /* ignore */ }
+        }
+        server.close(() => resolveClose());
+      }),
+  };
+}
+
+/** The cert-trust + proxy env that points an unmodified tool through the proxy and trusts the session
+ * CA — and ONLY this session (these are per-shell exports; nothing is installed system-wide). Mirrors
+ * the env list in WORLD_ACTIVATE.md §"The honest cost: a scoped CA". */
+export function proxyEnvFor(proxyUrl: string, caCertPath: string): Record<string, string> {
+  return {
+    HTTPS_PROXY: proxyUrl,
+    HTTP_PROXY: proxyUrl,
+    https_proxy: proxyUrl,
+    http_proxy: proxyUrl,
+    NODE_EXTRA_CA_CERTS: caCertPath,
+    AWS_CA_BUNDLE: caCertPath,
+    CURL_CA_BUNDLE: caCertPath,
+    REQUESTS_CA_BUNDLE: caCertPath,
+    SSL_CERT_FILE: caCertPath,
+    VOLTER_WORLD_PROXY: proxyUrl,
+    VOLTER_WORLD_CA: caCertPath,
+  };
+}