@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-store.js

@@ -0,0 +1,358 @@
+// X identity twin — STATE. Everything the twin knows lives in the shared kernel action log (D1):
+// OAuth clients, X accounts, the browser session (which account is "logged in" at x.com), pending
+// authorization requests, authorization codes, access/refresh tokens, the per-(client, user) grant
+// record and the per-user rate window. There is no parallel store.
+//
+// ID MINTING (ADDING_A_TWIN.md §5): every id is either the vendor's own natural key (an account
+// id) or MINTED HERE. The minted ones used to be ENTROPIC (`randomUUID`) — never a module counter
+// and never a row count. Every one of them is also SERVED: the `ar_` authorize handle is rendered
+// into the screen, the `…:ac:1` code rides the callback redirect, the `…:at:1`/`…:rt:1` tokens
+// ride the /2/oauth2/token reply, a minted client id rides the twin door's reply. Runtime contract
+// R9 (a served response is a pure function of (request, stored state) — no clock and no randomness
+// in served content) therefore governs all of them, and entropy is exactly the defect it names, so
+// they are ALL minted the resend way now: a stable hash of the world instant + the number of rows
+// of that type the store already holds (soft-deleted rows counted, so a value can never recur) +
+// the subject it is issued for.
+//
+// §5's count-mint hazard — a pulled vendor id sitting in a GAP above the row count, which local
+// creates then walk into and clobber — cannot arise here: these types are twin-internal or
+// twin-issued, no connector pulls one, and the count is a hash SEED rather than the id itself.
+// What §5's entropy bought (two writes at one instant never colliding) the count buys instead: it
+// advances on every mint.
+//
+// The `ar_` handle carries one extra rule the credentials do not: an authorize request whose
+// parameters already name an UNSETTLED pending row reuses that row's id, so re-serving the same
+// authorize screen is byte-identical (and a reload does not pile up a second pending request).
+//
+// The mutable-in-place rows (a code being consumed, a token being revoked, a grant re-granted, a
+// rate window advancing) carry a per-subject `rev` ordinal (the upstash precedent) so a
+// genuine write can never be mistaken for a replay.
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources } from '@volter/world-core';
+export const SERVICE = 'xidentity';
+export const RESOURCE_TYPES = [
+    'oauth_client',
+    'account',
+    'session',
+    'auth_request',
+    'authorization_code',
+    'access_token',
+    'refresh_token',
+    'grant',
+    'rate_window',
+];
+export function readAll(root) {
+    return projectResources(SERVICE, root);
+}
+export function readType(root, type) {
+    return readAll(root).filter((r) => r.type === type);
+}
+export function readOne(root, type, id) {
+    return readAll(root).find((r) => r.type === type && r.id === id);
+}
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export function nextRev(root, type, id) {
+    const existing = readOne(root, type, id);
+    return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+/** The next revision from a snapshot already held under the kernel projection lock. */
+export function nextRevIn(resources, type, id) {
+    const existing = resources.find((r) => r.type === type && r.id === id);
+    return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+/** A state-dependent one-row update whose read/revision/write decision is one kernel transaction. */
+export async function writeAtomic(type, id, operation, fields, opts) {
+    await applyTwinWriteAtomic(SERVICE, (resources) => ({
+        kind: 'write',
+        value: undefined,
+        write: {
+            operation,
+            subjectType: type,
+            subjectId: id,
+            fields: { ...fields(resources), rev: nextRevIn(resources, type, id) },
+            ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+            actor: { kind: 'agent' },
+        },
+    }), opts.root);
+    return readOne(opts.root, type, id);
+}
+export async function write(type, id, operation, fields, opts) {
+    const { resource } = await applyTwinWrite(SERVICE, {
+        operation,
+        subjectType: type,
+        subjectId: id,
+        fields,
+        ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, opts.root);
+    return resource;
+}
+// ── vendor-shaped id minting ────────────────────────────────────────────────────────────────────
+// X's OAuth 2.0 artefacts are base64url blobs with an internal structure the vendor's own docs
+// examples expose when decoded (docs.x.com user-access-token guide, fetched 2026-08-21):
+//
+//   client_id     M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ                → "<21 alnum>:1:ci"
+//   auth code     VGNibzFWSWRE…RchOXlMd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE
+//                                                                   → "<opaque>:<unix ms>:1:1:ac:1"
+//   access token  Q0Mzb0VhZ0V5…U3NZQnZQYjoxNjIyMTQ3NzQzOTE0OjE6MTphdDox
+//                                                                   → "<opaque>:<unix ms>:1:1:at:1"
+//   refresh token bWRWa3gzdnk3…QVdxbm06MTYyMjE0Nzc0MzkxNDoxOjE6cnQ6MQ
+//                                                                   → "<opaque>:<unix ms>:1:1:rt:1"
+//
+// The twin reproduces the SHAPE (an integrator's code may key on it); the bytes are not the
+// vendor's.
+//
+// Those bytes used to be `randomUUID()` entropy, and every one of them is SERVED (the code rides
+// the callback redirect, the tokens ride the /2/oauth2/token reply), so R9 governs them exactly as
+// it governs the `ar_` handle below. They are the resend pattern now: `stableHex` over (type, the
+// world instant, the rows of that type held BEFORE the insert, the subject being issued for),
+// occupying the same 21/45 characters of the same hex alphabet the entropic version did — the
+// shape is byte-for-byte what it was.
+//
+// A twin's credentials are stand-ins, not secrets: determinism is the contract, and predictability
+// from public state is not a threat model a twin has. UNIQUENESS is, and the seed carries it: the
+// row COUNT advances on every mint, so two credentials of one type at one instant differ even when
+// the subject is identical, and the SUBJECT is the credential being exchanged — the consent screen
+// for a code, the code or spent refresh token for a token — so concurrent exchanges never meet.
+// `xidentity.refresh.rotation` (a rotation must hand back a refresh token the caller did not send)
+// holds by construction: the spent row is already in the store when the replacement is seeded.
+const b64url = (s) => Buffer.from(s, 'utf8').toString('base64url');
+/** The seed every credential is minted from. `readType` is unfiltered (soft-deletes counted), so a
+ *  count — and therefore a credential — can never recur for one (type, instant, subject). */
+function credentialSeed(root, type, instant, subject) {
+    return `${type}:${instant}:${readType(root, type).length}:${subject}`;
+}
+/** An X OAuth 2.0 client id: base64url of `<opaque>:1:ci`. */
+export const mintClientId = (root, instant) => b64url(`${stableHex(credentialSeed(root, 'oauth_client', instant, 'client'), 21)}:1:ci`);
+/** An X OAuth 2.0 authorization code (`…:ac:1`). `subject` is the authorize screen it settles. */
+export const mintAuthorizationCode = (root, at, subject) => b64url(`${stableHex(credentialSeed(root, 'authorization_code', at, subject), 45)}:${at}:1:1:ac:1`);
+/** An X OAuth 2.0 user access token (`…:at:1`). `subject` is the credential exchanged for it. */
+export const mintAccessToken = (root, at, subject) => b64url(`${stableHex(credentialSeed(root, 'access_token', at, subject), 45)}:${at}:1:1:at:1`);
+/** An X OAuth 2.0 refresh token (`…:rt:1`). `subject` is the credential exchanged for it. */
+export const mintRefreshToken = (root, at, subject) => b64url(`${stableHex(credentialSeed(root, 'refresh_token', at, subject), 45)}:${at}:1:1:rt:1`);
+// ── the authorize screen's handle: DETERMINISTIC, because it is SERVED (R9) ─────────────────────
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+function stableHex(seed, n) {
+    let out = '';
+    for (let round = 0; out.length < n; round += 1) {
+        let h = 0x811c9dc5;
+        const s = `${round}:${seed}`;
+        for (let i = 0; i < s.length; i += 1) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        out += h.toString(16).padStart(8, '0');
+    }
+    return out.slice(0, n);
+}
+/** Every authorize parameter an `auth_request` row holds — its stable identity. Read off the
+ *  fields being written OR off a projected row (the key set is the same on both). */
+const AUTH_REQUEST_SIG_KEYS = [
+    'clientId', 'redirectUri', 'scope', 'state', 'codeChallenge', 'codeChallengeMethod', 'accountId',
+];
+function authRequestSignature(fields) {
+    return AUTH_REQUEST_SIG_KEYS.map((k) => `${k}=${String(fields[k] ?? '')}`).join('\u0001');
+}
+/**
+ * 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 function authRequestIdFor(root, occurredAt, fields) {
+    const prior = readType(root, 'auth_request');
+    const signature = authRequestSignature(fields);
+    const reusable = prior.find((r) => r.settled !== true && authRequestSignature(r) === signature);
+    if (reusable)
+        return String(reusable.id);
+    return `ar_${stableHex(`auth_request:${occurredAt}:${prior.length}`, 32)}`;
+}
+// ── seeded world ────────────────────────────────────────────────────────────────────────────────
+// The authorize page needs SOMEBODY to be signed in at x.com. X shows the consent screen for the
+// browser's current session; the twin's equivalent is deterministic personas seeded on first use
+// plus a `session` row naming the active one (`POST /_twin/session` switches it — X's real switcher
+// is the x.com account menu, which is not OAuth surface). The default clients mirror the two shapes
+// the X developer portal hands out: a CONFIDENTIAL client (Web App — has a secret, authenticates
+// with HTTP Basic) and a PUBLIC client (Native/SPA — no secret, client_id travels in the body).
+export const DEFAULT_CLIENT_ID = 'VHdpbkRlbW9BcHAwMDAwMDAwMDA6MTpjaQ';
+export const DEFAULT_CLIENT_SECRET = 'twin-confidential-secret-0000000000000000000000000';
+export const DEFAULT_PUBLIC_CLIENT_ID = 'VHdpblB1YmxpY0FwcDAwMDAwMDA6MTpjaQ';
+/** 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 const DEFAULT_ACCOUNTS = [
+    {
+        id: '9000000000000000001',
+        username: 'ada_twin',
+        name: 'Ada Lovelace',
+        createdAt: '2013-12-14T04:35:55.000Z',
+        description: 'Analyst. Engine programmer. First of her kind.',
+        location: 'London',
+        protectedAccount: false,
+        verified: true,
+        verifiedType: 'blue',
+        publicMetrics: { followers_count: 5834, following_count: 204, tweet_count: 1405, listed_count: 16, like_count: 320, media_count: 12 },
+        url: 'https://ada.example',
+        confirmedEmail: 'ada@twin.example',
+    },
+    {
+        id: '9000000000000000002',
+        username: 'grace_twin',
+        name: 'Grace Hopper',
+        createdAt: '2015-06-01T12:00:00.000Z',
+        description: 'It is easier to ask forgiveness than permission.',
+        protectedAccount: true,
+        verified: false,
+        verifiedType: 'none',
+        publicMetrics: { followers_count: 120, following_count: 88, tweet_count: 5210, listed_count: 3, like_count: 990, media_count: 41 },
+    },
+];
+/** NextAuth's callback path for the X provider — the one every X integration guide walks through. */
+const CALLBACK_PATH = '/api/auth/callback/x';
+/**
+ * Every spelling of the ORIGIN this twin was reached on that a browser could hand back.
+ *
+ * X matches redirect URIs EXACTLY and documents NO loopback-port exception (see
+ * `redirectUriAllowed` below), so `localhost` and the loopback IP are two different
+ * registrations — while a local app is reachable as both on the same port. A demo registration
+ * naming only one of them would fail half the time for a reason the developer cannot see.
+ */
+function originSpellings(origin) {
+    const base = (origin ?? '').trim().replace(/\/+$/, '');
+    if (!base)
+        return [];
+    let u;
+    try {
+        u = new URL(base);
+    }
+    catch {
+        return [base];
+    }
+    if (u.protocol !== 'http:')
+        return [base];
+    const port = u.port ? `:${u.port}` : '';
+    if (u.hostname === 'localhost')
+        return [base, `http://127.0.0.1${port}`];
+    if (u.hostname === '127.0.0.1')
+        return [base, `http://localhost${port}`];
+    return [base];
+}
+/**
+ * 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 function defaultRedirectUris(origin) {
+    return originSpellings(origin).map((base) => `${base}${CALLBACK_PATH}`);
+}
+/**
+ * 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 async function ensureSeed(opts) {
+    await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const has = (type, id) => resources.some((r) => r.type === type && r.id === id);
+        const missing = [];
+        if (!has('oauth_client', DEFAULT_CLIENT_ID))
+            missing.push({
+                type: 'oauth_client',
+                id: DEFAULT_CLIENT_ID,
+                fields: {
+                    name: 'Twin Demo App',
+                    secret: DEFAULT_CLIENT_SECRET,
+                    clientType: 'confidential',
+                    redirectUris: defaultRedirectUris(opts.origin),
+                    rev: 1,
+                },
+            });
+        if (!has('oauth_client', DEFAULT_PUBLIC_CLIENT_ID))
+            missing.push({
+                type: 'oauth_client',
+                id: DEFAULT_PUBLIC_CLIENT_ID,
+                fields: {
+                    name: 'Twin Public App',
+                    secret: null,
+                    clientType: 'public',
+                    redirectUris: defaultRedirectUris(opts.origin),
+                    rev: 1,
+                },
+            });
+        for (const account of DEFAULT_ACCOUNTS) {
+            if (has('account', account.id))
+                continue;
+            missing.push({
+                type: 'account',
+                id: account.id,
+                fields: {
+                    username: account.username,
+                    name: account.name,
+                    createdAt: account.createdAt,
+                    description: account.description,
+                    ...(account.location ? { location: account.location } : {}),
+                    ...(account.profileImageUrl ? { profileImageUrl: account.profileImageUrl } : {}),
+                    protectedAccount: account.protectedAccount,
+                    verified: account.verified,
+                    verifiedType: account.verifiedType,
+                    publicMetrics: account.publicMetrics,
+                    ...(account.url ? { url: account.url } : {}),
+                    ...(account.confirmedEmail ? { confirmedEmail: account.confirmedEmail } : {}),
+                    rev: 1,
+                },
+            });
+        }
+        if (!has('session', 'current'))
+            missing.push({
+                type: 'session',
+                id: 'current',
+                fields: { accountId: DEFAULT_ACCOUNTS[0].id, rev: 1 },
+            });
+        if (missing.length === 0)
+            return { kind: 'skip', value: undefined };
+        const [primary, ...rest] = missing;
+        return {
+            kind: 'write',
+            value: undefined,
+            write: {
+                operation: 'seed.ensure',
+                subjectType: primary.type,
+                subjectId: primary.id,
+                fields: primary.fields,
+                projection: {
+                    creates: rest.map((row) => ({ type: row.type, id: row.id, fields: row.fields })),
+                },
+                ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+                actor: { kind: 'system' },
+            },
+        };
+    }, opts.root);
+}
+/** The account the x.com browser session is signed in as (the one the authorize screen consents). */
+export function sessionAccount(root) {
+    const session = readOne(root, 'session', 'current');
+    const id = typeof session?.accountId === 'string' ? session.accountId : undefined;
+    return id ? readOne(root, 'account', id) : 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 function redirectUriAllowed(client, candidate) {
+    const registered = Array.isArray(client.redirectUris) ? client.redirectUris : [];
+    // A fragment never legitimately appears in a redirect_uri (RFC 6749 §3.1.2) and exact string
+    // membership would still admit one only if it had been REGISTERED with a fragment — refuse the
+    // candidate outright before comparing.
+    if (candidate.includes('#'))
+        return false;
+    return registered.includes(candidate);
+}

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

@@ -0,0 +1,54 @@
+import { type XResponse } from './xidentity-problems.js';
+export { RESOURCE_TYPES } from './xidentity-store.js';
+export type { XResponse } from './xidentity-problems.js';
+/** X's real hosts. The authorize screen lives on the site host; the API on api.x.com. The legacy
+ *  twitter.com pair still serves the same surface and X's legacy official SDK still targets it. */
+export declare const AUTHORIZE_ORIGIN = "https://x.com";
+export declare const API_ORIGIN = "https://api.x.com";
+export declare const LEGACY_AUTHORIZE_ORIGIN = "https://twitter.com";
+export declare const LEGACY_API_ORIGIN = "https://api.twitter.com";
+/** X's documented default access-token lifetime: "Access tokens default to 2-hour validity"
+ *  (docs.x.com authorization-code guide, fetched 2026-08-21). */
+export declare const ACCESS_TOKEN_TTL_SECONDS = 7200;
+/** X's authorization codes are short-lived; 30 seconds is the widely-reported figure.
+ *  EXTRAPOLATION — not read from a fetched official artefact; pinned as
+ *  `xidentity.token.code_ttl` (todo). The single-use rule, by contrast, is hard protocol. */
+export declare const AUTH_CODE_TTL_SECONDS = 30;
+/** GET /2/users/me: 75 requests / 15 min per user (docs.x.com/x-api/fundamentals/rate-limits,
+ *  fetched 2026-08-21). */
+export declare const USERS_ME_RATE_LIMIT = 75;
+export declare const RATE_WINDOW_SECONDS: number;
+export type XIdentityRequest = {
+    method: string;
+    /** Path plus query string, e.g. `/i/oauth2/authorize?client_id=…`. */
+    path: string;
+    body?: string;
+    /** Lower-cased request headers (authorization / content-type). */
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** Where this twin is reached (`twinPublicBase`: origin plus any served-World mount path) — the
+     *  consent form's action must point back at the twin. Absent (an in-process call), vendor-real
+     *  URLs are used. */
+    origin?: string;
+    /** The bare origin the request arrived at, when it differs from `origin` (a served World mounts
+     *  the twin under a path). The seeded demo app's callbacks derive from it; defaults to `origin`. */
+    callbackOrigin?: string;
+};
+export type XIdentityResponse = XResponse;
+/** The `user.fields` enum — the v2 OpenAPI's UserFieldsParameter (2.167), verbatim. */
+export declare const USER_FIELDS: readonly ["confirmed_email", "connection_status", "created_at", "description", "entities", "id", "is_identity_verified", "location", "name", "parody", "profile_banner_url", "profile_image_url", "protected", "public_metrics", "receives_your_dm", "subscribes_to_you", "subscription", "subscription_type", "url", "username", "verified", "verified_followers_count", "verified_type", "withheld"];
+/** The `expansions` enum — UserExpansionsParameter (2.167), verbatim. */
+export declare const USER_EXPANSIONS: readonly ["affiliation", "most_recent_post_id", "pinned_post_id"];
+/** The scopes GET /2/users/me demands — the OpenAPI operation's OAuth2UserToken entry lists BOTH. */
+export declare const USERS_ME_REQUIRED_SCOPES: readonly ["tweet.read", "users.read"];
+/** Every VENDOR endpoint this twin claims to serve. The conformance check drives one real request
+ *  per entry and grades the OUTCOME, so an entry here is a promise with teeth. Twin-only routes
+ *  (`/_twin/*`) are deliberately absent — they are scaffolding, not vendor surface. */
+export declare function xIdentityTwinSnapshot(): {
+    implementedEndpoints: string[];
+    resourceTypes: readonly string[];
+    grantTypes: string[];
+};
+export declare function handleXIdentityTwinRequest(req: XIdentityRequest): Promise<XResponse>;