@volter/twin-googleoauth 0.1.0

package/src/index.ts

@@ -0,0 +1,175 @@
+// @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.ts';
+export type { GoogleOAuthRequest, GoogleOAuthResponse } from './googleoauth-twin.ts';
+export { createGoogleOAuthConsentServer, createGoogleOAuthTwinFetch, createGoogleOAuthTwinServer, type GoogleOAuthTwinFetchOptions } from './googleoauth-server.ts';
+export {
+  DEFAULT_ACCOUNTS,
+  DEFAULT_CLIENT_ID,
+  DEFAULT_CLIENT_SECRET,
+  defaultRedirectUris,
+  RESOURCE_TYPES,
+  redirectUriAllowed,
+} from './googleoauth-store.ts';
+export {
+  atHash,
+  buildJwks,
+  buildLegacyPemCerts,
+  decodeJwt,
+  ensureKeypair,
+  pkceS256,
+  setKeypairGenerator,
+  signJwt,
+  verifyJwtWithJwks,
+} from './googleoauth-jwt.ts';
+export type { Jwk, Jwks } from './googleoauth-jwt.ts';
+export {
+  describeScope,
+  describeScopes,
+  formatScopeParam,
+  isGranularlyDeclinable,
+  OIDC_SCOPES,
+  parseScopeParam,
+  SCOPE_CATALOG,
+  sortScopesForConsent,
+} from './googleoauth-scopes.ts';
+export type { ScopeInfo } from './googleoauth-scopes.ts';
+export {
+  liveGoogleOAuthExecute,
+  mapTokenInfoClient,
+  mapTokenInfoGrant,
+  mapUserInfoAccount,
+  pullGoogleOAuthIdentity,
+  unpushableGoogleOAuthEntries,
+  syncGoogleOAuthFromReal,
+} from './googleoauth-connector.ts';
+export type { GoogleOAuthExecute, LiveGoogleOAuthOptions } from './googleoauth-connector.ts';
+// 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.ts';
+export type {
+  GoogleOAuthBudgetErrorKind,
+  GoogleOAuthBudgetOptions,
+  GoogleOAuthBudgetReservation,
+  GoogleOAuthBudgetSnapshot,
+} from './googleoauth-budget.ts';
+export {
+  consentPageHtml,
+  CONSENT_SCRIPT_PATH,
+  CONSENT_STYLE_PATH,
+  errorPageHtml,
+  googleOAuthConsentState,
+} from './googleoauth-consent-ui.ts';
+export type { ConsentAccount, ConsentScopeRow, ConsentView } from './googleoauth-consent-ui.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { GOOGLEOAUTH_RATE_BUDGET as RATE_BUDGET } from './googleoauth-budget.ts';
+import { performGoogleOAuthAction, syncGoogleOAuthFromRemote } from './googleoauth-connector.ts';
+
+export const pack: TwinPack = {
+  // 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);