@volter/twin-googleoauth 0.1.0

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

@@ -0,0 +1,78 @@
+import { type TwinResource } from '@volter/world-core';
+export declare const SERVICE = "googleoauth";
+export declare const RESOURCE_TYPES: readonly ["oauth_client", "account", "auth_request", "authorization_code", "access_token", "refresh_token", "grant"];
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+export type Row = TwinResource & Record<string, any>;
+export declare function readAll(root: string | undefined): Row[];
+export declare function readType(root: string | undefined, type: ResourceType): Row[];
+export declare function readOne(root: string | undefined, type: ResourceType, id: string): Row | undefined;
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export declare function nextRev(root: string | undefined, type: ResourceType, id: string): number;
+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 declare function write(type: ResourceType, id: string, operation: string, fields: Record<string, unknown>, opts: WriteOpts): Promise<Row>;
+/** `4/0A…` — Google's authorization codes. `subject` is the consent screen this code settles. */
+export declare const mintAuthorizationCode: (root: string | undefined, instant: string, subject: string) => string;
+/** `ya29.…` — Google's OAuth 2.0 access tokens. `subject` is the code or refresh token exchanged. */
+export declare const mintAccessToken: (root: string | undefined, instant: string, subject: string) => string;
+/** `1//0…` — Google's refresh tokens. `subject` is the code the grant was exchanged from. */
+export declare const mintRefreshToken: (root: string | undefined, instant: string, subject: string) => string;
+/**
+ * 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 declare function authRequestIdFor(root: string | undefined, occurredAt: string, fields: Record<string, unknown>): string;
+export declare const DEFAULT_CLIENT_ID = "1044839207-twindemoapp0000000000000000000.apps.googleusercontent.com";
+export declare 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 declare const DEFAULT_ACCOUNTS: SeedAccount[];
+/**
+ * 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 declare function defaultRedirectUris(origin?: string): string[];
+/**
+ * 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 declare function ensureSeed(opts: SeedOpts): Promise<void>;
+/** Every account the chooser can offer, oldest-seeded first (a stable screen order). */
+export declare function listAccounts(root: string | undefined): Row[];
+/**
+ * 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 declare function redirectUriAllowed(client: Row, candidate: string): boolean;

package/dist/src/googleoauth-store.js

@@ -0,0 +1,313 @@
+// 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 } from '@volter/world-core';
+export const SERVICE = 'googleoauth';
+export const RESOURCE_TYPES = [
+    'oauth_client',
+    'account',
+    'auth_request',
+    'authorization_code',
+    'access_token',
+    'refresh_token',
+    'grant',
+];
+export function readAll(root) {
+    return projectResources(SERVICE, root);
+}
+export function readType(root, type) {
+    return readAll(root).filter((r) => r.type === type);
+}
+export function readOne(root, type, id) {
+    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, type, id) {
+    const existing = readOne(root, type, id);
+    return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+export async function write(type, id, operation, fields, opts) {
+    const { resource } = await applyTwinWrite(SERVICE, {
+        operation,
+        subjectType: type,
+        subjectId: id,
+        fields,
+        ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, opts.root);
+    return resource;
+}
+// ── 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, type, instant, subject) {
+    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, 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, instant, subject) => `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, instant, subject) => `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, instant, subject) => `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, n) {
+    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',
+];
+function authRequestSignature(fields) {
+    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, occurredAt, fields) {
+    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';
+/** Google's `sub` is a stable 21-digit numeric string; these are deterministic stand-ins. */
+export const DEFAULT_ACCOUNTS = [
+    {
+        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) {
+    const base = (origin ?? '').trim().replace(/\/+$/, '');
+    if (!base)
+        return [];
+    let u;
+    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) {
+    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) {
+    const existing = readAll(opts.root);
+    const has = (type, id) => 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) {
+    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, candidate) {
+    const registered = 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, candidate) {
+    let a, b;
+    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) => 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;
+}

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

@@ -0,0 +1,53 @@
+export { RESOURCE_TYPES } from './googleoauth-store.js';
+/** Google's real hosts, used when a caller does not tell the twin its own origin. */
+export declare const ACCOUNTS_ORIGIN = "https://accounts.google.com";
+export declare const OAUTH2_ORIGIN = "https://oauth2.googleapis.com";
+export declare const APIS_ORIGIN = "https://www.googleapis.com";
+export declare const OIDC_ORIGIN = "https://openidconnect.googleapis.com";
+/** The `iss` Google puts in every id_token. (Google historically also used the bare
+ *  `accounts.google.com`; verifiers accept both, and this twin issues the URL form.) */
+export declare const ISSUER = "https://accounts.google.com";
+export type GoogleOAuthRequest = {
+    method: string;
+    /** Path plus query string, e.g. `/o/oauth2/v2/auth?client_id=…`. */
+    path: string;
+    body?: string;
+    /** Lower-cased request headers (authorization / content-type). */
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /**
+     * Where this twin is reached (`twinPublicBase`: origin plus any served-World mount path). The
+     * DISCOVERY document, the auth-error redirect and the consent page's own form action have to
+     * point back at the twin or a discovery-driven client (openid-client) would follow them out to
+     * the real Google. Absent — an in-process call — the
+     * document is rendered with Google's REAL endpoint URLs, which is the vendor-faithful answer.
+     */
+    origin?: string;
+    /** The bare origin the request arrived at, when it differs from `origin` (a served World mounts
+     *  the twin under a path). The seeded demo app's callbacks derive from it; defaults to `origin`. */
+    callbackOrigin?: string;
+};
+export type GoogleOAuthResponse = {
+    status: number;
+    /** A JSON-serialisable object, or a STRING when the response is an HTML page. */
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/**
+ * The OIDC discovery document. Every URL is rendered against `origin` when the caller supplied one,
+ * so a DISCOVERY-DRIVEN client (openid-client) that reads this document stays inside the twin
+ * instead of walking back out to the real Google — the single most important property of this
+ * endpoint for a sealed world.
+ */
+export declare function discoveryDocument(origin?: string): Record<string, unknown>;
+/** Every VENDOR endpoint this twin claims to serve. The conformance check drives one real request
+ *  per entry and grades the OUTCOME, so an entry here is a promise with teeth. Twin-only routes
+ *  (`/_twin/*`) are deliberately absent — they are scaffolding, not vendor surface. */
+export declare function googleOAuthTwinSnapshot(): {
+    implementedEndpoints: string[];
+    resourceTypes: readonly string[];
+    grantTypes: string[];
+};
+export declare function handleGoogleOAuthTwinRequest(req: GoogleOAuthRequest): Promise<GoogleOAuthResponse>;