@volter/twin-tiktok 0.1.0

package/src/tiktok-posting.ts

@@ -0,0 +1,617 @@
+// TikTok twin — the CONTENT POSTING API: a creator's video posted through TikTok's own API.
+//
+//   open.tiktokapis.com        POST /v2/post/publish/creator_info/query/  → who is posting, and what they may choose
+//                              POST /v2/post/publish/video/init/          → Direct Post (video.publish): publish_id + upload_url
+//                              POST /v2/post/publish/inbox/video/init/    → upload to the creator's inbox (video.upload)
+//                              POST /v2/post/publish/status/fetch/        → the publish_id's lifecycle
+//   open-upload.tiktokapis.com PUT  /video/?upload_id=…&upload_token=…    → the bytes, in chunks, with Content-Range
+//
+// Every shape here is from the vendor's own references (developers.tiktok.com, fetched 2026-09-27):
+// content-posting-api-reference-query-creator-info, -direct-post, -upload-video, -get-video-status and
+// content-posting-api-media-transfer-guide. Where a reference is silent the twin says so inline and a
+// manifest todo pins the live behaviour.
+//
+// ── THE UPLOAD URL ───────────────────────────────────────────────────────────────────────────────
+// TikTok's upload_url is on ANOTHER HOST than the API and carries its own authorization in the query
+// (`upload_id` + `upload_token`); the PUT sends no bearer. The twin mints it the same way: the upload
+// path `/video/` under the twin's own public base — or, when the request names the vendor's API host
+// (an app inside a World reaches the twin through the injector as open.tiktokapis.com), on the
+// vendor's own upload host, which the pack claims so the injector routes that PUT here too. The
+// `upload_token` is an HMAC-SHA256 over the upload id and its expiry, keyed by that upload's OWN secret
+// drawn from entropy at init (LinkedIn's per-asset secret), so the twin VERIFIES a token rather than
+// looking one up, a token for one upload opens no other, and no credential is ever a key. "The
+// upload_url is valid for one hour after issuance" — after that the PUT is 403. The upload record
+// holds the posting token's SHA-256, never the token.
+//
+// ── WHAT IS A KERNEL WRITE ───────────────────────────────────────────────────────────────────────
+// Only the FINALIZE. The init is staging (the byte annex holds the upload record, tiktok-blobs.ts),
+// every chunk is its own staged key, and the final chunk joins them, stores the video content-addressed
+// and makes ONE kernel write: `video.publish` (a Direct Post: the video on the creator's profile, plus
+// its `publish` row) or `video.inbox_upload` (a draft: the `publish` row alone). That write is what a
+// gated deploy performs against the vendor (tiktok-connector.ts).
+//
+// ── THE LIFECYCLE IS WORLD TIME ──────────────────────────────────────────────────────────────────
+// status/fetch is DERIVED at read from the finalize instant: PROCESSING_UPLOAD while chunks are
+// arriving and for PROCESSING_MS of World time after the last one ("The video processing will occur
+// asynchronously once the upload is complete"), then PUBLISH_COMPLETE (Direct Post) or
+// SEND_TO_USER_INBOX (inbox). A published video appears in /v2/video/list/ from that same instant.
+import { createHmac } from 'node:crypto';
+import { applyTwinWriteAtomic, type TwinResource } from '@volter/world-core';
+import {
+  clearStaged,
+  joinStaged,
+  putTikTokBlob,
+  readTikTokBlobRange,
+  readUpload,
+  readUploadByPublishId,
+  stageChunk,
+  stagedSize,
+  tikTokBlobSize,
+  writeUpload,
+  type TikTokUpload,
+} from './tiktok-blobs.ts';
+import { apiError, apiOk, postingError, type TikTokResponse } from './tiktok-errors.ts';
+import { logId } from './tiktok-ids.ts';
+import { probeMp4 } from './tiktok-media.ts';
+import { BK_ACCESS, mintPostId, mintPublishId, mintUploadId, nextRevIn, secretKey, type Row } from './tiktok-store.ts';
+
+/** The vendor's own upload host, and the path its upload_url carries. */
+export const UPLOAD_ORIGIN = 'https://open-upload.tiktokapis.com';
+export const UPLOAD_PATH = '/video';
+/** The API host a request names when an app inside a World reached the twin through the injector. */
+const API_HOST = 'open.tiktokapis.com';
+
+/** "The upload_url is valid for one hour after issuance. The upload must be completed in this time range." */
+export const UPLOAD_URL_TTL_MS = 60 * 60 * 1000;
+
+// The media transfer guide's chunk rules, verbatim in substance: "Minimum chunk size: 5 MB", "Maximum
+// chunk size: 64 MB", "the final chunk ... can be up to 128 MB", "Videos under 5 MB must upload whole",
+// "minimum 1 chunk, maximum 1000 chunks", total_chunk_count = video_size / chunk_size rounded DOWN (the
+// trailing bytes ride the final chunk), and a 4 GB file maximum. The guide writes "MB" without saying
+// which; the twin reads MiB, the stricter floor, so a client the twin accepts is one TikTok accepts.
+export const MIN_CHUNK_BYTES = 5 * 1024 * 1024;
+export const MAX_CHUNK_BYTES = 64 * 1024 * 1024;
+export const MAX_FINAL_CHUNK_BYTES = 128 * 1024 * 1024;
+export const MAX_CHUNK_COUNT = 1000;
+export const MAX_VIDEO_BYTES = 4 * 1024 * 1024 * 1024;
+/**
+ * THE TWIN'S OWN LIMIT, below TikTok's 4 GB, and stated rather than hidden: the final chunk joins the
+ * staged chunks into ONE allocation and stores it with one put, because the kernel's blob seam takes
+ * bytes (`BlobStore.put(key, bytes)`), not a stream. So the twin accepts a video up to what it can hold
+ * whole — 512 MiB, generous for a release video — and refuses a larger init with invalid_param naming
+ * this limit (`tiktok.content_posting.large_files`, todo, is the streaming seam that would lift it).
+ */
+export const TWIN_MAX_VIDEO_BYTES = 512 * 1024 * 1024;
+/** "Framerate: 23–60 FPS" (media transfer guide). */
+export const MIN_FRAME_RATE = 23;
+export const MAX_FRAME_RATE = 60;
+
+/** THE TWIN'S VALUE (TikTok publishes no processing time): how long, in World time, a finished upload
+ *  stays PROCESSING_UPLOAD — two seconds, plus one per 10 MiB. */
+export function processingMs(size: number): number {
+  return 2000 + Math.floor(size / (10 * 1024 * 1024)) * 1000;
+}
+
+/** Direct Post `privacy_level` values ("PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY"). */
+export const PRIVACY_LEVELS = ['PUBLIC_TO_EVERYONE', 'MUTUAL_FOLLOW_FRIENDS', 'FOLLOWER_OF_CREATOR', 'SELF_ONLY'] as const;
+/** The options a public account offers — the creator_info reference's own example. A PRIVATE account
+ *  offers FOLLOWER_OF_CREATOR in place of PUBLIC_TO_EVERYONE. */
+const PUBLIC_ACCOUNT_OPTIONS = ['PUBLIC_TO_EVERYONE', 'MUTUAL_FOLLOW_FRIENDS', 'SELF_ONLY'];
+const PRIVATE_ACCOUNT_OPTIONS = ['FOLLOWER_OF_CREATOR', 'MUTUAL_FOLLOW_FRIENDS', 'SELF_ONLY'];
+/** "Duration: Up to 10 minutes via API" (media transfer guide). An account may carry a lower
+ *  `maxVideoPostDurationSec`; the reference's own example shows 300. */
+export const DEFAULT_MAX_VIDEO_POST_DURATION_SEC = 600;
+/** "Title: max 2200 UTF-16 runes" — `String.length` counts UTF-16 code units. */
+export const MAX_TITLE_UTF16 = 2200;
+/** "max 5 pending shares per 24 hours" (inbox upload reference, spam_risk_too_many_pending_share). */
+export const MAX_PENDING_SHARES = 5;
+/** "Supported formats: MP4 (recommended), WebM, MOV". */
+const VIDEO_TYPES = ['video/mp4', 'video/quicktime', 'video/webm'];
+/** "Resolution: 360–4096 pixels per dimension". */
+const MIN_SIDE = 360;
+const MAX_SIDE = 4096;
+
+/** The poster a Content Posting call acts for, resolved from its bearer by the router. */
+export type PostingContext = {
+  resources: readonly TwinResource[];
+  account: Row;
+  openId: string;
+  scopes: string[];
+  /** The bearer's SHA-256 — what an upload record keeps of it. */
+  tokenHash: string;
+  clientKey: string;
+  at: string;
+  root?: string;
+  /** The twin's public base (origin plus any served-World mount path), when the request came over HTTP. */
+  origin?: string;
+  /** The vendor host the request named, when the injector or a World door forwarded it here. */
+  originalHost?: string;
+  readOnly?: boolean;
+};
+
+const nowMs = (at: string) => Date.parse(at);
+
+function parseBody(body: string | undefined): Record<string, unknown> | null {
+  if (body === undefined || body.trim() === '') return null;
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function needScope(ctx: PostingContext, anyOf: readonly string[]): TikTokResponse | null {
+  if (anyOf.some((s) => ctx.scopes.includes(s))) return null;
+  return apiError('scope_not_authorized', ctx.at, `The user did not authorize the scope required for completing this request: ${anyOf.join(' or ')}.`);
+}
+
+/** What creator_info answers for an account — every value from the account row, the reference's
+ *  defaults where the row names none. */
+export function creatorOptions(account: Row): { privacyLevelOptions: string[]; commentDisabled: boolean; duetDisabled: boolean; stitchDisabled: boolean; maxDurationSec: number } {
+  const options = Array.isArray(account.privacyLevelOptions)
+    ? (account.privacyLevelOptions as unknown[]).filter((o): o is string => typeof o === 'string')
+    : account.isPrivate === true ? PRIVATE_ACCOUNT_OPTIONS : PUBLIC_ACCOUNT_OPTIONS;
+  return {
+    privacyLevelOptions: options,
+    commentDisabled: account.commentDisabled === true,
+    duetDisabled: account.duetDisabled === true,
+    stitchDisabled: account.stitchDisabled === true,
+    maxDurationSec: typeof account.maxVideoPostDurationSec === 'number' ? account.maxVideoPostDurationSec : DEFAULT_MAX_VIDEO_POST_DURATION_SEC,
+  };
+}
+
+// ── creator_info ─────────────────────────────────────────────────────────────────────────────────
+
+export function creatorInfo(ctx: PostingContext): TikTokResponse {
+  const refusal = needScope(ctx, ['video.publish']);
+  if (refusal) return refusal;
+  const o = creatorOptions(ctx.account);
+  return apiOk({
+    creator_avatar_url: typeof ctx.account.avatarUrl === 'string' ? ctx.account.avatarUrl : '',
+    creator_username: String(ctx.account.username ?? ''),
+    creator_nickname: String(ctx.account.displayName ?? ''),
+    privacy_level_options: o.privacyLevelOptions,
+    comment_disabled: o.commentDisabled,
+    duet_disabled: o.duetDisabled,
+    stitch_disabled: o.stitchDisabled,
+    max_video_post_duration_sec: o.maxDurationSec,
+  }, ctx.at, `creator_info:${ctx.openId}`);
+}
+
+// ── init (Direct Post and inbox) ─────────────────────────────────────────────────────────────────
+
+const isInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v);
+
+/** The chunk plan a FILE_UPLOAD init names, checked against the guide's rules; a string is the refusal. */
+export function checkChunkPlan(videoSize: unknown, chunkSize: unknown, count: unknown): string | null {
+  if (!isInt(videoSize) || videoSize <= 0) return 'source_info.video_size must be a positive integer (bytes).';
+  if (videoSize > MAX_VIDEO_BYTES) return `source_info.video_size ${videoSize} exceeds the 4 GB maximum.`;
+  if (videoSize > TWIN_MAX_VIDEO_BYTES) return `source_info.video_size ${videoSize} exceeds this twin's ${TWIN_MAX_VIDEO_BYTES}-byte limit (it holds a video whole when the last chunk lands); TikTok itself accepts up to 4 GB.`;
+  if (!isInt(chunkSize) || chunkSize <= 0) return 'source_info.chunk_size must be a positive integer (bytes).';
+  if (!isInt(count) || count <= 0) return 'source_info.total_chunk_count must be a positive integer.';
+  if (videoSize < MIN_CHUNK_BYTES) {
+    if (chunkSize !== videoSize || count !== 1) return `A video under 5 MB must be uploaded whole: chunk_size must equal video_size (${videoSize}) and total_chunk_count must be 1.`;
+    return null;
+  }
+  if (chunkSize < MIN_CHUNK_BYTES) return `chunk_size ${chunkSize} is below the 5 MB minimum.`;
+  if (chunkSize > MAX_CHUNK_BYTES) return `chunk_size ${chunkSize} is above the 64 MB maximum.`;
+  const expected = Math.floor(videoSize / chunkSize);
+  if (count !== expected) return `total_chunk_count must be video_size / chunk_size rounded down: ${expected}, not ${count}.`;
+  if (count > MAX_CHUNK_COUNT) return `total_chunk_count ${count} exceeds the maximum of ${MAX_CHUNK_COUNT}.`;
+  // "videos over 64 MB require multiple chunks"
+  if (videoSize > MAX_CHUNK_BYTES && count < 2) return `A video over 64 MB must be uploaded in multiple chunks; ${videoSize} bytes in ${count} chunk is refused.`;
+  const last = videoSize - chunkSize * (count - 1);
+  if (last > MAX_FINAL_CHUNK_BYTES) return `The final chunk would carry ${last} bytes, above the 128 MB the final chunk may hold.`;
+  return null;
+}
+
+/** The byte length chunk `index` must carry under an upload's plan. */
+export function chunkLength(upload: Pick<TikTokUpload, 'videoSize' | 'chunkSize' | 'totalChunkCount'>, index: number): number {
+  return index < upload.totalChunkCount - 1 ? upload.chunkSize : upload.videoSize - upload.chunkSize * (upload.totalChunkCount - 1);
+}
+
+/** The upload_token: HMAC-SHA256 over `<upload_id>.<expiry seconds>`, keyed by the initializing token. */
+function signUpload(upload: Pick<TikTokUpload, 'uploadId' | 'expiresAt' | 'uploadSecret'>): string {
+  const mac = createHmac('sha256', upload.uploadSecret).update(`${upload.uploadId}.${Math.floor(upload.expiresAt / 1000)}`).digest('base64url');
+  return `${Math.floor(upload.expiresAt / 1000)}.${mac}`;
+}
+
+/** Compared in constant time over the expected length (the mirror's browser bundle walks this module,
+ *  so no node-only comparison helper). */
+function uploadTokenValid(upload: TikTokUpload, presented: string): boolean {
+  const expected = signUpload(upload);
+  if (presented.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < expected.length; i += 1) diff |= expected.charCodeAt(i) ^ presented.charCodeAt(i);
+  return diff === 0;
+}
+
+/** Where the upload_url points: the vendor's upload host when the request named the vendor's API host
+ *  (the injector's route), else the twin's own public base; vendor-real for an in-process call. */
+function uploadBase(ctx: PostingContext): string {
+  if (ctx.originalHost === API_HOST || !ctx.origin) return UPLOAD_ORIGIN;
+  return ctx.origin.replace(/\/+$/, '');
+}
+
+export async function initUpload(ctx: PostingContext, mode: 'direct' | 'inbox', rawBody: string | undefined): Promise<TikTokResponse> {
+  const refusal = needScope(ctx, [mode === 'direct' ? 'video.publish' : 'video.upload']);
+  if (refusal) return refusal;
+  const body = parseBody(rawBody);
+  if (!body) return postingError('invalid_param', ctx.at, 'The request body must be a JSON object.');
+
+  let postInfo: Record<string, unknown> = {};
+  if (mode === 'direct') {
+    const raw = body['post_info'];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return postingError('invalid_param', ctx.at, 'post_info is required.');
+    const p = raw as Record<string, unknown>;
+    // A missing privacy_level, or one this creator is not offered (any value outside creator_info's
+    // privacy_level_options), is the Direct Post reference's privacy_level_option_mismatch (403).
+    const privacy = p['privacy_level'];
+    if (typeof privacy !== 'string' || !creatorOptions(ctx.account).privacyLevelOptions.includes(privacy)) {
+      return postingError('privacy_level_option_mismatch', ctx.at, typeof privacy === 'string'
+        ? `privacy_level ${privacy} is not one of this creator's privacy_level_options.`
+        : 'post_info.privacy_level is required: one of the privacy_level_options creator_info answers.');
+    }
+    if (p['title'] !== undefined && typeof p['title'] !== 'string') return postingError('invalid_param', ctx.at, 'post_info.title must be a string.');
+    if (typeof p['title'] === 'string' && p['title'].length > MAX_TITLE_UTF16) return postingError('invalid_param', ctx.at, `post_info.title exceeds ${MAX_TITLE_UTF16} UTF-16 runes.`);
+    for (const flag of ['disable_duet', 'disable_comment', 'disable_stitch', 'brand_content_toggle', 'brand_organic_toggle', 'is_aigc']) {
+      if (p[flag] !== undefined && typeof p[flag] !== 'boolean') return postingError('invalid_param', ctx.at, `post_info.${flag} must be a boolean.`);
+    }
+    if (p['video_cover_timestamp_ms'] !== undefined && (!isInt(p['video_cover_timestamp_ms']) || (p['video_cover_timestamp_ms'] as number) < 0)) {
+      return postingError('invalid_param', ctx.at, 'post_info.video_cover_timestamp_ms must be a non-negative integer.');
+    }
+    postInfo = { ...p };
+  }
+
+  const source = body['source_info'];
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return postingError('invalid_param', ctx.at, 'source_info is required.');
+  const s = source as Record<string, unknown>;
+  if (s['source'] === 'PULL_FROM_URL') {
+    // The twin holds no verified URL prefixes or domains (a developer-portal setting), so every pull
+    // is the reference's own url_ownership_unverified — never a fetch of somebody's URL.
+    return postingError('url_ownership_unverified', ctx.at);
+  }
+  if (s['source'] !== 'FILE_UPLOAD') return postingError('invalid_param', ctx.at, 'source_info.source must be FILE_UPLOAD or PULL_FROM_URL.');
+  const plan = checkChunkPlan(s['video_size'], s['chunk_size'], s['total_chunk_count']);
+  if (plan) return postingError('invalid_param', ctx.at, plan);
+
+  if (mode === 'inbox') {
+    const since = nowMs(ctx.at) - 24 * 60 * 60 * 1000;
+    const pending = ctx.resources.filter((r) => r.type === 'publish' && (r as Row).mode === 'inbox' && (r as Row).accountId === ctx.account.id && Number((r as Row).finalizedAt) >= since).length;
+    if (pending >= MAX_PENDING_SHARES) return postingError('spam_risk_too_many_pending_share', ctx.at);
+  }
+  if (ctx.readOnly) return apiError('internal_error', ctx.at, 'This twin is read-only: nothing can be posted to it.');
+
+  const publishId = mintPublishId(mode);
+  const upload: TikTokUpload = {
+    uploadId: mintUploadId(),
+    publishId,
+    mode,
+    accountId: ctx.account.id,
+    clientKey: ctx.clientKey,
+    tokenSha256: ctx.tokenHash,
+    uploadSecret: Array.from(crypto.getRandomValues(new Uint8Array(32)), (b) => b.toString(16).padStart(2, '0')).join(''),
+    postInfo,
+    videoSize: s['video_size'] as number,
+    chunkSize: s['chunk_size'] as number,
+    totalChunkCount: s['total_chunk_count'] as number,
+    issuedAt: nowMs(ctx.at),
+    expiresAt: nowMs(ctx.at) + UPLOAD_URL_TTL_MS,
+  };
+  await writeUpload(upload, ctx.root);
+  const url = new URL(`${uploadBase(ctx)}${UPLOAD_PATH}/`);
+  url.searchParams.set('upload_id', upload.uploadId);
+  url.searchParams.set('upload_token', signUpload(upload));
+  return apiOk({ publish_id: publishId, upload_url: url.toString() }, ctx.at, `init:${publishId}`);
+}
+
+// ── the chunk PUT ────────────────────────────────────────────────────────────────────────────────
+// The guide publishes the STATUSES (201 all chunks in, 206 more to come, 400 bad headers or size,
+// 403 expired URL, 404 unknown upload, 416 range out of order) and no body; the twin answers each with
+// a short plain-text reason (EXTRAPOLATION: the live body is unpinned, `tiktok.content_posting.upload_bodies`).
+
+export type UploadRequest = {
+  /** Always PUT: the router sends nothing else to the upload path. */
+  method: string;
+  query: URLSearchParams;
+  headers?: Record<string, string>;
+  bytes?: Uint8Array;
+  at: string;
+  root?: string;
+  readOnly?: boolean;
+};
+
+function plain(status: number, text: string): TikTokResponse {
+  return { status, body: text, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } };
+}
+
+export async function uploadChunk(req: UploadRequest): Promise<TikTokResponse> {
+  if (req.readOnly) return plain(403, 'This twin is read-only.');
+  const upload = await readUpload(req.query.get('upload_id') ?? '', req.root);
+  if (!upload) return plain(404, 'No upload task has this upload_id.');
+  if (!uploadTokenValid(upload, req.query.get('upload_token') ?? '')) return plain(403, 'The upload_token does not authorize this upload.');
+  if (nowMs(req.at) >= upload.expiresAt && !upload.sha256) return plain(403, 'The upload URL has expired: it is valid for one hour after issuance.');
+
+  const header = (name: string) => req.headers?.[name];
+  const type = (header('content-type') ?? '').split(';')[0]!.trim().toLowerCase();
+  if (!VIDEO_TYPES.includes(type)) return plain(400, `Content-Type must be one of ${VIDEO_TYPES.join(', ')}.`);
+  const m = /^bytes (\d+)-(\d+)\/(\d+)$/.exec((header('content-range') ?? '').trim());
+  if (!m) return plain(400, 'Content-Range must be "bytes {FIRST_BYTE}-{LAST_BYTE}/{TOTAL_BYTE_LENGTH}".');
+  const first = Number(m[1]);
+  const last = Number(m[2]);
+  const total = Number(m[3]);
+  const bytes = req.bytes ?? new Uint8Array(0);
+  if (total !== upload.videoSize) return plain(400, `Content-Range total ${total} is not the video_size ${upload.videoSize} the upload was initialized with.`);
+  if (last < first || bytes.length !== last - first + 1) return plain(400, `Content-Range names ${last - first + 1} bytes; the body carries ${bytes.length}.`);
+  const declaredLength = header('content-length');
+  if (declaredLength !== undefined && Number(declaredLength) !== bytes.length) return plain(400, `Content-Length ${declaredLength} is not the body's ${bytes.length} bytes.`);
+
+  // a final PUT repeated after its answer was lost: the upload is already whole
+  const finalFirst = upload.chunkSize * (upload.totalChunkCount - 1);
+  const isFinal = first === finalFirst && last === upload.videoSize - 1;
+  if (upload.sha256) return isFinal ? { status: 201, body: '', headers: {} } : plain(416, 'This upload is already complete.');
+  const held = await stagedSize(upload.uploadId, req.root);
+  // every chunk is staged but the finalize did not finish (the process stopped between the last chunk
+  // and its answer): the repeated final PUT completes it — the finalize is idempotent by publish_id
+  if (held === upload.videoSize) {
+    if (!isFinal) return plain(416, 'Every chunk of this upload has arrived.');
+    await finalize(upload, (header('content-type') ?? '').split(';')[0]!.trim().toLowerCase(), req.at, req.root);
+    return { status: 201, body: '', headers: {} };
+  }
+  if (first !== held) return plain(416, `Chunks must be uploaded in order: the next chunk starts at byte ${held}.`);
+  const index = Math.floor(first / upload.chunkSize);
+  if (first !== index * upload.chunkSize || index >= upload.totalChunkCount) return plain(416, `Byte ${first} does not start a chunk of this upload.`);
+  const want = chunkLength(upload, index);
+  if (bytes.length !== want) return plain(400, `Chunk ${index + 1} of ${upload.totalChunkCount} must carry ${want} bytes, not ${bytes.length}.`);
+
+  await stageChunk(upload.uploadId, first, bytes, req.root);
+  if (index < upload.totalChunkCount - 1) return { status: 206, body: '', headers: {} };
+  await finalize(upload, type, req.at, req.root);
+  return { status: 201, body: '', headers: {} };
+}
+
+/**
+ * The final chunk landed: join the chunks, store the video content-addressed, check what TikTok's
+ * processing checks that the file itself can show — that it is a video file the twin can read
+ * (file_format_check_failed), its duration against the creator's maximum (duration_check_failed), its
+ * frame rate against 23–60 FPS (frame_rate_check_failed) and its picture size against 360–4096
+ * (picture_size_check_failed) — and make the ONE kernel write.
+ *
+ * ORDER, for a process that stops part-way: the bytes (content-addressed, so storing twice is a
+ * no-op), then the kernel write (skipped when the publish already exists), and only THEN the staging
+ * record's digest and the chunks' removal. A stop before the kernel write leaves every chunk staged,
+ * and the repeated final PUT runs this again.
+ */
+async function finalize(upload: TikTokUpload, contentType: string, at: string, root?: string): Promise<void> {
+  const whole = await joinStaged(upload.uploadId, root);
+  const blob = await putTikTokBlob(whole, root);
+  const probe = probeMp4(whole);
+
+  const finalizedAt = nowMs(at);
+  const completesAt = finalizedAt + processingMs(blob.size);
+  await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      if (resources.some((r) => r.type === 'publish' && r.id === upload.publishId)) return { kind: 'skip', value: undefined };
+      const account = resources.find((r) => r.type === 'account' && r.id === upload.accountId) as Row | undefined;
+      const max = account ? creatorOptions(account).maxDurationSec : DEFAULT_MAX_VIDEO_POST_DURATION_SEC;
+      // a file the reader cannot find a video track in is not a video TikTok can process
+      const failReason = probe.width === undefined || probe.height === undefined || probe.durationSeconds === undefined
+        ? 'file_format_check_failed'
+        : probe.durationSeconds > max
+          ? 'duration_check_failed'
+          : probe.frameRate !== undefined && (probe.frameRate < MIN_FRAME_RATE - 0.5 || probe.frameRate > MAX_FRAME_RATE + 0.5)
+            ? 'frame_rate_check_failed'
+            : Math.min(probe.width, probe.height) < MIN_SIDE || Math.max(probe.width, probe.height) > MAX_SIDE
+              ? 'picture_size_check_failed'
+              : null;
+      const media = {
+        _content_sha256: blob.sha256,
+        _content_type: contentType,
+        size: blob.size,
+        ...(probe.durationSeconds !== undefined ? { duration: Math.round(probe.durationSeconds) } : {}),
+        ...(probe.width !== undefined ? { width: probe.width, height: probe.height } : {}),
+      };
+      // a post id is drawn from entropy and RE-DRAWN while any id the branch holds — its own or an
+      // ancestor's, which the projection carries — already has it (the X and LinkedIn rule)
+      let postId: string | null = null;
+      if (upload.mode === 'direct' && !failReason) {
+        const held = new Set(resources.map((r) => String(r.id)));
+        do postId = mintPostId(); while (held.has(postId));
+      }
+      const publish = {
+        mode: upload.mode,
+        accountId: upload.accountId,
+        clientKey: upload.clientKey,
+        tokenSha256: upload.tokenSha256,
+        finalizedAt,
+        completesAt,
+        ...(failReason ? { failReason } : {}),
+        ...(postId ? { postId } : {}),
+        ...media,
+        rev: nextRevIn(resources, 'publish', upload.publishId),
+      };
+      if (postId) {
+        const p = upload.postInfo;
+        const caption = typeof p['title'] === 'string' ? p['title'] : '';
+        return {
+          kind: 'write',
+          value: undefined,
+          write: {
+            operation: 'video.publish',
+            subjectType: 'video',
+            subjectId: postId,
+            fields: {
+              ownerUnionId: upload.accountId,
+              publishId: upload.publishId,
+              // TikTok's post_info.title IS the caption; the Video Object reports a caption as its
+              // description (EXTRAPOLATION for `title`, pinned by tiktok.content_posting.caption_fields)
+              title: caption,
+              videoDescription: caption,
+              privacyLevel: p['privacy_level'],
+              disableComment: p['disable_comment'] === true,
+              disableDuet: p['disable_duet'] === true,
+              disableStitch: p['disable_stitch'] === true,
+              ...(typeof p['video_cover_timestamp_ms'] === 'number' ? { videoCoverTimestampMs: p['video_cover_timestamp_ms'] } : {}),
+              ...(p['brand_content_toggle'] === true ? { brandContentToggle: true } : {}),
+              ...(p['brand_organic_toggle'] === true ? { brandOrganicToggle: true } : {}),
+              ...(p['is_aigc'] === true ? { isAigc: true } : {}),
+              // it becomes a post when processing ends: /v2/video/list/ shows it from then
+              createTime: Math.floor(completesAt / 1000),
+              duration: media.duration ?? 0,
+              width: media.width ?? 0,
+              height: media.height ?? 0,
+              likeCount: 0,
+              commentCount: 0,
+              shareCount: 0,
+              viewCount: 0,
+              _content_sha256: blob.sha256,
+              _content_type: contentType,
+              rev: 1,
+            },
+            projection: { creates: [{ type: 'publish', id: upload.publishId, fields: publish }] },
+            occurredAt: at,
+            actor: { kind: 'agent' as const },
+          },
+        };
+      }
+      return {
+        kind: 'write',
+        value: undefined,
+        write: {
+          operation: failReason ? 'publish.fail' : 'video.inbox_upload',
+          subjectType: 'publish',
+          subjectId: upload.publishId,
+          fields: publish,
+          occurredAt: at,
+          actor: { kind: 'agent' as const },
+        },
+      };
+    },
+    root,
+  );
+  // the kernel holds the publish: now the staging record may say so, and the chunks may go
+  await writeUpload({ ...upload, sha256: blob.sha256 }, root);
+  await clearStaged(upload.uploadId, root);
+}
+
+// ── status/fetch ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The publish_id's lifecycle at World instant `at`. `publicaly_available_post_id` (the vendor's own
+ * spelling) is a list<int64>: the twin writes it as bare JSON NUMBERS, as TikTok does, so an
+ * integration that JSON.parse()s a 19-digit id into a double loses digits HERE rather than in
+ * production. It lists the post once it is public (PUBLIC_TO_EVERYONE) and complete.
+ */
+export async function fetchStatus(ctx: PostingContext, rawBody: string | undefined): Promise<TikTokResponse> {
+  const refusal = needScope(ctx, ['video.upload', 'video.publish']);
+  if (refusal) return refusal;
+  const body = parseBody(rawBody);
+  const publishId = body?.['publish_id'];
+  if (typeof publishId !== 'string' || publishId === '') return postingError('invalid_param', ctx.at, 'publish_id is required.');
+
+  const row = ctx.resources.find((r) => r.type === 'publish' && r.id === publishId) as Row | undefined;
+  const staging = row ? null : await readUploadByPublishId(publishId, ctx.root);
+  if (!row && !staging) return postingError('invalid_publish_id', ctx.at);
+  const owner = row ? { accountId: row.accountId, clientKey: row.clientKey } : { accountId: staging!.accountId, clientKey: staging!.clientKey };
+  if (owner.accountId !== ctx.account.id || owner.clientKey !== ctx.clientKey) return postingError('token_not_authorized_for_specified_publish_id', ctx.at);
+
+  let data: { status: string; fail_reason?: string; post?: string; uploaded_bytes: number };
+  if (!row) {
+    data = { status: 'PROCESSING_UPLOAD', uploaded_bytes: await stagedSize(staging!.uploadId, ctx.root) };
+  } else if (typeof row.failReason === 'string') {
+    data = { status: 'FAILED', fail_reason: row.failReason, uploaded_bytes: Number(row.size ?? 0) };
+  } else if (nowMs(ctx.at) < Number(row.completesAt)) {
+    data = { status: 'PROCESSING_UPLOAD', uploaded_bytes: Number(row.size ?? 0) };
+  } else if (row.mode === 'inbox') {
+    data = { status: 'SEND_TO_USER_INBOX', uploaded_bytes: Number(row.size ?? 0) };
+  } else {
+    const video = ctx.resources.find((r) => r.type === 'video' && r.id === row.postId) as Row | undefined;
+    const isPublic = video?.privacyLevel === 'PUBLIC_TO_EVERYONE';
+    data = { status: 'PUBLISH_COMPLETE', uploaded_bytes: Number(row.size ?? 0), ...(isPublic && typeof row.postId === 'string' ? { post: row.postId } : {}) };
+  }
+  const logid = logId(ctx.at, `api:ok:status:${publishId}:${data.status}`);
+  // hand-serialized so the int64 ids stay bare numbers (JSON.stringify of a JS number would round them)
+  const text = `{"data":{"status":${JSON.stringify(data.status)},${data.fail_reason ? `"fail_reason":${JSON.stringify(data.fail_reason)},` : ''}`
+    + `"publicaly_available_post_id":[${data.post && /^\d+$/.test(data.post) ? data.post : ''}],"uploaded_bytes":${data.uploaded_bytes}},`
+    + `"error":{"code":"ok","message":"","log_id":${JSON.stringify(logid)}}}`;
+  return { status: 200, body: text, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache, no-store, max-age=0' } };
+}
+
+// ── the published video's bytes ──────────────────────────────────────────────────────────────────
+// TikTok plays a post from its CDN, which is not Open API surface. The twin serves a published video's
+// bytes on its own origin, under its public base, at `/_twin/media/video/<post id>`, so the mirror (or
+// any client) plays exactly what was uploaded — here or at a branch's ancestor. Range is honoured (206
+// + Content-Range, 416 past the end), only the range asked for is read, and an open-ended range is
+// capped at MAX_SERVED_RANGE (a player asks again from where it got to). A post that is not
+// PUBLIC_TO_EVERYONE plays only for its creator: a <video> element sends no header, so the creator's
+// token rides the URL as `access_token`.
+
+export const MEDIA_PREFIX = '/_twin/media/video/';
+/** The most one open-ended range answers (`bytes=N-`): 8 MiB. */
+export const MAX_SERVED_RANGE = 8 * 1024 * 1024;
+
+type ParsedRange = { start: number; end: number } | 'unsatisfiable' | null;
+function parseRange(value: string | undefined, size: number): ParsedRange {
+  if (!value) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(value.trim());
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  if (m[1] === '') {
+    const n = Number(m[2]);
+    if (n === 0 || size === 0) return 'unsatisfiable';
+    return { start: Math.max(0, size - Math.min(n, MAX_SERVED_RANGE)), end: size - 1 };
+  }
+  const start = Number(m[1]);
+  if (start >= size) return 'unsatisfiable';
+  // a last-byte-pos below the first-byte-pos is an INVALID range, which RFC 9110 §14.1.1 says to
+  // ignore: the whole representation is answered (200), not a 416
+  if (m[2] !== '' && Number(m[2]) < start) return null;
+  const end = m[2] === '' ? Math.min(size - 1, start + MAX_SERVED_RANGE - 1) : Math.min(Number(m[2]), size - 1, start + MAX_SERVED_RANGE - 1);
+  return { start, end };
+}
+
+export type MediaRequest = { method: string; path: string; query: URLSearchParams; headers?: Record<string, string>; at: string; root?: string; resources: readonly TwinResource[] };
+
+export async function serveVideo(req: MediaRequest): Promise<TikTokResponse> {
+  const missing = (): TikTokResponse => ({ status: 404, body: new Uint8Array(0), headers: { 'content-type': 'text/plain' } });
+  const method = req.method.toUpperCase();
+  if (method !== 'GET' && method !== 'HEAD') return { status: 405, body: new Uint8Array(0), headers: { allow: 'GET, HEAD' } };
+  const id = req.path.slice(MEDIA_PREFIX.length).replace(/\.mp4$/, '');
+  const video = req.resources.find((r) => r.type === 'video' && r.id === id) as Row | undefined;
+  // a post plays once it IS a post: while processing it is not on the profile, and neither are its bytes
+  if (!video || Number(video.createTime) > Math.floor(nowMs(req.at) / 1000)) return missing();
+  const sha256 = String(video._content_sha256 ?? '');
+  const size = await tikTokBlobSize(sha256, req.root);
+  if (size === null) return missing();
+  if (video.privacyLevel !== undefined && video.privacyLevel !== 'PUBLIC_TO_EVERYONE') {
+    const presented = req.query.get('access_token') ?? /^bearer\s+(.+)$/i.exec(req.headers?.['authorization'] ?? '')?.[1]?.trim();
+    const token = presented ? req.resources.find((r) => r.type === BK_ACCESS && r.id === secretKey(presented)) as Row | undefined : undefined;
+    if (!token || token.revoked === true || token.sub !== video.ownerUnionId) {
+      return { status: 403, body: new TextEncoder().encode('This video is private.'), headers: { 'content-type': 'text/plain' } };
+    }
+  }
+  const base = { 'content-type': String(video._content_type ?? 'video/mp4'), 'accept-ranges': 'bytes', etag: `"${sha256}"`, 'cache-control': 'private, max-age=0' };
+  const head = method === 'HEAD';
+  const range = parseRange(req.headers?.['range'], size);
+  if (range === 'unsatisfiable') return { status: 416, body: new Uint8Array(0), headers: { ...base, 'content-range': `bytes */${size}` } };
+  if (range) {
+    const headers = { ...base, 'content-range': `bytes ${range.start}-${range.end}/${size}`, 'content-length': String(range.end - range.start + 1) };
+    if (head) return { status: 206, body: new Uint8Array(0), headers };
+    return { status: 206, body: (await readTikTokBlobRange(sha256, range.start, range.end, req.root)) ?? new Uint8Array(0), headers };
+  }
+  const headers = { ...base, 'content-length': String(size) };
+  if (head) return { status: 200, body: new Uint8Array(0), headers };
+  let at = 0;
+  const root = req.root;
+  const stream = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      if (at >= size) { controller.close(); return; }
+      const piece = await readTikTokBlobRange(sha256, at, Math.min(size - 1, at + MAX_SERVED_RANGE - 1), root);
+      if (!piece || piece.length === 0) { controller.close(); return; }
+      controller.enqueue(piece);
+      at += piece.length;
+    },
+  });
+  return { status: 200, body: stream, headers };
+}