@volter/twin-tiktok 0.1.0

package/dist/src/tiktok-mirror-ui.js

@@ -0,0 +1,159 @@
+// TIKTOK MIRROR UI — tiktok.com's own view of the twin's state: sign in as the creator, read their
+// profile (avatar, @handle, nickname, the Following / Followers / Likes counts, bio) over the 9:16
+// Videos grid, and open a post in the full-height vertical player with its caption and @handle. A
+// React/TSX app bundled by Bun that renders by consuming the twin's OWN API on the same origin —
+// `GET /v2/user/info/` and `POST /v2/video/list/`, the Display API reads any TikTok client makes —
+// and plays the posted bytes from the twin's media route, so every screen is data-coupled to real
+// twin state. Archetype A (passthrough), transcribed from the X and YouTube mirrors: one serving code
+// path, so API<->UI parity cannot drift.
+//
+// NOTHING IS INVENTED. A count the Display API does not return (a token without user.info.stats, a
+// persona seeded without it) is not drawn; a zero is drawn only when the twin holds a zero. Avatars
+// the twin holds no image for (the vendor's CDN URLs a seeded persona carries) are drawn as the
+// creator's initial.
+//
+// SIGN-IN. TikTok's "Log in" form (username, then the password) with the password leg replaced by the
+// user access token the twin issued through /_twin/tokens: the mirror presents a registered token and
+// `/v2/user/info/` says which creator it is — a token for another account is refused on the form.
+// Both are kept in the TAB'S sessionStorage.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's own
+// fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse, serveHttp } from '@volter/world-core';
+import { createTikTokTwinFetch } from "./tiktok-server.js";
+const CLIENT_ENTRY = () => new URL('../client/tiktok-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/tiktok-mirror.css', import.meta.url).pathname; // lazy: same reason
+/** The user fields the profile reads — every one the Display API gates behind the three user scopes. */
+export const PROFILE_FIELDS = 'open_id,union_id,avatar_url,display_name,username,bio_description,is_verified,follower_count,following_count,likes_count,video_count';
+/** The fields a token holding only user.info.basic may ask for (the header then carries no counts). */
+export const BASIC_FIELDS = 'open_id,union_id,avatar_url,display_name';
+/** The Video Object fields the grid and the player read. */
+export const VIDEO_READ_FIELDS = 'id,create_time,title,video_description,duration,width,height,like_count,comment_count,share_count,view_count';
+/** The Display API's own page maximum. */
+export const VIDEO_PAGE_SIZE = 20;
+/** tiktok.com's count: exact under 10,000 ("1280"), then one decimal of K or M ("45.1K", "1.4M"),
+ *  the trailing ".0" dropped ("12K"). */
+export function compactCount(raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return '0';
+    const scaled = (value, unit) => `${String(Math.floor(value * 10) / 10).replace(/\.0$/, '')}${unit}`;
+    if (n >= 1e9)
+        return scaled(n / 1e9, 'B');
+    if (n >= 1e6)
+        return scaled(n / 1e6, 'M');
+    if (n >= 1e4)
+        return scaled(n / 1e3, 'K');
+    return String(Math.floor(n));
+}
+/** The profile header's three counts, each only when the twin returned it. */
+export function profileStats(user) {
+    const out = [];
+    if (typeof user?.following_count === 'number')
+        out.push({ label: 'Following', value: compactCount(user.following_count) });
+    if (typeof user?.follower_count === 'number')
+        out.push({ label: 'Followers', value: compactCount(user.follower_count) });
+    if (typeof user?.likes_count === 'number')
+        out.push({ label: 'Likes', value: compactCount(user.likes_count) });
+    return out;
+}
+/** A caption split the way tiktok.com bolds it: #hashtags and @mentions are links, the rest text. */
+export function captionSegments(text) {
+    const source = typeof text === 'string' ? text : '';
+    const out = [];
+    let last = 0;
+    for (const m of source.matchAll(/(#[\p{L}\p{N}_]+)|(@[A-Za-z0-9_.]{2,24})/gu)) {
+        const at = m.index ?? 0;
+        if (at > 0 && /[\p{L}\p{N}_]/u.test(source[at - 1]))
+            continue;
+        if (at > last)
+            out.push({ kind: 'text', value: source.slice(last, at) });
+        out.push({ kind: m[1] ? 'hashtag' : 'mention', value: m[0] });
+        last = at + m[0].length;
+    }
+    if (last < source.length)
+        out.push({ kind: 'text', value: source.slice(last) });
+    return out;
+}
+/** The caption a post shows: the Video Object's description, else its title. */
+export function captionOf(video) {
+    const description = typeof video?.video_description === 'string' ? video.video_description : '';
+    return description !== '' ? description : typeof video?.title === 'string' ? video.title : '';
+}
+/** "0:03", "1:02" — the player's time readout. */
+export function clock(seconds) {
+    const s = Math.max(0, Math.floor(Number(seconds) || 0));
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
+}
+/** A post's bytes on the twin's media route, relative to the wire base. The creator's token rides the
+ *  URL (a <video> element sends no header), which is what a post that is not public needs. */
+export function mediaSource(base, videoId, token) {
+    return `${base}/_twin/media/video/${encodeURIComponent(videoId)}?access_token=${encodeURIComponent(token)}`;
+}
+/** The avatar placeholder's letter and hue: pure functions of the account. */
+export function avatarInitial(user) {
+    const source = String(user?.display_name ?? user?.username ?? '?').trim();
+    return (Array.from(source)[0] ?? '?').toUpperCase();
+}
+export function avatarHue(key) {
+    const s = String(key ?? '');
+    let h = 0;
+    for (let i = 0; i < s.length; i += 1)
+        h = (h * 31 + s.charCodeAt(i)) % 360;
+    return h;
+}
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>TikTok - Make Your Day</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+/** Build the React/TSX mirror client to browser JS; memoized, so a pack does exactly one Bun.build. */
+export function buildTiktokMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/** Serve the TikTok mirror UI (React app) + its backing API, upload and media routes on one origin. */
+export async function createTiktokMirrorServer(options) {
+    const twin = createTikTokTwinFetch(options);
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind, as the X and YouTube mirrors: a wildcard bind on `port: 0` can be
+        // shadowed by an app already listening on 127.0.0.1 at the same port.
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildTiktokMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // Everything else -> the twin's OWN FETCH ADAPTER: Login Kit, the Display API, Content Posting,
+            // the upload path and the media route, the same closure `createTikTokTwinServer` serves.
+            return twin(request);
+        },
+    });
+    const port = server.port ?? options.port ?? 0;
+    return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}
+/** The app-shell HTML (pure). The client itself is the React app. */
+export function tiktokMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function tiktokMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/tiktok-pkce.d.ts

@@ -0,0 +1,25 @@
+/** TikTok's `code_challenge`: the LOWERCASE HEX SHA-256 of the verifier (not base64url). */
+export declare function tiktokCodeChallenge(verifier: string): string;
+/** The RFC 7636 spelling, kept ONLY so a verify can prove the twin refuses it — TikTok does not
+ *  accept it, and a caller that carried an X/Google-shaped challenge here must fail visibly. */
+export declare function rfc7636Challenge(verifier: string): string;
+/** The only `code_challenge_method` TikTok supports, per the desktop guide, verbatim: `S256`. */
+export declare const CHALLENGE_METHOD = "S256";
+/**
+ * Is `raw` a code_challenge_method TikTok accepts? Only `S256` is documented ("TikTok only
+ * supports S256"), and unlike X there is no `plain` fallback to model. The comparison is
+ * case-SENSITIVE: no vendor artefact shows TikTok accepting `s256`, and inventing a tolerance
+ * would be the inverse false-green (`tiktok.authorize.challenge_method_case`, todo).
+ */
+export declare function isSupportedChallengeMethod(raw: string): boolean;
+/**
+ * Does `verifier` satisfy the challenge the code was minted against?
+ *
+ * The verifier must also be a well-formed one: "a high-entropy cryptographic random string using
+ * the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length
+ * of 43 characters and a maximum length of 128 characters" (the desktop guide, verbatim). A
+ * malformed verifier can never satisfy a challenge, so the shape check is folded in here rather
+ * than left to a caller that might forget it.
+ */
+export declare function pkceVerifies(challenge: string, verifier: string): boolean;
+export declare function isWellFormedVerifier(verifier: string): boolean;

package/dist/src/tiktok-pkce.js

@@ -0,0 +1,56 @@
+// PKCE, TikTok's way — and TikTok's way is NOT RFC 7636's, which is the whole reason this file
+// exists instead of a copied helper.
+//
+// RFC 7636 §4.2 defines `S256` as BASE64URL(SHA256(verifier)). TikTok's Login Kit for Desktop
+// guide says instead: "Create the code challenge by hashing the code verifier using hex encoding
+// of SHA256. Since TikTok only supports S256 as code_challenge_method, use code_challenge =
+// SHA256(code_verifier)" — i.e. the challenge is the 64-character LOWERCASE HEX digest
+// (developers.tiktok.com/doc/login-kit-desktop, fetched 2026-09-13). A twin that verified the
+// base64url form would accept challenges the real vendor rejects and reject the ones it accepts,
+// which is precisely the class of bug a twin exists to reproduce.
+//
+// PKCE IS OPTIONAL ON THIS VENDOR. The desktop guide requires it "for desktop apps"; the Login
+// Kit for Web parameter table lists neither `code_challenge` nor `code_challenge_method`, and the
+// token endpoint's own parameter table marks `code_verifier` "Required for mobile and desktop app
+// only". Dub — a web app — sends no challenge at all. So the twin BINDS a verifier only when the
+// authorize request carried a challenge, and requires none when it did not. Requiring PKCE the
+// way X requires it would refuse the motivating application outright.
+import { createHash } from 'node:crypto';
+/** TikTok's `code_challenge`: the LOWERCASE HEX SHA-256 of the verifier (not base64url). */
+export function tiktokCodeChallenge(verifier) {
+    return createHash('sha256').update(verifier).digest('hex');
+}
+/** The RFC 7636 spelling, kept ONLY so a verify can prove the twin refuses it — TikTok does not
+ *  accept it, and a caller that carried an X/Google-shaped challenge here must fail visibly. */
+export function rfc7636Challenge(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+/** The only `code_challenge_method` TikTok supports, per the desktop guide, verbatim: `S256`. */
+export const CHALLENGE_METHOD = 'S256';
+/**
+ * Is `raw` a code_challenge_method TikTok accepts? Only `S256` is documented ("TikTok only
+ * supports S256"), and unlike X there is no `plain` fallback to model. The comparison is
+ * case-SENSITIVE: no vendor artefact shows TikTok accepting `s256`, and inventing a tolerance
+ * would be the inverse false-green (`tiktok.authorize.challenge_method_case`, todo).
+ */
+export function isSupportedChallengeMethod(raw) {
+    return raw === CHALLENGE_METHOD;
+}
+/**
+ * Does `verifier` satisfy the challenge the code was minted against?
+ *
+ * The verifier must also be a well-formed one: "a high-entropy cryptographic random string using
+ * the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length
+ * of 43 characters and a maximum length of 128 characters" (the desktop guide, verbatim). A
+ * malformed verifier can never satisfy a challenge, so the shape check is folded in here rather
+ * than left to a caller that might forget it.
+ */
+export function pkceVerifies(challenge, verifier) {
+    if (!isWellFormedVerifier(verifier))
+        return false;
+    return tiktokCodeChallenge(verifier) === challenge;
+}
+const VERIFIER_RE = /^[A-Za-z0-9\-._~]{43,128}$/;
+export function isWellFormedVerifier(verifier) {
+    return VERIFIER_RE.test(verifier);
+}

package/dist/src/tiktok-posting.d.ts

@@ -0,0 +1,100 @@
+import { type TwinResource } from '@volter/world-core';
+import { type TikTokUpload } from './tiktok-blobs.js';
+import { type TikTokResponse } from './tiktok-errors.js';
+import { type Row } from './tiktok-store.js';
+/** The vendor's own upload host, and the path its upload_url carries. */
+export declare const UPLOAD_ORIGIN = "https://open-upload.tiktokapis.com";
+export declare const UPLOAD_PATH = "/video";
+/** "The upload_url is valid for one hour after issuance. The upload must be completed in this time range." */
+export declare const UPLOAD_URL_TTL_MS: number;
+export declare const MIN_CHUNK_BYTES: number;
+export declare const MAX_CHUNK_BYTES: number;
+export declare const MAX_FINAL_CHUNK_BYTES: number;
+export declare const MAX_CHUNK_COUNT = 1000;
+export declare const MAX_VIDEO_BYTES: number;
+/**
+ * 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 declare const TWIN_MAX_VIDEO_BYTES: number;
+/** "Framerate: 23–60 FPS" (media transfer guide). */
+export declare const MIN_FRAME_RATE = 23;
+export declare 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 declare function processingMs(size: number): number;
+/** Direct Post `privacy_level` values ("PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY"). */
+export declare const PRIVACY_LEVELS: readonly ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "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 declare const DEFAULT_MAX_VIDEO_POST_DURATION_SEC = 600;
+/** "Title: max 2200 UTF-16 runes" — `String.length` counts UTF-16 code units. */
+export declare const MAX_TITLE_UTF16 = 2200;
+/** "max 5 pending shares per 24 hours" (inbox upload reference, spam_risk_too_many_pending_share). */
+export declare const MAX_PENDING_SHARES = 5;
+/** 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;
+};
+/** What creator_info answers for an account — every value from the account row, the reference's
+ *  defaults where the row names none. */
+export declare function creatorOptions(account: Row): {
+    privacyLevelOptions: string[];
+    commentDisabled: boolean;
+    duetDisabled: boolean;
+    stitchDisabled: boolean;
+    maxDurationSec: number;
+};
+export declare function creatorInfo(ctx: PostingContext): TikTokResponse;
+/** The chunk plan a FILE_UPLOAD init names, checked against the guide's rules; a string is the refusal. */
+export declare function checkChunkPlan(videoSize: unknown, chunkSize: unknown, count: unknown): string | null;
+/** The byte length chunk `index` must carry under an upload's plan. */
+export declare function chunkLength(upload: Pick<TikTokUpload, 'videoSize' | 'chunkSize' | 'totalChunkCount'>, index: number): number;
+export declare function initUpload(ctx: PostingContext, mode: 'direct' | 'inbox', rawBody: string | undefined): Promise<TikTokResponse>;
+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;
+};
+export declare function uploadChunk(req: UploadRequest): Promise<TikTokResponse>;
+/**
+ * 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 declare function fetchStatus(ctx: PostingContext, rawBody: string | undefined): Promise<TikTokResponse>;
+export declare const MEDIA_PREFIX = "/_twin/media/video/";
+/** The most one open-ended range answers (`bytes=N-`): 8 MiB. */
+export declare const MAX_SERVED_RANGE: number;
+export type MediaRequest = {
+    method: string;
+    path: string;
+    query: URLSearchParams;
+    headers?: Record<string, string>;
+    at: string;
+    root?: string;
+    resources: readonly TwinResource[];
+};
+export declare function serveVideo(req: MediaRequest): Promise<TikTokResponse>;