@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-consent-ui.d.ts

@@ -0,0 +1,21 @@
+import { type ConsentView, type ErrorPageProps } from '../client/xidentity-consent.js';
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from '../client/xidentity-consent.js';
+export { XIDENTITY_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, XIDENTITY_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from './xidentity-consent-client.gen.js';
+/** Twin-only asset paths, clearly namespaced so they can never be mistaken for vendor surface. */
+export declare const CONSENT_SCRIPT_PATH = "/_twin/assets/consent.js";
+export declare const CONSENT_STYLE_PATH = "/_twin/assets/consent.css";
+/**
+ * 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 declare function xIdentityConsentState(opts: {
+    root?: string;
+    requestId: string;
+    origin: string;
+}): ConsentView | null;
+/** Render the authorize page from a view model. The tab title mirrors X's "Authorize <app>". */
+export declare function consentPageHtml(view: ConsentView, base?: string): string;
+/** Render the authorize-endpoint error page (an un-redirectable failure). */
+export declare function errorPageHtml(props: ErrorPageProps, base?: string): string;

package/dist/src/xidentity-consent-ui.js

@@ -0,0 +1,94 @@
+// 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, } from "../client/xidentity-consent.js";
+import { describeScopes, parseScopeParam, sortScopesForConsent } from "./xidentity-scopes.js";
+import { readOne } from "./xidentity-store.js";
+export { XIDENTITY_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, XIDENTITY_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from "./xidentity-consent-client.gen.js";
+/** 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) {
+    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) {
+    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 = 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, bodyMarkup, base) {
+    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) {
+    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, base = '') {
+    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, base = '') {
+    return page(`Error ${props.status}: ${props.code} / X`, renderToStaticMarkup(createElement(ErrorPage, props)), base);
+}

package/dist/src/xidentity-pkce.d.ts

@@ -0,0 +1,7 @@
+/** base64url(SHA-256(verifier)) — the S256 code_challenge for a code_verifier. */
+export declare function pkceS256(verifier: string): string;
+export type ChallengeMethod = 'S256' | 'plain';
+/** Normalise a caller-supplied code_challenge_method, or null when it isn't a documented value. */
+export declare function normalizeChallengeMethod(raw: string | null): ChallengeMethod | null;
+/** Does `verifier` satisfy the challenge the code was minted against? */
+export declare function pkceVerifies(method: ChallengeMethod, challenge: string, verifier: string): boolean;

package/dist/src/xidentity-pkce.js

@@ -0,0 +1,27 @@
+// 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) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+/** Normalise a caller-supplied code_challenge_method, or null when it isn't a documented value. */
+export function normalizeChallengeMethod(raw) {
+    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, challenge, verifier) {
+    return method === 'S256' ? pkceS256(verifier) === challenge : verifier === challenge;
+}

package/dist/src/xidentity-problems.d.ts

@@ -0,0 +1,38 @@
+export type XResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare function oauthError(error: string, description: string, status: number): XResponse;
+/**
+ * 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 declare function badAuthorizationCode(): XResponse;
+/** The refresh-token twin of the above — same reported-wire caveat. */
+export declare function badRefreshToken(): XResponse;
+/** Client authentication failed at the token/revoke endpoint (RFC 6749 §5.2: 401 invalid_client). */
+export declare function invalidClient(): XResponse;
+/** The generic auth problem X answers a bad/absent/expired bearer with on /2 resources. */
+export declare function unauthorizedProblem(): XResponse;
+/**
+ * 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 declare function forbiddenProblem(detail: string): XResponse;
+/** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
+export declare function notFoundProblem(): XResponse;
+/** A contained unexpected failure on the v2 resource surface. Never exposes local exception text. */
+export declare function internalServerProblem(): XResponse;
+/**
+ * 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 declare function invalidRequestProblem(parameters: Record<string, string[]>, message: string): XResponse;
+/** HTTP 429, legacy code 88 — the documented pair (docs.x.com fundamentals/rate-limits). */
+export declare function rateLimitExceeded(headers: Record<string, string>): XResponse;

package/dist/src/xidentity-problems.js

@@ -0,0 +1,108 @@
+// 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.
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+// ── family 1: OAuth token endpoint (RFC 6749 flat body) ─────────────────────────────────────────
+export function oauthError(error, description, status) {
+    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() {
+    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() {
+    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() {
+    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() {
+    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) {
+    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() {
+    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() {
+    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, message) {
+    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) {
+    return {
+        status: 429,
+        body: { errors: [{ code: 88, message: 'Rate limit exceeded' }] },
+        headers: { ...NOSTORE, ...headers, 'content-type': 'application/json' },
+    };
+}

package/dist/src/xidentity-scopes.d.ts

@@ -0,0 +1,23 @@
+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 declare const SCOPE_CATALOG: Record<string, {
+    label: string;
+    group: 'view' | 'do' | 'session';
+}>;
+export declare const KNOWN_SCOPES: readonly string[];
+/** Space-separated scope param → ordered unique scope list (X formats scope space-separated). */
+export declare function parseScopeParam(raw: string | null): string[];
+export declare function formatScopeParam(scopes: readonly string[]): string;
+export declare function describeScope(scope: string): ScopeInfo;
+export declare function describeScopes(scopes: readonly string[]): ScopeInfo[];
+/** Screen order: what the app can view, then what it can do, then the offline promise. */
+export declare function sortScopesForConsent(scopes: readonly string[]): string[];

package/dist/src/xidentity-scopes.js

@@ -0,0 +1,81 @@
+// 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.
+/** 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 = {
+    '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 = Object.keys(SCOPE_CATALOG);
+/** Space-separated scope param → ordered unique scope list (X formats scope space-separated). */
+export function parseScopeParam(raw) {
+    if (!raw)
+        return [];
+    const seen = new Set();
+    const out = [];
+    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) {
+    return scopes.join(' ');
+}
+export function describeScope(scope) {
+    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) {
+    return scopes.map(describeScope);
+}
+/** Screen order: what the app can view, then what it can do, then the offline promise. */
+export function sortScopesForConsent(scopes) {
+    const order = { view: 0, do: 1, session: 2 };
+    return [...scopes].sort((a, b) => order[describeScope(a).group] - order[describeScope(b).group]);
+}

package/dist/src/xidentity-server.d.ts

@@ -0,0 +1,33 @@
+/** Options every X-identity-twin HTTP surface needs, independent of who owns the socket. */
+export interface XIdentityTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createXIdentityTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only clock on
+ * the path is `worldNow()`, the world's frozen instant. The authorize screen's own script and
+ * stylesheet routes serve COMMITTED text (`xidentity-consent-client.gen.ts`, built on the dev
+ * plane by `scripts/consent-clients.ts`) — no build and no disk read on the fetch path.
+ */
+export declare function createXIdentityTwinFetch(options?: XIdentityTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createXIdentityTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/**
+ * The authorize screen is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-xidentity mirror` command and the
+ * journey harness have the conventional entry point, and it returns the very same server.
+ */
+export declare const createXIdentityConsentServer: typeof createXIdentityTwinServer;

package/dist/src/xidentity-server.js

@@ -0,0 +1,85 @@
+// X identity twin HTTP server — one server for the WHOLE vendor surface, because sign-in-with-X is
+// one product spread over two host families. Point `x.com`, `twitter.com`, `api.x.com` and
+// `api.twitter.com` here (the injector's `xidentity` VENDOR_HOSTS entry does exactly that) and an
+// unmodified X client completes a full authorization-code round trip against it.
+//
+// Two things this server does that a JSON-only twin server does not:
+//   • it can answer with HTML and with 302 redirects — the authorize screen and the callback
+//     bounce are the protocol, not decoration, so the handler's `headers` (content-type, location)
+//     pass straight through rather than being flattened into a JSON envelope;
+//   • it serves the authorize page's own assets under the twin-namespaced `/_twin/assets/*`.
+//
+// It also tells the handler its OWN origin, so the consent form's action points BACK AT THE TWIN.
+import { serveHttp } from '@volter/world-core';
+import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from "./xidentity-consent-ui.js";
+import { worldNow, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
+import { handleXIdentityTwinRequest } from "./xidentity-twin.js";
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createXIdentityTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only clock on
+ * the path is `worldNow()`, the world's frozen instant. The authorize screen's own script and
+ * stylesheet routes serve COMMITTED text (`xidentity-consent-client.gen.ts`, built on the dev
+ * plane by `scripts/consent-clients.ts`) — no build and no disk read on the fetch path.
+ */
+export function createXIdentityTwinFetch(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    return async function xIdentityTwinFetch(request) {
+        const url = new URL(request.url);
+        // GET /twin — the discovery manifest (education inside the twin).
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(statefulTwinManifest({ vendor: 'xidentity', twinOf: 'X (Twitter) identity / OAuth 2.0 + PKCE', stores: 'authorization codes, access/refresh tokens and the authorize-screen round trip' }));
+        }
+        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 = {};
+        request.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        const res = await handleXIdentityTwinRequest({
+            method: request.method,
+            path: url.pathname + (url.search || ''),
+            body,
+            headers,
+            readOnly,
+            occurredAt: worldNow(),
+            origin: twinPublicBase(request),
+            callbackOrigin: url.origin,
+            ...(options.root !== undefined ? { root: options.root } : {}),
+        });
+        const out = { ...(res.headers ?? {}) };
+        // A string body is already rendered (HTML, or the empty body of a 302); anything else is the
+        // vendor's JSON.
+        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 });
+    };
+}
+export async function createXIdentityTwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createXIdentityTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+/**
+ * The authorize screen is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-xidentity mirror` command and the
+ * journey harness have the conventional entry point, and it returns the very same server.
+ */
+export const createXIdentityConsentServer = createXIdentityTwinServer;

package/dist/src/xidentity-store.d.ts

@@ -0,0 +1,97 @@
+import { type TwinResource } from '@volter/world-core';
+export declare const SERVICE = "xidentity";
+export declare const RESOURCE_TYPES: readonly ["oauth_client", "account", "session", "auth_request", "authorization_code", "access_token", "refresh_token", "grant", "rate_window"];
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+export type Row = TwinResource & Record<string, any>;
+export declare function readAll(root: string | undefined): Row[];
+export declare function readType(root: string | undefined, type: ResourceType): Row[];
+export declare function readOne(root: string | undefined, type: ResourceType, id: string): Row | undefined;
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export declare function nextRev(root: string | undefined, type: ResourceType, id: string): number;
+/** The next revision from a snapshot already held under the kernel projection lock. */
+export declare function nextRevIn(resources: readonly TwinResource[], type: ResourceType, id: string): number;
+/** A state-dependent one-row update whose read/revision/write decision is one kernel transaction. */
+export declare function writeAtomic(type: ResourceType, id: string, operation: string, fields: (resources: readonly TwinResource[]) => Record<string, unknown>, opts: WriteOpts): Promise<Row>;
+export type WriteOpts = {
+    root?: string;
+    occurredAt?: string;
+};
+/** Seeding also needs the origin the twin was reached on, so the demo clients' registered
+ *  callbacks point back at THIS twin rather than at a baked-in port (runtime contract R7). */
+export type SeedOpts = WriteOpts & {
+    origin?: string;
+};
+export declare function write(type: ResourceType, id: string, operation: string, fields: Record<string, unknown>, opts: WriteOpts): Promise<Row>;
+/** An X OAuth 2.0 client id: base64url of `<opaque>:1:ci`. */
+export declare const mintClientId: (root: string | undefined, instant: string) => string;
+/** An X OAuth 2.0 authorization code (`…:ac:1`). `subject` is the authorize screen it settles. */
+export declare const mintAuthorizationCode: (root: string | undefined, at: number, subject: string) => string;
+/** An X OAuth 2.0 user access token (`…:at:1`). `subject` is the credential exchanged for it. */
+export declare const mintAccessToken: (root: string | undefined, at: number, subject: string) => string;
+/** An X OAuth 2.0 refresh token (`…:rt:1`). `subject` is the credential exchanged for it. */
+export declare const mintRefreshToken: (root: string | undefined, at: number, subject: string) => string;
+/**
+ * Twin-internal handle for an authorize screen in flight (never leaves the twin's own pages) —
+ * `ar_` + 32 hex, the shape `randomUUID()` gave it, now a pure function of (request, stored state).
+ *
+ * An authorize request whose parameters ALREADY name an unsettled pending row reuses that row's
+ * id: pressing reload on the authorize screen is the same screen, not a new one. Otherwise the id
+ * is `stableHex(auth_request:<world instant>:<rows already held>)` — two authorize requests at one
+ * instant differ by the count, and two identical worlds mint identical ids.
+ */
+export declare function authRequestIdFor(root: string | undefined, occurredAt: string, fields: Record<string, unknown>): string;
+export declare const DEFAULT_CLIENT_ID = "VHdpbkRlbW9BcHAwMDAwMDAwMDA6MTpjaQ";
+export declare const DEFAULT_CLIENT_SECRET = "twin-confidential-secret-0000000000000000000000000";
+export declare const DEFAULT_PUBLIC_CLIENT_ID = "VHdpblB1YmxpY0FwcDAwMDAwMDA6MTpjaQ";
+export type SeedAccount = {
+    id: string;
+    username: string;
+    name: string;
+    createdAt: string;
+    description: string;
+    location?: string;
+    profileImageUrl?: string;
+    protectedAccount: boolean;
+    verified: boolean;
+    verifiedType: 'none' | 'blue' | 'business' | 'government';
+    publicMetrics: {
+        followers_count: number;
+        following_count: number;
+        tweet_count: number;
+        listed_count: number;
+        like_count: number;
+        media_count: number;
+    };
+    url?: string;
+    confirmedEmail?: string;
+};
+/** X user ids are stable numeric strings (the docs' own example user is "2244994945"). The seeded
+ *  ids start at 9e18 — vendor-SHAPED (int64-range numeric) but far ABOVE the live snowflake id
+ *  space (~1.9e18 in 2026), so a locally seeded persona can never collide with a pulled real id
+ *  (the datadog EVENT_ID_BASE precedent; §9 round one). */
+export declare const DEFAULT_ACCOUNTS: SeedAccount[];
+/**
+ * The redirect URIs the seeded demo clients register.
+ *
+ * Runtime contract R7: a twin NEVER bakes a port into served content or config. The callbacks are
+ * DERIVED from the origin the twin was actually reached on (`XIdentityRequest.origin`, which
+ * xidentity-server fills from the URL the request arrived at). A caller that declares no origin —
+ * an in-process call — seeds no callbacks at all and registers its own through the twin door.
+ */
+export declare function defaultRedirectUris(origin?: string): string[];
+/**
+ * Materialise the default clients + accounts + session once per root. Idempotent by subject id:
+ * re-running it over a seeded root writes nothing new, and it NEVER overwrites an
+ * operator-registered client, account or session choice.
+ */
+export declare function ensureSeed(opts: SeedOpts): Promise<void>;
+/** The account the x.com browser session is signed in as (the one the authorize screen consents). */
+export declare function sessionAccount(root: string | undefined): Row | undefined;
+/**
+ * Is `candidate` an EXACT registered callback URI for this client? X documents exact-match
+ * validation for OAuth 2.0 callback URLs ("This value must correspond to one of the Callback URLs
+ * defined in your App's settings" — and the legacy official SDK's own docblock spells out "exact
+ * match validation"). No loopback-port exception is documented for X, so none is modelled — a
+ * loosely-matching twin would hide the single most common integration bug.
+ */
+export declare function redirectUriAllowed(client: Row, candidate: string): boolean;