@volter/world-core 2.0.0

package/vendor-hosts.cjs

@@ -0,0 +1,200 @@
+'use strict';
+// THE VENDOR HOST TABLE — which vendor's twin serves a hostname (and, where two vendors share a host, which path), the
+// one home of that fact in a process, dependency-free and side-effect free. The injector (inject.cjs) routes by it; the
+// application route (app-route.cjs) never answers a name it gives a vendor, in the injector or in a twin's delivery.
+// Moved out of inject.cjs unchanged (2026-09-27).
+// ── 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 = {
+  // 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' ||
+    h === 'www.googletagmanager.com' ||
+    h === 'www.google-analytics.com' ||
+    h === 'connect.facebook.net' ||
+    h === 'snap.licdn.com' ||
+    h === 'px.ads.linkedin.com' ||
+    h === 'static.hotjar.com' ||
+    h === 'fonts.googleapis.com' ||
+    h === 'fonts.gstatic.com' ||
+    h === 'api.fontshare.com' ||
+    h === 'images.subscribe.dev' ||
+    h === 'www.youtube.com' ||
+    h === 'www.youtube-nocookie.com' ||
+    h === 'i.ytimg.com',
+};
+
+// descriptor-first migration (adding-a-twin.md §3): 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
+    // (upstash: `.upstash.io` minus 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));
+    }
+  }
+}
+
+/** Whether any vendor's host rule names `host` (at the host level, whatever the path), whether or not its twin runs. */
+function isVendorHost(host) {
+  const h = String(host || '').toLowerCase().replace(/\.$/, '');
+  return Object.keys(VENDOR_HOSTS).some((vendor) => VENDOR_HOSTS[vendor](h));
+}
+
+module.exports = { VENDOR_HOSTS, isVendorHost };