@volter/twin-x 0.1.0

package/src/x-problems.ts

@@ -0,0 +1,143 @@
+// 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.
+
+export type XResponse = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+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(): XResponse {
+  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: string): XResponse {
+  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(): XResponse {
+  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: string, resourceType: 'tweet' | 'user', parameter: string): Record<string, unknown> {
+  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: string, resourceType: 'tweet' | 'user', parameter: string): XResponse {
+  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: unknown, errors: Array<Record<string, unknown>>, includes?: Record<string, unknown>): XResponse {
+  const body: Record<string, unknown> = {};
+  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: Record<string, string[]>, message: string): XResponse {
+  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: Record<string, string>): XResponse {
+  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(): XResponse {
+  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/src/x-scopes.ts

@@ -0,0 +1,67 @@
+// 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: Record<string, string> = {
+  '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: string | null | undefined): string[] {
+  if (!raw) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  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: Record<
+  'tweets.create' | 'tweets.reply' | 'tweets.delete' | 'mentions.list' | 'tweets.lookup' | 'timelines.read' | 'search.recent' | 'users.lookup' | 'media.upload',
+  readonly string[]
+> = {
+  '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: readonly string[], required: readonly string[]): string[] {
+  return required.filter((scope) => !held.includes(scope));
+}

package/src/x-server.ts

@@ -0,0 +1,126 @@
+// 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.ts';
+import { handleXTwinRequest } from './x-twin.ts';
+import { createTwinFetchFromHandler, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+
+/** Options every X-twin HTTP surface needs, independent of who owns the socket. */
+export interface XTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+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: Request, bytes: Uint8Array, contentType: string): Response {
+  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: XTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  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: Request): Promise<Response> => {
+    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: FormData;
+      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: Record<string, string> = {};
+      let media: Uint8Array | undefined;
+      for (const [name, value] of form.entries() as Iterable<[string, unknown]>) {
+        if (typeof value === 'string') fields[name] = value;
+        else if (name === 'media' && value instanceof Blob) media = new Uint8Array(await value.arrayBuffer());
+      }
+      const headers: Record<string, string> = {};
+      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: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createXTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}