@volter/twin-xidentity 0.1.0

package/src/xidentity-twin.ts

@@ -0,0 +1,944 @@
+// X (Twitter) identity twin REQUEST HANDLER — the vendor's sign-in-with-X surface, served locally.
+//
+// Contract: handleXIdentityTwinRequest({method, path, ...}) -> {status, body, headers}. It is the
+// faithful surface an unmodified X client talks to:
+//
+//   x.com        GET  /i/oauth2/authorize      → the AUTHORIZE (consent) SCREEN
+//   api.x.com    POST /2/oauth2/token          → authorization_code + refresh_token grants
+//                POST /2/oauth2/revoke         → token revocation
+//                GET  /2/users/me              → the authenticated user's identity
+//
+// (twitter.com / api.twitter.com are the same surface — X's LEGACY official SDK still points
+// there — and the injector's VENDOR_HOSTS entry routes both host families here.)
+//
+// ── WHY THIS PACK IS BROWSER-FACING ─────────────────────────────────────────────────────────────
+// The whole point of the authorization-code flow is that a browser is redirected to the vendor, a
+// person reads what the app is asking for, and clicks Authorize. A twin that skipped the screen
+// and 302'd straight back would be a bypass, not a twin — every integration bug that lives in the
+// consent leg (wrong redirect_uri, missing state, a user who cancels) would be invisible. So the
+// twin SERVES HTML at the vendor's real path, rendered server-side from its own projection by the
+// SAME React components the client bundle ships (xidentity-consent-ui.ts). The googleoauth pack is
+// the class precedent; the mirror DISCIPLINE applies in full.
+//
+// ── WHAT IS REAL HERE ───────────────────────────────────────────────────────────────────────────
+//   • The FULL authorization-code round trip: auth request → consent → 302 with code+state → the
+//     code is redeemable exactly ONCE at this same pack's token endpoint → refresh → revoke.
+//   • PKCE S256/plain, verified with real SHA-256 (xidentity-pkce.ts). PKCE is REQUIRED, as X
+//     requires it — an authorize request without a code_challenge is refused.
+//   • Redirect-URI matching is EXACT, the way X's is ("This value must correspond to one of the
+//     Callback URLs defined in your App's settings", with exact-match validation).
+//   • Tokens are OPAQUE, deliberately: X's OAuth 2.0 issues no id_token, no JWKS, no OIDC
+//     discovery — identity is fetched from GET /2/users/me with the access token. This NON-OIDC
+//     shape is the entire reason this vendor needs its own pack next to googleoauth.
+//
+// ── WHAT IS NOT ─────────────────────────────────────────────────────────────────────────────────
+// The twin authenticates NOBODY: there is no password, no 2FA, no risk engine. The x.com "signed
+// in" session is a seeded persona row (`POST /_twin/session` switches it) — a deliberate
+// design, not a hidden gap. This first X vendor service-area models IDENTITY only; posts,
+// timelines and DMs are additional service-areas that belong in this same vendor pack when built.
+//
+// EVIDENCE BOUNDARIES are marked inline: behaviours grounded in docs.x.com / the v2 OpenAPI /
+// X's official SDK sources (all fetched 2026-08-21) say so; behaviours derived from RFC 6749/7009
+// or widely-reported wire captures are marked EXTRAPOLATION with a manifest todo pinning them.
+//
+// State lives in the kernel action log (D1). No real X endpoint is ever called from this path (D4).
+import {
+  badAuthorizationCode,
+  badRefreshToken,
+  forbiddenProblem,
+  invalidClient,
+  invalidRequestProblem,
+  internalServerProblem,
+  notFoundProblem,
+  oauthError,
+  rateLimitExceeded,
+  unauthorizedProblem,
+  type XResponse,
+} from './xidentity-problems.ts';
+import { applyTwinWriteAtomic, type TwinResource } from '@volter/world-core';
+import { consentPageHtml, errorPageHtml, xIdentityConsentState } from './xidentity-consent-ui.ts';
+import { formatScopeParam, parseScopeParam } from './xidentity-scopes.ts';
+import { normalizeChallengeMethod, pkceVerifies } from './xidentity-pkce.ts';
+import {
+  authRequestIdFor,
+  ensureSeed,
+  mintAccessToken,
+  mintAuthorizationCode,
+  mintClientId,
+  mintRefreshToken,
+  nextRev,
+  nextRevIn,
+  readAll,
+  readOne,
+  readType,
+  RESOURCE_TYPES as STORE_RESOURCE_TYPES,
+  sessionAccount,
+  redirectUriAllowed,
+  write,
+  writeAtomic,
+  type Row,
+} from './xidentity-store.ts';
+
+export { RESOURCE_TYPES } from './xidentity-store.ts';
+export type { XResponse } from './xidentity-problems.ts';
+
+/** X's real hosts. The authorize screen lives on the site host; the API on api.x.com. The legacy
+ *  twitter.com pair still serves the same surface and X's legacy official SDK still targets it. */
+export const AUTHORIZE_ORIGIN = 'https://x.com';
+export const API_ORIGIN = 'https://api.x.com';
+export const LEGACY_AUTHORIZE_ORIGIN = 'https://twitter.com';
+export const LEGACY_API_ORIGIN = 'https://api.twitter.com';
+
+/** X's documented default access-token lifetime: "Access tokens default to 2-hour validity"
+ *  (docs.x.com authorization-code guide, fetched 2026-08-21). */
+export const ACCESS_TOKEN_TTL_SECONDS = 7200;
+/** X's authorization codes are short-lived; 30 seconds is the widely-reported figure.
+ *  EXTRAPOLATION — not read from a fetched official artefact; pinned as
+ *  `xidentity.token.code_ttl` (todo). The single-use rule, by contrast, is hard protocol. */
+export const AUTH_CODE_TTL_SECONDS = 30;
+/** GET /2/users/me: 75 requests / 15 min per user (docs.x.com/x-api/fundamentals/rate-limits,
+ *  fetched 2026-08-21). */
+export const USERS_ME_RATE_LIMIT = 75;
+export const RATE_WINDOW_SECONDS = 15 * 60;
+
+export type XIdentityRequest = {
+  method: string;
+  /** Path plus query string, e.g. `/i/oauth2/authorize?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
+   *  consent form's action must point back at the twin. Absent (an in-process call), vendor-real
+   *  URLs are used. */
+  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 XIdentityResponse = XResponse;
+
+const HTML = { 'content-type': 'text/html; charset=utf-8' };
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────────
+
+function splitPath(raw: string): { path: string; query: URLSearchParams } {
+  const [p, q = ''] = raw.split('?');
+  const path = (p ?? '/').replace(/\/+$/, '') || '/';
+  return { path, query: new URLSearchParams(q) };
+}
+
+/**
+ * The world instant this request happened at. The twin has NO clock of its own (runtime contract
+ * R9: no clock in served content) — `createXIdentityTwinFetch` stamps every request with
+ * `worldNow()`, the world's frozen instant, and a caller that names no instant is a DEFECT rather
+ * than a cue to read the wall clock. The old `?? Date.now()` fallback put the host's wall clock
+ * into `expires_in` and into the unix-ms segment of every minted code/token on any path that
+ * forgot to stamp; it throws now.
+ */
+function instantOf(occurredAt?: string): string {
+  if (!occurredAt) {
+    throw new Error('xidentity twin: the request carries no occurredAt — this twin has no clock of its own; the server stamps worldNow()');
+  }
+  return occurredAt;
+}
+
+function nowMillis(occurredAt?: string): number {
+  const ms = Date.parse(instantOf(occurredAt));
+  if (Number.isNaN(ms)) throw new Error(`xidentity twin: occurredAt is not a timestamp: ${occurredAt}`);
+  return ms;
+}
+
+function nowSeconds(occurredAt?: string): number {
+  return Math.floor(nowMillis(occurredAt) / 1000);
+}
+
+/**
+ * The authorize endpoint's un-redirectable failure path: until the redirect_uri is proven to
+ * belong to the client there is no address the twin may bounce an error to, so unknown-client and
+ * bad-callback failures render the vendor's error page (200 HTML would hide the failure from
+ * scripts; the page is served WITH the failure's status). EXTRAPOLATION: X's live page and its
+ * HTTP status were not captured — the security boundary itself is RFC 6749 §4.1.2.1's hard rule.
+ * Pinned as `xidentity.authorize.error_page_fidelity` (todo).
+ */
+function errorPage(req: XIdentityRequest, e: { status: number; code: string; detail: string; requestParam?: string }): XResponse {
+  return {
+    status: e.status,
+    body: errorPageHtml(e, req.origin ?? ''),
+    headers: { ...HTML, ...NOSTORE },
+  };
+}
+
+/** A 302 back to a VALIDATED redirect_uri carrying an OAuth error (RFC 6749 §4.1.2.1). */
+function redirectError(redirectUri: string, error: string, state: string | null, description?: string): XResponse {
+  const url = new URL(redirectUri);
+  url.searchParams.set('error', error);
+  if (description) url.searchParams.set('error_description', description);
+  if (state !== null) url.searchParams.set('state', state);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+/** The success bounce. X's documented callback carries EXACTLY `state` and `code` (the
+ *  user-access-token guide's example: `https://www.example.com/?state=state&code=VGNibzFWSWRE…`) —
+ *  no scope echo, no extra parameters, and the twin adds none. */
+function redirectSuccess(redirectUri: string, code: string, state: string): XResponse {
+  const url = new URL(redirectUri);
+  url.searchParams.set('state', state);
+  url.searchParams.set('code', code);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+/**
+ * Client authentication at the token/revoke endpoints. The docs' rule (user-access-token guide):
+ * a CONFIDENTIAL client authenticates with HTTP Basic — base64(client_id:client_secret) — and
+ * "you don't need client id [in the body] for confidential clients with a valid Authorization
+ * Header"; a PUBLIC client has no secret and "you still are required to include Client Id in the
+ * body". A confidential client presenting no Basic header is refused: the docs document no
+ * client_secret_post alternative for X, and inventing that tolerance would be the inverse
+ * false-green (`xidentity.token.client_secret_post`, todo pins the live behaviour).
+ */
+function authenticateClient(
+  form: URLSearchParams,
+  headers: Record<string, string> | undefined,
+  root: string | undefined,
+  resources?: readonly TwinResource[],
+): { client: Row } | { fail: XResponse } {
+  const lookup = (id: string) => (resources
+    ? resources.find((row) => row.type === 'oauth_client' && row.id === id) as Row | undefined
+    : readOne(root, 'oauth_client', id));
+  const basic = headers?.authorization;
+  if (basic && /^basic /i.test(basic)) {
+    let decoded = '';
+    try {
+      decoded = Buffer.from(basic.slice(6).trim(), 'base64').toString('utf8');
+    } catch {
+      return { fail: invalidClient() };
+    }
+    // The percent-decode below applies RFC 6749 §2.3.1's rule (client_id and client_secret are
+    // form-urlencoded before Basic encoding). X's docs describe the header only as
+    // base64(client_id:client_secret) — EXTRAPOLATION, and the containment of a hostile decode is
+    // what `xidentity.errors.malformed_client_auth_contained` certifies; the live tolerance is
+    // pinned by `xidentity.token.error_wording` (todo).
+    const sep = decoded.indexOf(':');
+    if (sep < 0) return { fail: invalidClient() };
+    const clientId = decodeURIComponent(decoded.slice(0, sep));
+    const secret = decodeURIComponent(decoded.slice(sep + 1));
+    const client = lookup(clientId);
+    if (!client || typeof client.secret !== 'string' || client.secret !== secret) return { fail: invalidClient() };
+    return { client };
+  }
+  const clientId = form.get('client_id');
+  if (!clientId) return { fail: oauthError('invalid_request', 'Missing required parameter [client_id].', 400) };
+  const client = lookup(clientId);
+  if (!client) return { fail: invalidClient() };
+  if (client.clientType === 'confidential') return { fail: invalidClient() };
+  return { client };
+}
+
+// ── the authorization endpoint (the authorize screen) ───────────────────────────────────────────
+
+const AUTHORIZE_PATH = '/i/oauth2/authorize';
+
+async function authorize(req: XIdentityRequest, query: URLSearchParams): Promise<XResponse> {
+  const root = req.root;
+
+  // 1. client_id — without a trusted client there is no trusted redirect_uri, so failures here
+  //    render the error page.
+  const clientId = query.get('client_id');
+  if (!clientId) return errorPage(req, { status: 400, code: 'invalid_request', detail: 'Missing required parameter: client_id.', requestParam: 'client_id' });
+  const client = readOne(root, 'oauth_client', clientId);
+  if (!client) return errorPage(req, { status: 401, code: 'invalid_client', detail: 'The client_id does not name a known App.', requestParam: `client_id=${clientId}` });
+
+  // 2. redirect_uri — THE SECURITY BOUNDARY. X validates the callback against the App's registered
+  //    Callback URLs with exact matching; an unregistered one gets the page, never a bounce.
+  const redirectUri = query.get('redirect_uri');
+  if (!redirectUri) return errorPage(req, { status: 400, code: 'invalid_request', detail: 'Missing required parameter: redirect_uri.', requestParam: 'redirect_uri' });
+  if (!redirectUriAllowed(client, redirectUri)) {
+    return errorPage(req, {
+      status: 400,
+      code: 'invalid_request',
+      detail: 'The redirect_uri does not match any registered Callback URL for this App. X compares callback URLs exactly.',
+      requestParam: `redirect_uri=${redirectUri}`,
+    });
+  }
+
+  // 3. Everything after the boundary has a trustworthy address, so protocol errors bounce there
+  //    (RFC 6749 §4.1.2.1 — EXTRAPOLATION for X: the docs show no authorize error examples; the
+  //    page-vs-redirect split for each case is pinned by `xidentity.authorize.error_channel`, todo).
+  const state = query.get('state');
+  const respond = (error: string, description: string) =>
+    redirectError(redirectUri, error, state, description);
+
+  const responseType = query.get('response_type');
+  if (!responseType) return respond('invalid_request', 'Missing required parameter: response_type.');
+  // `code` is the ONLY response_type X's OAuth 2.0 documents — there is no implicit flow to
+  // model, so an unknown value is the vendor's own unsupported_response_type, not "unmodelled".
+  if (responseType !== 'code') return respond('unsupported_response_type', `Unsupported response_type: ${responseType}.`);
+
+  const scopes = parseScopeParam(query.get('scope'));
+  if (scopes.length === 0) return respond('invalid_request', 'Missing required parameter: scope.');
+
+  // `state` is REQUIRED by X: both official SDKs' authorize-URL builders make it non-optional
+  // (twitter-api-typescript-sdk GenerateAuthUrlOptions; xdk oauth2_auth) and the docs describe it
+  // as the CSRF check with a 500-character ceiling.
+  if (state === null) return respond('invalid_request', 'Missing required parameter: state.');
+  if (state.length > 500) return respond('invalid_request', 'The state parameter must be at most 500 characters.');
+
+  // PKCE is REQUIRED on X's OAuth 2.0 — the docs' parameter tables list code_challenge, and the
+  // LEGACY official SDK always sends one. (The current xdk sends it only after
+  // setPkceParameters — the docs table, not the SDKs, is the load-bearing evidence; §9 round two.)
+  const codeChallenge = query.get('code_challenge');
+  if (!codeChallenge) return respond('invalid_request', 'Missing required parameter: code_challenge.');
+  const rawMethod = query.get('code_challenge_method');
+  // Method omitted ⇒ `plain` (RFC 6376 §4.3 default — EXTRAPOLATION for X, whose docs always show
+  // the parameter; pinned by `xidentity.authorize.challenge_method_default`, todo).
+  const method = rawMethod === null ? 'plain' : normalizeChallengeMethod(rawMethod);
+  if (method === null) {
+    return respond('invalid_request', `Invalid code_challenge_method: ${rawMethod}. Expected S256 or plain.`);
+  }
+
+  if (req.readOnly) {
+    return oauthError('temporarily_unavailable', 'this twin was started read-only; omit readOnly to accept writes', 405);
+  }
+
+  const account = sessionAccount(root);
+  if (!account) {
+    // No signed-in session to consent as. The REAL x.com would show a login screen here; the twin
+    // authenticates nobody, so it states that plainly rather than pretending.
+    return errorPage(req, { status: 400, code: 'invalid_request', detail: 'No x.com session is signed in on this twin. Seed an account and set /_twin/session.' });
+  }
+
+  // 4. Record the request, then render the screen. The auth_request row is what the
+  //    Authorize/Cancel post resolves — the browser never carries the parameters back, so they
+  //    cannot be tampered with between the two legs.
+  const fields = {
+    clientId,
+    redirectUri,
+    scope: formatScopeParam(scopes),
+    state,
+    codeChallenge,
+    codeChallengeMethod: method,
+    accountId: account.id,
+    settled: false,
+    rev: 1,
+  };
+  // The handle is SERVED (it is the authorize form's own hidden field), so R9 governs it: minted
+  // from the world instant + the rows already held, never from entropy, and an identical authorize
+  // at the same instant reuses the pending row rather than piling up a second screen.
+  const requestId = authRequestIdFor(root, instantOf(req.occurredAt), fields);
+  await write('auth_request', requestId, 'auth_request.create', fields, { root, occurredAt: instantOf(req.occurredAt) });
+
+  return renderConsent(req, requestId);
+}
+
+function renderConsent(req: XIdentityRequest, requestId: string): XResponse {
+  const view = xIdentityConsentState({
+    root: req.root,
+    requestId,
+    origin: req.origin ?? AUTHORIZE_ORIGIN,
+  });
+  if (!view) {
+    return errorPage(req, { status: 400, code: 'invalid_request', detail: 'Unknown or expired authorization request.' });
+  }
+  return { status: 200, body: consentPageHtml(view, req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+}
+
+/**
+ * The Authorize/Cancel post. TWIN-ONLY SURFACE, deliberately namespaced under `/_twin/` and
+ * deliberately ABSENT from the capability manifest: X's authorize form posts to an undocumented
+ * internal endpoint, so there is no vendor path to be faithful to here (the googleoauth
+ * `/_twin/consent` precedent, sanctioned by ADDING_A_TWIN.md §6's seed-route rule).
+ */
+async function consentDecision(req: XIdentityRequest, form: URLSearchParams): Promise<XResponse> {
+  const root = req.root;
+  const at = req.occurredAt;
+  const requestId = form.get('auth_request') ?? '';
+  const issuedMs = nowMillis(at);
+  const code = mintAuthorizationCode(root, issuedMs, requestId);
+  const decided = await applyTwinWriteAtomic(
+    'xidentity',
+    (resources) => {
+      const authRequest = resources.find((row) => row.type === 'auth_request' && row.id === requestId) as Row | undefined;
+      if (!authRequest || authRequest.settled === true) {
+        return { kind: 'skip', value: oauthError('invalid_request', 'Unknown, expired, or already settled authorization request.', 400) };
+      }
+      const redirectUri = String(authRequest.redirectUri);
+      const state = String(authRequest.state ?? '');
+      const settle = {
+        operation: 'auth_request.settle',
+        subjectType: 'auth_request',
+        subjectId: requestId,
+        fields: { settled: true, rev: nextRevIn(resources, 'auth_request', requestId) },
+        ...(at ? { occurredAt: at } : {}),
+        actor: { kind: 'human' as const },
+      };
+      if (form.get('decision') !== 'allow') {
+        return { kind: 'write', value: redirectError(redirectUri, 'access_denied', state), write: settle };
+      }
+      // Bind consent to the account displayed when this request was created. A concurrent session
+      // switch cannot make the screen name one account while minting credentials for another.
+      const account = resources.find((row) => row.type === 'account' && row.id === authRequest.accountId) as Row | undefined;
+      if (!account) return { kind: 'skip', value: oauthError('invalid_request', 'The account shown for this authorization request no longer exists.', 400) };
+      const scopes = parseScopeParam(String(authRequest.scope));
+      const grantId = `${authRequest.clientId}:${account.id}`;
+      const grantFields = { clientId: authRequest.clientId, sub: account.id, scopes, rev: nextRevIn(resources, 'grant', grantId) };
+      const grantExists = resources.some((row) => row.type === 'grant' && row.id === grantId);
+      return {
+        kind: 'write',
+        value: redirectSuccess(redirectUri, code, state),
+        write: {
+          ...settle,
+          projection: {
+            creates: [
+              ...(grantExists ? [] : [{ type: 'grant', id: grantId, fields: grantFields }]),
+              {
+                type: 'authorization_code',
+                id: code,
+                fields: {
+                  clientId: authRequest.clientId,
+                  sub: account.id,
+                  scope: formatScopeParam(scopes),
+                  redirectUri,
+                  codeChallenge: authRequest.codeChallenge,
+                  codeChallengeMethod: authRequest.codeChallengeMethod,
+                  consumed: false,
+                  expiresAt: nowSeconds(at) + AUTH_CODE_TTL_SECONDS,
+                  rev: 1,
+                },
+              },
+            ],
+            ...(grantExists ? { updates: [{ type: 'grant', id: grantId, fields: grantFields }] } : {}),
+          },
+        },
+      };
+    },
+    root,
+  );
+  return decided.value;
+}
+
+// ── the token endpoint ──────────────────────────────────────────────────────────────────────────
+
+async function token(req: XIdentityRequest): Promise<XResponse> {
+  // X's token endpoint is `application/x-www-form-urlencoded` (docs curl examples). The twin is
+  // deliberately strict about that rather than tolerating a JSON body it has no documented
+  // evidence the vendor accepts (`xidentity.token.json_body_tolerance`, todo).
+  const form = new URLSearchParams(req.body ?? '');
+  const grantType = form.get('grant_type');
+  if (!grantType) return oauthError('invalid_request', 'Missing required parameter [grant_type].', 400);
+  if (grantType === 'authorization_code') return authorizationCodeGrant(req, form);
+  if (grantType === 'refresh_token') return refreshTokenGrant(req, form);
+  // X's OAuth 2.0 user-token endpoint documents exactly the two grants. (The app-only bearer flow
+  // lives at the v1.1 `/oauth2/token` path, filed as `xidentity.app_only.bearer_token`, todo.)
+  return oauthError('unsupported_grant_type', `Unsupported grant_type: ${grantType}.`, 400);
+}
+
+function issuedTokenResponse(accessToken: string, scope: string, refreshToken?: string): XResponse {
+  return {
+    status: 200,
+    body: {
+      token_type: 'bearer',
+      expires_in: ACCESS_TOKEN_TTL_SECONDS,
+      access_token: accessToken,
+      scope,
+      ...(refreshToken ? { refresh_token: refreshToken } : {}),
+    },
+    headers: { ...NOSTORE },
+  };
+}
+
+async function authorizationCodeGrant(req: XIdentityRequest, form: URLSearchParams): Promise<XResponse> {
+  const root = req.root;
+  const code = form.get('code');
+  if (!code) return oauthError('invalid_request', 'Missing required parameter [code].', 400);
+  const redirectUri = form.get('redirect_uri');
+  if (!redirectUri) return oauthError('invalid_request', 'Missing required parameter [redirect_uri].', 400);
+  const verifier = form.get('code_verifier');
+  if (!verifier) return oauthError('invalid_request', 'Missing required parameter [code_verifier].', 400);
+
+  const issuedMs = nowMillis(req.occurredAt);
+  const accessToken = mintAccessToken(root, issuedMs, code);
+  const replacementRefreshToken = mintRefreshToken(root, issuedMs, code);
+  const committed = await applyTwinWriteAtomic(
+    'xidentity',
+    (resources) => {
+      const auth = authenticateClient(form, req.headers, root, resources);
+      if ('fail' in auth) return { kind: 'skip', value: auth.fail };
+      const row = resources.find((resource) => resource.type === 'authorization_code' && resource.id === code) as Row | undefined;
+      if (!row || row.clientId !== auth.client.id || row.consumed === true
+        || (typeof row.expiresAt === 'number' && nowSeconds(req.occurredAt) >= row.expiresAt)
+        || redirectUri !== row.redirectUri
+        || !pkceVerifies(row.codeChallengeMethod === 'S256' ? 'S256' : 'plain', String(row.codeChallenge ?? ''), verifier)) {
+        return { kind: 'skip', value: badAuthorizationCode() };
+      }
+      const scope = String(row.scope);
+      const withRefreshToken = parseScopeParam(scope).includes('offline.access');
+      return {
+        kind: 'write',
+        value: issuedTokenResponse(accessToken, scope, withRefreshToken ? replacementRefreshToken : undefined),
+        write: {
+          operation: 'authorization_code.redeem',
+          subjectType: 'authorization_code',
+          subjectId: code,
+          fields: { consumed: true, rev: nextRevIn(resources, 'authorization_code', code) },
+          projection: {
+            creates: [
+              {
+                type: 'access_token', id: accessToken,
+                fields: { clientId: auth.client.id, sub: String(row.sub), scope, expiresAt: nowSeconds(req.occurredAt) + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: 1 },
+              },
+              ...(withRefreshToken ? [{
+                type: 'refresh_token', id: replacementRefreshToken,
+                fields: { clientId: auth.client.id, sub: String(row.sub), scope, revoked: false, rev: 1 },
+              }] : []),
+            ],
+          },
+          ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+async function refreshTokenGrant(req: XIdentityRequest, form: URLSearchParams): Promise<XResponse> {
+  const root = req.root;
+  const refreshToken = form.get('refresh_token');
+  if (!refreshToken) return oauthError('invalid_request', 'Missing required parameter [refresh_token].', 400);
+  const issuedMs = nowMillis(req.occurredAt);
+  const accessToken = mintAccessToken(root, issuedMs, refreshToken);
+  const replacementRefreshToken = mintRefreshToken(root, issuedMs, refreshToken);
+  const committed = await applyTwinWriteAtomic(
+    'xidentity',
+    (resources) => {
+      const auth = authenticateClient(form, req.headers, root, resources);
+      if ('fail' in auth) return { kind: 'skip', value: auth.fail };
+      const row = resources.find((resource) => resource.type === 'refresh_token' && resource.id === refreshToken) as Row | undefined;
+      if (!row || row.revoked === true || row.clientId !== auth.client.id) return { kind: 'skip', value: badRefreshToken() };
+      const scope = String(row.scope);
+      return {
+        kind: 'write',
+        value: issuedTokenResponse(accessToken, scope, replacementRefreshToken),
+        write: {
+          operation: 'refresh_token.rotate',
+          subjectType: 'refresh_token',
+          subjectId: refreshToken,
+          fields: { revoked: true, rev: nextRevIn(resources, 'refresh_token', refreshToken) },
+          projection: {
+            creates: [
+              { type: 'access_token', id: accessToken, fields: { clientId: auth.client.id, sub: String(row.sub), scope, expiresAt: nowSeconds(req.occurredAt) + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: 1 } },
+              { type: 'refresh_token', id: replacementRefreshToken, fields: { clientId: auth.client.id, sub: String(row.sub), scope, revoked: false, rev: 1 } },
+            ],
+          },
+          ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+// ── the revoke endpoint ─────────────────────────────────────────────────────────────────────────
+
+async function revoke(req: XIdentityRequest): Promise<XResponse> {
+  const form = new URLSearchParams(req.body ?? '');
+  const root = req.root;
+  const opts = { root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) };
+  const auth = authenticateClient(form, req.headers, root);
+  if ('fail' in auth) return auth.fail;
+  const { client } = auth;
+
+  const token_ = form.get('token');
+  if (!token_) return oauthError('invalid_request', 'Missing required parameter [token].', 400);
+  // `token_type_hint` (access_token | refresh_token) is what X's LEGACY official SDK always sends
+  // (RevokeAccessTokenParams). Per RFC 7009 §2.1 the hint only optimises the lookup — the twin
+  // searches both types regardless, so a wrong hint cannot change the outcome.
+
+  const access = readOne(root, 'access_token', token_);
+  const refresh = readOne(root, 'refresh_token', token_);
+  const match = access ?? refresh;
+
+  // A token that does not exist answers 200 (RFC 7009 §2.2: "invalid tokens do not cause an
+  // error" — answering differently would let a client probe which tokens exist). A token that
+  // belongs to ANOTHER client also answers 200 here WITHOUT revoking — but note RFC 7009 §2.1
+  // says a failed issued-to-this-client validation is REFUSED with an error, so the 200 reading
+  // treats a foreign token as merely invalid; which reading X takes is UNPINNED — EXTRAPOLATION,
+  // pinned by `xidentity.revoke.cross_client_wire` (the foreign-client case) and
+  // `xidentity.revoke.wire_pin` (unknown-token status, sweep, body). The response body
+  // `{"revoked": true}` is grounded in the legacy official SDK's RevokeAccessTokenResponse type.
+  if (match && match.clientId === client.id) {
+    // Revocation is the docs' "log out" feature, and the GRANT RECORD is what dies: the twin
+    // resolves the (client, user) grant the named token belongs to and revokes everything under
+    // it — every access token, every refresh token, and the grant itself, whichever half was
+    // named. EXTRAPOLATION for the pair-wide sweep (`xidentity.revoke.pair_revocation`, todo);
+    // revoking ONLY the named token would leave a "logged out" user's other half alive. A token
+    // whose grant row is somehow gone falls back to dying alone.
+    const sub = String(match.sub);
+    const clientId = String(match.clientId);
+    const grantId = `${clientId}:${sub}`;
+    const grant = readOne(root, 'grant', grantId);
+    if (grant) {
+      for (const row of readType(root, 'access_token')) {
+        if (row.sub === sub && row.clientId === clientId && row.revoked !== true) {
+          await write('access_token', row.id, 'access_token.revoke', { revoked: true, rev: nextRev(root, 'access_token', row.id) }, opts);
+        }
+      }
+      for (const row of readType(root, 'refresh_token')) {
+        if (row.sub === sub && row.clientId === clientId && row.revoked !== true) {
+          await write('refresh_token', row.id, 'refresh_token.revoke', { revoked: true, rev: nextRev(root, 'refresh_token', row.id) }, opts);
+        }
+      }
+      await write('grant', grantId, 'grant.revoke', { clientId, sub, scopes: [], rev: nextRev(root, 'grant', grantId) }, opts);
+    } else {
+      const type = access ? 'access_token' : 'refresh_token';
+      await write(type, match.id, `${type}.revoke`, { revoked: true, rev: nextRev(root, type, match.id) }, opts);
+    }
+  }
+  return { status: 200, body: { revoked: true }, headers: { ...NOSTORE } };
+}
+
+// ── GET /2/users/me ─────────────────────────────────────────────────────────────────────────────
+
+/** The `user.fields` enum — the v2 OpenAPI's UserFieldsParameter (2.167), verbatim. */
+export const USER_FIELDS = [
+  'confirmed_email',
+  'connection_status',
+  'created_at',
+  'description',
+  'entities',
+  'id',
+  'is_identity_verified',
+  'location',
+  'name',
+  'parody',
+  'profile_banner_url',
+  'profile_image_url',
+  'protected',
+  'public_metrics',
+  'receives_your_dm',
+  'subscribes_to_you',
+  'subscription',
+  'subscription_type',
+  'url',
+  'username',
+  'verified',
+  'verified_followers_count',
+  'verified_type',
+  'withheld',
+] as const;
+
+/** The `expansions` enum — UserExpansionsParameter (2.167), verbatim. */
+export const USER_EXPANSIONS = ['affiliation', 'most_recent_post_id', 'pinned_post_id'] as const;
+
+/** The scopes GET /2/users/me demands — the OpenAPI operation's OAuth2UserToken entry lists BOTH. */
+export const USERS_ME_REQUIRED_SCOPES = ['tweet.read', 'users.read'] as const;
+
+/** Map an account row to the vendor's User object for a requested field set. Default fields are
+ *  id, name, username (the OpenAPI/docs default); everything else appears only when asked for and
+ *  only when the twin models it — a modelled-but-absent optional field is OMITTED, matching the
+ *  spec (no User property is `required`). Unmodelled enum values (`connection_status`,
+ *  `receives_your_dm`, …) are accepted and omitted; each is a named manifest todo, not silent.
+ *  `confirmed_email` additionally demands the `users.email` scope (X's April-2025 announcement —
+ *  see xidentity-scopes.ts); OMISSION when the scope is missing is EXTRAPOLATION, pinned by
+ *  `xidentity.users_me.confirmed_email_scope_behavior` (todo). */
+function renderUser(account: Row, fields: readonly string[], heldScopes: readonly string[]): Record<string, unknown> {
+  // name/username are default fields on the wire, but a PARTIALLY-pulled persona may genuinely
+  // lack them — serving "" would be the connector's placeholder bug relocated (§9 round two), so
+  // an absent value is OMITTED here too.
+  const out: Record<string, unknown> = {
+    id: account.id,
+    ...(typeof account.name === 'string' ? { name: account.name } : {}),
+    ...(typeof account.username === 'string' ? { username: account.username } : {}),
+  };
+  const want = new Set(fields);
+  if (want.has('created_at') && typeof account.createdAt === 'string') out['created_at'] = account.createdAt;
+  if (want.has('description') && typeof account.description === 'string') out['description'] = account.description;
+  if (want.has('location') && typeof account.location === 'string') out['location'] = account.location;
+  if (want.has('profile_image_url') && typeof account.profileImageUrl === 'string') out['profile_image_url'] = account.profileImageUrl;
+  if (want.has('protected')) out['protected'] = account.protectedAccount === true;
+  if (want.has('public_metrics') && account.publicMetrics && typeof account.publicMetrics === 'object') out['public_metrics'] = account.publicMetrics;
+  if (want.has('url') && typeof account.url === 'string') out['url'] = account.url;
+  if (want.has('verified')) out['verified'] = account.verified === true;
+  if (want.has('verified_type') && typeof account.verifiedType === 'string') out['verified_type'] = account.verifiedType;
+  if (want.has('confirmed_email') && typeof account.confirmedEmail === 'string' && heldScopes.includes('users.email')) {
+    out['confirmed_email'] = account.confirmedEmail;
+  }
+  return out;
+}
+
+function csvParam(query: URLSearchParams, name: string): string[] {
+  const raw = query.get(name);
+  if (raw === null || raw === '') return [];
+  return raw.split(',').map((s) => s.trim());
+}
+
+/** The invalid-enum message, shaped like the wire's: names the bad values and the allowed set. */
+function enumMessage(param: string, bad: string[], allowed: readonly string[]): string {
+  return `The \`${param}\` query parameter value [${bad.join(', ')}] is not one of [${allowed.join(', ')}]`;
+}
+
+async function usersMe(req: XIdentityRequest, query: URLSearchParams): Promise<XResponse> {
+  const root = req.root;
+  const header = req.headers?.authorization ?? '';
+  const bearer = /^bearer\s+(.+)$/i.exec(header)?.[1]?.trim();
+  if (!bearer) return unauthorizedProblem();
+
+  // Parameter validation happens BEFORE rate accounting: a 400 is not a spent request.
+  // EXTRAPOLATION on the ordering (`xidentity.rate.what_counts`, todo).
+  const fields = csvParam(query, 'user.fields');
+  const badFields = fields.filter((f) => !(USER_FIELDS as readonly string[]).includes(f));
+  if (badFields.length > 0) {
+    return invalidRequestProblem({ 'user.fields': badFields }, enumMessage('user.fields', badFields, USER_FIELDS));
+  }
+  const expansions = csvParam(query, 'expansions');
+  const badExpansions = expansions.filter((e) => !(USER_EXPANSIONS as readonly string[]).includes(e));
+  if (badExpansions.length > 0) {
+    return invalidRequestProblem({ expansions: badExpansions }, enumMessage('expansions', badExpansions, USER_EXPANSIONS));
+  }
+  // `tweet.fields` is accepted surface (PostFieldsParameter) but no expansion the twin models
+  // hydrates a post yet, so it validates nothing and shapes nothing —
+  // `xidentity.users_me.expansion_hydration` (todo) owns the honest gap.
+
+  const evaluate = (resources: readonly TwinResource[], spend: boolean) => {
+    const tokenRow = resources.find((row) => row.type === 'access_token' && row.id === bearer) as Row | undefined;
+    if (!tokenRow || tokenRow.revoked === true
+      || (typeof tokenRow.expiresAt === 'number' && nowSeconds(req.occurredAt) >= tokenRow.expiresAt)) {
+      return { response: unauthorizedProblem() };
+    }
+    const held = parseScopeParam(String(tokenRow.scope));
+    const missing = USERS_ME_REQUIRED_SCOPES.filter((scope) => !held.includes(scope));
+    if (missing.length > 0) {
+      return { response: forbiddenProblem(`The access token does not carry the scope(s) required by this endpoint: ${missing.join(', ')}.`) };
+    }
+    const account = resources.find((row) => row.type === 'account' && row.id === String(tokenRow.sub)) as Row | undefined;
+    if (!account) return { response: unauthorizedProblem() };
+    const now = nowSeconds(req.occurredAt);
+    const windowId = `users_me:${account.id}`;
+    const rateRow = resources.find((row) => row.type === 'rate_window' && row.id === windowId) as Row | undefined;
+    const active = rateRow && typeof rateRow.windowStart === 'number' && now < rateRow.windowStart + RATE_WINDOW_SECONDS;
+    const windowStart = active ? Number(rateRow.windowStart) : now;
+    const before = active && typeof rateRow.used === 'number' ? rateRow.used : 0;
+    const reset = String(windowStart + RATE_WINDOW_SECONDS);
+    if (before >= USERS_ME_RATE_LIMIT) {
+      return { response: rateLimitExceeded({ 'x-rate-limit-limit': String(USERS_ME_RATE_LIMIT), 'x-rate-limit-remaining': '0', 'x-rate-limit-reset': reset }) };
+    }
+    const used = spend ? before + 1 : before;
+    const response: XResponse = {
+      status: 200,
+      body: { data: renderUser(account, fields, held) },
+      headers: {
+        ...NOSTORE,
+        'content-type': 'application/json; charset=utf-8',
+        'x-rate-limit-limit': String(USERS_ME_RATE_LIMIT),
+        'x-rate-limit-remaining': String(Math.max(0, USERS_ME_RATE_LIMIT - used)),
+        'x-rate-limit-reset': reset,
+      },
+    };
+    return { response, windowId, windowStart, used };
+  };
+
+  if (req.readOnly) return evaluate(readAll(root), false).response;
+  const committed = await applyTwinWriteAtomic(
+    'xidentity',
+    (resources) => {
+      const result = evaluate(resources, true);
+      if (!result.windowId) return { kind: 'skip', value: result.response };
+      return {
+        kind: 'write',
+        value: result.response,
+        write: {
+          operation: 'rate_window.spend',
+          subjectType: 'rate_window',
+          subjectId: result.windowId,
+          fields: { windowStart: result.windowStart, used: result.used, rev: nextRevIn(resources, 'rate_window', result.windowId) },
+          ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+/** 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 function xIdentityTwinSnapshot(): { implementedEndpoints: string[]; resourceTypes: readonly string[]; grantTypes: string[] } {
+  return {
+    implementedEndpoints: [
+      'GET /i/oauth2/authorize',
+      'POST /2/oauth2/token',
+      'POST /2/oauth2/revoke',
+      'GET /2/users/me',
+    ],
+    resourceTypes: STORE_RESOURCE_TYPES,
+    grantTypes: ['authorization_code', 'refresh_token'],
+  };
+}
+
+// ── twin-only control routes (NOT vendor surface — see the manifest) ────────────────────────────
+
+async function twinControl(req: XIdentityRequest, path: string, form: URLSearchParams): Promise<XResponse | null> {
+  const root = req.root;
+  const opts = { root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) };
+  const json = () => {
+    try {
+      return JSON.parse(req.body ?? '{}') as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  };
+  if (req.method === 'GET' && path === '/_twin/consent') {
+    const { query } = splitPath(req.path);
+    return renderConsent(req, query.get('auth_request') ?? '');
+  }
+  if (req.method === 'POST' && path === '/_twin/consent') return consentDecision(req, form);
+  if (req.method === 'POST' && path === '/_twin/clients') {
+    const b = json();
+    if (!b) return oauthError('invalid_request', 'A JSON body is required.', 400);
+    // `:` is the grant-id separator (`clientId:sub`), so a colon in a caller-supplied id could
+    // forge a composite collision (client `A:B`+sub `C` vs client `A`+sub `B:C`). Real X client
+    // ids are base64url (colon-free); the scaffolding refuses the character outright.
+    if (typeof b['client_id'] === 'string' && b['client_id'].includes(':')) {
+      return oauthError('invalid_request', 'client_id must not contain ":".', 400);
+    }
+    const clientId = typeof b['client_id'] === 'string' && b['client_id'] ? (b['client_id'] as string) : mintClientId(root, instantOf(req.occurredAt));
+    const clientType = b['client_type'] === 'public' ? 'public' : 'confidential';
+    const row = await writeAtomic(
+      'oauth_client',
+      clientId,
+      'oauth_client.create',
+      () => ({
+        name: typeof b['name'] === 'string' ? b['name'] : 'Twin App',
+        secret: clientType === 'public' ? null : typeof b['client_secret'] === 'string' ? b['client_secret'] : `twin-secret-${clientId.slice(0, 16)}`,
+        clientType,
+        redirectUris: Array.isArray(b['redirect_uris']) ? b['redirect_uris'] : [],
+      }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  if (req.method === 'POST' && path === '/_twin/accounts') {
+    const b = json();
+    if (!b || typeof b['id'] !== 'string' || !b['id']) return oauthError('invalid_request', 'id is required', 400);
+    if (b['id'].includes(':')) return oauthError('invalid_request', 'id must not contain ":".', 400);
+    const id = b['id'] as string;
+    const row = await writeAtomic(
+      'account',
+      id,
+      'account.create',
+      () => ({
+        username: typeof b['username'] === 'string' ? b['username'] : `user_${id}`,
+        name: typeof b['name'] === 'string' ? b['name'] : 'Twin Persona',
+        ...(typeof b['created_at'] === 'string' ? { createdAt: b['created_at'] } : {}),
+        ...(typeof b['description'] === 'string' ? { description: b['description'] } : {}),
+        ...(typeof b['location'] === 'string' ? { location: b['location'] } : {}),
+        ...(typeof b['profile_image_url'] === 'string' ? { profileImageUrl: b['profile_image_url'] } : {}),
+        ...(typeof b['protected'] === 'boolean' ? { protectedAccount: b['protected'] } : {}),
+        ...(typeof b['verified'] === 'boolean' ? { verified: b['verified'] } : {}),
+        ...(typeof b['verified_type'] === 'string' ? { verifiedType: b['verified_type'] } : {}),
+        ...(b['public_metrics'] && typeof b['public_metrics'] === 'object' ? { publicMetrics: b['public_metrics'] } : {}),
+        ...(typeof b['url'] === 'string' ? { url: b['url'] } : {}),
+        ...(typeof b['confirmed_email'] === 'string' ? { confirmedEmail: b['confirmed_email'] } : {}),
+      }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  if (req.method === 'POST' && path === '/_twin/session') {
+    const b = json();
+    if (!b || typeof b['account_id'] !== 'string' || !b['account_id']) return oauthError('invalid_request', 'account_id is required', 400);
+    if (!readOne(root, 'account', b['account_id'] as string)) return oauthError('invalid_request', 'Unknown account.', 400);
+    const row = await writeAtomic('session', 'current', 'session.switch', () => ({ accountId: b['account_id'] }), opts);
+    return { status: 200, body: row };
+  }
+  if (req.method === 'POST' && path === '/_twin/rate_limit') {
+    // Arm a deterministic rate state (the figma armed-429 precedent): set the used count for a
+    // user's users_me window so a verify can prove the 429 without 75 real spends.
+    const b = json();
+    if (!b || typeof b['account_id'] !== 'string' || typeof b['used'] !== 'number') {
+      return oauthError('invalid_request', 'account_id and used are required', 400);
+    }
+    const windowId = `users_me:${b['account_id']}`;
+    const row = await writeAtomic(
+      'rate_window',
+      windowId,
+      'rate_window.arm',
+      () => ({ windowStart: nowSeconds(req.occurredAt), used: b['used'] }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  return null;
+}
+
+// ── public entry + router ───────────────────────────────────────────────────────────────────────
+
+export async function handleXIdentityTwinRequest(req: XIdentityRequest): Promise<XResponse> {
+  try {
+    return await routeXIdentityTwinRequest(req);
+  } catch (e) {
+    // MALFORMED-REQUEST GUARD (route boundary), the gemini/googleoauth precedent: a residual
+    // TypeError (a wrong-typed field the router walked) or URIError (bad percent-encoding) becomes
+    // the vendor's own 400 envelope instead of escaping as a non-vendor 500 — in the error FAMILY
+    // of the endpoint that failed: the /2 resource surface speaks problem envelopes, the OAuth
+    // endpoints speak the flat RFC body (§9 round one: one family for both misdescribed the /2
+    // contract). Every OTHER error type still propagates loudly rather than being masked as a
+    // caller mistake.
+    if (e instanceof TypeError || e instanceof URIError) {
+      // The flat OAuth body is the right family for every REACHABLE throw site: the only decode
+      // that can raise these lives in the token/revoke client authentication (the Basic
+      // percent-decode), and the /2/users read path walks nothing that throws them. A /2-family
+      // problem-envelope branch here was removed as unfalsifiable (§9 round two) — if a /2 path
+      // ever gains a throwing walk, add the branch WITH the test that reddens on its removal.
+      return oauthError('invalid_request', 'Request contains an invalid argument.', 400);
+    }
+    const { path } = splitPath(typeof req.path === 'string' ? req.path : '/');
+    if (path.startsWith('/2/') && path !== '/2/oauth2/token' && path !== '/2/oauth2/revoke') {
+      return internalServerProblem();
+    }
+    if (path === AUTHORIZE_PATH || path.startsWith('/_twin/consent')) {
+      return errorPage(req, { status: 500, code: 'server_error', detail: 'The authorization server could not complete the request.' });
+    }
+    return oauthError('server_error', 'The authorization server could not complete the request.', 500);
+  }
+}
+
+async function routeXIdentityTwinRequest(req: XIdentityRequest): Promise<XResponse> {
+  const method = req.method.toUpperCase();
+  const { path, query } = splitPath(req.path);
+  const form = new URLSearchParams(method === 'GET' || method === 'HEAD' ? '' : (req.body ?? ''));
+
+  // D3: a read-only twin cannot mint credentials or settle consent. GET /2/users/me stays served
+  // (a read), with rate accounting suspended. The refusal is an OAuth error body, so a client sees
+  // a protocol error rather than an HTML surprise.
+  const writes = path.startsWith('/_twin/') || path === '/2/oauth2/token' || path === '/2/oauth2/revoke';
+  if (req.readOnly && writes) {
+    return oauthError('temporarily_unavailable', 'this twin was started read-only; omit readOnly to accept writes', 405);
+  }
+
+  // Seeding is idempotent and cheap; doing it at the router boundary means every entry point sees
+  // a world with clients, personas and a signed-in session — exactly what a browser at x.com has.
+  if (!req.readOnly) await ensureSeed({ root: req.root, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), ...((req.callbackOrigin ?? req.origin) ? { origin: req.callbackOrigin ?? req.origin } : {}) });
+
+  const control = await twinControl(req, path, form);
+  if (control) return control;
+
+  if (method === 'GET' && path === AUTHORIZE_PATH) return authorize(req, query);
+  if (method === 'POST' && path === '/2/oauth2/token') return token(req);
+  if (method === 'POST' && path === '/2/oauth2/revoke') return revoke(req);
+  if (method === 'GET' && path === '/2/users/me') return usersMe(req, query);
+
+  // An operation the twin does not model fails like the vendor — never a fake success. The /2
+  // problem envelope is the not-found shape; unclaimed paths on the twinned hosts refuse loudly.
+  return notFoundProblem();
+}