@volter/twin-xidentity 0.1.0

package/src/xidentity-consent-ui.ts

@@ -0,0 +1,113 @@
+// X identity twin — the SERVER HALF of the authorize screen.
+//
+// Named `-consent-ui` rather than `-mirror-ui` on purpose (the googleoauth class doctrine): a
+// dashboard mirror is a SECOND renderer this repo writes over a vendor's data, whereas this is the
+// vendor's OWN page, on the vendor's OWN path, in the middle of the vendor's OWN protocol. The
+// mirror DISCIPLINE still applies in full — one renderer, data-coupled to the projection, driven
+// by a real browser journey.
+//
+// The pieces:
+//   • `xIdentityConsentState` — THE STATE BUILDER. Everything on screen is derived here, from the
+//     kernel projection, and nowhere else. It is the seam `scripts/mutation-test.ts` sabotages in
+//     the mirror phase (TWIN-20/B9): with it dead the screen has no app name, no account and no
+//     scopes, so every UI capability must go red while the write/handler path stays real.
+//   • `consentPageHtml` / `errorPageHtml` — server-render the REAL exported React components with
+//     `renderToStaticMarkup`. There is no template string of vendor markup anywhere.
+//   • `CONSENT_CLIENT_JS` / `CONSENT_CLIENT_CSS` — the browser bundle and stylesheet as COMMITTED TEXT
+//     (`xidentity-consent-client.gen.ts`, written by `scripts/consent-clients.ts` and drift-gated):
+//     progressive enhancement only, and the serve path never builds (runtime contract R12b, R9).
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import {
+  ConsentPage,
+  ErrorPage,
+  type ConsentAccount,
+  type ConsentScopeRow,
+  type ConsentView,
+  type ErrorPageProps,
+} from '../client/xidentity-consent.tsx';
+import { describeScopes, parseScopeParam, sortScopesForConsent } from './xidentity-scopes.ts';
+import { readOne, type Row } from './xidentity-store.ts';
+
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from '../client/xidentity-consent.tsx';
+export { XIDENTITY_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, XIDENTITY_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from './xidentity-consent-client.gen.ts';
+
+/** Twin-only asset paths, clearly namespaced so they can never be mistaken for vendor surface. */
+export const CONSENT_SCRIPT_PATH = '/_twin/assets/consent.js';
+export const CONSENT_STYLE_PATH = '/_twin/assets/consent.css';
+
+function toConsentAccount(row: Row): ConsentAccount {
+  return {
+    id: row.id,
+    username: String(row.username ?? ''),
+    name: String(row.name ?? ''),
+    profileImageUrl: String(row.profileImageUrl ?? ''),
+  };
+}
+
+/**
+ * THE STATE BUILDER — the authorize screen's entire view model, folded out of the kernel
+ * projection. Returns `null` when the authorization request is unknown or already settled, or when
+ * no x.com session exists to consent as (the caller renders the error page); it never invents an
+ * app name, an account or a scope row.
+ */
+export function xIdentityConsentState(opts: {
+  root?: string;
+  requestId: string;
+  origin: string;
+}): ConsentView | null {
+  const authRequest = readOne(opts.root, 'auth_request', opts.requestId);
+  if (!authRequest || authRequest.settled === true) return null;
+  const client = readOne(opts.root, 'oauth_client', String(authRequest.clientId));
+  if (!client) return null;
+  const account = readOne(opts.root, 'account', String(authRequest.accountId ?? ''));
+  if (!account) return null;
+
+  const requested = sortScopesForConsent(parseScopeParam(String(authRequest.scope ?? '')));
+  const scopes: ConsentScopeRow[] = describeScopes(requested).map((s) => ({
+    scope: s.scope,
+    label: s.label,
+    group: s.group,
+    known: s.known,
+  }));
+
+  let redirectHost = '';
+  try {
+    redirectHost = new URL(String(authRequest.redirectUri)).host;
+  } catch {
+    redirectHost = String(authRequest.redirectUri);
+  }
+
+  return {
+    requestId: opts.requestId,
+    origin: opts.origin,
+    app: { clientId: client.id, name: String(client.name ?? '') },
+    account: toConsentAccount(account),
+    scopes,
+    redirectHost,
+  };
+}
+
+/** `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount path),
+ *  so the page's assets resolve inside the World's mount; empty for an in-process render. */
+function page(title: string, bodyMarkup: string, base: string): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title><link rel="stylesheet" href="${base}${CONSENT_STYLE_PATH}"></head>
+<body>${bodyMarkup}<div id="consent-enhanced"></div><script type="module" src="${base}${CONSENT_SCRIPT_PATH}"></script></body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Render the authorize page from a view model. The tab title mirrors X's "Authorize <app>". */
+export function consentPageHtml(view: ConsentView, base = ''): string {
+  const markup = renderToStaticMarkup(createElement(ConsentPage, { view }));
+  return page(`Authorize ${view.app.name} to access your account? / X`, markup, base);
+}
+
+/** Render the authorize-endpoint error page (an un-redirectable failure). */
+export function errorPageHtml(props: ErrorPageProps, base = ''): string {
+  return page(`Error ${props.status}: ${props.code} / X`, renderToStaticMarkup(createElement(ErrorPage, props)), base);
+}

package/src/xidentity-journey.uitest.ts

@@ -0,0 +1,277 @@
+// X IDENTITY UI JOURNEY — the authorize leg, driven in a real headless chromium.
+//
+// The browser is the protocol participant: the app redirects, a human reads what the App is asking
+// for, clicks "Authorize app" (or Cancel), and the browser is bounced back to the app's callback
+// carrying a code — which the test then REDEEMS at the twin's token endpoint and USES at
+// /2/users/me. A journey that stopped at "the screen rendered" would prove the page exists; this
+// one proves the round trip closes.
+//
+// Seeds through the pack's OWN write path (the twin-only client/session controls and the real
+// authorize endpoint — never a hand-written events.jsonl), boots the real twin handler on an
+// ephemeral port with the app's callback page alongside it (see `startJourneyServer`), and drives
+// it with role/text locators only. Every step writes a filmstrip frame (the harness helpers do
+// it), so a reviewer can LOOK at the screens rather than trusting a green tick.
+import { describe, expect, test } from 'bun:test';
+import { atPath, clickByName, requireBrowser, runUiJourney, visible } from '@volter/world-tooling';
+import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from './xidentity-consent-ui.ts';
+import { pkceS256 } from './xidentity-pkce.ts';
+import { DEFAULT_ACCOUNTS } from './xidentity-store.ts';
+import { handleXIdentityTwinRequest } from './xidentity-twin.ts';
+
+const JOURNEY_LABEL = 'xidentity UI journey';
+
+const CLIENT_ID = 'Sm91cm5leVNjaGVkdWxlcjoxOmNp';
+const CLIENT_SECRET = 'journey-secret-0000000000000000000000000000000000';
+const APP_NAME = 'Twin Journey Scheduler';
+const SCOPE = 'tweet.read users.read offline.access';
+const VERIFIER = 'journey-verifier-0123456789-0123456789-01234567';
+const ADA = DEFAULT_ACCOUNTS[0]!;
+/** The integrating app's callback, served on the same loopback origin (see `startJourneyServer`). */
+const APP_CALLBACK_PATH = '/oauth/callback';
+
+/**
+ * The journey's server: the REAL twin handler, plus a tiny `/oauth/callback` page standing in for
+ * the integrating app.
+ *
+ * WHY THEY SHARE ONE ORIGIN. The journey harness is loopback-only and installs a route guard that
+ * ABORTS any request leaving the server origin it was given (`uiJourney.ts`) — so a callback
+ * server on its own port is unreachable from the piloted page. Sharing the loopback origin is a
+ * harness accommodation, not a fidelity claim; the SDK fidelity test exercises the ordinary
+ * cross-origin configuration. What the journey proves is the leg only a browser can: a human's
+ * click turning into a code on the app's callback URL.
+ */
+function startJourneyServer(root: string): { url: string; stop: () => void; last: () => URL | null } {
+  let last: URL | null = null;
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    idleTimeout: 30,
+    async fetch(request) {
+      const url = new URL(request.url);
+
+      // ── the harness's landing page ──
+      // `runUiJourney` navigates to the server URL and waits for `#root` to have children before
+      // it hands the page over. A vendor twin has no app shell at `/` (x.com's root is the
+      // timeline, which this pack does not model), so the JOURNEY supplies one. Test scaffolding
+      // in this file — never pack surface.
+      if (url.pathname === '/') {
+        return new Response(
+          `<!doctype html><html><body><div id="root"><h1>Twin X world</h1>`
+            + `<p>the ${APP_NAME} integration starts by redirecting to the x.com authorize page</p></div></body></html>`,
+          { headers: { 'content-type': 'text/html; charset=utf-8' } },
+        );
+      }
+
+      // ── the app's callback ──
+      if (url.pathname === APP_CALLBACK_PATH) {
+        last = url;
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        const body = code
+          ? `<h1>${APP_NAME}</h1><p>authorization code received</p><pre>${code}</pre>`
+          : `<h1>${APP_NAME}</h1><p>authorization failed</p><pre>${error ?? 'no error parameter'}</pre>`;
+        return new Response(`<!doctype html><html><body>${body}</body></html>`, {
+          headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
+      }
+
+      // ── everything else: the real twin ──
+      if (request.method === 'GET' && url.pathname === CONSENT_SCRIPT_PATH) {
+        return new Response(CONSENT_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && url.pathname === CONSENT_STYLE_PATH) {
+        return new Response(CONSENT_CLIENT_CSS, { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+      const res = await handleXIdentityTwinRequest({
+        method: request.method,
+        path: url.pathname + (url.search || ''),
+        body,
+        headers,
+        root,
+        occurredAt: new Date().toISOString(),
+        origin: url.origin,
+      });
+      const out = { ...(res.headers ?? {}) };
+      if (typeof res.body === 'string') {
+        if (!out['content-type'] && res.body) out['content-type'] = 'text/html; charset=utf-8';
+        return new Response(res.body, { status: res.status, headers: out });
+      }
+      out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
+      return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
+    },
+  });
+  return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop(true), last: () => last };
+}
+
+/** Register the journey's OAuth client through the twin's own write path. */
+async function seedClient(twinOrigin: string, redirectUri: string) {
+  const res = await fetch(`${twinOrigin}/_twin/clients`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      name: APP_NAME,
+      client_type: 'confidential',
+      redirect_uris: [redirectUri],
+    }),
+  });
+  expect(res.status).toBe(200);
+}
+
+const authUrl = (twinOrigin: string, redirectUri: string, extra: Record<string, string> = {}) =>
+  `${twinOrigin}/i/oauth2/authorize?${new URLSearchParams({
+    response_type: 'code',
+    client_id: CLIENT_ID,
+    redirect_uri: redirectUri,
+    scope: SCOPE,
+    state: 'journey-state-1',
+    code_challenge: pkceS256(VERIFIER),
+    code_challenge_method: 'S256',
+    ...extra,
+  })}`;
+
+describe('xidentity UI journey', () => {
+  test('a human reads the authorize screen, clicks Authorize app — and the code redeems into a usable identity', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    // Captured inside the journey while the server is still up; asserted after teardown, so a
+    // torn-down fixture can never read as a product failure.
+    let redeemed: Record<string, any> | null = null;
+    let identity: Record<string, any> | null = null;
+    let callback: URL | null = null;
+
+    await runUiJourney({
+      label: 'xidentity authorize round trip',
+      // The pack's write path IS its HTTP server, and the harness calls `seed` BEFORE `serve` —
+      // so the client registration happens as the journey's first step instead of here.
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+
+        // 1. The app redirects the browser to the vendor. What lands is X's AUTHORIZE screen,
+        //    naming the registered app, the signed-in account, and the scopes in X's own wording.
+        await page.goto(authUrl(origin, redirectUri));
+        await atPath(page, '/i/oauth2/authorize');
+        await visible(page, `${APP_NAME} wants to access your X account`);
+        await visible(page, ADA.name);
+        await visible(page, `@${ADA.username}`);
+        await visible(page, `Things ${APP_NAME} can view`);
+        await visible(page, 'View all posts you can see, including those from protected accounts.');
+        await visible(page, 'View any account you can see, including protected accounts.');
+        await visible(page, 'Stay connected to your account until you revoke access.');
+
+        // 2. Authorize. The browser leaves the vendor's path and lands on the APP's callback.
+        await clickByName(page, 'Authorize app');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization code received');
+
+        callback = new URL(page.url());
+        const code = callback.searchParams.get('code')!;
+
+        // 3. THE POINT OF THE WHOLE FLOW: the code a browser CLICK produced is redeemable at the
+        //    token endpoint, and the token it yields answers /2/users/me with the account that
+        //    was signed in on the screen.
+        const tokenRes = await fetch(`${origin}/2/oauth2/token`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+            authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
+          },
+          body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            client_id: CLIENT_ID,
+            redirect_uri: redirectUri,
+            code_verifier: VERIFIER,
+          }).toString(),
+        });
+        redeemed = (await tokenRes.json()) as Record<string, any>;
+
+        const me = await fetch(`${origin}/2/users/me`, {
+          headers: { authorization: `Bearer ${redeemed.access_token}` },
+        });
+        identity = (await me.json()) as Record<string, any>;
+      },
+    });
+
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(Buffer.from(callback!.searchParams.get('code')!, 'base64url').toString('utf8')).toContain(':ac:');
+    expect(redeemed!.token_type).toBe('bearer');
+    expect(redeemed!.scope).toBe(SCOPE);
+    expect(Buffer.from(String(redeemed!.refresh_token), 'base64url').toString('utf8')).toContain(':rt:');
+    // The account that was on the screen is the identity the token yields — the click really
+    // consented as that person.
+    expect(identity!.data.id).toBe(ADA.id);
+    expect(identity!.data.username).toBe(ADA.username);
+  }, 30_000);
+
+  test('Cancel bounces back with error=access_denied and no code', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    let callback: URL | null = null;
+    await runUiJourney({
+      label: 'xidentity authorize denial',
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+
+        await page.goto(authUrl(origin, redirectUri));
+        await visible(page, `${APP_NAME} wants to access your X account`);
+        await clickByName(page, 'Cancel');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization failed');
+        await visible(page, 'access_denied');
+        callback = new URL(page.url());
+      },
+    });
+
+    expect(callback!.searchParams.get('error')).toBe('access_denied');
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(callback!.searchParams.get('code')).toBeNull();
+  }, 30_000);
+
+  test('a misconfigured redirect_uri stays on the vendor error page, and the app is NEVER reached', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    let finalUrl = '';
+    // The HANDLE, kept so the assertion can read it AFTER the journey (the googleoauth §9 lesson:
+    // reading `last()` inside `serve` stores a value that is null by construction, and the
+    // security assertion could then never fail).
+    let app: { last: () => URL | null } | null = null;
+    await runUiJourney({
+      label: 'xidentity redirect_uri mismatch error page',
+      seed: async () => {},
+      serve: (root) => {
+        const server = startJourneyServer(root);
+        app = server;
+        return server;
+      },
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        await seedClient(origin, `${origin}${APP_CALLBACK_PATH}`);
+
+        // The single most common integration bug, seen the way a developer sees it: the browser
+        // STAYS on the vendor showing the error, and the app is never reached.
+        await page.goto(authUrl(origin, `${origin}/oauth/WRONG`));
+        await atPath(page, '/i/oauth2/authorize');
+        await visible(page, 'Something went wrong');
+        await visible(page, 'Error 400: invalid_request');
+        finalUrl = page.url();
+      },
+    });
+
+    expect(new URL(finalUrl).pathname, 'the browser must end on the vendor authorize path showing the error').toBe('/i/oauth2/authorize');
+    // Read AFTER the journey: the app must never have been reached at all.
+    expect(app!.last(), 'the app callback must never have been called').toBeNull();
+  }, 30_000);
+});

package/src/xidentity-pkce.ts

@@ -0,0 +1,29 @@
+// PKCE (RFC 7636) — real SHA-256, no stubs. X's documented code_challenge_method values are
+// `S256` and `plain` (docs.x.com authorization-code guide, fetched 2026-08-21).
+//
+// CASE: the docs write `S256`; X's LEGACY official SDK (twitter-api-typescript-sdk, OAuth2User.
+// generateAuthURL) emits the lowercase `s256` in its authorize URLs, so a twin that refused the
+// lowercase form would refuse the vendor's own client. Both spellings are accepted and normalised
+// here; the exact live tolerance is pinned as a manifest todo rather than asserted
+// (`xidentity.authorize.challenge_method_case`).
+import { createHash } from 'node:crypto';
+
+/** base64url(SHA-256(verifier)) — the S256 code_challenge for a code_verifier. */
+export function pkceS256(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+export type ChallengeMethod = 'S256' | 'plain';
+
+/** Normalise a caller-supplied code_challenge_method, or null when it isn't a documented value. */
+export function normalizeChallengeMethod(raw: string | null): ChallengeMethod | null {
+  if (raw === null) return null;
+  if (raw === 'plain') return 'plain';
+  if (raw.toUpperCase() === 'S256') return 'S256';
+  return null;
+}
+
+/** Does `verifier` satisfy the challenge the code was minted against? */
+export function pkceVerifies(method: ChallengeMethod, challenge: string, verifier: string): boolean {
+  return method === 'S256' ? pkceS256(verifier) === challenge : verifier === challenge;
+}

package/src/xidentity-problems.ts

@@ -0,0 +1,128 @@
+// X API v2 error envelopes — the vendor's THREE distinct error families, kept distinct because an
+// integration can (and X's own SDKs do) branch on them:
+//
+//   1. OAuth token-endpoint errors: the RFC 6749 §5.2 flat body `{ error, error_description }`.
+//      The docs show no error examples (user-access-token guide, fetched 2026-08-21), so the
+//      `error` codes here are RFC 6749's and the descriptions are the widely-reported X wire
+//      strings — the EVIDENCE BOUNDARY is marked at each call site and the exact texts are filed
+//      as `xidentity.token.error_wording` (todo) rather than claimed pinned.
+//
+//   2. v2 problem envelopes (`application/problem+json` shapes): the OpenAPI 2.167 `Problem`
+//      family, discriminated by a `type` URL (`https://api.x.com/2/problems/…`). The generic
+//      auth failure is the `about:blank` form (`{title, type: "about:blank", status, detail}`) —
+//      observed wire behaviour for a bad bearer, marked extrapolated where the doc trail stops.
+//
+//   3. The request-level invalid-parameter envelope: `{errors: [{parameters, message}], title:
+//      "Invalid Request", detail: "One or more parameters to your request was invalid.", type:
+//      …/invalid-request}` — the OpenAPI's InvalidRequestProblem, with the per-parameter `errors`
+//      array the wire carries.
+//
+//   4. The 15-minute-window rate refusal: HTTP 429 with legacy error code 88 — docs.x.com
+//      fundamentals/rate-limits (fetched 2026-08-21) documents "a 429 error with error code 88:
+//      Rate limit exceeded" verbatim, hence the v1.1-style `{errors: [{code, message}]}` body.
+
+export type XResponse = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+
+// ── family 1: OAuth token endpoint (RFC 6749 flat body) ─────────────────────────────────────────
+
+export function oauthError(error: string, description: string, status: number): XResponse {
+  return { status, body: { error, error_description: description }, headers: { ...NOSTORE } };
+}
+
+/**
+ * The ONE answer an unusable authorization code gets — unknown, already-redeemed, expired, minted
+ * for another client, wrong redirect_uri pairing or failed PKCE are deliberately indistinguishable
+ * (telling them apart would leak which codes exist). The description is the widely-reported X wire
+ * string for this case; the `error` code X pairs with it is reported as `invalid_request` (where
+ * RFC 6749 would say `invalid_grant`) and the twin follows the REPORTED WIRE, marked extrapolated.
+ */
+export function badAuthorizationCode(): XResponse {
+  return oauthError('invalid_request', 'Value passed for the authorization code was invalid.', 400);
+}
+
+/** The refresh-token twin of the above — same reported-wire caveat. */
+export function badRefreshToken(): XResponse {
+  return oauthError('invalid_request', 'Value passed for the token was invalid.', 400);
+}
+
+/** Client authentication failed at the token/revoke endpoint (RFC 6749 §5.2: 401 invalid_client). */
+export function invalidClient(): XResponse {
+  return oauthError('invalid_client', 'Client authentication failed.', 401);
+}
+
+// ── family 2: v2 problem envelopes ──────────────────────────────────────────────────────────────
+
+/** The generic auth problem X answers a bad/absent/expired bearer with on /2 resources. */
+export function unauthorizedProblem(): XResponse {
+  return {
+    status: 401,
+    body: { title: 'Unauthorized', type: 'about:blank', status: 401, detail: 'Unauthorized' },
+    headers: { ...NOSTORE, 'content-type': 'application/problem+json' },
+  };
+}
+
+/**
+ * A user token whose scope set does not cover the endpoint. The 403 + problem SHAPE follows the
+ * OpenAPI's default-error contract; X's exact wording for the insufficient-scope case was not
+ * captured from an official artefact, so the twin states the refusal plainly rather than inventing
+ * vendor prose — pinning the live body is `xidentity.users_me.insufficient_scope_wording` (todo).
+ */
+export function forbiddenProblem(detail: string): XResponse {
+  return {
+    status: 403,
+    body: { title: 'Forbidden', type: 'about:blank', status: 403, detail },
+    headers: { ...NOSTORE, 'content-type': 'application/problem+json' },
+  };
+}
+
+/** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
+export function notFoundProblem(): XResponse {
+  return {
+    status: 404,
+    body: { title: 'Not Found Error', type: 'about:blank', status: 404, detail: 'Not Found' },
+    headers: { ...NOSTORE, 'content-type': 'application/problem+json' },
+  };
+}
+
+/** A contained unexpected failure on the v2 resource surface. Never exposes local exception text. */
+export function internalServerProblem(): XResponse {
+  return {
+    status: 500,
+    body: { title: 'Internal Server Error', type: 'about:blank', status: 500, detail: 'Internal Server Error' },
+    headers: { ...NOSTORE, 'content-type': 'application/problem+json' },
+  };
+}
+
+/**
+ * The invalid-parameter envelope (OpenAPI InvalidRequestProblem + the wire's per-parameter
+ * `errors` array). `parameters` maps the offending query parameter to the values it arrived with.
+ */
+export function invalidRequestProblem(parameters: Record<string, string[]>, message: string): XResponse {
+  return {
+    status: 400,
+    body: {
+      errors: [{ parameters, message }],
+      title: 'Invalid Request',
+      detail: 'One or more parameters to your request was invalid.',
+      type: 'https://api.x.com/2/problems/invalid-request',
+    },
+    headers: { ...NOSTORE, 'content-type': 'application/json' },
+  };
+}
+
+// ── family 4: the rate refusal ──────────────────────────────────────────────────────────────────
+
+/** HTTP 429, legacy code 88 — the documented pair (docs.x.com fundamentals/rate-limits). */
+export function rateLimitExceeded(headers: Record<string, string>): XResponse {
+  return {
+    status: 429,
+    body: { errors: [{ code: 88, message: 'Rate limit exceeded' }] },
+    headers: { ...NOSTORE, ...headers, 'content-type': 'application/json' },
+  };
+}

package/src/xidentity-scopes.ts

@@ -0,0 +1,96 @@
+// X OAuth 2.0 scopes — the vendor's own catalog, transcribed VERBATIM from the X API v2 OpenAPI
+// document's `OAuth2UserToken` security scheme (https://api.x.com/2/openapi.json, version 2.167,
+// fetched 2026-08-21). The description strings are X's own consent-screen wording, so the authorize
+// page the twin serves shows exactly what the vendor's shows for each scope.
+//
+// The screen model: X's authorize page is ALL-OR-NOTHING. It lists what the app will be able to
+// view and do, with exactly two buttons — "Authorize app" and "Cancel" — and no per-scope
+// checkboxes (unlike Google's granular consent). The grant is the full requested scope set or
+// nothing.
+
+export type ScopeInfo = {
+  scope: string;
+  /** X's own consent wording for the scope (OpenAPI securityScheme description). */
+  label: string;
+  /** How the authorize screen groups it: things the app can VIEW vs DO vs the session promise. */
+  group: 'view' | 'do' | 'session';
+  /** In the vendor catalog? An unknown scope is still displayed, flagged, so a typo is visible. */
+  known: boolean;
+};
+
+/** The 24 scopes X's OpenAPI declares, plus the announcement-grounded `users.email` (see its
+ *  in-line note), keyed by scope id. */
+export const SCOPE_CATALOG: Record<string, { label: string; group: 'view' | 'do' | 'session' }> = {
+  'block.read': { label: 'View accounts you have blocked.', group: 'view' },
+  'block.write': { label: 'Block and unblock accounts on your behalf.', group: 'do' },
+  'bookmark.read': { label: 'Read your bookmarked Posts.', group: 'view' },
+  'bookmark.write': { label: 'Create and delete your bookmarks.', group: 'do' },
+  'broadcast.read': { label: 'View your live broadcasts and their chat.', group: 'view' },
+  'broadcast.write': { label: 'Manage your live broadcasts and send chat messages on your behalf.', group: 'do' },
+  'dm.read': { label: 'Read all your Direct Messages.', group: 'view' },
+  'dm.write': { label: 'Send and manage your Direct Messages.', group: 'do' },
+  'follows.read': { label: 'View accounts you follow and accounts following you.', group: 'view' },
+  'follows.write': { label: 'Follow and unfollow accounts on your behalf.', group: 'do' },
+  'like.read': { label: 'View Posts you have liked and likes you can see.', group: 'view' },
+  'like.write': { label: 'Like and unlike Posts on your behalf.', group: 'do' },
+  'list.read': { label: 'View Lists, members, and followers of Lists you created or are a member of, including private Lists.', group: 'view' },
+  'list.write': { label: 'Create and manage Lists on your behalf.', group: 'do' },
+  'media.write': { label: 'Upload media, such as photos and videos, on your behalf.', group: 'do' },
+  'mute.read': { label: 'View accounts you have muted.', group: 'view' },
+  'mute.write': { label: 'Mute and unmute accounts on your behalf.', group: 'do' },
+  'offline.access': { label: 'Stay connected to your account until you revoke access.', group: 'session' },
+  'space.read': { label: 'View all Spaces you have access to.', group: 'view' },
+  'timeline.read': { label: 'View all Custom Timelines you can see.', group: 'view' },
+  'tweet.moderate.write': { label: 'Hide and unhide replies to your posts.', group: 'do' },
+  'tweet.read': { label: 'View all posts you can see, including those from protected accounts.', group: 'view' },
+  'tweet.write': { label: 'Create and repost on your behalf.', group: 'do' },
+  'users.read': { label: 'View any account you can see, including protected accounts.', group: 'view' },
+  // NOT in the 2.167 OpenAPI securityScheme catalog (a recorded intra-vendor discrepancy): X's own
+  // April-2025 announcement ("Announcing support for email address retrieval with OAuth 2.0 in the
+  // X API v2", devcommunity.x.com/t/240555, re-fetched 2026-08-21) adds `users.email` as the scope
+  // gating the `confirmed_email` field on /2/users/me. The label is NOT vendor wording —
+  // EXTRAPOLATION, pinned by `xidentity.scopes.users_email_wording` (todo).
+  'users.email': { label: 'Access your email address.', group: 'view' },
+};
+// EVIDENCE BOUNDARY: every label above is the OpenAPI description verbatim EXCEPT `offline.access`,
+// whose OpenAPI description ("Request a refresh token for the app.") is developer-facing, not the
+// consent-screen line. The consent-screen wording used here is the widely-reported "Stay connected
+// …" line; it is not from a fetched official artefact and is marked as such in the manifest
+// (`xidentity.consent.offline_access_wording`, todo).
+
+export const KNOWN_SCOPES: readonly string[] = Object.keys(SCOPE_CATALOG);
+
+/** Space-separated scope param → ordered unique scope list (X formats scope space-separated). */
+export function parseScopeParam(raw: string | null): string[] {
+  if (!raw) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const s of raw.split(/[\s+]+/)) {
+    // `+` appears when a caller form-encodes spaces as plus signs and a layer decodes only %XX.
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+export function formatScopeParam(scopes: readonly string[]): string {
+  return scopes.join(' ');
+}
+
+export function describeScope(scope: string): ScopeInfo {
+  const known = SCOPE_CATALOG[scope];
+  return known
+    ? { scope, label: known.label, group: known.group, known: true }
+    : { scope, label: scope, group: 'view', known: false };
+}
+
+export function describeScopes(scopes: readonly string[]): ScopeInfo[] {
+  return scopes.map(describeScope);
+}
+
+/** Screen order: what the app can view, then what it can do, then the offline promise. */
+export function sortScopesForConsent(scopes: readonly string[]): string[] {
+  const order: Record<'view' | 'do' | 'session', number> = { view: 0, do: 1, session: 2 };
+  return [...scopes].sort((a, b) => order[describeScope(a).group] - order[describeScope(b).group]);
+}