@volter/twin-googleoauth 0.1.0

package/src/googleoauth-consent-ui.ts

@@ -0,0 +1,124 @@
+// Google OAuth twin — the SERVER HALF of the consent screen.
+//
+// Named `-consent-ui` rather than `-mirror-ui` on purpose, and that name IS the class doctrine: a
+// dashboard mirror is a SECOND renderer this repo writes over a vendor's data, whereas this is the
+// vendor's OWN page, on the vendor's OWN path, in the middle of the vendor's OWN protocol. The
+// mirror DISCIPLINE still applies in full — one renderer, data-coupled to the projection, driven by
+// a real browser journey — but calling it a mirror would misdescribe what it is.
+//
+// The pieces:
+//   • `googleOAuthConsentState` — THE STATE BUILDER. Everything on screen is derived here, from the
+//     kernel projection, and nowhere else. It is the seam `scripts/mutation-test.ts` sabotages in
+//     the mirror phase (TWIN-20/B9): with it dead the screen has no app name, no accounts and no
+//     scopes, so every UI capability must go red while the write/handler path stays real.
+//   • `consentPageHtml` / `errorPageHtml` — server-render the REAL exported React components with
+//     `renderToStaticMarkup`. There is no template string of markup anywhere: what the browser gets
+//     IS the component tree the verifies assert over.
+//   • `CONSENT_CLIENT_JS` / `CONSENT_CLIENT_CSS` — the browser bundle and stylesheet as COMMITTED TEXT
+//     (`googleoauth-consent-client.gen.ts`, written by `scripts/consent-clients.ts` and drift-gated):
+//     progressive enhancement only, and the serve path never builds (runtime contract R12b, R9).
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import {
+  ConsentPage,
+  ErrorPage,
+  type ConsentAccount,
+  type ConsentScopeRow,
+  type ConsentView,
+  type ErrorPageProps,
+} from '../client/googleoauth-consent.tsx';
+import { describeScopes, isGranularlyDeclinable, parseScopeParam, sortScopesForConsent } from './googleoauth-scopes.ts';
+import { listAccounts, readOne, type Row } from './googleoauth-store.ts';
+
+export type { ConsentAccount, ConsentScopeRow, ConsentView } from '../client/googleoauth-consent.tsx';
+export { GOOGLEOAUTH_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, GOOGLEOAUTH_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from './googleoauth-consent-client.gen.ts';
+
+/** Twin-only asset paths. Google serves its consent assets from accounts.google.com too, but under
+ *  paths we have not read; these are clearly namespaced so they can never be mistaken for vendor
+ *  surface. */
+export const CONSENT_SCRIPT_PATH = '/_twin/assets/consent.js';
+export const CONSENT_STYLE_PATH = '/_twin/assets/consent.css';
+
+function toConsentAccount(row: Row): ConsentAccount {
+  return {
+    sub: row.id,
+    email: String(row.email ?? ''),
+    name: String(row.name ?? ''),
+    givenName: String(row.givenName ?? ''),
+    picture: String(row.picture ?? ''),
+    ...(row.hd ? { hd: String(row.hd) } : {}),
+  };
+}
+
+/**
+ * THE STATE BUILDER — the consent screen's entire view model, folded out of the kernel projection.
+ *
+ * Returns `null` when the authorization request is unknown (the caller renders the vendor's error
+ * page); it never invents an app name, an account or a scope row.
+ */
+export function googleOAuthConsentState(opts: {
+  root?: string;
+  requestId: string;
+  /** Present ⇒ render the CONSENT step for that account; absent ⇒ the account CHOOSER. */
+  sub?: string | null;
+  origin: string;
+}): ConsentView | null {
+  const authRequest = readOne(opts.root, 'auth_request', opts.requestId);
+  if (!authRequest) return null;
+  const client = readOne(opts.root, 'oauth_client', String(authRequest.clientId));
+  if (!client) return null;
+
+  const accounts = listAccounts(opts.root).map(toConsentAccount);
+  const requested = sortScopesForConsent(parseScopeParam(String(authRequest.scope ?? '')));
+  const scopes: ConsentScopeRow[] = describeScopes(requested).map((s) => ({
+    scope: s.scope,
+    label: s.label,
+    group: s.group,
+    ...(s.sensitivity ? { sensitivity: s.sensitivity } : {}),
+    known: s.known,
+    declinable: isGranularlyDeclinable(s.scope),
+  }));
+
+  const account = opts.sub ? accounts.find((a) => a.sub === opts.sub) : undefined;
+  return {
+    step: account ? 'consent' : 'choose',
+    requestId: opts.requestId,
+    origin: opts.origin,
+    app: {
+      clientId: client.id,
+      name: String(client.name ?? ''),
+      supportEmail: String(client.supportEmail ?? ''),
+      verified: client.verified === true,
+    },
+    accounts,
+    scopes,
+    ...(account ? { account } : {}),
+  };
+}
+
+/** `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount path),
+ *  so the page's assets resolve inside the World's mount; empty for an in-process render. */
+function page(title: string, bodyMarkup: string, base: string): string {
+  // The `<title>` is read by the bundled client (`hydrateConsentControls`) to name the app in the
+  // granular-consent hint, so it carries the app name exactly as Google's own tab title does.
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title><link rel="stylesheet" href="${base}${CONSENT_STYLE_PATH}"></head>
+<body>${bodyMarkup}<script type="module" src="${base}${CONSENT_SCRIPT_PATH}"></script></body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Render the consent (or account-chooser) page from a view model. */
+export function consentPageHtml(view: ConsentView, base = ''): string {
+  const markup = renderToStaticMarkup(createElement(ConsentPage, { view }));
+  const title = view.step === 'choose' ? `${view.app.name} — Choose an account` : `${view.app.name} — Sign in with Google`;
+  return page(title, markup, base);
+}
+
+/** Render the vendor's browser error page (an un-redirectable failure). */
+export function errorPageHtml(props: ErrorPageProps, base = ''): string {
+  return page(`Error ${props.status}: ${props.code}`, renderToStaticMarkup(createElement(ErrorPage, props)), base);
+}

package/src/googleoauth-journey.uitest.ts

@@ -0,0 +1,296 @@
+// GOOGLE OAUTH UI JOURNEY — the consent leg, driven in a real headless chromium.
+//
+// This is what makes the pack browser-facing rather than merely browser-shaped. Every other twin's
+// journey navigates a DASHBOARD; this one performs the vendor's actual protocol with a browser as
+// the protocol participant: the app redirects, a human picks an account, reads what is being asked,
+// clicks Continue (or Cancel), and the browser is bounced back to the app's callback carrying a
+// code — which the test then REDEEMS at the twin's token endpoint. A journey that stopped at "the
+// screen rendered" would prove the page exists; this one proves the round trip closes.
+//
+// Seeds through the pack's OWN write path (the twin's client/account control routes and the real
+// authorization endpoint — never a hand-written events.jsonl), boots the real twin server on an
+// ephemeral port with the app's callback page alongside it (see `startJourneyServer`), and drives
+// it with role/text locators only.
+//
+// Every step writes a filmstrip frame (the harness helpers do it), so a reviewer can LOOK at the
+// screens rather than trusting a green tick.
+import { describe, expect, test } from 'bun:test';
+import { atPath, clickByName, requireBrowser, runUiJourney, visible } from '@volter/world-tooling';
+import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from './googleoauth-consent-ui.ts';
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_SECRET } from './googleoauth-store.ts';
+import { handleGoogleOAuthTwinRequest } from './googleoauth-twin.ts';
+
+const JOURNEY_LABEL = 'googleoauth UI journey';
+
+const CLIENT_ID = 'journeyapp.apps.googleusercontent.com';
+const APP_NAME = 'Twin Journey Scheduler';
+const SCOPE = 'openid email profile https://www.googleapis.com/auth/calendar.readonly';
+const ADA = DEFAULT_ACCOUNTS[0]!;
+const GRACE = DEFAULT_ACCOUNTS[1]!;
+/** The integrating app's callback, served on the same loopback origin (see `startJourneyServer`). */
+const APP_CALLBACK_PATH = '/oauth/callback';
+
+/**
+ * The journey's server: the REAL twin handler, plus a tiny `/oauth/callback` page standing in for
+ * the integrating app.
+ *
+ * WHY THEY SHARE ONE ORIGIN. The journey harness is loopback-only and installs a route guard that
+ * ABORTS any request leaving the server origin it was given (`uiJourney.ts`) — so a callback server
+ * on its own port is unreachable from the piloted page, and the OAuth bounce would simply never
+ * arrive. Putting the app's callback on the same loopback origin is a harness accommodation, not a
+ * fidelity claim: in a real deployment the app is a different origin, and the twin does not care —
+ * the redirect it emits is an absolute URL either way, and the SDK fidelity test
+ * (`googleoauth-sdk.integration.test.ts`) exercises the cross-origin form. What the journey proves
+ * is the leg only a browser can: a human's clicks turning into a code on the app's callback URL.
+ */
+function startJourneyServer(root: string): { url: string; stop: () => void; last: () => URL | null } {
+  let last: URL | null = null;
+  const server = Bun.serve({
+    port: 0,
+    idleTimeout: 30,
+    async fetch(request) {
+      const url = new URL(request.url);
+
+      // ── the harness's landing page ──
+      // `runUiJourney` navigates to the server URL and waits for `#root` to have children before it
+      // hands the page over. A vendor twin has no app shell at `/` (accounts.google.com's root is
+      // Google's own account page, which this pack does not model), so the JOURNEY supplies one.
+      // It is test scaffolding in this file — never pack surface.
+      if (url.pathname === '/') {
+        return new Response(
+          `<!doctype html><html><body><div id="root"><h1>Twin OAuth world</h1>`
+            + `<p>the ${APP_NAME} integration starts by redirecting to accounts.google.com</p></div></body></html>`,
+          { headers: { 'content-type': 'text/html; charset=utf-8' } },
+        );
+      }
+
+      // ── the app's callback ──
+      if (url.pathname === APP_CALLBACK_PATH) {
+        last = url;
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        const body = code
+          ? `<h1>${APP_NAME}</h1><p>authorization code received</p><pre>${code}</pre>`
+          : `<h1>${APP_NAME}</h1><p>authorization failed</p><pre>${error ?? 'no error parameter'}</pre>`;
+        return new Response(`<!doctype html><html><body>${body}</body></html>`, {
+          headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
+      }
+
+      // ── everything else: the real twin ──
+      if (request.method === 'GET' && url.pathname === CONSENT_SCRIPT_PATH) {
+        return new Response(CONSENT_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && url.pathname === CONSENT_STYLE_PATH) {
+        return new Response(CONSENT_CLIENT_CSS, { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+      const res = await handleGoogleOAuthTwinRequest({
+        method: request.method,
+        path: url.pathname + (url.search || ''),
+        body,
+        headers,
+        root,
+        occurredAt: new Date().toISOString(),
+        origin: url.origin,
+      });
+      const out = { ...(res.headers ?? {}) };
+      if (typeof res.body === 'string') {
+        if (!out['content-type'] && res.body) out['content-type'] = 'text/html; charset=utf-8';
+        return new Response(res.body, { status: res.status, headers: out });
+      }
+      out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
+      return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
+    },
+  });
+  return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop(true), last: () => last };
+}
+
+/** Register the journey's OAuth client through the twin's own write path. */
+async function seedClient(twinOrigin: string, redirectUri: string) {
+  const res = await fetch(`${twinOrigin}/_twin/clients`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      client_id: CLIENT_ID,
+      client_secret: DEFAULT_CLIENT_SECRET,
+      name: APP_NAME,
+      support_email: 'dev@journey.test',
+      redirect_uris: [redirectUri],
+    }),
+  });
+  expect(res.status).toBe(200);
+}
+
+const authUrl = (twinOrigin: string, redirectUri: string, extra: Record<string, string> = {}) =>
+  `${twinOrigin}/o/oauth2/v2/auth?${new URLSearchParams({
+    client_id: CLIENT_ID,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: SCOPE,
+    state: 'journey-state-1',
+    access_type: 'offline',
+    prompt: 'consent',
+    ...extra,
+  })}`;
+
+describe('googleoauth UI journey', () => {
+  test('a human picks an account, reads the scopes, clicks Continue — and the code redeems', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    // Captured inside the journey while the server is still up; asserted after teardown, so a
+    // torn-down fixture can never read as a product failure.
+    let redeemed: Record<string, any> | null = null;
+    let verified: Record<string, any> | null = null;
+    let callback: URL | null = null;
+
+    await runUiJourney({
+      label: 'googleoauth consent round trip',
+      // The pack's write path IS its HTTP server, and the harness calls `seed` BEFORE `serve` — so
+      // the client registration happens as the journey's first step instead of here.
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+
+        // 1. The app redirects the browser to the vendor. What lands is the ACCOUNT CHOOSER,
+        //    naming the registered app and every seeded persona.
+        await page.goto(authUrl(origin, redirectUri));
+        await atPath(page, '/o/oauth2/v2/auth');
+        await visible(page, 'Sign in with Google');
+        await visible(page, 'Choose an account');
+        await visible(page, APP_NAME);
+        await visible(page, ADA.name);
+        await visible(page, ADA.email);
+        await visible(page, GRACE.name);
+
+        // 2. Picking an account is a real submit — the URL changes, which is what proves the click
+        //    navigated rather than merely re-rendering.
+        await clickByName(page, new RegExp(ADA.name));
+        await atPath(page, '/_twin/consent');
+
+        // 3. The consent screen names the app, the CHOSEN account, and the scopes in Google's own
+        //    wording — those sentences come from the twin's scope catalog, not the raw strings.
+        await visible(page, `${APP_NAME} wants access to your Google Account`);
+        await visible(page, ADA.email);
+        await visible(page, `Select what ${APP_NAME} can access`);
+        await visible(page, 'See your primary Google Account email address');
+        await visible(page, 'See and download any calendar you can access using your Google Calendar');
+        // …and the unverified-app notice, because this client is not marked verified.
+        await visible(page, "Google hasn't verified this app");
+
+        // 4. Continue. The browser leaves the vendor's path and lands on the APP's callback.
+        await clickByName(page, 'Continue');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization code received');
+
+        callback = new URL(page.url());
+        const code = callback.searchParams.get('code')!;
+
+        // 5. THE POINT OF THE WHOLE FLOW: the code a browser CLICK produced is redeemable at the
+        //    token endpoint, and the access token it yields describes the account that was clicked.
+        const tokenRes = await fetch(`${origin}/token`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            client_id: CLIENT_ID,
+            client_secret: DEFAULT_CLIENT_SECRET,
+            redirect_uri: redirectUri,
+          }).toString(),
+        });
+        redeemed = (await tokenRes.json()) as Record<string, any>;
+
+        const userinfo = await fetch(`${origin}/v1/userinfo`, {
+          headers: { authorization: `Bearer ${redeemed.access_token}` },
+        });
+        verified = (await userinfo.json()) as Record<string, any>;
+      },
+    });
+
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(callback!.searchParams.get('code')!).toStartWith('4/0A');
+    expect(callback!.searchParams.get('scope')).toBe(SCOPE);
+    expect(redeemed!.access_token).toStartWith('ya29.');
+    expect(redeemed!.refresh_token).toStartWith('1//');
+    expect(redeemed!.id_token).toBeTruthy();
+    expect(redeemed!.scope).toBe(SCOPE);
+    // The account the human CLICKED is the subject the tokens describe — the click really chose it.
+    expect(verified!.sub).toBe(ADA.sub);
+    expect(verified!.email).toBe(ADA.email);
+  }, 30_000);
+
+  test('Cancel bounces back with error=access_denied and no code', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    let callback: URL | null = null;
+    await runUiJourney({
+      label: 'googleoauth consent denial',
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+
+        // Straight to the consent step via login_hint — Google skips the chooser for an account it
+        // already knows, and so does the twin.
+        await page.goto(authUrl(origin, redirectUri, { login_hint: GRACE.email }));
+        await visible(page, `${APP_NAME} wants access to your Google Account`);
+        await visible(page, GRACE.email);
+
+        await clickByName(page, 'Cancel');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization failed');
+        await visible(page, 'access_denied');
+        callback = new URL(page.url());
+      },
+    });
+
+    expect(callback!.searchParams.get('error')).toBe('access_denied');
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(callback!.searchParams.get('code')).toBeNull();
+  }, 30_000);
+
+  test('a misconfigured redirect_uri lands on Google\'s error page, NOT on the app', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    let finalUrl = '';
+    // The HANDLE, kept so the assertion can read it AFTER the journey. An earlier version read
+    // `server.last()` inside `serve` and stored the boolean — which is `false` by construction at
+    // that instant, so the assertion could never fail even if the twin had bounced the error
+    // straight to the app (§9 round two, MAJOR: a security assertion that could not fail).
+    let app: { last: () => URL | null } | null = null;
+    await runUiJourney({
+      label: 'googleoauth redirect_uri_mismatch error page',
+      seed: async () => {},
+      serve: (root) => {
+        const server = startJourneyServer(root);
+        app = server;
+        return server;
+      },
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        await seedClient(origin, `${origin}${APP_CALLBACK_PATH}`);
+
+        // The single most common Google integration bug, seen the way a developer sees it: the
+        // browser STAYS on the vendor showing the error, and the app is never reached.
+        await page.goto(authUrl(origin, `${origin}/oauth/WRONG`));
+        await atPath(page, '/signin/oauth/error');
+        await visible(page, "Access blocked: This app's request is invalid");
+        await visible(page, 'Error 400: redirect_uri_mismatch');
+        await visible(page, `If you are a developer of ${APP_NAME}, see error details.`);
+        finalUrl = page.url();
+      },
+    });
+
+    expect(new URL(finalUrl).pathname, 'the browser must end on the vendor error page').toBe('/signin/oauth/error');
+    // Read AFTER the journey: the app must never have been reached at all.
+    expect(app!.last(), 'the app callback must never have been called').toBeNull();
+  }, 30_000);
+});

package/src/googleoauth-jwt.ts

@@ -0,0 +1,207 @@
+// Google OAuth twin — REAL RS256 crypto (the clerk-jwt.ts precedent, adapted to Google's OIDC).
+//
+// Google's id_token is a genuine RS256 JWT signed by a key whose public half is published at
+// https://www.googleapis.com/oauth2/v3/certs. Every real relying party — `google-auth-library`'s
+// `verifyIdToken`, `openid-client`, NextAuth, passport-google-oidc — VERIFIES that signature
+// against that JWKS. A twin that emitted an `alg: none` stub would be refused by every one of
+// them, so the honest twin does what clerk does: generate an RSA-2048 keypair on first use,
+// PERSIST it in kernel state (so signing and the served JWKS are the SAME key and survive a
+// restart), sign real tokens, and serve a real JWKS.
+//
+// `node:crypto` is required LAZILY (inside the functions that use it), NOT as a top-level static
+// import, so this module can be pulled into the browser bundle of the consent client without Bun's
+// browser target choking on it — the signing helpers are server-only and never reached there.
+import { applyTwinWrite, projectResources, nodeBuiltin } from '@volter/world-core';
+
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+const SERVICE = 'googleoauth';
+// The keypair is stored as a single twin-internal resource so it persists in kernel state (the
+// SAME substrate the rest of the twin uses — no parallel store). `_`-prefixed fields are
+// twin-internal.
+const KEYPAIR_TYPE = '_keypair';
+const KEYPAIR_ID = 'googleoauth_signing_key';
+
+export type GoogleOAuthKeypair = { kid: string; publicKeyPem: string; privateKeyPem: string };
+export type KeypairMaterial = { publicKeyPem: string; privateKeyPem: string };
+export type KeypairGenerator = () => KeypairMaterial;
+
+function nodeGenerateKeypair(): KeypairMaterial {
+  const { generateKeyPairSync } = nodeCrypto();
+  const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKeyPem: publicKey as string, privateKeyPem: privateKey as string };
+}
+
+// Injectable keypair seam (the clerk `setKeypairGenerator` precedent): a host where RUNTIME RSA
+// keygen is not viable installs a provider returning a PRE-GENERATED keypair. The kid is still
+// derived from the public key by `kidFor`, so a stable baked key yields a STABLE kid.
+const keypairGenerator = { current: nodeGenerateKeypair as KeypairGenerator }; // a slot, not module truth (protocol 2)
+
+/** Override how `ensureKeypair` mints a new keypair; pass `null` to restore the node:crypto default. */
+export function setKeypairGenerator(generator: KeypairGenerator | null): void {
+  keypairGenerator.current = generator ?? nodeGenerateKeypair;
+}
+
+/**
+ * The twin's RSA signing keypair for `root`, generated + persisted on first use and stable
+ * thereafter — so signing and the served JWKS share ONE key. Deterministic `kid` derived from the
+ * public key's DER, so the JWKS `kid` matches the token header `kid` (what a verifier keys on).
+ */
+export async function ensureKeypair(root?: string): Promise<GoogleOAuthKeypair> {
+  const existing = projectResources(SERVICE, root).find((r) => r.type === KEYPAIR_TYPE && r.id === KEYPAIR_ID);
+  if (existing && typeof existing._privateKeyPem === 'string' && typeof existing._publicKeyPem === 'string') {
+    return { kid: String(existing._kid), publicKeyPem: existing._publicKeyPem, privateKeyPem: existing._privateKeyPem };
+  }
+  const { publicKeyPem, privateKeyPem } = keypairGenerator.current();
+  const kid = kidFor(publicKeyPem);
+  await applyTwinWrite(
+    SERVICE,
+    {
+      operation: '_keypair.create',
+      subjectType: KEYPAIR_TYPE,
+      subjectId: KEYPAIR_ID,
+      fields: { _kid: kid, _publicKeyPem: publicKeyPem, _privateKeyPem: privateKeyPem },
+      actor: { kind: 'system' },
+    },
+    root,
+  );
+  return { kid, publicKeyPem, privateKeyPem };
+}
+
+/** Stable key id = first 40 hex of SHA-1-length SHA-256 over the SPKI DER. Google's own kids are
+ *  opaque 40-hex strings, so the SHAPE is vendor-faithful as well as deterministic per key. */
+function kidFor(publicKeyPem: string): string {
+  const { createHash, createPublicKey } = nodeCrypto();
+  const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  return createHash('sha256').update(der).digest('hex').slice(0, 40);
+}
+
+export function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function base64urlJson(obj: unknown): string {
+  return base64url(JSON.stringify(obj));
+}
+
+/**
+ * Sign a JWT (RS256) with the twin's persisted private key. Header carries `alg`/`kid`/`typ`
+ * exactly as Google's does. Pure local crypto — no network.
+ */
+export async function signJwt(
+  claims: Record<string, unknown>,
+  opts: { root?: string; expiresInSeconds?: number; now?: number } = {},
+): Promise<string> {
+  const { createSign } = nodeCrypto();
+  const { kid, privateKeyPem } = await ensureKeypair(opts.root);
+  // `iat`/`exp` are SERVED (they ride inside the id_token this returns), so R9 governs them: the
+  // caller names the instant — `handleGoogleOAuthTwinRequest` passes the world instant the server
+  // stamped with `worldNow()`. The old `?? Math.floor(Date.now()/1000)` fallback put the host's
+  // wall clock into a signed token on any path that forgot to say when; it throws now.
+  if (opts.now === undefined) throw new Error('googleoauth signJwt: `now` is required — this twin has no clock of its own (pass the request\'s world instant)');
+  const iat = opts.now;
+  const exp = iat + (opts.expiresInSeconds ?? 3600);
+  const header = { alg: 'RS256', kid, typ: 'JWT' };
+  const payload = { ...claims, iat, exp };
+  const signingInput = `${base64urlJson(header)}.${base64urlJson(payload)}`;
+  const signer = createSign('RSA-SHA256');
+  signer.update(signingInput);
+  signer.end();
+  return `${signingInput}.${base64url(signer.sign(privateKeyPem))}`;
+}
+
+/** The decoded parts of a JWT (NO verification). */
+export function decodeJwt(token: string): { header: Record<string, unknown>; payload: Record<string, unknown> } {
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('malformed jwt');
+  const dec = (s: string) => JSON.parse(Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')) as Record<string, unknown>;
+  return { header: dec(parts[0]!), payload: dec(parts[1]!) };
+}
+
+export type Jwk = { kty: 'RSA'; use: 'sig'; alg: 'RS256'; kid: string; n: string; e: string };
+export type Jwks = { keys: Jwk[] };
+
+/**
+ * Verify a token's RS256 signature against a JWKS document (the SAME shape the twin serves at
+ * /oauth2/v3/certs) and check exp/nbf. This is what a relying party does to trust an id_token.
+ * Pure local crypto — no network.
+ */
+export function verifyJwtWithJwks(
+  token: string,
+  jwks: Jwks,
+  opts: { now?: number } = {},
+): { valid: boolean; payload?: Record<string, unknown>; reason?: string } {
+  const { createVerify, createPublicKey } = nodeCrypto();
+  let header: Record<string, unknown>, payload: Record<string, unknown>, parts: string[];
+  try {
+    parts = token.split('.');
+    if (parts.length !== 3) return { valid: false, reason: 'malformed' };
+    ({ header, payload } = decodeJwt(token));
+  } catch {
+    return { valid: false, reason: 'malformed' };
+  }
+  if (header.alg !== 'RS256') return { valid: false, reason: 'unexpected_alg' };
+  const key = jwks.keys.find((k) => k.kid === header.kid) ?? jwks.keys[0];
+  if (!key) return { valid: false, reason: 'no_matching_key' };
+  const publicKey = createPublicKey({ key: { kty: 'RSA', n: key.n, e: key.e }, format: 'jwk' });
+  const verifier = createVerify('RSA-SHA256');
+  verifier.update(`${parts[0]}.${parts[1]}`);
+  verifier.end();
+  const sig = Buffer.from(parts[2]!.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  if (!verifier.verify(publicKey, sig)) return { valid: false, reason: 'bad_signature' };
+  // The relying party names the instant it is verifying AT, for the same reason the signer does:
+  // this module is on the pack's serve-path import closure and holds no clock of its own.
+  if (opts.now === undefined) throw new Error('googleoauth verifyJwtWithJwks: `now` is required — this module has no clock of its own (pass the instant you are verifying at)');
+  const now = opts.now;
+  if (typeof payload.exp === 'number' && now >= payload.exp) return { valid: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return { valid: false, reason: 'not_yet_valid' };
+  return { valid: true, payload };
+}
+
+/** Build the JWKS document served at /oauth2/v3/certs — Google's real shape, from the SAME
+ *  persisted key used to sign. */
+export async function buildJwks(root?: string): Promise<Jwks> {
+  const { createPublicKey } = nodeCrypto();
+  const { kid, publicKeyPem } = await ensureKeypair(root);
+  const jwk = createPublicKey(publicKeyPem).export({ format: 'jwk' }) as { n?: string; e?: string };
+  return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid, n: String(jwk.n), e: String(jwk.e) }] };
+}
+
+/**
+ * Google's legacy PEM certificate endpoint (`/oauth2/v1/certs`) answers `{ "<kid>": "<PEM>" }`.
+ * `google-auth-library` still reads it when `certificateCacheFormat` is PEM, so the twin serves
+ * the SAME persisted key in that shape too rather than 404ing a documented endpoint.
+ *
+ * Google publishes X.509 CERTIFICATES there; the twin has no CA and refuses to fabricate a
+ * certificate chain, so it publishes the SPKI PUBLIC KEY PEM for the same key instead. That
+ * difference is stated in the README and filed as `googleoauth.certs.v1_x509_certificate` (todo)
+ * — never dressed up as a certificate.
+ */
+export async function buildLegacyPemCerts(root?: string): Promise<Record<string, string>> {
+  const { kid, publicKeyPem } = await ensureKeypair(root);
+  return { [kid]: publicKeyPem };
+}
+
+/**
+ * OIDC `at_hash` — base64url of the LEFT HALF of SHA-256(access_token). Google puts it in every
+ * id_token minted through the authorization-code flow, and `openid-client` VALIDATES it when
+ * present, so computing it wrong breaks a real client. (OpenID Connect Core 1.0 §3.1.3.6.)
+ */
+export function atHash(accessToken: string): string {
+  const { createHash } = nodeCrypto();
+  const digest = createHash('sha256').update(accessToken).digest();
+  return base64url(digest.subarray(0, digest.length / 2));
+}
+
+/** PKCE S256 transform: BASE64URL(SHA256(ASCII(code_verifier))) — RFC 7636 §4.2. */
+export function pkceS256(codeVerifier: string): string {
+  const { createHash } = nodeCrypto();
+  return base64url(createHash('sha256').update(codeVerifier, 'ascii').digest());
+}