@volter/twin-x 0.1.0 → 0.1.1

package/dist/src/index.js

@@ -16,11 +16,13 @@ import { X_RATE_BUDGET as RATE_BUDGET } from "./x-budget.js";
  * recent search, the three per-user timelines (mentions, the account's own posts, the home
  * timeline), user lookup by id and by username, and image upload (one-shot and chunked) — plus the
  * twin-only control prefix. The user-id
- * rule EXCLUDES `/2/users/me`: that route is xidentity's, and the two claims stay disjoint. ANCHORED: an unanchored claim would swallow
+ * rule EXCLUDES `/2/users/me`: that route is xidentity's, and the two claims stay disjoint. So does
+ * the control prefix: `/_twin/assets/consent.{js,css}` are xidentity's, the page assets of the
+ * OAuth 1.0a screen it serves on this host (claimed here, the screen rendered unstyled in a World). ANCHORED: an unanchored claim would swallow
  * `/2/tweetsomething`. Everything else on api.x.com stays unclaimed, so an unmodelled X call
  * refuses loudly rather than landing in a twin that cannot serve it.
  */
-const X_API_PATHS = '^(?:/2/media/upload/?|/2/media/upload/initialize/?|/2/media/upload/[0-9]+/(?:append|finalize)/?|/2/tweets/?|/2/tweets/[^/]+/?|/2/tweets/search/recent/?|/2/users/(?!me/?$)[^/]+/?|/2/users/by/username/[^/]+/?|/2/users/[^/]+/mentions/?|/2/users/[^/]+/tweets/?|/2/users/[^/]+/timelines/reverse_chronological/?)$|^/_twin/';
+const X_API_PATHS = '^(?:/2/media/upload/?|/2/media/upload/initialize/?|/2/media/upload/[0-9]+/(?:append|finalize)/?|/2/tweets/?|/2/tweets/[^/]+/?|/2/tweets/search/recent/?|/2/users/(?!me/?$)[^/]+/?|/2/users/by/username/[^/]+/?|/2/users/[^/]+/mentions/?|/2/users/[^/]+/tweets/?|/2/users/[^/]+/timelines/reverse_chronological/?)$|^/_twin/(?!assets/consent\\.(?:js|css)$)';
 export const pack = {
     vendor: 'x',
     // The SAME object x-budget.ts declares at module load — one source of truth, so registering

package/dist/src/x-capabilities.js

@@ -6,6 +6,7 @@
 // are X surface this manifest deliberately does NOT enumerate — they are outside the census's
 // committed boundary, and claiming them here would inflate a denominator nothing measures.
 // (`packages/twin/xidentity` owns X's OAuth + identity surface and its own denominator.)
+import { createHmac } from 'node:crypto';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -13,6 +14,8 @@ import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
 import { pushXAction, xRequestForAction, syncXFromReal } from "./x-connector.js";
 import { X_BUDGET_CEILING, X_CALL_WEIGHTS, X_RATE_BUDGET, XBudget, XBudgetError, xCallWeight } from "./x-budget.js";
 import { handleXTwinRequest } from "./x-twin.js";
+import { createXTwinFetch } from "./x-server.js";
+import { applyTwinWrite } from '@volter/world-core';
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { PostRow, ProfileHeader } from "../client/x-mirror.js";
@@ -101,6 +104,30 @@ const MEDIA_AUTH = { authorization: 'Bearer org-media-token' };
 async function mediaToken(h) {
     await h({ m: 'POST', p: '/_twin/tokens', b: { token: 'org-media-token', account_id: ORG, scopes: [...FULL_SCOPES, 'media.write'] }, headers: {} });
 }
+// ── OAuth 1.0a: xidentity's credential store, and an independent client signer ──────────────────
+// The access token a person approved lives in xidentity's state (xidentity-oauth1.ts names the row
+// shapes as the contract; x-oauth1.ts reads them). A verify here cannot run xidentity's legs — A3
+// forbids the import — so it writes the rows those legs write, on the same root, as a World that
+// ran them would hold; x-oauth1.integration.test.ts drives the real legs across both packs.
+const O1_APP = { key: 'VerifyConsumerKey00000001', secret: 'VerifyConsumerSecret000000000000000000000000001' };
+const O1_TOKEN = { key: `${ORG}-VerifyAccessToken0000000000000000000000000`, secret: 'VerifyAccessSecret000000000000000000000001' };
+async function seedOAuth1(root, token = O1_TOKEN, fields = {}) {
+    const at = '2026-02-01T00:00:00.000Z';
+    await applyTwinWrite('xidentity', { operation: 'oauth1_app.create', subjectType: 'oauth1_app', subjectId: O1_APP.key, fields: { secret: O1_APP.secret, name: 'Verify App', callbackUrls: [], accessLevel: 'read-write' }, occurredAt: at }, root);
+    await applyTwinWrite('xidentity', { operation: 'oauth1_token.create', subjectType: 'oauth1_token', subjectId: token.key, fields: { consumerKey: O1_APP.key, secret: token.secret, userId: ORG, screenName: 'orgvoice', accessLevel: 'read-write', revoked: false, ...fields }, occurredAt: at }, root);
+}
+/** RFC 5849 HMAC-SHA1, written here from docs.x.com's creating-a-signature guide — NOT x-oauth1.ts's
+ *  verifier, so a verify cannot pass by agreeing with itself. `url` is what the client signed. */
+function o1Header(method, url, app = O1_APP, token = O1_TOKEN) {
+    const enc = (v) => encodeURIComponent(v).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+    const [base, query = ''] = url.split('?');
+    const oauth = { oauth_consumer_key: app.key, oauth_nonce: 'verifynonce', oauth_signature_method: 'HMAC-SHA1', oauth_timestamp: '1769904000', oauth_token: token.key, oauth_version: '1.0' };
+    const params = [...Object.entries(oauth), ...new URLSearchParams(query).entries()].map(([k, v]) => `${enc(k)}=${enc(v)}`).sort().join('&');
+    oauth['oauth_signature'] = createHmac('sha1', `${enc(app.secret)}&${enc(token.secret)}`).update(`${method}&${enc(base)}&${enc(params)}`).digest('base64');
+    return 'OAuth ' + Object.entries(oauth).map(([k, v]) => `${enc(k)}="${enc(v)}"`).join(', ');
+}
+/** A direct in-process call names no host, so the client signed X's own API origin. */
+const API = 'https://api.x.com';
 const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
 const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
 export const X_CAPABILITIES = [
@@ -108,6 +135,22 @@ export const X_CAPABILITIES = [
     // packages/twin/xidentity; this pack CONSUMES the user access token that flow mints) ─────────
     todo('x.stream.filtered', 'streaming', 'Filtered stream (GET /2/tweets/search/stream): serve the long-lived streaming connection over the twin\'s stored posts, matching the filtered-stream rules, with reconnect and backfill_minutes semantics', 'api', 'common'),
     todo('x.stream.sampled', 'streaming', 'Sampled volume streams (GET /2/tweets/sample/stream and sample10): serve the streaming connection over the twin\'s stored posts with the vendor\'s partitioning parameters', 'api', 'niche'),
+    done('x.media.multipart_unnamed_part', 'media', 'A multipart APPEND whose media part names no filename (twitter-api-v2\'s uploadMedia, what Postiz sends) keeps its bytes exactly: the image it finalizes is the one uploaded', 'api', 'common', () => withWorld(async (h, root) => {
+        await mediaToken(h);
+        const fetchTwin = createXTwinFetch({ root });
+        const png = tinyPng();
+        const init = await h({ m: 'POST', p: '/2/media/upload/initialize', b: { media_type: 'image/png', total_bytes: png.length, media_category: 'tweet_image' }, headers: MEDIA_AUTH });
+        const id = String(init.body.data?.id ?? '');
+        const boundary = '----twinverify';
+        const part = (head, bytes) => concat(new TextEncoder().encode(`--${boundary}\r\n${head}\r\n\r\n`), bytes, new TextEncoder().encode('\r\n'));
+        const body = concat(new TextEncoder().encode(`a preamble, which is not a part --${boundary} either\r\n`), part('Content-Disposition: form-data; name="segment_index"', new TextEncoder().encode('0')), part('Content-Disposition: form-data; name="media"\r\nContent-Type: application/octet-stream', png), new TextEncoder().encode(`--${boundary}--\r\n`));
+        const append = await fetchTwin(new Request(`http://127.0.0.1:9/2/media/upload/${id}/append`, { method: 'POST', headers: { ...MEDIA_AUTH, 'content-type': `multipart/form-data; boundary=${boundary}` }, body: Buffer.from(body) }));
+        const fin = await h({ m: 'POST', p: `/2/media/upload/${id}/finalize`, headers: MEDIA_AUTH });
+        const posted = await h({ m: 'POST', p: '/2/tweets', b: { text: 'with the image', media: { media_ids: [id] } }, headers: MEDIA_AUTH });
+        const read = await h({ m: 'GET', p: `/2/tweets/${String(posted.body.data?.id)}?expansions=attachments.media_keys&media.fields=width,height,url`, headers: MEDIA_AUTH });
+        const media = read.body.includes?.media?.[0];
+        return append.status === 200 && fin.status === 200 && posted.status === 201 && media?.width === 64 && media?.height === 48;
+    })),
     done('x.media.upload', 'media', 'Media upload: POST /2/media/upload for an image, and the chunked initialize/append/finalize protocol with its STATUS-polled processing states for a video, persisting the bytes and returning a media_id attachable to a post', 'api', 'common', () => withWorld(async (h) => {
         await mediaToken(h);
         // an image in one request, base64 in a JSON body: its size and dimensions read from its bytes
@@ -183,6 +226,35 @@ export const X_CAPABILITIES = [
             && body.title === 'Invalid Request'
             && Array.isArray(body.errors) && body.errors[0].parameters.text !== undefined;
     })),
+    done('x.tweets.disclosure_labels_false', 'tweets', 'made_with_ai / paid_partnership sent as false: an unlabelled post or reply, as Postiz sends every one', 'api', 'common', () => withWorld(async (h) => {
+        const labels = { made_with_ai: false, paid_partnership: false };
+        const created = await h({ m: 'POST', p: '/2/tweets', b: { text: 'scheduled from postiz', ...labels } });
+        const id = created.body.data?.id;
+        if (created.status !== 201 || typeof id !== 'string')
+            return false;
+        const replied = await h({ m: 'POST', p: '/2/tweets', b: { text: 'and a thread', reply: { in_reply_to_tweet_id: id }, ...labels } });
+        const replyId = replied.body.data?.id;
+        if (replied.status !== 201)
+            return false;
+        // both landed as STATE: the reply joined the post's conversation, read back through the twin
+        const read = (await h({ m: 'GET', p: `/2/tweets/${replyId}?${THREAD_FIELDS}` })).body;
+        if (read.data?.conversation_id !== id || read.data?.referenced_tweets?.[0]?.id !== id)
+            return false;
+        // a label that says something is still refused by name, and nothing lands; a non-boolean is invalid
+        const before = (await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body.meta?.result_count;
+        const labelled = await h({ m: 'POST', p: '/2/tweets', b: { text: 'an ad', paid_partnership: true } });
+        const stringly = await h({ m: 'POST', p: '/2/tweets', b: { text: 'ai?', made_with_ai: 'false' } });
+        const after = (await h({ m: 'GET', p: `/2/users/${ORG}/tweets` })).body.meta?.result_count;
+        // `true` is refused as unmodelled surface; a string is not a boolean at all — two different refusals
+        const labelledError = labelled.body.errors?.[0];
+        const stringlyError = stringly.body.errors?.[0];
+        return labelled.status === 400 && labelledError?.parameters?.paid_partnership?.[0] === 'true'
+            && /does not model/.test(String(labelledError?.message)) && !/must be a boolean/.test(String(labelledError?.message))
+            && stringly.status === 400 && stringlyError?.parameters?.made_with_ai?.[0] === '"false"'
+            && /must be a boolean/.test(String(stringlyError?.message)) && !/does not model/.test(String(stringlyError?.message))
+            && before === 2 && after === 2;
+    })),
+    todo('x.tweets.disclosure_labels', 'tweets', 'made_with_ai / paid_partnership set true: the AI-generated-media and paid-partnership labels stored and shown on the post', 'api', 'common'),
     done('x.tweets.ids_are_snowflake_shaped_and_unique', 'tweets', 'Minted post ids are numeric snowflakes, never a row count', 'api', 'core', () => withWorld(async (h) => {
         const ids = [];
         for (const text of ['one', 'two', 'three']) {
@@ -381,6 +453,21 @@ export const X_CAPABILITIES = [
             && unmodelled.status === 400 && unmodelled.body.errors?.[0]?.parameters?.['user.fields']?.[0] === 'public_metrics'
             && unknown.status === 400;
     })),
+    // Postiz asks it on every @-mention lookup (x.provider.ts `mention`: userByUsername with
+    // user.fields username,name,profile_image_url; its connect-time v2.me is xidentity's); refused, the
+    // mention box showed no suggestions (cookbook/postiz finding 14).
+    done('x.fields.user_profile_image_url', 'fields', "user.fields=profile_image_url: the photo the account set, or X's default avatar for one that never set a photo — every X account has one", 'api', 'common', () => withWorld(async (h) => {
+        const photo = 'https://pbs.twimg.com/profile_images/1/pictured_normal.jpg';
+        await h({ m: 'POST', p: '/_twin/accounts', b: { id: '3100', username: 'pictured', name: 'Pictured', profile_image_url: photo }, headers: {} });
+        await h({ m: 'POST', p: '/_twin/accounts', b: { id: '3101', username: 'plain', name: 'Plain' }, headers: {} });
+        const own = (await h({ m: 'GET', p: '/2/users/by/username/pictured?user.fields=username,name,profile_image_url' })).body.data;
+        const plain = (await h({ m: 'GET', p: '/2/users/3101?user.fields=profile_image_url' })).body.data;
+        const bare = (await h({ m: 'GET', p: '/2/users/3100' })).body.data;
+        const bad = await h({ m: 'POST', p: '/_twin/accounts', b: { username: 'badphoto', profile_image_url: 'not a url' }, headers: {} });
+        return own?.profile_image_url === photo && own?.name === 'Pictured'
+            && plain?.profile_image_url === 'https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png'
+            && bare?.profile_image_url === undefined && bad.status === 400;
+    })),
     // ── user lookup ──────────────────────────────────────────────────────────────────────────────
     done('x.users.lookup_by_id', 'users', 'User lookup by id (GET /2/users/:id)', 'api', 'core', () => withWorld(async (h) => {
         const found = await h({ m: 'GET', p: `/2/users/${ORG}` });
@@ -1033,7 +1120,87 @@ export const X_CAPABILITIES = [
     todo('x.errors.text_length_weighting', 'errors', "X's WEIGHTED character count (CJK and emoji cost two, a URL counts 23) rather than the twin's plain code-point count", 'api', 'common'),
     todo('x.errors.duplicate_content', 'errors', "X's duplicate-content refusal for posting the same text twice", 'api', 'common'),
     todo('x.auth.app_only_bearer', 'auth', 'App-only (OAuth 2.0 client-credentials) bearer for the public read endpoints', 'api', 'common'),
-    todo('x.auth.oauth1_user_context', 'auth', "OAuth 1.0a user-context signing, X's alternate auth for these endpoints", 'api', 'niche'),
+    done('x.auth.oauth1_user_context', 'auth', "OAuth 1.0a User Context, X's alternate auth for these endpoints: a request signed with an access token xidentity issued posts and reads as that token's user", 'api', 'common', () => withWorld(async (h, root) => {
+        await seedOAuth1(root);
+        const posted = await h({ m: 'POST', p: '/2/tweets', b: { text: 'signed, not bearer' }, headers: { authorization: o1Header('POST', `${API}/2/tweets`) } });
+        const id = String(posted.body.data?.id ?? '');
+        // a read with a query: the query is part of what was signed
+        const q = `/2/tweets/${id}?tweet.fields=author_id`;
+        const read = await h({ m: 'GET', p: q, headers: { authorization: o1Header('GET', `${API}${q}`) } });
+        return posted.status === 201 && read.body.data?.author_id === ORG && read.body.data?.text === 'signed, not bearer';
+    })),
+    done('x.auth.oauth1_bad_signature_refuses', 'auth', 'An OAuth 1.0a signature made with the wrong consumer or token secret, or over another URL or query, is the about:blank 401 and writes nothing', 'api', 'core', () => withWorld(async (h, root) => {
+        await seedOAuth1(root);
+        const post = (authorization) => h({ m: 'POST', p: '/2/tweets', b: { text: 'forged' }, headers: { authorization } });
+        const wrongConsumer = await post(o1Header('POST', `${API}/2/tweets`, { ...O1_APP, secret: 'wrong' }));
+        const wrongToken = await post(o1Header('POST', `${API}/2/tweets`, O1_APP, { ...O1_TOKEN, secret: 'wrong' }));
+        const otherUrl = await post(o1Header('POST', `${API}/2/tweets/other`));
+        const q = `/2/users/by/username/orgvoice`;
+        const otherQuery = await h({ m: 'GET', p: `${q}?user.fields=description`, headers: { authorization: o1Header('GET', `${API}${q}`) } });
+        // a repeated key (X accepts none) and a query realm (signed like any parameter) do not ride on a valid signature
+        const signedQ = o1Header('GET', `${API}${q}?user.fields=description`);
+        const plainQ = await h({ m: 'GET', p: `${q}?user.fields=description`, headers: { authorization: signedQ } });
+        const dup = `${q}?user.fields=description&user.fields=description`;
+        const repeated = await h({ m: 'GET', p: dup, headers: { authorization: o1Header('GET', `${API}${dup}`) } });
+        const realm = await h({ m: 'GET', p: `${q}?user.fields=description&realm=x`, headers: { authorization: signedQ } });
+        const timeline = await h({ m: 'GET', p: `/2/users/${ORG}/tweets` });
+        return plainQ.status === 200 && [wrongConsumer, wrongToken, otherUrl, otherQuery, repeated, realm].every((r) => r.status === 401 && r.body.type === 'about:blank')
+            && timeline.body.meta?.result_count === 0;
+    })),
+    done('x.auth.oauth1_unissued_or_revoked_refuses', 'auth', 'An access token xidentity never issued, has revoked, or issued to another App is refused (401)', 'api', 'core', () => withWorld(async (h, root) => {
+        await seedOAuth1(root);
+        const revoked = { key: `${ORG}-RevokedAccessToken000000000000000000000000`, secret: 'RevokedSecret' };
+        await seedOAuth1(root, revoked, { revoked: true });
+        const other = { key: `${ORG}-OtherAppsToken00000000000000000000000000000`, secret: 'OtherSecret' };
+        await seedOAuth1(root, other, { consumerKey: 'SomeOtherApp' });
+        const post = (token) => h({ m: 'POST', p: '/2/tweets', b: { text: 'x' }, headers: { authorization: o1Header('POST', `${API}/2/tweets`, O1_APP, token) } });
+        const good = await post(O1_TOKEN);
+        return good.status === 201 && (await post({ key: `${ORG}-NeverIssued`, secret: O1_TOKEN.secret })).status === 401
+            && (await post(revoked)).status === 401 && (await post(other)).status === 401;
+    })),
+    done('x.auth.oauth1_read_only_permission', 'auth', 'A token from a Read-only App (or x_auth_access_type=read) reads but cannot post or upload: the 403 oauth1-permissions problem', 'api', 'common', () => withWorld(async (h, root) => {
+        await seedOAuth1(root, O1_TOKEN, { accessLevel: 'read' });
+        const q = '/2/users/by/username/orgvoice';
+        const read = await h({ m: 'GET', p: q, headers: { authorization: o1Header('GET', `${API}${q}`) } });
+        const post = await h({ m: 'POST', p: '/2/tweets', b: { text: 'read-only' }, headers: { authorization: o1Header('POST', `${API}/2/tweets`) } });
+        const upload = await h({ m: 'POST', p: '/2/media/upload/initialize', b: { media_type: 'video/mp4', total_bytes: 10, media_category: 'tweet_video' }, headers: { authorization: o1Header('POST', `${API}/2/media/upload/initialize`) } });
+        const isPermissions = (r) => r.status === 403 && r.body.type === 'https://api.twitter.com/2/problems/oauth1-permissions';
+        return read.status === 200 && read.body.data?.id === ORG && isPermissions(post) && isPermissions(upload);
+    })),
+    done('x.auth.oauth1_signed_host', 'auth', 'The signature covers the URL the client signed: https://api.x.com when the request names X\'s host (the injector keeps it), the twin\'s own origin when reached directly', 'api', 'common', () => withWorld(async (_h, root) => {
+        await seedOAuth1(root);
+        const fetchTwin = createXTwinFetch({ root });
+        const q = '/2/users/by/username/orgvoice';
+        const named = await fetchTwin(new Request(`http://127.0.0.1:9${q}`, { headers: { host: 'api.x.com', authorization: o1Header('GET', `https://api.x.com${q}`) } }));
+        const direct = await fetchTwin(new Request(`http://127.0.0.1:9${q}`, { headers: { authorization: o1Header('GET', `http://127.0.0.1:9${q}`) } }));
+        const mismatch = await fetchTwin(new Request(`http://127.0.0.1:9${q}`, { headers: { authorization: o1Header('GET', `https://api.x.com${q}`) } }));
+        return named.status === 200 && direct.status === 200 && mismatch.status === 401;
+    })),
+    done('x.auth.oauth1_world_app', 'auth', "The World's own App (X_API_KEY / X_API_SECRET the World sets) verifies a token issued to it; the same values from the caller's shell alone do not", 'api', 'common', () => withWorld(async (h, root) => {
+        const names = ['X_API_KEY', 'X_API_SECRET', 'VOLTER_WORLD_ENV_NAMES'];
+        const saved = Object.fromEntries(names.map((n) => [n, process.env[n]]));
+        const app = { key: 'WorldConsumerKey000000001', secret: 'WorldConsumerSecret0000000000000000000000000001' };
+        await applyTwinWrite('xidentity', { operation: 'oauth1_token.create', subjectType: 'oauth1_token', subjectId: O1_TOKEN.key, fields: { consumerKey: app.key, secret: O1_TOKEN.secret, userId: ORG, screenName: 'orgvoice', accessLevel: 'read-write', revoked: false }, occurredAt: '2026-02-01T00:00:00.000Z' }, root);
+        const post = () => h({ m: 'POST', p: '/2/tweets', b: { text: 'from the World app' }, headers: { authorization: o1Header('POST', `${API}/2/tweets`, app) } });
+        try {
+            Object.assign(process.env, { X_API_KEY: app.key, X_API_SECRET: app.secret });
+            delete process.env.VOLTER_WORLD_ENV_NAMES;
+            const shellOnly = await post();
+            process.env.VOLTER_WORLD_ENV_NAMES = JSON.stringify(['X_API_KEY', 'X_API_SECRET']);
+            const world = await post();
+            return shellOnly.status === 401 && world.status === 201;
+        }
+        finally {
+            for (const [n, v] of Object.entries(saved)) {
+                if (v === undefined)
+                    delete process.env[n];
+                else
+                    process.env[n] = v;
+            }
+        }
+    })),
+    todo('x.auth.oauth1_permissions_wording', 'auth', 'PIN the live 403 for a Read-only OAuth 1.0a token on a write endpoint (the twin serves the widely-reported oauth1-permissions problem)', 'api', 'niche'),
+    todo('x.auth.oauth1_timestamp_window', 'auth', "Refuse an OAuth 1.0a oauth_timestamp outside X's window and a replayed nonce", 'api', 'niche'),
     todo('x.auth.access_tier_gate', 'auth', "Access-tier gating (Free/Basic/Pro), which decides whether an endpoint exists for a token at all", 'api', 'common'),
     // ══ MIRROR (dimension: 'ui' — every one is DATA-COUPLED: seed through the handler, read the
     // SAME route the screen reads, render the mirror's OWN component over it) ══════════════════════

package/dist/src/x-oauth1.d.ts

@@ -0,0 +1,24 @@
+export type OAuth1User = {
+    userId: string;
+    token: string;
+    accessLevel: 'read' | 'read-write';
+};
+export declare const isOAuth1Header: (value: string | undefined) => boolean;
+/**
+ * The user a request signed with OAuth 1.0a acts for, or null: an unparseable header, a method
+ * other than HMAC-SHA1, a token xidentity never issued or has revoked, a token presented by another
+ * App, or a signature that does not verify over (method, the signed URL, query + oauth params) with
+ * `consumer_secret&token_secret`. A JSON or multipart body is not signed (the guide; twitter-api-v2
+ * signs a body only when it is form-encoded, and this surface has no form-encoded route).
+ */
+export declare function verifyOAuth1(req: {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    root?: string;
+    publicBase?: string;
+}): OAuth1User | null;
+/** OAuth 1.0a has no scopes: the App's permission level decides (docs.x.com developer-apps, "App
+ *  permissions (OAuth 1.0a)" — Read only: view; Read and write: also post and delete). As the OAuth
+ *  2.0 scopes those levels stand for on the routes this pack gates. */
+export declare function scopesOfAccessLevel(level: OAuth1User['accessLevel']): string[];

package/dist/src/x-oauth1.js

@@ -0,0 +1,145 @@
+// OAuth 1.0a User Context on the posting surface — X's alternate auth for these endpoints (every
+// operation this pack serves lists `UserToken` beside `OAuth2UserToken` in X's v2 OpenAPI), and the
+// one Postiz posts with (gitroomhq/postiz-app@374fb202334a x.provider.ts: twitter-api-v2 with
+// appKey/appSecret/accessToken/accessSecret, and its own `signOAuth1` for POST /2/tweets).
+//
+// ONE VENDOR, TWO PACKS. X has one credential store and `xidentity` is it: its three legs
+// (xidentity-oauth1.ts) mint the access token a person approved. This pack READS that store through
+// the kernel projection — `projectOwnerResources('xidentity', root)`, never a write — for exactly the two
+// row types that file names as the contract:
+//   oauth1_app   id=consumer key  { secret, name, callbackUrls, accessLevel: 'read'|'read-write', deleted? }
+//   oauth1_token id=access token  { consumerKey, secret, userId, screenName, accessLevel, revoked }
+// plus the World's own App from the env (worldOAuth1App there, transcribed below). A3 forbids the
+// import, so the RFC 5849 verifier is TRANSCRIBED from xidentity-oauth1.ts, as x-problems.ts and
+// x-scopes.ts transcribe theirs; the twitter-api-v2 test that spans both packs
+// (x-oauth1.integration.test.ts) goes red if the two drift apart.
+//
+// The token acts for its `userId`. That id is the X account in this pack's state too: a World that
+// posts as a person seeds the same account (id and handle) in both packs, as it seeds the one a
+// bearer from `/_twin/tokens` names.
+import { createHmac } from 'node:crypto';
+import { OwnerStoreAmbiguousError, projectOwnerResources, worldEnvValue } from '@volter/world-core';
+/** Constant-time equality of two same-length byte strings. Not node:crypto's timingSafeEqual: the
+ *  mirror's browser client bundles this module's chain, and Bun's browser polyfill has none. */
+function sameBytes(a, b) {
+    let difference = 0;
+    for (let i = 0; i < a.length; i++)
+        difference |= a[i] ^ b[i];
+    return difference === 0;
+}
+// ── RFC 5849, transcribed from xidentity-oauth1.ts (docs.x.com creating-a-signature) ─────────────
+const pct = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+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;
+}
+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('&'))}`;
+}
+const X_HOSTS = new Set(['api.x.com', 'api.twitter.com']);
+/** The URL the client signed: X's host when the request still names it (the injector keeps Host,
+ *  or names it in `x-volter-twin-original-host`), else where it was sent (`publicBase`), else — a
+ *  direct in-process call — X's own API origin. */
+function signedBaseUrl(headers, publicBase, path) {
+    const named = (headers['x-volter-twin-original-host'] ?? headers['host'] ?? '').toLowerCase().replace(/:\d+$/, '');
+    if (X_HOSTS.has(named))
+        return `https://${named}${path}`;
+    if (!publicBase)
+        return `https://api.x.com${path}`;
+    let u;
+    try {
+        u = new URL(publicBase);
+    }
+    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}`;
+}
+// ── the World's own App (transcribed from xidentity-oauth1.ts worldOAuth1App) ────────────────────
+const WORLD_APP_ENV = [['X_API_KEY', 'X_API_SECRET'], ['TWITTER_API_KEY', 'TWITTER_API_SECRET']];
+function consumerSecretOf(identity, consumerKey) {
+    const row = identity.find((r) => r.type === 'oauth1_app' && String(r.id) === consumerKey);
+    if (row && row.deleted !== true)
+        return String(row.secret);
+    for (const [keyName, secretName] of WORLD_APP_ENV) {
+        const key = worldEnvValue(keyName);
+        const secret = worldEnvValue(secretName);
+        if (key && secret)
+            return key === consumerKey ? secret : undefined;
+    }
+    return undefined;
+}
+export const isOAuth1Header = (value) => /^OAuth\s/i.test((value ?? '').trim());
+/**
+ * The user a request signed with OAuth 1.0a acts for, or null: an unparseable header, a method
+ * other than HMAC-SHA1, a token xidentity never issued or has revoked, a token presented by another
+ * App, or a signature that does not verify over (method, the signed URL, query + oauth params) with
+ * `consumer_secret&token_secret`. A JSON or multipart body is not signed (the guide; twitter-api-v2
+ * signs a body only when it is form-encoded, and this surface has no form-encoded route).
+ */
+export function verifyOAuth1(req) {
+    const header = parseOAuthHeader(req.headers['authorization'] ?? Object.entries(req.headers).find(([k]) => k.toLowerCase() === 'authorization')?.[1]);
+    if (!header)
+        return null;
+    const oauth = new Map(header);
+    if (oauth.get('oauth_signature_method') !== 'HMAC-SHA1' || (oauth.has('oauth_version') && oauth.get('oauth_version') !== '1.0'))
+        return null;
+    for (const k of ['oauth_consumer_key', 'oauth_nonce', 'oauth_signature', 'oauth_timestamp', 'oauth_token'])
+        if (!oauth.get(k))
+            return null;
+    let identity;
+    try {
+        // the store that issued this token (a World running xidentity twice: the one holding it)
+        identity = projectOwnerResources('xidentity', req.root, { type: 'oauth1_token', id: String(oauth.get('oauth_token')) });
+    }
+    catch (error) {
+        if (error instanceof OwnerStoreAmbiguousError)
+            return null; // two stores issued it: not a token this World can resolve
+        throw error;
+    }
+    const token = identity.find((r) => r.type === 'oauth1_token' && String(r.id) === oauth.get('oauth_token'));
+    if (!token || token.revoked === true || token.consumerKey !== oauth.get('oauth_consumer_key'))
+        return null;
+    const consumerSecret = consumerSecretOf(identity, String(token.consumerKey));
+    if (consumerSecret === undefined)
+        return null;
+    const [p, q = ''] = req.path.split('?');
+    const query = [...new URLSearchParams(q).entries()];
+    // X accepts no duplicate keys (creating-a-signature footnote 2); only the header's realm is unsigned (RFC 5849 §3.4.1.3.1)
+    if (new Set(query.map(([k]) => k)).size !== query.length)
+        return null;
+    const pairs = [...header.filter(([k]) => k !== 'realm'), ...query].filter(([k]) => k !== 'oauth_signature');
+    const base = baseString(req.method, signedBaseUrl(req.headers, req.publicBase, p ?? '/'), pairs);
+    const expected = Buffer.from(createHmac('sha1', `${pct(consumerSecret)}&${pct(String(token.secret))}`).update(base).digest('base64'));
+    const given = Buffer.from(oauth.get('oauth_signature'));
+    if (expected.length !== given.length || !sameBytes(expected, given))
+        return null;
+    return { userId: String(token.userId), token: String(token.id), accessLevel: token.accessLevel === 'read' ? 'read' : 'read-write' };
+}
+/** OAuth 1.0a has no scopes: the App's permission level decides (docs.x.com developer-apps, "App
+ *  permissions (OAuth 1.0a)" — Read only: view; Read and write: also post and delete). As the OAuth
+ *  2.0 scopes those levels stand for on the routes this pack gates. */
+export function scopesOfAccessLevel(level) {
+    return level === 'read' ? ['tweet.read', 'users.read'] : ['tweet.read', 'users.read', 'tweet.write', 'media.write'];
+}

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

@@ -7,6 +7,13 @@ export type XResponse = {
 export declare function unauthorizedProblem(): XResponse;
 /** A user token whose scope set does not cover the endpoint. Wording: `x.errors.scope_wording`. */
 export declare function forbiddenProblem(detail: string): XResponse;
+/**
+ * An OAuth 1.0a token whose App permission does not reach the endpoint (a Read-only token posting).
+ * X's v2 answers this with its own problem type rather than the scope wording: the type and detail
+ * are the widely-reported wire strings, not a fetched page — EXTRAPOLATION, pinned by
+ * `x.auth.oauth1_permissions_wording`.
+ */
+export declare function oauth1PermissionsProblem(): XResponse;
 /** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
 export declare function notFoundProblem(): XResponse;
 /**

package/dist/src/x-problems.js

@@ -45,6 +45,24 @@ export function forbiddenProblem(detail) {
         headers: { ...PROBLEM },
     };
 }
+/**
+ * An OAuth 1.0a token whose App permission does not reach the endpoint (a Read-only token posting).
+ * X's v2 answers this with its own problem type rather than the scope wording: the type and detail
+ * are the widely-reported wire strings, not a fetched page — EXTRAPOLATION, pinned by
+ * `x.auth.oauth1_permissions_wording`.
+ */
+export function oauth1PermissionsProblem() {
+    return {
+        status: 403,
+        body: {
+            title: 'Forbidden',
+            type: 'https://api.twitter.com/2/problems/oauth1-permissions',
+            status: 403,
+            detail: 'Your client app is not configured with the appropriate oauth1 app permissions for this endpoint.',
+        },
+        headers: { ...PROBLEM },
+    };
+}
 /** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
 export function notFoundProblem() {
     return {

package/dist/src/x-server.js

@@ -54,6 +54,54 @@ function bytesResponse(request, bytes, contentType) {
         headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
     });
 }
+/**
+ * An RFC 7578 multipart body, read as BYTES. The `media` part is binary whether or not its
+ * disposition names a filename: twitter-api-v2@1.29.1's FormDataHelper — what Postiz's
+ * `client.v2.uploadMedia` sends each APPEND with — writes `Content-Disposition: form-data;
+ * name="media"` and `Content-Type: application/octet-stream` with NO filename, and a WHATWG
+ * `formData()` parse turns such a part into a UTF-8-decoded string, corrupting the bytes. Every other
+ * part is a text field. Null when the body is not the multipart its content type declares.
+ */
+function parseMultipart(body, contentType) {
+    const b = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
+    if (!b)
+        return null;
+    const boundary = b[1] ?? b[2];
+    const buf = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    // A delimiter is CRLF "--boundary" (RFC 2046 §5.1.1); the first may open the body with no CRLF
+    // before it, anything ahead of it is preamble. A boundary string not at a line start is content.
+    const delimiter = Buffer.from(`\r\n--${boundary}`);
+    const first = Buffer.from(`--${boundary}`);
+    let pos = buf.subarray(0, first.length).equals(first) ? first.length : (() => { const i = buf.indexOf(delimiter); return i < 0 ? -1 : i + delimiter.length; })();
+    if (pos < 0)
+        return null;
+    const fields = {};
+    let media;
+    for (;;) {
+        if (buf[pos] === 0x2d && buf[pos + 1] === 0x2d)
+            break; // the closing delimiter
+        while (buf[pos] === 0x20 || buf[pos] === 0x09)
+            pos += 1; // transport padding
+        if (buf[pos] !== 0x0d || buf[pos + 1] !== 0x0a)
+            return null;
+        const headEnd = buf.indexOf('\r\n\r\n', pos + 2);
+        if (headEnd < 0)
+            return null;
+        const head = buf.subarray(pos + 2, headEnd).toString('utf8');
+        const next = buf.indexOf(delimiter, headEnd + 2);
+        if (next < 0)
+            return null;
+        const content = buf.subarray(Math.min(headEnd + 4, next), next);
+        const disposition = head.split('\r\n').find((line) => /^content-disposition\s*:/i.test(line)) ?? '';
+        const name = /;\s*name="([^"]*)"/i.exec(disposition)?.[1];
+        if (name === 'media')
+            media = new Uint8Array(content);
+        else if (name !== undefined)
+            fields[name] = content.toString('utf8');
+        pos = next + delimiter.length;
+    }
+    return { fields, ...(media ? { media } : {}) };
+}
 export function createXTwinFetch(options = {}) {
     const adapted = createTwinFetchFromHandler(handleXTwinRequest, {
         ...options,
@@ -83,21 +131,11 @@ export function createXTwinFetch(options = {}) {
         }
         const type = request.headers.get('content-type') ?? '';
         if (request.method === 'POST' && MULTIPART_UPLOAD_PATH.test(url.pathname) && /^multipart\/form-data/i.test(type)) {
-            let form;
-            try {
-                form = await request.formData();
-            }
-            catch {
+            const parsed = parseMultipart(new Uint8Array(await request.arrayBuffer()), type);
+            if (!parsed) {
                 return Response.json({ errors: [{ parameters: { body: ['(unparseable)'] }, message: 'The multipart body could not be parsed.' }], title: 'Invalid Request', detail: 'One or more parameters to your request was invalid.', type: 'https://api.x.com/2/problems/invalid-request' }, { status: 400 });
             }
-            const fields = {};
-            let media;
-            for (const [name, value] of form.entries()) {
-                if (typeof value === 'string')
-                    fields[name] = value;
-                else if (name === 'media' && value instanceof Blob)
-                    media = new Uint8Array(await value.arrayBuffer());
-            }
+            const { fields, media } = parsed;
             const headers = {};
             request.headers.forEach((value, key) => { headers[key] = value; });
             const invoke = () => handleXTwinRequest({

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

@@ -18,4 +18,8 @@ export type XRequest = {
      *  is minted from it; a direct handler call with none mints X's own pbs.twimg.com form. */
     publicBase?: string;
 };
+/** The picture X shows for an account that never uploaded one: every X account has a
+ *  `profile_image_url`, and this is its value until the person sets a photo. The twin serves the
+ *  URL, not the bytes (it claims no abs.twimg.com), as it serves no profile photos at all. */
+export declare const X_DEFAULT_PROFILE_IMAGE_URL = "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png";
 export declare function handleXTwinRequest(request: XRequest): Promise<XResponse>;