@volter/twin-googleoauth 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+export { ACCOUNTS_ORIGIN, APIS_ORIGIN, discoveryDocument, handleGoogleOAuthTwinRequest, ISSUER, OAUTH2_ORIGIN, OIDC_ORIGIN, } from './googleoauth-twin.js';
+export type { GoogleOAuthRequest, GoogleOAuthResponse } from './googleoauth-twin.js';
+export { createGoogleOAuthConsentServer, createGoogleOAuthTwinFetch, createGoogleOAuthTwinServer, type GoogleOAuthTwinFetchOptions } from './googleoauth-server.js';
+export { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, defaultRedirectUris, RESOURCE_TYPES, redirectUriAllowed, } from './googleoauth-store.js';
+export { atHash, buildJwks, buildLegacyPemCerts, decodeJwt, ensureKeypair, pkceS256, setKeypairGenerator, signJwt, verifyJwtWithJwks, } from './googleoauth-jwt.js';
+export type { Jwk, Jwks } from './googleoauth-jwt.js';
+export { describeScope, describeScopes, formatScopeParam, isGranularlyDeclinable, OIDC_SCOPES, parseScopeParam, SCOPE_CATALOG, sortScopesForConsent, } from './googleoauth-scopes.js';
+export type { ScopeInfo } from './googleoauth-scopes.js';
+export { liveGoogleOAuthExecute, mapTokenInfoClient, mapTokenInfoGrant, mapUserInfoAccount, pullGoogleOAuthIdentity, unpushableGoogleOAuthEntries, syncGoogleOAuthFromReal, } from './googleoauth-connector.js';
+export type { GoogleOAuthExecute, LiveGoogleOAuthOptions } from './googleoauth-connector.js';
+export { GOOGLEOAUTH_BUDGET_CEILING, GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S, GOOGLEOAUTH_BUDGET_WINDOW_MS, GOOGLEOAUTH_CALL_WEIGHTS, GOOGLEOAUTH_RATE_BUDGET, GoogleOAuthBudget, GoogleOAuthBudgetError, googleOAuthBudgetPath, googleOAuthCallWeight, } from './googleoauth-budget.js';
+export type { GoogleOAuthBudgetErrorKind, GoogleOAuthBudgetOptions, GoogleOAuthBudgetReservation, GoogleOAuthBudgetSnapshot, } from './googleoauth-budget.js';
+export { consentPageHtml, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH, errorPageHtml, googleOAuthConsentState, } from './googleoauth-consent-ui.js';
+export type { ConsentAccount, ConsentScopeRow, ConsentView } from './googleoauth-consent-ui.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,102 @@
+// @volter/twin-googleoauth — the Google OAuth 2.0 / OpenID Connect twin (one vendor, one package),
+// built on the shared @volter/world-core kernel.
+//
+// The catalog's first BROWSER-FACING pack: it serves the vendor's own consent screen as HTML at
+// accounts.google.com's real path, completes the full authorization-code round trip (consent → 302
+// with code+state → redemption at the token endpoint → refresh), and mints REAL RS256 id_tokens
+// verifiable against the JWKS it serves. Conformance tooling lives in @volter/world-tooling (a dev
+// dependency) — not shipped in the runtime API.
+export { ACCOUNTS_ORIGIN, APIS_ORIGIN, discoveryDocument, handleGoogleOAuthTwinRequest, ISSUER, OAUTH2_ORIGIN, OIDC_ORIGIN, } from "./googleoauth-twin.js";
+export { createGoogleOAuthConsentServer, createGoogleOAuthTwinFetch, createGoogleOAuthTwinServer } from "./googleoauth-server.js";
+export { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, defaultRedirectUris, RESOURCE_TYPES, redirectUriAllowed, } from "./googleoauth-store.js";
+export { atHash, buildJwks, buildLegacyPemCerts, decodeJwt, ensureKeypair, pkceS256, setKeypairGenerator, signJwt, verifyJwtWithJwks, } from "./googleoauth-jwt.js";
+export { describeScope, describeScopes, formatScopeParam, isGranularlyDeclinable, OIDC_SCOPES, parseScopeParam, SCOPE_CATALOG, sortScopesForConsent, } from "./googleoauth-scopes.js";
+export { liveGoogleOAuthExecute, mapTokenInfoClient, mapTokenInfoGrant, mapUserInfoAccount, pullGoogleOAuthIdentity, unpushableGoogleOAuthEntries, syncGoogleOAuthFromReal, } from "./googleoauth-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveGoogleOAuthExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is this vendor's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `GoogleOAuthBudgetError` by type; there is deliberately no export that disables the guard.
+export { GOOGLEOAUTH_BUDGET_CEILING, GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S, GOOGLEOAUTH_BUDGET_WINDOW_MS, GOOGLEOAUTH_CALL_WEIGHTS, GOOGLEOAUTH_RATE_BUDGET, GoogleOAuthBudget, GoogleOAuthBudgetError, googleOAuthBudgetPath, googleOAuthCallWeight, } from "./googleoauth-budget.js";
+export { consentPageHtml, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH, errorPageHtml, googleOAuthConsentState, } from "./googleoauth-consent-ui.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { GOOGLEOAUTH_RATE_BUDGET as RATE_BUDGET } from "./googleoauth-budget.js";
+import { performGoogleOAuthAction, syncGoogleOAuthFromRemote } from "./googleoauth-connector.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+    // state system. Moved 2026-09-08. NOTHING here can cross: Google publishes no API that creates an OAuth
+    // client, seeds a user or grants a scope — those are Cloud Console and myaccount.google.com actions a
+    // person takes in a browser — so `perform` settles every entry with that reason and only `refresh` reads.
+    protocol: '2',
+    refresh: { every: '30m', onDemand: { atMost: '60s' } },
+    stateSystem: { perform: performGoogleOAuthAction, refresh: syncGoogleOAuthFromRemote },
+    // the round trip registers an OAuth client through the twin's own door, because the vendor has no API for
+    // it at all — which is the same reason `perform` never crosses
+    roundTrip: { method: 'POST', path: '/_twin/clients', body: { client_id: 'round-trip.apps.googleusercontent.com', name: 'Round Trip', redirect_uris: ['https://round.trip.test/callback'] } },
+    parityOrigin: 'http://twin',
+    // shapeParity is NOT held, for a structural reason rather than a divergence: the refresh reads the ACCOUNT
+    // this credential names (its identity and granted scopes) — there is no listing of OAuth clients to
+    // observe back, because Google publishes none. Written and observed are different subjects by design.
+    vendor: 'googleoauth',
+    // The SAME object googleoauth-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-googleoauth',
+    resources: ['oauth_client', 'account', 'auth_request', 'authorization_code', 'access_token', 'refresh_token', 'grant'],
+    specSource: 'accounts.google.com/.well-known/openid-configuration (the vendor\'s own OIDC discovery document) '
+        + '+ developers.google.com/identity/protocols/oauth2/{web-server,native-app,openid-connect,service-account}',
+    description: 'Google OAuth 2.0 / OIDC twin — the real consent screen as HTML, the full authorization-code '
+        + 'round trip (PKCE S256, state, granular consent, refresh), real RS256 id_tokens and a real JWKS.',
+    // Adoption, all in the pack's one home (descriptor-first back-migration, adding-a-twin.md §3, 2026-08-31;
+    // `google-auth-library` and the bare `google`/`googleoauth`/`googleoidc` stems moved off the
+    // central maps unchanged).
+    //
+    // `google-auth-library` is the class every Google client builds its auth on (googleapis,
+    // @googleapis/*, @google-cloud/*), and it is the package an app adds when it does three-legged
+    // OAuth itself. `openid-client` is deliberately NOT claimed: it is a third-party generic OIDC
+    // library (panva), not a Google client, and claiming it would say any OIDC provider is this twin.
+    //
+    // GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REDIRECT_URI stem to `google` and are the
+    // OAuth-app credential shape — the exact vars the Cal.com blind-adoption run dropped nine of
+    // before _CLIENT_ID/_CLIENT_SECRET became strict suffixes (covers.ts's ENV_SUFFIX_STRICT). NB the
+    // `google-auth-library` package does NOT itself read these (it reads GOOGLE_APPLICATION_
+    // CREDENTIALS); apps set them and pass them to the constructor, which is exactly why the ENV
+    // signal and the SDK signal are separate and both worth having. The rest are the credential-var
+    // stems real apps use for sign-in-with-Google.
+    //
+    // NOTE: this pack's injector rule stays in the hand VENDOR_HOSTS table, and that is a ROUTING
+    // constraint, not an omission. It shares oauth2.googleapis.com and www.googleapis.com with the
+    // pack-less `googleauth` plumbing key, and it is 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 (whose endpoint is a strict SUPERSET —
+    // authorization_code and refresh_token, which googleauth has no state for, PLUS the jwt-bearer
+    // service-account exchange, with a REAL RS256 id_token instead of gemini's `alg: none` stub).
+    // Descriptor-declared hosts are appended AFTER the whole hand table, so moving this entry alone
+    // would flip that precedence. It can move once `googleauth` has a home of its own.
+    adoption: {
+        // Google's official auth libraries - the Python counterparts of `google-auth-library`: token
+        // minting/refresh against oauth2.googleapis.com and the installed-app OAuth flow.
+        // `google-api-python-client` is deliberately UNCLAIMED: it is the generic multi-service Google
+        // API client (Drive, Sheets, YouTube, ...) whose calls go to whichever API the caller names,
+        // not to this pack's OAuth endpoints - claiming it here would map every Google-anything repo
+        // onto the OAuth twin.
+        pypi: ['google-auth', 'google-auth-oauthlib'],
+        sdks: ['google-auth-library', '@googleapis/oauth2'],
+        envStems: [
+            'GOOGLE', 'GOOGLEOAUTH', 'GOOGLEOIDC',
+            'AUTHGOOGLE', 'AUTHGOOGLEOAUTH2', 'BACKENDGOOGLE', 'GOOGLEIOS',
+            'GOOGLELOGIN', 'GOOGLEWEB', 'NEXTPRIVATEGOOGLE', 'SSOGOOGLEOAUTH2',
+            // appsmith's Google OAuth app: APPSMITH_OAUTH2_GOOGLE_CLIENT_ID/_SECRET — the same
+            // app-prefixed shape as AUTHGOOGLEOAUTH2 / SSOGOOGLEOAUTH2 (ladder classification 2026-09-02).
+            'APPSMITHOAUTH2GOOGLE',
+        ],
+    },
+    // A browser is REDIRECTED to accounts.google.com — there is no single API path prefix to proxy,
+    // so the loader host is the consent host and the prefix is the OAuth path root.
+    browserRouting: { apiPathPrefix: '/o/oauth2/', loaderHost: 'https://accounts.google.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@volter/twin-googleoauth",
+  "version": "0.1.0",
+  "description": "Local Google OAuth 2.0 / OpenID Connect twin — the real consent screen, the real authorization-code round trip, and real RS256 id_tokens an unmodified OAuth client library completes a full flow against. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "oauth",
+    "oauth2",
+    "openid-connect",
+    "oidc",
+    "google",
+    "consent",
+    "sign-in-with-google"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/googleoauth"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/googleoauth#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-googleoauth": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "google-auth-library": "^9.15.1",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-googleoauth CLI: serve the Google OAuth 2.0 / OIDC twin, or run conformance.
+//
+// `serve` and `mirror` start the SAME server, because the consent screen is served by the twin at
+// the vendor's own path — there is no second renderer to start. `mirror` additionally prints a
+// ready-to-open authorization URL, which is the thing an operator actually wants when they ask to
+// "see the UI".
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createGoogleOAuthTwinServer } from './googleoauth-server.ts';
+import { DEFAULT_CLIENT_ID, defaultRedirectUris } from './googleoauth-store.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === 'mirror') {
+  const s = await createGoogleOAuthTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  const origin = `http://127.0.0.1:${s.port}`;
+  process.stdout.write(`googleoauth twin (OAuth 2.0 / OIDC)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
+  if (cmd === 'mirror') {
+    const url = new URL(`${origin}/o/oauth2/v2/auth`);
+    url.searchParams.set('client_id', DEFAULT_CLIENT_ID);
+    url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]!);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', 'openid email profile https://www.googleapis.com/auth/calendar.readonly');
+    url.searchParams.set('state', 'twin-demo-state');
+    url.searchParams.set('access_type', 'offline');
+    process.stdout.write(`consent screen: ${url.toString()}\n`);
+  }
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkGoogleOAuthConformance } = await import('./googleoauth-conformance.ts');
+  const report = await checkGoogleOAuthConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-googleoauth serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/googleoauth-autherror.ts

@@ -0,0 +1,150 @@
+// Google's OAuth ERROR-PAGE mechanism, reproduced.
+//
+// THE FACT THIS FILE EXISTS FOR: when Google's authorization endpoint rejects a request for a
+// configuration or parameter reason, it does NOT answer with an HTML body and it does NOT redirect
+// to the caller's `redirect_uri`. It 302s to ITS OWN error page:
+//
+//   https://accounts.google.com/signin/oauth/error
+//     ?authError=<base64url protobuf>&flowName=GeneralOAuthFlow&client_id=<id>
+//
+// and that page renders "Access blocked: …" plus the "Error <status>: <code>" line every integrator
+// ends up searching for. The `authError` payload is a base64url-encoded protobuf with five fields:
+//
+//   1 (string) the OAuth error code          e.g. "redirect_uri_mismatch"
+//   2 (string) the human message             e.g. "The OAuth client was not found."
+//   3 (string) a documentation URL
+//   4 (varint) the HTTP status the page names e.g. 401
+//   5 (string) the echoed parameter           e.g. "redirect_uri=https://evil.test/steal"
+//
+// Reproducing the REDIRECT (rather than serving HTML inline) is what makes the twin's browser
+// behaviour match: the address bar changes to accounts.google.com/signin/oauth/error, which is
+// exactly what a developer sees and screenshots when they file a bug.
+//
+// Grounded by a read-only live capture of the real endpoint on 2026-08-20 (the field numbering was
+// decoded from real `authError` payloads); recorded in spec-sources.json.
+//
+// UNCONFIRMED, and therefore not asserted anywhere: the HTTP STATUS the rendered error page itself
+// is served with. The status in field 4 is the one the page DISPLAYS. The twin serves the page as a
+// normal 200 document and puts the status in the text, which is what the capture shows the page
+// saying; `googleoauth.errors.error_page_http_status` is the filed todo.
+
+export const ERROR_PAGE_PATH = '/signin/oauth/error';
+/** Google puts this on every OAuth error-page URL; a real capture always carries it. */
+export const FLOW_NAME = 'GeneralOAuthFlow';
+
+export type AuthError = {
+  /** The OAuth error code (protobuf field 1). */
+  code: string;
+  /** The human-readable message (field 2). */
+  message: string;
+  /** The documentation URL Google links (field 3). */
+  docUrl?: string;
+  /** The HTTP status the page NAMES in its "Error <status>: <code>" line (field 4). */
+  status: number;
+  /** The offending parameter, echoed back (field 5). */
+  param?: string;
+};
+
+function varint(n: number): number[] {
+  const out: number[] = [];
+  let v = n;
+  while (v > 0x7f) {
+    out.push((v & 0x7f) | 0x80);
+    v >>>= 7;
+  }
+  out.push(v);
+  return out;
+}
+
+function stringField(field: number, value: string): number[] {
+  const bytes = Array.from(Buffer.from(value, 'utf8'));
+  return [(field << 3) | 2, ...varint(bytes.length), ...bytes];
+}
+
+/** Encode an AuthError as the base64url protobuf Google puts in `?authError=`. */
+export function encodeAuthError(e: AuthError): string {
+  const out: number[] = [
+    ...stringField(1, e.code),
+    ...stringField(2, e.message),
+    ...(e.docUrl ? stringField(3, e.docUrl) : []),
+    (4 << 3) | 0,
+    ...varint(e.status),
+    ...(e.param ? stringField(5, e.param) : []),
+  ];
+  return Buffer.from(Uint8Array.from(out)).toString('base64url');
+}
+
+/** Decode a `?authError=` payload back into its fields. Returns null on anything unparseable. */
+export function decodeAuthError(encoded: string): AuthError | null {
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(encoded, 'base64url');
+  } catch {
+    return null;
+  }
+  const out: Partial<AuthError> = {};
+  let i = 0;
+  const readVarint = (): number => {
+    let result = 0;
+    let shift = 0;
+    while (i < buf.length) {
+      const byte = buf[i++]!;
+      result |= (byte & 0x7f) << shift;
+      if ((byte & 0x80) === 0) return result >>> 0;
+      shift += 7;
+      if (shift > 28) return -1;
+    }
+    return -1;
+  };
+  while (i < buf.length) {
+    const tag = readVarint();
+    if (tag < 0) return null;
+    const field = tag >>> 3;
+    const wire = tag & 7;
+    if (wire === 0) {
+      const value = readVarint();
+      if (value < 0) return null;
+      if (field === 4) out.status = value;
+    } else if (wire === 2) {
+      const len = readVarint();
+      if (len < 0 || i + len > buf.length) return null;
+      const value = buf.subarray(i, i + len).toString('utf8');
+      i += len;
+      if (field === 1) out.code = value;
+      else if (field === 2) out.message = value;
+      else if (field === 3) out.docUrl = value;
+      else if (field === 5) out.param = value;
+    } else {
+      return null; // a wire type Google's payload never uses
+    }
+  }
+  if (!out.code || out.message === undefined || out.status === undefined) return null;
+  return out as AuthError;
+}
+
+/** The full error-page URL an authorization request is bounced to. */
+export function authErrorRedirect(origin: string, e: AuthError, clientId?: string): string {
+  const url = new URL(`${origin}${ERROR_PAGE_PATH}`);
+  url.searchParams.set('authError', encodeAuthError(e));
+  url.searchParams.set('flowName', FLOW_NAME);
+  if (clientId) url.searchParams.set('client_id', clientId);
+  return url.toString();
+}
+
+/** The two headline strings Google's error pages use, chosen by error code (captured verbatim). */
+export function errorHeadline(code: string): string {
+  // `redirect_uri_mismatch` is an app-configuration failure, and Google words it as one; every
+  // other code lands on the generic authorization-error headline.
+  return code === 'redirect_uri_mismatch'
+    ? "Access blocked: This app's request is invalid"
+    : 'Access blocked: Authorization Error';
+}
+
+/** Google's documentation URLs, per error code (captured from real `authError` payloads). */
+export const ERROR_DOC_URLS: Record<string, string> = {
+  redirect_uri_mismatch: 'https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation',
+  invalid_client: 'https://developers.google.com/identity/protocols/oauth2',
+  invalid_request: 'https://developers.google.com/identity/protocols/oauth2/web-server',
+  invalid_scope: 'https://developers.google.com/identity/protocols/oauth2/scopes',
+  unsupported_response_type: 'https://developers.google.com/identity/protocols/oauth2/web-server',
+};

package/src/googleoauth-budget.ts

@@ -0,0 +1,147 @@
+// Google OAuth's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin
+// typed bindings `liveGoogleOAuthExecute` uses. The MECHANISM — the durable token-keyed ledger, the
+// rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt
+// ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that
+// module's header for the full rationale AND for the honest list of what the guard does not
+// guarantee (an injected clock or ledger path still defeats it — it guards carelessness, not
+// malice).
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// GOOGLE PUBLISHES NO SCALAR PER-MINUTE RATE LIMIT for its OAuth 2.0 endpoints. That is the
+// honest finding, and it is the reason this declaration is NOT more permissive than the kernel's
+// undeclared fallback. What Google DOES publish about these endpoints is quota of a different
+// SHAPE entirely — per-user/per-client TOKEN COUNTS, not a request rate:
+//   • a Google Account can hold at most 100 refresh tokens per OAuth client; minting the 101st
+//     silently invalidates the oldest (developers.google.com/identity/protocols/oauth2, "Refresh
+//     token expiration");
+//   • a testing-mode app's refresh tokens expire after 7 days;
+//   • a client has a cap on unexpired refresh tokens across all users.
+// None of those is a per-minute rate, so none of them can anchor a rolling-window ceiling — and
+// dressing one up as one would be exactly the "never a guess presented as a vendor fact" failure
+// ADDING_A_TWIN.md warns about. The ceiling therefore sits AT the kernel fallback's burst (30 calls
+// a minute at the default weight), which is also why this pack needs no `VENDOR_BURST_ANCHOR`
+// entry in scripts/rate-budget-isolation.test.ts.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (a judgement call, stated as one) ────────────────────────────
+// The connector only ever READS (there is no OAuth write API — see the connector header), so every
+// call is a read and every read costs the same 2. Exactly ONE call is priced up:
+//   • `POST /revoke` costs 10. Revocation is the one destructive thing this surface can do to a
+//     real account, and it takes the WHOLE grant with it (every access and refresh token AND the
+//     grant record for that client+user). A loop that revokes is a loop that logs a human out of an
+//     app, which is a human blast radius rather than a throttle.
+// There is deliberately NO second rule. An earlier version carried `^GET /tokeninfo` at the DEFAULT
+// weight "so the rule exists to be found and re-priced" — but a rule whose weight equals the default
+// changes nothing and CANNOT BE PINNED: delete it and every assertion about it still passes, because
+// the fallback returns the same number (§9 round two). A rule no test can lose is not a rule; if
+// tokeninfo ever needs a different price, the rule arrives WITH the number that makes it testable.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'googleoauth';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const GOOGLEOAUTH_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s = 30 calls a minute at the default weight —
+ * EXACTLY the kernel fallback's burst, because Google publishes no rate this could be measured
+ * against. See the header.
+ */
+export const GOOGLEOAUTH_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is judged vs. documented. */
+export const GOOGLEOAUTH_CALL_WEIGHTS = {
+  /** `POST /revoke` — destroys a whole grant on a REAL account. The only destructive call here. */
+  revoke: 10,
+  /** Everything else: discovery, certs, userinfo, tokeninfo. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Google-specific thing in the whole budget. */
+export const GOOGLEOAUTH_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: GOOGLEOAUTH_BUDGET_WINDOW_MS,
+  ceiling: GOOGLEOAUTH_BUDGET_CEILING,
+  defaultWeight: GOOGLEOAUTH_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [{ match: '^POST /revoke$', weight: GOOGLEOAUTH_CALL_WEIGHTS.revoke }],
+  reason:
+    'Google publishes NO scalar per-minute rate limit for its OAuth 2.0 / OIDC endpoints '
+    + '(accounts.google.com, oauth2.googleapis.com, www.googleapis.com/oauth2/*). What it does '
+    + 'publish for this surface is quota of a different SHAPE — per-user/per-client TOKEN COUNTS, '
+    + 'not a request rate: at most 100 refresh tokens per Google Account per OAuth client (the '
+    + '101st silently invalidates the oldest), a 7-day refresh-token expiry for apps still in '
+    + 'testing status, and a per-client cap on unexpired refresh tokens '
+    + '(developers.google.com/identity/protocols/oauth2, "Refresh token expiration"). A token-count '
+    + 'cap cannot anchor a rolling-window rate, so this declaration does NOT claim it does and does '
+    + "NOT out-burst the kernel's undeclared fallback: 60 weighted units / 60s at defaultWeight 2 is "
+    + '30 calls a minute, exactly the fallback. POST /revoke costs 10 (it destroys the WHOLE grant '
+    + 'on a real account — every access and refresh token for that client+user — which is a human '
+    + 'blast radius, not a throttle). It is the ONLY rule: a rule at the default weight changes no '
+    + 'price and cannot be pinned by any test, so there is none. That price is a judgement call, not '
+    + 'a published cost. The window bounds the 60s AVERAGE and does not pace; the 429 / Retry-After '
+    + 'cooldown is the backstop for a sub-second burst.',
+};
+
+// Declared at module load, so merely importing this module (which `googleoauth-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, GOOGLEOAUTH_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/revoke')` really does issue the destructive call and must be priced as one.
+ */
+export function googleOAuthCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to opt
+ *  into world-scoped accounting. */
+export function googleOAuthBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type GoogleOAuthBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not an
+ * alias, so `budget instanceof GoogleOAuthBudget` means "a budget that accounts against
+ * GOOGLEOAUTH's ledger under GOOGLEOAUTH's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable there.
+ */
+export class GoogleOAuthBudget extends RateBudget {
+  constructor(opts: GoogleOAuthBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as GoogleOAuthBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as GoogleOAuthBudgetErrorKind } from '@volter/world-core';
+export type GoogleOAuthBudgetReservation = RateBudgetReservation;
+export type GoogleOAuthBudgetSnapshot = RateBudgetSnapshot;