@volter/twin-xidentity 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @volter/twin-xidentity
+
+A local, stateful, vendor-faithful twin of **X (Twitter) identity** — the x.com authorize screen,
+the full OAuth 2.0 authorization-code + PKCE round trip (token, refresh, revoke), and
+`GET /2/users/me` with X's real field/expansion/problem envelopes. Point an unmodified X client at
+it and complete a whole sign-in-with-X flow offline.
+
+```bash
+bun run packages/twin/xidentity/src/cli.ts mirror
+# xidentity twin (X OAuth 2.0 + /2/users/me) at http://127.0.0.1:54321
+# authorize screen: http://127.0.0.1:54321/i/oauth2/authorize?response_type=code&client_id=…
+```
+
+## Deliberately NON-OIDC — because the vendor is
+
+X's OAuth 2.0 issues **opaque bearer tokens**: no `id_token`, no JWKS, no discovery document.
+Identity is fetched from `GET /2/users/me` with the access token. That non-OIDC shape is the whole
+reason this vendor needs its own pack next to `googleoauth` — an integration built against an OIDC
+provider (id_token claims, `openid email profile` scopes) breaks against X in exactly the ways this
+twin reproduces: the scope model is X's own catalog (the OpenAPI's 24 scopes plus the announcement-added
+`users.email`, which gates `confirmed_email` — a recorded intra-vendor discrepancy), the refresh
+token only arrives with `offline.access`, PKCE is **required**, and the only identity read is the
+API call.
+
+It is a **browser-facing protocol pack** (the `googleoauth` class): the authorize screen is served
+as HTML at the vendor's real path (`/i/oauth2/authorize`), server-rendered from the twin's own
+kernel projection by the **same React components** the browser bundle ships — one renderer, so
+API↔UI parity cannot drift. The decision is two plain `<form>` submits ("Authorize app" /
+"Cancel"), so **no JavaScript is required to complete an OAuth round trip** against this twin. The
+bundle and stylesheet the twin serves are **committed text** (`src/xidentity-consent-client.gen.ts`,
+written from `client/` by `bun scripts/consent-clients.ts` and drift-gated by
+`scripts/consent-clients.test.ts`): the serve path reads constants and never runs a bundler.
+
+## Coverage
+
+Partial and honest. The manifest (`src/xidentity-capabilities.ts`) is the **enumerated identity
+service-area** denominator, not a claim to enumerate the whole X vendor surface. It is authored
+top-down from X's own artefacts (all fetched 2026-08-21): the **X API
+v2 OpenAPI document** (2.167) for `/2/users/me`, the Problem error family and the 24-scope catalog
+with X's consent descriptions; the **docs.x.com OAuth 2.0 guides** for the authorize/token/refresh/
+revoke requests; the **docs.x.com rate-limit pages** for the `x-rate-limit-*` headers and the
+75/15-minute per-user figure; and the **official SDK sources** (`@xdevplatform/xdk`,
+`twitter-api-typescript-sdk`) for the token/revoke response shapes the docs never show as JSON.
+It currently reads **82 done / 131 covered** (49 `todo`, and the login leg is not an API surface: it is the seeded session, so it is not in that
+denominator). The `todo`s are real X identity
+surface this twin does not model — most notably **OAuth 1.0a three-legged sign-in**, the **v1.1
+app-only bearer flow**, the unmodelled `user.fields` (entities, withheld, subscription, the
+relational fields), expansion hydration — plus a family of **wire-pinning todos**: behaviours the
+twin models from RFC 6749/7009 or widely-reported captures because no fetched official artefact
+states them (exact token error wording, the authorize error channel, refresh-token rotation, the
+code TTL). Each such `done` names its evidence boundary in the manifest and its pinning todo.
+
+### What is real here
+
+- **The complete round trip.** Authorization request → authorize screen → 302 to `redirect_uri`
+  with exactly `state`+`code` (the documented callback shape) → the code is redeemable **exactly
+  once**, PKCE-verified with real SHA-256 → `refresh_token` grant (rotating) → revoke kills the
+  whole grant. One pack against one state root, so the code minted at the screen is honoured at
+  the token endpoint by construction.
+- **PKCE required**, `S256` and `plain`, exactly as X requires it; the legacy official SDK's
+  lowercase `s256` spelling is accepted because the vendor's own client emits it.
+- **Exact callback matching** — X documents exact-match validation, so a trailing slash is a
+  different URI and `redirect_uri_mismatch`-class bugs reproduce.
+- **Confidential vs public clients** — HTTP Basic for confidential (the docs' rule), body
+  `client_id` for public; a confidential client without its Basic header is refused.
+- **Vendor-shaped opaque credentials** — the twin's codes/tokens are base64url blobs whose decoded
+  structure (`<opaque>:<unix-ms>:1:1:ac|at|rt:1`) matches what the docs' own examples decode to.
+- **The identity read** — `GET /2/users/me` with the OpenAPI's scope demands (`tweet.read` +
+  `users.read`), the 24-value `user.fields` enum with the wire's invalid-parameter envelope, the
+  documented `x-rate-limit-*` headers, 75/15min per-user accounting, and the documented
+  429 + legacy code 88 refusal.
+- **SDK fidelity** — the unmodified current official SDK (`@xdevplatform/xdk`) drives
+  `users.getMe()` against the twin through its own public `baseUrl` config
+  (`xidentity-sdk.integration.test.ts`); the OAuth legs its hardcoded hosts cannot re-aim are
+  proven over real transport in the docs' own curl shapes.
+
+### What is not
+
+The twin **authenticates nobody**: no password, no 2FA, no risk engine. The
+x.com "signed in" session is a seeded persona row — `POST /_twin/session` switches it, which is the
+honest local equivalent of "the browser is already signed in". This is the **identity service-area**
+of the X vendor twin. Posts, timelines, DMs and the rest of the X content API are additional
+service-areas to add within this same pack; they are not a reason to create a second X vendor pack.
+
+### Twin-only scaffolding (not vendor surface, not counted)
+
+`GET /_twin/consent` (re-render a pending authorize screen by request handle) and
+`POST /_twin/consent` (the Authorize/Cancel form post — X's real form posts to an undocumented
+internal endpoint), `POST /_twin/clients`, `POST /_twin/accounts`, `POST /_twin/session`,
+`POST /_twin/rate_limit` (arm a deterministic 429), and the `/_twin/assets/*` page assets. This
+list is the audit trail the conformance census deliberately excludes — keep it in lockstep with
+`twinControl`'s branches in `xidentity-twin.ts`.
+
+## The three operations
+
+- **pull** — `syncXIdentityFromReal(execute)` observes the real account behind the operator's own
+  user token (`GET /2/users/me`, every modelled field) over an **injected executor**; live runs use
+  `liveXIdentityExecute(accessToken)`, the ONE place a real X request may be issued, guarded by the
+  fail-closed rate budget (`xidentity-budget.ts`: X's own 75/15min scheme, live-fetched
+  2026-08-21). The client registry and the grant's scope set are **not observable** (no API reads
+  X Apps; X has no token introspection) — reasoned gaps, not fakes.
+- **write** — the default: local consent flows mint local credentials, no real calls.
+- **push** — structurally impossible (X exposes no write API for this surface) and reported as
+  such, never faked.
+
+## Serving
+
+`world-xidentity serve` starts one server for the WHOLE surface; point `x.com`, `twitter.com`,
+`api.x.com` and `api.twitter.com` at it (the injector's `xidentity` `VENDOR_HOSTS` entry does
+exactly that). `mirror` is the same server plus a ready-to-open authorize URL; `conformance` runs
+the endpoint census (one real probe per claimed endpoint + the hand-enumerated router surface +
+a reachability witness per resource type).

package/client/xidentity-consent.css

@@ -0,0 +1,204 @@
+/* X authorize screen — the twin's rendering of x.com's OAuth consent page. Dark, single-column,
+   pill buttons: the visual grammar of the real page, sized for the journey filmstrip review. */
+
+:root {
+  color-scheme: dark;
+  --x-bg: #000000;
+  --x-card: #000000;
+  --x-text: #e7e9ea;
+  --x-muted: #71767b;
+  --x-border: #2f3336;
+  --x-primary: #eff3f4;
+  --x-primary-text: #0f1419;
+  --x-danger: #f4212e;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--x-bg);
+  color: var(--x-text);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  display: flex;
+  justify-content: center;
+  padding: 32px 16px;
+}
+
+.card {
+  width: 100%;
+  max-width: 600px;
+  background: var(--x-card);
+  border: 1px solid var(--x-border);
+  border-radius: 16px;
+  padding: 32px 32px 24px;
+}
+
+.x-header {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.x-mark {
+  font-size: 32px;
+  line-height: 1;
+  color: var(--x-text);
+}
+
+.signed-in {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  border: 1px solid var(--x-border);
+  border-radius: 9999px;
+  padding: 8px 16px;
+  margin: 0 auto 20px;
+  width: fit-content;
+}
+
+.avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background: #1d9bf0;
+  color: #fff;
+  font-weight: 700;
+  font-size: 18px;
+}
+
+.account-text {
+  display: flex;
+  flex-direction: column;
+}
+
+.account-name {
+  font-weight: 700;
+  font-size: 15px;
+}
+
+.account-username {
+  color: var(--x-muted);
+  font-size: 14px;
+}
+
+.title {
+  font-size: 23px;
+  font-weight: 800;
+  text-align: center;
+  margin: 0 0 24px;
+}
+
+.app-name {
+  font-weight: 800;
+}
+
+.scope-section {
+  margin-bottom: 20px;
+}
+
+.scope-heading {
+  font-size: 17px;
+  font-weight: 700;
+  margin: 0 0 8px;
+}
+
+.scope-list {
+  list-style: disc;
+  margin: 0;
+  padding-left: 24px;
+}
+
+.scope-row {
+  font-size: 15px;
+  color: var(--x-text);
+  margin-bottom: 6px;
+}
+
+.scope-tag {
+  margin-left: 8px;
+  font-size: 12px;
+  border: 1px solid var(--x-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  color: var(--x-muted);
+}
+
+.scope-tag-unknown {
+  color: var(--x-danger);
+  border-color: var(--x-danger);
+}
+
+.consent-form {
+  margin-top: 24px;
+}
+
+.actions {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.btn {
+  border-radius: 9999px;
+  font-size: 17px;
+  font-weight: 700;
+  padding: 12px 24px;
+  cursor: pointer;
+  border: 1px solid var(--x-border);
+  background: transparent;
+  color: var(--x-text);
+}
+
+.btn-primary {
+  background: var(--x-primary);
+  color: var(--x-primary-text);
+  border-color: var(--x-primary);
+}
+
+.btn-primary:hover {
+  background: #d7dbdc;
+}
+
+.btn-secondary:hover {
+  background: #16181c;
+}
+
+.legal {
+  margin-top: 20px;
+  color: var(--x-muted);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.redirect-host {
+  color: var(--x-text);
+}
+
+.card-error .title {
+  margin-bottom: 12px;
+}
+
+.error-detail {
+  font-size: 15px;
+  text-align: center;
+  color: var(--x-text);
+}
+
+.error-code {
+  text-align: center;
+  color: var(--x-muted);
+  font-size: 14px;
+}
+
+.error-request {
+  text-align: center;
+  color: var(--x-muted);
+  font-size: 13px;
+  word-break: break-all;
+}

package/client/xidentity-consent.tsx

@@ -0,0 +1,162 @@
+// X's AUTHORIZE SCREEN, as React — the vendor's own product UI, not a dashboard mirror.
+//
+// These components are the ONE renderer for the screen: the twin server-renders them with
+// `renderToStaticMarkup` to answer `GET /i/oauth2/authorize`, the capability verifies render the
+// SAME exported components over the SAME projection, and the Playwright journey drives the HTML
+// they emit. There is no second implementation to drift from.
+//
+// PROGRESSIVE ENHANCEMENT, DELIBERATELY: the decision is a plain `<form>` POST with two submit
+// buttons — X's real page is exactly two choices, "Authorize app" and "Cancel", with no per-scope
+// checkboxes — so no JavaScript is required to complete an OAuth round trip against this twin
+// (headless browsers, `curl`, and redirect-following libraries all work).
+//
+// LAYOUT PROVENANCE: the section headings ("Things App can view…" / "…do…"), the two buttons and
+// the redirect notice reproduce X's authorize page as widely screenshotted; the exact live DOM was
+// not captured from a vendor artefact, so visual fidelity is certified by the journey filmstrip
+// review, not asserted as a pin.
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+export type ConsentAccount = {
+  id: string;
+  username: string;
+  name: string;
+  profileImageUrl: string;
+};
+
+export type ConsentScopeRow = {
+  scope: string;
+  label: string;
+  group: 'view' | 'do' | 'session';
+  known: boolean;
+};
+
+export type ConsentApp = {
+  clientId: string;
+  name: string;
+};
+
+export type ConsentView = {
+  requestId: string;
+  /** Where the twin is reachable — the form action posts back here. */
+  origin: string;
+  app: ConsentApp;
+  /** The x.com session this browser is signed in as — the account that will consent. */
+  account: ConsentAccount;
+  scopes: ConsentScopeRow[];
+  /** Host of the validated redirect_uri, shown in the "you'll be redirected to" notice. */
+  redirectHost: string;
+};
+
+/** The X mark, drawn rather than fetched — a twin never reaches out to a vendor CDN. */
+function XMark() {
+  return (
+    <span className="x-mark" aria-hidden="true">
+      𝕏
+    </span>
+  );
+}
+
+function ScopeSection({ heading, rows }: { heading: string; rows: ConsentScopeRow[] }) {
+  if (rows.length === 0) return null;
+  return (
+    <section className="scope-section">
+      <h2 className="scope-heading">{heading}</h2>
+      <ul className="scope-list">
+        {rows.map((row) => (
+          <li key={row.scope} className="scope-row">
+            <span className="scope-text">{row.label}</span>
+            {row.known ? null : <span className="scope-tag scope-tag-unknown">not in the twin&apos;s scope catalog</span>}
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+/** The authorize screen — X's consent page for the app named by the pending auth request. */
+export function ConsentPage({ view }: { view: ConsentView }) {
+  const appName = view.app.name;
+  return (
+    <div className="card">
+      <header className="x-header">
+        <XMark />
+      </header>
+      <div className="signed-in">
+        <span className="account-text">
+          {/* A partially-pulled persona may lack a display name or handle; the fallback shows the
+              REAL id rather than an empty pill or a bare "@" (never an invented placeholder). */}
+          <span className="account-name">{view.account.name || view.account.username || view.account.id}</span>
+          {view.account.username ? <span className="account-username">@{view.account.username}</span> : null}
+        </span>
+      </div>
+      <h1 className="title">
+        <strong className="app-name">{appName}</strong> wants to access your X account
+      </h1>
+      <ScopeSection heading={`Things ${appName} can view`} rows={view.scopes.filter((s) => s.group === 'view')} />
+      <ScopeSection heading={`Things ${appName} can do`} rows={view.scopes.filter((s) => s.group === 'do')} />
+      <ScopeSection heading="Until you revoke access" rows={view.scopes.filter((s) => s.group === 'session')} />
+      <form method="POST" action={`${view.origin}/_twin/consent`} className="consent-form">
+        <input type="hidden" name="auth_request" value={view.requestId} />
+        <div className="actions">
+          <button className="btn btn-primary" type="submit" name="decision" value="allow">
+            Authorize app
+          </button>
+          <button className="btn btn-secondary" type="submit" name="decision" value="deny">
+            Cancel
+          </button>
+        </div>
+      </form>
+      <p className="legal">
+        You&apos;ll be redirected to <strong className="redirect-host">{view.redirectHost}</strong>. You can revoke
+        access to any app at any time from the Apps and sessions section of your X settings.
+      </p>
+    </div>
+  );
+}
+
+export type ErrorPageProps = {
+  status: number;
+  /** The OAuth error code the failure classifies as (e.g. `invalid_request`). */
+  code: string;
+  detail: string;
+  /** The offending parameter, echoed for the developer. */
+  requestParam?: string;
+};
+
+/**
+ * The authorize-endpoint error PAGE — what a browser sees when the twin cannot trust the
+ * redirect_uri (unknown client, unregistered callback) and therefore must not bounce the error
+ * back to it. X's live page for this case renders a terse "Something went wrong" card; its exact
+ * DOM was not captured, so this page states the failure plainly and machine-readably rather than
+ * imitating unverified vendor prose (`xidentity.authorize.error_page_fidelity`, todo).
+ */
+export function ErrorPage({ status, code, detail, requestParam }: ErrorPageProps) {
+  return (
+    <div className="card card-error">
+      <header className="x-header">
+        <XMark />
+      </header>
+      <h1 className="title">Something went wrong</h1>
+      <p className="error-detail">You weren&apos;t able to give access to the App. {detail}</p>
+      <p className="error-code">
+        Error {status}: {code}
+      </p>
+      {requestParam ? <p className="error-request">Request details: {requestParam}</p> : null}
+    </div>
+  );
+}
+
+/**
+ * The bundled browser entry. The screen is fully functional server-side; the bundle only marks the
+ * document as enhanced (a hook for future affordances) without re-rendering server markup, so the
+ * no-JavaScript path and the enhanced path agree by construction.
+ */
+export function hydrateConsentControls(): void {
+  const slot = document.getElementById('consent-enhanced');
+  if (!slot) return;
+  createRoot(slot).render(<StrictMode>{null}</StrictMode>);
+  document.documentElement.dataset['twinEnhanced'] = 'true';
+}
+
+if (typeof document !== 'undefined') hydrateConsentControls();