@volter/world-core 2.0.0

package/inject.cjs

@@ -0,0 +1,1097 @@
+'use strict';
+// @volter/world-core/inject — zero-edit backend injection.
+//
+// Redirect a process's calls to real vendor hosts (api.stripe.com, slack.com,
+// api.github.com, *.atlassian.net, api.linear.app, S3 endpoints, and other
+// configured vendor API hosts) to local twins, WITHOUT
+// changing the app: the app constructs its SDK exactly as in production.
+//
+//   node --require @volter/world-core/inject app.js
+//   NODE_OPTIONS="--require @volter/world-core/inject" <your start command>
+//
+//   <VENDOR>_TWIN_URL for every pack in the catalog (uppercase vendor id, non-alnum → _),
+//   e.g. STRIPE_TWIN_URL=http://127.0.0.1:12111 or a hosted skin URL
+//   {twinsUrl}/{org}/{world}/{vendor} with VOLTER_TWINS_KEY set (R7c). Host claims come
+//   from pack-facts at runtime — this file carries no per-vendor roster to rot.
+//   AWS service-areas (DYNAMODB/TIMESTREAM/SESV2/SECRETSMANAGER/BEDROCK_TWIN_URL) point at
+//   the consolidated `aws` twin, same as S3_TWIN_URL.
+//   …or combined: TWIN_INJECT="stripe=http://127.0.0.1:12111,github=http://127.0.0.1:12120"
+//
+// It patches http/https `request`/`get` and global `fetch` at the process
+// boundary. Every Node vendor SDK in this set routes through one of those
+// (stripe-node → https; @octokit → fetch; @slack/web-api & jira.js → axios →
+// http/https; @linear/sdk → fetch), so no per-SDK shim is needed.
+//
+// A client can still open its own sockets (npm `undici`'s Agent, which
+// @turbopuffer/turbopuffer uses under Node, honours neither patch nor HTTPS_PROXY).
+// `net.connect`/`tls.connect` are the seam every Node client ends at, so they carry
+// the backstop: a connect to a twinned vendor host went around the rewrite and is
+// refused, never sent to the real vendor; a connect to an untwinned host is refused
+// wherever strict egress or the World's network policy refuses it. The refusal
+// names the pack's endpoint env, the SDK's own door to the twin, when it has one.
+const http = require('http');
+const https = require('https');
+const net = require('net');
+const tls = require('tls');
+const { isIP } = require('node:net');
+const { EventEmitter } = require('events');
+const { Readable } = require('stream');
+const Module = require('module');
+const { worldNetworkPolicyFromEnv, isWorldInternalHost, worldEgressRefusal } = require('./network-policy.cjs');
+const { createPublicKey, createVerify } = require('crypto');
+
+// the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
+// serves it) has its own home, shared with the application route
+const { VENDOR_HOSTS, isVendorHost } = require('./vendor-hosts.cjs');
+const dns = require('dns');
+
+function decodeBase64UrlJson(part) {
+  try {
+    const padded = String(part).replace(/-/g, '+').replace(/_/g, '/');
+    const json = Buffer.from(padded + '='.repeat((4 - (padded.length % 4)) % 4), 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+function decodeBase64Url(part) {
+  const padded = String(part || '').replace(/-/g, '+').replace(/_/g, '/');
+  return Buffer.from(padded + '='.repeat((4 - (padded.length % 4)) % 4), 'base64');
+}
+
+function verifyJwtWithCachedJwks(token, jwks) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3 || !jwks || !Array.isArray(jwks.keys)) return null;
+  const header = decodeBase64UrlJson(parts[0]);
+  const payload = decodeBase64UrlJson(parts[1]);
+  if (!header || !payload || header.alg !== 'RS256') return null;
+  const key = jwks.keys.find((candidate) => candidate && candidate.kid === header.kid) || jwks.keys[0];
+  if (!key) return null;
+  try {
+    const verifier = createVerify('RSA-SHA256');
+    verifier.update(`${parts[0]}.${parts[1]}`);
+    verifier.end();
+    const publicKey = createPublicKey({ key: { kty: 'RSA', n: key.n, e: key.e }, format: 'jwk' });
+    if (!verifier.verify(publicKey, decodeBase64Url(parts[2]))) return null;
+  } catch {
+    return null;
+  }
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === 'number' && now >= payload.exp) return null;
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return null;
+  const issuer = String(payload.iss || '');
+  const isTwinIssuer = issuer.includes('twin.clerk') || issuer.includes('clerk.twin') || issuer.includes('accounts.dev');
+  return isTwinIssuer ? payload : null;
+}
+
+function installClerkFastifyTwinShim() {
+  if (!process.env.CLERK_TWIN_URL || Module.__volterClerkFastifyShimInstalled) return;
+  Module.__volterClerkFastifyShimInstalled = true;
+  let cachedJwks = null;
+  const originalLoad = Module._load;
+  Module._load = function volterTwinLoad(request, parent, isMain) {
+    if (request === '@clerk/fastify') {
+      return {
+        clerkPlugin: async function clerkPlugin() {
+          const baseUrl = String(process.env.CLERK_TWIN_URL || '').replace(/\/$/, '');
+          if (!baseUrl) return;
+          const response = await fetch(`${baseUrl}/.well-known/jwks.json`);
+          if (!response.ok) throw new Error(`Clerk twin JWKS fetch failed: ${response.status}`);
+          cachedJwks = await response.json();
+        },
+        getAuth: function getAuth(req) {
+          const auth = req && (req.headers?.authorization || req.headers?.Authorization);
+          const token = typeof auth === 'string' && auth.startsWith('Bearer ') ? auth.slice('Bearer '.length) : '';
+          const payload = token ? verifyJwtWithCachedJwks(token, cachedJwks) : null;
+          return {
+            userId: typeof payload?.sub === 'string' ? payload.sub : null,
+            sessionId: typeof payload?.sid === 'string' ? payload.sid : null,
+            orgId: typeof payload?.org_id === 'string' ? payload.org_id : null,
+          };
+        },
+      };
+    }
+    return originalLoad.apply(this, arguments);
+  };
+}
+
+installClerkFastifyTwinShim();
+
+// Prisma over a twinned database. Prisma's client-engine build — the build a tab runs, and
+// the one its edge client uses — refuses to construct without a driver adapter, and an
+// application written against Prisma's library engine names none (`new PrismaClient()`).
+// When the attached World twins a database vendor whose pack declares `prismaAdapter`
+// (DATA on the descriptor, compiled into pack-facts), a client constructed without an
+// adapter gets that vendor's HTTP adapter from the APPLICATION'S OWN dependencies,
+// resolved from the requiring module, over the URL the endpoint template rendered into
+// the vendor's `urlEnv`. An application that already passes an adapter, or does not
+// install the adapter package, is left exactly as it was. The vendor is chosen by the
+// twin that is attached AND whose URL variable is set; the first such pack wins.
+function installPrismaAdapterShim() {
+  if (Module.__volterPrismaAdapterShimInstalled) return;
+  const { packs } = require('./generated/pack-facts.json');
+  const candidates = Object.keys(packs).filter((vendor) => packs[vendor].prismaAdapter).sort();
+  if (candidates.length === 0) return;
+  Module.__volterPrismaAdapterShimInstalled = true;
+  const path = require('path');
+  const originalLoad = Module._load;
+  Module._load = function volterPrismaLoad(request, parent, isMain) {
+    const exports = originalLoad.apply(this, arguments);
+    if (request !== '@prisma/client' || !exports || typeof exports.PrismaClient !== 'function' || exports.PrismaClient.__volterAdapted) return exports;
+    const vendor = candidates.find((candidate) => MAP[candidate] && process.env[packs[candidate].prismaAdapter.urlEnv]);
+    if (!vendor) return exports;
+    const facts = packs[vendor].prismaAdapter;
+    // From the requiring module first (a library that constructs the client), then the
+    // application itself, whose dependency the adapter is under pnpm's isolated layout.
+    const from = parent && parent.filename ? path.dirname(parent.filename) : process.cwd();
+    let adapterModule;
+    try {
+      adapterModule = originalLoad.call(this, require.resolve(facts.adapter, { paths: [from, process.cwd()] }), parent, false);
+    } catch {
+      // Left as it was, said once: on the client engine Prisma refuses the construction itself;
+      // on the library engine the client reaches the twin over the vendor's own wire.
+      process.stderr.write(`[twin-inject] ${vendor}: ${facts.adapter} is not installed in this application, so a Prisma client constructed without an adapter is left as it was\n`);
+      exports.PrismaClient.__volterAdapted = true;
+      return exports;
+    }
+    const Adapter = adapterModule && adapterModule[facts.export];
+    if (typeof Adapter !== 'function') {
+      process.stderr.write(`[twin-inject] ${vendor}: ${facts.adapter} exports no ${facts.export}; a Prisma client constructed without an adapter is left as it was\n`);
+      exports.PrismaClient.__volterAdapted = true;
+      return exports;
+    }
+    const Base = exports.PrismaClient;
+    class PrismaClient extends Base {
+      constructor(options) {
+        const given = options || {};
+        // An adapter the application passes, or `null`, Prisma's own explicit opt-out, is its
+        // decision. The URL is the application's where it names one (its host is twinned by the
+        // injector's own host rules), else the endpoint template's variable.
+        if ('adapter' in given) { super(given); return; }
+        const named = given.datasources && typeof given.datasources === 'object'
+          ? Object.values(given.datasources).map((source) => source && source.url).find((value) => typeof value === 'string') : undefined;
+        const url = given.datasourceUrl || named || process.env[facts.urlEnv];
+        super({ ...given, adapter: new Adapter({ url, fetch: (...args) => globalThis.fetch(...args) }) });
+      }
+    }
+    PrismaClient.__volterAdapted = true;
+    exports.PrismaClient = PrismaClient;
+    return exports;
+  };
+}
+
+// The exact inverse of readMap's env lookup: which vendor (if any) would the injector read
+// this env var for? `S3_TWIN_URL` → 's3'; `AWS_TWIN_URL` → null (the consolidated aws twin
+// answers as s3/dynamodb/timestream/sesv2/secretsmanager/bedrock — there IS no 'aws' vendor key, which is exactly the
+// silent-inert-env trap this helper exists to make checkable). Shared with world-runtime so
+// its "this injectEnv var is inert" warning can never drift from what readMap actually reads.
+function twinEnvStem(vendor) {
+  return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
+function twinUrlVendor(name) {
+  const match = /^([A-Z][A-Z0-9_]*)_TWIN_URL$/.exec(String(name || ''));
+  if (!match) return null;
+  return Object.keys(VENDOR_HOSTS).find((vendor) => twinEnvStem(vendor) === match[1]) || null;
+}
+
+function readMap(env) {
+  const map = {};
+  // the World instance whose recorded app hosts this map routes (APP HOSTS, below); not a vendor, so not a key
+  if (env.VOLTER_WORLD_INSTANCE) Object.defineProperty(map, APP_INSTANCE, { value: env.VOLTER_WORLD_INSTANCE, enumerable: false });
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
+    if (url) map[vendor] = url.replace(/\/$/, '');
+  }
+  if (env.TWIN_INJECT) {
+    for (const pair of env.TWIN_INJECT.split(',')) {
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      const vendor = pair.slice(0, eq).trim();
+      const url = pair.slice(eq + 1).trim();
+      if (vendor && url && VENDOR_HOSTS[vendor]) map[vendor] = url.replace(/\/$/, '');
+    }
+  }
+  return map;
+}
+
+/**
+ * Which twin (if any) serves `hostname` — and, when the caller knows it, `pathname`.
+ *
+ * `pathname` is optional and backward-compatible: predicates that take one argument ignore it, so
+ * a two-argument call is identical to the old behavior for every vendor that owns its host. It
+ * matters only where two vendors SHARE a host (see the VENDOR_HOSTS header). Callers that have a
+ * URL should always pass it; callers that genuinely do not (the proxy's CONNECT handler, which
+ * sees only the SNI name) omit it and get host-level candidacy.
+ */
+function resolveTwin(hostname, map, pathname) {
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    if (map[vendor] && VENDOR_HOSTS[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
+  }
+  // then a host a running twin claims (a custom domain a person connected), as DNS would route it; never one a
+  // descriptor's hosts name, which the loop above has already answered
+  const host = String(hostname || '').toLowerCase();
+  for (const vendor of Object.keys(CLAIMERS)) {
+    if (map[vendor] && claimsAt(map[vendor], CLAIMERS[vendor]).hosts.has(host)) return { vendor, origin: map[vendor] };
+  }
+  // last, the application's own production hostnames, routed to where it listens in the World; never the World's own
+  // origin or a twin's, whose requests carry the World key
+  const app = appRoute(map[APP_INSTANCE]);
+  const bare = host.replace(/\.$/, '');
+  const base = worldBase();
+  // a name a vendor's host rule gives its twin is never the application's, whether or not that twin runs here
+  if (app && appHostMatch(app.hosts, bare) && !isVendorHost(bare) && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
+    return { vendor: 'app', origin: app.origin };
+  }
+  return null;
+}
+
+// APP HOSTS: the hostnames an application answers as in production (`volter-world app-url <world> --host`), recorded
+// beside its URL in the instance (`app-url.json`), and routed to that URL as DNS routes them to its host in production.
+// Read from the instance the World env names, at most once a second, so a host or URL recorded after the process
+// started applies. The request keeps its Host and says, as a proxy in front of it would, the host and the scheme it
+// was made with (appForwardHeaders), so an application serving several hostnames answers each as in production.
+const APP_INSTANCE = Symbol.for('volter.inject.appInstance');
+// the route itself (the record, its wildcards, the forwarded headers) has one home, shared with the twins' deliveries
+const { appRoute, appHostMatch, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
+
+// HOSTS A TWIN CLAIMS WHILE IT RUNS (packRegistry `hostsClaimed`): no descriptor can list a name a person makes answer
+// to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the
+// injector installs (or, in a process that only resolves, the proxy, from its first resolve). A fetch that would be
+// refused while a first read is still in flight waits for it; a name connected moments ago is refused until the next
+// read, as a new DNS record takes a moment.
+const CLAIMERS = {};
+{
+  const { packs } = require('./generated/pack-facts.json');
+  for (const vendor of Object.keys(packs)) if (packs[vendor].hostsClaimed) CLAIMERS[vendor] = packs[vendor].hostsClaimed.door;
+}
+const CLAIMS = new Map(); // cache: origin -> the hosts its twin last listed; refreshed by the poll below
+function claimsAt(origin, door) {
+  const held = CLAIMS.get(origin);
+  if (held) return held;
+  const entry = { hosts: new Set(), loaded: false, ready: null };
+  let settle;
+  entry.ready = new Promise((resolve) => { settle = resolve; });
+  CLAIMS.set(origin, entry);
+  const read = () => {
+    // the unpatched fetch: the door is the twin's own origin, never a vendor host to redirect
+    const f = (ORIGINALS && ORIGINALS.fetch) || globalThis.fetch;
+    if (typeof f !== 'function') return;
+    Promise.resolve()
+      .then(() => f(`${origin}${door}`, { headers: attachTwinsKey({}) }))
+      .then((r) => (r.ok ? r.json() : null))
+      .then((body) => { if (body && Array.isArray(body.hosts)) entry.hosts = new Set(body.hosts.map((h) => String(h).toLowerCase())); })
+      .catch(() => {})
+      .then(() => { entry.loaded = true; settle(); });
+  };
+  read();
+  // every five seconds: each process that loads the injector reads (the app's workers, the proxy), and a custom domain
+  // takes Cloudflare minutes to turn Active, so a faster read buys nothing and loads the twin
+  const timer = setInterval(read, 5000);
+  if (timer.unref) timer.unref();
+  return entry;
+}
+/** The first read of a claiming twin's door still in flight for this map, or null when every one has landed. */
+function claimsPending(map) {
+  const pending = Object.keys(CLAIMERS).filter((v) => map[v]).map((v) => claimsAt(map[v], CLAIMERS[v])).filter((e) => !e.loaded);
+  return pending.length ? Promise.all(pending.map((e) => e.ready)) : null;
+}
+
+function isLocalOrPrivateHost(hostname) {
+  return isWorldInternalHost(hostname);
+}
+
+function strictEgressEnabled() {
+  return process.env.VOLTER_TWIN_STRICT_EGRESS === '1' || process.env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+}
+
+function shouldBlockUntwinned(url) {
+  const routed = url && resolveTwin(url.hostname, MAP, url.pathname);
+  if (!url || (routed && routed.vendor !== 'app')) return false;
+  return worldEgressRefusal(url) !== null;
+}
+
+// --- untwinned-host TLS failure naming (local mode) -----------------------------------------
+// Untwinned local-mode requests reach their real origin. A certificate error still needs
+// the routing context, but session trust supplements public roots; it is not the cause
+// of every failed certificate chain.
+const TLS_ISSUER_CODES = new Set([
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+]);
+
+// Only annotate when the world's CA env is actually in force — a TLS failure without it is a
+// genuinely bad chain, and blaming the world would mislead. VOLTER_WORLD_CA is the world's
+// definitive marker (proxyEnvFor sets it alongside the trust vars); SSL_CERT_FILE is the var
+// that mechanically replaces Node's root store.
+function worldCaIsConfigured() {
+  return Boolean(process.env.VOLTER_WORLD_CA || process.env.SSL_CERT_FILE);
+}
+
+function untwinnedTlsExplanation(hostname) {
+  return `[twin-inject] host ${hostname} is not twinned in this world; local mode does not intercept it — this traffic goes to the REAL vendor. (The real origin's certificate failed verification. Check its certificate chain and configured trust. Use sealed mode for a strict refusal, or add a twin for ${hostname}.)`;
+}
+
+function annotateUntwinnedTlsError(error, hostname) {
+  let cursor = error;
+  for (let depth = 0; cursor && depth < 5; depth += 1) {
+    const code = cursor.code;
+    const message = String(cursor.message || '');
+    if ((code && TLS_ISSUER_CODES.has(code)) || message.includes('unable to get local issuer certificate')) {
+      if (error instanceof Error && !String(error.message).includes('[twin-inject]')) {
+        error.message = `${error.message}\n${untwinnedTlsExplanation(hostname)}`;
+      }
+      return;
+    }
+    cursor = cursor.cause;
+  }
+}
+
+// --- request-args → { url, method, headers, callback } across every overload ---
+function describe(args, defaultProtocol) {
+  const input = args[0];
+  let options = {};
+  let callback;
+  if (typeof args[1] === 'function') callback = args[1];
+  else {
+    options = args[1] || {};
+    if (typeof args[2] === 'function') callback = args[2];
+  }
+  let url = null;
+  let headers = {};
+  let method = 'GET';
+  if (input instanceof URL || typeof input === 'string') {
+    try { url = new URL(String(input)); } catch { url = null; }
+    headers = options.headers || {};
+    method = options.method || 'GET';
+  } else {
+    const merged = Object.assign({}, input || {}, options);
+    headers = merged.headers || {};
+    method = merged.method || 'GET';
+    const proto = String(merged.protocol || defaultProtocol);
+    const host = merged.hostname || merged.host;
+    const path = merged.path || '/';
+    // A request addressed to a proxy (axios and others honour the World's HTTPS_PROXY) names the proxy as its host
+    // and carries the real target as its path: "When making a request to a proxy ... a client MUST send the target
+    // URI in "absolute-form" as the request-target" (RFC 9112 §3.2.2). That target is the request's URL.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) {
+      try { url = new URL(path); } catch { url = null; }
+    } else if (host) {
+      try { url = new URL(`${proto.endsWith(':') ? proto : `${proto}:`}//${host}${path}`); } catch { url = null; }
+    }
+  }
+  return { url, method: String(method).toUpperCase(), headers, callback };
+}
+
+let ORIGINALS = null; // captured once, used to forward to the twin without re-entering the patch
+
+// R7c (runtime contract): when *_TWIN_URL points at a hosted SKIN
+// ({twinsUrl}/{org}/{world}/{vendor}), the transport key rides x-twins-key on every
+// REWRITTEN request — its own header, never Authorization (that stays vendor
+// semantics). One key per world: VOLTER_TWINS_KEY. Absent = local loopback twins,
+// no key attached — exactly today's behavior.
+function twinsKey() { return process.env.VOLTER_TWINS_KEY || null; }
+function attachTwinsKey(headers) {
+  const key = twinsKey();
+  // Case-insensitive caller check (S4 review F6): node header iteration is
+  // last-write-wins case-insensitively, so ANY caller casing must suppress the attach.
+  if (key && !Object.keys(headers).some((k) => k.toLowerCase() === 'x-twins-key')) headers['x-twins-key'] = key;
+  return headers;
+}
+
+// The hosted World this process is attached to (VOLTER_WORLD, a URL). A request an SDK addresses
+// to one of the World's own paths — an app-read endpoint (TUNNEL_SERVER_URL, QSTASH_URL) pointed
+// at its twin, or its doors — is the World's wire as much as a rewritten one, so it carries the
+// same key (R7c). Only there: never to any other origin.
+function worldBase() {
+  const ref = process.env.VOLTER_WORLD;
+  if (!ref || !/^https?:\/\//i.test(ref)) return null;
+  try { const base = new URL(ref.replace(/\/\.well-known\/volter-world\/?$/, '').replace(/\/+$/, '')); return { origin: base.origin, path: base.pathname.replace(/\/+$/, '') }; } catch { return null; }
+}
+function addressedToWorld(url) {
+  const base = worldBase();
+  if (!base || !url || !base.path || url.origin.replace(/^ws/, 'http') !== base.origin) return false;
+  return url.pathname.startsWith(`${base.path}/`) || url.pathname.startsWith(`/-${base.path}/`);
+}
+/** http(s).request's arguments with the World key added to its headers (a copy; the caller's own
+ *  header, in any casing, wins). */
+function withWorldKey(args) {
+  const key = twinsKey();
+  if (!key) return args;
+  const keyed = (options) => {
+    const headers = Object.assign({}, (options && options.headers) || {});
+    if (!Object.keys(headers).some((k) => k.toLowerCase() === 'x-twins-key')) headers['x-twins-key'] = key;
+    return Object.assign({}, options || {}, { headers });
+  };
+  const out = args.slice();
+  if (typeof out[0] === 'string' || out[0] instanceof URL) {
+    if (out[1] && typeof out[1] === 'object') out[1] = keyed(out[1]);
+    else out.splice(1, 0, keyed({}));
+  } else {
+    out[0] = keyed(out[0]);
+  }
+  return out;
+}
+
+// S4 review F3: undici's default redirect-follow forwards CUSTOM headers across origins — a
+// twin (or the World) answering 30x to an external URL would carry x-twins-key to a REAL host. A
+// keyed fetch follows redirects itself: a hop that is a twin or the World re-enters the patched
+// fetch (the key re-attached there); any other hop is fetched WITHOUT the key.
+async function followKeyless(first, target, reqInit) {
+  let hop = await first();
+  let hopUrl = target;
+  let hopMethod = String(reqInit.method || 'GET').toUpperCase();
+  let hopBody = reqInit.body;
+  for (let hops = 0; hops < 5; hops += 1) {
+    const location = hop.status >= 300 && hop.status < 400 ? hop.headers.get('location') : null;
+    if (!location) return hop;
+    // RFC semantics per hop (audit M7): 303 → GET; 301/302 demote POST to GET
+    // (the browser convention SDKs expect); 307/308 preserve method AND body.
+    if (hop.status === 303 || ((hop.status === 301 || hop.status === 302) && hopMethod === 'POST')) {
+      hopMethod = 'GET';
+      hopBody = undefined;
+    }
+    // Resolve against the CURRENT hop (a relative Location from hop 2 is relative to hop 2),
+    // cancel the interim body, and re-enter the PATCHED fetch with the ORIGINAL headers minus
+    // the key.
+    const nextUrl = new URL(location, hopUrl);
+    try { hop.body && (await hop.body.cancel()); } catch { /* interim body */ }
+    const hopHeaders = new Headers(reqInit.headers || {});
+    hopHeaders.delete('x-twins-key');
+    hopHeaders.delete('x-volter-twin-original-host');
+    hop = await globalThis.fetch(nextUrl, {
+      method: hopMethod,
+      headers: hopHeaders,
+      ...(hopBody === undefined ? {} : { body: hopBody }),
+      redirect: 'manual',
+    });
+    hopUrl = nextUrl;
+  }
+  return hop;
+}
+
+// A request routed to the application is a real request to where it listens (the original http/https request, so
+// streaming, aborts and timeouts behave as the client expects); its options are app-route.cjs's, shared with the twins'
+// deliveries.
+function requestApp(route, url, method, headers, extra, callback) {
+  const options = appRequestOptions(route, url, method, headers, extra);
+  const make = options.protocol === 'https:' ? ORIGINALS.httpsRequest : ORIGINALS.httpRequest;
+  return callback ? make(options, callback) : make(options);
+}
+
+// What leaves the application with a redirect to anywhere else: what native fetch drops crossing origins, and the World's own.
+const CROSS_ORIGIN_DROPPED = ['authorization', 'cookie', 'proxy-authorization', 'x-twins-key', 'x-volter-twin-original-host'];
+
+/** fetch() routed to the application, as native fetch behaves: the caller's redirect mode, its signal, a streamed
+ *  body, decoded content; redirects followed (at most 20) within the application while they stay on its hosts, and
+ *  through the patched fetch, without credentials or the World's headers, once they leave. */
+async function fetchApp(route, url, input, init) {
+  const request = typeof input === 'object' && input !== null && !(input instanceof URL) && typeof input.url === 'string' ? input : null;
+  const mode = (init && init.redirect) || (request && request.redirect) || 'follow';
+  const signal = (init && init.signal) || (request && request.signal) || undefined;
+  let method = String((init && init.method) || (request && request.method) || 'GET').toUpperCase();
+  const headers = {};
+  new Headers((init && init.headers) || (request && request.headers) || {}).forEach((value, key) => { headers[key] = value; });
+  let body = init && init.body !== undefined ? init.body : request && request.body ? request.body : undefined;
+  if (body != null && typeof body !== 'string' && !Buffer.isBuffer(body)) {
+    // the body's own type (a form's boundary, URLSearchParams, a Blob's type), as native fetch sends it
+    const read = new Response(body);
+    const type = read.headers.get('content-type');
+    if (type && !Object.keys(headers).some((k) => k.toLowerCase() === 'content-type')) headers['content-type'] = type;
+    body = Buffer.from(await read.arrayBuffer());
+  } else if (typeof body === 'string' && !Object.keys(headers).some((k) => k.toLowerCase() === 'content-type')) headers['content-type'] = 'text/plain;charset=UTF-8';
+  let at = url; let current = route;
+  for (let hops = 0; ; hops++) {
+    if (signal && signal.aborted) throw signal.reason ?? new DOMException('This operation was aborted', 'AbortError');
+    const res = await new Promise((resolve, reject) => {
+      const req = requestApp(current, at, method, headers, { signal }, resolve);
+      req.on('error', reject);
+      if (body != null) req.write(body);
+      req.end();
+    });
+    const location = res.headers.location;
+    if (res.statusCode >= 300 && res.statusCode < 400 && location && [301, 302, 303, 307, 308].includes(res.statusCode) && mode !== 'manual') {
+      res.resume();
+      if (mode === 'error') throw new TypeError('fetch failed: unexpected redirect');
+      if (hops >= 20) throw new TypeError('fetch failed: redirect count exceeded');
+      const next = new URL(String(location), at);
+      // 303 answers with a GET (a HEAD stays one); 301 and 302 turn only a POST into a GET, as fetch does
+      if ((res.statusCode === 303 && method !== 'HEAD') || ((res.statusCode === 301 || res.statusCode === 302) && method === 'POST')) {
+        method = 'GET'; body = undefined;
+        for (const k of Object.keys(headers)) if (/^content-/i.test(k)) delete headers[k];
+      }
+      const nextRoute = resolveTwin(next.hostname, MAP, next.pathname);
+      if (!nextRoute || nextRoute.vendor !== 'app') {
+        for (const k of Object.keys(headers)) if (CROSS_ORIGIN_DROPPED.includes(k.toLowerCase())) delete headers[k];
+        const onward = await globalThis.fetch(next.toString(), { method, headers, redirect: mode, ...(signal ? { signal } : {}), ...(body != null ? { body } : {}) });
+        return onward;
+      }
+      at = next; current = nextRoute;
+      continue;
+    }
+    const out = new Headers();
+    for (const [k, v] of Object.entries(res.headers)) if (v !== undefined) for (const one of Array.isArray(v) ? v : [v]) out.append(k, String(one));
+    let stream = res;
+    const encoding = String(res.headers['content-encoding'] || '').toLowerCase();
+    const zlib = require('zlib');
+    const decoder = encoding === 'gzip' || encoding === 'x-gzip' ? zlib.createGunzip() : encoding === 'deflate' ? zlib.createInflate() : encoding === 'br' ? zlib.createBrotliDecompress() : null;
+    if (decoder) { stream = res.pipe(decoder); out.delete('content-encoding'); out.delete('content-length'); }
+    const empty = [101, 204, 205, 304].includes(res.statusCode) || method === 'HEAD';
+    if (empty) res.resume();
+    const response = new Response(empty ? null : Readable.toWeb(stream), { status: res.statusCode, statusText: res.statusMessage, headers: out });
+    Object.defineProperty(response, 'url', { value: at.toString() });
+    if (hops > 0) Object.defineProperty(response, 'redirected', { value: true });
+    return response;
+  }
+}
+
+function forward(origin, method, fullPath, headers, body) {
+  return new Promise((resolve, reject) => {
+    let target;
+    try { target = new URL(origin); } catch (error) { reject(new Error(`bad twin URL "${origin}": ${error.message}`)); return; }
+    const mod = target.protocol === 'https:' ? ORIGINALS.httpsRequest : ORIGINALS.httpRequest;
+    const fwdHeaders = attachTwinsKey(Object.assign({}, headers));
+    delete fwdHeaders['accept-encoding']; delete fwdHeaders['Accept-Encoding'];
+    // A SKIN origin carries its namespace as a PATH (/{org}/{world}/{vendor}) — prefix
+    // it, or the hosted twin is addressed at the wrong root (R7c). Loopback origins have
+    // pathname '/', which prefixes to nothing: local behavior unchanged.
+    const originPath = target.pathname.replace(/\/$/, '');
+    fullPath = `${originPath}${fullPath}`;
+    // an https twin origin (a served world's door) verifies against the session
+    // CA even when NODE_EXTRA_CA_CERTS was set after process start (the rung-2
+    // dormant attach does exactly that)
+    const ca = target.protocol === 'https:' ? sessionCa() : null;
+    const req = mod({
+      protocol: target.protocol,
+      hostname: target.hostname,
+      port: target.port,
+      method,
+      path: fullPath,
+      headers: fwdHeaders,
+      ...(ca ? { ca } : {}),
+      // the TLS name is the twin's: Node's agent otherwise takes it from the forwarded Host (the
+      // vendor's, e.g. api.stripe.com), and the socket guard refuses a connection naming a twinned host
+      ...(target.protocol === 'https:' && !isIP(target.hostname) ? { servername: target.hostname } : {}),
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('error', reject);
+      res.on('end', () => resolve({ statusCode: res.statusCode || 200, headers: res.headers || {}, body: Buffer.concat(chunks) }));
+    });
+    req.on('error', reject);
+    if (body && body.length) req.write(body);
+    req.end();
+  });
+}
+
+// A stand-in ClientRequest: collects the body, forwards to the twin on end(),
+// then emits the twin's response as an IncomingMessage-shaped Readable.
+function fakeClientRequest(origin, method, fullPath, headers, callback) {
+  const request = new EventEmitter();
+  const bodyChunks = [];
+  // Some SDKs (e.g. stripe-node's NodeHttpClient) only call write()/end() from
+  // inside a `req.once('socket', …)` handler — so we must emit a socket. The
+  // socket reports `connecting: false` so callers write+end immediately.
+  const socket = new EventEmitter();
+  socket.connecting = false;
+  socket.setKeepAlive = () => socket;
+  socket.setTimeout = () => socket;
+  socket.unref = () => socket;
+  socket.ref = () => socket;
+  socket.destroy = () => socket;
+  request.socket = socket;
+  request.connection = socket;
+  process.nextTick(() => request.emit('socket', socket));
+  request.write = (chunk, enc, cb) => {
+    if (chunk) bodyChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), typeof enc === 'string' ? enc : 'utf8'));
+    if (typeof enc === 'function') enc();
+    else if (typeof cb === 'function') cb();
+    return true;
+  };
+  // A ClientRequest emits 'finish' once its body is flushed and 'close' when
+  // the exchange ends; stream.pipeline() into a request waits for them.
+  let closed = false;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    request.destroyed = true;
+    request.emit('close');
+  };
+  request.destroyed = false;
+  request.writableFinished = false;
+  let ended = false;
+  request.end = (chunk, enc, cb) => {
+    if (typeof chunk === 'function') { cb = chunk; chunk = undefined; }
+    else if (typeof enc === 'function') { cb = enc; enc = undefined; }
+    if (ended) return request;
+    ended = true;
+    if (chunk) request.write(chunk, enc);
+    process.nextTick(() => { request.writableFinished = true; request.emit('finish'); });
+    forward(origin, method, fullPath, headers, Buffer.concat(bodyChunks))
+      .then(({ statusCode, headers: resHeaders, body }) => {
+        // A request destroyed while the twin answered never emits a response.
+        if (closed) return;
+        const res = Readable.from([body]);
+        res.once('end', close);
+        res.once('close', close);
+        res.statusCode = statusCode;
+        // Preserve Node IncomingMessage semantics. npm's pacote path classifies a missing
+        // packument from statusCode + the canonical statusMessage; the generic "Error" placeholder
+        // made an ordinary 404 fatal before npm publish could proceed to PUT.
+        res.statusMessage = http.STATUS_CODES[statusCode] || '';
+        res.headers = Object.assign({}, resHeaders);
+        res.rawHeaders = Object.entries(resHeaders).flatMap(([name, value]) => [name, String(value)]);
+        res.trailers = {};
+        res.rawTrailers = [];
+        res.complete = true;
+        res.socket = socket;
+        res.connection = socket;
+        res.httpVersion = '1.1';
+        res.httpVersionMajor = 1;
+        res.httpVersionMinor = 1;
+        if (typeof callback === 'function') callback(res);
+        request.emit('response', res);
+        if (typeof cb === 'function') cb();
+      })
+      .catch((error) => { if (!closed) request.emit('error', error); close(); });
+    return request;
+  };
+  request.setHeader = () => {};
+  request.getHeader = () => undefined;
+  request.removeHeader = () => {};
+  request.setNoDelay = () => {};
+  request.setSocketKeepAlive = () => {};
+  request.flushHeaders = () => {};
+  request.setTimeout = (_timeout, cb) => { if (typeof cb === 'function') request.once('timeout', cb); return request; };
+  request.abort = () => { request.emit('abort'); close(); };
+  request.destroy = (error) => {
+    if (error && !closed) process.nextTick(() => request.emit('error', error));
+    process.nextTick(close);
+    return request;
+  };
+  return request;
+}
+
+// --- unclaimed path on a twinned shared host: refuse LOUDLY, never mis-route -----------------
+// The Cal.com incident class: a host two vendors share (www.googleapis.com) is twinned, the
+// request's PATH belongs to neither twin (`/calendar/v3/*` — Google Calendar has no pack), and
+// the old catch-all matcher answered it from the WRONG pack with a vendor-shaped 404: fails open
+// AND plausible. The operator declared this host virtualized, so the traffic must not leak to the
+// real vendor either. The only honest outcome is a refusal that NAMES the situation.
+
+/** The configured vendors that claim `hostname` at host level (candidacy, pathname undefined). */
+function twinnedHostVendors(hostname, map) {
+  return Object.keys(VENDOR_HOSTS).filter((vendor) => map[vendor] && VENDOR_HOSTS[vendor](hostname, undefined));
+}
+
+function unclaimedTwinnedHostPathMessage(hostname, pathname, map) {
+  const vendors = twinnedHostVendors(hostname, map);
+  return `[twin-inject] host ${hostname} is twinned in this world (configured twin${vendors.length === 1 ? '' : 's'}: ${vendors.join(', ')}), `
+    + `but path ${pathname} belongs to no pack in this world — no twin serves that API yet. `
+    + `Refusing loudly rather than answering from the wrong twin or leaking to the real vendor. `
+    + `If a twin for this API exists, set its *_TWIN_URL; otherwise this API needs a new pack.`;
+}
+
+function blockedClientRequest(message) {
+  const request = new EventEmitter();
+  const error = new Error(message);
+  const socket = new EventEmitter();
+  socket.connecting = false;
+  socket.setKeepAlive = () => socket;
+  socket.setTimeout = () => socket;
+  socket.unref = () => socket;
+  socket.ref = () => socket;
+  socket.destroy = () => socket;
+  request.socket = socket;
+  request.connection = socket;
+  request.write = () => true;
+  request.end = (_chunk, _enc, cb) => {
+    process.nextTick(() => {
+      request.emit('error', error);
+      if (typeof cb === 'function') cb(error);
+    });
+    return request;
+  };
+  request.setHeader = () => {};
+  request.getHeader = () => undefined;
+  request.removeHeader = () => {};
+  request.setNoDelay = () => {};
+  request.setSocketKeepAlive = () => {};
+  request.flushHeaders = () => {};
+  request.setTimeout = (_timeout, cb) => { if (typeof cb === 'function') request.once('timeout', cb); return request; };
+  request.abort = () => request.emit('abort');
+  request.destroy = () => { request.emit('close'); return request; };
+  return request;
+}
+
+// ── SOCKET BACKSTOP ──────────────────────────────────────────────────────────────────────────
+// The target a `net.connect`/`tls.connect` call names, in every argument form Node accepts:
+// (options[, cb]), (port[, host][, options][, cb]), (path[, cb]). A unix path names no host.
+// SNI counts only for TLS: Node's http Agent sets `servername` from the Host header on plain
+// connections too, which is how a request forwarded to a loopback twin still names its vendor.
+function socketTargetHosts(args, isTls) {
+  const [first, second, third] = args;
+  const hosts = [];
+  if (first !== null && typeof first === 'object') {
+    if (first.path !== undefined && first.host === undefined) return hosts;
+    hosts.push(first.host === undefined ? 'localhost' : first.host);
+    if (isTls && first.servername) hosts.push(first.servername);
+    return hosts;
+  }
+  if (typeof first === 'string' && !/^\d+$/.test(first)) return hosts; // a unix socket path
+  hosts.push(typeof second === 'string' ? second : 'localhost');
+  const options = typeof second === 'object' && second !== null ? second : typeof third === 'object' && third !== null ? third : null;
+  if (isTls && options && options.servername) hosts.push(options.servername);
+  return hosts;
+}
+
+function endpointEnvFor(vendor) {
+  try {
+    const facts = require('./generated/pack-facts.json').packs[vendor];
+    const endpoint = facts && facts.endpointEnv;
+    if (!endpoint) return null;
+    const templates = Object.keys(endpoint.templates || {});
+    return templates.length > 0 ? templates.join(', ') : endpoint.name;
+  } catch { return null; }
+}
+
+function isTwinOriginHost(host) {
+  return Object.values(MAP).some((origin) => {
+    try { return new URL(origin).hostname.toLowerCase() === host; } catch { return false; }
+  });
+}
+
+// WORLD DNS: a name the World routes (a vendor's host its twin serves, a host a twin claims, the application's own)
+// resolves in a process the injector is installed in, as it resolves on the internet, including a name nothing public
+// holds (a custom domain connected in the World, assets.<zone>): code that vets a URL before fetching it (an SSRF
+// guard: look the name up, refuse a private address, then fetch by name, as Dub's storage does) meets the answer a
+// public name gets. The address is one of the documentation ranges (RFC 5737's 203.0.113.0/24, RFC 3849's
+// 2001:db8::/32): public-shaped, never private, and routed nowhere, so nothing reaches a host by it; the request by name
+// is routed as every other one is, and a socket dialled to the address itself is refused with the reason. Every other
+// name is the real resolver's, unchanged.
+const WORLD_ADDRESS = { 4: '203.0.113.7', 6: '2001:db8::7' };
+function worldResolves(hostname) {
+  const host = String(hostname || '').toLowerCase().replace(/\.$/, '');
+  return !!host && !isIP(host) && !isLocalOrPrivateHost(host) && resolveTwin(host, MAP) !== null;
+}
+/** dns.lookup's answer for a name the World routes, in the shape `options` asks for (family, all). */
+function worldLookupAnswer(options) {
+  const raw = typeof options === 'number' ? options : options && options.family;
+  const family = raw === 'IPv6' || Number(raw) === 6 ? 6 : raw === 'IPv4' || Number(raw) === 4 ? 4 : 0;
+  const v6first = !!(options && typeof options === 'object' && options.order === 'ipv6first');
+  const families = family === 6 ? [6] : family === 4 ? [4] : v6first ? [6, 4] : [4, 6];
+  const all = !!(options && typeof options === 'object' && options.all);
+  return all ? families.map((f) => ({ address: WORLD_ADDRESS[f], family: f })) : { address: WORLD_ADDRESS[families[0]], family: families[0] };
+}
+/** Whether a lookup of `hostname` waits for the claiming twins' first read: never for a twin's own origin, whose
+ *  lookup that read itself makes (a claimer at a hostname origin, as `attach` gives one, would wait on itself). */
+function lookupWaitsForClaims(hostname) {
+  const host = String(hostname || '').toLowerCase();
+  if (!host || isIP(host) || isLocalOrPrivateHost(host) || isTwinOriginHost(host)) return null;
+  for (const origin of Object.values(MAP)) { try { if (new URL(origin).hostname.toLowerCase() === host) return null; } catch { /* not a URL */ } }
+  return claimsPendingBriefly();
+}
+/** The claiming twins' first read, waited a moment at most: a slow or unanswering twin delays a lookup or a fetch as a
+ *  slow resolver would, and a name it claims is known from its next read. Null when every first read has landed. */
+function claimsPendingBriefly() {
+  const pending = claimsPending(MAP);
+  return pending ? Promise.race([pending, new Promise((ok) => { const t = setTimeout(ok, 1500); if (t.unref) t.unref(); })]) : null;
+}
+function patchedLookup(original) {
+  return function patchedDnsLookup(hostname, options, callback) {
+    const cb = typeof options === 'function' ? options : callback;
+    const opts = typeof options === 'function' ? undefined : options;
+    if (typeof cb !== 'function') return original.apply(this, arguments);
+    const answer = () => {
+      if (!worldResolves(hostname)) return original.call(dns, hostname, opts ?? {}, cb);
+      const a = worldLookupAnswer(opts);
+      process.nextTick(() => (Array.isArray(a) ? cb(null, a) : cb(null, a.address, a.family)));
+    };
+    // a name a twin may claim is decided once its door has been read (HOSTS A TWIN CLAIMS, above)
+    const pending = lookupWaitsForClaims(hostname);
+    // the original's own throw (an invalid name) reaches the callback, as it would have
+    if (pending) pending.then(answer).catch((error) => cb(error)); else answer();
+    return {};
+  };
+}
+function patchedPromisesLookup(original) {
+  return async function patchedDnsPromisesLookup(hostname, options) {
+    const pending = lookupWaitsForClaims(hostname);
+    if (pending) await pending;
+    return worldResolves(hostname) ? worldLookupAnswer(options) : original.call(dns.promises, hostname, options);
+  };
+}
+
+function socketRefusal(hostname) {
+  const host = String(hostname || '').toLowerCase();
+  if (host === WORLD_ADDRESS[4] || host === WORLD_ADDRESS[6]) {
+    return `[twin-inject] refused a socket to ${host}, the address this World's DNS gives the names it routes: `
+      + 'nothing listens there; connect by the name, which the World routes to its twin or its application.';
+  }
+  if (!host || isLocalOrPrivateHost(host) || isTwinOriginHost(host)) return null;
+  const vendors = twinnedHostVendors(host, MAP);
+  if (vendors.length > 0) {
+    const doors = vendors.map(endpointEnvFor).filter(Boolean);
+    return `[twin-inject] refused a raw socket to ${host}, which is twinned in this world (${vendors.join(', ')}): `
+      + `the client opened its own connection instead of going through http/https or fetch, so the twin never saw it. `
+      + (doors.length > 0
+        ? `The SDK reaches the twin through ${doors.join('; ')}, which the world sets when it runs the app.`
+        : `This client needs an endpoint door on the pack before the world can serve it.`);
+  }
+  if (resolveTwin(host, MAP)?.vendor === 'app') {
+    return `[twin-inject] refused a raw socket to ${host}, which this world routes to the application (volter-world app-url --host): `
+      + 'the client opened its own connection instead of going through http/https or fetch, so it could not be routed.';
+  }
+  const url = (() => { try { return new URL(`https://${isIP(host) === 6 ? `[${host}]` : host}/`); } catch { return null; } })();
+  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${host}`;
+  return null;
+}
+
+function refusedSocket(message) {
+  const socket = new net.Socket();
+  process.nextTick(() => socket.destroy(Object.assign(new Error(message), { code: 'ECONNREFUSED' })));
+  return socket;
+}
+
+function patchedConnect(originalConnect, isTls) {
+  return function patchedSocketConnect(...args) {
+    for (const host of socketTargetHosts(args, isTls)) {
+      const refusal = socketRefusal(host);
+      if (refusal) return refusedSocket(refusal);
+    }
+    return originalConnect.apply(this, args);
+  };
+}
+
+let MAP = {};
+let installed = false;
+
+function patchedFactory(originalRequest, defaultProtocol) {
+  return function patchedRequest(...args) {
+    const { url, method, headers, callback } = describe(args, defaultProtocol);
+    const twin = url && resolveTwin(url.hostname, MAP, url.pathname);
+    if (twin && twin.vendor === 'app') {
+      const given = args.find((a) => a && typeof a === 'object' && !(a instanceof URL)) || {};
+      return requestApp(twin, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
+    }
+    if (twin) {
+      const fwdHeaders = Object.assign({}, headers);
+      if (!fwdHeaders.host && !fwdHeaders.Host) fwdHeaders.host = url.host;
+      return fakeClientRequest(twin.origin, method, url.pathname + url.search, fwdHeaders, callback);
+    }
+    // No twin claims this path — but if configured twins claim the HOST, the path is an unclaimed
+    // slice of a shared, virtualized host (the Cal.com /calendar/v3 case): refuse loudly, in every
+    // mode, before the strict-egress check gets a chance to phrase it as an ordinary untwinned host.
+    if (url && twinnedHostVendors(url.hostname, MAP).length > 0) {
+      return blockedClientRequest(unclaimedTwinnedHostPathMessage(url.hostname, url.pathname, MAP));
+    }
+    if (shouldBlockUntwinned(url)) return blockedClientRequest(`[twin-inject] blocked untwinned external request to ${url.hostname}`);
+    const request = originalRequest.apply(this, addressedToWorld(url) ? withWorldKey(args) : args);
+    // Local mode, untwinned external host, world CA in force: the TLS handshake against the
+    // real vendor is about to fail with a bare OpenSSL message — annotate it in-place via an
+    // emit wrapper (NOT an 'error' listener, which would swallow the crash-on-unhandled
+    // semantics callers rely on).
+    if (url && !isLocalOrPrivateHost(url.hostname) && worldCaIsConfigured() && request && typeof request.emit === 'function') {
+      const originalEmit = request.emit;
+      const hostname = url.hostname;
+      request.emit = function annotatedEmit(event, ...rest) {
+        if (event === 'error' && rest[0]) annotateUntwinnedTlsError(rest[0], hostname);
+        return originalEmit.call(this, event, ...rest);
+      };
+    }
+    return request;
+  };
+}
+
+function install(mapOverride) {
+  const read = mapOverride || readMap(process.env);
+  MAP = Object.assign({}, MAP, read);
+  // the instance a map routes app hosts for is not a key, so Object.assign leaves it behind
+  if (read[APP_INSTANCE] || MAP[APP_INSTANCE] === undefined) Object.defineProperty(MAP, APP_INSTANCE, { value: read[APP_INSTANCE], enumerable: false, configurable: true });
+  // the claiming twins' doors are read from the start, so a process's first request finds what they claim
+  for (const vendor of Object.keys(CLAIMERS)) if (MAP[vendor]) claimsAt(MAP[vendor], CLAIMERS[vendor]);
+  const active = Object.keys(MAP);
+  if (installed || (!active.length && !worldBase() && !MAP[APP_INSTANCE] && !strictEgressEnabled() && !worldNetworkPolicyFromEnv(process.env))) return { active };
+
+  ORIGINALS = {
+    httpRequest: http.request.bind(http),
+    httpGet: http.get.bind(http),
+    httpsRequest: https.request.bind(https),
+    httpsGet: https.get.bind(https),
+    fetch: typeof globalThis.fetch === 'function' ? globalThis.fetch : null,
+    netConnect: net.connect,
+    netCreateConnection: net.createConnection,
+    tlsConnect: tls.connect,
+    dnsLookup: dns.lookup,
+    dnsPromisesLookup: dns.promises.lookup,
+  };
+
+  http.request = patchedFactory(ORIGINALS.httpRequest, 'http:');
+  https.request = patchedFactory(ORIGINALS.httpsRequest, 'https:');
+  http.get = function patchedHttpGet(...args) { const req = http.request(...args); req.end(); return req; };
+  https.get = function patchedHttpsGet(...args) { const req = https.request(...args); req.end(); return req; };
+  net.connect = patchedConnect(ORIGINALS.netConnect, false);
+  net.createConnection = patchedConnect(ORIGINALS.netCreateConnection, false);
+  tls.connect = patchedConnect(ORIGINALS.tlsConnect, true);
+  dns.lookup = patchedLookup(ORIGINALS.dnsLookup);
+  dns.promises.lookup = patchedPromisesLookup(ORIGINALS.dnsPromisesLookup);
+
+  if (ORIGINALS.fetch) {
+    const originalFetch = ORIGINALS.fetch;
+    globalThis.fetch = function patchedFetch(input, init, claimsWaited) {
+      let urlStr;
+      try { urlStr = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input && input.url; } catch { urlStr = undefined; }
+      let url = null;
+      if (urlStr) { try { url = new URL(urlStr); } catch { url = null; } }
+      const twin = url && resolveTwin(url.hostname, MAP, url.pathname);
+      if (!twin) {
+        // a host a twin may claim is decided once its door has been read (HOSTS A TWIN CLAIMS, above)
+        // waited once at most: a retry after the wait goes on with what is known
+        const pending = !claimsWaited && url && !isLocalOrPrivateHost(url.hostname) && !isTwinOriginHost(url.hostname) ? claimsPendingBriefly() : null;
+        if (pending) return pending.then(() => patchedFetch(input, init, true));
+        // Same shared-host rule as patchedFactory: an unclaimed path on a twinned host refuses
+        // loudly in every mode — never mis-routed, never leaked to the real vendor.
+        if (url && twinnedHostVendors(url.hostname, MAP).length > 0) {
+          return Promise.reject(new Error(unclaimedTwinnedHostPathMessage(url.hostname, url.pathname, MAP)));
+        }
+        if (shouldBlockUntwinned(url)) return Promise.reject(new Error(`[twin-inject] blocked untwinned external fetch to ${url.hostname}`));
+        // Automatic redirects run inside native fetch, past this interception
+        // point. Under an explicit World policy they must not open an unchecked
+        // second origin. Manual redirects remain readable for an SDK to follow
+        // through this same authorization door.
+        if (addressedToWorld(url) && twinsKey()) {
+          const request = typeof input === 'object' && input !== null ? input : undefined;
+          const headers = new Headers(init?.headers ?? request?.headers ?? {});
+          if (!headers.has('x-twins-key')) headers.set('x-twins-key', twinsKey());
+          const keyed = Object.assign({}, init, { headers });
+          if (!keyed.method && request?.method) keyed.method = request.method;
+          const redirect = keyed.redirect ?? request?.redirect ?? 'follow';
+          if (redirect === 'follow') {
+            if (worldNetworkPolicyFromEnv(process.env)) return originalFetch(input, Object.assign(keyed, { redirect: 'error' }));
+            keyed.redirect = 'manual';
+            return followKeyless(() => originalFetch(input, keyed), url, keyed);
+          }
+          return originalFetch(input, keyed);
+        }
+        const policy = worldNetworkPolicyFromEnv(process.env);
+        const redirect = init?.redirect ?? (typeof input === 'object' && input?.redirect) ?? 'follow';
+        const passthrough = originalFetch(input, policy && redirect === 'follow'
+          ? { ...init, redirect: 'error' } : init);
+        // Same untwinned-host TLS naming as patchedFactory: fetch wraps the issuer error in
+        // "fetch failed" with the code down the `cause` chain — annotate the surfaced error.
+        if (url && !isLocalOrPrivateHost(url.hostname) && worldCaIsConfigured() && passthrough && typeof passthrough.catch === 'function') {
+          const hostname = url.hostname;
+          return passthrough.catch((error) => {
+            annotateUntwinnedTlsError(error, hostname);
+            throw error;
+          });
+        }
+        return passthrough;
+      }
+      if (twin.vendor === 'app') return fetchApp(twin, url, input, init);
+      const target = `${twin.origin.replace(/\/$/, '')}${url.pathname}${url.search}`;
+      const reqInit = Object.assign({}, init);
+      if (!reqInit.method && typeof input === 'object' && input && input.method) reqInit.method = input.method;
+      if (!reqInit.headers && typeof input === 'object' && input && input.headers) reqInit.headers = input.headers;
+      // A Request's body is a ReadableStream, and fetch refuses a stream body without `duplex: 'half'` ("duplex option is
+      // required when sending a body"): aws4fetch hands fetch such a Request for every signed upload.
+      if (reqInit.body === undefined && typeof input === 'object' && input && input.body != null) {
+        reqInit.body = input.body;
+        if (reqInit.duplex === undefined) reqInit.duplex = 'half';
+      }
+      if (reqInit.redirect === undefined && typeof input === 'object' && input?.redirect) reqInit.redirect = input.redirect;
+      if (worldNetworkPolicyFromEnv(process.env) && (reqInit.redirect === undefined || reqInit.redirect === 'follow')) reqInit.redirect = 'error';
+      // Preserve the vendor destination for twins that serve more than one registry flavor from
+      // one local origin. Host is honored by node:http; this explicit internal header is the
+      // fetch-safe fallback when a runtime normalizes the forbidden Host header itself.
+      const redirectedHeaders = new Headers(reqInit.headers || {});
+      redirectedHeaders.set('x-volter-twin-original-host', url.host);
+      { const key = twinsKey(); if (key && !redirectedHeaders.has('x-twins-key')) redirectedHeaders.set('x-twins-key', key); }
+      reqInit.headers = redirectedHeaders;
+      // The application is routed with its own Host (native fetch sets Host from the target, and the application tells
+      // its hostnames apart by it) through forward(), the node path; a redirect it answers is followed as fetch would,
+      // through this same patch, so its next host is routed on its own.
+      // Redirects are followed by followKeyless, so the key never reaches another origin. The
+      // node path already behaves this way (the SDK sees the 30x and retries through the patch).
+      if (twinsKey() && (reqInit.redirect === undefined || reqInit.redirect === 'follow')) {
+        reqInit.redirect = 'manual';
+        return followKeyless(() => originalFetch(target, reqInit), target, reqInit);
+      }
+      // an https twin origin (a served world's door): undici cannot use a
+      // session CA set after process start, so route through forward() — the
+      // node-https path that honors it — and synthesize a Response. Falls
+      // back to the native fetch for streaming bodies (rare for SDK JSON).
+      if (/^https:/i.test(twin.origin) && sessionCa()) {
+        const bodyValue = reqInit.body;
+        if (bodyValue === undefined || typeof bodyValue === 'string' || Buffer.isBuffer(bodyValue)) {
+          const headerObj = {};
+          const rawHeaders = reqInit.headers;
+          if (rawHeaders && typeof rawHeaders.forEach === 'function') rawHeaders.forEach((value, key) => { headerObj[key] = value; });
+          else if (rawHeaders) Object.assign(headerObj, rawHeaders);
+          headerObj.host = url.host; // the vendor host, for the door's Host-routing fidelity
+          // forward() is the SINGLE owner of origin-path prefixing (S4 review F1: this
+          // branch used to prefix too, doubling the namespace on pathed https skins).
+          const fullPath = `${url.pathname}${url.search}`;
+          return forward(twin.origin, String(reqInit.method || 'GET').toUpperCase(), fullPath, headerObj, bodyValue === undefined ? undefined : Buffer.from(bodyValue))
+            .then((res) => new Response(res.body, { status: res.statusCode, headers: res.headers }));
+        }
+      }
+      return originalFetch(target, reqInit);
+    };
+  }
+
+  // Bun replaces `node-fetch` imports with an internal shim bound to the
+  // NATIVE fetch, so a library that imports node-fetch bypasses the
+  // globalThis.fetch patch above entirely (gaxios v7 does exactly this when
+  // `window` is absent — every google-auth token exchange would leak). The
+  // shim's exports object is mutable and later ESM imports observe the
+  // mutation, so re-point `default` at whatever globalThis.fetch is at CALL
+  // time — which keeps redirect + strict-egress semantics, and stays correct
+  // if restore() later swaps the patched fetch back out.
+  if (typeof Bun !== 'undefined') {
+    try {
+      const nodeFetchShim = require('node-fetch');
+      if (nodeFetchShim && (typeof nodeFetchShim === 'object' || typeof nodeFetchShim === 'function')) {
+        nodeFetchShim.default = (input, init) => globalThis.fetch(input, init);
+      }
+    } catch { /* node-fetch not importable here — nothing to seal */ }
+  }
+
+  installed = true;
+  // Exact subprocess-output receipts still need the interception itself, but
+  // infrastructure diagnostics must not become application stderr. The
+  // attach command can opt those descendants into silence without weakening
+  // routing or the sealed-world boundary.
+  if (process.env.VOLTER_TWIN_INJECT_QUIET !== '1') {
+    for (const vendor of active) {
+      process.stderr.write(`[twin-inject] ${vendor}: redirecting to ${MAP[vendor]}\n`);
+    }
+  }
+  return { active };
+}
+
+function restore() {
+  if (!installed || !ORIGINALS) { MAP = {}; return; }
+  http.request = ORIGINALS.httpRequest;
+  http.get = ORIGINALS.httpGet;
+  https.request = ORIGINALS.httpsRequest;
+  https.get = ORIGINALS.httpsGet;
+  if (ORIGINALS.fetch) globalThis.fetch = ORIGINALS.fetch;
+  net.connect = ORIGINALS.netConnect;
+  net.createConnection = ORIGINALS.netCreateConnection;
+  tls.connect = ORIGINALS.tlsConnect;
+  dns.lookup = ORIGINALS.dnsLookup;
+  dns.promises.lookup = ORIGINALS.dnsPromisesLookup;
+  installed = false;
+  MAP = {};
+}
+
+module.exports = { install, restore, readMap, resolveTwin, twinUrlVendor, twinnedHostVendors, unclaimedTwinnedHostPathMessage, appForwardHeaders, VENDOR_HOSTS };
+
+// Auto-install as a preload (`--require`); strict refusal also applies without twin URLs.
+install();
+installPrismaAdapterShim();