@volter/twin-googleoauth 0.1.0

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

@@ -0,0 +1,10 @@
+export type GoogleOAuthConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    endpointsProbed: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkGoogleOAuthConformance(opts?: {
+    root?: string;
+}): Promise<GoogleOAuthConformanceReport>;

package/dist/src/googleoauth-conformance.js

@@ -0,0 +1,426 @@
+// Google OAuth conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// ── THIS CHECK DRIVES THE ROUTER AND ASSERTS WHAT CAME BACK ─────────────────────────────────
+// Held to ADDING_A_TWIN.md §6's bar, and to the two escalating false-greens two packs' §9 reviews
+// found there:
+//   • two constants asserting about each other is not a check (tinybird round one) — so every
+//     expectation below is a LITERAL, never a value read back out of the handler's own module;
+//   • "not the router's own miss" has teeth at the dispatch and nowhere deeper (tinybird round
+//     two) — so each probe declares the STATUS SET and a PREDICATE over the body that a live
+//     handler produces, and the endpoint census is a two-way bijection with the snapshot.
+//
+// And the whole point of this pack — the ROUND TRIP — is checked as a round trip: a real
+// authorization request, a real consent, a real 302 carrying a real code, and that code redeemed
+// for a real token whose id_token verifies against the JWKS this same twin serves. A router that
+// dispatches every route while folding nothing cannot pass that.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { encodeAuthError } from "./googleoauth-autherror.js";
+import { verifyJwtWithJwks } from "./googleoauth-jwt.js";
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, defaultRedirectUris } from "./googleoauth-store.js";
+import { googleOAuthTwinSnapshot, handleGoogleOAuthTwinRequest } from "./googleoauth-twin.js";
+const isObject = (b) => !!b && typeof b === 'object';
+const hasKeys = (...keys) => (b) => isObject(b) && keys.every((k) => b[k] !== undefined);
+const htmlContaining = (...needles) => (b) => typeof b === 'string' && needles.every((n) => b.includes(n));
+/** The origin this harness's world serves the twin at. The seeded demo client's callbacks are
+ *  DERIVED from it (runtime contract R7: the port belongs to the caller's world, never to the
+ *  twin's source), so the probes below name no port of their own. */
+const DEMO_ORIGIN = 'http://localhost:3000';
+const REDIRECT_URI = defaultRedirectUris(DEMO_ORIGIN)[0];
+const SCOPE = 'openid email profile';
+const AT = '2026-02-01T00:00:00.000Z';
+/** Placeholders substituted with values the live flow actually minted. */
+const CODE = 'PROBE_CODE';
+const ACCESS = 'PROBE_ACCESS_TOKEN';
+const REFRESH = 'PROBE_REFRESH_TOKEN';
+const authQuery = `client_id=${encodeURIComponent(DEFAULT_CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`
+    + `&response_type=code&scope=${encodeURIComponent(SCOPE)}&state=probe-state&access_type=offline&prompt=consent`;
+const form = (params) => new URLSearchParams(params).toString();
+/** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
+const PROBES = {
+    'GET /.well-known/openid-configuration': {
+        method: 'GET',
+        path: '/.well-known/openid-configuration',
+        status: [200],
+        // Literals, deliberately: asserting against the handler's own constants would be the tautology
+        // §6 names. These are the values Google's real discovery document carries.
+        expect: (b) => isObject(b)
+            && b.issuer === 'https://accounts.google.com'
+            && String(b.authorization_endpoint).endsWith('/o/oauth2/v2/auth')
+            && String(b.token_endpoint).endsWith('/token')
+            && String(b.jwks_uri).endsWith('/oauth2/v3/certs')
+            && Array.isArray(b.id_token_signing_alg_values_supported)
+            && b.id_token_signing_alg_values_supported.includes('RS256')
+            && Array.isArray(b.code_challenge_methods_supported)
+            && b.code_challenge_methods_supported.includes('S256'),
+    },
+    'GET /oauth2/v3/certs': {
+        method: 'GET',
+        path: '/oauth2/v3/certs',
+        status: [200],
+        expect: (b) => {
+            if (!isObject(b) || !Array.isArray(b.keys) || b.keys.length !== 1)
+                return false;
+            const k = b.keys[0];
+            return k.kty === 'RSA' && k.alg === 'RS256' && k.use === 'sig' && typeof k.n === 'string' && k.n.length > 300 && k.e === 'AQAB';
+        },
+    },
+    'GET /oauth2/v1/certs': {
+        method: 'GET',
+        path: '/oauth2/v1/certs',
+        status: [200],
+        expect: (b) => isObject(b) && Object.values(b).every((v) => typeof v === 'string' && v.includes('-----BEGIN PUBLIC KEY-----')) && Object.keys(b).length === 1,
+    },
+    'GET /o/oauth2/v2/auth': {
+        method: 'GET',
+        path: `/o/oauth2/v2/auth?${authQuery}`,
+        status: [200],
+        // The consent surface is HTML, and its content is the claim: the app name from the client
+        // registry and every seeded persona's e-mail address must be ON the page.
+        expect: htmlContaining('Choose an account', 'Twin Demo App', DEFAULT_ACCOUNTS[0].email, DEFAULT_ACCOUNTS[1].email),
+    },
+    'GET /o/oauth2/auth': {
+        method: 'GET',
+        path: `/o/oauth2/auth?${authQuery}`,
+        status: [200],
+        expect: htmlContaining('Choose an account', 'Twin Demo App'),
+    },
+    'GET /o/oauth2/v2/auth/oauthchooseaccount': {
+        method: 'GET',
+        path: `/o/oauth2/v2/auth/oauthchooseaccount?${authQuery}`,
+        status: [200],
+        expect: htmlContaining('Choose an account', 'Twin Demo App'),
+    },
+    'GET /signin/oauth/error': {
+        method: 'GET',
+        // The page every authorization failure is bounced to, probed with a payload built HERE rather
+        // than one the handler produced — so this cannot become the twin agreeing with itself.
+        path: `/signin/oauth/error?authError=${encodeAuthError({ code: 'invalid_client', message: 'The OAuth client was not found.', status: 401 })}&flowName=GeneralOAuthFlow`,
+        status: [200],
+        expect: htmlContaining('Error 401', 'invalid_client', 'The OAuth client was not found.', 'Access blocked: Authorization Error'),
+    },
+    'POST /token': {
+        method: 'POST',
+        path: '/token',
+        body: form({ grant_type: 'authorization_code', code: CODE, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }),
+        status: [200],
+        expect: (b) => isObject(b)
+            && typeof b.access_token === 'string' && b.access_token.startsWith('ya29.')
+            && b.token_type === 'Bearer'
+            && b.expires_in === 3600
+            && typeof b.id_token === 'string' && b.id_token.split('.').length === 3
+            && typeof b.refresh_token === 'string' && b.refresh_token.startsWith('1//'),
+    },
+    'POST /oauth2/v4/token': {
+        method: 'POST',
+        path: '/oauth2/v4/token',
+        // The LEGACY token path, probed through the grant that needs no minted fixture. A signed
+        // assertion is not required: the twin decodes but never verifies it (it authenticates nobody).
+        body: form({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: `e30.${Buffer.from(JSON.stringify({ iss: 'probe@twin.iam.gserviceaccount.com', scope: 'https://www.googleapis.com/auth/cloud-platform' })).toString('base64url')}.x`,
+        }),
+        status: [200],
+        expect: (b) => isObject(b) && typeof b.access_token === 'string' && b.token_type === 'Bearer' && b.expires_in === 3600,
+    },
+    'POST /o/oauth2/token': {
+        method: 'POST',
+        // The accounts.google.com legacy token path (the injector claims it, so the twin must serve it).
+        // Probed through the grant that needs no minted fixture.
+        path: '/o/oauth2/token',
+        body: form({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: `e30.${Buffer.from(JSON.stringify({ iss: 'probe@twin.iam.gserviceaccount.com' })).toString('base64url')}.x`,
+        }),
+        status: [200],
+        expect: (b) => isObject(b) && typeof b.access_token === 'string' && b.token_type === 'Bearer',
+    },
+    'POST /v1/userinfo': {
+        method: 'POST',
+        path: '/v1/userinfo',
+        body: '',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b) && b.sub === DEFAULT_ACCOUNTS[0].sub && b.email === DEFAULT_ACCOUNTS[0].email,
+    },
+    'POST /revoke': {
+        method: 'POST',
+        path: '/revoke',
+        body: `token=${REFRESH}`,
+        status: [200],
+        expect: (b) => isObject(b) && Object.keys(b).length === 0,
+    },
+    'GET /revoke': {
+        method: 'GET',
+        path: `/revoke?token=${ACCESS}`,
+        status: [200],
+        expect: (b) => isObject(b) && Object.keys(b).length === 0,
+    },
+    'GET /tokeninfo': {
+        method: 'GET',
+        path: `/tokeninfo?access_token=${ACCESS}`,
+        status: [200],
+        expect: (b) => isObject(b)
+            && b.aud === DEFAULT_CLIENT_ID
+            && b.azp === DEFAULT_CLIENT_ID
+            && b.sub === DEFAULT_ACCOUNTS[0].sub
+            && b.scope === SCOPE
+            && b.email === DEFAULT_ACCOUNTS[0].email,
+    },
+    'GET /v1/userinfo': {
+        method: 'GET',
+        path: '/v1/userinfo',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b)
+            && b.sub === DEFAULT_ACCOUNTS[0].sub
+            && b.email === DEFAULT_ACCOUNTS[0].email
+            && b.name === DEFAULT_ACCOUNTS[0].name
+            && b.email_verified === true,
+    },
+    'GET /oauth2/v3/userinfo': {
+        method: 'GET',
+        path: '/oauth2/v3/userinfo',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: hasKeys('sub', 'email', 'name'),
+    },
+    'POST /oauth2/v3/userinfo': {
+        method: 'POST',
+        path: '/oauth2/v3/userinfo',
+        body: '',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b) && b.sub === DEFAULT_ACCOUNTS[0].sub,
+    },
+};
+/**
+ * Every method/path pair a reader of `routeGoogleOAuthTwinRequest` can see the router branch on,
+ * INCLUDING the ones the snapshot is not expected to claim. Written by hand from the router, so the
+ * census can catch surface that is served without being claimed — the one direction the
+ * probes⇄snapshot bijection is blind to.
+ */
+const ROUTER_SURFACE = [
+    ['GET', '/.well-known/openid-configuration'],
+    ['GET', '/oauth2/v3/certs'],
+    ['GET', '/oauth2/v1/certs'],
+    ['GET', '/oauth2/v2/certs'],
+    ['GET', `/signin/oauth/error?authError=${encodeAuthError({ code: 'invalid_request', message: 'probe', status: 400 })}`],
+    ['GET', `/o/oauth2/v2/auth?${authQuery}`],
+    ['GET', `/o/oauth2/auth?${authQuery}`],
+    ['GET', `/o/oauth2/v2/auth/oauthchooseaccount?${authQuery}`],
+    ['GET', `/o/oauth2/auth/oauthchooseaccount?${authQuery}`],
+    ['POST', '/token'],
+    ['POST', '/oauth2/v4/token'],
+    ['POST', '/o/oauth2/token'],
+    ['POST', '/revoke'],
+    ['GET', '/revoke'],
+    ['GET', '/o/oauth2/revoke'],
+    ['GET', '/tokeninfo'],
+    ['GET', '/v1/userinfo'],
+    ['POST', '/v1/userinfo'],
+    ['GET', '/oauth2/v3/userinfo'],
+    ['POST', '/oauth2/v3/userinfo'],
+    ['GET', '/oauth2/v2/userinfo'],
+    ['GET', '/device/code'],
+    ['POST', '/device/code'],
+];
+export async function checkGoogleOAuthConformance(opts = {}) {
+    const snapshot = googleOAuthTwinSnapshot();
+    const violations = [];
+    // Always a THROWAWAY root, even when a caller passes one: the check mints and then REVOKES
+    // credentials, and doing that in an operator's world would log them out of their own twin.
+    const root = mkdtempSync(join(tmpdir(), 'googleoauth-conformance-'));
+    const call = (method, path, body, headers) => handleGoogleOAuthTwinRequest({ method, path, ...(body !== undefined ? { body } : {}), ...(headers ? { headers } : {}), root, origin: DEMO_ORIGIN, occurredAt: AT });
+    let probed = 0;
+    try {
+        // ── the ROUND TRIP, driven for real, before any probing ──
+        const authRes = await call('GET', `/o/oauth2/v2/auth?${authQuery}`);
+        const requestId = /name="auth_request" value="([^"]+)"/.exec(String(authRes.body))?.[1] ?? '';
+        if (!requestId)
+            violations.push('the authorization endpoint did not render a consent form carrying an auth_request handle');
+        const sub = DEFAULT_ACCOUNTS[0].sub;
+        const decision = await call('POST', '/_twin/consent', form({ auth_request: requestId, sub, decision: 'allow' }));
+        const location = decision.headers?.location ?? '';
+        if (decision.status !== 302 || !location.startsWith(REDIRECT_URI)) {
+            violations.push(`consent did not 302 back to the registered redirect_uri: ${decision.status} ${location}`);
+        }
+        const back = new URL(location || 'http://invalid.test/');
+        const code = back.searchParams.get('code') ?? '';
+        if (back.searchParams.get('state') !== 'probe-state') {
+            violations.push(`the redirect did not echo the caller's state verbatim: ${back.searchParams.get('state')}`);
+        }
+        if (!code.startsWith('4/0A'))
+            violations.push(`the redirect did not carry a Google-shaped authorization code: ${code}`);
+        const tokenRes = await call('POST', '/token', form({ grant_type: 'authorization_code', code, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }));
+        const tokens = tokenRes.body;
+        if (tokenRes.status !== 200 || typeof tokens?.access_token !== 'string') {
+            violations.push(`the minted code was not redeemable at the token endpoint: ${tokenRes.status} ${JSON.stringify(tokenRes.body).slice(0, 160)}`);
+        }
+        // …and the id_token is REAL: it verifies against the JWKS this same twin serves.
+        const jwksRes = await call('GET', '/oauth2/v3/certs');
+        const verified = typeof tokens?.id_token === 'string'
+            ? verifyJwtWithJwks(tokens.id_token, jwksRes.body, { now: Math.floor(Date.parse(AT) / 1000) + 10 })
+            : { valid: false, reason: 'no id_token' };
+        if (!verified.valid)
+            violations.push(`the id_token does not verify against the served JWKS: ${verified.reason}`);
+        if (verified.valid && verified.payload?.iss !== 'https://accounts.google.com') {
+            violations.push(`the id_token issuer is not Google's: ${String(verified.payload?.iss)}`);
+        }
+        if (verified.valid && verified.payload?.sub !== sub) {
+            violations.push(`the id_token subject is not the consenting account: ${String(verified.payload?.sub)}`);
+        }
+        // A redeemed code must be DEAD. This is the security property, so it is checked here and not
+        // only in the manifest.
+        const replay = await call('POST', '/token', form({ grant_type: 'authorization_code', code, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }));
+        if (replay.status !== 400 || replay.body?.error !== 'invalid_grant') {
+            violations.push(`a replayed authorization code was not refused with invalid_grant: ${replay.status} ${JSON.stringify(replay.body).slice(0, 120)}`);
+        }
+        // ── the endpoint census, THREE ways ──
+        // The probe table and the snapshot are checked against each other below, but that pair
+        // structurally cannot see surface the ROUTER serves and the snapshot never claimed — which is
+        // how four endpoints stayed deletable through §9 round one, and how a fifth
+        // (`POST /oauth2/v3/userinfo`) was still missing after it. So the router is enumerated too:
+        // every method/path pair that answers anything but the not-found envelope must be claimed.
+        const claimed = new Set(snapshot.implementedEndpoints);
+        for (const key of Object.keys(PROBES)) {
+            if (!claimed.has(key))
+                violations.push(`probe '${key}' does not correspond to any claimed endpoint — the probe table has drifted`);
+        }
+        for (const [method, probePath] of ROUTER_SURFACE) {
+            const res = await call(method, probePath);
+            const notFound = res.status === 404 && res.body?.error?.status === 'NOT_FOUND';
+            const key = `${method} ${probePath.split('?')[0]}`;
+            if (!notFound && !claimed.has(key)) {
+                violations.push(`the router answers '${key}' (${res.status}) but the snapshot does not claim it — served surface outside the census is deletable without this check noticing`);
+            }
+        }
+        // Each destructive probe needs its own fixtures, so probe ORDER cannot make this check lie:
+        // `/revoke` kills the WHOLE grant, which would take the tokeninfo/userinfo probes' token with
+        // it. Mint one throwaway grant per revoke probe instead of sharing the round-trip's.
+        const throwaway = async () => {
+            const a = await call('GET', `/o/oauth2/v2/auth?${authQuery}`);
+            const rid = /name="auth_request" value="([^"]+)"/.exec(String(a.body))?.[1] ?? '';
+            const d = await call('POST', '/_twin/consent', form({ auth_request: rid, sub: DEFAULT_ACCOUNTS[1].sub, decision: 'allow' }));
+            const c = new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+            const t = await call('POST', '/token', form({ grant_type: 'authorization_code', code: c, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }));
+            const b = t.body;
+            return { access: String(b.access_token ?? ''), refresh: String(b.refresh_token ?? '') };
+        };
+        const revokeFixtureA = await throwaway();
+        const revokeFixtureB = await throwaway();
+        // A FRESH code for the `POST /token` probe, since the round-trip's is now consumed.
+        const probeAuth = await call('GET', `/o/oauth2/v2/auth?${authQuery}`);
+        const probeRid = /name="auth_request" value="([^"]+)"/.exec(String(probeAuth.body))?.[1] ?? '';
+        const probeDecision = await call('POST', '/_twin/consent', form({ auth_request: probeRid, sub, decision: 'allow' }));
+        const probeCode = new URL(probeDecision.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+        const substitute = (s) => s.replace(CODE, probeCode).replace(ACCESS, String(tokens?.access_token ?? '')).replace(REFRESH, String(tokens?.refresh_token ?? ''));
+        for (const endpoint of snapshot.implementedEndpoints) {
+            const probe = PROBES[endpoint];
+            if (!probe) {
+                violations.push(`endpoint '${endpoint}' is claimed but has no conformance probe — the claim is unverified`);
+                continue;
+            }
+            const [claimedMethod, claimedPath] = endpoint.split(' ');
+            if (probe.method !== claimedMethod) {
+                violations.push(`probe '${endpoint}' drives ${probe.method}, not ${claimedMethod}`);
+                continue;
+            }
+            if ((probe.path.split('?')[0] ?? '') !== claimedPath) {
+                violations.push(`probe '${endpoint}' drives ${probe.path}, which is not the claimed path ${claimedPath}`);
+                continue;
+            }
+            // The two revoke probes get their own grant so they cannot disarm each other's fixtures.
+            const path = endpoint === 'POST /revoke'
+                ? probe.path
+                : endpoint === 'GET /revoke'
+                    ? probe.path.replace(ACCESS, revokeFixtureB.access)
+                    : substitute(probe.path);
+            const body = endpoint === 'POST /revoke' ? `token=${revokeFixtureA.refresh}` : probe.body === undefined ? undefined : substitute(probe.body);
+            const headers = probe.headers ? Object.fromEntries(Object.entries(probe.headers).map(([k, v]) => [k, substitute(v)])) : undefined;
+            const res = await call(probe.method, path, body, headers);
+            probed += 1;
+            if (!probe.status.includes(res.status)) {
+                violations.push(`endpoint '${endpoint}' answered ${res.status} (expected ${probe.status.join('/')}): ${JSON.stringify(res.body).slice(0, 160)}`);
+                continue;
+            }
+            if (probe.expect && !probe.expect(res.body)) {
+                violations.push(`endpoint '${endpoint}' answered ${res.status} but the body is not the shape this route returns: ${JSON.stringify(res.body).slice(0, 200)}`);
+            }
+        }
+        // Every grant type the snapshot claims must actually dispatch — an unsupported one answers
+        // `unsupported_grant_type`, so a claimed-but-missing grant is caught by name.
+        for (const grantType of snapshot.grantTypes) {
+            const res = await call('POST', '/token', form({ grant_type: grantType }));
+            const err = res.body?.error;
+            if (err === 'unsupported_grant_type')
+                violations.push(`grant type '${grantType}' is claimed but the token endpoint does not dispatch it`);
+        }
+        // Every resource type the twin projects must be reachable through the protocol — a type with no
+        // endpoint is state a consumer can never see.
+        //
+        // Checked against a REAL RESPONSE, not against the snapshot. An earlier version asked
+        // `claimed.has('GET /tokeninfo')` for each type, which is the snapshot asserting about itself —
+        // exactly the two-constants tautology this file's header disavows, and §9 round one caught it
+        // sitting three lines under that header. Each probe below reads a value only a live handler
+        // that genuinely projects that resource type can produce.
+        const witness = {
+            // the app's registered NAME is only on the screen if the oauth_client row projected
+            oauth_client: async () => String((await call('GET', `/o/oauth2/v2/auth?${authQuery}`)).body).includes('Twin Demo App'),
+            // the persona's e-mail comes back only if the account row projected — so READ it, rather than
+            // grading a bare 200 while the comment claims otherwise (§9 round two)
+            account: async () => {
+                const r = await call('GET', '/v1/userinfo', undefined, { authorization: `Bearer ${tokens?.access_token}` });
+                return r.status === 200 && r.body?.email === DEFAULT_ACCOUNTS[0].email;
+            },
+            // an auth_request that did not project could not have carried a settleable handle
+            auth_request: async () => /name="auth_request" value="ar_[0-9a-f]{32}"/.test(String((await call('GET', `/o/oauth2/v2/auth?${authQuery}`)).body)),
+            // A code that did not project could not be REDEEMED. The witness has to be the SUCCESS, not
+            // the refusal: the handler deliberately answers `invalid_grant` for unknown / consumed /
+            // expired / wrong-client alike, so "it was refused" is exactly what a twin projecting NO
+            // authorization_code rows would also say — a tautology in a new costume (§9 round two).
+            authorization_code: async () => {
+                const a = await call('GET', `/o/oauth2/v2/auth?${authQuery}`);
+                const rid = /name="auth_request" value="([^"]+)"/.exec(String(a.body))?.[1] ?? '';
+                const d = await call('POST', '/_twin/consent', form({ auth_request: rid, sub, decision: 'allow' }));
+                const fresh = new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+                const r = await call('POST', '/token', form({ grant_type: 'authorization_code', code: fresh, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }));
+                return r.status === 200 && typeof r.body?.access_token === 'string';
+            },
+            access_token: async () => (await call('GET', `/tokeninfo?access_token=${tokens?.access_token}`)).status === 200,
+            refresh_token: async () => (await call('POST', '/token', form({ grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token), client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET }))).status === 200,
+            // the grant row is what makes a SECOND offline authorization withhold a refresh token
+            grant: async () => {
+                const a = await call('GET', `/o/oauth2/v2/auth?${authQuery.replace('&prompt=consent', '')}`);
+                const rid = /name="auth_request" value="([^"]+)"/.exec(String(a.body))?.[1] ?? '';
+                const d = await call('POST', '/_twin/consent', form({ auth_request: rid, sub, decision: 'allow' }));
+                const c = new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+                const t = await call('POST', '/token', form({ grant_type: 'authorization_code', code: c, client_id: DEFAULT_CLIENT_ID, client_secret: DEFAULT_CLIENT_SECRET, redirect_uri: REDIRECT_URI }));
+                const b = t.body;
+                // The SUCCESS must be asserted too: `refresh_token === undefined` alone is satisfied by any
+                // error body, so a failure anywhere in the four steps above read as a pass (§9 round two).
+                return t.status === 200 && typeof b?.access_token === 'string' && b.refresh_token === undefined;
+            },
+        };
+        for (const type of snapshot.resourceTypes) {
+            const probe = witness[type];
+            if (!probe) {
+                violations.push(`resource type '${type}' has no reachability witness — the claim is unverified`);
+                continue;
+            }
+            if (!(await probe()))
+                violations.push(`resource type '${type}' is not reachable through any served endpoint`);
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        endpointsProbed: probed,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

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

@@ -0,0 +1,70 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { GoogleOAuthBudget, type GoogleOAuthBudgetOptions } from './googleoauth-budget.js';
+/**
+ * The injected real-Google boundary. `execute` issues ONE request and returns the parsed JSON body.
+ * A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type GoogleOAuthExecute = (method: 'GET' | 'POST', path: string, init?: {
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<Record<string, any>>;
+export type LiveGoogleOAuthOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: GoogleOAuthBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: GoogleOAuthBudgetOptions;
+};
+/**
+ * A live executor against the real Google OAuth endpoints, holding the operator's OWN access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live Google request, and therefore the one place the
+ * rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request
+ * goes out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says
+ * stop) and the response is fed back (`recordCall`) so a `Retry-After` / 429 becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching Google. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client — a
+ * duck-typed stand-in, a SUBCLASS overriding `checkBudget`, and a Proxy trapping it are all refused
+ * (`assertBudgetGuardIntact`). What this cannot stop is deliberate sabotage from inside the process
+ * (an injected clock, a throwaway ledger path); the kernel's header states that limit rather than
+ * pretending otherwise.
+ */
+export declare function liveGoogleOAuthExecute(accessToken: string, opts?: LiveGoogleOAuthOptions): GoogleOAuthExecute;
+/** Map a real `tokeninfo` response → the OAuth client SyncResource it names. */
+export declare function mapTokenInfoClient(info: Record<string, any>): SyncResource;
+/** Map a real `userinfo` response → the account (persona) SyncResource. */
+export declare function mapUserInfoAccount(profile: Record<string, any>): SyncResource;
+/** Map a real `tokeninfo` response → the (client, user) grant SyncResource it evidences. */
+export declare function mapTokenInfoGrant(info: Record<string, any>): SyncResource;
+/** PULL the operator's own identity + client into the twin's observed log (idempotent). */
+export declare function pullGoogleOAuthIdentity(execute: GoogleOAuthExecute, root?: string, occurredAt?: string): Promise<number>;
+export declare function syncGoogleOAuthFromReal(execute: GoogleOAuthExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The pack's executor over the kernel's. */
+export declare function googleOAuthExecuteOver(execute: RemoteExecute): GoogleOAuthExecute;
+/** The refresh adapter: read the account this credential names (its identity and granted scopes). */
+export declare function syncGoogleOAuthFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The perform adapter — and the honest answer is that NOTHING here can cross. Google publishes no API
+ *  that creates an OAuth client, seeds a user or grants a scope: those are Cloud Console and
+ *  myaccount.google.com actions a person takes in a browser. So every entry settles with that reason,
+ *  which is exactly what the v1 push reported by refusing to confirm anything. */
+export declare function performGoogleOAuthAction(_execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;
+/** How much local state has no upstream home — the count the v1 push reported, kept for the claim that
+ *  states this vendor's bound honestly. */
+export declare function unpushableGoogleOAuthEntries(root?: string): {
+    pushed: 0;
+    unpushable: number;
+};