@volter/twin-xidentity 0.1.0 → 0.1.2

package/dist/src/xidentity-oauth1.js

@@ -0,0 +1,594 @@
+// X's OAuth 1.0a — the three-legged flow and the user-context signature that authorizes the API.
+//
+//   api.x.com  POST /oauth/request_token        → step 1: a request token for a registered App
+//              GET  /oauth/authorize            → step 2: the authorize screen, always shown
+//              GET  /oauth/authenticate         → step 2 (Sign in with X): skipped once approved
+//              POST /oauth/access_token         → step 3: the request token + verifier → access token
+//              POST /1.1/oauth/invalidate_token → an App revokes an access token it holds
+//
+// GROUNDING (docs.x.com, fetched 2026-09-27): resources/fundamentals/authentication/api-reference
+// (the five endpoints, their parameters and the request/response examples quoted at each site),
+// .../oauth-1-0a/obtaining-user-access-tokens (the walkthrough: oauth_callback_confirmed, the
+// callback carrying oauth_token + oauth_verifier, tokens that "do not expire but can be revoked"),
+// .../oauth-1-0a/creating-a-signature (the HMAC-SHA1 base string: method, base URL, the sorted
+// percent-encoded parameter string; the signing key `consumer_secret&token_secret`), and
+// fundamentals/developer-apps (the Read / Read and write permission levels; the 415 "Callback URL
+// not approved" body verbatim). Legacy error codes 32/89/135/215 are X's v1.1 error table
+// (developer.x.com error-troubleshooting, whose codes the consumer library also enumerates:
+// twitter-api-v2@1.29.1 EApiV1ErrorCode); where a wording or status is not in a fetched page the
+// site says EXTRAPOLATION and a manifest todo pins it.
+//
+// THE CONSUMER this was built for is Postiz (gitroomhq/postiz-app@374fb202334a,
+// libraries/nestjs-libraries/src/integrations/social/x.provider.ts): `generateAuthLink(callback,
+// {authAccessType:'write', linkMode:'authenticate'})`, `login(oauth_verifier)`, then `v2.me()`,
+// v2 media upload and `POST /2/tweets`, every one signed with OAuth 1.0a HMAC-SHA1 by
+// twitter-api-v2 or by Postiz's own `signOAuth1`.
+//
+// ONE VENDOR, TWO PACKS. The access tokens minted here authorize X's posting surface too, which
+// the `x` pack serves. X has one credential store; this pack is it. The `x` pack READS the
+// `oauth1_token` and `oauth1_app` rows below through the kernel projection (never writes them) and
+// verifies the signature with its own transcription of `oauth1Params`/`signatureMatches` (A3
+// forbids the import). The row shapes are that contract:
+//   oauth1_app   id=consumer key  { secret, name, callbackUrls: string[], accessLevel: 'read'|'read-write', deleted? }
+//   oauth1_token id=access token  { consumerKey, secret, userId, screenName, accessLevel, revoked }
+// and the World's own App is the pair its env names (worldOAuth1App below, transcribed there too).
+//
+// NOT MODELLED (manifest todos): the ±5-minute timestamp window and nonce replay (code 135) — the
+// twin has no clock but the World's, and an app signs with its host's; request-token expiry; the
+// login screen force_login/screen_name would show (the twin authenticates nobody: the signed-in
+// session is the seeded persona, as for OAuth 2.0); the v1.1 API the tokens also authorize.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { applyTwinWriteAtomic, worldEnvValue } from '@volter/world-core';
+import { errorPageHtml, pinPageHtml, consentPageHtml, xIdentityOAuth1ConsentState } from "./xidentity-consent-ui.js";
+import { oauthError } from "./xidentity-problems.js";
+import { nextRevIn, readAll, readType, sessionAccount, stableHex, writeAtomic } from "./xidentity-store.js";
+const HTML = { 'content-type': 'text/html; charset=utf-8' };
+const JSON_TYPE = { 'content-type': 'application/json; charset=utf-8' };
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+// ── RFC 5849 mechanics, as X's creating-a-signature guide states them ───────────────────────────
+/** RFC 3986 percent-encoding, the guide's "Percent encoding parameters" (unreserved: A-Z a-z 0-9 - . _ ~). */
+export const pct = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+/** The `Authorization: OAuth k="v", …` header as decoded pairs; null when it is not an OAuth header. */
+export function parseOAuthHeader(value) {
+    if (!value)
+        return null;
+    const m = /^OAuth\s+(.*)$/is.exec(value.trim());
+    if (!m)
+        return null;
+    const out = [];
+    for (const part of m[1].split(',')) {
+        const kv = /^\s*([^=\s]+)\s*=\s*"([^"]*)"\s*$/.exec(part);
+        if (!kv) {
+            if (part.trim() === '')
+                continue;
+            return null;
+        }
+        try {
+            out.push([decodeURIComponent(kv[1]), decodeURIComponent(kv[2])]);
+        }
+        catch {
+            return null;
+        }
+    }
+    return out;
+}
+/** Every oauth_* protocol parameter the request carries, header first (RFC 5849 §3.5 order). */
+export function oauth1Params(req) {
+    const out = new Map();
+    for (const list of [req.header, req.body, req.query]) {
+        for (const [k, v] of list)
+            if (k.startsWith('oauth_') && !out.has(k))
+                out.set(k, v);
+    }
+    return out;
+}
+function baseString(method, baseUrl, pairs) {
+    const encoded = pairs.map(([k, v]) => [pct(k), pct(v)]).sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1));
+    return `${method.toUpperCase()}&${pct(baseUrl)}&${pct(encoded.map(([k, v]) => `${k}=${v}`).join('&'))}`;
+}
+/**
+ * The base strings a correct signer may have signed. The guide's rule collects every parameter
+ * once per occurrence (header, query, body) except `oauth_signature`, and RFC 5849 §3.4.1.3.1
+ * excludes the Authorization header's `realm` — only that one: a `realm` in the query or body is
+ * an ordinary, signed parameter. ONE leniency, and only it: twitter-api-v2 — the library Postiz
+ * logs in with — sends `oauth_token` in BOTH the header and the body of `POST oauth/access_token`
+ * and signs it ONCE (its OAuth1Helper merges the two into one object); X completes that login in
+ * production (Postiz's x.provider.ts `authenticate`), so the twin also accepts an `oauth_*`
+ * parameter the HEADER carries and the body or query repeats with the same value, counted once.
+ * Any other repetition is signed per occurrence (X "does not accept duplicate keys in API
+ * requests", creating-a-signature footnote 2 — a request that repeats a key is refused below).
+ */
+function candidateBaseStrings(req) {
+    const header = req.header.filter(([k]) => k !== 'oauth_signature' && k !== 'realm');
+    const rest = [...req.query, ...req.body].filter(([k]) => k !== 'oauth_signature');
+    const strict = baseString(req.method, req.baseUrl, [...header, ...rest]);
+    const inHeader = new Set(header.map(([k, v]) => `${k}\u0000${v}`));
+    const echoed = rest.filter(([k, v]) => !(k.startsWith('oauth_') && inHeader.has(`${k}\u0000${v}`)));
+    if (echoed.length === rest.length)
+        return [strict];
+    return [strict, baseString(req.method, req.baseUrl, [...header, ...echoed])];
+}
+/** A key repeated within the query or within the body (X accepts no duplicate keys — the guide). */
+function repeatsAKey(req) {
+    for (const list of [req.query, req.body]) {
+        const keys = list.map(([k]) => k);
+        if (new Set(keys).size !== keys.length)
+            return true;
+    }
+    return false;
+}
+/** HMAC-SHA1 over the base string with `pct(consumer_secret)&pct(token_secret)` — the guide's key. */
+export function signatureMatches(req, consumerSecret, tokenSecret) {
+    const presented = oauth1Params(req).get('oauth_signature');
+    if (!presented || repeatsAKey(req))
+        return false;
+    const key = `${pct(consumerSecret)}&${pct(tokenSecret)}`;
+    const given = Buffer.from(presented);
+    return candidateBaseStrings(req).some((base) => {
+        const expected = Buffer.from(createHmac('sha1', key).update(base).digest('base64'));
+        return expected.length === given.length && timingSafeEqual(expected, given);
+    });
+}
+/** The protocol parameters every signed X request carries. X signs with HMAC-SHA1 only (the guide). */
+function wellFormed(params) {
+    return ['oauth_consumer_key', 'oauth_nonce', 'oauth_signature', 'oauth_timestamp'].every((k) => (params.get(k) ?? '') !== '')
+        && params.get('oauth_signature_method') === 'HMAC-SHA1'
+        && (!params.has('oauth_version') || params.get('oauth_version') === '1.0');
+}
+const X_HOSTS = new Set(['api.x.com', 'api.twitter.com', 'x.com', 'twitter.com']);
+/**
+ * The URL the client signed. Reached through the injector the request still names X's host (the
+ * Node path keeps Host; the fetch path names it in `x-volter-twin-original-host`) and the client
+ * signed `https://<that host><path>`. Reached directly, it signed where it sent: `origin` (the
+ * twin's public base, a World mount included). A direct in-process call with neither is X's own
+ * API origin.
+ */
+export function signedBaseUrl(headers, origin, path) {
+    const named = (headers?.['x-volter-twin-original-host'] ?? headers?.['host'] ?? '').toLowerCase().replace(/:443$/, '');
+    if (X_HOSTS.has(named.replace(/:\d+$/, '')))
+        return `https://${named.replace(/:\d+$/, '')}${path}`;
+    const base = origin ?? 'https://api.x.com';
+    let u;
+    try {
+        u = new URL(base);
+    }
+    catch {
+        return `https://api.x.com${path}`;
+    }
+    const port = u.port && !((u.protocol === 'https:' && u.port === '443') || (u.protocol === 'http:' && u.port === '80')) ? `:${u.port}` : '';
+    return `${u.protocol}//${u.hostname.toLowerCase()}${port}${u.pathname.replace(/\/+$/, '')}${path}`;
+}
+/** Split a request into the signed pieces. Body pairs count only for a form-encoded body (the guide). */
+export function signedRequestOf(req) {
+    const [p, q = ''] = req.path.split('?');
+    const pairs = (s) => [...new URLSearchParams(s).entries()];
+    const type = (req.headers?.['content-type'] ?? '').toLowerCase();
+    const formBody = type.startsWith('application/x-www-form-urlencoded') && req.method.toUpperCase() !== 'GET';
+    return {
+        method: req.method,
+        baseUrl: signedBaseUrl(req.headers, req.origin, p ?? '/'),
+        header: parseOAuthHeader(req.headers?.['authorization']) ?? [],
+        query: pairs(q),
+        body: formBody ? pairs(req.body ?? '') : [],
+    };
+}
+// ── X's v1.1 error family for the OAuth endpoints ───────────────────────────────────────────────
+function v1Error(status, code, message) {
+    return { status, body: { errors: [{ code, message }] }, headers: { ...JSON_TYPE, ...NOSTORE } };
+}
+/** 215 "Bad Authentication data." — no usable OAuth header at all; X's table pairs it with HTTP 400. */
+export const badAuthenticationData = () => v1Error(400, 215, 'Bad Authentication data.');
+/** 32 "Could not authenticate you." — an unknown consumer key or a signature that does not verify (401). */
+export const couldNotAuthenticate = () => v1Error(401, 32, 'Could not authenticate you.');
+/** 89 "Invalid or expired token." — verbatim from the invalidate_token example (api-reference). */
+export const invalidOrExpiredToken = () => v1Error(401, 89, 'Invalid or expired token.');
+/** 415, the body verbatim from developer-apps' troubleshooting. HTTP 403 is EXTRAPOLATION
+ *  (the page shows the body only) — `xidentity.oauth1.callback_refusal_status` pins it. */
+export const callbackNotApproved = () => v1Error(403, 415, 'Callback URL not approved for this client application.');
+/** The env pairs a World names its X App with: Postiz's X_API_KEY / X_API_SECRET (x.provider.ts),
+ *  and the TWITTER_ spelling of the same "API Key and Secret" (docs.x.com's own name for the pair). */
+export const WORLD_APP_ENV = [['X_API_KEY', 'X_API_SECRET'], ['TWITTER_API_KEY', 'TWITTER_API_SECRET']];
+/**
+ * The World's own App: the one its env describes. An app holding consumer keys is an App its
+ * developer made in the X developer console, so the twin takes the World's values as that App's —
+ * the slack pack's worldSlackApp precedent. Only a value the World sets counts (worldEnvValue),
+ * never one the caller's shell passes. Where the documentation stops and the twin decides: the App
+ * is named for the World (VOLTER_WORLD_NAME, else "World app"); a key with no secret is no App;
+ * its console lists no callback URLs, since the env names none, so it accepts the callback each
+ * request names; its permission is Read and write, which an `x_auth_access_type=read` narrows.
+ */
+export function worldOAuth1App() {
+    for (const [keyName, secretName] of WORLD_APP_ENV) {
+        const key = worldEnvValue(keyName);
+        const secret = worldEnvValue(secretName);
+        if (key && secret) {
+            const name = (typeof process === 'undefined' ? undefined : process.env.VOLTER_WORLD_NAME) || 'World app';
+            return { consumerKey: key, secret, name, callbackUrls: [], accessLevel: 'read-write', world: true };
+        }
+    }
+    return undefined;
+}
+/** The App a consumer key names: one registered through the twin door, else the World's own. */
+export function oauth1AppOf(resources, consumerKey) {
+    if (!consumerKey)
+        return undefined;
+    const row = resources.find((r) => r.type === 'oauth1_app' && r.id === consumerKey);
+    if (row && row.deleted !== true) {
+        return {
+            consumerKey,
+            secret: String(row.secret),
+            name: String(row.name ?? consumerKey),
+            callbackUrls: Array.isArray(row.callbackUrls) ? row.callbackUrls.map(String) : [],
+            accessLevel: row.accessLevel === 'read' ? 'read' : 'read-write',
+        };
+    }
+    const world = worldOAuth1App();
+    return world?.consumerKey === consumerKey ? world : undefined;
+}
+// ── minting (the store's R9 rule: a stable hash of instant + rows held + subject) ───────────────
+const ALNUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** `n` characters of X's mixed-case alphanumeric token alphabet, from the store's stable hash. */
+function alnum(seed, n) {
+    const hex = stableHex(seed, n * 2);
+    let out = '';
+    for (let i = 0; i < n; i += 1)
+        out += ALNUM[parseInt(hex.slice(i * 2, i * 2 + 2), 16) % ALNUM.length];
+    return out;
+}
+function formBody(req) {
+    return new URLSearchParams(req.method.toUpperCase() === 'GET' ? '' : (req.body ?? ''));
+}
+/** A consumer-signed request, checked: the App it names and the signature it carries. */
+function verifyConsumer(req, resources, tokenSecret) {
+    const signed = signedRequestOf(req);
+    const params = oauth1Params(signed);
+    // No credentials at all (no consumer key, no signature, wherever they might travel): 215.
+    if (!params.has('oauth_consumer_key') && !params.has('oauth_signature'))
+        return { fail: badAuthenticationData() };
+    if (!wellFormed(params))
+        return { fail: couldNotAuthenticate() };
+    const app = oauth1AppOf(resources, params.get('oauth_consumer_key'));
+    if (!app)
+        return { fail: couldNotAuthenticate() };
+    const secret = tokenSecret(params);
+    if (secret === null)
+        return { fail: invalidOrExpiredToken() };
+    if (!signatureMatches(signed, app.secret, secret))
+        return { fail: couldNotAuthenticate() };
+    return { app, params };
+}
+const formReply = (pairs) => ({
+    status: 200,
+    body: new URLSearchParams(pairs).toString(),
+    // X answers these legs with a form-encoded body served as text/html (the api-reference examples
+    // show the body; the type is the widely-reported wire one — EXTRAPOLATION, and twitter-api-v2
+    // parses the OAuth endpoints as form-encoded whatever the type says).
+    headers: { ...HTML, ...NOSTORE },
+});
+// ── step 1: POST oauth/request_token ────────────────────────────────────────────────────────────
+async function requestToken(req) {
+    const at = req.occurredAt;
+    return (await applyTwinWriteAtomic('xidentity', (resources) => {
+        const checked = verifyConsumer(req, resources, () => '');
+        if ('fail' in checked)
+            return { kind: 'skip', value: checked.fail };
+        const { app, params } = checked;
+        // "For OAuth 1.0a compliance this parameter is required" (api-reference). A missing one is a
+        // malformed request: RFC 5849 §3.2 answers 400; the body is EXTRAPOLATION (215, pinned by
+        // `xidentity.oauth1.request_token_error_wording`).
+        const callback = params.get('oauth_callback');
+        if (!callback)
+            return { kind: 'skip', value: badAuthenticationData() };
+        // Any callback other than `oob` "will have to be configured within the App's settings", matched
+        // exactly (developer-apps troubleshooting). The World's App lists none and takes any.
+        if (callback !== 'oob') {
+            try {
+                new URL(callback);
+            }
+            catch {
+                return { kind: 'skip', value: callbackNotApproved() };
+            }
+            if (!app.world && !app.callbackUrls.includes(callback))
+                return { kind: 'skip', value: callbackNotApproved() };
+        }
+        // x_auth_access_type "overrides the access level an application requests … supported values are
+        // read or write … to register a read/write application but also request read only access": it
+        // can only narrow. A value outside the two is ignored (EXTRAPOLATION, pinned by
+        // `xidentity.oauth1.access_type_unknown_value`).
+        const asked = new URLSearchParams(req.path.split('?')[1] ?? '').get('x_auth_access_type') ?? formBody(req).get('x_auth_access_type');
+        const accessLevel = app.accessLevel === 'read' || asked === 'read' ? 'read' : 'read-write';
+        const held = resources.filter((r) => r.type === 'oauth1_request_token').length;
+        const token = alnum(`oauth1_request_token:${at}:${held}:${app.consumerKey}`, 27);
+        const secret = alnum(`oauth1_request_token_secret:${at}:${held}:${token}`, 32);
+        return {
+            kind: 'write',
+            value: formReply({ oauth_token: token, oauth_token_secret: secret, oauth_callback_confirmed: 'true' }),
+            write: {
+                operation: 'oauth1_request_token.create',
+                subjectType: 'oauth1_request_token',
+                subjectId: token,
+                fields: { consumerKey: app.consumerKey, secret, callback, accessLevel, state: 'issued', rev: 1 },
+                occurredAt: at,
+                actor: { kind: 'agent' },
+            },
+        };
+    }, req.root)).value;
+}
+// ── step 2: GET oauth/authorize | oauth/authenticate ────────────────────────────────────────────
+/** The page X shows for a request token it does not hold. The "Whoa there!" wording is X's classic
+ *  page as widely reported; status and DOM are EXTRAPOLATION (`xidentity.oauth1.invalid_token_page`). */
+function invalidRequestTokenPage(req) {
+    return {
+        status: 400,
+        body: errorPageHtml({ status: 400, code: 'invalid_request_token', detail: 'Whoa there! The request token for this page is invalid. It may have already been used, or expired because it is too old. Please go back to the site or application that sent you here and try again; it was probably just a mistake.' }, req.origin ?? ''),
+        headers: { ...HTML, ...NOSTORE },
+    };
+}
+function withParams(callback, params) {
+    const url = new URL(callback);
+    for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, v);
+    return url.toString();
+}
+async function authorizeScreen(req, mode) {
+    const root = req.root;
+    const query = new URLSearchParams(req.path.split('?')[1] ?? '');
+    const token = query.get('oauth_token') ?? '';
+    const at = req.occurredAt;
+    const all = readAll(root);
+    const row = all.find((r) => r.type === 'oauth1_request_token' && r.id === token);
+    if (!row || (row.state !== 'issued' && row.state !== 'pending'))
+        return invalidRequestTokenPage(req);
+    const app = oauth1AppOf(all, String(row.consumerKey));
+    if (!app)
+        return invalidRequestTokenPage(req);
+    if (req.readOnly)
+        return oauthError('temporarily_unavailable', 'this twin was started read-only; omit readOnly to accept writes', 405);
+    const account = sessionAccount(root);
+    if (!account) {
+        return { status: 400, body: errorPageHtml({ status: 400, code: 'invalid_request', detail: 'No x.com session is signed in on this twin. Seed an account and set /_twin/session.' }, req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+    }
+    // Sign in with X: "if the user has already granted the application permission, the redirect will
+    // occur without the user having to re-approve" — unless force_login=true (api-reference). A
+    // grant at a narrower level than this request asks for is not that permission. X does this only
+    // for an App with the "Use Sign in with X" setting enabled; the twin treats every App as having it
+    // (EXTRAPOLATION — `xidentity.oauth1.sign_in_with_x_setting`, todo).
+    const grant = all.find((r) => r.type === 'oauth1_grant' && r.id === `${app.consumerKey}:${account.id}`);
+    const covered = grant && grant.revoked !== true && (grant.accessLevel === 'read-write' || row.accessLevel === 'read');
+    if (mode === 'authenticate' && covered && query.get('force_login') !== 'true' && row.callback !== 'oob') {
+        return settle(req, token, 'allow', String(account.id));
+    }
+    // Bind the screen to the account it shows, so a later session switch cannot mint for another.
+    const presented = await applyTwinWriteAtomic('xidentity', (resources) => {
+        const now = resources.find((r) => r.type === 'oauth1_request_token' && r.id === token);
+        // decided (or exchanged) since the read above: never reopen it
+        if (!now || (now.state !== 'issued' && now.state !== 'pending'))
+            return { kind: 'skip', value: false };
+        return {
+            kind: 'write',
+            value: true,
+            write: { operation: 'oauth1_request_token.present', subjectType: 'oauth1_request_token', subjectId: token, fields: { state: 'pending', accountId: account.id, rev: nextRevIn(resources, 'oauth1_request_token', token) }, occurredAt: at, actor: { kind: 'agent' } },
+        };
+    }, root);
+    if (!presented.value)
+        return invalidRequestTokenPage(req);
+    const view = xIdentityOAuth1ConsentState({ root, requestToken: token, appName: app.name, origin: req.origin ?? 'https://api.x.com' });
+    if (!view)
+        return invalidRequestTokenPage(req);
+    return { status: 200, body: consentPageHtml(view, req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+}
+/**
+ * The decision: the screen's form posts back to `POST oauth/authorize` on the host that served it,
+ * as X's own authorize screen does (its form's action is `https://api.x.com/oauth/authorize`; the
+ * form fields are the twin's). It must be a path this pack claims on api.x.com: that host is
+ * shared with the `x` pack, which owns its `/_twin/*`, so a `/_twin/` door there never reached this
+ * pack in a World (the Postiz walk, 2026-09-28: "Authorize app" answered the x pack's JSON 400). Allow → the callback with `oauth_token` and
+ * `oauth_verifier` (obtaining-user-access-tokens), or for `oob` the PIN page; Cancel → the callback
+ * with `denied=<request token>` (the flowchart on the same page; the parameter name is the widely
+ * reported one — EXTRAPOLATION, `xidentity.oauth1.denied_callback`).
+ */
+async function settle(req, token, decision, accountId) {
+    const at = req.occurredAt;
+    const decided = await applyTwinWriteAtomic('xidentity', (resources) => {
+        const row = resources.find((r) => r.type === 'oauth1_request_token' && r.id === token);
+        const who = accountId ?? (row ? String(row.accountId ?? '') : '');
+        if (!row || (accountId ? row.state !== 'issued' && row.state !== 'pending' : row.state !== 'pending') || !who) {
+            return { kind: 'skip', value: { page: 'invalid' } };
+        }
+        const app = oauth1AppOf(resources, String(row.consumerKey));
+        const base = { operation: 'oauth1_request_token.settle', subjectType: 'oauth1_request_token', subjectId: token, occurredAt: at, actor: { kind: 'human' } };
+        if (decision !== 'allow' || !app) {
+            return { kind: 'write', value: { denied: String(row.callback) }, write: { ...base, fields: { state: 'denied', rev: nextRevIn(resources, 'oauth1_request_token', token) } } };
+        }
+        const held = resources.filter((r) => r.type === 'oauth1_request_token' && typeof r.verifier === 'string').length;
+        // The web flow's verifier is an opaque string (obtaining-user-access-tokens' example: 42
+        // alphanumerics; the twin mints 32). Out-of-band it is the PIN the person types: "a X
+        // generated ~7 digit PIN" (pin-based-oauth), `oauth_verifier=4868795` in the api-reference.
+        const verifier = row.callback === 'oob'
+            ? String(parseInt(stableHex(`oauth1_pin:${at}:${held}:${token}`, 8), 16) % 9_000_000 + 1_000_000)
+            : alnum(`oauth1_verifier:${at}:${held}:${token}`, 32);
+        const grantId = `${app.consumerKey}:${who}`;
+        const grantExists = resources.some((r) => r.type === 'oauth1_grant' && r.id === grantId);
+        // A narrower approval does not take back a wider one the person already gave this App.
+        const prior = resources.find((r) => r.type === 'oauth1_grant' && r.id === grantId);
+        const level = prior && prior.revoked !== true && prior.accessLevel === 'read-write' ? 'read-write' : row.accessLevel;
+        const grantFields = { consumerKey: app.consumerKey, userId: who, accessLevel: level, revoked: false, rev: nextRevIn(resources, 'oauth1_grant', grantId) };
+        return {
+            kind: 'write',
+            value: { allowed: String(row.callback), verifier, appName: app.name },
+            write: {
+                ...base,
+                fields: { state: 'authorized', verifier, accountId: who, rev: nextRevIn(resources, 'oauth1_request_token', token) },
+                projection: grantExists
+                    ? { updates: [{ type: 'oauth1_grant', id: grantId, fields: grantFields }] }
+                    : { creates: [{ type: 'oauth1_grant', id: grantId, fields: grantFields }] },
+            },
+        };
+    }, req.root);
+    const v = decided.value;
+    if (v.page === 'invalid')
+        return invalidRequestTokenPage(req);
+    if (v.denied !== undefined) {
+        if (v.denied === 'oob')
+            return { status: 200, body: errorPageHtml({ status: 200, code: 'access_denied', detail: 'You did not authorize the app.' }, req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+        return { status: 302, body: '', headers: { location: withParams(v.denied, { denied: token }), ...NOSTORE } };
+    }
+    if (v.allowed === 'oob')
+        return { status: 200, body: pinPageHtml(v.appName ?? '', v.verifier ?? '', req.origin ?? ''), headers: { ...HTML, ...NOSTORE } };
+    return { status: 302, body: '', headers: { location: withParams(v.allowed, { oauth_token: token, oauth_verifier: v.verifier }), ...NOSTORE } };
+}
+// ── step 3: POST oauth/access_token ─────────────────────────────────────────────────────────────
+async function accessToken(req) {
+    const at = req.occurredAt;
+    return (await applyTwinWriteAtomic('xidentity', (resources) => {
+        const requestRow = (params) => resources.find((r) => r.type === 'oauth1_request_token' && r.id === params.get('oauth_token'));
+        const checked = verifyConsumer(req, resources, (params) => {
+            const row = requestRow(params);
+            // Unknown, already exchanged, denied or never approved: the token is not one X will trade.
+            if (!row || row.state !== 'authorized' || row.consumerKey !== params.get('oauth_consumer_key'))
+                return null;
+            return String(row.secret);
+        });
+        if ('fail' in checked)
+            return { kind: 'skip', value: checked.fail };
+        const row = requestRow(checked.params);
+        // "applications not using the oauth_verifier will fail to complete the OAuth flow"
+        // (api-reference). The refusal's body is EXTRAPOLATION (X answers this leg with a plain-text
+        // error, widely reported as below — `xidentity.oauth1.access_token_error_wording`).
+        const verifier = checked.params.get('oauth_verifier') ?? formBody(req).get('oauth_verifier') ?? new URLSearchParams(req.path.split('?')[1] ?? '').get('oauth_verifier');
+        if (!verifier || verifier !== row.verifier) {
+            return { kind: 'skip', value: { status: 401, body: 'Error processing your OAuth request: Invalid oauth_verifier parameter', headers: { 'content-type': 'text/plain; charset=utf-8', ...NOSTORE } } };
+        }
+        const userId = String(row.accountId);
+        const account = resources.find((r) => r.type === 'account' && r.id === userId);
+        if (!account)
+            return { kind: 'skip', value: invalidOrExpiredToken() };
+        // X's user access tokens "do not expire but can be revoked" (obtaining-user-access-tokens), and
+        // "once an access_token has been invalidated, new creation attempts will yield a different
+        // Access Token" (api-reference, invalidate_token) — so until then a creation attempt yields the
+        // token the App already holds for that user and level. That reading is EXTRAPOLATION from the
+        // two sentences, pinned by `xidentity.oauth1.reauthorize_token_reuse_pin` (todo).
+        const existing = resources.find((r) => r.type === 'oauth1_token' && r.consumerKey === row.consumerKey
+            && r.userId === userId && r.accessLevel === row.accessLevel && r.revoked !== true);
+        const held = resources.filter((r) => r.type === 'oauth1_token').length;
+        // The docs' example: `oauth_token=6253282-eWudHldSbIaelX7swmsiHImEL4KinwaGloHANdrY` — the user
+        // id, a dash, 40 alphanumerics; a 40-character secret.
+        const token = existing ? String(existing.id) : `${userId}-${alnum(`oauth1_token:${at}:${held}:${row.id}`, 40)}`;
+        const secret = existing ? String(existing.secret) : alnum(`oauth1_token_secret:${at}:${held}:${token}`, 40);
+        const screenName = String(account.username ?? '');
+        const consume = { operation: 'oauth1_request_token.exchange', subjectType: 'oauth1_request_token', subjectId: String(row.id), occurredAt: at, actor: { kind: 'agent' } };
+        return {
+            kind: 'write',
+            value: formReply({ oauth_token: token, oauth_token_secret: secret, user_id: userId, screen_name: screenName }),
+            write: {
+                ...consume,
+                fields: { state: 'exchanged', rev: nextRevIn(resources, 'oauth1_request_token', String(row.id)) },
+                ...(existing ? {} : {
+                    projection: { creates: [{ type: 'oauth1_token', id: token, fields: { consumerKey: row.consumerKey, secret, userId, screenName, accessLevel: row.accessLevel, revoked: false, rev: 1 } }] },
+                }),
+            },
+        };
+    }, req.root)).value;
+}
+/** A request signed with an access token this pack issued and has not revoked; null otherwise. */
+export function verifyUserContext(req, resources) {
+    const signed = signedRequestOf(req);
+    if (signed.header.length === 0)
+        return null;
+    const params = oauth1Params(signed);
+    if (!wellFormed(params))
+        return null;
+    const token = resources.find((r) => r.type === 'oauth1_token' && r.id === params.get('oauth_token'));
+    if (!token || token.revoked === true || token.consumerKey !== params.get('oauth_consumer_key'))
+        return null;
+    const app = oauth1AppOf(resources, String(token.consumerKey));
+    if (!app)
+        return null;
+    return signatureMatches(signed, app.secret, String(token.secret)) ? { token, app } : null;
+}
+/** The OAuth 2.0 scopes an OAuth 1.0a token's permission level stands for on a v2 endpoint that
+ *  declares both schemes (the OpenAPI's `security` lists OAuth2UserToken scopes OR UserToken). */
+export function scopesOfAccessLevel(level) {
+    return level === 'read' ? ['tweet.read', 'users.read'] : ['tweet.read', 'users.read', 'tweet.write', 'media.write'];
+}
+// ── POST 1.1/oauth/invalidate_token ─────────────────────────────────────────────────────────────
+async function invalidateToken(req) {
+    const at = req.occurredAt;
+    return (await applyTwinWriteAtomic('xidentity', (resources) => {
+        const who = verifyUserContext(req, resources);
+        if (!who)
+            return { kind: 'skip', value: invalidOrExpiredToken() };
+        const id = String(who.token.id);
+        const grantId = `${who.token.consumerKey}:${who.token.userId}`;
+        const grant = resources.some((r) => r.type === 'oauth1_grant' && r.id === grantId);
+        return {
+            kind: 'write',
+            // The api-reference example response, verbatim in shape: {"access_token":"ACCESS_TOKEN"}.
+            value: { status: 200, body: { access_token: id }, headers: { ...JSON_TYPE, ...NOSTORE } },
+            write: {
+                operation: 'oauth1_token.invalidate',
+                subjectType: 'oauth1_token',
+                subjectId: id,
+                fields: { revoked: true, rev: nextRevIn(resources, 'oauth1_token', id) },
+                ...(grant ? { projection: { updates: [{ type: 'oauth1_grant', id: grantId, fields: { revoked: true, rev: nextRevIn(resources, 'oauth1_grant', grantId) } }] } } : {}),
+                occurredAt: at,
+                actor: { kind: 'agent' },
+            },
+        };
+    }, req.root)).value;
+}
+// ── the twin door: register an App (the developer console has no API) ─────────────────────────
+async function registerApp(req) {
+    let b;
+    try {
+        b = JSON.parse(req.body ?? '{}');
+    }
+    catch {
+        return oauthError('invalid_request', 'A JSON body is required.', 400);
+    }
+    const at = req.occurredAt;
+    const held = readType(req.root, 'oauth1_app').length;
+    const key = typeof b['consumer_key'] === 'string' && b['consumer_key'] ? String(b['consumer_key']) : alnum(`oauth1_app:${at}:${held}`, 25);
+    if (key.includes(':'))
+        return oauthError('invalid_request', 'consumer_key must not contain ":".', 400);
+    const level = b['access_level'] === 'read' ? 'read' : 'read-write';
+    const row = await writeAtomic('oauth1_app', key, 'oauth1_app.create', () => ({
+        name: typeof b['name'] === 'string' ? b['name'] : 'Twin App',
+        secret: typeof b['consumer_secret'] === 'string' && b['consumer_secret'] ? b['consumer_secret'] : alnum(`oauth1_app_secret:${at}:${held}:${key}`, 50),
+        callbackUrls: Array.isArray(b['callback_urls']) ? b['callback_urls'].map(String) : [],
+        accessLevel: level,
+    }), { root: req.root, occurredAt: at });
+    return { status: 200, body: { consumer_key: key, consumer_secret: row.secret, name: row.name, callback_urls: row.callbackUrls, access_level: row.accessLevel } };
+}
+// ── router slice ────────────────────────────────────────────────────────────────────────────────
+export const OAUTH1_ENDPOINTS = [
+    'POST /oauth/request_token',
+    'GET /oauth/authorize',
+    'POST /oauth/authorize',
+    'GET /oauth/authenticate',
+    'POST /oauth/access_token',
+    'POST /1.1/oauth/invalidate_token',
+    'POST /1.1/oauth/invalidate_token.json',
+];
+/** Paths this slice writes on (read-only twins refuse them). */
+export const OAUTH1_WRITE_PATHS = new Set(['/oauth/request_token', '/oauth/access_token', '/1.1/oauth/invalidate_token', '/1.1/oauth/invalidate_token.json']);
+/** Route an OAuth 1.0a request; null when the path is not this slice's. */
+export async function routeOAuth1(req, method, path) {
+    if (method === 'POST' && path === '/oauth/request_token')
+        return requestToken(req);
+    if (method === 'GET' && path === '/oauth/authorize')
+        return authorizeScreen(req, 'authorize');
+    if (method === 'GET' && path === '/oauth/authenticate')
+        return authorizeScreen(req, 'authenticate');
+    if (method === 'POST' && path === '/oauth/access_token')
+        return accessToken(req);
+    if (method === 'POST' && (path === '/1.1/oauth/invalidate_token' || path === '/1.1/oauth/invalidate_token.json'))
+        return invalidateToken(req);
+    if (method === 'POST' && path === '/oauth/authorize') {
+        const form = formBody(req);
+        return settle(req, form.get('auth_request') ?? '', form.get('decision') ?? '');
+    }
+    if (method === 'POST' && path === '/_twin/oauth1_apps')
+        return registerApp(req);
+    return null;
+}

package/dist/src/xidentity-server.js

@@ -10,8 +10,9 @@
 //   • 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 { isReadOnlyRequest, serveHttp, withRequestScopes } from '@volter/world-core';
 import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from "./xidentity-consent-ui.js";
+import { oauthError } from "./xidentity-problems.js";
 import { worldNow, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
 import { handleXIdentityTwinRequest } from "./xidentity-twin.js";
 /**
@@ -28,8 +29,12 @@ import { handleXIdentityTwinRequest } from "./xidentity-twin.js";
  * 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) {
+    // a read-only request (x-volter-read-only, a World's read token) is a request to a read-only twin: the
+    // authorize screen never signs anyone in or mints a code, no token is minted or revoked, GET
+    // /2/users/me is served without spending the app's rate window (D3), and the kernel refuses any write
+    // that slips past as X's own flat OAuth error
+    return withRequestScopes(async function xIdentityTwinFetch(request) {
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
         const url = new URL(request.url);
         // GET /twin — the discovery manifest (education inside the twin).
         if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
@@ -67,7 +72,12 @@ export function createXIdentityTwinFetch(options = {}) {
         }
         out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
         return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
-    };
+    }, {
+        refuse: () => {
+            const refused = oauthError('temporarily_unavailable', 'this request is read-only', 405);
+            return Response.json(refused.body, { status: refused.status, headers: refused.headers });
+        },
+    });
 }
 export async function createXIdentityTwinServer(options) {
     const server = await serveHttp({