@volter/world-runtime 2.0.0

package/src/redirect-proxy.ts

@@ -0,0 +1,684 @@
+import { serveHttp, type HttpServer } from '@volter/world-core';
+import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
+import { websocketRelay } from './websocket-relay.ts';
+// 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/world-core/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 a host the World refuses is
+//     terminated the same way and answered 502 with the reason (outsideWorld). 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 { createHash } from 'node:crypto';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { BlockList, Socket, isIP, connect as netConnect, createServer as createNetServer } from 'node:net';
+import { networkInterfaces } from 'node:os';
+import { connect as tlsConnect } from 'node:tls';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// The host→twin table is loaded through the shared inject-map module (one world-runtime home
+// for the injector's data), so this proxy, `covers`, and `up`'s inert-injectEnv warning can
+// never re-encode the vendor host predicates — they stay one source of truth with the Node
+// injector. External callers go through `proxyTargetFor`/`activeVendorMap`.
+import { loadInject } from './inject-map.ts';
+import { sessionTrustEnv, type CaTrustInputs } from './ca-trust.ts';
+
+/**
+ * The body served when a host was MITM'd but no twin serves the PATH.
+ *
+ * Two deliberate choices, both §9 round 2 findings:
+ *  • The request path is JSON-escaped and the response is sent as `text/plain`. `req.url` may
+ *    legally carry `<` and `>`, and an untyped body is MIME-sniffable — so on a machine that has
+ *    trusted the session CA, a crafted URL could otherwise execute in the vendor's origin. The
+ *    sibling raw-socket error path already set `text/plain`; this matches it.
+ *  • It names the SITUATION, not just the miss (the Cal.com finding): this handler only runs after
+ *    the host was MITM'd, i.e. the host IS twinned in this world — so the bare "no twin for host"
+ *    sent readers hunting for a `*_TWIN_URL` that was already set. On a shared host the path may
+ *    belong to a vendor whose twin merely is not configured (youtube vs googleauth), OR to no pack
+ *    at all (Google Calendar on www.googleapis.com has no twin yet) — the message states both,
+ *    because this refusal is exactly what replaced the silent mis-route that answered Calendar
+ *    calls with plausible Google-shaped 404s from the gemini pack.
+ */
+export function noTwinMessage(host: string, path: string): string {
+  return `host ${host} is twinned in this world, but path ${JSON.stringify(path)} belongs to no twin configured here.\n`
+    + 'This host is shared between vendors, and no pack in this world serves this path. Either the\n'
+    + 'vendor that owns this path has a twin that is not configured — set its *_TWIN_URL (for\n'
+    + 'www.googleapis.com: YOUTUBE_TWIN_URL serves /youtube/v3/*, GOOGLEAUTH_TWIN_URL serves the\n'
+    + 'OAuth2 token paths) — or this API has no twin pack yet (e.g. Google Calendar /calendar/v3/*),\n'
+    + 'in which case this loud refusal is the honest outcome: the request is neither answered by the\n'
+    + 'wrong twin nor leaked to the real vendor.\n';
+}
+
+/** 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.
+ *
+ * `pathname` is optional and matters only for hosts TWO vendors share (see `VENDOR_HOSTS` in
+ * inject.cjs — `www.googleapis.com` is served by both `googleauth` and `youtube`, split by path).
+ * At CONNECT time there is no path yet, so it is omitted and the answer is host-level candidacy:
+ * "MITM this host". Once TLS is terminated and the real request line is readable, the caller
+ * re-resolves WITH the path so each request reaches the twin that actually serves it. */
+export function proxyTargetFor(
+  hostname: string,
+  env: Record<string, string | undefined>,
+  pathname?: string,
+): { vendor: string; origin: string } | null {
+  const inject = loadInject();
+  return inject.resolveTwin(hostname, inject.readMap(env), pathname);
+}
+
+/** 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 (isIP(h) !== 4) return false;
+  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;
+}
+
+/** A connection from anything but the proxy host's own loopback is a guest's (a World Machine: its forwarder connects
+ *  from 127.0.0.2 on this host, or from its VM's address): architecture, "The scoped proxy's local pass-through". */
+export function isGuestSource(address: string | undefined): boolean {
+  const a = String(address ?? '').replace(/^::ffff:/i, '');
+  return a !== '127.0.0.1' && a !== '::1';
+}
+
+// What a guest may not be connected to: the host's own networks. IPv4: this network, private, CGNAT, loopback, link-local,
+// IETF protocol, benchmarking, multicast and reserved (broadcast included). IPv6: unspecified, loopback, IPv4-compatible,
+// unique-local, link-local, multicast, NAT64 and 6to4 (both carry an IPv4 address a translator reaches).
+const GUEST_V4_BLOCKED = new BlockList();
+for (const [net, bits] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['224.0.0.0', 4], ['240.0.0.0', 4]] as const) GUEST_V4_BLOCKED.addSubnet(net, bits, 'ipv4');
+const GUEST_V6_BLOCKED = new BlockList();
+for (const [net, bits] of [['::', 128], ['::1', 128], ['::', 96], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8], ['64:ff9b::', 96], ['64:ff9b:1::', 48], ['2002::', 16]] as const) GUEST_V6_BLOCKED.addSubnet(net, bits, 'ipv6');
+
+/** An IPv6 address's 16 bytes (any spelling: `::`, a dotted IPv4 tail), or null. */
+function ipv6Bytes(a: string): number[] | null {
+  let text = a.replace(/%.*$/, '');
+  const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (dotted) {
+    const q = dotted[1]!.split('.').map(Number);
+    text = `${text.slice(0, -dotted[1]!.length)}${((q[0]! << 8) | q[1]!).toString(16)}:${((q[2]! << 8) | q[3]!).toString(16)}`;
+  }
+  const halves = text.split('::');
+  if (halves.length > 2) return null;
+  const words = (h: string) => (h ? h.split(':') : []);
+  const head = words(halves[0]!); const tail = halves.length === 2 ? words(halves[1]!) : [];
+  const fill = 8 - head.length - tail.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const all = [...head, ...Array(fill).fill('0'), ...tail].map((w) => parseInt(w, 16));
+  if (all.some((w) => !Number.isInteger(w) || w < 0 || w > 0xffff)) return null;
+  return all.flatMap((w) => [w >> 8, w & 0xff]);
+}
+
+/** An address a guest may not be connected to: one of the host's networks (above), or an address of the host's own
+ *  interfaces; an IPv4 address mapped into IPv6 (in any spelling) is checked as IPv4. */
+export function isGuestForbiddenAddress(ip: string): boolean {
+  let a = ip.toLowerCase().replace(/^\[|\]$/g, '');
+  if (isIP(a) === 6) {
+    const b = ipv6Bytes(a);
+    if (!b) return true;
+    if (b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff) a = b.slice(12).join('.');
+  }
+  const own = Object.values(networkInterfaces()).flat().some((i) => i && i.address.toLowerCase() === a);
+  if (own) return true;
+  if (isIP(a) === 4) return GUEST_V4_BLOCKED.check(a, 'ipv4');
+  if (isIP(a) === 6) return GUEST_V6_BLOCKED.check(a, 'ipv6');
+  return true;
+}
+
+/** Where a guest may be connected for `host`: the address checked (a literal, or what the name resolves to, every
+ *  answer checked), or the refusal. The caller connects to that address, so a second resolution cannot move it. */
+export async function guestDestination(host: string): Promise<{ address: string } | { refused: string }> {
+  const h = host.replace(/^\[|\]$/g, '');
+  let addresses: string[];
+  try { addresses = isIP(h) ? [h] : (await dnsLookup(h, { all: true })).map((r) => r.address); } catch (error) {
+    return { refused: `${host} does not resolve (${(error as Error).message})` };
+  }
+  const bad = addresses.find(isGuestForbiddenAddress);
+  if (bad || !addresses.length) return { refused: `${host} is on the machine's host network (${bad ?? 'no address'}), which a World Machine cannot reach` };
+  return { address: addresses[0]! };
+}
+
+function shouldBlockUntwinned(value: URL | string, env: Record<string, string | undefined>): boolean {
+  let url: URL;
+  try { url = value instanceof URL ? value : new URL(value); } catch { return true; }
+  const policy = worldNetworkPolicyFromEnv(env);
+  if (isLocalOrPrivateHost(url.hostname) || proxyTargetFor(url.hostname, env)) return false;
+  return strictEgressEnabled(env) || (policy !== undefined && !allowsWorldNetworkEgress(policy, url));
+}
+
+// --- 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',
+    // A CA cert without keyUsage is refused by OpenSSL 3 (Python, curl on Debian 13: "CA cert does not
+    // include key usage extension"), so the CA states what a CA is for.
+    '-addext', 'basicConstraints=critical,CA:TRUE',
+    '-addext', 'keyUsage=critical,keyCertSign,cRLSign',
+    '-addext', 'subjectKeyIdentifier=hash',
+  ]);
+  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 } {
+  // A pathname can hold a replacement CA; its certificate identifies the signing generation.
+  const cacheKey = `${createHash('sha256').update(readFileSync(ca.caCert)).digest('hex')}:${host}`;
+  const cached = leafCache.get(cacheKey);
+  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(cacheKey, 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>;
+  /** Keep caller trust separate from persisted World trust so neither overwrites the other. */
+  trustEnv?: CaTrustInputs;
+  /** 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;
+  /** Where each refusal and each failed twin request is written (the detached daemon's log), so an app that swallows
+   *  a 502 still leaves the World a record of it. */
+  note?: (line: string) => void;
+  /** 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;
+  /** Its guests' listener (a World Machine's forwarder targets it): every connection there gets the guest rule. */
+  guestUrl: string;
+  /** The cert-trust + proxy env an activate/shell session exports to route through this proxy. */
+  proxyEnv(): Record<string, string>;
+  close(): Promise<void>;
+};
+
+/** A failed twin request's answer: the twin, its origin, the World and the cause, so the app's error says which service
+ *  of which World to look at (`doctor`). Shared by every front that relays to twins. */
+export function twinUnreachableMessage(vendor: string, origin: string, err: Error, world?: string): string {
+  const cause = (err as { cause?: { code?: string; message?: string } }).cause;
+  return `twin "${vendor}" at ${origin} is unreachable${world ? ` in World "${world}"` : ''}: ${err.message}${cause?.code ? ` (${cause.code})` : cause?.message ? ` (${cause.message})` : ''}; check \`volter-world doctor${world ? ` ${world}` : ''}\`\n`;
+}
+
+/** 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> => {
+    const env = options.envLoader?.() ?? options.env ?? {};
+    worldNetworkPolicyFromEnv(env);
+    return env;
+  };
+  currentEnv(); // Invalid authority must fail before the proxy reports readiness.
+  const note = (line: string): string => { try { options.note?.(`${new Date().toISOString()} ${line.trimEnd()}`); } catch { /* the answer still goes out */ } return line; };
+  const twinUnreachable = (vendor: string, origin: string, err: Error): string => {
+    let world: string | undefined;
+    try { world = currentEnv().VOLTER_WORLD; } catch { /* an unreadable env must not crash the proxy on its error path */ }
+    return note(twinUnreachableMessage(vendor, origin, err, world));
+  };
+  const ca = ensureCa(options.tlsDir);
+  const trust = sessionTrustEnv(ca.caCert, options.trustEnv ?? options.envLoader?.() ?? options.env ?? process.env);
+  // 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 TLS server PER vendor host (loopback, ephemeral port), each pinned
+  // to that host's leaf 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. (One server per host
+  // rather than SNI: hosts are few and known from the world's vendor map.)
+  // The portable host uses native upgrades on each runtime, so a websocket on a twinned host —
+  // discord.py's gateway at wss://gateway.discord.gg/ — must reach the twin. HTTP is forwarded with fetch; a
+  // websocket is relayed message by message to the twin's own websocket at the same path.
+  const tlsServers = new Map<string, HttpServer>();
+  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 = await serveHttp({
+      hostname: '127.0.0.1',
+      port: 0,
+      tls: { key: leaf.key, cert: leaf.cert },
+      // A twin can think before its first byte (a git pack built from a cold cache took 19-28 s); Bun's 10 s idle
+      // default cut those connections and the client read an empty reply. Bun's maximum, as reflect.ts serves.
+      idleTimeout: 255,
+      async fetch(req) {
+        const u = new URL(req.url);
+        const hostHeader = (req.headers.get('host') ?? vendorHost).split(':')[0] ?? vendorHost;
+        const env = currentEnv();
+        // The request line is readable now, so resolve WITH the path: this is the point where a host two vendors
+        // share (www.googleapis.com → googleauth vs youtube) gets split correctly; on a shared host there IS a twin
+        // for the host and merely not for this path, and the bare message sends the next reader hunting.
+        const twin = proxyTargetFor(hostHeader, env, u.pathname) ?? proxyTargetFor(vendorHost, env, u.pathname);
+        if (!twin) {
+          // a host the World refuses (sealed, or outside its network policy): answered here, over the World's TLS, so
+          // a person's browser shows where it was sent and why nothing is there, not an empty tunnel error; nothing
+          // leaves the World
+          if (shouldBlockUntwinned(`https://${hostHeader}`, env)) return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'));
+          const unreachable = unreachableHosts.get(hostHeader.toLowerCase());
+          if (unreachable) return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), unreachable);
+          return new Response(note(noTwinMessage(hostHeader, u.pathname)), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+        }
+        const origin = new URL(twin.origin);
+
+        const headers = new Headers(req.headers);
+        for (const h of ['proxy-connection', 'accept-encoding', 'connection']) headers.delete(h);
+        // the application is not a twin: it gets no World key, keeps its Host and hears it was reached over TLS
+        if (twin.vendor === 'app') {
+          headers.delete('x-twins-key');
+          for (const [k, v] of Object.entries(loadInject().appForwardHeaders(new URL(`https://${req.headers.get('host') ?? vendorHost}`)))) headers.set(k, v);
+        } else if (env.VOLTER_TWINS_KEY) headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+        // Hosted namespaces need their transport Host; direct twins can use
+        // the original Host for vendor semantics (for example S3 buckets).
+        if (origin.pathname.replace(/\/$/, '') && twin.vendor !== 'app') {
+          headers.set('x-volter-twin-original-host', hostHeader);
+          headers.set('host', origin.host);
+        }
+        const target = new URL(origin);
+        target.pathname = `${origin.pathname.replace(/\/$/, '')}${u.pathname}`;
+        target.search = u.search;
+        try {
+          const upRes = await fetch(target, { method: req.method, headers, body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req.body, ...(req.body ? { duplex: 'half' as const } : {}), redirect: 'manual' });
+          const out = new Headers(upRes.headers);
+          for (const h of ['content-encoding', 'content-length', 'transfer-encoding', 'connection', 'keep-alive']) out.delete(h);
+          return new Response(upRes.body, { status: upRes.status, headers: out });
+        } catch (err) {
+          return new Response(twinUnreachable(twin.vendor, origin.origin, err as Error), { status: 502 });
+        }
+      },
+      upgrade: websocketRelay(req => {
+        const url = new URL(req.url);
+        const host = (req.headers.get('host') ?? vendorHost).split(':')[0]!;
+        const twin = proxyTargetFor(host, currentEnv(), url.pathname) ?? proxyTargetFor(vendorHost, currentEnv(), url.pathname);
+        if (!twin) return undefined;
+        const origin = new URL(twin.origin);
+        return `${origin.protocol === 'https:' ? 'wss' : 'ws'}://${origin.host}${origin.pathname.replace(/\/$/, '')}${url.pathname}${url.search}`;
+      }),
+    });
+    const p = hostServer.port ?? 0;
+    tlsServers.set(vendorHost, hostServer);
+    tlsPorts.set(vendorHost, p);
+    return p;
+  };
+
+  // two listeners with one handler: the World's (host clients; a connection from elsewhere is still a guest's) and its
+  // guests' (a World Machine's forwarder targets it: every connection a guest's, whatever NAT makes its source look like)
+  const accept = (guestListener: boolean) => (clientSocket: Socket) => {
+    const guest = guestListener || isGuestSource(clientSocket.remoteAddress);
+    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') {
+        try { handleConnect(urlStr, clientSocket, head, guest); }
+        catch { writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('World network policy unavailable\n')); }
+        return;
+      }
+
+      handlePlainProxyRequest(method, urlStr, version, headers, clientSocket, head, guest);
+    };
+    clientSocket.on('data', onData);
+  };
+  const server = createNetServer(accept(false));
+  const guestServer = createNetServer(accept(true));
+
+  /** A refused host's answer: 502, naming the host and why, as a page a person reads in a browser (the address bar
+   *  keeps where the request was sent) or as text for any other client. */
+  const outsideWorld = (host: string, path: string, accept: string | null, unreachable?: string): Response => {
+    // the CONNECT that reached this server was noted when it was refused
+    const why = unreachable
+      ? `no twin serves it, and it did not answer from this World (${unreachable}).`
+      : 'no twin serves it, and the World does not reach the internet for it.';
+    const text = `${host} is outside this World: ${why}\n`;
+    // connection: close, so a reload opens a new CONNECT, which reaches the origin once it answers (a kept-alive tunnel
+    // would keep answering this page)
+    if (!(accept ?? '').includes('text/html')) return new Response(text, { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', connection: 'close' } });
+    const esc = (v: string) => v.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+    const page = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(host)} is outside this World</title>`
+      + '<style>body{font:15px system-ui,sans-serif;max-width:620px;margin:12vh auto;padding:0 16px;color:#222}code{background:#f2f2f2;padding:1px 4px;border-radius:4px}</style></head><body>'
+      + `<h1>${esc(host)} is outside this World</h1><p>You were sent to <code>https://${esc(host)}${esc(path)}</code>. ${esc(why.charAt(0).toUpperCase() + why.slice(1))} There is nothing to show here.</p></body></html>`;
+    return new Response(page, { status: 502, headers: { 'content-type': 'text/html; charset=utf-8', connection: 'close' } });
+  };
+
+  // the refused hosts answered with a page, each holding a leaf and a listener until the proxy closes: bounded
+  const REFUSED_PAGES_MAX = 64;
+  const refusedPages = new Set<string>();
+  // the names on 443 a tunnel could not reach, with why, answered by their host server's page
+  const unreachableHosts = new Map<string, string>();
+  const isDnsName = (host: string): boolean => /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/i.test(host);
+
+  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,
+    vendor?: string,
+    address?: string,
+  ): void => {
+    // where to connect: the address a guest's check passed, else the origin's host (an IPv6 one unbracketed)
+    const connectHost = address ?? origin.hostname.replace(/^\[|\]$/g, '');
+    const connected = () => {
+      const outHeaders = { ...headers };
+      if (origin.pathname.replace(/\/$/, '')) {
+        outHeaders['x-volter-twin-original-host'] = headers.host ?? origin.host;
+        outHeaders.host = origin.host;
+      }
+      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);
+    };
+    const upstream = origin.protocol === 'https:'
+      ? tlsConnect({ host: connectHost, port: Number(origin.port || 443), ...(isIP(origin.hostname.replace(/^\[|\]$/g, '')) ? {} : { servername: origin.hostname }), ca: readFileSync(trust.SSL_CERT_FILE!) }, connected)
+      : netConnect(Number(origin.port || 80), connectHost, connected);
+    openSockets.add(upstream);
+    upstream.on('close', () => openSockets.delete(upstream));
+    upstream.on('error', (err: Error) => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', vendor ? twinUnreachable(vendor, origin.origin, err) : note(`upstream ${origin.host} unreachable: ${err.message}\n`)));
+  };
+
+  const handlePlainProxyRequest = (
+    method: string,
+    urlStr: string,
+    version: string,
+    headers: Record<string, string>,
+    socket: Socket,
+    head: Buffer,
+    guest: boolean,
+  ): void => {
+    try {
+      const u = new URL(urlStr);
+      const twin = proxyTargetFor(u.hostname, currentEnv(), u.pathname);
+      const path = u.pathname + u.search;
+      if (twin) {
+        const target = new URL(twin.origin);
+        const key = twin.vendor === 'app' ? undefined : currentEnv().VOLTER_TWINS_KEY;
+        const app = twin.vendor === 'app' ? loadInject().appForwardHeaders(u) : {};
+        forwardRawHttp(target, method, `${target.pathname.replace(/\/$/, '')}${path}`, version, { ...headers, ...app, ...(key ? { 'x-twins-key': key } : {}) }, socket, head, twin.vendor);
+        return;
+      }
+      // No twin claims this PATH — but if the HOST is twinned (host-level candidacy), the path is
+      // an unclaimed slice of a shared, virtualized host: refuse loudly (same rule as the MITM
+      // handler's noTwinMessage), never pass through to the real vendor.
+      if (proxyTargetFor(u.hostname, currentEnv())) {
+        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)));
+        return;
+      }
+      if (shouldBlockUntwinned(u, currentEnv())) {
+        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`));
+        return;
+      }
+      // Non-vendor: plain pass-through to the real host; for a World Machine, only off its host's own network, and to
+      // the address checked (architecture, "The scoped proxy's local pass-through")
+      if (guest) {
+        void guestDestination(u.hostname).then((d) => {
+          if ('refused' in d) { writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`${d.refused}\n`)); return; }
+          // to the address checked (TLS still names the host: SNI and the certificate)
+          forwardRawHttp(new URL(`${u.protocol}//${u.host}`), method, path, version, headers, socket, head, undefined, d.address);
+        }).catch(() => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', 'bad gateway\n')); // (a throw must not end the proxy)
+        return;
+      }
+      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, guest: boolean): void => {
+    const [connectHostRaw, connectPortRaw] = urlStr.split(':');
+    const connectHost = connectHostRaw?.toLowerCase(); // hostnames are case-insensitive; the host rules are lowercase
+    const connectPort = Number(connectPortRaw || 443);
+    const twin = connectHost ? proxyTargetFor(connectHost, currentEnv()) : null;
+    const tunnel = (destPort: number, destHost: string, unreachable?: (reason: string) => boolean): void => {
+      let connected = false;
+      const upstream = netConnect(destPort, destHost, () => {
+        connected = true;
+        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));
+      // a destination that cannot be reached at all (a name that does not resolve, a refused port) is answered by the
+      // caller's fallback when it has one, before the tunnel was ever established; otherwise the client's socket ends
+      upstream.on('error', (error: NodeJS.ErrnoException) => {
+        if (!connected && unreachable && unreachable(error.code ?? error.message)) return;
+        clientSocket.destroy();
+      });
+    };
+    /** A page for a DNS name on 443 that cannot be reached, as for a refused one (within REFUSED_PAGES_MAX). */
+    const unreachablePage = (reason: string): boolean => {
+      if (!(connectHost && connectPort === 443 && isDnsName(connectHost) && (refusedPages.has(connectHost) || refusedPages.size < REFUSED_PAGES_MAX))) return false;
+      note(`${connectHost}:${connectPort} did not answer (${reason})`);
+      refusedPages.add(connectHost);
+      unreachableHosts.set(connectHost, reason);
+      ensureHostServer(connectHost).then((port) => tunnel(port, '127.0.0.1')).catch(() => clientSocket.destroy());
+      return true;
+    };
+    // 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(`https://${connectHost}:${connectPort}`, currentEnv())) {
+      note(`blocked untwinned external request to ${connectHost}:${connectPort}`);
+      // a browser's https to a DNS name: terminated with the World's TLS and answered by the host server's page
+      // (outsideWorld), so the person sees where they were sent. Anything else (another port or protocol, an address,
+      // a name past the first REFUSED_PAGES_MAX, each of which costs a leaf and a listener) is refused on the tunnel
+      // line, as before
+      if (connectPort === 443 && isDnsName(connectHost) && (refusedPages.has(connectHost) || refusedPages.size < REFUSED_PAGES_MAX)) {
+        refusedPages.add(connectHost);
+        ensureHostServer(connectHost)
+          .then((port) => tunnel(port, '127.0.0.1'))
+          .catch(() => clientSocket.destroy());
+      } else {
+        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 if (guest) {
+      // a World Machine: never its host's own network (architecture, "The scoped proxy's local pass-through")
+      void guestDestination(connectHost!).then((d) => {
+        if ('refused' in d) {
+          note(`refused a machine's tunnel to ${connectHost}:${connectPort}: ${d.refused}`);
+          clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\n${d.refused}\r\n`);
+          clientSocket.destroy();
+        } else tunnel(connectPort, d.address);
+      }).catch(() => clientSocket.destroy()); // (outside the handler's own try: a throw here must not end the proxy)
+    } else {
+      tunnel(connectPort, connectHost!, unreachablePage);
+    }
+  };
+
+  await new Promise<void>((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, host, () => resolveListen());
+  });
+  await new Promise<void>((resolveListen, reject) => {
+    guestServer.once('error', reject);
+    guestServer.listen(0, host, () => resolveListen());
+  });
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : (options.port ?? 0);
+  const url = `http://${host}:${port}`;
+  const guestAddr = guestServer.address();
+  const guestUrl = `http://${host}:${typeof guestAddr === 'object' && guestAddr ? guestAddr.port : 0}`;
+
+  return {
+    port,
+    host,
+    caCertPath: ca.caCert,
+    url,
+    guestUrl,
+    proxyEnv: () => ({ ...proxyAddressEnv(url, ca.caCert, guestUrl), ...trust }),
+    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.stop(true); } catch { /* ignore */ } }
+        guestServer.close();
+        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, caller: CaTrustInputs = process.env, guestUrl?: string): Record<string, string> {
+  return { ...proxyAddressEnv(proxyUrl, caCertPath, guestUrl), ...sessionTrustEnv(caCertPath, caller) };
+}
+
+/** The proxy's address env; `VOLTER_WORLD_GUEST_PROXY` is its guests' listener, which a World Machine's forwarder
+ *  targets (architecture, "The scoped proxy's local pass-through"). */
+function proxyAddressEnv(proxyUrl: string, caCertPath: string, guestUrl?: string): Record<string, string> {
+  return {
+    ...(guestUrl ? { VOLTER_WORLD_GUEST_PROXY: guestUrl } : {}),
+    HTTPS_PROXY: proxyUrl,
+    HTTP_PROXY: proxyUrl,
+    https_proxy: proxyUrl,
+    http_proxy: proxyUrl,
+    VOLTER_WORLD_PROXY: proxyUrl,
+    VOLTER_WORLD_CA: caCertPath,
+  };
+}