@volter/twin-xidentity 0.1.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@volter/twin-xidentity",
+  "version": "0.1.0",
+  "description": "Local X (Twitter) identity twin — the real 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, so an unmodified X client completes sign-in-with-X against it. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "oauth",
+    "oauth2",
+    "pkce",
+    "x",
+    "twitter",
+    "identity",
+    "sign-in-with-x"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/xidentity"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/xidentity#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-xidentity": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@xdevplatform/xdk": "^0.6.6",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-xidentity CLI: serve the X identity twin, or run conformance.
+//
+// `serve` and `mirror` start the SAME server, because the authorize screen is served by the twin
+// at the vendor's own path — there is no second renderer to start. `mirror` additionally prints a
+// ready-to-open authorization URL, which is the thing an operator actually wants when they ask to
+// "see the UI".
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createXIdentityTwinServer } from './xidentity-server.ts';
+import { pkceS256 } from './xidentity-pkce.ts';
+import { DEFAULT_CLIENT_ID, defaultRedirectUris } from './xidentity-store.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === 'mirror') {
+  const s = await createXIdentityTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  const origin = `http://127.0.0.1:${s.port}`;
+  process.stdout.write(`xidentity twin (X OAuth 2.0 + /2/users/me)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
+  if (cmd === 'mirror') {
+    const url = new URL(`${origin}/i/oauth2/authorize`);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', DEFAULT_CLIENT_ID);
+    url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]!);
+    url.searchParams.set('scope', 'tweet.read users.read offline.access');
+    url.searchParams.set('state', 'twin-demo-state');
+    url.searchParams.set('code_challenge', pkceS256('twin-demo-verifier'));
+    url.searchParams.set('code_challenge_method', 'S256');
+    process.stdout.write(`authorize screen: ${url.toString()}\n`);
+  }
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkXIdentityConformance } = await import('./xidentity-conformance.ts');
+  const report = await checkXIdentityConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-xidentity serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+// @volter/twin-xidentity — the X (Twitter) identity twin (one vendor, one package), built on the
+// shared @volter/world-core kernel.
+//
+// A BROWSER-FACING protocol pack (the googleoauth class): it serves X's own authorize screen as
+// HTML at x.com's real path, completes the full OAuth 2.0 authorization-code + PKCE round trip
+// (consent → 302 with code+state → redemption at the token endpoint → refresh → revoke), and
+// answers GET /2/users/me with X's real field/expansion/problem envelopes. Deliberately NON-OIDC,
+// exactly as the vendor is: opaque tokens, no id_token, no JWKS — identity comes from the API.
+// Conformance tooling lives in @volter/world-tooling (a dev dependency) — not shipped here.
+export {
+  ACCESS_TOKEN_TTL_SECONDS,
+  API_ORIGIN,
+  AUTH_CODE_TTL_SECONDS,
+  AUTHORIZE_ORIGIN,
+  handleXIdentityTwinRequest,
+  LEGACY_API_ORIGIN,
+  LEGACY_AUTHORIZE_ORIGIN,
+  RATE_WINDOW_SECONDS,
+  RESOURCE_TYPES,
+  USER_EXPANSIONS,
+  USER_FIELDS,
+  USERS_ME_RATE_LIMIT,
+  USERS_ME_REQUIRED_SCOPES,
+  xIdentityTwinSnapshot,
+} from './xidentity-twin.ts';
+export type { XIdentityRequest, XIdentityResponse, XResponse } from './xidentity-twin.ts';
+export { createXIdentityConsentServer, createXIdentityTwinFetch, createXIdentityTwinServer, type XIdentityTwinFetchOptions } from './xidentity-server.ts';
+export {
+  DEFAULT_ACCOUNTS,
+  DEFAULT_CLIENT_ID,
+  DEFAULT_CLIENT_SECRET,
+  DEFAULT_PUBLIC_CLIENT_ID,
+  defaultRedirectUris,
+  redirectUriAllowed,
+  sessionAccount,
+} from './xidentity-store.ts';
+export { normalizeChallengeMethod, pkceS256, pkceVerifies } from './xidentity-pkce.ts';
+export {
+  describeScope,
+  describeScopes,
+  formatScopeParam,
+  KNOWN_SCOPES,
+  parseScopeParam,
+  SCOPE_CATALOG,
+  sortScopesForConsent,
+} from './xidentity-scopes.ts';
+export type { ScopeInfo } from './xidentity-scopes.ts';
+export {
+  liveXIdentityExecute,
+  mapUsersMeAccount,
+  PULL_USER_FIELDS,
+  pullXIdentity,
+  pushPendingXIdentityActions,
+  syncXIdentityFromReal,
+} from './xidentity-connector.ts';
+export type { LiveXIdentityOptions, XIdentityExecute } from './xidentity-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveXIdentityExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is this vendor's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `XIdentityBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  XIDENTITY_BUDGET_CEILING,
+  XIDENTITY_BUDGET_MAX_RETRY_AFTER_S,
+  XIDENTITY_BUDGET_WINDOW_MS,
+  XIDENTITY_CALL_WEIGHTS,
+  XIDENTITY_RATE_BUDGET,
+  XIdentityBudget,
+  XIdentityBudgetError,
+  xIdentityBudgetPath,
+  xIdentityCallWeight,
+} from './xidentity-budget.ts';
+export type {
+  XIdentityBudgetErrorKind,
+  XIdentityBudgetOptions,
+  XIdentityBudgetReservation,
+  XIdentityBudgetSnapshot,
+} from './xidentity-budget.ts';
+export {
+  consentPageHtml,
+  CONSENT_SCRIPT_PATH,
+  CONSENT_STYLE_PATH,
+  errorPageHtml,
+  xIdentityConsentState,
+} from './xidentity-consent-ui.ts';
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from './xidentity-consent-ui.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/world-core';
+import { XIDENTITY_RATE_BUDGET as RATE_BUDGET } from './xidentity-budget.ts';
+/**
+ * The x.com / twitter.com paths THIS pack serves — the consent leg — as a RegExp SOURCE for the
+ * descriptor's `hosts` path rule. x.com is NOT an API host: it is the whole X web property (the
+ * timeline, settings, everything). Claiming the host outright would be the Cal.com mis-route
+ * incident with the largest possible blast radius, so this claims EXACTLY the authorize path plus
+ * the twin-only prefix. ANCHORED, the googleoauth lesson: an unanchored claim swallows
+ * `/i/oauth2/authorize2` and friends. Transcribed unchanged from inject.cjs's former
+ * `isXIdentityConsentPath` predicate.
+ */
+const XIDENTITY_CONSENT_PATHS = '^/i/oauth2/authorize/?$|^/_twin/';
+
+/**
+ * The api.x.com / api.twitter.com paths THIS pack serves: the OAuth 2.0 token + revoke endpoints
+ * and the authenticated-user read. api.x.com is the ENTIRE X API v2 host — posts, DMs, spaces — and
+ * this pack models the identity slice only, so nothing else is claimed: an unmodelled X call must
+ * refuse loudly rather than land in a twin that cannot serve it. Transcribed unchanged from
+ * inject.cjs's former `isXIdentityApiPath` predicate.
+ */
+const XIDENTITY_API_PATHS = '^/2/(?:oauth2/(?:token|revoke)|users/me)/?$';
+
+export const pack: TwinPack = {
+  // STILL PROTOCOL 1, and the reason is the gate rather than the pack (ROADMAP.md,
+  // shape-parity-refusals: a refusal the harness cannot express). Everything else is ready: the connector
+  // is on the v2 kernel and `performXIdentityAction` / `syncXIdentityFromRemote` are written and
+  // exported below. What blocks the declaration is that `GET /2/users/me` needs an access token
+  // that only a completed OAuth flow mints, so the refresh REFUSES at the twin's own wire — which
+  // is correct (never fold an empty account over observed state) and which the parity harness
+  // turns into a crash rather than a reported diff.
+
+  vendor: 'xidentity',
+  // The SAME object xidentity-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-xidentity',
+  resources: ['oauth_client', 'account', 'session', 'auth_request', 'authorization_code', 'access_token', 'refresh_token', 'grant', 'rate_window'],
+  specSource:
+    'api.x.com/2/openapi.json (X API v2 OpenAPI 2.167: /2/users/me, the Problem family, the '
+    + '24-scope OAuth2UserToken catalog) + docs.x.com OAuth 2.0 authorization-code/user-access-token '
+    + 'guides + the official SDK sources (@xdevplatform/xdk, twitter-api-typescript-sdk), all '
+    + 'fetched 2026-08-21',
+  description:
+    'X (Twitter) identity twin — the real 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. Non-OIDC, exactly as the vendor is.",
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  //
+  // BOTH official clients — the current XDK and the legacy (archived but still installed) SDK —
+  // plus X's own npm scope, where the current official XDK lives and any future first-party
+  // sibling will. `twitter-api-v2` is deliberately NOT claimed here: it is a third-party library
+  // spanning the whole X API and belongs to the POSTING pack (`x`), which models the surface it is
+  // installed for.
+  //
+  // The X_* / TWITTER_* stems stay on THIS pack now that a second X pack exists, deliberately:
+  // X_CLIENT_ID / X_CLIENT_SECRET and TWITTER_CLIENT_ID / TWITTER_BEARER_TOKEN name the OAuth APP
+  // credentials, which is this pack's surface. NB the single-letter `X` stem fires on ANY
+  // X_<credential-suffix> shape the BROAD suffix list admits (X_KEY, X_TOKEN, X_API_URL, …), not
+  // only the strict _CLIENT_ID/_CLIENT_SECRET pair — accepted deliberately: a var actually named
+  // bare `X_*` with a credential suffix is overwhelmingly the vendor, and a false hit surfaces as
+  // a visible coverage row rather than a silent drop.
+  adoption: {
+    // No Python distribution of its own: X's official SDKs are TypeScript, and the one community
+    // Python client of this API - `tweepy` - is claimed by the `x` pack (one name, one pack), whose
+    // posting surface is what tweepy is overwhelmingly used for.
+    pypi: [],
+    sdks: ['@xdevplatform/xdk', 'twitter-api-sdk'],
+    scopes: ['@xdevplatform/'],
+    envStems: ['X', 'TWITTER'],
+  },
+  // TWO host families — x.com/api.x.com plus the twitter.com pair X's LEGACY official SDK still
+  // targets — every one path-scoped, because x.com is the entire X web property and api.x.com the
+  // entire X API v2 host, of which this pack models the identity slice only. With no pathname each
+  // host is still claimed so the ambient proxy MITMs it; the post-decrypt resolve then routes the
+  // identity paths here and refuses the rest loudly (unclaimedTwinnedHostPathMessage) — the
+  // Cal.com mis-route lesson.
+  hosts: [
+    { host: 'x.com', pathPattern: XIDENTITY_CONSENT_PATHS },
+    { host: 'twitter.com', pathPattern: XIDENTITY_CONSENT_PATHS },
+    { host: 'api.x.com', pathPattern: XIDENTITY_API_PATHS },
+    { host: 'api.twitter.com', pathPattern: XIDENTITY_API_PATHS },
+  ],
+  // A browser is REDIRECTED to x.com/i/oauth2/authorize — the loader host is the consent host and
+  // the prefix is the OAuth path root.
+  browserRouting: { apiPathPrefix: '/i/oauth2/', loaderHost: 'https://x.com' },
+};

package/src/xidentity-budget.ts

@@ -0,0 +1,135 @@
+// X identity's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveXIdentityExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`).
+//
+// ── HOW THE CEILING WAS CHOSEN (live-fetched first-party figures) ───────────────────────────────
+// X PUBLISHES per-endpoint rate limits. From https://docs.x.com/x-api/fundamentals/rate-limits
+// (fetched 2026-08-21): `GET /2/users/me` is **75 requests / 15 minutes per user** (no per-app
+// row), other user lookups are 300/15min (app) and 900/15min (user), windows are 15 minutes, and
+// exceeding one answers HTTP 429 with legacy code 88. The OAuth token/revoke endpoints publish NO
+// scalar limit on that page — that absence is stated here rather than dressed up, and those calls
+// are priced ABOVE the documented read so the undocumented surface is the conservative one.
+//
+// The window is therefore the vendor's own 15 minutes and the ceiling is the vendor's own 75,
+// with `GET /2/users/me` at weight 1 — the declaration REPRODUCES the published per-user budget
+// for the one endpoint the connector reads (the github-budget precedent: when the vendor's scheme
+// is already a windowed budget, transcribe it). The kernel demands a `burstCeiling` for any
+// window longer than its 60s burst sub-window; 15 units/60s (15 users/me reads a minute, 3× the
+// window's average pace) bounds the instant WITHOUT out-bursting the kernel fallback's 30, so no
+// VENDOR_BURST_ANCHOR entry is required in `scripts/rate-budget-isolation.test.ts`.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'xidentity';
+
+/** Rolling window, in ms — X's own 15-minute rate-limit window. */
+export const XIDENTITY_BUDGET_WINDOW_MS = 15 * 60_000;
+
+/** Weighted units allowed inside one window — X's own per-user allowance for GET /2/users/me. */
+export const XIDENTITY_BUDGET_CEILING = 75;
+
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 3× the window's average
+ *  pace, and UNDER the kernel fallback's burst of 30. */
+export const XIDENTITY_BUDGET_BURST_CEILING = 15;
+
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const XIDENTITY_BUDGET_MAX_RETRY_AFTER_S = 900;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const XIDENTITY_CALL_WEIGHTS = {
+  /** `GET /2/users/me` — 75/15min per user is the PUBLISHED limit; weight 1 transcribes it. */
+  usersMe: 1,
+  /** `POST /2/oauth2/revoke` — logs a human out of an app on a REAL account. Priced as a human
+   *  blast radius, not a throttle (a judgement call, stated as one). */
+  revoke: 15,
+  /** Everything else (the token endpoint): no published scalar limit → priced conservatively. */
+  other: 3,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export const XIDENTITY_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: XIDENTITY_BUDGET_WINDOW_MS,
+  ceiling: XIDENTITY_BUDGET_CEILING,
+  burstCeiling: XIDENTITY_BUDGET_BURST_CEILING,
+  defaultWeight: XIDENTITY_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: XIDENTITY_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^GET /2/users/me$', weight: XIDENTITY_CALL_WEIGHTS.usersMe },
+    { match: '^POST /2/oauth2/revoke$', weight: XIDENTITY_CALL_WEIGHTS.revoke },
+  ],
+  reason:
+    'X publishes per-endpoint rate limits (https://docs.x.com/x-api/fundamentals/rate-limits, '
+    + 'fetched 2026-08-21): GET /2/users/me is 75 requests / 15 minutes PER USER, windows are 15 '
+    + 'minutes, and exceeding one answers HTTP 429 with legacy code 88 "Rate limit exceeded". This '
+    + "declaration transcribes that scheme: the window is the vendor's own 15 minutes, the ceiling "
+    + "is the vendor's own 75, and GET /2/users/me costs 1 — the one documented figure for the one "
+    + 'endpoint the connector reads. The OAuth token and revoke endpoints publish NO scalar limit '
+    + 'on that page; they are priced ABOVE the documented read (defaultWeight 3, revoke 15) so the '
+    + 'undocumented surface is the conservative one. POST /2/oauth2/revoke costs 15 because it is '
+    + 'the one destructive call here — it logs a human out of an app on a REAL account — which is a '
+    + 'human blast radius, not a throttle; that price is a judgement call, stated as one. The '
+    + "burstCeiling of 15 units/60s (3x the window's average pace, under the kernel fallback's "
+    + 'burst of 30) bounds the instant, and the 429 / Retry-After cooldown is the backstop.',
+};
+
+// Declared at module load, so merely importing this module (which `xidentity-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, XIDENTITY_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/2/oauth2/revoke')` really does issue the destructive call and must be priced
+ * as one.
+ */
+export function xIdentityCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export function xIdentityBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through must not
+  // redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type XIdentityBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof XIdentityBudget` means "a budget that accounts against
+ * XIDENTITY's ledger under XIDENTITY's ceiling".
+ */
+export class XIdentityBudget extends RateBudget {
+  constructor(opts: XIdentityBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as XIdentityBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XIdentityBudgetErrorKind } from '@volter/world-core';
+export type XIdentityBudgetReservation = RateBudgetReservation;
+export type XIdentityBudgetSnapshot = RateBudgetSnapshot;