@volter/twin-x 0.1.0

package/dist/src/x-problems.js

@@ -0,0 +1,130 @@
+// X API v2 error envelopes for the POSTING surface.
+//
+// TRANSCRIBED, NOT SHARED. `packages/twin/xidentity/src/xidentity-problems.ts` already models
+// X's error families for the identity surface, and two packs disagreeing about one vendor's
+// error shape would be worse than one pack. The architecture guardrail forbids a cross-vendor
+// pack import (`scripts/architecture.test.ts`, A3: "does not import another vendor pack"), so
+// the agreement is kept by TRANSCRIPTION and stated here, at the seam, rather than by a shared
+// module: every envelope below is byte-identical in shape to the xidentity function named beside
+// it. If X's error shape is ever re-grounded, both files move together.
+//
+// The families this surface can produce (numbering follows xidentity-problems.ts):
+//
+//   2. v2 problem envelopes — the OpenAPI 2.167 `Problem` family, discriminated by a `type`
+//      URL. The generic auth failure is the `about:blank` form.
+//      (xidentity: `unauthorizedProblem` / `forbiddenProblem` / `notFoundProblem`.)
+//   3. the request-level invalid-parameter envelope `{errors:[{parameters,message}], title,
+//      detail, type: …/invalid-request}` — the OpenAPI's InvalidRequestProblem.
+//      (xidentity: `invalidRequestProblem`.)
+//   4. the 15-minute-window rate refusal: HTTP 429 with legacy error code 88.
+//      (xidentity: `rateLimitExceeded`.)
+//
+// Family 1 (the RFC 6749 token-endpoint body) cannot arise here: OAuth is xidentity's and stays
+// there. This pack consumes the bearer token that flow produces; it never mints one.
+//
+// EVIDENCE BOUNDARY. Shapes are the OpenAPI 2.167 `Problem` family as recorded in
+// spec-sources.json's xidentity entry (live-fetched 2026-08-21). Exact wire WORDING for the
+// posting surface's refusals was not captured from an official artefact by this build — no X
+// call is made anywhere in this pack — so each string that is not shape-forced is filed as a
+// pinning todo in the manifest (`x.errors.*_wording`) rather than claimed pinned.
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+const PROBLEM = { ...NOSTORE, 'content-type': 'application/problem+json' };
+/** The generic auth problem X answers a bad/absent/expired bearer with on /2 resources. */
+export function unauthorizedProblem() {
+    return {
+        status: 401,
+        body: { title: 'Unauthorized', type: 'about:blank', status: 401, detail: 'Unauthorized' },
+        headers: { ...PROBLEM },
+    };
+}
+/** A user token whose scope set does not cover the endpoint. Wording: `x.errors.scope_wording`. */
+export function forbiddenProblem(detail) {
+    return {
+        status: 403,
+        body: { title: 'Forbidden', type: 'about:blank', status: 403, detail },
+        headers: { ...PROBLEM },
+    };
+}
+/** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
+export function notFoundProblem() {
+    return {
+        status: 404,
+        body: { title: 'Not Found Error', type: 'about:blank', status: 404, detail: 'Not Found' },
+        headers: { ...PROBLEM },
+    };
+}
+/**
+ * A named resource the request addressed does not exist — X's `resource-not-found` problem,
+ * which carries the offending value/resource_type rather than the bare about:blank form.
+ * Wording pinned by `x.errors.resource_not_found_wording`.
+ */
+export function resourceNotFoundError(value, resourceType, parameter) {
+    return {
+        parameter,
+        resource_id: value,
+        value,
+        detail: `Could not find ${resourceType} with ${parameter}: [${value}].`,
+        title: 'Not Found Error',
+        resource_type: resourceType,
+        type: 'https://api.twitter.com/2/problems/resource-not-found',
+    };
+}
+export function resourceNotFoundProblem(value, resourceType, parameter) {
+    return {
+        status: 404,
+        body: { errors: [resourceNotFoundError(value, resourceType, parameter)] },
+        headers: { ...NOSTORE, 'content-type': 'application/json' },
+    };
+}
+/**
+ * THE LOOKUP ENVELOPE, and why its status differs from the refusal above. X's *lookup* endpoints
+ * (`GET /2/tweets`, `GET /2/tweets/:id`) answer PARTIALLY: a request for five ids where two are
+ * missing has to return the three that exist AND say what happened to the other two, so the
+ * missing ones ride in a sibling `errors` array under HTTP 200 rather than turning the whole
+ * request into a 404. The bulk route FORCES that model — there is no other way to express a
+ * partial result — and X applies the same envelope to the single-id route. What matters for this
+ * twin, and what its verifies assert, is the half that is not a status: a `data` entry is NEVER
+ * fabricated for an id nobody created; the id comes back inside `errors`, by name.
+ *
+ * The exact `detail`/`title` WORDING is unpinned by this build, same boundary as every other
+ * envelope here (`x.errors.resource_not_found_wording`).
+ */
+export function lookupResult(data, errors, includes) {
+    const body = {};
+    if (data !== undefined)
+        body.data = data;
+    if (includes !== undefined && Object.keys(includes).length > 0)
+        body.includes = includes;
+    if (errors.length > 0)
+        body.errors = errors;
+    return { status: 200, body, headers: { ...NOSTORE, 'content-type': 'application/json' } };
+}
+/** The invalid-parameter envelope (OpenAPI InvalidRequestProblem + the wire's `errors` array). */
+export function invalidRequestProblem(parameters, message) {
+    return {
+        status: 400,
+        body: {
+            errors: [{ parameters, message }],
+            title: 'Invalid Request',
+            detail: 'One or more parameters to your request was invalid.',
+            type: 'https://api.x.com/2/problems/invalid-request',
+        },
+        headers: { ...NOSTORE, 'content-type': 'application/json' },
+    };
+}
+/** HTTP 429, legacy code 88 — the documented pair (docs.x.com fundamentals/rate-limits). */
+export function rateLimitExceeded(headers) {
+    return {
+        status: 429,
+        body: { errors: [{ code: 88, message: 'Rate limit exceeded' }] },
+        headers: { ...NOSTORE, ...headers, 'content-type': 'application/json' },
+    };
+}
+/** A write attempted against a read-only twin. Not a vendor shape — the kernel's own refusal. */
+export function readOnlyRefusal() {
+    return {
+        status: 405,
+        body: { title: 'Method Not Allowed', type: 'about:blank', status: 405, detail: 'This twin is running read-only; writes are refused.' },
+        headers: { ...PROBLEM },
+    };
+}

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

@@ -0,0 +1,7 @@
+/** The subset of X's scope catalog the posting surface can require, with X's own consent wording. */
+export declare const X_SCOPES: Record<string, string>;
+/** Space-separated scope param → ordered unique scope list (X formats scope space-separated). */
+export declare function parseScopeList(raw: string | null | undefined): string[];
+/** The scopes a token must hold for one modelled operation, from the OpenAPI's `security` entry. */
+export declare const REQUIRED_SCOPES: Record<'tweets.create' | 'tweets.reply' | 'tweets.delete' | 'mentions.list' | 'tweets.lookup' | 'timelines.read' | 'search.recent' | 'users.lookup' | 'media.upload', readonly string[]>;
+export declare function missingScopes(held: readonly string[], required: readonly string[]): string[];

package/dist/src/x-scopes.js

@@ -0,0 +1,62 @@
+// The X OAuth 2.0 scopes this POSTING surface reads, and the endpoint→scope map that gates it.
+//
+// TRANSCRIBED, NOT SHARED — same seam note as x-problems.ts. The catalog itself is
+// `packages/twin/xidentity/src/xidentity-scopes.ts`'s `SCOPE_CATALOG`, taken verbatim from the
+// X API v2 OpenAPI 2.167 `OAuth2UserToken` security scheme (recorded in spec-sources.json's
+// xidentity entry, live-fetched 2026-08-21). Only the scopes THIS surface can require are
+// listed; the other nineteen are xidentity's business, and re-listing them here would create a
+// second catalog to drift.
+//
+// The endpoint→scope pairs are the OpenAPI's own per-operation `security` entries for the three
+// operations this pack models — the same source the catalog came from.
+/** The subset of X's scope catalog the posting surface can require, with X's own consent wording. */
+export const X_SCOPES = {
+    'tweet.read': 'View all posts you can see, including those from protected accounts.',
+    'tweet.write': 'Create and repost on your behalf.',
+    'users.read': 'View any account you can see, including protected accounts.',
+    'offline.access': 'Stay connected to your account until you revoke access.',
+    'media.write': 'Upload media, such as photos and videos, on your behalf.',
+};
+/** Space-separated scope param → ordered unique scope list (X formats scope space-separated). */
+export function parseScopeList(raw) {
+    if (!raw)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const s of raw.split(/[\s+]+/)) {
+        if (!s || seen.has(s))
+            continue;
+        seen.add(s);
+        out.push(s);
+    }
+    return out;
+}
+/** The scopes a token must hold for one modelled operation, from the OpenAPI's `security` entry. */
+export const REQUIRED_SCOPES = {
+    'tweets.create': ['tweet.write', 'users.read'],
+    // A reply is the SAME OpenAPI operation as an original post (`POST /2/tweets`), so its scope
+    // requirement is identical at the vendor. The split lives one layer up — in the CENSUS, where
+    // a grant can name one and not the other. Keeping the two rows here, equal and separate,
+    // records that the vendor does not distinguish them and this estate does.
+    'tweets.reply': ['tweet.write', 'users.read'],
+    'tweets.delete': ['tweet.write', 'users.read'],
+    'mentions.list': ['tweet.read', 'users.read'],
+    // The READ operations, from the same source: the pinned client's own per-method docblocks name
+    // `users.read` + `tweet.read` on the lookup endpoints (dist/cjs/v2/client.v2.read.js, the
+    // `singleTweet`/`tweets` comments) and `tweet.read` + `users.read` on the timelines
+    // (`homeTimeline`, `userTimeline`). One scope pair for the whole read surface, as X publishes it.
+    'tweets.lookup': ['tweet.read', 'users.read'],
+    'timelines.read': ['tweet.read', 'users.read'],
+    'search.recent': ['tweet.read', 'users.read'],
+    // User lookup (by id and by username). The pinned client's `user`/`userByUsername` docblocks
+    // name no scope; the adjacent `me()` docblock (client.v2.read.js:234) names this pair, and it is
+    // transcribed from there — the one user-lookup scope statement in the grounding source.
+    'users.lookup': ['tweet.read', 'users.read'],
+    // Media upload (one-shot, initialize/append/finalize, STATUS): docs.x.com's per-operation
+    // security entry names `media.write` alone ("Upload media, such as photos and videos, on your
+    // behalf"). Attaching the uploaded id to a post is POST /2/tweets and needs that route's pair.
+    'media.upload': ['media.write'],
+};
+export function missingScopes(held, required) {
+    return required.filter((scope) => !held.includes(scope));
+}

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

@@ -0,0 +1,14 @@
+/** Options every X-twin HTTP surface needs, independent of who owns the socket. */
+export interface XTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createXTwinFetch(options?: XTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createXTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/x-server.js

@@ -0,0 +1,127 @@
+// X (Twitter) twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler` — manifest door, body read, header map,
+// worldNow() stamp, JSON reply); this file contributes only VALUES — plus the two places X's wire
+// exceeds that adapter's text-in/JSON-out shape, both about media BYTES:
+//
+//   - a MULTIPART upload (`POST /2/media/upload`, `…/{id}/append`): the adapter reads bodies as
+//     text, which corrupts binary, so the form is parsed here and handed to the same handler as
+//     `form` (a JSON upload, base64 in the body, goes through the adapter unchanged);
+//   - the media bytes themselves, read from the blob seam by digest, at X's own path shapes:
+//     pbs.twimg.com's `/media/<name>.<ext>` for an image and `/ext_tw_video_thumb/<id>/pu/img/…`
+//     for a video's preview, video.twimg.com's `/ext_tw_video/<id>/pu/vid/avc1/<w>x<h>/<name>.mp4`
+//     for the video file — with HTTP Range (206), so a <video> can seek. Those hosts are public
+//     at X (an <img> or <video> carries no bearer), so these routes are too.
+//
+// The server is one line of Bun.serve around that same closure.
+import { readMediaRecord, readXBlob, readXBlobType, videoPosterSvg } from "./x-media.js";
+import { handleXTwinRequest } from "./x-twin.js";
+import { createTwinFetchFromHandler, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+const MULTIPART_UPLOAD_PATH = /^\/2\/media\/upload(?:\/\d{1,19}\/append)?\/?$/;
+const MEDIA_BYTES_PATH = /^\/media\/([0-9a-f]{64})\.(jpg|png|gif|webp)$/;
+const VIDEO_BYTES_PATH = /^\/ext_tw_video\/\d{1,19}\/pu\/vid\/avc1\/\d+x\d+\/([0-9a-f]{64})\.mp4$/;
+const VIDEO_THUMB_PATH = /^\/ext_tw_video_thumb\/(\d{1,19})\/pu\/img\/[0-9a-f]{64}\.svg$/;
+/**
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range
+ * that does not parse — including a first-byte-pos past its last-byte-pos (`bytes=5-2`) — is
+ * IGNORED and the whole body is a 200; a well-formed range that starts past the end is a 416. The
+ * content type is the one the twin decided at upload (stored beside the bytes), and `nosniff`
+ * stops a browser second-guessing it.
+ */
+function bytesResponse(request, bytes, contentType) {
+    const total = bytes.length;
+    const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': 'public, max-age=604800, immutable' };
+    const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
+    let start = 0;
+    let end = total - 1;
+    const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && Number(range[1]) > Number(range[2]));
+    if (valid) {
+        if (range[1] === '') {
+            start = Math.max(0, total - Number(range[2]));
+        }
+        else {
+            start = Number(range[1]);
+            end = range[2] === '' ? total - 1 : Math.min(Number(range[2]), total - 1);
+        }
+        if (start >= total || (range[1] === '' && Number(range[2]) === 0))
+            return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
+    }
+    const partial = start !== 0 || end !== total - 1;
+    const body = bytes.slice(start, end + 1);
+    return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+        status: partial ? 206 : 200,
+        headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+    });
+}
+export function createXTwinFetch(options = {}) {
+    const adapted = createTwinFetchFromHandler(handleXTwinRequest, {
+        ...options,
+        extras: (request) => ({ publicBase: twinPublicBase(request) }),
+        manifest: statefulTwinManifest({ vendor: 'x', twinOf: 'the X (Twitter) API v2 posting surface', stores: 'tweets, replies, deletions, the mentions timeline and uploaded images' }),
+    });
+    return async (request) => {
+        const url = new URL(request.url);
+        const reading = request.method === 'GET' || request.method === 'HEAD';
+        const image = reading ? MEDIA_BYTES_PATH.exec(url.pathname) : null;
+        const video = reading ? VIDEO_BYTES_PATH.exec(url.pathname) : null;
+        if (image || video) {
+            const digest = (image ?? video)[1];
+            const bytes = await readXBlob(digest, options.root);
+            const type = await readXBlobType(digest, options.root);
+            // bytes with no recorded type were never an upload this twin read: not served
+            if (!bytes || !type)
+                return new Response('Not Found', { status: 404 });
+            return bytesResponse(request, bytes, type);
+        }
+        const thumb = reading ? VIDEO_THUMB_PATH.exec(url.pathname) : null;
+        if (thumb) {
+            const record = await readMediaRecord(thumb[1], options.root);
+            if (!record?.sha256)
+                return new Response('Not Found', { status: 404 });
+            return new Response(request.method === 'HEAD' ? null : videoPosterSvg(record.width ?? 0, record.height ?? 0), { headers: { 'content-type': 'image/svg+xml', 'x-content-type-options': 'nosniff', 'cache-control': 'public, max-age=604800' } });
+        }
+        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 {
+                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 headers = {};
+            request.headers.forEach((value, key) => { headers[key] = value; });
+            const invoke = () => handleXTwinRequest({
+                method: request.method,
+                path: url.pathname + (url.search || ''),
+                headers,
+                form: { fields, ...(media ? { media } : {}) },
+                readOnly: options.readOnly ?? false,
+                occurredAt: worldNow(),
+                publicBase: twinPublicBase(request),
+                ...(options.root !== undefined ? { root: options.root } : {}),
+            });
+            const requestId = request.headers.get('x-twins-request-id') ?? undefined;
+            const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+            return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json', ...result.headers } });
+        }
+        return adapted(request);
+    };
+}
+export async function createXTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createXTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,21 @@
+import { type XResponse } from './x-problems.js';
+export type XRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    readOnly?: boolean;
+    occurredAt?: string;
+    root?: string;
+    /** A multipart body, parsed by the server (x-server.ts): its text fields and the `media` part's
+     *  bytes. The JSON adapter reads bodies as text, which would corrupt binary; so a multipart
+     *  upload arrives here instead of in `body`. */
+    form?: {
+        fields: Record<string, string>;
+        media?: Uint8Array;
+    };
+    /** Where this twin is reached (`twinPublicBase`: origin plus any World mount path). A media `url`
+     *  is minted from it; a direct handler call with none mints X's own pbs.twimg.com form. */
+    publicBase?: string;
+};
+export declare function handleXTwinRequest(request: XRequest): Promise<XResponse>;