@volter/twin-googleoauth 0.1.0

package/src/googleoauth-conformance.ts

@@ -0,0 +1,472 @@
+// 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.ts';
+import { verifyJwtWithJwks, type Jwks } from './googleoauth-jwt.ts';
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, defaultRedirectUris } from './googleoauth-store.ts';
+import { googleOAuthTwinSnapshot, handleGoogleOAuthTwinRequest, type GoogleOAuthResponse } from './googleoauth-twin.ts';
+
+export type GoogleOAuthConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  endpointsProbed: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+type Probe = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  /** The status(es) a WORKING handler answers with. */
+  status: number[];
+  /** What a working handler's body must look like. */
+  expect?: (body: unknown) => boolean;
+};
+
+const isObject = (b: unknown): b is Record<string, unknown> => !!b && typeof b === 'object';
+const hasKeys = (...keys: string[]) => (b: unknown) => isObject(b) && keys.every((k) => b[k] !== undefined);
+const htmlContaining = (...needles: string[]) => (b: unknown) => 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: Record<string, string>) => new URLSearchParams(params).toString();
+
+/** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
+const PROBES: Record<string, Probe> = {
+  '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 as string[]).includes('RS256')
+      && Array.isArray(b.code_challenge_methods_supported)
+      && (b.code_challenge_methods_supported as string[]).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] as Record<string, unknown>;
+      return k.kty === 'RSA' && k.alg === 'RS256' && k.use === 'sig' && typeof k.n === 'string' && (k.n as string).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 as string).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 as string).startsWith('ya29.')
+      && b.token_type === 'Bearer'
+      && b.expires_in === 3600
+      && typeof b.id_token === 'string' && (b.id_token as string).split('.').length === 3
+      && typeof b.refresh_token === 'string' && (b.refresh_token as string).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: Array<[string, string]> = [
+  ['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: { root?: string } = {}): Promise<GoogleOAuthConformanceReport> {
+  const snapshot = googleOAuthTwinSnapshot();
+  const violations: string[] = [];
+  // 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: string, path: string, body?: string, headers?: Record<string, string>): Promise<GoogleOAuthResponse> =>
+    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 as Record<string, any>;
+    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 as Jwks, { 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 as Record<string, unknown>)?.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 as { error?: { status?: string } } | null)?.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 (): Promise<{ access: string; refresh: string }> => {
+      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 as Record<string, any>;
+      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: string) =>
+      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 as Record<string, unknown> | null)?.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: Record<string, () => Promise<boolean>> = {
+      // 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 as Record<string, unknown>)?.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 as Record<string, unknown>)?.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 as Record<string, unknown>;
+        // 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,
+  };
+}