@volter/world-core 2.0.36 → 3.0.0

package/dist/vendor-hosts.cjs

@@ -13,124 +13,19 @@
 //     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 (all of its methods default 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/* (the googlecalendar pack's), /drive/v3/*, … are other Google products, 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, the v3
- * userinfo alias, and the OAuth2 API v2's userinfo (`/oauth2/v2/userinfo` and its `/userinfo/v2/me`
- * alias, a different field set: `googleoauth.endpoints.userinfo_v2`), which `@googleapis/oauth2`
- * calls (Cal.com's Google Calendar callback). NOT `/oauth2/v2/certs`: Google publishes no v2 certs
- * endpoint at all.
- */
-const isGoogleOAuthApisPath = (p) =>
-  typeof p === 'string' && /^\/(oauth2\/(v1\/certs|v3\/(certs|userinfo)|v2\/userinfo)|userinfo\/v2\/me)\/?$/.test(p);
+// Where two packs share a host (www.googleapis.com: googleoauth's /oauth2/*, googlecalendar's
+// /calendar/v3), each claims ONLY the paths its twin serves, never "the rest of the host": a pack
+// claiming the remainder answers another product's SDK with plausible vendor-shaped 404s, 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: the error names the host as twinned and the path as
+// belonging to no pack in this world.
 
 // 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.
+// `browserassets` and `googlefavicon`; kernel packages carry no pack descriptor). 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' ||
@@ -149,23 +44,29 @@ const VENDOR_HOSTS = {
     h === 'i.ytimg.com',
 };
 
-// descriptor-first migration (adding-a-twin.md §3): packs now declare their hosts as DATA on their descriptor
+// descriptor-first migration (architecture.md, "The descriptor"): 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');
+/** The keys each pack's compiled rules answer under, by vendor: a pack's own facts learned later (addPackHosts) replace
+ *  that vendor's rules, never another's. */
+const COMPILED = new Map();
+/** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
+ *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
+const HAND = new Set(Object.keys(VENDOR_HOSTS));
+function compilePackHosts(packs, overlay) {
   for (const vendor of Object.keys(packs)) {
     const rules = packs[vendor].hosts;
     if (!rules || rules.length === 0) continue;
-    if (VENDOR_HOSTS[vendor]) {
+    for (const key of COMPILED.get(vendor) || []) delete VENDOR_HOSTS[key];
+    COMPILED.delete(vendor);
+    if (VENDOR_HOSTS[vendor] && !(overlay && HAND.has(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).
+    // Rules group by `key` (default: the vendor id) — aws's descriptor declares the s3 and
+    // secretsmanager routing identities its twin answers under. A key matches when ANY include
+    // rule matches AND NO exclude rule matches.
     const byKey = new Map();
     for (const rule of rules) {
       const key = rule.key === undefined ? vendor : rule.key;
@@ -173,7 +74,7 @@ const VENDOR_HOSTS = {
       byKey.get(key).push(rule);
     }
     for (const [key, keyRules] of byKey) {
-      if (VENDOR_HOSTS[key]) {
+      if (VENDOR_HOSTS[key] && !(overlay && HAND.has(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) => {
@@ -188,9 +89,19 @@ const VENDOR_HOSTS = {
       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));
+      COMPILED.set(vendor, [...(COMPILED.get(vendor) || []), key]);
     }
   }
 }
+{
+  const facts = require('./pack-facts.cjs').packFacts();
+  const installed = new Set(facts.installed || []);
+  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => !installed.has(vendor))), false);
+  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => installed.has(vendor))), true);
+}
+/** Rules from packs' facts learned after this module loaded (a runtime told the facts of the World it boots): each
+ *  vendor's replace its earlier rules. */
+function addPackHosts(packs) { compilePackHosts(packs || {}, true); }
 
 /** Whether any vendor's host rule names `host` (at the host level, whatever the path), whether or not its twin runs. */
 function isVendorHost(host) {
@@ -204,7 +115,7 @@ function vendorsOfHost(host) {
   return Object.keys(VENDOR_HOSTS).filter((vendor) => VENDOR_HOSTS[vendor](h));
 }
 
-/** A vendor key's env stem: `S3_TWIN_URL` is s3's; `googleauth` → GOOGLEAUTH. */
+/** A vendor key's env stem: `S3_TWIN_URL` is s3's; `browserassets` → BROWSERASSETS. */
 function twinEnvStem(vendor) {
   return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
 }
@@ -230,4 +141,4 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+module.exports = { VENDOR_HOSTS, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/dist/vendor-hosts.d.cts

@@ -0,0 +1,8 @@
+/** A vendor's host rule: whether a request to `hostname` (and, where the vendor shares a host, `pathname`) is its. */
+export type HostRule = (hostname: string, pathname?: string) => boolean;
+export const VENDOR_HOSTS: Record<string, HostRule>;
+export function isVendorHost(hostname: string): boolean;
+export function vendorsOfHost(hostname: string): string[];
+export function twinEnvStem(vendor: string): string;
+/** The vendors whose twin `env` points at, each with its origin. */
+export function twinOrigins(env: Readonly<Record<string, string | undefined>>): Record<string, string>;