@volter/twin-googleoauth 0.1.0

package/src/googleoauth-twin.ts

@@ -0,0 +1,1207 @@
+// Google OAuth 2.0 / OpenID Connect twin REQUEST HANDLER — the vendor's THREE-LEGGED consent
+// surface, served locally.
+//
+// Contract: handleGoogleOAuthTwinRequest({method, path, ...}) -> {status, body, headers}. It is the
+// faithful surface an unmodified OAuth client library talks to:
+//
+//   accounts.google.com   GET  /o/oauth2/v2/auth   (+ legacy /o/oauth2/auth)   → the CONSENT SCREEN
+//                         GET  /.well-known/openid-configuration               → OIDC discovery
+//   oauth2.googleapis.com POST /token              (+ /oauth2/v4/token, /o/oauth2/token)
+//                         POST|GET /revoke
+//                         GET  /tokeninfo
+//   www.googleapis.com    GET  /oauth2/v3/certs    (+ legacy /oauth2/v1/certs) → the JWKS
+//                         GET  /oauth2/v3/userinfo
+//   openidconnect.googleapis.com GET|POST /v1/userinfo
+//
+// ── WHY THIS PACK IS BROWSER-FACING, AND WHAT THAT MEANS ────────────────────────────────────────
+// Every other twin in this repo answers a MACHINE. This one has to answer a HUMAN: the whole point
+// of the authorization-code flow is that a browser is redirected to the vendor, a person reads what
+// the app is asking for, and clicks Allow. A twin that skipped the screen and 302'd straight back
+// would not be a twin of Google OAuth — it would be a bypass, and every integration bug that lives
+// in the consent leg (wrong redirect_uri, missing state, a scope the user declined) would be
+// invisible. So the twin SERVES HTML at the vendor's real path, rendered server-side from its own
+// projection by the SAME React components the client bundle ships (googleoauth-consent-ui.ts).
+// This is the vendor's OWN product UI, not a dashboard mirror — but the mirror DISCIPLINE applies
+// in full: the screen is data-coupled to kernel state and is driven by a Playwright journey.
+//
+// ── WHAT IS REAL HERE ───────────────────────────────────────────────────────────────────────────
+//   • The FULL authorization-code round trip: auth request → consent → 302 with code+state → the
+//     code is redeemable exactly ONCE at this same pack's token endpoint → refresh_token grant.
+//   • PKCE S256/plain, verified with real SHA-256 (googleoauth-jwt.ts `pkceS256`).
+//   • id_token is a GENUINE RS256 JWT signed by a persisted RSA keypair whose public half this
+//     twin serves at /oauth2/v3/certs, so `google-auth-library`'s `verifyIdToken` and
+//     `openid-client`'s id_token validation both succeed UNMODIFIED. (The clerk precedent: real
+//     crypto or nothing.)
+//   • Redirect-URI matching is EXACT, the way Google's is — the single most common integration bug
+//     is only reproducible if the twin is as strict as the vendor.
+//
+// ── WHAT IS NOT ────────────────────────────────────────────────────────────────────────────────
+// The twin authenticates NOBODY. There is no password, no 2FA, no session cookie, no risk engine:
+// the account chooser lists personas seeded into kernel state and picking one IS the login. That is
+// deliberate and stated on the screen, not a gap being hidden — a local twin cannot hold a Google
+// credential and must never appear to.
+//
+// State lives in the kernel action log (D1). No real Google endpoint is ever called from this path
+// (D4).
+import { nodeBuiltin } from '@volter/world-core';
+import { atHash, buildJwks, buildLegacyPemCerts, pkceS256, signJwt } from './googleoauth-jwt.ts';
+import { authErrorRedirect, decodeAuthError, ERROR_DOC_URLS, ERROR_PAGE_PATH, errorHeadline } from './googleoauth-autherror.ts';
+import { consentPageHtml, errorPageHtml, googleOAuthConsentState } from './googleoauth-consent-ui.ts';
+import { formatScopeParam, isGranularlyDeclinable, parseScopeParam } from './googleoauth-scopes.ts';
+import { granularConsentApplies } from '../client/googleoauth-consent.tsx';
+import {
+  authRequestIdFor,
+  ensureSeed,
+  listAccounts,
+  mintAccessToken,
+  mintAuthorizationCode,
+  mintRefreshToken,
+  nextRev,
+  readOne,
+  readType,
+  redirectUriAllowed,
+  RESOURCE_TYPES as STORE_RESOURCE_TYPES,
+  write,
+  type Row,
+} from './googleoauth-store.ts';
+
+export { RESOURCE_TYPES } from './googleoauth-store.ts';
+
+/** Google's real hosts, used when a caller does not tell the twin its own origin. */
+export const ACCOUNTS_ORIGIN = 'https://accounts.google.com';
+export const OAUTH2_ORIGIN = 'https://oauth2.googleapis.com';
+export const APIS_ORIGIN = 'https://www.googleapis.com';
+export const OIDC_ORIGIN = 'https://openidconnect.googleapis.com';
+/** The `iss` Google puts in every id_token. (Google historically also used the bare
+ *  `accounts.google.com`; verifiers accept both, and this twin issues the URL form.) */
+export const ISSUER = 'https://accounts.google.com';
+
+/** Google's real default access-token lifetime. (The web-server guide's sample body shows 3920;
+ *  live tokens read 3600 at issue, and tokeninfo reports the REMAINING life, hence the ~3568
+ *  values in Google's own tokeninfo examples.) */
+const ACCESS_TOKEN_TTL_SECONDS = 3600;
+/** Google's authorization codes are short-lived; the published guidance is ~10 minutes. */
+const AUTH_CODE_TTL_SECONDS = 600;
+
+export type GoogleOAuthRequest = {
+  method: string;
+  /** Path plus query string, e.g. `/o/oauth2/v2/auth?client_id=…`. */
+  path: string;
+  body?: string;
+  /** Lower-cased request headers (authorization / content-type). */
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /**
+   * Where this twin is reached (`twinPublicBase`: origin plus any served-World mount path). The
+   * DISCOVERY document, the auth-error redirect and the consent page's own form action have to
+   * point back at the twin or a discovery-driven client (openid-client) would follow them out to
+   * the real Google. Absent — an in-process call — the
+   * document is rendered with Google's REAL endpoint URLs, which is the vendor-faithful answer.
+   */
+  origin?: string;
+  /** The bare origin the request arrived at, when it differs from `origin` (a served World mounts
+   *  the twin under a path). The seeded demo app's callbacks derive from it; defaults to `origin`. */
+  callbackOrigin?: string;
+};
+
+export type GoogleOAuthResponse = {
+  status: number;
+  /** A JSON-serialisable object, or a STRING when the response is an HTML page. */
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+const HTML = { 'content-type': 'text/html; charset=utf-8' };
+const NOSTORE = { 'cache-control': 'no-store', pragma: 'no-cache' };
+
+// ── vendor error envelopes ──────────────────────────────────────────────────────────────────────
+
+/** The OAuth 2.0 token-endpoint error body Google returns: `{ error, error_description }`. */
+function oauthError(error: string, description: string, status: number): GoogleOAuthResponse {
+  return { status, body: { error, error_description: description }, headers: { ...NOSTORE } };
+}
+
+/**
+ * The ONE answer an unusable authorization code gets: unknown, already-redeemed, expired, or minted
+ * for a different client are deliberately INDISTINGUISHABLE, because telling them apart would leak
+ * which codes exist. The wording is Google's own documented text for `invalid_grant`.
+ */
+function badCode(): GoogleOAuthResponse {
+  return oauthError('invalid_grant', 'The supplied authorization code is invalid or in the wrong format.', 400);
+}
+
+/**
+ * The Google-API error envelope (`{ error: { code, message, status } }`) — the shape every
+ * googleapis.com REST surface uses.
+ *
+ * NOTE it is NOT what the userinfo endpoints answer with: those return the FLAT OAuth-style
+ * `{ error, error_description }` body, and the two hosts disagree on which code they use (see
+ * `userinfo` below). Both were captured live on 2026-08-20.
+ */
+function apiError(code: number, message: string, status: string): GoogleOAuthResponse {
+  return { status: code, body: { error: { code, message, status } }, headers: { ...NOSTORE } };
+}
+
+/**
+ * The authorization endpoint's failure path, and the single most-misunderstood thing about this
+ * surface.
+ *
+ * Google does NOT answer a bad authorization request with an HTML body, and it does NOT bounce the
+ * error to the caller's `redirect_uri` — bouncing would hand an attacker an open redirector, and
+ * for a bad `redirect_uri` there is no trustworthy address to bounce TO. It 302s to its OWN error
+ * page at `/signin/oauth/error?authError=<protobuf>&flowName=GeneralOAuthFlow`, which then renders
+ * "Access blocked: …" and the "Error <status>: <code>" line (googleoauth-autherror.ts).
+ *
+ * The ONLY things that go back to `redirect_uri` are the two documented user-facing outcomes:
+ * `access_denied` (the user pressed Cancel) and `interaction_required` (prompt=none could not be
+ * satisfied silently). An earlier version of this handler redirected every parameter error the way
+ * RFC 6749 §4.1.2.1 describes; a live capture of the real endpoint refuted that — Google renders
+ * the page for `invalid_request`, `invalid_scope` and friends too.
+ */
+function errorPage(req: GoogleOAuthRequest, e: { code: string; message: string; status: number; param?: string }): GoogleOAuthResponse {
+  const origin = req.origin ?? ACCOUNTS_ORIGIN;
+  const clientId = new URLSearchParams(req.path.split('?')[1] ?? '').get('client_id') ?? undefined;
+  return {
+    status: 302,
+    body: '',
+    headers: {
+      location: authErrorRedirect(origin, { ...e, ...(ERROR_DOC_URLS[e.code] ? { docUrl: ERROR_DOC_URLS[e.code]! } : {}) }, clientId),
+      ...NOSTORE,
+    },
+  };
+}
+
+/** A 302 back to a VALIDATED redirect_uri carrying one of the two user-facing OAuth errors. */
+function redirectError(redirectUri: string, error: string, state: string | null, extra: Record<string, string> = {}): GoogleOAuthResponse {
+  const url = new URL(redirectUri);
+  url.searchParams.set('error', error);
+  for (const [k, v] of Object.entries(extra)) url.searchParams.set(k, v);
+  if (state !== null) url.searchParams.set('state', state);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+function redirectSuccess(redirectUri: string, params: Record<string, string>): GoogleOAuthResponse {
+  const url = new URL(redirectUri);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────────
+
+function splitPath(raw: string): { path: string; query: URLSearchParams } {
+  const [p, q = ''] = raw.split('?');
+  const path = (p ?? '/').replace(/\/+$/, '') || '/';
+  return { path, query: new URLSearchParams(q) };
+}
+
+/**
+ * The world instant this request happened at. The twin has NO clock of its own (runtime contract
+ * R9: no clock in served content) — `createGoogleOAuthTwinFetch` stamps every request with
+ * `worldNow()`, the world's frozen instant, and a caller that names no instant is a DEFECT rather
+ * than a cue to read the wall clock. The old `?? Date.now()` fallback put the host's wall clock
+ * into `expires_in`/`iat`/`exp` on any path that forgot to stamp; it throws now.
+ */
+function instantOf(occurredAt?: string): string {
+  if (!occurredAt) {
+    throw new Error('googleoauth twin: the request carries no occurredAt — this twin has no clock of its own; the server stamps worldNow()');
+  }
+  return occurredAt;
+}
+
+function nowSeconds(occurredAt?: string): number {
+  const ms = Date.parse(instantOf(occurredAt));
+  if (Number.isNaN(ms)) throw new Error(`googleoauth twin: occurredAt is not a timestamp: ${occurredAt}`);
+  return Math.floor(ms / 1000);
+}
+
+/** A deterministic 21-digit stand-in for a service account's numeric unique id, derived from its
+ *  address. Shape-faithful (Google's `sub` really is a 21-digit string) without pretending to know
+ *  a number only Google's directory holds. */
+function serviceAccountSubject(email: string): string {
+  const { createHash } = nodeBuiltin('node:crypto') as typeof import('node:crypto');
+  const digits = BigInt('0x' + createHash('sha256').update(email).digest('hex').slice(0, 24)).toString().slice(0, 20);
+  return `1${digits.padStart(20, '0')}`;
+}
+
+/** Google's `sub`-keyed account row → the OIDC claim bag, FILTERED BY GRANTED SCOPE. */
+function profileClaims(account: Row, scopes: readonly string[]): Record<string, unknown> {
+  const wantsEmail = scopes.includes('email') || scopes.includes('https://www.googleapis.com/auth/userinfo.email');
+  const wantsProfile = scopes.includes('profile') || scopes.includes('https://www.googleapis.com/auth/userinfo.profile');
+  return {
+    ...(wantsEmail ? { email: account.email, email_verified: account.emailVerified === true } : {}),
+    ...(wantsProfile
+      ? {
+          name: account.name,
+          given_name: account.givenName,
+          family_name: account.familyName,
+          picture: account.picture,
+        }
+      : {}),
+    ...(account.hd ? { hd: account.hd } : {}),
+  };
+}
+
+/**
+ * Client authentication. Google accepts the secret in the POST body (`client_secret`, the default
+ * `google-auth-library` uses) or as HTTP Basic (`clientAuthentication: 'basic'`), and accepts NO
+ * secret at all from an `installed` (public) client, which is what PKCE exists to protect.
+ */
+function authenticateClient(
+  form: URLSearchParams,
+  headers: Record<string, string> | undefined,
+  root: string | undefined,
+): { client: Row } | { fail: GoogleOAuthResponse } {
+  let clientId = form.get('client_id');
+  let clientSecret = form.get('client_secret');
+  const basic = headers?.authorization;
+  if (basic && /^basic /i.test(basic)) {
+    const decoded = Buffer.from(basic.slice(6).trim(), 'base64').toString('utf8');
+    const sep = decoded.indexOf(':');
+    if (sep >= 0) {
+      clientId = decodeURIComponent(decoded.slice(0, sep));
+      clientSecret = decodeURIComponent(decoded.slice(sep + 1));
+    }
+  }
+  if (!clientId) return { fail: oauthError('invalid_request', 'client_id is required', 400) };
+  const client = readOne(root, 'oauth_client', clientId);
+  // Google answers an unknown client with 401 invalid_client at the TOKEN endpoint (as opposed to
+  // the error PAGE it renders at the authorization endpoint).
+  if (!client) return { fail: oauthError('invalid_client', 'The OAuth client was not found.', 401) };
+  if (client.clientType === 'web') {
+    if (!clientSecret) return { fail: oauthError('invalid_client', 'The provided client secret is invalid.', 401) };
+    if (clientSecret !== client.secret) return { fail: oauthError('invalid_client', 'The provided client secret is invalid.', 401) };
+  } else if (clientSecret && clientSecret !== client.secret) {
+    // A public client MAY omit the secret, but a WRONG one is still a rejection.
+    return { fail: oauthError('invalid_client', 'The provided client secret is invalid.', 401) };
+  }
+  return { client };
+}
+
+// ── the authorization endpoint (the consent screen) ─────────────────────────────────────────────
+
+const AUTH_PATHS = new Set(['/o/oauth2/v2/auth', '/o/oauth2/auth', '/o/oauth2/v2/auth/oauthchooseaccount']);
+
+/**
+ * Google refuses a REPEATED query parameter outright rather than picking one — captured live:
+ * `response_type=code&response_type=id_token` answers
+ * "OAuth 2 parameters can only have a single value: response_type". Worth modelling because a
+ * duplicated parameter is a real and confusing integration bug (two layers of a framework both
+ * appending `scope`), and a twin that quietly took the first value would hide it.
+ */
+const SINGLE_VALUED = [
+  'client_id', 'redirect_uri', 'response_type', 'scope', 'state', 'access_type', 'prompt',
+  'login_hint', 'nonce', 'code_challenge', 'code_challenge_method', 'include_granted_scopes',
+  'enable_granular_consent', 'display', 'hd',
+] as const;
+
+/** One enum-valued parameter, with the message Google produces for a bad value (captured live). */
+const ENUM_PARAMS: Array<{ name: string; allowed: string[]; message: (v: string) => string }> = [
+  { name: 'access_type', allowed: ['online', 'offline'], message: (v) => `Invalid parameter value for access_type: '${v}' is not valid` },
+  { name: 'display', allowed: ['page', 'popup', 'touch', 'wap'], message: (v) => `Invalid parameter value for display: '${v}' is not valid` },
+  { name: 'include_granted_scopes', allowed: ['true', 'false'], message: (v) => `Invalid value, must be one of false, true: ${v}` },
+  { name: 'enable_granular_consent', allowed: ['true', 'false'], message: (v) => `Invalid value, must be one of false, true: ${v}` },
+];
+
+async function authorize(req: GoogleOAuthRequest, query: URLSearchParams): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const state = query.get('state');
+  const fail = (code: string, message: string, status: number, param?: string) =>
+    errorPage(req, { code, message, status, ...(param ? { param } : {}) });
+
+  // 0. Repeated parameters are refused before anything else looks at a value.
+  for (const name of SINGLE_VALUED) {
+    if (query.getAll(name).length > 1) {
+      return fail('invalid_request', `OAuth 2 parameters can only have a single value: ${name}`, 400, name);
+    }
+  }
+
+  // 1. client_id.
+  const clientId = query.get('client_id');
+  if (!clientId) return fail('invalid_request', 'Required parameter is missing: client_id', 400, 'client_id');
+  const client = readOne(root, 'oauth_client', clientId);
+  if (!client) return fail('invalid_client', 'The OAuth client was not found.', 401);
+
+  // 2. redirect_uri. THE SECURITY BOUNDARY: until the URI is proven to belong to this client there
+  //    is no address the twin may bounce an error to, so both failures render the error page.
+  const redirectUri = query.get('redirect_uri');
+  if (!redirectUri) return fail('invalid_request', 'Required parameter is missing: redirect_uri', 400, 'redirect_uri');
+  if (!redirectUriAllowed(client, redirectUri)) {
+    return fail(
+      'redirect_uri_mismatch',
+      "You can't sign in to this app because it doesn't comply with Google's OAuth 2.0 policy.\n\n"
+        + "If you're the app developer, register the redirect URI in the Google Cloud Console.",
+      400,
+      `redirect_uri=${redirectUri}`,
+    );
+  }
+
+  // 3. …and everything AFTER that boundary is still an error PAGE, not a redirect. This is the part
+  //    that surprises people (RFC 6749 §4.1.2.1 says to redirect); a live capture of the real
+  //    endpoint shows Google rendering the page for invalid_request/invalid_scope too. Only
+  //    `access_denied` and `interaction_required` ever reach the caller's redirect_uri.
+  const responseType = query.get('response_type');
+  if (!responseType) return fail('invalid_request', 'Required parameter is missing: response_type', 400, 'response_type');
+  if (responseType !== 'code') {
+    // Google DOES support `token`/`id_token` response types (the implicit and hybrid flows), so the
+    // twin must NOT answer "invalid response_type" — that would be claiming the vendor rejects
+    // something it accepts, the inverse false-green. It refuses as UNMODELLED instead, and says so.
+    return fail(
+      'unsupported_response_type',
+      `This twin models the authorization-code flow only; response_type=${responseType} is not modelled `
+        + '(googleoauth.authorize.implicit_flow). Real Google supports it.',
+      400,
+      `response_type=${responseType}`,
+    );
+  }
+  const scopes = parseScopeParam(query.get('scope'));
+  if (scopes.length === 0) return fail('invalid_request', 'Missing required parameter: scope', 400, 'scope');
+
+  for (const spec of ENUM_PARAMS) {
+    const value = query.get(spec.name);
+    if (value !== null && !spec.allowed.includes(value)) {
+      return fail('invalid_request', spec.message(value), 400, `${spec.name}=${value}`);
+    }
+  }
+
+  const codeChallenge = query.get('code_challenge');
+  const codeChallengeMethod = query.get('code_challenge_method') ?? (codeChallenge ? 'plain' : null);
+  if (codeChallengeMethod && !['S256', 'plain'].includes(codeChallengeMethod)) {
+    return fail('invalid_request', `Invalid parameter value for code_challenge_method: '${codeChallengeMethod}' is not a valid CodeChallengeMethod`, 400, `code_challenge_method=${codeChallengeMethod}`);
+  }
+  if (codeChallengeMethod && !codeChallenge) {
+    return fail('invalid_request', 'Missing required parameter: code_challenge', 400, 'code_challenge');
+  }
+
+  const accessType = query.get('access_type') ?? 'online';
+  const prompt = query.get('prompt');
+  if (prompt !== null) {
+    const values = prompt.split(/\s+/).filter(Boolean);
+    const allowed = new Set(['none', 'consent', 'select_account']);
+    // `none` must be alone — Google documents it as mutually exclusive with the others.
+    if (values.length === 0 || values.some((v) => !allowed.has(v)) || (values.includes('none') && values.length > 1)) {
+      return fail('invalid_request', `Invalid prompt: ${prompt}`, 400, `prompt=${prompt}`);
+    }
+  }
+
+  // 4. Record the request, then render the screen. The auth_request row is what the Allow/Deny post
+  //    resolves — the browser never carries the parameters back, so they cannot be tampered with
+  //    between the two legs (which is exactly the property Google's own opaque state handle has).
+  const fields = {
+    clientId,
+    redirectUri,
+    scope: formatScopeParam(scopes),
+    state: state ?? null,
+    nonce: query.get('nonce'),
+    accessType,
+    prompt: prompt ?? null,
+    loginHint: query.get('login_hint'),
+    includeGrantedScopes: query.get('include_granted_scopes') === 'true',
+    codeChallenge,
+    codeChallengeMethod: codeChallenge ? (codeChallengeMethod ?? 'plain') : null,
+    settled: false,
+    rev: 1,
+  };
+  // The handle is SERVED (it is the consent form's own hidden field), so R9 governs it: minted from
+  // the world instant + the rows already held, never from entropy, and an identical authorize at
+  // the same instant reuses the pending row rather than piling up a second screen.
+  const requestId = authRequestIdFor(root, instantOf(req.occurredAt), fields);
+  await write('auth_request', requestId, 'auth_request.create', fields, { root, occurredAt: instantOf(req.occurredAt) });
+
+  const accounts = listAccounts(root);
+
+  // `login_hint` names the account the app already knows about, and Google honours it by SKIPPING
+  // the chooser and going straight to consent for that account. An unmatched hint is not an error —
+  // Google falls back to the chooser — so the twin does the same rather than inventing a failure.
+  const hint = query.get('login_hint');
+  const hinted = hint
+    ? accounts.find((a) => a.id === hint || String(a.email).toLowerCase() === hint.toLowerCase())
+    : undefined;
+
+  // `prompt=none` is the "NEVER show me a screen" flow, and it has exactly two outcomes: a silent
+  // 302 carrying a code, or `interaction_required`. An earlier version got the FAILURE right and
+  // then fell through to `renderConsent` on success — serving an HTML page to a caller that asked
+  // for no UI, which a redirect-following client cannot use (§9 round one, MAJOR). It also only
+  // ever consulted `accounts[0]`, so any persona but the first could hold a covering grant and
+  // still be refused.
+  if (prompt?.split(/\s+/).includes('none')) {
+    const covers = (account: Row) => {
+      const grant = readOne(root, 'grant', `${clientId}:${account.id}`);
+      const granted: string[] = Array.isArray(grant?.scopes) ? grant!.scopes : [];
+      return scopes.every((s) => granted.includes(s));
+    };
+    // A `login_hint` that does not cover is a REFUSAL, never a substitution. An earlier version fell
+    // through to `accounts.find(covers)`, so an app that named Ada and got no screen could be handed
+    // an id_token for Grace — a different human — and could not find out until it decoded the token
+    // (§9 round two, MAJOR). If the app named a subject, that subject is the only candidate.
+    const silent = hinted ? (covers(hinted) ? hinted : undefined) : accounts.find(covers);
+    if (!silent) {
+      // Captured live: Google answers `?error=interaction_required&error_subtype=access_denied`.
+      return redirectError(redirectUri, 'interaction_required', state, { error_subtype: 'access_denied' });
+    }
+    return grantSilently(req, requestId, silent);
+  }
+
+  return renderConsent(req, requestId, hinted?.id ?? null);
+}
+
+/**
+ * `prompt=none`'s success path: mint the code and 302, with NO screen. Shares `settleAuthRequest`
+ * with the Allow button so the two paths cannot drift — the only difference is that nobody clicked.
+ */
+async function grantSilently(req: GoogleOAuthRequest, requestId: string, account: Row): Promise<GoogleOAuthResponse> {
+  const form = new URLSearchParams();
+  form.set('auth_request', requestId);
+  form.set('sub', account.id);
+  form.set('decision', 'allow');
+  // Everything already granted stays granted: `prompt=none` cannot be a granular-consent screen,
+  // because there is no screen.
+  const authRequest = readOne(req.root, 'auth_request', requestId);
+  for (const scope of parseScopeParam(String(authRequest?.scope ?? ''))) form.append('scope', scope);
+  return consentDecision(req, form, true);
+}
+
+/** Render whichever consent step the (requestId, sub) pair selects, from the projection alone. */
+function renderConsent(req: GoogleOAuthRequest, requestId: string, sub: string | null): GoogleOAuthResponse {
+  const view = googleOAuthConsentState({
+    root: req.root,
+    requestId,
+    sub,
+    origin: req.origin ?? ACCOUNTS_ORIGIN,
+  });
+  if (!view) {
+    return errorPage(req, { code: 'invalid_request', message: 'Unknown or expired authorization request.', status: 400 });
+  }
+  return { status: 200, body: consentPageHtml(view, req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+}
+
+/**
+ * `GET /signin/oauth/error` — the page every authorization failure above is bounced to. It decodes
+ * the `authError` protobuf it was handed and renders it with the REAL exported `ErrorPage`
+ * component, so the served page and the components the verifies assert over are one renderer.
+ *
+ * Served 200: the status the page NAMES (its "Error 401: invalid_client" line) travels in the
+ * payload, not in the HTTP status, and the real page's own HTTP status was not captured — filed as
+ * `googleoauth.errors.error_page_http_status` rather than guessed.
+ */
+function signinOAuthErrorPage(req: GoogleOAuthRequest, query: URLSearchParams): GoogleOAuthResponse {
+  const decoded = decodeAuthError(query.get('authError') ?? '');
+  if (!decoded) {
+    return {
+      status: 400,
+      body: errorPageHtml({ status: 400, code: 'invalid_request', summary: errorHeadline('invalid_request'), detail: 'That authorization error link is not valid.' }, req.origin ?? ''),
+      headers: { ...HTML, ...NOSTORE },
+    };
+  }
+  return {
+    status: 200,
+    body: errorPageHtml({
+      status: decoded.status,
+      code: decoded.code,
+      summary: errorHeadline(decoded.code),
+      detail: decoded.message,
+      ...(decoded.param ? { requestPath: decoded.param } : {}),
+      ...(decoded.docUrl ? { docUrl: decoded.docUrl } : {}),
+      appName: appNameFor(req.root, query.get('client_id')),
+    }, req.origin ?? ''),
+    headers: { ...HTML, ...NOSTORE },
+  };
+}
+
+function appNameFor(root: string | undefined, clientId: string | null): string | undefined {
+  if (!clientId) return undefined;
+  const client = readOne(root, 'oauth_client', clientId);
+  return client ? String(client.name) : undefined;
+}
+
+/**
+ * The Allow/Deny post. TWIN-ONLY SURFACE, deliberately namespaced under `/_twin/` and deliberately
+ * ABSENT from the capability manifest: Google's consent form posts to an undocumented internal
+ * endpoint, so there is no vendor path to be faithful to here and inventing one would be surface
+ * the vendor does not have. It is the twin's equivalent of the seed routes ADDING_A_TWIN.md §6
+ * sanctions (`POST /twin/observation`, `POST /v1/_twin/...`).
+ */
+async function consentDecision(req: GoogleOAuthRequest, form: URLSearchParams, silentlyGranted = false): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const at = req.occurredAt;
+  const opts = { root, ...(at ? { occurredAt: at } : {}) };
+  const requestId = form.get('auth_request') ?? '';
+  const authRequest = readOne(root, 'auth_request', requestId);
+  if (!authRequest) return oauthError('invalid_request', 'Unknown or expired authorization request.', 400);
+  if (authRequest.settled === true) return oauthError('invalid_request', 'This authorization request was already settled.', 400);
+
+  const redirectUri = String(authRequest.redirectUri);
+  const state: string | null = typeof authRequest.state === 'string' ? authRequest.state : null;
+
+  await write('auth_request', requestId, 'auth_request.settle', { settled: true, rev: nextRev(root, 'auth_request', requestId) }, opts);
+
+  // DENY — Google's documented user-refusal redirect.
+  if (form.get('decision') !== 'allow') {
+    return redirectError(redirectUri, 'access_denied', state);
+  }
+
+  const sub = form.get('sub') ?? '';
+  const account = readOne(root, 'account', sub);
+  if (!account) return oauthError('invalid_request', 'Unknown account.', 400);
+
+  // GRANULAR CONSENT — the user may untick individual product scopes; the OIDC scopes ride with
+  // signing in and are never declinable. What survives here is what the grant (and the echoed
+  // `scope` on the redirect) carries — a real integration MUST cope with getting less than it
+  // asked for, and a twin that always granted everything would hide that entire bug class.
+  const requested = parseScopeParam(String(authRequest.scope));
+  // Google only SHOWS checkboxes when its granular rule applies (a sign-in scope mixed with a
+  // product one, or two or more product ones). When it does not, the grant is all-or-nothing and a
+  // posted scope list cannot narrow it — so the twin ignores the tick list exactly as the screen
+  // that never rendered a checkbox would.
+  const granular = granularConsentApplies(requested.map((s) => ({ declinable: isGranularlyDeclinable(s) })));
+  const ticked = new Set(form.getAll('scope'));
+  const granted = granular ? requested.filter((s) => !isGranularlyDeclinable(s) || ticked.has(s)) : requested;
+  if (granted.length === 0) {
+    // Declining every declinable scope with nothing left is a refusal, not an empty grant.
+    return redirectError(redirectUri, 'access_denied', state);
+  }
+
+  const declined = requested.filter((s) => !granted.includes(s));
+  const grantId = `${authRequest.clientId}:${sub}`;
+  const priorGrant = readOne(root, 'grant', grantId);
+  // A REVOKED grant is not a prior grant. `revoke` clears the scope set (see `revoke` below), and
+  // real Google treats a re-consent after a revocation as a first authorization — which is why it
+  // hands back a refresh token. Reading the row's mere EXISTENCE made the twin withhold one
+  // (§9 round one, MAJOR).
+  const priorScopes: string[] = Array.isArray(priorGrant?.scopes) ? priorGrant!.scopes : [];
+  const isFirstGrant = priorScopes.length === 0;
+  // THE GRANT AFTER THIS SCREEN. Computed BEFORE `effective`, because `effective` must be derived
+  // from it: an earlier version unioned the PRE-removal prior scopes into the code and the access
+  // token, so a scope the user unticked ON THIS VERY SCREEN was handed straight back in the same
+  // request while the grant row correctly dropped it — leaving a token whose scope set was a strict
+  // superset of the grant that authorised it (§9 round two, MAJOR).
+  const nextScopes = [...new Set([...priorScopes.filter((s) => !declined.includes(s)), ...granted])];
+  // include_granted_scopes=true is Google's INCREMENTAL AUTHORIZATION: the new token carries the
+  // union of everything this user STILL grants this client — never a scope this screen declined.
+  const effective = authRequest.includeGrantedScopes === true ? nextScopes : granted;
+
+  // THE GRANT IS WHAT THE SCREEN DECIDED, not a monotonic union: a scope this request ASKED about is
+  // governed by this request's answer, and a scope it did not mention is untouched. An earlier
+  // version unioned unconditionally, so a decline stayed granted forever (§9 round one, MAJOR).
+  await write(
+    'grant',
+    grantId,
+    'grant.upsert',
+    { clientId: authRequest.clientId, sub, scopes: nextScopes, rev: nextRev(root, 'grant', grantId) },
+    opts,
+  );
+
+  const code = mintAuthorizationCode(root, instantOf(at), requestId);
+  await write(
+    'authorization_code',
+    code,
+    'authorization_code.create',
+    {
+      clientId: authRequest.clientId,
+      sub,
+      scope: formatScopeParam(effective),
+      redirectUri,
+      nonce: authRequest.nonce ?? null,
+      accessType: authRequest.accessType,
+      prompt: authRequest.prompt ?? null,
+      codeChallenge: authRequest.codeChallenge ?? null,
+      codeChallengeMethod: authRequest.codeChallengeMethod ?? null,
+      isFirstGrant,
+      consumed: false,
+      expiresAt: nowSeconds(at) + AUTH_CODE_TTL_SECONDS,
+      rev: 1,
+    },
+    opts,
+  );
+
+  return redirectSuccess(redirectUri, {
+    code,
+    ...(state !== null ? { state } : {}),
+    scope: formatScopeParam(effective),
+    authuser: '0',
+    // `prompt` echoes what actually happened. The silent `prompt=none` path shows no screen, so
+    // stamping `consent` there positively asserted a screen that does not exist (§9 round two).
+    ...(silentlyGranted ? {} : { prompt: 'consent' }),
+    // A Workspace account's hosted domain rides on the redirect (GIS code-model documents `hd`).
+    ...(account.hd ? { hd: String(account.hd) } : {}),
+    // NO `iss` PARAMETER, deliberately. An earlier version emitted RFC 9207's `iss` here, reasoning
+    // from an `authorization_response_iss_parameter_supported: true` key it also put in the
+    // discovery document — but neither the key nor the parameter could be confirmed against
+    // Google's real artefacts, and §9 round one correctly called the pair invented surface. Both
+    // are gone: a twin that invents a response parameter is one an integration can come to depend
+    // on and then break against the real vendor. Filed as `googleoauth.authorize.iss_parameter`.
+  });
+}
+
+// ── the token endpoint ──────────────────────────────────────────────────────────────────────────
+
+async function token(req: GoogleOAuthRequest): Promise<GoogleOAuthResponse> {
+  // Google's token endpoint is `application/x-www-form-urlencoded`. The twin is deliberately strict
+  // about that rather than tolerating a JSON body it has no documented evidence the vendor accepts
+  // (`googleoauth.token.json_body_tolerance`, todo) — an invented tolerance is the inverse
+  // false-green: a client that only works against the twin.
+  const form = new URLSearchParams(req.body ?? '');
+  const grantType = form.get('grant_type');
+  if (!grantType) return oauthError('invalid_request', 'Missing required parameter: grant_type', 400);
+
+  if (grantType === 'urn:ietf:params:oauth:grant-type:jwt-bearer') return jwtBearerGrant(req, form);
+  if (grantType === 'authorization_code') return authorizationCodeGrant(req, form);
+  if (grantType === 'refresh_token') return refreshTokenGrant(req, form);
+  return oauthError('unsupported_grant_type', `Invalid grant_type: ${grantType}`, 400);
+}
+
+async function issueTokens(
+  req: GoogleOAuthRequest,
+  opts: { client: Row; sub: string; scope: string; nonce: string | null; withRefreshToken: boolean;
+    /** The credential being EXCHANGED (the authorization code, or the refresh token presented).
+     *  It seeds the minted tokens (R9), so two exchanges at one world instant differ by what was
+     *  handed in as well as by the row count. */
+    subject: string;
+    /** The grant's access type. Carried EXPLICITLY because a refresh does not mint a new refresh
+     *  token yet still belongs to an OFFLINE grant — deriving it from `withRefreshToken` made a
+     *  refreshed token report `access_type: online` at /tokeninfo, which is wrong. */
+    accessType?: 'online' | 'offline' },
+): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const at = req.occurredAt;
+  const writeOpts = { root, ...(at ? { occurredAt: at } : {}) };
+  const scopes = parseScopeParam(opts.scope);
+  const account = readOne(root, 'account', opts.sub);
+  if (!account) return badCode();
+  const issuedAt = nowSeconds(at);
+
+  const accessToken = mintAccessToken(root, instantOf(at), opts.subject);
+  await write(
+    'access_token',
+    accessToken,
+    'access_token.create',
+    {
+      clientId: opts.client.id,
+      sub: opts.sub,
+      scope: opts.scope,
+      accessType: opts.accessType ?? (opts.withRefreshToken ? 'offline' : 'online'),
+      expiresAt: issuedAt + ACCESS_TOKEN_TTL_SECONDS,
+      revoked: false,
+      rev: 1,
+    },
+    writeOpts,
+  );
+
+  let refreshToken: string | undefined;
+  if (opts.withRefreshToken) {
+    refreshToken = mintRefreshToken(root, instantOf(at), opts.subject);
+    await write(
+      'refresh_token',
+      refreshToken,
+      'refresh_token.create',
+      { clientId: opts.client.id, sub: opts.sub, scope: opts.scope, revoked: false, rev: 1 },
+      writeOpts,
+    );
+  }
+
+  // The id_token rides only when `openid` was granted — that is what makes this an OIDC flow rather
+  // than a plain OAuth 2.0 one, and a client that asked for OAuth must not be handed an id_token.
+  let idToken: string | undefined;
+  if (scopes.includes('openid')) {
+    idToken = await signJwt(
+      {
+        iss: ISSUER,
+        azp: opts.client.id,
+        aud: opts.client.id,
+        sub: opts.sub,
+        at_hash: atHash(accessToken),
+        ...profileClaims(account, scopes),
+        ...(opts.nonce ? { nonce: opts.nonce } : {}),
+      },
+      { root, expiresInSeconds: ACCESS_TOKEN_TTL_SECONDS + 1, now: issuedAt },
+    );
+  }
+
+  return {
+    status: 200,
+    body: {
+      access_token: accessToken,
+      expires_in: ACCESS_TOKEN_TTL_SECONDS,
+      scope: opts.scope,
+      token_type: 'Bearer',
+      ...(refreshToken ? { refresh_token: refreshToken } : {}),
+      ...(idToken ? { id_token: idToken } : {}),
+    },
+    headers: { ...NOSTORE },
+  };
+}
+
+async function authorizationCodeGrant(req: GoogleOAuthRequest, form: URLSearchParams): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const auth = authenticateClient(form, req.headers, root);
+  if ('fail' in auth) return auth.fail;
+  const { client } = auth;
+
+  const code = form.get('code');
+  if (!code) return oauthError('invalid_request', 'Missing required parameter: code', 400);
+  const row = readOne(root, 'authorization_code', code);
+  // Unknown, already-redeemed and expired codes are ONE answer — `invalid_grant` — because telling
+  // them apart would leak which codes exist. The description is Google's own documented wording for
+  // this case (web-server guide, "invalid_grant"). It is NOT "Bad Request": a live capture on
+  // 2026-08-20 showed that string belongs to a malformed `invalid_request` on the jwt-bearer grant,
+  // refuting a widely-repeated assumption this handler originally encoded.
+  if (!row) return badCode();
+  if (row.clientId !== client.id) return badCode();
+  if (row.consumed === true) return badCode();
+  if (typeof row.expiresAt === 'number' && nowSeconds(req.occurredAt) >= row.expiresAt) {
+    return badCode();
+  }
+
+  // redirect_uri must be REPEATED at the token endpoint and must match the one the code was minted
+  // against (RFC 6749 §4.1.3); Google names this failure specifically.
+  const redirectUri = form.get('redirect_uri');
+  if (!redirectUri || redirectUri !== row.redirectUri) {
+    return oauthError('redirect_uri_mismatch', 'Bad Request', 400);
+  }
+
+  // PKCE.
+  if (row.codeChallenge) {
+    const verifier = form.get('code_verifier');
+    if (!verifier) return oauthError('invalid_grant', 'The code_challenge parameter is invalid or missing.', 400);
+    const computed = row.codeChallengeMethod === 'S256' ? pkceS256(verifier) : verifier;
+    if (computed !== row.codeChallenge) return badCode();
+  } else if (form.get('code_verifier')) {
+    // A verifier for a code minted without a challenge is a client bug, and Google rejects it.
+    return badCode();
+  }
+
+  await write(
+    'authorization_code',
+    code,
+    'authorization_code.consume',
+    { consumed: true, rev: nextRev(root, 'authorization_code', code) },
+    { root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) },
+  );
+
+  // Google returns a refresh_token only for an OFFLINE request, and then only on the FIRST
+  // authorization for this client+user or when the app forced the screen with prompt=consent.
+  // Integrations that assume every exchange yields a refresh_token are a well-known class of
+  // production bug; the twin reproduces the rule so that bug is reproducible.
+  const promptValues = typeof row.prompt === 'string' ? row.prompt.split(/\s+/) : [];
+  const withRefreshToken = row.accessType === 'offline' && (row.isFirstGrant === true || promptValues.includes('consent'));
+
+  return issueTokens(req, {
+    client,
+    sub: String(row.sub),
+    scope: String(row.scope),
+    nonce: typeof row.nonce === 'string' ? row.nonce : null,
+    withRefreshToken,
+    subject: code,
+    accessType: row.accessType === 'offline' ? 'offline' : 'online',
+  });
+}
+
+async function refreshTokenGrant(req: GoogleOAuthRequest, form: URLSearchParams): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const auth = authenticateClient(form, req.headers, root);
+  if ('fail' in auth) return auth.fail;
+  const { client } = auth;
+
+  const refreshToken = form.get('refresh_token');
+  if (!refreshToken) return oauthError('invalid_request', 'Missing required parameter: refresh_token', 400);
+  const row = readOne(root, 'refresh_token', refreshToken);
+  if (!row || row.revoked === true || row.clientId !== client.id) {
+    return oauthError('invalid_grant', 'Token has been expired or revoked.', 400);
+  }
+
+  // A refresh may NARROW the scope but never widen it (RFC 6749 §6).
+  let scope = String(row.scope);
+  const requested = parseScopeParam(form.get('scope'));
+  if (requested.length) {
+    const held = parseScopeParam(scope);
+    if (!requested.every((s) => held.includes(s))) {
+      return oauthError('invalid_scope', 'Bad Request', 400);
+    }
+    scope = formatScopeParam(requested);
+  }
+
+  // Google does NOT rotate the refresh token on use — the same one keeps working. The new access
+  // token still belongs to an OFFLINE grant, though (a refresh token only exists for one), so it
+  // must keep reporting `access_type: offline` at /tokeninfo.
+  return issueTokens(req, { client, sub: String(row.sub), scope, nonce: null, withRefreshToken: false, subject: String(row.id), accessType: 'offline' });
+}
+
+/**
+ * The SERVICE-ACCOUNT (two-legged) grant — `urn:ietf:params:oauth:grant-type:jwt-bearer`.
+ *
+ * This is the surface the pack-less `googleauth` injector key has been pointing at gemini-twin.ts
+ * for: `google-auth-library` signs a JWT locally and posts it here before ANY Vertex/GCS call, so a
+ * sealed world that does not model it dies in auth before reaching a modelled API. It is
+ * reproduced here — with REAL RS256 signing rather than gemini's `alg: none` stub — so that ONE
+ * token endpoint answers ALL of Google's grants, exactly as the vendor's does. See the README
+ * §"Why this pack owns oauth2.googleapis.com".
+ *
+ * The assertion's payload is DECODED, never verified: the twin authenticates nothing and holds no
+ * service-account key. It is read only to answer in the flow the caller used — a `target_audience`
+ * claim marks the ID-token flow (`getIdTokenClient`), anything else the access-token flow.
+ */
+async function jwtBearerGrant(req: GoogleOAuthRequest, form: URLSearchParams): Promise<GoogleOAuthResponse> {
+  const assertion = form.get('assertion');
+  if (!assertion) return oauthError('invalid_request', 'Missing required parameter: assertion', 400);
+  let payload: { target_audience?: unknown; iss?: unknown; scope?: unknown } = {};
+  try {
+    payload = JSON.parse(Buffer.from(assertion.split('.')[1] ?? '', 'base64url').toString('utf8'));
+  } catch {
+    // Captured live: a malformed jwt-bearer assertion is `invalid_request` with the description
+    // literally "Bad Request" — NOT invalid_grant. (An assertion naming an unknown service account
+    // is the one that answers `invalid_grant: Invalid grant: account not found`.)
+    return oauthError('invalid_request', 'Bad Request', 400);
+  }
+  const issuedAt = nowSeconds(req.occurredAt);
+  const email = typeof payload.iss === 'string' && payload.iss ? payload.iss : 'twin-service-account';
+  // Google's id_token `sub` is the service account's NUMERIC unique id, not its address — the
+  // address travels in `email`. The twin has no directory to look one up in, so it derives a stable
+  // 21-digit id from the address: vendor-SHAPED, deterministic, and never mistaken for the email
+  // (§9 round one caught the two being conflated).
+  const sub = serviceAccountSubject(email);
+  if (payload.target_audience) {
+    const idToken = await signJwt(
+      { iss: ISSUER, aud: String(payload.target_audience), azp: sub, sub, email, email_verified: true },
+      { root: req.root, expiresInSeconds: ACCESS_TOKEN_TTL_SECONDS + 1, now: issuedAt },
+    );
+    return { status: 200, body: { id_token: idToken }, headers: { ...NOSTORE } };
+  }
+  // The access token is PERSISTED, so it is a usable credential the way a real service-account
+  // token is. An earlier version minted a bare string and stored nothing, so the token it handed
+  // back was refused by the twin's own /tokeninfo the moment anyone tried to use it
+  // (§9 round one). The service account is not a consenting user, so no `account` row is written
+  // and no `grant` exists — /v1/userinfo correctly refuses it.
+  const accessToken = mintAccessToken(req.root, instantOf(req.occurredAt), sub);
+  const scope = typeof payload.scope === 'string' ? payload.scope : '';
+  await write(
+    'access_token',
+    accessToken,
+    'access_token.create',
+    { clientId: sub, sub, scope, accessType: 'online', serviceAccountEmail: email, expiresAt: issuedAt + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: 1 },
+    { root: req.root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) },
+  );
+  return {
+    status: 200,
+    body: {
+      access_token: accessToken,
+      expires_in: ACCESS_TOKEN_TTL_SECONDS,
+      token_type: 'Bearer',
+      ...(scope ? { scope } : {}),
+    },
+    headers: { ...NOSTORE },
+  };
+}
+
+// ── revoke / tokeninfo / userinfo ───────────────────────────────────────────────────────────────
+
+async function revoke(req: GoogleOAuthRequest, token_: string | null): Promise<GoogleOAuthResponse> {
+  const root = req.root;
+  const opts = { root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) };
+  if (!token_) return oauthError('invalid_request', 'Missing required parameter: token', 400);
+  const access = readOne(root, 'access_token', token_);
+  const refresh = readOne(root, 'refresh_token', token_);
+  if (!access && !refresh) return oauthError('invalid_token', 'Token expired or revoked', 400);
+
+  // Revoking EITHER half of a grant kills BOTH — Google revokes the whole grant, and an
+  // integration that assumes its access token survives a refresh-token revocation is broken.
+  const sub = String((access ?? refresh)!.sub);
+  const clientId = String((access ?? refresh)!.clientId);
+  for (const row of readType(root, 'access_token')) {
+    if (row.sub === sub && row.clientId === clientId && row.revoked !== true) {
+      await write('access_token', row.id, 'access_token.revoke', { revoked: true, rev: nextRev(root, 'access_token', row.id) }, opts);
+    }
+  }
+  for (const row of readType(root, 'refresh_token')) {
+    if (row.sub === sub && row.clientId === clientId && row.revoked !== true) {
+      await write('refresh_token', row.id, 'refresh_token.revoke', { revoked: true, rev: nextRev(root, 'refresh_token', row.id) }, opts);
+    }
+  }
+  // …and the GRANT itself goes with them. Google's revocation "removes all scopes granted to the
+  // project", which is why a later re-consent behaves as a FIRST authorization and hands back a
+  // refresh token. Leaving the row's scopes in place made the twin withhold one (§9 round one).
+  const grantId = `${clientId}:${sub}`;
+  if (readOne(root, 'grant', grantId)) {
+    await write('grant', grantId, 'grant.revoke', { clientId, sub, scopes: [], rev: nextRev(root, 'grant', grantId) }, opts);
+  }
+  // Google answers a successful revocation with 200 and an EMPTY body.
+  return { status: 200, body: {}, headers: { ...NOSTORE } };
+}
+
+function tokeninfo(req: GoogleOAuthRequest, query: URLSearchParams): GoogleOAuthResponse {
+  const root = req.root;
+  const accessToken = query.get('access_token');
+  const idToken = query.get('id_token');
+  if (!accessToken && !idToken) return oauthError('invalid_request', 'Invalid Value', 400);
+  if (idToken) {
+    // The id_token branch is a filed todo (`googleoauth.tokeninfo.id_token`) rather than a fake:
+    // answering it needs the token DECODED and its claims re-emitted, which the twin can do, but
+    // the vendor's exact field set for this branch has not been grounded.
+    return oauthError('invalid_token', 'Invalid Value', 400);
+  }
+  const row = readOne(root, 'access_token', accessToken!);
+  if (!row || row.revoked === true) return oauthError('invalid_token', 'Invalid Value', 400);
+  const now = nowSeconds(req.occurredAt);
+  if (typeof row.expiresAt === 'number' && now >= row.expiresAt) return oauthError('invalid_token', 'Invalid Value', 400);
+  const account = readOne(root, 'account', String(row.sub));
+  const scopes = parseScopeParam(String(row.scope));
+  const wantsEmail = scopes.includes('email') || scopes.includes('https://www.googleapis.com/auth/userinfo.email');
+  return {
+    status: 200,
+    body: {
+      azp: row.clientId,
+      aud: row.clientId,
+      sub: row.sub,
+      scope: row.scope,
+      exp: String(row.expiresAt),
+      expires_in: String(Math.max(0, Number(row.expiresAt) - now)),
+      access_type: row.accessType ?? 'online',
+      ...(wantsEmail && account ? { email: account.email, email_verified: String(account.emailVerified === true) } : {}),
+    },
+    headers: { ...NOSTORE },
+  };
+}
+
+/**
+ * The userinfo endpoints — and a fidelity trap worth spelling out: THE TWO HOSTS DISAGREE ON THEIR
+ * ERROR BODY. Captured live on 2026-08-20 with a bad credential:
+ *
+ *   openidconnect.googleapis.com/v1/userinfo → 401 {"error":"invalid_request",
+ *                                                   "error_description":"Invalid Credentials"}
+ *   www.googleapis.com/oauth2/v3/userinfo    → 401 {"error":"invalid_token",
+ *                                                   "error_description":"Invalid Value"}
+ *
+ * Neither is the `{ error: { code, message, status } }` Google-API envelope a reader would predict
+ * from the rest of googleapis.com. A twin that normalised the two into one shape would be hiding a
+ * real difference an integration can trip over.
+ */
+function userinfoUnauthorized(path: string): GoogleOAuthResponse {
+  return path === '/v1/userinfo'
+    ? oauthError('invalid_request', 'Invalid Credentials', 401)
+    : oauthError('invalid_token', 'Invalid Value', 401);
+}
+
+function userinfo(req: GoogleOAuthRequest, path: string, query: URLSearchParams): GoogleOAuthResponse {
+  const root = req.root;
+  const header = req.headers?.authorization ?? '';
+  const bearer = /^bearer\s+(.+)$/i.exec(header)?.[1]?.trim() ?? query.get('access_token');
+  if (!bearer) return userinfoUnauthorized(path);
+  const row = readOne(root, 'access_token', bearer);
+  if (!row || row.revoked === true) return userinfoUnauthorized(path);
+  if (typeof row.expiresAt === 'number' && nowSeconds(req.occurredAt) >= row.expiresAt) return userinfoUnauthorized(path);
+  const scopes = parseScopeParam(String(row.scope));
+  const hasIdentityScope = scopes.some((s) =>
+    s === 'openid' || s === 'email' || s === 'profile'
+    || s === 'https://www.googleapis.com/auth/userinfo.email'
+    || s === 'https://www.googleapis.com/auth/userinfo.profile');
+  if (!hasIdentityScope) {
+    // A token with no identity scope has no right to a profile, so the twin REFUSES rather than
+    // serving one — never a fake success. Google's EXACT answer for this case was not captured, so
+    // the twin reuses the credential-rejection envelope above rather than inventing a third shape;
+    // `googleoauth.userinfo.insufficient_scope_shape` is the filed todo for pinning it down.
+    return userinfoUnauthorized(path);
+  }
+  const account = readOne(root, 'account', String(row.sub));
+  if (!account) return apiError(404, 'Requested entity was not found.', 'NOT_FOUND');
+  return { status: 200, body: { sub: account.id, ...profileClaims(account, scopes) }, headers: { ...NOSTORE } };
+}
+
+/**
+ * The OIDC discovery document. Every URL is rendered against `origin` when the caller supplied one,
+ * so a DISCOVERY-DRIVEN client (openid-client) that reads this document stays inside the twin
+ * instead of walking back out to the real Google — the single most important property of this
+ * endpoint for a sealed world.
+ */
+export function discoveryDocument(origin?: string): Record<string, unknown> {
+  const accounts = origin ?? ACCOUNTS_ORIGIN;
+  const oauth2 = origin ?? OAUTH2_ORIGIN;
+  const apis = origin ?? APIS_ORIGIN;
+  const oidc = origin ?? OIDC_ORIGIN;
+  return {
+    issuer: ISSUER,
+    authorization_endpoint: `${accounts}/o/oauth2/v2/auth`,
+    device_authorization_endpoint: `${oauth2}/device/code`,
+    token_endpoint: `${oauth2}/token`,
+    userinfo_endpoint: `${oidc}/v1/userinfo`,
+    revocation_endpoint: `${oauth2}/revoke`,
+    jwks_uri: `${apis}/oauth2/v3/certs`,
+    response_types_supported: ['code', 'token', 'id_token', 'code token', 'code id_token', 'token id_token', 'code token id_token', 'none'],
+    subject_types_supported: ['public'],
+    id_token_signing_alg_values_supported: ['RS256'],
+    scopes_supported: ['openid', 'email', 'profile'],
+    token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic'],
+    claims_supported: ['aud', 'email', 'email_verified', 'exp', 'family_name', 'given_name', 'iat', 'iss', 'name', 'picture', 'sub'],
+    code_challenge_methods_supported: ['plain', 'S256'],
+    grant_types_supported: ['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:device_code', 'urn:ietf:params:oauth:grant-type:jwt-bearer'],
+  };
+}
+
+/** Every VENDOR endpoint this twin claims to serve. The conformance check drives one real request
+ *  per entry and grades the OUTCOME, so an entry here is a promise with teeth. Twin-only routes
+ *  (`/_twin/*`) are deliberately absent — they are scaffolding, not vendor surface. */
+export function googleOAuthTwinSnapshot(): { implementedEndpoints: string[]; resourceTypes: readonly string[]; grantTypes: string[] } {
+  return {
+    implementedEndpoints: [
+      'GET /.well-known/openid-configuration',
+      'GET /oauth2/v3/certs',
+      'GET /oauth2/v1/certs',
+      'GET /o/oauth2/v2/auth',
+      'GET /o/oauth2/auth',
+      'GET /o/oauth2/v2/auth/oauthchooseaccount',
+      'GET /signin/oauth/error',
+      'POST /token',
+      'POST /oauth2/v4/token',
+      'POST /o/oauth2/token',
+      'POST /revoke',
+      'GET /revoke',
+      'GET /tokeninfo',
+      'GET /v1/userinfo',
+      'POST /v1/userinfo',
+      'GET /oauth2/v3/userinfo',
+      'POST /oauth2/v3/userinfo',
+    ],
+    resourceTypes: STORE_RESOURCE_TYPES,
+    grantTypes: ['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:jwt-bearer'],
+  };
+}
+
+// ── twin-only control routes (NOT vendor surface — see the manifest) ────────────────────────────
+
+async function twinControl(req: GoogleOAuthRequest, path: string, form: URLSearchParams): Promise<GoogleOAuthResponse | null> {
+  const root = req.root;
+  const opts = { root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) };
+  const json = () => {
+    try {
+      return JSON.parse(req.body ?? '{}') as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  };
+  // STEP 2 of the screen: the account chooser's GET submit lands here with the chosen `sub`.
+  if (req.method === 'GET' && path === '/_twin/consent') {
+    const { query } = splitPath(req.path);
+    return renderConsent(req, query.get('auth_request') ?? '', query.get('sub'));
+  }
+  if (req.method === 'POST' && path === '/_twin/consent') return consentDecision(req, form);
+  if (req.method === 'POST' && path === '/_twin/clients') {
+    const b = json();
+    if (!b || typeof b.client_id !== 'string' || !b.client_id) return oauthError('invalid_request', 'client_id is required', 400);
+    const row = await write(
+      'oauth_client',
+      b.client_id,
+      'oauth_client.create',
+      {
+        name: typeof b.name === 'string' ? b.name : 'Twin App',
+        secret: typeof b.client_secret === 'string' ? b.client_secret : `GOCSPX-${b.client_id.slice(0, 20)}`,
+        redirectUris: Array.isArray(b.redirect_uris) ? b.redirect_uris : [],
+        clientType: b.client_type === 'installed' ? 'installed' : 'web',
+        supportEmail: typeof b.support_email === 'string' ? b.support_email : 'support@twin.example',
+        verified: b.verified === true,
+        rev: nextRev(root, 'oauth_client', b.client_id),
+      },
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  if (req.method === 'POST' && path === '/_twin/accounts') {
+    const b = json();
+    if (!b || typeof b.sub !== 'string' || !b.sub) return oauthError('invalid_request', 'sub is required', 400);
+    const row = await write(
+      'account',
+      b.sub,
+      'account.create',
+      {
+        email: typeof b.email === 'string' ? b.email : `${b.sub}@twin.example`,
+        emailVerified: b.email_verified !== false,
+        name: typeof b.name === 'string' ? b.name : 'Twin Persona',
+        givenName: typeof b.given_name === 'string' ? b.given_name : 'Twin',
+        familyName: typeof b.family_name === 'string' ? b.family_name : 'Persona',
+        picture: typeof b.picture === 'string' ? b.picture : `https://lh3.googleusercontent.com/a/${b.sub}`,
+        ...(typeof b.hd === 'string' ? { hd: b.hd } : {}),
+        rev: nextRev(root, 'account', b.sub),
+      },
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  return null;
+}
+
+// ── public entry + router ───────────────────────────────────────────────────────────────────────
+
+export async function handleGoogleOAuthTwinRequest(req: GoogleOAuthRequest): Promise<GoogleOAuthResponse> {
+  try {
+    return await routeGoogleOAuthTwinRequest(req);
+  } catch (e) {
+    // MALFORMED-REQUEST GUARD (route boundary), the gemini precedent: a residual TypeError (a
+    // wrong-typed field the router walked) or URIError (bad percent-encoding in the query) becomes
+    // the vendor's own 400 envelope instead of escaping as a non-vendor HTML 500. Every OTHER error
+    // type still propagates loudly rather than being masked as a caller mistake.
+    if (e instanceof TypeError || e instanceof URIError) {
+      return oauthError('invalid_request', 'Request contains an invalid argument.', 400);
+    }
+    throw e;
+  }
+}
+
+async function routeGoogleOAuthTwinRequest(req: GoogleOAuthRequest): Promise<GoogleOAuthResponse> {
+  const method = req.method.toUpperCase();
+  const { path, query } = splitPath(req.path);
+  const form = new URLSearchParams(method === 'GET' || method === 'HEAD' ? '' : (req.body ?? ''));
+
+  // ── stateless reads, safe on a read-only twin ──
+  if (method === 'GET' && path === '/.well-known/openid-configuration') {
+    return { status: 200, body: discoveryDocument(req.origin) };
+  }
+  // v1 (PEM) and v3 (JWK) ONLY. An earlier version also answered `/oauth2/v2/certs`, which Google
+  // does not publish — invented surface, removed (§9 round one).
+  if (method === 'GET' && path === '/oauth2/v3/certs') {
+    return { status: 200, body: await buildJwks(req.root) };
+  }
+  if (method === 'GET' && path === '/oauth2/v1/certs') {
+    return { status: 200, body: await buildLegacyPemCerts(req.root) };
+  }
+  // The error page every authorization failure is bounced to. A pure read — safe read-only.
+  if (method === 'GET' && path === ERROR_PAGE_PATH) return signinOAuthErrorPage(req, query);
+
+  // D3: a read-only twin cannot mint credentials, so every leg of the flow is refused. This is a
+  // TWIN-level refusal (Google has no read-only mode), deliberately shaped as an OAuth error body
+  // so a client sees a protocol error rather than an HTML surprise.
+  const writes = AUTH_PATHS.has(path) || path.startsWith('/_twin/') || path === '/token'
+    || path === '/oauth2/v4/token' || path === '/o/oauth2/token' || path === '/revoke';
+  if (req.readOnly && writes) {
+    return oauthError('temporarily_unavailable', 'this twin was started read-only; omit readOnly to accept writes', 405);
+  }
+
+  // Seeding is idempotent and cheap; doing it at the router boundary means every entry point sees a
+  // world with a client and personas in it, exactly as a browser signed in to Google would.
+  if (!req.readOnly) await ensureSeed({ root: req.root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), ...((req.callbackOrigin ?? req.origin) ? { origin: req.callbackOrigin ?? req.origin } : {}) });
+
+  const control = await twinControl(req, path, form);
+  if (control) return control;
+
+  if (method === 'GET' && AUTH_PATHS.has(path)) return authorize(req, query);
+  if (method === 'POST' && (path === '/token' || path === '/oauth2/v4/token' || path === '/o/oauth2/token')) return token(req);
+  if (path === '/revoke' && (method === 'POST' || method === 'GET')) {
+    // The token may arrive in the FORM BODY or in the QUERY STRING, on either method.
+    // `google-auth-library`'s own `revokeToken()` issues `POST /revoke?token=…` with an EMPTY body
+    // (oauth2client.js) — a body-only reading of this endpoint refuses the vendor's own client,
+    // which is exactly the bug the SDK fidelity test caught.
+    return revoke(req, form.get('token') ?? query.get('token'));
+  }
+  if (method === 'GET' && path === '/tokeninfo') return tokeninfo(req, query);
+  // `/oauth2/v2/userinfo` is NOT served: it is Google's oldest alias and returns a DIFFERENT field
+  // set, which this twin does not model (`googleoauth.endpoints.userinfo_v2`, todo). Answering it
+  // with the v3 shape would be a fake success on a route the pack itself says is unmodelled
+  // (§9 round one).
+  if ((method === 'GET' || method === 'POST') && (path === '/v1/userinfo' || path === '/oauth2/v3/userinfo')) {
+    return userinfo(req, path, query);
+  }
+
+  // An operation the twin does not model fails like the vendor — never a fake success. Google's own
+  // 404 on these hosts is the API error envelope.
+  if (AUTH_PATHS.has(path) || path === '/token' || path === '/revoke' || path === '/tokeninfo') {
+    return apiError(405, `Method ${method} is not supported on ${path}.`, 'FAILED_PRECONDITION');
+  }
+  return apiError(404, `The requested URL ${path} was not found on this server.`, 'NOT_FOUND');
+}