@volter/twin-x 0.1.0 → 0.1.1

package/src/x-problems.ts

@@ -55,6 +55,25 @@ export 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 function oauth1PermissionsProblem(): XResponse {
+  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(): XResponse {
   return {

package/src/x-server.ts

@@ -59,6 +59,46 @@ function bytesResponse(request: Request, bytes: Uint8Array, contentType: string)
   });
 }
 
+/**
+ * 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: Uint8Array, contentType: string): { fields: Record<string, string>; media?: Uint8Array } | null {
+  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: Record<string, string> = {};
+  let media: Uint8Array | undefined;
+  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: XTwinFetchOptions = {}): (request: Request) => Promise<Response> {
   const adapted = createTwinFetchFromHandler(handleXTwinRequest, {
     ...options,
@@ -86,16 +126,11 @@ export function createXTwinFetch(options: XTwinFetchOptions = {}): (request: Req
     }
     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 {
+      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: 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 { fields, media } = parsed;
       const headers: Record<string, string> = {};
       request.headers.forEach((value, key) => { headers[key] = value; });
       const invoke = () => handleXTwinRequest({

package/src/x-twin.ts

@@ -35,19 +35,21 @@
 // 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 { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import {
   forbiddenProblem,
   invalidRequestProblem,
   lookupResult,
   notFoundProblem,
+  oauth1PermissionsProblem,
   rateLimitExceeded,
   readOnlyRefusal,
   resourceNotFoundError,
@@ -56,6 +58,7 @@ import {
   type XResponse,
 } from './x-problems.ts';
 import { missingScopes, parseScopeList, REQUIRED_SCOPES } from './x-scopes.ts';
+import { isOAuth1Header, scopesOfAccessLevel, verifyOAuth1 } from './x-oauth1.ts';
 import {
   clearSegments,
   listMediaIds,
@@ -159,7 +162,7 @@ function newestFirst(posts: Resource[]): Resource[] {
 // unregistered, malformed or absent bearer is the vendor's about:blank 401 — never a local
 // exception, and never a pass.
 
-type Authorized = { accountId: string; scopes: string[]; token: string };
+type Authorized = { accountId: string; scopes: string[]; token: string; oauth1?: true };
 
 function bearerFrom(headers: Record<string, string> | undefined): string | undefined {
   if (!headers) return undefined;
@@ -171,7 +174,16 @@ function bearerFrom(headers: Record<string, string> | undefined): string | undef
   return undefined;
 }
 
-function authorize(all: Resource[], headers: Record<string, string> | undefined): Authorized | XResponse {
+function authorize(all: Resource[], request: XRequest): Authorized | XResponse {
+  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();
   const row = ofType(all, 'token').find((t) => String(t.id) === token);
@@ -184,6 +196,7 @@ const isResponse = (value: Authorized | XResponse): value is XResponse => 'statu
 function scopeRefusal(auth: Authorized, operation: keyof typeof REQUIRED_SCOPES): XResponse | undefined {
   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.`);
 }
 
@@ -266,9 +279,14 @@ 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: URL): Set<string> | XResponse {
   const userFields = new Set<string>();
@@ -395,6 +413,9 @@ function projectUser(account: Resource, userFields: Set<string>, all: Resource[]
   if (userFields.has('description')) out.description = typeof account.description === 'string' ? account.description : '';
   if (userFields.has('location') && typeof account.location === 'string' && account.location !== '') 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')) out.verified = account.verified === true;
   if (userFields.has('most_recent_tweet_id')) {
@@ -677,6 +698,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: unknown, parameter: string): string | XResponse {
@@ -689,6 +717,10 @@ function postIdField(value: unknown, parameter: string): string | XResponse {
 async function createPost(request: XRequest, all: Resource[], auth: Authorized, payload: Record<string, any>): Promise<XResponse> {
   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.`);
   }
@@ -752,7 +784,7 @@ async function createPost(request: XRequest, all: Resource[], auth: Authorized,
 
   // 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',
@@ -791,7 +823,7 @@ async function deletePost(request: XRequest, all: Resource[], auth: Authorized,
     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 } });
@@ -843,7 +875,7 @@ const CHECK_AFTER_SECS = 1;
 const isVideoCategory = (category: string): boolean => VIDEO_CATEGORIES.has(category);
 
 function nowSeconds(request: XRequest): number {
-  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. */
@@ -1000,7 +1032,7 @@ async function uploadMedia(request: XRequest, all: Resource[], auth: Authorized,
   const opened: XMediaRecord = {
     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, '');
@@ -1039,7 +1071,7 @@ async function initializeUpload(request: XRequest, all: Resource[], auth: Author
   const record: XMediaRecord = {
     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 } });
@@ -1347,12 +1379,19 @@ async function handleTwinControl(request: XRequest, all: Resource[], path: strin
       if (typeof payload[key] !== 'string') 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'] as const) {
       if (payload[key] === undefined) continue;
       if (typeof payload[key] !== 'boolean') 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',
@@ -1376,7 +1415,7 @@ async function handleTwinControl(request: XRequest, all: Resource[], path: strin
       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 } });
   }
@@ -1389,7 +1428,7 @@ async function handleTwinControl(request: XRequest, all: Resource[], path: strin
       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',
@@ -1416,7 +1455,7 @@ async function handleTwinControl(request: XRequest, all: Resource[], path: strin
       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 } });
   }
@@ -1430,7 +1469,7 @@ async function handleTwinControl(request: XRequest, all: Resource[], path: strin
       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 } });
   }
@@ -1485,7 +1524,7 @@ export async function handleXTwinRequest(request: XRequest): Promise<XResponse>
   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(/\/+$/, '');