@volter/twin 0.1.0 → 0.1.1

package/inject.cjs

@@ -9,13 +9,12 @@
 //   node --require @volter/twin/inject app.js
 //   NODE_OPTIONS="--require @volter/twin/inject" <your start command>
 //
-// Twin URLs come from the environment (only configured vendors are redirected):
-//   STRIPE_TWIN_URL=http://127.0.0.1:12111
-//   SLACK_TWIN_URL  GITHUB_TWIN_URL  JIRA_TWIN_URL  LINEAR_TWIN_URL  S3_TWIN_URL
-//   OPENROUTER_TWIN_URL  CLERK_TWIN_URL  WEBRISK_TWIN_URL  RESEND_TWIN_URL  SENTRY_TWIN_URL
-//   POLAR_TWIN_URL  ANTHROPIC_TWIN_URL  ELEVENLABS_TWIN_URL  GOOGLEFAVICON_TWIN_URL  BROWSERASSETS_TWIN_URL
-//   VITAL_TWIN_URL  CALCOM_TWIN_URL  OPENWEATHER_TWIN_URL  GOOGLEMAPS_TWIN_URL  MAPBOX_TWIN_URL  STREAM_TWIN_URL
-//   DYNAMODB_TWIN_URL  TIMESTREAM_TWIN_URL  (point these at the consolidated `aws` twin, same as S3_TWIN_URL)
+//   <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
@@ -29,27 +28,133 @@ const { Readable } = require('stream');
 const Module = require('module');
 const { createPublicKey, createVerify } = require('crypto');
 
-// vendor → predicate(hostname). A vendor is only active if its twin URL is set.
+// ── PATH-AWARE DISAMBIGUATION (the shared-host case) ─────────────────────────────────────────
+// A predicate is called as `(hostname, pathname)`. `pathname` is OPTIONAL and is `undefined`
+// wherever the caller genuinely does not have one yet — most importantly the proxy's CONNECT
+// handler, which sees only the SNI host before TLS is terminated. So the contract is:
+//
+//   • pathname === undefined  ⇒  "could this vendor serve ANY path on this host?" (candidacy).
+//     The ambient proxy uses this to decide whether to MITM at all, then re-resolves WITH the
+//     path once the request is decrypted.
+//   • pathname supplied       ⇒  "does this vendor serve THIS path on this host?" (routing).
+//
+// Nearly every predicate ignores the second argument, because nearly every vendor owns its host
+// outright. `www.googleapis.com` is the exception: `googleauth` serves the OAuth2 token exchange
+// there and `youtube` serves the Data API v3 at /youtube/v3/*. Since `resolveTwin` returns the
+// FIRST matching vendor in insertion order, a host-only match would give whichever key is declared
+// first the entire host — silently breaking the other twin whenever both are configured in one
+// world. The two predicates below are therefore mutually exclusive on that host BY PATH.
+//
+// THE SHARED-HOST RULE (Cal.com incident, 2026-08): a shared-host predicate must claim ONLY the
+// paths its twin actually serves — never "the rest of the host". Claiming the remainder is how
+// every `@googleapis/calendar` call (37 methods, all defaulting to www.googleapis.com) was routed
+// into the googleauth/gemini twin and answered with a plausible Google-shaped 404: a mis-route
+// that fails OPEN and PLAUSIBLE, strictly worse than a coverage gap. An UNCLAIMED path on a
+// claimed host is refused LOUDLY instead (see unclaimedTwinnedHostPathMessage below): the error
+// names the host as twinned and the path as belonging to no pack in this world.
+/**
+ * Does this path belong to the OAuth2 token-exchange surface the googleauth twin actually serves?
+ * Exactly the routes gemini-twin.ts §googleauth models: `POST /token` (the oauth2.googleapis.com
+ * path, also answered on the legacy host) and `POST /oauth2/v4/token` (the legacy
+ * www.googleapis.com token path older google-auth-library versions default to). NOTHING else:
+ * /calendar/v3/*, /drive/v3/*, … are other Google products with no twin in this repo, and
+ * claiming them would mis-route those SDKs into an auth twin that answers with vendor-shaped
+ * 404s (the Cal.com incident).
+ */
+// (The `googleauth` matcher itself is DATA on gemini's descriptor — packages/twin/gemini/src/index.ts.)
+
+/**
+ * Does this path belong to Google's user-facing OAuth 2.0 / OIDC surface — the one the
+ * `googleoauth` PACK serves?
+ *
+ * accounts.google.com is NOT an API host: it is Google's whole sign-in web property (the account
+ * chooser, Gmail SSO, security settings, the Workspace admin login). Claiming the host outright
+ * would be the Cal.com mis-route incident again in a much larger blast radius — every Google
+ * sign-in a browser in the world performs would land in a twin that models one protocol. So this
+ * claims EXACTLY the OAuth/OIDC paths the pack serves and refuses the rest LOUDLY
+ * (unclaimedTwinnedHostPathMessage).
+ */
+const isGoogleOAuthConsentPath = (p) =>
+  typeof p === 'string'
+  && (/^\/(o\/oauth2\/v2\/auth(\/oauthchooseaccount)?|o\/oauth2\/auth|o\/oauth2\/token|signin\/oauth\/error|\.well-known\/openid-configuration)\/?$/.test(p)
+    || /^\/_twin\//.test(p));
+// ANCHORED, and `/o/oauth2/auth/oauthchooseaccount` deliberately absent. The first version had no
+// terminal anchor, so `/o/oauth2/tokeninfo`, `/signin/oauth/errorPage` and
+// `/.well-known/openid-configuration.json` were all claimed and all 404 — and its alternation also
+// claimed an UN-VERSIONED chooser path the router does not serve (§9 round two). The claim set is
+// now exactly `AUTH_PATHS` + the three singles + the twin-only prefix.
+// NB `/o/oauth2/revoke` (the legacy revocation alias) is NOT claimed: the pack files it as a todo
+// and its handler 404s it. An injector entry claiming a path the twin then refuses routes real
+// traffic into a twin that cannot serve it — the Cal.com mis-route in miniature, and the reason
+// every claim here is checked against what the router actually answers.
+
+/**
+ * The oauth2.googleapis.com paths the googleoauth PACK serves: the token endpoint (all three
+ * spellings), revocation, and token introspection.
+ */
+const isGoogleOAuthTokenPath = (p) =>
+  typeof p === 'string' && /^\/(token|oauth2\/v4\/token|revoke|tokeninfo|device\/code)\/?$/.test(p);
+// `/device/code` is a DELIBERATE exception to "never claim a path the twin refuses", and the two
+// rules genuinely collide here (§9 round two). The twin's own discovery document advertises
+// `device_authorization_endpoint` — because Google's does, and dropping it would be infidelity — so
+// a discovery-driven client WILL dial it. Unclaimed, that client escapes a sealed world and reaches
+// the real Google; claimed, it gets the twin's honest 404. Containment wins: an unmodelled
+// operation must fail LOCALLY, not succeed remotely.
+
+/**
+ * The www.googleapis.com paths it serves: the v1 (PEM) and v3 (JWK) cert endpoints, and the v3
+ * userinfo alias. NOT `/oauth2/v2/*` — Google publishes no v2 certs endpoint at all, and the v2
+ * userinfo alias returns a DIFFERENT field set the pack does not model
+ * (`googleoauth.endpoints.userinfo_v2`, todo), so its handler refuses it.
+ */
+const isGoogleOAuthApisPath = (p) =>
+  typeof p === 'string' && /^\/oauth2\/(v1\/certs|v3\/(certs|userinfo))\/?$/.test(p);
+
+// vendor → predicate(hostname, pathname?). A vendor is only active if its twin URL is set.
+// THE HAND TABLE'S ONLY RESIDENTS: keys served by KERNEL packages (browser-assets serves
+// `browserassets` and `googlefavicon`; kernel packages carry no pack descriptor) and
+// `googleoauth`, which must precede gemini's `googleauth` key on the shared token host
+// (`resolveTwin` is first-match in insertion order, and this table is inserted before the
+// compiled descriptors below). Every vendor pack's hosts live on its descriptor as DATA —
+// host | suffix | hostPattern, pathPattern, exclude, key — compiled from pack-facts.json.
 const VENDOR_HOSTS = {
-  stripe: (h) => h === 'api.stripe.com',
-  slack: (h) => h === 'slack.com' || h === 'www.slack.com' || h === 'api.slack.com',
-  github: (h) => h === 'api.github.com',
-  jira: (h) => h === 'atlassian.net' || h.endsWith('.atlassian.net'),
-  linear: (h) => h === 'api.linear.app',
-  openrouter: (h) => h === 'openrouter.ai',
-  anthropic: (h) => h === 'api.anthropic.com',
-  clerk: (h) => h === 'api.clerk.com',
-  webrisk: (h) => h === 'webrisk.googleapis.com',
-  resend: (h) => h === 'api.resend.com',
-  sentry: (h) => h === 'sentry.io' || h.endsWith('.ingest.sentry.io'),
-  polar: (h) => h === 'api.polar.sh' || h === 'sandbox-api.polar.sh',
-  elevenlabs: (h) => h === 'api.elevenlabs.io',
-  vital: (h) => h === 'api.tryvital.io' || h === 'api.sandbox.tryvital.io',
-  calcom: (h) => h === 'api.cal.com',
-  openweather: (h) => h === 'api.openweathermap.org',
-  googlemaps: (h) => h === 'maps.googleapis.com',
-  mapbox: (h) => h === 'api.mapbox.com',
-  stream: (h) => h === 'chat.stream-io-api.com',
+  // google-auth-library exchanges a locally-signed JWT here before ANY
+  // Vertex/GCS call — a sealed world must model the exchange or every
+  // service-account flow dies in auth before reaching a modeled API.
+  //
+  // SHARES www.googleapis.com with the `youtube` PACK (whose `hosts` declaration carries the
+  // matching pathPattern): this vendor claims
+  // ONLY the token-exchange paths its twin serves there (`/token`, `/oauth2/v4/token` —
+  // gemini-twin.ts §googleauth; the `googleauth` key on gemini's descriptor). It used to claim "everything that
+  // is not YouTube" on that host, which silently swallowed Google Calendar (`/calendar/v3/*` —
+  // `@googleapis/calendar` defaults every method to www.googleapis.com) and answered it with
+  // plausible Google-shaped 404s from the wrong pack: the Cal.com mis-route incident. Unclaimed
+  // paths on this host now refuse loudly instead (unclaimedTwinnedHostPathMessage). With no
+  // pathname it still claims the host so the ambient proxy MITMs it; the post-decrypt resolve
+  // then routes each request to the right twin — or to the loud refusal.
+  //
+  // GOOGLEOAUTH — the real PACK (@volter/twin-googleoauth), declared BEFORE `googleauth` on purpose.
+  // `resolveTwin` returns the FIRST matching vendor in insertion order, so in a world where BOTH are
+  // configured the token endpoint goes to the pack rather than to the pack-less plumbing key — which
+  // is what you want, because the pack's token endpoint is a strict SUPERSET: it serves
+  // authorization_code and refresh_token (which googleauth has no state for) AND the
+  // jwt-bearer service-account exchange googleauth exists for, with a REAL RS256 id_token instead of
+  // gemini's `alg: none` stub. A world running ONLY the gemini twin still resolves through
+  // `googleauth` below, unchanged.
+  //
+  // FOUR hosts, every one path-scoped, because Google spreads ONE product across them and shares
+  // three of them with other products:
+  //   • accounts.google.com          the consent screen, the error page, OIDC discovery. NOT claimed
+  //                                  outright: this host is Google's entire sign-in web property.
+  //   • oauth2.googleapis.com        token / revoke / tokeninfo. SHARED with `googleauth`.
+  //   • www.googleapis.com           the JWKS + legacy userinfo. SHARED with `googleauth` AND
+  //                                  `youtube`, and disambiguated from both BY PATH.
+  //   • openidconnect.googleapis.com the OIDC userinfo endpoint. Not shared.
+  googleoauth: (h, p) =>
+    (h === 'accounts.google.com' && (p === undefined || isGoogleOAuthConsentPath(p)))
+    || (h === 'oauth2.googleapis.com' && (p === undefined || isGoogleOAuthTokenPath(p)))
+    || (h === 'www.googleapis.com' && (p === undefined || isGoogleOAuthApisPath(p)))
+    || h === 'openidconnect.googleapis.com',
   googlefavicon: (h) => h === 'www.google.com' || h === 'google.com' || h === 't2.gstatic.com',
   browserassets: (h) =>
     h === 'cdnjs.cloudflare.com' ||
@@ -66,22 +171,51 @@ const VENDOR_HOSTS = {
     h === 'www.youtube.com' ||
     h === 'www.youtube-nocookie.com' ||
     h === 'i.ytimg.com',
-  s3: (h) =>
-    h === 's3.amazonaws.com' ||
-    h.endsWith('.s3.amazonaws.com') ||
-    /^s3[.-][a-z0-9-]+\.amazonaws\.com$/.test(h) ||
-    /\.s3[.-][a-z0-9-]+\.amazonaws\.com$/.test(h) ||
-    /^s3\.dualstack\.[a-z0-9-]+\.amazonaws\.com$/.test(h) ||
-    /\.s3\.dualstack\.[a-z0-9-]+\.amazonaws\.com$/.test(h) ||
-    h.endsWith('.s3-accelerate.amazonaws.com') ||
-    h.endsWith('.s3-accelerate.dualstack.amazonaws.com') ||
-    h.endsWith('.r2.cloudflarestorage.com'),
-  // DynamoDB + Timestream are served by the SAME consolidated `aws` twin as s3 (it routes by
-  // X-Amz-Target). Point DYNAMODB_TWIN_URL / TIMESTREAM_TWIN_URL at the aws twin's URL.
-  dynamodb: (h) => /^dynamodb\.[a-z0-9-]+\.amazonaws\.com$/.test(h),
-  timestream: (h) => /(^|\.)(ingest|query)\.timestream\.[a-z0-9-]+\.amazonaws\.com$/.test(h),
 };
 
+// TWIN-PACK-CONTRACT migration: packs now declare their hosts as DATA on their descriptor
+// (`hosts` on TwinPack), compiled into the committed pack-facts artifact — a plain JSON this
+// preloaded, dependency-free module can `require` natively. The hand table above shrinks toward
+// empty as entries move; a vendor present in both homes throws (dual declaration is the drift
+// this migration ends, and a broken checkout should refuse to inject rather than half-route).
+{
+  const { packs } = require('./generated/pack-facts.json');
+  for (const vendor of Object.keys(packs)) {
+    const rules = packs[vendor].hosts;
+    if (!rules || rules.length === 0) continue;
+    if (VENDOR_HOSTS[vendor]) {
+      throw new Error(`inject: vendor "${vendor}" declares hosts on its pack descriptor AND in the hand VENDOR_HOSTS table — one home per fact; delete the hand entry.`);
+    }
+    // Rules group by `key` (default: the vendor id) — an aws descriptor declares the s3 /
+    // dynamodb / … routing identities its consolidated twin answers under; gemini declares
+    // `googleauth`. A key matches when ANY include rule matches AND NO exclude rule matches
+    // (upstashredis: `.upstash.io` minus qstash and the vector hosts).
+    const byKey = new Map();
+    for (const rule of rules) {
+      const key = rule.key === undefined ? vendor : rule.key;
+      if (!byKey.has(key)) byKey.set(key, []);
+      byKey.get(key).push(rule);
+    }
+    for (const [key, keyRules] of byKey) {
+      if (VENDOR_HOSTS[key]) {
+        throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
+      }
+      const compile = (rule) => {
+        const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
+        if (selectors !== 1) throw new Error(`inject: key "${key}" (pack ${vendor}) rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
+        const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
+        const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
+        return (h, p) =>
+          (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
+          && (pathRe === null || p === undefined || pathRe.test(p));
+      };
+      const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
+      const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
+      VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
+    }
+  }
+}
+
 function decodeBase64UrlJson(part) {
   try {
     const padded = String(part).replace(/-/g, '+').replace(/_/g, '/');
@@ -155,10 +289,25 @@ function installClerkFastifyTwinShim() {
 
 installClerkFastifyTwinShim();
 
+// 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 = {};
   for (const vendor of Object.keys(VENDOR_HOSTS)) {
-    const url = env[`${vendor.toUpperCase()}_TWIN_URL`];
+    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
     if (url) map[vendor] = url.replace(/\/$/, '');
   }
   if (env.TWIN_INJECT) {
@@ -173,9 +322,18 @@ function readMap(env) {
   return map;
 }
 
-function resolveTwin(hostname, 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)) return { vendor, origin: map[vendor] };
+    if (map[vendor] && VENDOR_HOSTS[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
   }
   return null;
 }
@@ -201,7 +359,53 @@ function strictEgressEnabled() {
 }
 
 function shouldBlockUntwinned(url) {
-  return strictEgressEnabled() && url && !isLocalOrPrivateHost(url.hostname) && !resolveTwin(url.hostname, MAP);
+  return strictEgressEnabled() && url && !isLocalOrPrivateHost(url.hostname) && !resolveTwin(url.hostname, MAP, url.pathname);
+}
+
+// --- untwinned-host TLS failure naming (local mode) -----------------------------------------
+// A world's activate/shell env points the whole TLS trust story at the session CA:
+// `SSL_CERT_FILE` — which Node honors and which REPLACES the default root store (verified on
+// Node 22: with it set, both https.request and fetch fail EVERY real-vendor chain) — plus
+// `NODE_EXTRA_CA_CERTS`. Twinned hosts never notice: the injector intercepts before TLS, and
+// the ambient proxy serves session-CA leaves. But a Node request to an UNTWINNED host in
+// local mode escapes the injector, reaches the real vendor, and dies with a bare
+// "unable to get local issuer certificate" — while curl (whose CA story the world also
+// scopes, but whose escape hatch differs) sails through to the real vendor. That bare
+// OpenSSL message cost the LibreChat blind-adoption run real time: NAME the situation on the
+// error, exactly where it surfaces (the app's request/fetch rejection).
+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 worldCaSealsTls() {
+  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. (Node TLS trusts only the world session CA here, so the real vendor's certificate fails verification. 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 ---
@@ -237,13 +441,45 @@ function describe(args, defaultProtocol) {
 
 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;
+}
+
+let SESSION_CA = undefined; // lazily read once; NODE_EXTRA_CA_CERTS set after process start
+function sessionCa() {
+  if (SESSION_CA === undefined) {
+    const caPath = process.env.NODE_EXTRA_CA_CERTS;
+    try { SESSION_CA = caPath ? require('fs').readFileSync(caPath) : null; } catch { SESSION_CA = null; }
+  }
+  return SESSION_CA;
+}
+
 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 = Object.assign({}, headers);
+    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,
@@ -251,6 +487,7 @@ function forward(origin, method, fullPath, headers, body) {
       method,
       path: fullPath,
       headers: fwdHeaders,
+      ...(ca ? { ca } : {}),
     }, (res) => {
       const chunks = [];
       res.on('data', (chunk) => chunks.push(chunk));
@@ -295,9 +532,20 @@ function fakeClientRequest(origin, method, fullPath, headers, callback) {
       .then(({ statusCode, headers: resHeaders, body }) => {
         const res = Readable.from([body]);
         res.statusCode = statusCode;
-        res.statusMessage = statusCode >= 400 ? 'Error' : 'OK';
+        // 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 = [];
+        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();
@@ -317,9 +565,29 @@ function fakeClientRequest(origin, method, fullPath, headers, callback) {
   return request;
 }
 
-function blockedClientRequest(hostname) {
+// --- 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(`[twin-inject] blocked untwinned external request to ${hostname}`);
+  const error = new Error(message);
   const socket = new EventEmitter();
   socket.connecting = false;
   socket.setKeepAlive = () => socket;
@@ -355,14 +623,33 @@ 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);
+    const twin = url && resolveTwin(url.hostname, MAP, url.pathname);
     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);
     }
-    if (shouldBlockUntwinned(url)) return blockedClientRequest(url.hostname);
-    return originalRequest.apply(this, args);
+    // 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, 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) && worldCaSealsTls() && 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;
   };
 }
 
@@ -391,23 +678,130 @@ function install(mapOverride) {
       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);
+      const twin = url && resolveTwin(url.hostname, MAP, url.pathname);
       if (!twin) {
+        // 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}`));
-        return originalFetch(input, init);
+        const passthrough = originalFetch(input, 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) && worldCaSealsTls() && passthrough && typeof passthrough.catch === 'function') {
+          const hostname = url.hostname;
+          return passthrough.catch((error) => {
+            annotateUntwinnedTlsError(error, hostname);
+            throw error;
+          });
+        }
+        return passthrough;
       }
-      const target = `${twin.origin}${url.pathname}${url.search}`;
+      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;
       if (reqInit.body === undefined && typeof input === 'object' && input && input.body != null) reqInit.body = input.body;
+      // 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;
+      // S4 review F3: undici's default redirect-follow forwards CUSTOM headers across
+      // origins — a twin answering 30x to an external URL would carry x-twins-key to a
+      // REAL host. Follow ourselves instead: a twin-resolvable hop re-enters this patch
+      // (key re-attached correctly); anything else is fetched WITHOUT the key. The node
+      // path already behaves this way (the SDK sees the 30x and retries through the
+      // patch), so the two rewrite paths now agree.
+      if (twinsKey() && (reqInit.redirect === undefined || reqInit.redirect === 'follow')) {
+        reqInit.redirect = 'manual';
+        const followedFetch = async () => {
+          let hop = await originalFetch(target, reqInit);
+          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 twins key — a twin-resolvable
+            // hop gets the key re-attached by the patch; an external hop stays keyless.
+            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;
+        };
+        return followedFetch();
+      }
+      // 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;
-  for (const vendor of active) {
-    process.stderr.write(`[twin-inject] ${vendor}: redirecting to ${MAP[vendor]}\n`);
+  // 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 };
 }
@@ -423,7 +817,7 @@ function restore() {
   MAP = {};
 }
 
-module.exports = { install, restore, readMap, resolveTwin, VENDOR_HOSTS };
+module.exports = { install, restore, readMap, resolveTwin, twinUrlVendor, twinnedHostVendors, unclaimedTwinnedHostPathMessage, VENDOR_HOSTS };
 
 // Auto-install when loaded as a preload (`--require`). No-op if no twin URLs are set.
 install();