@volter/twin-tiktok 0.1.0

package/src/tiktok-sample-mp4.ts

@@ -0,0 +1,54 @@
+// A real video, as data only — the one sample file the pack's conformance probes, capability verifies
+// and gate replay upload. Kept apart from the handler so the dev-plane gate can read it without
+// importing the code it exists to sabotage.
+/**
+ * A REAL video the posting probes upload: one second of 360x640 black at 24 FPS, H.264 in MP4
+ * (`ffmpeg -f lavfi -i color=c=black:size=360x640:rate=24 -t 1 -crf 51 -movflags +faststart`), the
+ * smallest file TikTok's checks accept — the twin reads its duration, picture size and frame rate,
+ * and a file it cannot read fails with file_format_check_failed.
+ */
+export const TINY_MP4: Uint8Array<ArrayBuffer> = Uint8Array.from(atob(''
+  + 'AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAQHbW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAA+gAAQAAAQAA'
+  + 'AAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAA'
+  + 'AzF0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAA+gAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAA'
+  + 'AAAAAAAAAAAAAABAAAAAAWgAAAKAAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAAAPoAAAEAAABAAAAAAKpbWRpYQAAACBtZGhk'
+  + 'AAAAAAAAAAAAAAAAAAAwAAAAMABVxAAAAAAALWhkbHIAAAAAAAAAAHZpZGUAAAAAAAAAAAAAAABWaWRlb0hhbmRsZXIAAAACVG1p'
+  + 'bmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQAAAAx1cmwgAAAAAQAAAhRzdGJsAAAAxHN0c2QA'
+  + 'AAAAAAAAAQAAALRhdmMxAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAWgCgABIAAAASAAAAAAAAAABFUxhdmM2Mi4yOC4xMDIgbGli'
+  + 'eDI2NAAAAAAAAAAAAAAAGP//AAAAOmF2Y0MBZAAf/+EAHGdkAB+scgRBcFHl8BEAAAMAAQAAAwAwDxgxhGABAAdo6EOBlLIs/fj4'
+  + 'AAAAABBwYXNwAAAAAQAAAAEAAAAUYnRydAAAAAAAACVYAAAAAAAAABhzdHRzAAAAAAAAAAEAAAAYAAACAAAAABRzdHNzAAAAAAAA'
+  + 'AAEAAAABAAAAeGN0dHMAAAAAAAAADQAAAAEAAAQAAAAAAQAAFAAAAAABAAAIAAAAAAMAAAAAAAAABAAAAgAAAAABAAAUAAAAAAEA'
+  + 'AAgAAAAAAwAAAAAAAAAEAAACAAAAAAEAAAwAAAAAAQAABAAAAAABAAAAAAAAAAIAAAIAAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAAY'
+  + 'AAAAAQAAAHRzdHN6AAAAAAAAAAAAAAAYAAADCQAAABIAAAARAAAAEQAAABEAAAARAAAAEQAAABEAAAARAAAAEQAAABcAAAASAAAA'
+  + 'EgAAABIAAAASAAAAEgAAABIAAAASAAAAEgAAABkAAAASAAAAEgAAABIAAAASAAAAFHN0Y28AAAAAAAAAAQAABDcAAABidWR0YQAA'
+  + 'AFptZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAC1pbHN0AAAAJal0b28AAAAdZGF0YQAAAAEAAAAA'
+  + 'TGF2ZjYyLjEyLjEwMgAAAAhmcmVlAAAEs21kYXQAAAKxBgX//63cRem95tlIt5Ys2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIy'
+  + 'IGIzNTYwNWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQgMjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xh'
+  + 'bi5vcmcveDI2NC5odG1sIC0gb3B0aW9uczogY2FiYWM9MSByZWY9MTYgZGVibG9jaz0xOjA6MCBhbmFseXNlPTB4MzoweDEzMyBt'
+  + 'ZT11bWggc3VibWU9MTAgcHN5PTEgcHN5X3JkPTEuMDA6MC4wMCBtaXhlZF9yZWY9MSBtZV9yYW5nZT0yNCBjaHJvbWFfbWU9MSB0'
+  + 'cmVsbGlzPTIgOHg4ZGN0PTEgY3FtPTAgZGVhZHpvbmU9MjEsMTEgZmFzdF9wc2tpcD0xIGNocm9tYV9xcF9vZmZzZXQ9LTIgdGhy'
+  + 'ZWFkcz0xOCBsb29rYWhlYWRfdGhyZWFkcz0zIHNsaWNlZF90aHJlYWRzPTAgbnI9MCBkZWNpbWF0ZT0xIGludGVybGFjZWQ9MCBi'
+  + 'bHVyYXlfY29tcGF0PTAgY29uc3RyYWluZWRfaW50cmE9MCBiZnJhbWVzPTggYl9weXJhbWlkPTIgYl9hZGFwdD0yIGJfYmlhcz0w'
+  + 'IGRpcmVjdD0zIHdlaWdodGI9MSBvcGVuX2dvcD0wIHdlaWdodHA9MiBrZXlpbnQ9MjUwIGtleWludF9taW49MjQgc2NlbmVjdXQ9'
+  + 'NDAgaW50cmFfcmVmcmVzaD0wIHJjX2xvb2thaGVhZD02MCByYz1jcmYgbWJ0cmVlPTEgY3JmPTUxLjAgcWNvbXA9MC42MCBxcG1p'
+  + 'bj0wIHFwbWF4PTY5IHFwc3RlcD00IGlwX3JhdGlvPTEuNDAgYXE9MToxLjAwAIAAAABQZYiBAAT/Hru//lSYAAADAAAKEgzs1poj'
+  + 'pAAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAC7kAAAAOQZoJLYhP/wAAAwAAEnAA'
+  + 'AAANQZ4QhxCPAAADAAA1IQAAAA0BnhgmiL8AAAMAADegAAAADQGeGEaIvwAAAwAAN6EAAAANAZ4YZoi/AAADAAA3oQAAAA0Bnhit'
+  + 'SL8AAAMAADehAAAADQGeGM1IvwAAAwAAN6EAAAANAZ4Y7Ui/AAADAAA3oAAAAA0BnhkNSL8AAAMAADegAAAAE0GaGkk1AgLRMpgQ'
+  + 'jwAAAwAAFTEAAAAOQZ4hpcQj/wAAAwAANSAAAAAOAZ4pRaIv/wAAAwAAN6AAAAAOAZ4pZaIv/wAAAwAAN6EAAAAOAZ4phaIv/wAA'
+  + 'AwAAN6EAAAAOAZ4pzJIv/wAAAwAAN6EAAAAOAZ4p7JIv/wAAAwAAN6AAAAAOAZ4qDJIv/wAAAwAAN6AAAAAOAZ4qLJIv/wAAAwAA'
+  + 'N6EAAAAVQZoq6bUCAtrRMpgBF/8AAAMAAB6QAAAADkGeMoSxH/8AAAMAADZgAAAADgGeOmSoi/8AAAMAADehAAAADgGeOqzSL/8A'
+  + 'AAMAADegAAAADgGeOszSL/8AAAMAADeh'), (c) => c.charCodeAt(0));
+
+/** TINY_MP4 grown to exactly `size` bytes by a trailing `free` box (ISO BMFF's padding box): still a
+ *  valid, readable MP4, for the probes that need a video past TikTok's 5 MB chunk floor. */
+export function paddedMp4(size: number): Uint8Array<ArrayBuffer> {
+  const pad = size - TINY_MP4.length;
+  if (pad < 8) throw new Error(`paddedMp4: ${size} is below ${TINY_MP4.length + 8}`);
+  const out = new Uint8Array(size);
+  out.set(TINY_MP4);
+  new DataView(out.buffer).setUint32(TINY_MP4.length, pad);
+  out.set([0x66, 0x72, 0x65, 0x65], TINY_MP4.length + 4);
+  for (let i = TINY_MP4.length + 8; i < size; i += 1) out[i] = (i * 31 + (i >> 11)) & 0xff;
+  return out;
+}

package/src/tiktok-scopes.ts

@@ -0,0 +1,122 @@
+// TikTok OAuth scopes — the vendor's own catalog, transcribed from the TikTok for Developers
+// "Scopes Overview" page (https://developers.tiktok.com/doc/tiktok-api-scopes/, fetched
+// 2026-09-13) together with the per-product reference pages the overview links to.
+//
+// TWO THINGS THIS VENDOR DOES THAT THE X / GOOGLE CONSENT MODELS DO NOT:
+//
+//   1. The scope parameter is COMMA-separated (`scope=user.info.basic,user.info.profile`), not
+//      space-separated. That is documented on the Login Kit for Web parameter table ("A comma (,)
+//      separated string of authorization scope(s)") and it is exactly how Dub builds its authorize
+//      URL. A twin that accepted only spaces would refuse the vendor's own callers.
+//
+//   2. Consent is GRANULAR, not all-or-nothing. The documented callback carries a `scopes`
+//      parameter — "A comma-separated (,) string of authorization scope(s), which the user has
+//      granted" — which only has meaning if the granted set can be a SUBSET of the requested set,
+//      and the token response's `scope` is likewise "the scopes the user has agreed to authorize".
+//      So the authorize screen this twin serves offers one checkbox per requested scope and the
+//      granted set is what came back checked. EVIDENCE BOUNDARY: the two parameters above are
+//      documented; the SHAPE of the live affordance (per-scope toggles, which scopes are
+//      mandatory, what the buttons say) was not captured from a vendor artefact and is pinned by
+//      `tiktok.consent.optional_scope_toggles` and `tiktok.consent.button_wording` (todo).
+//
+// EVIDENCE BOUNDARY on the LABELS, and it is NOT uniform — say which is which rather than let a
+// "verbatim" claim cover the lot. THREE labels are the Scopes Overview's own published text, word
+// for word, and are asserted as such by `tiktok.scopes.catalog_matches_vendor_list`:
+// `user.info.basic`, `user.info.profile` and `video.list`. The other EIGHTEEN are TWIN PARAPHRASES
+// written from the overview's per-product descriptions — accurate in substance, not quotations —
+// because the overview publishes those rows as product prose rather than as a scope string. Every
+// label is developer-facing either way, never a capture of the live consent sheet, so
+// `tiktok.scopes.consent_wording` (todo) pins the strings a person actually reads. The SCOPE IDS,
+// by contrast, are all twenty-one exactly as published, and that set is what the capability
+// asserts a bijection against.
+
+export type ScopeProduct = 'user' | 'video' | 'portability' | 'research' | 'local';
+
+export type ScopeInfo = {
+  scope: string;
+  /** The vendor's own published description of the scope. */
+  label: string;
+  product: ScopeProduct;
+  /** In the vendor catalog? An unknown scope is still displayed, flagged, so a typo is visible. */
+  known: boolean;
+};
+
+/** The scopes TikTok's scopes-overview page publishes, keyed by scope id. */
+export const SCOPE_CATALOG: Record<string, { label: string; product: ScopeProduct }> = {
+  // ── User Info API ──
+  // VERBATIM marks a label that is the Scopes Overview's own published text, word for word;
+  // every unmarked label is a TWIN PARAPHRASE of that page's product prose (see the header).
+  // VERBATIM
+  'user.info.basic': { label: "Read a user's profile info (open id, avatar, display name...)", product: 'user' },
+  // VERBATIM
+  'user.info.profile': { label: 'Read access to profile_web_link, profile_deep_link, bio_description, is_verified', product: 'user' },
+  'user.info.stats': { label: 'Read your engagement metrics: follower count, following count, likes count and video count', product: 'user' },
+  // ── Display API / Content Posting API ──
+  // VERBATIM
+  'video.list': { label: "Read a user's public videos on TikTok", product: 'video' },
+  'video.upload': { label: 'Share videos to your account as drafts, for you to edit before posting', product: 'video' },
+  'video.publish': { label: "Directly post content to a user's TikTok profile", product: 'video' },
+  // ── Data Portability API ──
+  'portability.activity.ongoing': { label: 'Export your activity data on an ongoing basis', product: 'portability' },
+  'portability.activity.single': { label: 'Export your activity data once', product: 'portability' },
+  'portability.all.ongoing': { label: 'Export your complete data archive on an ongoing basis', product: 'portability' },
+  'portability.all.single': { label: 'Export your complete data archive once', product: 'portability' },
+  'portability.directmessages.ongoing': { label: 'Export your direct messages on an ongoing basis', product: 'portability' },
+  'portability.directmessages.single': { label: 'Export your direct messages once', product: 'portability' },
+  'portability.postsandprofile.ongoing': { label: 'Export your posts and profile data on an ongoing basis', product: 'portability' },
+  'portability.postsandprofile.single': { label: 'Export your posts and profile data once', product: 'portability' },
+  // ── Research API ──
+  'research.data.basic': { label: 'Access public data for research purposes', product: 'research' },
+  'research.data.u18eu': { label: 'Access data of European users under 18 for research purposes', product: 'research' },
+  'research.data.vra': { label: 'Access vetted-researcher provisioned data', product: 'research' },
+  'research.adlib.basic': { label: 'Access commercial content data for research purposes', product: 'research' },
+  // ── Local Services API ──
+  'local.product.manage': { label: 'Manage the products of your local services account', product: 'local' },
+  'local.shop.manage': { label: 'Manage the shops of your local services account', product: 'local' },
+  'local.voucher.manage': { label: 'Manage the vouchers of your local services account', product: 'local' },
+};
+
+export const KNOWN_SCOPES: readonly string[] = Object.keys(SCOPE_CATALOG);
+
+/**
+ * Comma-separated scope param -> ordered unique scope list.
+ *
+ * Whitespace around a comma is tolerated because a caller that pretty-prints its scope constant
+ * would otherwise send a scope literally named " video.list". The SEPARATOR the twin requires is
+ * still the comma: a space-separated X-style string parses as ONE unknown scope and renders
+ * flagged on the screen, which is the integration bug a developer needs to see.
+ */
+export function parseScopeParam(raw: string | null): string[] {
+  if (!raw) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const piece of raw.split(',')) {
+    const s = piece.trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+/** The wire form: comma-separated, no spaces (the docs' own `user.info.basic,video.list`). */
+export function formatScopeParam(scopes: readonly string[]): string {
+  return scopes.join(',');
+}
+
+export function describeScope(scope: string): ScopeInfo {
+  const known = SCOPE_CATALOG[scope];
+  return known
+    ? { scope, label: known.label, product: known.product, known: true }
+    : { scope, label: scope, product: 'user', known: false };
+}
+
+export function describeScopes(scopes: readonly string[]): ScopeInfo[] {
+  return scopes.map(describeScope);
+}
+
+/** Screen order: the vendor's own product order, stable so the page is byte-identical on reload. */
+const PRODUCT_ORDER: Record<ScopeProduct, number> = { user: 0, video: 1, portability: 2, research: 3, local: 4 };
+export function sortScopesForConsent(scopes: readonly string[]): string[] {
+  return [...scopes].sort((a, b) => PRODUCT_ORDER[describeScope(a).product] - PRODUCT_ORDER[describeScope(b).product]);
+}

package/src/tiktok-server.ts

@@ -0,0 +1,100 @@
+// TikTok twin HTTP server — ONE server for the whole vendor surface, because Login Kit is one
+// product spread over two hosts. Point `www.tiktok.com` (the authorization page) and
+// `open.tiktokapis.com` (the OAuth + Display API endpoints) here and an unmodified TikTok
+// integration completes a full authorization-code round trip against it.
+//
+// Two things this server does that a JSON-only twin server does not:
+//   • it can answer with HTML and with 302 redirects — the authorization page and the callback
+//     bounce are the protocol, not decoration, so the handler's `headers` (content-type, location)
+//     pass straight through rather than being flattened into a JSON envelope;
+//   • it tells the handler its OWN origin, so the consent form's action points BACK AT THE TWIN.
+//
+// The page needs no assets: the stylesheet is inlined and the screen ships no JavaScript, so there
+// is no bundler and no disk read anywhere on the serve path (runtime contract R12b, R9).
+import { serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+import { UPLOAD_PATH } from './tiktok-posting.ts';
+import { handleTikTokTwinRequest } from './tiktok-twin.ts';
+
+/** Options every TikTok-twin HTTP surface needs, independent of who owns the socket. */
+export interface TikTokTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createTikTokTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted surfaces
+ * are the SAME code — there is no second HTTP adaptation to drift.
+ */
+export function createTikTokTwinFetch(options: TikTokTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  return async function tiktokTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({
+        vendor: 'tiktok',
+        twinOf: 'TikTok Login Kit, the Display API and the Content Posting API',
+        stores: 'developer apps, TikTok accounts and their videos (with the posted media), authorization codes, user access/refresh tokens, the authorization-page round trip and Content Posting publishes',
+      }));
+    }
+
+    // the upload URL's chunk PUT carries BYTES; every other body is text (form or JSON)
+    const upload = url.pathname.replace(/\/+$/, '') === UPLOAD_PATH;
+    const raw = request.method === 'GET' || request.method === 'HEAD' ? new Uint8Array(0) : new Uint8Array(await request.arrayBuffer());
+    const body = upload ? '' : new TextDecoder().decode(raw);
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+
+    const res = await handleTikTokTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: worldNow(),
+      origin: twinPublicBase(request),
+      callbackOrigin: url.origin,
+      ...(upload ? { bytes: raw } : {}),
+      ...(headers['x-volter-twin-original-host'] ? { originalHost: headers['x-volter-twin-original-host'].toLowerCase() } : {}),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+
+    const out = { ...(res.headers ?? {}) };
+    // a post's bytes (the media route): a range as bytes, a whole file as a stream of ranged reads;
+    // HEAD answers the headers alone
+    if (res.body instanceof Uint8Array || res.body instanceof ReadableStream) {
+      const media = request.method === 'HEAD' ? null : (res.body as Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>);
+      return new Response(media, { status: res.status, headers: out });
+    }
+    // A string body is already rendered (HTML, or the empty body of a 302); anything else is the
+    // vendor's JSON.
+    if (typeof res.body === 'string') {
+      if (!out['content-type'] && res.body) out['content-type'] = 'text/html; charset=utf-8';
+      return new Response(res.body, { status: res.status, headers: out });
+    }
+    out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
+    return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
+  };
+}
+
+export async function createTikTokTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createTikTokTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/**
+ * The authorization page is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-tiktok mirror` command and the journey
+ * harness have the conventional entry point, and it returns the very same server.
+ */
+export const createTikTokConsentServer = createTikTokTwinServer;