npm - @volter/twin-tiktok - Versions diffs - 0.1.0 - Mend

@volter/twin-tiktok 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/LICENSE +202 -0
package/README.md +310 -0
package/client/tiktok-consent.tsx +154 -0
package/client/tiktok-mirror.css +137 -0
package/client/tiktok-mirror.tsx +492 -0
package/dist/client/tiktok-consent.bundle.js +18 -0
package/dist/client/tiktok-consent.d.ts +47 -0
package/dist/client/tiktok-consent.js +20 -0
package/dist/client/tiktok-consent.tsx +154 -0
package/dist/client/tiktok-mirror.bundle.js +487 -0
package/dist/client/tiktok-mirror.css +137 -0
package/dist/client/tiktok-mirror.d.ts +42 -0
package/dist/client/tiktok-mirror.js +315 -0
package/dist/client/tiktok-mirror.tsx +492 -0
package/dist/src/cli.d.ts +2 -0
package/dist/src/cli.js +44 -0
package/dist/src/index.d.ts +22 -0
package/dist/src/index.js +167 -0
package/dist/src/tiktok-blobs.d.ts +66 -0
package/dist/src/tiktok-blobs.js +161 -0
package/dist/src/tiktok-budget.d.ts +56 -0
package/dist/src/tiktok-budget.js +136 -0
package/dist/src/tiktok-capabilities.d.ts +7 -0
package/dist/src/tiktok-capabilities.js +1855 -0
package/dist/src/tiktok-conformance.d.ts +11 -0
package/dist/src/tiktok-conformance.js +498 -0
package/dist/src/tiktok-connector.d.ts +158 -0
package/dist/src/tiktok-connector.js +600 -0
package/dist/src/tiktok-consent-ui.d.ts +19 -0
package/dist/src/tiktok-consent-ui.js +127 -0
package/dist/src/tiktok-errors.d.ts +78 -0
package/dist/src/tiktok-errors.js +175 -0
package/dist/src/tiktok-ids.d.ts +16 -0
package/dist/src/tiktok-ids.js +48 -0
package/dist/src/tiktok-media.d.ts +7 -0
package/dist/src/tiktok-media.js +86 -0
package/dist/src/tiktok-mirror-ui.d.ts +49 -0
package/dist/src/tiktok-mirror-ui.js +159 -0
package/dist/src/tiktok-pkce.d.ts +25 -0
package/dist/src/tiktok-pkce.js +56 -0
package/dist/src/tiktok-posting.d.ts +100 -0
package/dist/src/tiktok-posting.js +599 -0
package/dist/src/tiktok-sample-mp4.d.ts +10 -0
package/dist/src/tiktok-sample-mp4.js +55 -0
package/dist/src/tiktok-scopes.d.ts +29 -0
package/dist/src/tiktok-scopes.js +106 -0
package/dist/src/tiktok-server.d.ts +28 -0
package/dist/src/tiktok-server.js +89 -0
package/dist/src/tiktok-store.d.ts +164 -0
package/dist/src/tiktok-store.js +451 -0
package/dist/src/tiktok-twin.d.ts +70 -0
package/dist/src/tiktok-twin.js +1197 -0
package/dist/src/tiktok-user.d.ts +28 -0
package/dist/src/tiktok-user.js +174 -0
package/package.json +74 -0
package/src/cli.ts +43 -0
package/src/index.ts +270 -0
package/src/tiktok-blobs.ts +217 -0
package/src/tiktok-budget.ts +163 -0
package/src/tiktok-capabilities.ts +2022 -0
package/src/tiktok-conformance.ts +526 -0
package/src/tiktok-connector.ts +637 -0
package/src/tiktok-consent-ui.ts +146 -0
package/src/tiktok-errors.ts +197 -0
package/src/tiktok-ids.ts +51 -0
package/src/tiktok-journey.uitest.ts +305 -0
package/src/tiktok-media.ts +89 -0
package/src/tiktok-mirror-ui.ts +167 -0
package/src/tiktok-pkce.ts +61 -0
package/src/tiktok-posting.ts +617 -0
package/src/tiktok-sample-mp4.ts +54 -0
package/src/tiktok-scopes.ts +122 -0
package/src/tiktok-server.ts +100 -0
package/src/tiktok-store.ts +543 -0
package/src/tiktok-twin.ts +1361 -0
package/src/tiktok-user.ts +137 -0

package/src/tiktok-journey.uitest.ts ADDED Viewed

@@ -0,0 +1,305 @@
+// TIKTOK UI JOURNEY — the authorization leg, driven in a real headless chromium.
+//
+// The browser is the protocol participant: the app redirects, a human reads what the app is asking
+// for, DECIDES WHICH PERMISSIONS TO LEAVE ON, and clicks Continue (or Cancel). The browser is
+// bounced back to the app's callback carrying a code and the granted `scopes` — which the test then
+// REDEEMS at the twin's token endpoint and USES at the Display API. A journey that stopped at "the
+// screen rendered" would prove the page exists; this one proves the round trip closes, and that the
+// person's per-scope decision really reaches the token.
+//
+// Seeds through the pack's OWN write path (the twin-only client/session controls and the real
+// authorize endpoint — never a hand-written events.jsonl), boots the real twin handler on an
+// ephemeral port with the app's callback page alongside it, and drives it with role/text locators
+// only. Every step writes a filmstrip frame (the harness helpers do it), so a reviewer can LOOK at
+// the screens rather than trusting a green tick.
+import { describe, expect, test } from 'bun:test';
+import { atPath, clickByName, requireBrowser, runUiJourney, visible } from '@volter/world-tooling';
+import { DEFAULT_ACCOUNTS } from './tiktok-store.ts';
+import { handleTikTokTwinRequest } from './tiktok-twin.ts';
+const JOURNEY_LABEL = 'tiktok UI journey';
+const CLIENT_KEY = 'awjourneyapp000001';
+const CLIENT_SECRET = 'journey-secret-0000';
+const APP_NAME = 'Twin Journey Scheduler';
+const SCOPE = 'user.info.basic,user.info.profile,video.list';
+const ADA = DEFAULT_ACCOUNTS[0]!;
+/** The integrating app's callback, served on the same loopback origin (see `startJourneyServer`). */
+const APP_CALLBACK_PATH = '/oauth/callback';
+/**
+ * The journey's server: the REAL twin handler, plus a tiny `/oauth/callback` page standing in for
+ * the integrating app.
+ *
+ * WHY THEY SHARE ONE ORIGIN. The journey harness is loopback-only and installs a route guard that
+ * ABORTS any request leaving the server origin it was given — so a callback server on its own port
+ * is unreachable from the piloted page. Sharing the loopback origin is a harness accommodation, not
+ * a fidelity claim; the SDK fidelity test exercises the ordinary cross-origin configuration. What
+ * the journey proves is the leg only a browser can: a human's clicks turning into a code and a
+ * granted scope set on the app's callback URL.
+ */
+function startJourneyServer(root: string): { url: string; stop: () => void; last: () => URL | null } {
+  let last: URL | null = null;
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    idleTimeout: 30,
+    async fetch(request) {
+      const url = new URL(request.url);
+      // ── the harness's landing page ──
+      // `runUiJourney` navigates to the server URL and waits for `#root` to have children before it
+      // hands the page over. A vendor twin has no app shell at `/` (tiktok.com's root is the For
+      // You feed, which this pack does not model), so the JOURNEY supplies one. Test scaffolding in
+      // this file — never pack surface.
+      if (url.pathname === '/') {
+        return new Response(
+          `<!doctype html><html><body><div id="root"><h1>Twin TikTok world</h1>`
+            + `<p>the ${APP_NAME} integration starts by redirecting to the tiktok.com authorization page</p></div></body></html>`,
+          { headers: { 'content-type': 'text/html; charset=utf-8' } },
+        );
+      }
+      // ── the app's callback ──
+      if (url.pathname === APP_CALLBACK_PATH) {
+        last = url;
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        const body = code
+          ? `<h1>${APP_NAME}</h1><p>authorization code received</p><pre>${code}</pre><p>granted: ${url.searchParams.get('scopes')}</p>`
+          : `<h1>${APP_NAME}</h1><p>authorization failed</p><pre>${error ?? 'no error parameter'}</pre>`;
+        return new Response(`<!doctype html><html><body>${body}</body></html>`, {
+          headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
+      }
+      // ── everything else: the real twin ──
+      const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+      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,
+        root,
+        occurredAt: new Date().toISOString(),
+        origin: url.origin,
+      });
+      const out = { ...(res.headers ?? {}) };
+      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 });
+    },
+  });
+  return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop(true), last: () => last };
+}
+/** Register the journey's TikTok app through the twin's own write path. */
+async function seedClient(twinOrigin: string, redirectUri: string) {
+  const res = await fetch(`${twinOrigin}/_twin/clients`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ client_key: CLIENT_KEY, client_secret: CLIENT_SECRET, name: APP_NAME, redirect_uris: [redirectUri] }),
+  });
+  expect(res.status).toBe(200);
+}
+const authUrl = (twinOrigin: string, redirectUri: string, extra: Record<string, string> = {}) =>
+  `${twinOrigin}/v2/auth/authorize?${new URLSearchParams({
+    client_key: CLIENT_KEY,
+    response_type: 'code',
+    redirect_uri: redirectUri,
+    scope: SCOPE,
+    state: 'journey-state-1',
+    ...extra,
+  })}`;
+describe('tiktok UI journey', () => {
+  test('a human reads the authorization page, clicks Continue — and the code redeems into a usable identity', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    // Captured inside the journey while the server is still up; asserted after teardown, so a
+    // torn-down fixture can never read as a product failure.
+    let redeemed: Record<string, any> | null = null;
+    let identity: Record<string, any> | null = null;
+    let callback: URL | null = null;
+    await runUiJourney({
+      label: 'tiktok authorization round trip',
+      // The pack's write path IS its HTTP server, and the harness calls `seed` BEFORE `serve` — so
+      // the app registration happens as the journey's first step instead of here.
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+        // 1. The app redirects the browser to the vendor. What lands is TikTok's AUTHORIZATION
+        //    page, naming the registered app, the signed-in account, and the scopes in the
+        //    vendor's own published wording.
+        await page.goto(authUrl(origin, redirectUri));
+        await atPath(page, '/v2/auth/authorize');
+        await visible(page, `${APP_NAME} would like to access your TikTok account`);
+        await visible(page, ADA.displayName);
+        await visible(page, `@${ADA.username}`);
+        await visible(page, "Read a user's profile info (open id, avatar, display name...)");
+        await visible(page, "Read a user's public videos on TikTok");
+        // 2. Continue. The browser leaves the vendor's path and lands on the APP's callback.
+        await clickByName(page, 'Continue');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization code received');
+        callback = new URL(page.url());
+        const code = callback.searchParams.get('code')!;
+        // 3. THE POINT OF THE WHOLE FLOW: the code a browser CLICK produced is redeemable at the
+        //    token endpoint, and the token it yields answers the Display API with the account that
+        //    was signed in on the screen.
+        const tokenRes = await fetch(`${origin}/v2/oauth/token/`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({
+            client_key: CLIENT_KEY,
+            client_secret: CLIENT_SECRET,
+            code,
+            grant_type: 'authorization_code',
+            redirect_uri: redirectUri,
+          }).toString(),
+        });
+        redeemed = (await tokenRes.json()) as Record<string, any>;
+        const me = await fetch(`${origin}/v2/user/info/?fields=open_id,union_id,username`, {
+          headers: { authorization: `Bearer ${redeemed.access_token}` },
+        });
+        identity = (await me.json()) as Record<string, any>;
+      },
+    });
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(callback!.searchParams.get('scopes')).toBe(SCOPE);
+    expect(redeemed!.token_type).toBe('Bearer');
+    expect(redeemed!.scope).toBe(SCOPE);
+    expect(String(redeemed!.refresh_token)).toMatch(/^rft\./);
+    // The account that was on the screen is the identity the token yields — the click really
+    // consented as that person.
+    expect(identity!.data.user.union_id).toBe(ADA.unionId);
+    expect(identity!.data.user.username).toBe(ADA.username);
+  }, 30_000);
+  test('unchecking a permission narrows the grant — the callback and the token both say so, and the Display API refuses the field', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let callback: URL | null = null;
+    let refusal: Record<string, any> | null = null;
+    let redeemed: Record<string, any> | null = null;
+    await runUiJourney({
+      label: 'tiktok granular consent',
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+        await page.goto(authUrl(origin, redirectUri));
+        // The person switches OFF the profile permission before continuing — the decision TikTok's
+        // own `scopes` callback parameter exists to report.
+        await page.locator('input[value="user.info.profile"]').uncheck();
+        await clickByName(page, 'Continue');
+        await atPath(page, APP_CALLBACK_PATH);
+        callback = new URL(page.url());
+        const tokenRes = await fetch(`${origin}/v2/oauth/token/`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({
+            client_key: CLIENT_KEY,
+            client_secret: CLIENT_SECRET,
+            code: callback.searchParams.get('code')!,
+            grant_type: 'authorization_code',
+            redirect_uri: redirectUri,
+          }).toString(),
+        });
+        redeemed = (await tokenRes.json()) as Record<string, any>;
+        const me = await fetch(`${origin}/v2/user/info/?fields=username`, {
+          headers: { authorization: `Bearer ${redeemed.access_token}` },
+        });
+        refusal = (await me.json()) as Record<string, any>;
+      },
+    });
+    expect(callback!.searchParams.get('scopes')).toBe('user.info.basic,video.list');
+    expect(redeemed!.scope).toBe('user.info.basic,video.list');
+    expect(refusal!.error.code).toBe('scope_not_authorized');
+  }, 30_000);
+  test('Cancel bounces back with error=access_denied and no code', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let callback: URL | null = null;
+    await runUiJourney({
+      label: 'tiktok authorization denial',
+      seed: async () => {},
+      serve: (root) => startJourneyServer(root),
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        const redirectUri = `${origin}${APP_CALLBACK_PATH}`;
+        await seedClient(origin, redirectUri);
+        await page.goto(authUrl(origin, redirectUri));
+        await visible(page, `${APP_NAME} would like to access your TikTok account`);
+        await clickByName(page, 'Cancel');
+        await atPath(page, APP_CALLBACK_PATH);
+        await visible(page, 'authorization failed');
+        await visible(page, 'access_denied');
+        callback = new URL(page.url());
+      },
+    });
+    expect(callback!.searchParams.get('error')).toBe('access_denied');
+    expect(callback!.searchParams.get('state')).toBe('journey-state-1');
+    expect(callback!.searchParams.get('code')).toBeNull();
+  }, 30_000);
+  test('a misconfigured redirect_uri stays on the vendor error page, and the app is NEVER reached', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+    let finalUrl = '';
+    // The HANDLE, kept so the assertion can read it AFTER the journey (the googleoauth §9 lesson:
+    // reading `last()` inside `serve` stores a value that is null by construction, and the security
+    // assertion could then never fail).
+    let app: { last: () => URL | null } | null = null;
+    await runUiJourney({
+      label: 'tiktok redirect_uri mismatch error page',
+      seed: async () => {},
+      serve: (root) => {
+        const server = startJourneyServer(root);
+        app = server;
+        return server;
+      },
+      journey: async (page) => {
+        const origin = new URL(page.url()).origin;
+        await seedClient(origin, `${origin}${APP_CALLBACK_PATH}`);
+        // The single most common Login Kit integration bug, seen the way a developer sees it: the
+        // browser STAYS on the vendor showing the error, and the app is never reached.
+        await page.goto(authUrl(origin, `${origin}/oauth/WRONG`));
+        await atPath(page, '/v2/auth/authorize');
+        await visible(page, 'Something went wrong');
+        await visible(page, 'Error 400: invalid_request');
+        finalUrl = page.url();
+      },
+    });
+    expect(new URL(finalUrl).pathname, 'the browser must end on the vendor authorize path showing the error').toBe('/v2/auth/authorize');
+    // Read AFTER the journey: the app must never have been reached at all.
+    expect(app!.last(), 'the app callback must never have been called').toBeNull();
+  }, 30_000);
+});

package/src/tiktok-media.ts ADDED Viewed

@@ -0,0 +1,89 @@
+// What TikTok's processing reads off an uploaded file, for the fields the twin reports on the video it
+// publishes: `duration`, `width` and `height` (the Video Object's own fields), and the
+// max_video_post_duration_sec check the init promised, and the frame rate (23–60 FPS) the media transfer
+// guide requires.
+//
+// Transcribed from the YouTube pack's reader (youtube-media.ts): only the ISO BMFF container (MP4/MOV,
+// the format TikTok recommends) is read, and only its headers — `moov/mvhd` for the duration and the
+// first `moov/trak/tkhd` with a picture size for the dimensions; that video track's
+// `mdia/mdhd` timescale and duration over its `mdia/minf/stbl/stts` sample count for the frame rate. No decoder, no toolchain: a file the
+// reader does not understand leaves the fields unset rather than inventing values.
+export type MediaProbe = { durationSeconds?: number; width?: number; height?: number; frameRate?: number };
+type Box = { type: string; start: number; end: number };
+function boxes(view: DataView, start: number, end: number): Box[] {
+  const out: Box[] = [];
+  let at = start;
+  while (at + 8 <= end) {
+    let size = view.getUint32(at);
+    const type = String.fromCharCode(view.getUint8(at + 4), view.getUint8(at + 5), view.getUint8(at + 6), view.getUint8(at + 7));
+    let header = 8;
+    if (size === 1) {
+      if (at + 16 > end) break;
+      size = Number(view.getBigUint64(at + 8));
+      header = 16;
+    } else if (size === 0) {
+      size = end - at;
+    }
+    if (size < header || at + size > end) break;
+    out.push({ type, start: at + header, end: at + size });
+    at += size;
+  }
+  return out;
+}
+/** A track's frame rate: its sample count over its media duration (mdhd timescale units). */
+function frameRateOf(view: DataView, trak: Box): number | undefined {
+  const mdia = boxes(view, trak.start, trak.end).find((b) => b.type === 'mdia');
+  if (!mdia) return undefined;
+  const inMdia = boxes(view, mdia.start, mdia.end);
+  const mdhd = inMdia.find((b) => b.type === 'mdhd');
+  const stbl = (() => { const minf = inMdia.find((b) => b.type === 'minf'); return minf ? boxes(view, minf.start, minf.end).find((b) => b.type === 'stbl') : undefined; })();
+  const stts = stbl ? boxes(view, stbl.start, stbl.end).find((b) => b.type === 'stts') : undefined;
+  if (!mdhd || !stts) return undefined;
+  const version = view.getUint8(mdhd.start);
+  const timescale = view.getUint32(mdhd.start + (version === 1 ? 20 : 12));
+  const duration = version === 1 ? Number(view.getBigUint64(mdhd.start + 24)) : view.getUint32(mdhd.start + 16);
+  const entries = view.getUint32(stts.start + 4);
+  let samples = 0;
+  for (let i = 0; i < entries && stts.start + 8 + i * 8 + 4 <= stts.end; i += 1) samples += view.getUint32(stts.start + 8 + i * 8);
+  if (timescale <= 0 || duration <= 0 || samples <= 0) return undefined;
+  return samples / (duration / timescale);
+}
+export function probeMp4(bytes: Uint8Array): MediaProbe {
+  try {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const moov = boxes(view, 0, bytes.byteLength).find((b) => b.type === 'moov');
+    if (!moov) return {};
+    const out: MediaProbe = {};
+    const children = boxes(view, moov.start, moov.end);
+    const mvhd = children.find((b) => b.type === 'mvhd');
+    if (mvhd) {
+      const version = view.getUint8(mvhd.start);
+      const timescale = view.getUint32(mvhd.start + (version === 1 ? 20 : 12));
+      const duration = version === 1 ? Number(view.getBigUint64(mvhd.start + 24)) : view.getUint32(mvhd.start + 16);
+      if (timescale > 0) out.durationSeconds = duration / timescale;
+    }
+    for (const trak of children.filter((b) => b.type === 'trak')) {
+      const tkhd = boxes(view, trak.start, trak.end).find((b) => b.type === 'tkhd');
+      if (!tkhd) continue;
+      const version = view.getUint8(tkhd.start);
+      const sizeAt = tkhd.start + (version === 1 ? 88 : 76);
+      if (sizeAt + 8 > tkhd.end) continue;
+      const width = view.getUint32(sizeAt) / 65536;
+      const height = view.getUint32(sizeAt + 4) / 65536;
+      if (width > 0 && height > 0) {
+        out.width = Math.round(width);
+        out.height = Math.round(height);
+        const rate = frameRateOf(view, trak);
+        if (rate !== undefined) out.frameRate = rate;
+        break;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}

package/src/tiktok-mirror-ui.ts ADDED Viewed

@@ -0,0 +1,167 @@
+// 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.ts';
+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
+// ---------------------------------------------------------------------------
+// Pure, dependency-free helpers (importable by the React client; Bun tree-shakes the server-only
+// exports out of the browser bundle).
+// ---------------------------------------------------------------------------
+export type TtRow = Record<string, any>;
+/** 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: unknown): string {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return '0';
+  const scaled = (value: number, unit: string) => `${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: TtRow | undefined): Array<{ label: 'Following' | 'Followers' | 'Likes'; value: string }> {
+  const out: Array<{ label: 'Following' | 'Followers' | 'Likes'; value: string }> = [];
+  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;
+}
+export type CaptionSegment = { kind: 'text' | 'hashtag' | 'mention'; value: string };
+/** A caption split the way tiktok.com bolds it: #hashtags and @mentions are links, the rest text. */
+export function captionSegments(text: unknown): CaptionSegment[] {
+  const source = typeof text === 'string' ? text : '';
+  const out: CaptionSegment[] = [];
+  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: TtRow | undefined): string {
+  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: unknown): string {
+  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: string, videoId: string, token: string): string {
+  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: TtRow | undefined): string {
+  const source = String(user?.display_name ?? user?.username ?? '?').trim();
+  return (Array.from(source)[0] ?? '?').toUpperCase();
+}
+export function avatarHue(key: unknown): number {
+  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: Promise<string> | null = null;
+/** Build the React/TSX mirror client to browser JS; memoized, so a pack does exactly one Bun.build. */
+export function buildTiktokMirrorClient(): Promise<string> {
+  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: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; url: string; stop: () => void }> {
+  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(): string {
+  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(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/tiktok-pkce.ts ADDED Viewed

@@ -0,0 +1,61 @@
+// 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: string): string {
+  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: string): string {
+  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: string): boolean {
+  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: string, verifier: string): boolean {
+  if (!isWellFormedVerifier(verifier)) return false;
+  return tiktokCodeChallenge(verifier) === challenge;
+}
+const VERIFIER_RE = /^[A-Za-z0-9\-._~]{43,128}$/;
+export function isWellFormedVerifier(verifier: string): boolean {
+  return VERIFIER_RE.test(verifier);
+}