@volter/twin-googleoauth 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# @volter/twin-googleoauth
+
+A local, stateful, vendor-faithful twin of **Google OAuth 2.0 / OpenID Connect** — the consent
+screen, the full authorization-code round trip, and real RS256 `id_token`s. Point an unmodified
+OAuth client library at it and complete a whole sign-in flow offline.
+
+```bash
+bun run packages/twin/googleoauth/src/cli.ts mirror
+# googleoauth twin (OAuth 2.0 / OIDC) at http://127.0.0.1:54321
+# consent screen: http://127.0.0.1:54321/o/oauth2/v2/auth?client_id=…&redirect_uri=…
+```
+
+## The catalog's first browser-facing pack
+
+Every other twin in this repo answers a **machine**. This one answers a **human**.
+
+The authorization-code flow is *defined* by a browser redirect: the app sends a person to
+`accounts.google.com`, that person reads what is being asked and decides, and the browser is bounced
+back with a code. A twin that skipped the screen and 302'd straight back with a code would not be a
+twin of Google OAuth — it would be a **bypass**, and every bug that lives in the consent leg would
+become invisible: an unregistered `redirect_uri`, a dropped `state`, a scope the user unticked, a
+refresh token that never arrived because `access_type` was `online`.
+
+So the twin **serves HTML at the vendor's real path**. The screen is server-rendered from the
+twin's own kernel projection by the **same React components** the browser bundle ships
+(`client/googleoauth-consent.tsx` + `src/googleoauth-consent-ui.ts`) — one renderer, so API↔UI
+parity cannot drift. The whole flow is plain `<form>` submits: **no JavaScript is required to
+complete an OAuth round trip** against this twin. The bundle only adds the granular-consent
+"Select all" pill into a slot that is empty server-side. The bundle and stylesheet the twin serves
+are **committed text** (`src/googleoauth-consent-client.gen.ts`, written from `client/` by
+`bun scripts/consent-clients.ts` and drift-gated by `scripts/consent-clients.test.ts`): the serve path
+reads constants and never runs a bundler.
+
+**This is the vendor's own product UI, not a dashboard mirror** — but the mirror *discipline* applies
+in full. Every UI capability is data-coupled to real twin state, the screens are driven by a
+Playwright journey (`googleoauth-journey.uitest.ts`), and the mutation gate sabotages the screen's
+state builder in an isolated phase.
+
+## Coverage
+
+Partial and honest. The manifest (`src/googleoauth-capabilities.ts`) is the **real vendor surface**
+as the denominator — authored top-down from Google's own OIDC discovery document and the four
+first-party protocol guides, **not** from what the twin has built. It currently reads
+**113 done / 164 total** (51 `todo`). The `todo`s are real Google surface this twin
+does not model, most notably the whole **Google Identity Services** product (One Tap, the
+Sign in with Google button, `initTokenClient`/`initCodeClient`), the **device / limited-input flow**,
+the **implicit and hybrid** response types, and **RISC** cross-account protection.
+
+### What is real here
+
+- **The complete authorization-code round trip.** Authorization request → account chooser → consent
+  screen → 302 to `redirect_uri` with `code`+`state`+`scope` → the code is redeemable **exactly
+  once** at the token endpoint → `refresh_token` grant. Consent, redemption and refresh are all
+  served by **one pack against one state root**, so the code minted at the screen is honoured at the
+  token endpoint by construction.
+- **Real crypto.** The `id_token` is a genuine RS256 JWT signed by an RSA-2048 keypair generated on
+  first use and **persisted in kernel state**, whose public half the twin serves at
+  `/oauth2/v3/certs`. `google-auth-library`'s own `verifyIdToken` fetches that JWKS and verifies the
+  signature, issuer, audience and expiry itself. (The `clerk` precedent: real crypto or nothing.)
+- **PKCE** `S256` and `plain`, verified with real SHA-256; the transform is pinned against RFC 7636
+  Appendix B's published test vector.
+- **Exact redirect-URI matching**, with the documented loopback-IP port exception — and *only* that
+  exception. `localhost` and `127.0.0.1` are different registrations, and a trailing slash is a
+  different URI. The most common Google integration bug is only reproducible if the twin is as
+  strict as the vendor.
+- **Granular consent** and **incremental authorization**: a user can untick individual product
+  scopes, and the grant carries only what survived — a decline genuinely *removes* the scope, so a
+  later `include_granted_scopes=true` cannot resurrect it. The checkbox screen appears only under
+  Google's documented rule (a sign-in scope mixed with a product one, or two or more product
+  scopes), so a single-scope request is all-or-nothing exactly as it is in production.
+- **Google's real error-page behaviour** (see below).
+- **The service-account grant** (`urn:ietf:params:oauth:grant-type:jwt-bearer`), so one token
+  endpoint answers every grant Google's does.
+
+### Error fidelity: the page, not the redirect
+
+The single most-misunderstood thing about this surface, and the one that refuted an RFC-shaped first
+implementation of this pack. RFC 6749 §4.1.2.1 says to bounce parameter errors back to the client.
+**Google does not.** It 302s to its own page:
+
+```
+https://accounts.google.com/signin/oauth/error?authError=<base64url protobuf>&flowName=GeneralOAuthFlow&client_id=…
+```
+
+…which renders `Access blocked: …` and the `Error <status>: <code>` line every integrator ends up
+searching for. The `authError` payload is a five-field protobuf — `{1: code, 2: message, 3: doc-url,
+4: http-status, 5: echoed-param}` — reproduced in `src/googleoauth-autherror.ts`, so the twin's
+browser behaviour matches: the address bar really changes to the vendor's error page.
+
+**Only two outcomes ever reach the caller's `redirect_uri`:** `access_denied` (the user pressed
+Cancel) and `interaction_required` (`prompt=none` could not be satisfied silently). Everything else —
+unknown `client_id`, unregistered `redirect_uri`, a missing or invalid parameter, a repeated
+parameter — renders the page. For an untrusted `redirect_uri` this is a security property, not a
+style choice: bouncing there would make the twin an open redirector.
+
+Other error facts, grounded from a read-only live capture of the real endpoints (2026-08-20) rather
+than from repetition:
+
+| | |
+|---|---|
+| unknown client at the token endpoint | `401 {"error":"invalid_client","error_description":"The OAuth client was not found."}` |
+| wrong client secret | `401 …"The provided client secret is invalid."` — a *different* message |
+| malformed jwt-bearer assertion | `400 {"error":"invalid_request","error_description":"Bad Request"}` |
+| userinfo, bad credential | `openidconnect.googleapis.com` → `invalid_request`/`Invalid Credentials`; `www.googleapis.com` → `invalid_token`/`Invalid Value`. **The two hosts disagree**, and the twin keeps them disagreeing |
+| tokeninfo | `exp`, `expires_in` and `email_verified` come back as JSON **strings** |
+
+The widely-repeated claim that `invalid_grant`'s `error_description` is `"Bad Request"` is **false** —
+that string belongs to a malformed `invalid_request` on the jwt-bearer grant. The twin uses Google's
+documented wording for `invalid_grant` instead.
+
+### Host claiming (path-aware, deliberately)
+
+`accounts.google.com` is **not an API host**: it is Google's entire sign-in web property. The
+injector entry (`packages/world-core/inject.cjs`, `VENDOR_HOSTS.googleoauth`) therefore
+claims only the OAuth/OIDC paths this pack serves across four hosts, and everything else refuses
+**loudly** rather than being answered by a twin that cannot serve it:
+
+| host | claimed |
+|---|---|
+| `accounts.google.com` | `/o/oauth2/*auth*`, `/o/oauth2/token`, `/signin/oauth/error`, `/.well-known/openid-configuration`, `/_twin/*` |
+| `oauth2.googleapis.com` | `/token`, `/oauth2/v4/token`, `/revoke`, `/tokeninfo` |
+| `www.googleapis.com` | `/oauth2/v1/certs`, `/oauth2/v3/{certs,userinfo}` — shared with `youtube`, split by path |
+| `openidconnect.googleapis.com` | all of it |
+
+The pack is declared **before** the pack-less `googleauth` key, so a world running both routes the
+token endpoint to this pack — whose token endpoint is a strict superset (it serves
+`authorization_code` and `refresh_token`, which `googleauth` has no state for, *and* the jwt-bearer
+exchange `googleauth` exists for, with a real RS256 `id_token` instead of an `alg: none` stub). A
+world running only the `gemini` twin is unaffected.
+
+### Twin-only routes (not vendor surface, not counted)
+
+`POST|GET /_twin/consent` (the Allow/Deny form target — Google's own consent form posts to an
+undocumented internal endpoint, so there is no vendor path to be faithful to), `POST /_twin/clients`
+and `POST /_twin/accounts` (registration and persona seeding — Google has no API for either). They
+are clearly namespaced and deliberately **absent from the capability manifest**; counting them would
+pad the denominator.
+
+### The twin authenticates nobody
+
+The account chooser lists personas seeded into kernel state and picking one **is** the login — said
+on the screen rather than hidden. There is no password, no second factor, no risk engine and no
+Google-minted session cookie, because a local twin holds no Google credential and must never appear
+to. App verification is a manual multi-week Google review, so the twin models only its **result**
+(the `verified` flag on a client) and shows the unverified interstitial from it.
+
+What the SID/SSID cookies *carry* is ordinary same-origin state a twin can hold — a chooser that
+remembers you, the multi-login `authuser` index — and is filed as
+`googleoauth.accounts.multi_login_authuser` (todo). Verifying a service-account assertion is
+likewise a todo, not an impossibility: it needs the key's *public* half, which a world's own SA key
+file carries and the twin could register exactly as it registers OAuth clients, so the honest label
+is "no key registry yet" (`googleoauth.serviceaccount.assertion_signature_verified`). The twin
+decodes the assertion to answer in the flow the caller used, and never pretends to have verified it.
+
+### Known deliberate deviations
+
+- **`/oauth2/v1/certs` serves the public key PEM, not an X.509 certificate.** Google publishes
+  certificates there; the twin has no CA and refuses to fabricate a chain. Filed as
+  `googleoauth.certs.v1_x509_certificate`.
+- **The token endpoint is form-encoded only.** A JSON body is not accepted, because there is no
+  first-party evidence that Google accepts one and an invented tolerance produces clients that only
+  work against the twin. Filed as `googleoauth.token.json_body_tolerance`.
+- **The error page is served HTTP 200**, with the status it *names* travelling in the `authError`
+  payload. The real page's own HTTP status was not captured. Filed as
+  `googleoauth.errors.error_page_http_status`.
+- **One signing key, never rotated.** Google publishes several and rotates them. Filed as
+  `googleoauth.idtoken.key_rotation`.
+- **`iss` is always the URL form** (`https://accounts.google.com`). Google also issues the bare
+  `accounts.google.com`. Filed as `googleoauth.idtoken.iss_bare_host_variant`.
+
+## Fidelity
+
+`src/googleoauth-sdk.integration.test.ts` drives **`google-auth-library`'s `OAuth2Client`
+unmodified** — the class `googleapis`, `@googleapis/*` and every Google Cloud SDK build their auth
+on — through `generateAuthUrl` → consent → `getToken` → `verifyIdToken` → `refreshAccessToken` →
+`revokeToken`, plus its own `generateCodeVerifierAsync` PKCE helper.
+
+**Unmodified means un-patched, not un-configured.** The client is pointed at the twin through the
+SDK's own public `endpoints` option — exactly what a caller pointing at a private Google-compatible
+IdP does. Nothing is monkey-patched and no request is hand-rolled to dodge the SDK.
+
+> One wiring note worth knowing for *any* Google-compatible IdP: `verifyIdToken` defaults to the
+> SDK's **PEM** certificate format, so it reads `oauth2FederatedSignonPemCertsUrl` — **not** the JWK
+> URL. Configure only the JWK one and the SDK quietly fetches the real
+> `www.googleapis.com/oauth2/v1/certs` and fails with `No pem found for envelope`, which looks like
+> an IdP bug and is really a configuration one.
+
+The **browser leg** — a human clicking Continue — is not something an SDK can do, so it is driven by
+a real headless chromium in `src/googleoauth-journey.uitest.ts`, which then redeems the code the click
+produced.
+
+## Rate budget
+
+Google publishes **no scalar per-minute rate limit** for these endpoints. What it publishes for this
+surface is quota of a different *shape* — 100 refresh tokens per Google Account per OAuth client
+(the 101st silently invalidates the oldest), a 7-day refresh-token expiry for apps in testing status,
+and a reputation-based new-user authorization limit with **no published numbers** (exceeding it gives
+`Error 403: rate_limit_exceeded`). A token-count cap cannot anchor a rolling-window rate, so the
+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` is priced at 10 — it destroys the *whole* grant on a real account (every access and
+refresh token, and the grant record), which is a human blast radius rather than a throttle. It is
+the only call priced above the default. That is a judgement call, and is stated as one.
+
+## Layout
+
+```
+src/googleoauth-twin.ts          the request handler (the protocol)
+src/googleoauth-store.ts         kernel-backed state + vendor-shaped id minting
+src/googleoauth-jwt.ts           real RS256 signing, JWKS, at_hash, PKCE S256
+src/googleoauth-autherror.ts     Google's authError protobuf + error-page URL
+src/googleoauth-scopes.ts        the scope catalog (consent-screen wording)
+src/googleoauth-consent-ui.ts    the consent screen's state builder + server render
+client/googleoauth-consent.tsx   the React components (server-rendered AND bundled)
+src/googleoauth-consent-client.gen.ts  GENERATED: the bundle + stylesheet as committed text (scripts/consent-clients.ts)
+src/googleoauth-connector.ts     pull over an injected client; push is an honest gap
+src/googleoauth-budget.ts        the rate-budget declaration
+```

package/client/googleoauth-consent.css

@@ -0,0 +1,207 @@
+/* Google's consent screen, as close as a twin gets without shipping the vendor's assets:
+   the Google Sans-ish system stack, the centred card on a grey field, the blue pill button. */
+:root {
+  --g-blue: #1a73e8;
+  --g-text: #202124;
+  --g-muted: #5f6368;
+  --g-border: #dadce0;
+  --g-bg: #f1f3f4;
+  --g-red: #d93025;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 48px 16px;
+  background: var(--g-bg);
+  color: var(--g-text);
+  font-family: 'Google Sans', Roboto, -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.card {
+  width: 100%;
+  max-width: 450px;
+  background: #fff;
+  border: 1px solid var(--g-border);
+  border-radius: 8px;
+  padding: 48px 40px 36px;
+}
+.card-error { max-width: 512px; }
+
+.g-mark {
+  font-size: 24px;
+  font-weight: 500;
+  letter-spacing: -0.5px;
+  margin-bottom: 16px;
+}
+.g-b { color: #4285f4; }
+.g-r { color: #ea4335; }
+.g-y { color: #fbbc05; }
+.g-g { color: #34a853; }
+
+.title {
+  font-size: 24px;
+  font-weight: 400;
+  line-height: 1.3;
+  margin: 0 0 8px;
+}
+.title .app-name { font-weight: 500; }
+
+.subtitle {
+  margin: 0 0 24px;
+  color: var(--g-muted);
+}
+
+.account-list {
+  display: flex;
+  flex-direction: column;
+  border-top: 1px solid var(--g-border);
+  margin: 8px 0 16px;
+}
+
+.account-row {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  width: 100%;
+  padding: 12px 8px;
+  background: none;
+  border: none;
+  border-bottom: 1px solid var(--g-border);
+  cursor: pointer;
+  text-align: left;
+  font: inherit;
+  color: inherit;
+}
+.account-row:hover { background: #f8f9fa; }
+
+.avatar {
+  flex: 0 0 auto;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: var(--g-blue);
+  color: #fff;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 500;
+}
+
+.account-text { display: flex; flex-direction: column; }
+.account-name { font-weight: 500; }
+.account-email { color: var(--g-muted); }
+
+.chosen-account {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  border: 1px solid var(--g-border);
+  border-radius: 16px;
+  padding: 4px 12px 4px 4px;
+  margin-bottom: 24px;
+}
+.chosen-account .avatar { width: 24px; height: 24px; font-size: 12px; }
+
+.unverified {
+  background: #fef7e0;
+  border: 1px solid #fdd663;
+  border-radius: 4px;
+  padding: 8px 12px;
+  margin: 0 0 16px;
+  color: #7f5700;
+}
+
+.scope-list {
+  list-style: none;
+  margin: 0 0 24px;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.scope-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+.scope-check { margin-top: 3px; accent-color: var(--g-blue); }
+.scope-label { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; cursor: pointer; }
+.scope-text { flex: 1 1 auto; }
+
+.scope-tag {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+  border-radius: 4px;
+  padding: 1px 6px;
+  background: #e8f0fe;
+  color: #174ea6;
+}
+.scope-tag-unknown { background: #fce8e6; color: #a50e0e; }
+
+.granular-controls {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  margin: -16px 0 8px;
+}
+.granular-controls .btn { padding: 4px 12px; }
+
+.legal { color: var(--g-muted); margin: 0 0 24px; }
+.support { color: var(--g-muted); margin: 24px 0 0; font-size: 12px; }
+
+.actions { display: flex; justify-content: flex-end; gap: 8px; }
+
+.btn {
+  font: inherit;
+  font-weight: 500;
+  border-radius: 4px;
+  padding: 9px 24px;
+  cursor: pointer;
+  border: 1px solid transparent;
+}
+.btn-text { background: none; color: var(--g-blue); }
+.btn-text:hover { background: #f1f8ff; }
+.btn-primary { background: var(--g-blue); color: #fff; }
+.btn-primary:hover { background: #1765cc; }
+
+.error-detail { margin: 0 0 24px; color: var(--g-muted); }
+.error-code {
+  margin: 0;
+  font-family: 'Roboto Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: var(--g-red);
+}
+.error-request {
+  margin: 8px 0 0;
+  font-family: 'Roboto Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--g-muted);
+  word-break: break-all;
+}
+
+/* Google puts a "Sign in with Google" line beside the wordmark on both screens. */
+.g-header {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  margin-bottom: 16px;
+}
+.g-signin { color: var(--g-muted); font-size: 13px; }
+
+.support summary,
+.error-details summary {
+  cursor: pointer;
+  color: var(--g-blue);
+  font-weight: 500;
+}
+.support p,
+.error-details p { margin: 8px 0 0; }
+.error-details { margin-top: 16px; }