@volter/twin-x 0.1.0 → 0.1.1

package/dist/src/x-twin.js

@@ -35,16 +35,18 @@
 // default projection is the vendor's three fields, and `projectPost` is the ONE place a stored
 // post becomes a response body.
 //
-// AUTH. OAuth 2.0 is xidentity's and stays there. This pack CONSUMES the user access token that
-// flow mints: a bearer, opaque, scope-carrying. `/_twin/tokens` registers one locally, which is
-// what a world does instead of running the authorize leg for every test.
+// AUTH. OAuth is xidentity's and stays there. This pack CONSUMES what it mints: an OAuth 2.0 user
+// bearer — opaque, scope-carrying; `/_twin/tokens` registers one locally, which is what a world
+// does instead of running the authorize leg for every test — or an OAuth 1.0a User Context
+// signature over an access token xidentity's three legs issued (x-oauth1.ts).
 //
 // DETERMINISM. Every served response is a pure function of (request, stored state). Nothing on
 // the read path reads a clock: `created_at` is what the WRITE stored, and the `next_token` a page
 // hands back is derived from the id of the last row on that page, never from entropy or time.
-import { applyTwinWrite, projectResources } from '@volter/world-core';
-import { forbiddenProblem, invalidRequestProblem, lookupResult, notFoundProblem, rateLimitExceeded, readOnlyRefusal, resourceNotFoundError, resourceNotFoundProblem, unauthorizedProblem, } from "./x-problems.js";
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
+import { forbiddenProblem, invalidRequestProblem, lookupResult, notFoundProblem, oauth1PermissionsProblem, rateLimitExceeded, readOnlyRefusal, resourceNotFoundError, resourceNotFoundProblem, unauthorizedProblem, } from "./x-problems.js";
 import { missingScopes, parseScopeList, REQUIRED_SCOPES } from "./x-scopes.js";
+import { isOAuth1Header, scopesOfAccessLevel, verifyOAuth1 } from "./x-oauth1.js";
 import { clearSegments, listMediaIds, MAX_IMAGE_BYTES, MAX_TWEET_VIDEO_MS, MAX_VIDEO_BYTES, MEDIA_EXPIRES_AFTER_SECS, mediaExtension, putSegment, putXBlob, readMediaRecord, readSegments, sniffImage, sniffVideo, writeMediaRecord, } from "./x-media.js";
 const SERVICE = 'x';
 /** X's post ids are snowflakes. A minted id must never collide with one PULLED from the real
@@ -112,7 +114,17 @@ function bearerFrom(headers) {
     }
     return undefined;
 }
-function authorize(all, headers) {
+function authorize(all, request) {
+    const headers = request.headers;
+    const authorization = headers ? Object.entries(headers).find(([k]) => k.toLowerCase() === 'authorization')?.[1] : undefined;
+    if (isOAuth1Header(authorization)) {
+        // X's alternate scheme for every route here: a request signed with an access token the
+        // person approved at xidentity's screen. Anything that does not verify is the same 401.
+        const user = verifyOAuth1({ method: request.method, path: request.path, headers: headers ?? {}, root: request.root, publicBase: request.publicBase });
+        if (!user)
+            return unauthorizedProblem();
+        return { accountId: user.userId, scopes: scopesOfAccessLevel(user.accessLevel), token: user.token, oauth1: true };
+    }
     const token = bearerFrom(headers);
     if (!token)
         return unauthorizedProblem();
@@ -126,6 +138,8 @@ function scopeRefusal(auth, operation) {
     const missing = missingScopes(auth.scopes, REQUIRED_SCOPES[operation]);
     if (missing.length === 0)
         return undefined;
+    if (auth.oauth1)
+        return oauth1PermissionsProblem();
     return forbiddenProblem(`This request requires the ${missing.join(', ')} scope(s), which this token does not hold.`);
 }
 // ── tweet.fields / expansions: the projection X actually serves ──────────────────────────────
@@ -196,8 +210,12 @@ const USER_FIELDS_DOCUMENTED = new Set([
  *  which is a pure function of the account's live posts. `public_metrics` is NOT here: two of its
  *  counts (listed, like) have no state behind them, and a zero the twin cannot know is a fabrication. */
 const USER_FIELDS_MODELLED = new Set([
-    'created_at', 'description', 'id', 'location', 'most_recent_tweet_id', 'name', 'protected', 'url', 'username', 'verified',
+    'created_at', 'description', 'id', 'location', 'most_recent_tweet_id', 'name', 'profile_image_url', 'protected', 'url', 'username', 'verified',
 ]);
+/** 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 const X_DEFAULT_PROFILE_IMAGE_URL = 'https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png';
 /** Read `user.fields` off the query string, refusing the way `tweet.fields` refuses. */
 function parseUserFields(url) {
     const userFields = new Set();
@@ -328,6 +346,9 @@ function projectUser(account, userFields, all) {
         out.location = account.location;
     if (userFields.has('url'))
         out.url = typeof account.url === 'string' ? account.url : '';
+    if (userFields.has('profile_image_url')) {
+        out.profile_image_url = typeof account.profile_image_url === 'string' && account.profile_image_url !== '' ? account.profile_image_url : X_DEFAULT_PROFILE_IMAGE_URL;
+    }
     if (userFields.has('protected'))
         out.protected = account.protected === true;
     if (userFields.has('verified'))
@@ -614,6 +635,13 @@ const POST_FIELDS_UNMODELLED = new Set([
     'nullcast', 'paid_partnership', 'poll', 'reply_settings', 'share_with_followers',
 ]);
 const REPLY_FIELDS_UNMODELLED = new Set(['exclude_reply_user_ids', 'auto_populate_reply_metadata']);
+/** The two disclosure labels, when they label nothing. `made_with_ai` ("this post contains AI-generated
+ *  media") and `paid_partnership` ("this post is a paid partnership") are booleans whose `false` is the
+ *  post every create here already makes, unlabelled; Postiz sends both on every post and reply, `false`
+ *  unless the person ticked the box (x.provider.ts, `assetBoolean(...) || false`). `false` is read as the
+ *  absent value it is; `true` — a label this twin does not store or show — stays refused by name, and
+ *  so does a non-boolean. */
+const POST_DISCLOSURE_FIELDS = new Set(['made_with_ai', 'paid_partnership']);
 /** A post id in a request body: a STRING matching ^[0-9]{1,19}$, as the schema types it. */
 function postIdField(value, parameter) {
     if (typeof value !== 'string' || !/^\d{1,19}$/.test(value)) {
@@ -625,6 +653,11 @@ async function createPost(request, all, auth, payload) {
     for (const key of Object.keys(payload)) {
         if (POST_FIELDS_MODELLED.has(key))
             continue;
+        if (POST_DISCLOSURE_FIELDS.has(key) && payload[key] === false)
+            continue;
+        if (POST_DISCLOSURE_FIELDS.has(key) && payload[key] !== true) {
+            return invalidRequestProblem({ [key]: [JSON.stringify(payload[key])] }, `The \`${key}\` field must be a boolean.`);
+        }
         if (POST_FIELDS_UNMODELLED.has(key))
             return unmodelledOption(key, JSON.stringify(payload[key]));
         return invalidRequestProblem({ [key]: [JSON.stringify(payload[key])] }, `The \`${key}\` field is not a parameter of this request.`);
@@ -698,7 +731,7 @@ async function createPost(request, all, auth, payload) {
     }
     // a post's id is the snowflake high-water mark + 1: timelines, since_id and pagination order by it
     const id = mintSnowflakeId(all, await listMediaIds(request.root));
-    const createdAt = request.occurredAt ?? new Date().toISOString();
+    const createdAt = request.occurredAt ?? worldNow();
     await applyTwinWrite(SERVICE, {
         operation: isReply ? 'x.post.reply' : isQuote ? 'x.post.quote' : 'x.post.create',
         subjectType: 'post',
@@ -738,7 +771,7 @@ async function deletePost(request, all, auth, id) {
         subjectType: 'post',
         subjectId: id,
         fields: { ...Object.fromEntries(Object.entries(post).filter(([k]) => k !== 'type' && k !== 'id' && k !== 'updatedAt')), deleted: true },
-        occurredAt: request.occurredAt ?? new Date().toISOString(),
+        occurredAt: request.occurredAt ?? worldNow(),
         actor: { kind: 'agent', id: auth.accountId },
     }, request.root);
     return ok({ data: { deleted: true } });
@@ -785,7 +818,7 @@ const INVALID_MEDIA_IDS = 'Your media IDs are invalid.';
 const CHECK_AFTER_SECS = 1;
 const isVideoCategory = (category) => VIDEO_CATEGORIES.has(category);
 function nowSeconds(request) {
-    return Math.floor(Date.parse(request.occurredAt ?? new Date().toISOString()) / 1000);
+    return Math.floor(Date.parse(request.occurredAt ?? worldNow()) / 1000);
 }
 /** A field of the upload body, from the multipart form or the JSON object. */
 function uploadField(request, payload, name) {
@@ -952,7 +985,7 @@ async function uploadMedia(request, all, auth, payload) {
     const opened = {
         id, media_key: mediaKeyFor(category, id), account_id: auth.accountId, media_category: category, media_type: 'application/octet-stream', state: 'initialized',
         ...(owners.length > 0 ? { additional_owners: owners } : {}),
-        created_at: request.occurredAt ?? new Date().toISOString(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
+        created_at: request.occurredAt ?? worldNow(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
     };
     // Check before storing: a refused image leaves no bytes behind.
     const checked = finishUpload(opened, bytes, '');
@@ -997,7 +1030,7 @@ async function initializeUpload(request, all, auth, payload) {
     const record = {
         id, media_key: mediaKeyFor(category, id), account_id: auth.accountId, media_category: category, media_type: mediaType, state: 'initialized', total_bytes: total,
         ...(owners.length > 0 ? { additional_owners: owners } : {}),
-        created_at: request.occurredAt ?? new Date().toISOString(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
+        created_at: request.occurredAt ?? worldNow(), expires_at: nowSeconds(request) + MEDIA_EXPIRES_AFTER_SECS,
     };
     await writeMediaRecord(record, request.root);
     return ok({ data: { id, media_key: record.media_key, expires_after_secs: MEDIA_EXPIRES_AFTER_SECS } });
@@ -1334,6 +1367,13 @@ async function handleTwinControl(request, all, path, payload) {
                 return invalidRequestProblem({ [key]: [String(payload[key])] }, `A seeded account's \`${key}\` must be a string.`);
             profile[key] = payload[key];
         }
+        // A photo the person uploaded: X serves it from pbs.twimg.com/profile_images/…, an https URL.
+        if (payload.profile_image_url !== undefined) {
+            if (typeof payload.profile_image_url !== 'string' || !/^https:\/\/\S+$/.test(payload.profile_image_url)) {
+                return invalidRequestProblem({ profile_image_url: [String(payload.profile_image_url)] }, "A seeded account's `profile_image_url` must be an https URL.");
+            }
+            profile.profile_image_url = payload.profile_image_url;
+        }
         for (const key of ['protected', 'verified']) {
             if (payload[key] === undefined)
                 continue;
@@ -1341,7 +1381,7 @@ async function handleTwinControl(request, all, path, payload) {
                 return invalidRequestProblem({ [key]: [String(payload[key])] }, `A seeded account's \`${key}\` must be a boolean.`);
             profile[key] = payload[key];
         }
-        const createdAt = request.occurredAt ?? new Date().toISOString();
+        const createdAt = request.occurredAt ?? worldNow();
         await applyTwinWrite(SERVICE, {
             operation: 'x.twin.seed_account',
             subjectType: 'account',
@@ -1365,7 +1405,7 @@ async function handleTwinControl(request, all, path, payload) {
             subjectType: 'token',
             subjectId: token,
             fields: { account_id: accountId, scopes },
-            occurredAt: request.occurredAt ?? new Date().toISOString(),
+            occurredAt: request.occurredAt ?? worldNow(),
         }, request.root);
         return ok({ data: { token, account_id: accountId, scopes } });
     }
@@ -1378,7 +1418,7 @@ async function handleTwinControl(request, all, path, payload) {
             return invalidRequestProblem({ author_id: [String(authorId ?? '')] }, 'A seeded post must name an account seeded through /_twin/accounts.');
         }
         const id = mintSnowflakeId(all);
-        const createdAt = request.occurredAt ?? new Date().toISOString();
+        const createdAt = request.occurredAt ?? worldNow();
         await applyTwinWrite(SERVICE, {
             operation: 'x.twin.seed_post',
             subjectType: 'post',
@@ -1405,7 +1445,7 @@ async function handleTwinControl(request, all, path, payload) {
             subjectType: 'follow',
             subjectId: `${followerId}:${followedId}`,
             fields: { follower_id: followerId, followed_id: followedId },
-            occurredAt: request.occurredAt ?? new Date().toISOString(),
+            occurredAt: request.occurredAt ?? worldNow(),
         }, request.root);
         return ok({ data: { follower_id: followerId, followed_id: followedId } });
     }
@@ -1418,7 +1458,7 @@ async function handleTwinControl(request, all, path, payload) {
             subjectType: 'rate_limit',
             subjectId: 'armed',
             fields: { armed: payload.armed !== false, reset: resetAt, limit: typeof payload.limit === 'number' ? payload.limit : 200 },
-            occurredAt: request.occurredAt ?? new Date().toISOString(),
+            occurredAt: request.occurredAt ?? worldNow(),
         }, request.root);
         return ok({ data: { armed: payload.armed !== false, reset: resetAt } });
     }
@@ -1469,7 +1509,7 @@ export async function handleXTwinRequest(request) {
     const refusal = armedRateRefusal(all);
     if (refusal)
         return refusal;
-    const auth = authorize(all, request.headers);
+    const auth = authorize(all, request);
     if (isResponse(auth))
         return auth;
     const publicBase = (request.publicBase ?? PBS_BASE).replace(/\/+$/, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-x",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local X (Twitter) API v2 twin (post, reply, delete, timelines, user lookup) with an x.com mirror, built on @volter/world-core.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
@@ -36,14 +36,14 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.1"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.1",
     "@volter/world-tooling": "0.1.0",
     "twitter-api-v2": "^1.29.1",
     "typescript": "^5.9.0"

package/src/index.ts

@@ -79,11 +79,13 @@ import { X_RATE_BUDGET as RATE_BUDGET } from './x-budget.ts';
  * 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: TwinPack = {
   vendor: 'x',

package/src/x-capabilities.ts

@@ -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, type CapabilityReport, type CapabilitySpec, verifyBo
 import { pushXAction, xRequestForAction, syncXFromReal, type XExecute } from './x-connector.ts';
 import { X_BUDGET_CEILING, X_CALL_WEIGHTS, X_RATE_BUDGET, XBudget, XBudgetError, xCallWeight } from './x-budget.ts';
 import { handleXTwinRequest } from './x-twin.ts';
+import { createXTwinFetch } from './x-server.ts';
+import { applyTwinWrite } from '@volter/world-core';
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { PostRow, ProfileHeader } from '../client/x-mirror.tsx';
@@ -107,6 +110,31 @@ async function mediaToken(h: Handle): Promise<void> {
   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: string, token = O1_TOKEN, fields: Record<string, unknown> = {}): Promise<void> {
+  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: string, url: string, app = O1_APP, token = O1_TOKEN): string {
+  const enc = (v: string) => encodeURIComponent(v).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+  const [base, query = ''] = url.split('?');
+  const oauth: Record<string, string> = { 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: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
   ({ id, area, title, dimension, tier, expected: 'done', verify });
 const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
@@ -117,6 +145,28 @@ export const X_CAPABILITIES: CapabilitySpec[] = [
   // 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 as Body).data?.id ?? '');
+      const boundary = '----twinverify';
+      const part = (head: string, bytes: Uint8Array) => 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 as Body).data?.id)}?expansions=attachments.media_keys&media.fields=width,height,url`, headers: MEDIA_AUTH });
+      const media = (read.body as 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);
@@ -190,6 +240,33 @@ export const X_CAPABILITIES: CapabilitySpec[] = [
         && 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 as Body).data?.id as string;
+      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 as Body).data?.id as string;
+      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 as 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 as 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 as 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 as Body).errors?.[0];
+      const stringlyError = (stringly.body as 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: string[] = [];
@@ -404,6 +481,23 @@ export const X_CAPABILITIES: CapabilitySpec[] = [
         && 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 as Body).data;
+      const plain = ((await h({ m: 'GET', p: '/2/users/3101?user.fields=profile_image_url' })).body as Body).data;
+      const bare = ((await h({ m: 'GET', p: '/2/users/3100' })).body as 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) => {
@@ -1087,7 +1181,87 @@ export const X_CAPABILITIES: CapabilitySpec[] = [
   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 as 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 as Body).data?.author_id === ORG && (read.body as 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: string) => 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 as Body).type === 'about:blank')
+        && (timeline.body as 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: { key: string; secret: string }) => 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: { status: number; body: unknown }) => r.status === 403 && (r.body as Body).type === 'https://api.twitter.com/2/problems/oauth1-permissions';
+      return read.status === 200 && (read.body as 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/src/x-oauth1.ts

@@ -0,0 +1,138 @@
+// 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: Uint8Array, b: Uint8Array): boolean {
+  let difference = 0;
+  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
+  return difference === 0;
+}
+
+type Row = Record<string, any>;
+
+// ── RFC 5849, transcribed from xidentity-oauth1.ts (docs.x.com creating-a-signature) ─────────────
+
+const pct = (s: string): string =>
+  encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+function parseOAuthHeader(value: string | undefined): Array<[string, string]> | null {
+  if (!value) return null;
+  const m = /^OAuth\s+(.*)$/is.exec(value.trim());
+  if (!m) return null;
+  const out: Array<[string, string]> = [];
+  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: string, baseUrl: string, pairs: Array<[string, string]>): string {
+  const encoded = pairs.map(([k, v]) => [pct(k), pct(v)] as const).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: Record<string, string>, publicBase: string | undefined, path: string): string {
+  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: URL;
+  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: ReadonlyArray<readonly [string, string]> = [['X_API_KEY', 'X_API_SECRET'], ['TWITTER_API_KEY', 'TWITTER_API_SECRET']];
+
+function consumerSecretOf(identity: Row[], consumerKey: string): string | undefined {
+  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;
+}
+
+// ── the check ────────────────────────────────────────────────────────────────────────────────────
+
+export type OAuth1User = { userId: string; token: string; accessLevel: 'read' | 'read-write' };
+
+export const isOAuth1Header = (value: string | undefined): boolean => /^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: { method: string; path: string; headers: Record<string, string>; root?: string; publicBase?: string }): OAuth1User | null {
+  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: Row[];
+  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')) }) as unknown as Row[];
+  } 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: OAuth1User['accessLevel']): string[] {
+  return level === 'read' ? ['tweet.read', 'users.read'] : ['tweet.read', 'users.read', 'tweet.write', 'media.write'];
+}