@volter/twin-googleoauth 0.1.0

package/dist/src/googleoauth-consent-ui.d.ts

@@ -0,0 +1,25 @@
+import { type ConsentView, type ErrorPageProps } from '../client/googleoauth-consent.js';
+export type { ConsentAccount, ConsentScopeRow, ConsentView } from '../client/googleoauth-consent.js';
+export { GOOGLEOAUTH_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, GOOGLEOAUTH_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from './googleoauth-consent-client.gen.js';
+/** 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 declare const CONSENT_SCRIPT_PATH = "/_twin/assets/consent.js";
+export declare const CONSENT_STYLE_PATH = "/_twin/assets/consent.css";
+/**
+ * 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 declare 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;
+/** Render the consent (or account-chooser) page from a view model. */
+export declare function consentPageHtml(view: ConsentView, base?: string): string;
+/** Render the vendor's browser error page (an un-redirectable failure). */
+export declare function errorPageHtml(props: ErrorPageProps, base?: string): string;

package/dist/src/googleoauth-consent-ui.js

@@ -0,0 +1,102 @@
+// 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, } from "../client/googleoauth-consent.js";
+import { describeScopes, isGranularlyDeclinable, parseScopeParam, sortScopesForConsent } from "./googleoauth-scopes.js";
+import { listAccounts, readOne } from "./googleoauth-store.js";
+export { GOOGLEOAUTH_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, GOOGLEOAUTH_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from "./googleoauth-consent-client.gen.js";
+/** 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) {
+    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) {
+    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 = 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, bodyMarkup, base) {
+    // 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) {
+    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, base = '') {
+    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, base = '') {
+    return page(`Error ${props.status}: ${props.code}`, renderToStaticMarkup(createElement(ErrorPage, props)), base);
+}

package/dist/src/googleoauth-jwt.d.ts

@@ -0,0 +1,78 @@
+export type GoogleOAuthKeypair = {
+    kid: string;
+    publicKeyPem: string;
+    privateKeyPem: string;
+};
+export type KeypairMaterial = {
+    publicKeyPem: string;
+    privateKeyPem: string;
+};
+export type KeypairGenerator = () => KeypairMaterial;
+/** Override how `ensureKeypair` mints a new keypair; pass `null` to restore the node:crypto default. */
+export declare function setKeypairGenerator(generator: KeypairGenerator | null): void;
+/**
+ * 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 declare function ensureKeypair(root?: string): Promise<GoogleOAuthKeypair>;
+export declare function base64url(input: Buffer | string): string;
+/**
+ * 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 declare function signJwt(claims: Record<string, unknown>, opts?: {
+    root?: string;
+    expiresInSeconds?: number;
+    now?: number;
+}): Promise<string>;
+/** The decoded parts of a JWT (NO verification). */
+export declare function decodeJwt(token: string): {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+};
+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 declare function verifyJwtWithJwks(token: string, jwks: Jwks, opts?: {
+    now?: number;
+}): {
+    valid: boolean;
+    payload?: Record<string, unknown>;
+    reason?: string;
+};
+/** Build the JWKS document served at /oauth2/v3/certs — Google's real shape, from the SAME
+ *  persisted key used to sign. */
+export declare function buildJwks(root?: string): Promise<Jwks>;
+/**
+ * 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 declare function buildLegacyPemCerts(root?: string): Promise<Record<string, string>>;
+/**
+ * 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 declare function atHash(accessToken: string): string;
+/** PKCE S256 transform: BASE64URL(SHA256(ASCII(code_verifier))) — RFC 7636 §4.2. */
+export declare function pkceS256(codeVerifier: string): string;

package/dist/src/googleoauth-jwt.js

@@ -0,0 +1,183 @@
+// 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';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+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';
+function nodeGenerateKeypair() {
+    const { generateKeyPairSync } = nodeCrypto();
+    const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    return { publicKeyPem: publicKey, privateKeyPem: privateKey };
+}
+// 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 }; // 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.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) {
+    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) {
+    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) {
+    return Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function base64urlJson(obj) {
+    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, opts = {}) {
+    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) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('malformed jwt');
+    const dec = (s) => JSON.parse(Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+    return { header: dec(parts[0]), payload: dec(parts[1]) };
+}
+/**
+ * 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, jwks, opts = {}) {
+    const { createVerify, createPublicKey } = nodeCrypto();
+    let header, payload, parts;
+    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) {
+    const { createPublicKey } = nodeCrypto();
+    const { kid, publicKeyPem } = await ensureKeypair(root);
+    const jwk = createPublicKey(publicKeyPem).export({ format: 'jwk' });
+    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) {
+    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) {
+    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) {
+    const { createHash } = nodeCrypto();
+    return base64url(createHash('sha256').update(codeVerifier, 'ascii').digest());
+}

package/dist/src/googleoauth-scopes.d.ts

@@ -0,0 +1,36 @@
+export type ScopeInfo = {
+    /** The scope string a client requests. */
+    scope: string;
+    /** The consent-screen sentence Google shows for it. */
+    label: string;
+    /** Google's own grouping — OIDC scopes are shown above the granular product scopes. */
+    group: 'openid' | 'product';
+    /** Google marks a subset "sensitive"/"restricted"; those show the extra review notice. */
+    sensitivity?: 'sensitive' | 'restricted';
+};
+/** The three OIDC scopes, which Google treats specially (they mint id_token claims). */
+export declare const OIDC_SCOPES: readonly ["openid", "email", "profile"];
+export declare const SCOPE_CATALOG: ScopeInfo[];
+/** Split a `scope` parameter the way OAuth 2.0 does — space-delimited, order preserved, deduped. */
+export declare function parseScopeParam(raw: string | null | undefined): string[];
+/** Render a scope list back to the wire form Google echoes in `scope` responses. */
+export declare function formatScopeParam(scopes: readonly string[]): string;
+/**
+ * The consent-screen row for one scope. An UNKNOWN scope is shown with its raw string as the
+ * label (see the honesty note above) and flagged so the caller can tell the two apart.
+ */
+export declare function describeScope(scope: string): ScopeInfo & {
+    known: boolean;
+};
+/** Every requested scope, in request order, described for the consent screen. */
+export declare function describeScopes(scopes: readonly string[]): Array<ScopeInfo & {
+    known: boolean;
+}>;
+/** Google shows the OIDC ("Associate you with…") rows above the granular product rows. */
+export declare function sortScopesForConsent(scopes: readonly string[]): string[];
+/**
+ * Granular consent: Google lets a user UNCHECK individual non-OIDC scopes, and the resulting grant
+ * carries only what was ticked. The OIDC scopes are not individually declinable — they ride with
+ * signing in — so they are always returned.
+ */
+export declare function isGranularlyDeclinable(scope: string): boolean;

package/dist/src/googleoauth-scopes.js

@@ -0,0 +1,92 @@
+// Google OAuth scope catalog — the SCOPE STRINGS Google publishes
+// (developers.google.com/identity/protocols/oauth2/scopes) paired with the human sentence its
+// consent screen shows for each ("See your primary Google Account email address", …).
+//
+// This file is PURE data + pure functions and is imported by the browser consent client as well as
+// the server, so it must stay free of `@volter/world-core`, `node:*` and Bun.
+//
+// HONESTY NOTE. Google's scope list is ~400 entries long and grows with every product; this
+// catalog carries the OIDC core scopes plus the scopes real integrations actually request (the
+// Cal.com/Dub calendar+contacts+drive families). An UNKNOWN scope is NOT an error — Google accepts
+// any scope string a project has enabled — so the twin renders an unknown scope with its raw
+// string rather than inventing a description for it. Fabricating a friendly sentence for a scope
+// we have not read from the vendor would be exactly the "serving surface the vendor doesn't have"
+// false-green ADDING_A_TWIN.md §6 warns about.
+/** The three OIDC scopes, which Google treats specially (they mint id_token claims). */
+export const OIDC_SCOPES = ['openid', 'email', 'profile'];
+export const SCOPE_CATALOG = [
+    { scope: 'openid', label: 'Associate you with your personal info on Google', group: 'openid' },
+    { scope: 'email', label: 'See your primary Google Account email address', group: 'openid' },
+    { scope: 'profile', label: 'See your personal info, including any personal info you\'ve made publicly available', group: 'openid' },
+    { scope: 'https://www.googleapis.com/auth/userinfo.email', label: 'See your primary Google Account email address', group: 'openid' },
+    { scope: 'https://www.googleapis.com/auth/userinfo.profile', label: 'See your personal info, including any personal info you\'ve made publicly available', group: 'openid' },
+    // Calendar — the family every scheduling integration (Cal.com has 12 OAuth integrations) asks for.
+    { scope: 'https://www.googleapis.com/auth/calendar', label: 'See, edit, share, and permanently delete all the calendars you can access using Google Calendar', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/calendar.readonly', label: 'See and download any calendar you can access using your Google Calendar', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/calendar.events', label: 'View and edit events on all your calendars', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/calendar.events.readonly', label: 'View events on all your calendars', group: 'product', sensitivity: 'sensitive' },
+    // Drive.
+    { scope: 'https://www.googleapis.com/auth/drive', label: 'See, edit, create, and delete all of your Google Drive files', group: 'product', sensitivity: 'restricted' },
+    { scope: 'https://www.googleapis.com/auth/drive.file', label: 'See, edit, create, and delete only the specific Google Drive files you use with this app', group: 'product' },
+    { scope: 'https://www.googleapis.com/auth/drive.readonly', label: 'See and download all your Google Drive files', group: 'product', sensitivity: 'restricted' },
+    // Gmail.
+    { scope: 'https://www.googleapis.com/auth/gmail.readonly', label: 'Read all resources and their metadata—no write operations', group: 'product', sensitivity: 'restricted' },
+    { scope: 'https://www.googleapis.com/auth/gmail.send', label: 'Send email on your behalf', group: 'product', sensitivity: 'sensitive' },
+    // Contacts / directory.
+    { scope: 'https://www.googleapis.com/auth/contacts.readonly', label: 'See and download your contacts', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/directory.readonly', label: 'See and download your organization\'s GSuite directory', group: 'product', sensitivity: 'sensitive' },
+    // Spreadsheets — the other integration workhorse.
+    { scope: 'https://www.googleapis.com/auth/spreadsheets', label: 'See, edit, create, and delete all your Google Sheets spreadsheets', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/spreadsheets.readonly', label: 'See all your Google Sheets spreadsheets', group: 'product', sensitivity: 'sensitive' },
+    // YouTube — the sibling twin in this repo.
+    { scope: 'https://www.googleapis.com/auth/youtube.readonly', label: 'View your YouTube account', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/youtube.upload', label: 'Manage your YouTube videos', group: 'product', sensitivity: 'sensitive' },
+    // Cloud — what a service-account / Vertex flow asks for.
+    { scope: 'https://www.googleapis.com/auth/cloud-platform', label: 'See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account', group: 'product', sensitivity: 'sensitive' },
+    { scope: 'https://www.googleapis.com/auth/devstorage.read_write', label: 'Manage your data in Cloud Storage and see the email address of your Google Account', group: 'product', sensitivity: 'sensitive' },
+];
+const BY_SCOPE = new Map(SCOPE_CATALOG.map((s) => [s.scope, s]));
+/** Split a `scope` parameter the way OAuth 2.0 does — space-delimited, order preserved, deduped. */
+export function parseScopeParam(raw) {
+    if (typeof raw !== 'string')
+        return [];
+    const out = [];
+    for (const piece of raw.split(/[\s+]+/)) {
+        if (piece && !out.includes(piece))
+            out.push(piece);
+    }
+    return out;
+}
+/** Render a scope list back to the wire form Google echoes in `scope` responses. */
+export function formatScopeParam(scopes) {
+    return scopes.join(' ');
+}
+/**
+ * The consent-screen row for one scope. An UNKNOWN scope is shown with its raw string as the
+ * label (see the honesty note above) and flagged so the caller can tell the two apart.
+ */
+export function describeScope(scope) {
+    const known = BY_SCOPE.get(scope);
+    if (known)
+        return { ...known, known: true };
+    return { scope, label: scope, group: 'product', known: false };
+}
+/** Every requested scope, in request order, described for the consent screen. */
+export function describeScopes(scopes) {
+    return scopes.map(describeScope);
+}
+/** Google shows the OIDC ("Associate you with…") rows above the granular product rows. */
+export function sortScopesForConsent(scopes) {
+    const described = describeScopes(scopes);
+    return [...described].sort((a, b) => (a.group === b.group ? 0 : a.group === 'openid' ? -1 : 1)).map((s) => s.scope);
+}
+/**
+ * Granular consent: Google lets a user UNCHECK individual non-OIDC scopes, and the resulting grant
+ * carries only what was ticked. The OIDC scopes are not individually declinable — they ride with
+ * signing in — so they are always returned.
+ */
+export function isGranularlyDeclinable(scope) {
+    return !OIDC_SCOPES.includes(scope)
+        && scope !== 'https://www.googleapis.com/auth/userinfo.email'
+        && scope !== 'https://www.googleapis.com/auth/userinfo.profile';
+}

package/dist/src/googleoauth-server.d.ts

@@ -0,0 +1,34 @@
+/** Options every Google-OAuth-twin HTTP surface needs, independent of who owns the socket. */
+export interface GoogleOAuthTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createGoogleOAuthTwinServer`
+ * is nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only clock on
+ * the path is `worldNow()`, the world's frozen instant. The consent screen's own script and
+ * stylesheet routes serve COMMITTED text (`googleoauth-consent-client.gen.ts`, built on the dev
+ * plane by `scripts/consent-clients.ts`) — no build and no disk read on the fetch path.
+ */
+export declare function createGoogleOAuthTwinFetch(options?: GoogleOAuthTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createGoogleOAuthTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/**
+ * The consent screen is served BY THE TWIN, at the vendor's own path — there is no second "mirror"
+ * server to start, and pretending otherwise would imply a second renderer. This alias exists so the
+ * `world-googleoauth mirror` command and the journey harness have the conventional entry point,
+ * and it returns the very same server.
+ */
+export declare const createGoogleOAuthConsentServer: typeof createGoogleOAuthTwinServer;

package/dist/src/googleoauth-server.js

@@ -0,0 +1,89 @@
+// Google OAuth twin HTTP server — one server for the WHOLE vendor surface, because Google's OAuth
+// is one product spread over four hostnames. Point `accounts.google.com`, `oauth2.googleapis.com`,
+// `www.googleapis.com/oauth2/*` and `openidconnect.googleapis.com` here (the injector's
+// `googleoauth` VENDOR_HOSTS entry does exactly that) and an unmodified OAuth client completes a
+// full authorization-code round trip against it.
+//
+// Two things this server does that a JSON-only twin server does not:
+//   • it can answer with HTML and with 302 redirects — the consent screen and the callback bounce
+//     are the protocol, not decoration, so the handler's `headers` (content-type, location) are
+//     passed straight through rather than being flattened into a JSON envelope;
+//   • it serves the consent page's own assets under the twin-namespaced `/_twin/assets/*`.
+//
+// It also tells the handler its OWN origin, so the OIDC discovery document and the consent form's
+// action point BACK AT THE TWIN. Without that a discovery-driven client (openid-client) would read
+// the document and walk straight out to the real accounts.google.com.
+import { serveHttp } from '@volter/world-core';
+import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from "./googleoauth-consent-ui.js";
+import { worldNow, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
+import { handleGoogleOAuthTwinRequest } from "./googleoauth-twin.js";
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createGoogleOAuthTwinServer`
+ * is nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only clock on
+ * the path is `worldNow()`, the world's frozen instant. The consent screen's own script and
+ * stylesheet routes serve COMMITTED text (`googleoauth-consent-client.gen.ts`, built on the dev
+ * plane by `scripts/consent-clients.ts`) — no build and no disk read on the fetch path.
+ */
+export function createGoogleOAuthTwinFetch(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    return async function googleOAuthTwinFetch(request) {
+        const url = new URL(request.url);
+        // GET /twin — the discovery manifest (education inside the twin).
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(statefulTwinManifest({ vendor: 'googleoauth', twinOf: 'Google OAuth 2.0 / OpenID Connect', stores: 'authorization codes, tokens and RS256 id_tokens minted by the full code round trip' }));
+        }
+        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 = {};
+        request.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        const res = await handleGoogleOAuthTwinRequest({
+            method: request.method,
+            path: url.pathname + (url.search || ''),
+            body,
+            headers,
+            readOnly,
+            occurredAt: worldNow(),
+            origin: twinPublicBase(request),
+            callbackOrigin: url.origin,
+            ...(options.root !== undefined ? { root: options.root } : {}),
+        });
+        const out = { ...(res.headers ?? {}) };
+        // A string body is already rendered (HTML, or the empty body of a 302); anything else is the
+        // vendor's JSON.
+        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 });
+    };
+}
+export async function createGoogleOAuthTwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createGoogleOAuthTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+/**
+ * The consent screen is served BY THE TWIN, at the vendor's own path — there is no second "mirror"
+ * server to start, and pretending otherwise would imply a second renderer. This alias exists so the
+ * `world-googleoauth mirror` command and the journey harness have the conventional entry point,
+ * and it returns the very same server.
+ */
+export const createGoogleOAuthConsentServer = createGoogleOAuthTwinServer;