@volter/twin-googleoauth 0.1.0

package/src/googleoauth-scopes.ts

@@ -0,0 +1,109 @@
+// 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.
+
+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 const OIDC_SCOPES = ['openid', 'email', 'profile'] as const;
+
+export const SCOPE_CATALOG: ScopeInfo[] = [
+  { 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: string | null | undefined): string[] {
+  if (typeof raw !== 'string') return [];
+  const out: string[] = [];
+  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: readonly string[]): string {
+  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: string): ScopeInfo & { known: boolean } {
+  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: readonly string[]): Array<ScopeInfo & { known: boolean }> {
+  return scopes.map(describeScope);
+}
+
+/** Google shows the OIDC ("Associate you with…") rows above the granular product rows. */
+export function sortScopesForConsent(scopes: readonly string[]): string[] {
+  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: string): boolean {
+  return !(OIDC_SCOPES as readonly string[]).includes(scope)
+    && scope !== 'https://www.googleapis.com/auth/userinfo.email'
+    && scope !== 'https://www.googleapis.com/auth/userinfo.profile';
+}

package/src/googleoauth-server.ts

@@ -0,0 +1,101 @@
+// 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.ts';
+import { worldNow, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
+import { handleGoogleOAuthTwinRequest } from './googleoauth-twin.ts';
+
+/** 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 function createGoogleOAuthTwinFetch(options: GoogleOAuthTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  return async function googleOAuthTwinFetch(request: Request): Promise<Response> {
+    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: 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,
+      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: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  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;

package/src/googleoauth-store.ts

@@ -0,0 +1,359 @@
+// Google OAuth twin — STATE. Everything the twin knows lives in the shared kernel action log
+// (D1): OAuth clients, the Google accounts a user can choose between, pending authorization
+// requests, authorization codes, access/refresh tokens and the per-(client, user) grant record.
+// There is no parallel store.
+//
+// ID MINTING (ADDING_A_TWIN.md §5): every id is either the vendor's own natural key (a client_id,
+// an account `sub`) or MINTED HERE. The minted ones used to be ENTROPIC (`randomUUID`) — never a
+// module counter and never a row count, the collision class three packs' §9 reviews each found
+// independently. Every one of them is also SERVED: the `ar_` consent handle is rendered into the
+// screen, the `4/0A` code rides the callback redirect, the `ya29.`/`1//0` tokens ride the /token
+// reply. Runtime contract R9 (a served response is a pure function of (request, stored state) —
+// no clock and no randomness in served content) therefore governs all of them, and entropy is
+// exactly the defect it names, so they are ALL minted the resend way now: a stable hash of the
+// world instant + the number of rows of that type the store already holds (soft-deleted rows
+// counted, so a value can never recur) + the subject it is issued for.
+//
+// §5's count-mint hazard — a pulled vendor id sitting in a GAP above the row count, which local
+// creates then walk into and clobber — cannot arise here: these types are twin-internal or
+// twin-issued, no connector pulls one, and the count is a hash SEED rather than the id itself.
+// What §5's entropy bought (two writes at one instant never colliding) the count buys instead:
+// it advances on every mint, so `googleoauth-twin.test.ts`'s "two grants in the same millisecond
+// mint DIFFERENT credentials" holds by construction rather than by luck.
+//
+// The `ar_` handle carries one extra rule the credentials do not: an authorize request whose
+// parameters already name an UNSETTLED pending row reuses that row's id, so re-serving the same
+// consent screen is byte-identical (and a reload does not pile up a second pending request).
+//
+// The one state shape that DOES revisit values is the mutable-in-place kind: a code being consumed,
+// a token being revoked, a grant's scope set being re-granted with the same scopes. Those carry a
+// per-subject `rev` ordinal (the upstash precedent) so a genuine write can never be mistaken
+// for a replay.
+import { applyTwinWrite, projectResources, type TwinResource } from '@volter/world-core';
+
+export const SERVICE = 'googleoauth';
+
+export const RESOURCE_TYPES = [
+  'oauth_client',
+  'account',
+  'auth_request',
+  'authorization_code',
+  'access_token',
+  'refresh_token',
+  'grant',
+] as const;
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+
+export type Row = TwinResource & Record<string, any>;
+
+export function readAll(root: string | undefined): Row[] {
+  return projectResources(SERVICE, root) as Row[];
+}
+export function readType(root: string | undefined, type: ResourceType): Row[] {
+  return readAll(root).filter((r) => r.type === type);
+}
+export function readOne(root: string | undefined, type: ResourceType, id: string): Row | undefined {
+  return readAll(root).find((r) => r.type === type && r.id === id);
+}
+
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export function nextRev(root: string | undefined, type: ResourceType, id: string): number {
+  const existing = readOne(root, type, id);
+  return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+
+export type WriteOpts = { root?: string; occurredAt?: string };
+/** Seeding also needs the origin the twin was reached on, so the demo client's registered
+ *  callbacks point back at THIS twin rather than at a baked-in port (runtime contract R7). */
+export type SeedOpts = WriteOpts & { origin?: string };
+
+export async function write(
+  type: ResourceType,
+  id: string,
+  operation: string,
+  fields: Record<string, unknown>,
+  opts: WriteOpts,
+): Promise<Row> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    {
+      operation,
+      subjectType: type,
+      subjectId: id,
+      fields,
+      ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+      actor: { kind: 'agent' },
+    },
+    opts.root,
+  );
+  return resource as Row;
+}
+
+// ── vendor-shaped credential minting: DETERMINISTIC, because it is SERVED (R9) ──────────────
+// Google's opaque credentials have RECOGNISABLE prefixes and an integrator's code often keys on
+// them (a `ya29.` access token, a `1//` refresh token, a `4/0A` auth code). The twin reproduces the
+// prefix and the LENGTH — the shape is vendor surface, the bytes are not.
+//
+// The bytes used to be `randomUUID()` entropy, and every one of them is SERVED (the code rides the
+// callback redirect, the tokens ride the /token reply), so R9 governs them exactly as it governs
+// the `ar_` handle below. They are now the resend pattern: 32 bytes of `stableHex` over
+// (type, world instant, rows of that type held BEFORE the insert, the subject being issued for),
+// base64url-ed and sliced to the vendor's length — the SAME construction as before, with the
+// entropy source swapped for a pure hash, so the shape is byte-for-byte what it was.
+//
+// A twin's credentials are stand-ins, not secrets: determinism is the contract, and predictability
+// from public state is not a threat model a twin has. UNIQUENESS is, and the seed carries it: the
+// row COUNT advances on every mint, so two credentials of one type at one instant differ even when
+// the subject is identical (`googleoauth-twin.test.ts` — "two grants in the same millisecond mint
+// DIFFERENT credentials"), and the subject separates concurrent exchanges.
+
+/** The seed every credential is minted from. `readType` is unfiltered (soft-deletes counted), so a
+ *  count — and therefore a credential — can never recur for one (type, instant, subject). */
+function credentialSeed(root: string | undefined, type: ResourceType, instant: string, subject: string): string {
+  return `${type}:${instant}:${readType(root, type).length}:${subject}`;
+}
+
+/** base64url over 32 hashed bytes, sliced to the vendor's length (unchanged from the entropic
+ *  version — only the byte source moved from `randomUUID` to `stableHex`). */
+const opaque = (seed: string, bytes = 24) =>
+  Buffer.from(stableHex(seed, 64), 'hex')
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .slice(0, bytes);
+
+/** `4/0A…` — Google's authorization codes. `subject` is the consent screen this code settles. */
+export const mintAuthorizationCode = (root: string | undefined, instant: string, subject: string): string =>
+  `4/0A${opaque(credentialSeed(root, 'authorization_code', instant, subject), 40)}`;
+/** `ya29.…` — Google's OAuth 2.0 access tokens. `subject` is the code or refresh token exchanged. */
+export const mintAccessToken = (root: string | undefined, instant: string, subject: string): string =>
+  `ya29.${opaque(credentialSeed(root, 'access_token', instant, subject), 64)}`;
+/** `1//0…` — Google's refresh tokens. `subject` is the code the grant was exchanged from. */
+export const mintRefreshToken = (root: string | undefined, instant: string, subject: string): string =>
+  `1//0${opaque(credentialSeed(root, 'refresh_token', instant, subject), 48)}`;
+
+// ── the consent screen's handle: DETERMINISTIC, because it is SERVED (R9) ───────────────────
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+function stableHex(seed: string, n: number): string {
+  let out = '';
+  for (let round = 0; out.length < n; round += 1) {
+    let h = 0x811c9dc5;
+    const s = `${round}:${seed}`;
+    for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+    out += h.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, n);
+}
+
+/** Every authorize parameter an `auth_request` row holds — its stable identity. Read off the
+ *  fields being written OR off a projected row (the key set is the same on both). */
+const AUTH_REQUEST_SIG_KEYS = [
+  'clientId', 'redirectUri', 'scope', 'state', 'nonce', 'accessType', 'prompt', 'loginHint',
+  'includeGrantedScopes', 'codeChallenge', 'codeChallengeMethod',
+] as const;
+function authRequestSignature(fields: Record<string, unknown>): string {
+  return AUTH_REQUEST_SIG_KEYS.map((k) => `${k}=${String(fields[k] ?? '')}`).join('\u0001');
+}
+
+/**
+ * Twin-internal handle for a consent screen in flight (never leaves the twin's own pages) —
+ * `ar_` + 32 hex, the shape `randomUUID()` gave it, now a pure function of (request, stored state).
+ *
+ * An authorize request whose parameters ALREADY name an unsettled pending row reuses that row's
+ * id: pressing reload on a consent screen is the same screen, not a new one. Otherwise the id is
+ * `stableHex(auth_request:<world instant>:<rows already held>)` — two authorize requests at one
+ * instant differ by the count, and two identical worlds mint identical ids.
+ */
+export function authRequestIdFor(root: string | undefined, occurredAt: string, fields: Record<string, unknown>): string {
+  const prior = readType(root, 'auth_request');
+  const signature = authRequestSignature(fields);
+  const reusable = prior.find((r) => r.settled !== true && authRequestSignature(r) === signature);
+  if (reusable) return String(reusable.id);
+  return `ar_${stableHex(`auth_request:${occurredAt}:${prior.length}`, 32)}`;
+}
+
+// ── seeded world ────────────────────────────────────────────────────────────────────────────
+// A twin has to have SOMETHING to consent as. Google's own account chooser lists the Google
+// accounts signed in to the browser; the twin's equivalent is a small set of deterministic
+// personas seeded into kernel state on first use, and `POST /_twin/accounts` adds more. The
+// default OAuth client mirrors the shape the Google Cloud console hands out (a `.apps.
+// googleusercontent.com` client_id and a `GOCSPX-` secret).
+
+export const DEFAULT_CLIENT_ID = '1044839207-twindemoapp0000000000000000000.apps.googleusercontent.com';
+export const DEFAULT_CLIENT_SECRET = 'GOCSPX-twin0000000000000000000000';
+
+export type SeedAccount = {
+  sub: string;
+  email: string;
+  name: string;
+  givenName: string;
+  familyName: string;
+  picture: string;
+  emailVerified: boolean;
+  hd?: string;
+};
+
+/** Google's `sub` is a stable 21-digit numeric string; these are deterministic stand-ins. */
+export const DEFAULT_ACCOUNTS: SeedAccount[] = [
+  {
+    sub: '100000000000000000001',
+    email: 'ada.lovelace@gmail.com',
+    name: 'Ada Lovelace',
+    givenName: 'Ada',
+    familyName: 'Lovelace',
+    picture: 'https://lh3.googleusercontent.com/a/twin-ada',
+    emailVerified: true,
+  },
+  {
+    sub: '100000000000000000002',
+    email: 'grace.hopper@navy.example',
+    name: 'Grace Hopper',
+    givenName: 'Grace',
+    familyName: 'Hopper',
+    picture: 'https://lh3.googleusercontent.com/a/twin-grace',
+    emailVerified: true,
+    hd: 'navy.example',
+  },
+];
+
+/** NextAuth's callback path — the one every Google integration guide walks a reader through. */
+const CALLBACK_PATH = '/api/auth/callback/google';
+/** Google's out-of-band redirect for installed apps: an URN, so it carries no host at all. */
+const OOB_REDIRECT = 'urn:ietf:wg:oauth:2.0:oob';
+
+/**
+ * Every spelling of the ORIGIN this twin was reached on that a browser could hand back.
+ *
+ * Google matches redirect URIs EXACTLY, and it treats `localhost` and the loopback IP as different
+ * hosts (see `redirectUriAllowed` below) — while a local app is reachable as BOTH on the same port.
+ * A demo registration that named only one of them would fail half the time for a reason the
+ * developer cannot see, so the seed registers both spellings of whatever origin it was reached on.
+ */
+function originSpellings(origin?: string): string[] {
+  const base = (origin ?? '').trim().replace(/\/+$/, '');
+  if (!base) return [];
+  let u: URL;
+  try { u = new URL(base); } catch { return [base]; }
+  if (u.protocol !== 'http:') return [base];
+  const port = u.port ? `:${u.port}` : '';
+  if (u.hostname === 'localhost') return [base, `http://127.0.0.1${port}`];
+  if (u.hostname === '127.0.0.1') return [base, `http://localhost${port}`];
+  return [base];
+}
+
+/**
+ * The redirect URIs the seeded demo client registers.
+ *
+ * Runtime contract R7: a twin NEVER bakes a port into served content or config. The callbacks are
+ * DERIVED from the origin the twin was actually reached on (`GoogleOAuthRequest.origin`, which
+ * googleoauth-server fills from the URL the request arrived at). A caller that declares no origin
+ * — an in-process call — gets the host-free out-of-band URN only, and registers whatever callbacks
+ * it wants through `POST /_twin/clients`.
+ */
+export function defaultRedirectUris(origin?: string): string[] {
+  return [...originSpellings(origin).map((base) => `${base}${CALLBACK_PATH}`), OOB_REDIRECT];
+}
+
+/**
+ * Materialise the default client + accounts once per root. Idempotent by subject id: re-running it
+ * over a seeded root writes nothing new, and it NEVER overwrites an operator-registered client or
+ * account (an existing subject id is left exactly as it is).
+ */
+export async function ensureSeed(opts: SeedOpts): Promise<void> {
+  const existing = readAll(opts.root);
+  const has = (type: ResourceType, id: string) => existing.some((r) => r.type === type && r.id === id);
+  if (!has('oauth_client', DEFAULT_CLIENT_ID)) {
+    await write(
+      'oauth_client',
+      DEFAULT_CLIENT_ID,
+      'oauth_client.create',
+      {
+        name: 'Twin Demo App',
+        secret: DEFAULT_CLIENT_SECRET,
+        redirectUris: defaultRedirectUris(opts.origin),
+        clientType: 'web',
+        supportEmail: 'support@twin.example',
+        verified: false,
+        rev: 1,
+      },
+      opts,
+    );
+  }
+  for (const account of DEFAULT_ACCOUNTS) {
+    if (has('account', account.sub)) continue;
+    await write(
+      'account',
+      account.sub,
+      'account.create',
+      {
+        email: account.email,
+        emailVerified: account.emailVerified,
+        name: account.name,
+        givenName: account.givenName,
+        familyName: account.familyName,
+        picture: account.picture,
+        ...(account.hd ? { hd: account.hd } : {}),
+        rev: 1,
+      },
+      opts,
+    );
+  }
+}
+
+/** Every account the chooser can offer, oldest-seeded first (a stable screen order). */
+export function listAccounts(root: string | undefined): Row[] {
+  return readType(root, 'account');
+}
+
+/**
+ * Is `candidate` an EXACT registered redirect URI for this client? Google matches redirect URIs
+ * exactly (scheme, host, port and path all compared literally; a trailing slash is a different
+ * URI), which is precisely why `redirect_uri_mismatch` is the single most common integration
+ * error. A twin that matched loosely would hide every one of those bugs.
+ *
+ * The one documented exception is the loopback-IP flow for installed apps: Google ignores the PORT
+ * for `http://127.0.0.1` / `http://[::1]` redirect URIs, because the app binds an ephemeral port.
+ */
+export function redirectUriAllowed(client: Row, candidate: string): boolean {
+  const registered: string[] = Array.isArray(client.redirectUris) ? client.redirectUris : [];
+  // A FRAGMENT is refused outright, before any comparison. Google documents that a redirect URI may
+  // not contain one, and an exact-string match alone did not catch it: the loopback branch below
+  // compares protocol/host/path/search and never looked at `hash`, so
+  // `http://127.0.0.1:3000/cb#evil` was accepted against a registration of `http://127.0.0.1:3000/cb`
+  // (§9 round two). A fragment is attacker-controlled and never reaches the server, which is
+  // exactly why it is banned.
+  if (candidate.includes('#')) return false;
+  // USERINFO (`http://user:pass@host/…`) likewise: Google forbids the subcomponent, and the
+  // loopback branch never compared it either.
+  if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(candidate)) return false;
+  if (registered.includes(candidate)) return true;
+  return registered.some((uri) => loopbackEquivalent(uri, candidate));
+}
+
+function loopbackEquivalent(registered: string, candidate: string): boolean {
+  let a: URL, b: URL;
+  try {
+    a = new URL(registered);
+    b = new URL(candidate);
+  } catch {
+    return false;
+  }
+  if (a.protocol !== 'http:' || b.protocol !== 'http:') return false;
+  // The exception is documented for the loopback IP LITERALS only (`http://127.0.0.1:<port>` and
+  // `http://[::1]:<port>` — an installed app binds a random available port). `localhost` is NOT in
+  // that list: Google treats it as an ordinary host string that must match exactly, port included.
+  // `URL` normalises `[::1]` to the bracketed form in `hostname`, so both spellings land here.
+  const loopbackIp = (h: string) => h === '127.0.0.1' || h === '[::1]';
+  if (!loopbackIp(a.hostname) || !loopbackIp(b.hostname)) return false;
+  // The CANDIDATE's host must be the literal Google documents, not merely something WHATWG `URL`
+  // normalises to it. `URL` folds `0177.0.0.1`, `2130706433` and `127.1` all onto `127.0.0.1`, so
+  // reading `.hostname` alone accepted three spellings Google's exact-match rule does not
+  // (§9 round two). Compare the raw authority the caller actually sent.
+  const rawHost = /^https?:\/\/([^/?#]*)/i.exec(candidate)?.[1] ?? '';
+  const rawName = rawHost.replace(/:\d+$/, '');
+  if (rawName !== '127.0.0.1' && rawName !== '[::1]') return false;
+  // Only the PORT is forgiven — the host and path still have to agree exactly.
+  return a.hostname === b.hostname && a.pathname === b.pathname && a.search === b.search;
+}