@volter/twin-tiktok 0.1.0

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

@@ -0,0 +1,28 @@
+import type { Row } from './tiktok-store.js';
+export declare const USER_INFO_SCOPES: readonly ["user.info.basic", "user.info.profile", "user.info.stats"];
+/** Field -> the scope that gates it, in the reference table's own order. */
+export declare const USER_FIELD_SCOPES: Record<string, string>;
+export declare const USER_FIELDS: readonly string[];
+/**
+ * Render an account row as the vendor's User object for a requested field set.
+ *
+ * `open_id` is APP-SCOPED and therefore comes from the grant, not from the account — that is the
+ * whole distinction TikTok draws between `open_id` and `union_id`. A modelled field whose value
+ * this persona genuinely lacks is OMITTED rather than served as a placeholder (the connector's
+ * "invent nothing" rule, applied at the read side too).
+ */
+export declare function renderUser(account: Row, openId: string, fields: readonly string[]): Record<string, unknown>;
+/** The Video Object's fields, verbatim from the vendor's own reference table. */
+export declare const VIDEO_FIELDS: readonly string[];
+/** The single scope every Display API video read is gated behind. */
+export declare const VIDEO_SCOPE = "video.list";
+/**
+ * Render a video row for a requested field set.
+ *
+ * The four LINK fields are DERIVED, deterministically, from the stored row — TikTok composes them
+ * the same way (`share_url` is the canonical `/@handle/video/<id>` permalink and `embed_link` the
+ * `/embed/v2/<id>` player). Deriving keeps them consistent with the id and the owner's handle
+ * instead of storing four strings that could drift apart; the exact CDN host of `cover_image_url`
+ * is a twin host, not the vendor's, and `tiktok.video.link_shapes` (todo) pins the live forms.
+ */
+export declare function renderVideo(video: Row, ownerUsername: string, fields: readonly string[]): Record<string, unknown>;

package/dist/src/tiktok-user.js

@@ -0,0 +1,174 @@
+export const USER_INFO_SCOPES = ['user.info.basic', 'user.info.profile', 'user.info.stats'];
+/** Field -> the scope that gates it, in the reference table's own order. */
+export const USER_FIELD_SCOPES = {
+    open_id: 'user.info.basic',
+    union_id: 'user.info.basic',
+    avatar_url: 'user.info.basic',
+    avatar_url_100: 'user.info.basic',
+    avatar_large_url: 'user.info.basic',
+    display_name: 'user.info.basic',
+    bio_description: 'user.info.profile',
+    profile_deep_link: 'user.info.profile',
+    is_verified: 'user.info.profile',
+    username: 'user.info.profile',
+    follower_count: 'user.info.stats',
+    following_count: 'user.info.stats',
+    likes_count: 'user.info.stats',
+    video_count: 'user.info.stats',
+};
+export const USER_FIELDS = Object.keys(USER_FIELD_SCOPES);
+/**
+ * Render an account row as the vendor's User object for a requested field set.
+ *
+ * `open_id` is APP-SCOPED and therefore comes from the grant, not from the account — that is the
+ * whole distinction TikTok draws between `open_id` and `union_id`. A modelled field whose value
+ * this persona genuinely lacks is OMITTED rather than served as a placeholder (the connector's
+ * "invent nothing" rule, applied at the read side too).
+ */
+export function renderUser(account, openId, fields) {
+    const out = {};
+    const put = (key, value) => {
+        if (value !== undefined && value !== null)
+            out[key] = value;
+    };
+    for (const field of fields) {
+        switch (field) {
+            case 'open_id':
+                put(field, openId);
+                break;
+            case 'union_id':
+                put(field, account.id);
+                break;
+            case 'avatar_url':
+                put(field, account.avatarUrl);
+                break;
+            case 'avatar_url_100':
+                put(field, account.avatarUrl100);
+                break;
+            case 'avatar_large_url':
+                put(field, account.avatarLargeUrl);
+                break;
+            case 'display_name':
+                put(field, account.displayName);
+                break;
+            case 'bio_description':
+                put(field, account.bioDescription);
+                break;
+            case 'profile_deep_link':
+                put(field, account.profileDeepLink);
+                break;
+            case 'is_verified':
+                put(field, typeof account.isVerified === 'boolean' ? account.isVerified : undefined);
+                break;
+            case 'username':
+                put(field, account.username);
+                break;
+            case 'follower_count':
+                put(field, account.followerCount);
+                break;
+            case 'following_count':
+                put(field, account.followingCount);
+                break;
+            case 'likes_count':
+                put(field, account.likesCount);
+                break;
+            case 'video_count':
+                put(field, account.videoCount);
+                break;
+            default: break;
+        }
+    }
+    return out;
+}
+/** The Video Object's fields, verbatim from the vendor's own reference table. */
+export const VIDEO_FIELDS = [
+    'id',
+    'create_time',
+    'cover_image_url',
+    'share_url',
+    'video_description',
+    'duration',
+    'height',
+    'width',
+    'title',
+    'embed_html',
+    'embed_link',
+    'like_count',
+    'comment_count',
+    'share_count',
+    'view_count',
+    'is_aigc',
+];
+/** The single scope every Display API video read is gated behind. */
+export const VIDEO_SCOPE = 'video.list';
+/**
+ * Render a video row for a requested field set.
+ *
+ * The four LINK fields are DERIVED, deterministically, from the stored row — TikTok composes them
+ * the same way (`share_url` is the canonical `/@handle/video/<id>` permalink and `embed_link` the
+ * `/embed/v2/<id>` player). Deriving keeps them consistent with the id and the owner's handle
+ * instead of storing four strings that could drift apart; the exact CDN host of `cover_image_url`
+ * is a twin host, not the vendor's, and `tiktok.video.link_shapes` (todo) pins the live forms.
+ */
+export function renderVideo(video, ownerUsername, fields) {
+    const shareUrl = `https://www.tiktok.com/@${ownerUsername}/video/${video.id}`;
+    const out = {};
+    const put = (key, value) => {
+        if (value !== undefined && value !== null)
+            out[key] = value;
+    };
+    for (const field of fields) {
+        switch (field) {
+            case 'id':
+                put(field, video.id);
+                break;
+            case 'create_time':
+                put(field, video.createTime);
+                break;
+            case 'cover_image_url':
+                put(field, `https://p16-sign.tiktokcdn-us.com/twin/${video.id}~tplv-cover.jpeg`);
+                break;
+            case 'share_url':
+                put(field, shareUrl);
+                break;
+            case 'video_description':
+                put(field, video.videoDescription);
+                break;
+            case 'duration':
+                put(field, video.duration);
+                break;
+            case 'height':
+                put(field, video.height);
+                break;
+            case 'width':
+                put(field, video.width);
+                break;
+            case 'title':
+                put(field, video.title);
+                break;
+            case 'embed_html':
+                put(field, `<blockquote class="tiktok-embed" cite="${shareUrl}" data-video-id="${video.id}"></blockquote>`);
+                break;
+            case 'embed_link':
+                put(field, `https://www.tiktok.com/embed/v2/${video.id}`);
+                break;
+            case 'like_count':
+                put(field, video.likeCount);
+                break;
+            case 'comment_count':
+                put(field, video.commentCount);
+                break;
+            case 'share_count':
+                put(field, video.shareCount);
+                break;
+            case 'view_count':
+                put(field, video.viewCount);
+                break;
+            case 'is_aigc':
+                put(field, video.isAigc === true);
+                break;
+            default: break;
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@volter/twin-tiktok",
+  "version": "0.1.0",
+  "description": "Local TikTok twin — the real tiktok.com authorization page, the full Login Kit OAuth round trip (token, refresh, revoke, client_credentials) and the Display API user/video reads with TikTok's own comma-separated scopes, per-app open_id, field-level scope gating and both of its error envelopes, so an unmodified TikTok integration completes sign-in-with-TikTok against it. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "oauth",
+    "oauth2",
+    "tiktok",
+    "login-kit",
+    "display-api",
+    "identity",
+    "sign-in-with-tiktok"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/tiktok"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/tiktok#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-tiktok": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// world-tiktok CLI: serve the TikTok twin, or run conformance.
+//
+// `serve` starts the twin. `mirror` starts the same twin with tiktok.com's profile and player in
+// front of it (tiktok-mirror-ui.ts: the shell at `/`, everything else the twin's own fetch adapter),
+// and prints both screens an operator asks to "see": the mirror, and a ready-to-open authorize URL
+// for the authorization page the twin serves at the vendor's own path.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createTikTokTwinServer } from './tiktok-server.ts';
+import { createTiktokMirrorServer } from './tiktok-mirror-ui.ts';
+import { DEFAULT_CLIENT_KEY, defaultRedirectUris } from './tiktok-store.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === 'mirror') {
+  const options = { readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) };
+  const s = cmd === 'mirror' ? await createTiktokMirrorServer(options) : await createTikTokTwinServer(options);
+  const origin = `http://127.0.0.1:${s.port}`;
+  process.stdout.write(`tiktok twin (Login Kit OAuth + Display API + Content Posting)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
+  if (cmd === 'mirror') {
+    process.stdout.write(`mirror (tiktok.com profile + player): ${origin}/\n`);
+    const url = new URL(`${origin}/v2/auth/authorize`);
+    url.searchParams.set('client_key', DEFAULT_CLIENT_KEY);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]!);
+    url.searchParams.set('scope', 'user.info.basic,user.info.profile,video.list');
+    url.searchParams.set('state', 'twin-demo-state');
+    process.stdout.write(`authorization page: ${url.toString()}\n`);
+  }
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkTikTokConformance } = await import('./tiktok-conformance.ts');
+  const report = await checkTikTokConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-tiktok serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,270 @@
+// @volter/twin-tiktok — the TikTok twin (one vendor, one package), built on the shared
+// @volter/world-core kernel.
+//
+// A BROWSER-FACING protocol pack (the googleoauth class): it serves TikTok's own authorization
+// page as HTML at www.tiktok.com's real path, completes the full Login Kit authorization-code
+// round trip (consent -> 302 with code+scopes+state -> redemption at the token endpoint -> refresh
+// -> revoke), and answers the Display API's `/v2/user/info/`, `/v2/video/list/` and
+// `/v2/video/query/` reads with TikTok's real field-selection, scope-gating and error envelopes, and
+// posts a creator's video through the Content Posting API (creator_info, the Direct Post and inbox
+// inits, the chunked upload to a signed upload URL, status/fetch) with the bytes on the blob seam, a
+// tiktok.com-style mirror over that state, and a perform that sends a World's post to TikTok.
+// Deliberately NON-OIDC, exactly as the vendor is: opaque `act.`/`rft.` tokens, no id_token, no
+// JWKS — identity comes from the Display API, and `open_id` is per-app while `union_id` is
+// per-human. Conformance tooling lives in @volter/world-tooling (a dev dependency), not here.
+import { registerPack, type TwinPack } from '@volter/world-core';
+
+export {
+  ACCESS_TOKEN_TTL_SECONDS,
+  API_ORIGIN,
+  AUTH_CODE_TTL_SECONDS,
+  AUTHORIZE_ORIGIN,
+  CLIENT_TOKEN_TTL_SECONDS,
+  handleTikTokTwinRequest,
+  METERED_ENDPOINTS,
+  RATE_LIMIT_PER_WINDOW,
+  RATE_LIMITS,
+  RATE_WINDOW_SECONDS,
+  REFRESH_TOKEN_TTL_SECONDS,
+  RESOURCE_TYPES,
+  tiktokTwinSnapshot,
+  USER_FIELDS,
+  VIDEO_FIELDS,
+  VIDEO_LIST_DEFAULT_COUNT,
+  VIDEO_LIST_MAX_COUNT,
+  VIDEO_QUERY_MAX_IDS,
+} from './tiktok-twin.ts';
+export type { MeteredEndpoint, TikTokRequest, TikTokResponse } from './tiktok-twin.ts';
+export { createTikTokConsentServer, createTikTokTwinFetch, createTikTokTwinServer, type TikTokTwinFetchOptions } from './tiktok-server.ts';
+export {
+  DEFAULT_ACCOUNTS,
+  DEFAULT_CLIENT_KEY,
+  DEFAULT_CLIENT_SECRET,
+  DEFAULT_VIDEOS,
+  defaultRedirectUris,
+  openIdFor,
+  redirectUriAllowed,
+  sessionAccount,
+} from './tiktok-store.ts';
+export { CHALLENGE_METHOD, isSupportedChallengeMethod, isWellFormedVerifier, pkceVerifies, rfc7636Challenge, tiktokCodeChallenge } from './tiktok-pkce.ts';
+export {
+  describeScope,
+  describeScopes,
+  formatScopeParam,
+  KNOWN_SCOPES,
+  parseScopeParam,
+  SCOPE_CATALOG,
+  sortScopesForConsent,
+} from './tiktok-scopes.ts';
+export type { ScopeInfo, ScopeProduct } from './tiktok-scopes.ts';
+export { API_ERRORS, OAUTH_ERRORS } from './tiktok-errors.ts';
+export { logId } from './tiktok-ids.ts';
+export { renderUser, renderVideo, USER_FIELD_SCOPES, USER_INFO_SCOPES, VIDEO_SCOPE } from './tiktok-user.ts';
+export {
+  liveTikTokExecute,
+  mapUserInfoAccount,
+  mapVideo,
+  performTikTokAction,
+  PULL_USER_FIELDS,
+  PULL_VIDEO_FIELDS,
+  pullTikTok,
+  pushPendingTikTokActions,
+  syncTikTokFromReal,
+  syncTikTokFromRemote,
+  tiktokExecuteOver,
+} from './tiktok-connector.ts';
+export type { LiveTikTokOptions, PullOptions, TikTokExecute } from './tiktok-connector.ts';
+export {
+  budgetedTikTokExecute,
+  MAX_PUBLISH_WAIT_MS,
+  TikTokRetryableError,
+  PERFORM_CHUNK_BYTES,
+  performChunkPlan,
+  STATUS_POLL_MS,
+  TikTokStillProcessingError,
+} from './tiktok-connector.ts';
+export {
+  checkChunkPlan,
+  chunkLength,
+  creatorOptions,
+  DEFAULT_MAX_VIDEO_POST_DURATION_SEC,
+  MAX_CHUNK_BYTES,
+  MAX_CHUNK_COUNT,
+  MAX_FINAL_CHUNK_BYTES,
+  MAX_SERVED_RANGE,
+  MAX_VIDEO_BYTES,
+  MEDIA_PREFIX,
+  MIN_CHUNK_BYTES,
+  PRIVACY_LEVELS,
+  processingMs,
+  UPLOAD_ORIGIN,
+  UPLOAD_PATH,
+  UPLOAD_URL_TTL_MS,
+} from './tiktok-posting.ts';
+export { POSTING_ERRORS } from './tiktok-errors.ts';
+// The client-side rate budget — the fail-closed backstop `liveTikTokExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is this vendor's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `TikTokBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  TIKTOK_BUDGET_BURST_CEILING,
+  TIKTOK_BUDGET_CEILING,
+  TIKTOK_BUDGET_MAX_RETRY_AFTER_S,
+  TIKTOK_BUDGET_WINDOW_MS,
+  TIKTOK_CALL_WEIGHTS,
+  TIKTOK_RATE_BUDGET,
+  TikTokBudget,
+  TikTokBudgetError,
+  tiktokBudgetPath,
+  tiktokCallWeight,
+} from './tiktok-budget.ts';
+export type {
+  TikTokBudgetErrorKind,
+  TikTokBudgetOptions,
+  TikTokBudgetReservation,
+  TikTokBudgetSnapshot,
+} from './tiktok-budget.ts';
+export { CONSENT_CSS, consentPageHtml, errorPageHtml, tiktokConsentState } from './tiktok-consent-ui.ts';
+// The tiktok.com mirror (profile, grid, vertical player): its pure helpers and its server. The hosted
+// mirror mount reads tiktok-mirror-ui.ts directly (`tiktokMirrorHtml`, `buildTiktokMirrorClient`,
+// `tiktokMirrorStyles`).
+export { captionOf, captionSegments, compactCount, createTiktokMirrorServer, mediaSource, profileStats } from './tiktok-mirror-ui.ts';
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from './tiktok-consent-ui.ts';
+
+import { TIKTOK_RATE_BUDGET as RATE_BUDGET } from './tiktok-budget.ts';
+import { performTikTokAction, syncTikTokFromRemote } from './tiktok-connector.ts';
+
+/**
+ * The www.tiktok.com paths THIS pack serves — the Login Kit authorization leg — as a RegExp SOURCE
+ * for the descriptor's `hosts` path rule. www.tiktok.com is NOT an API host: it is the whole
+ * TikTok web property (the For You feed, profiles, settings, everything). Claiming the host
+ * outright would be the Cal.com mis-route incident with the largest possible blast radius, so this
+ * claims EXACTLY the authorize path plus the twin-only prefix. ANCHORED, the googleoauth lesson:
+ * an unanchored claim swallows `/v2/auth/authorize2` and friends. The optional trailing slash is
+ * load-bearing — TikTok's own documentation writes `/v2/auth/authorize/` while Dub's URL builder
+ * omits it, and both must route here.
+ */
+const TIKTOK_AUTHORIZE_PATHS = '^/v2/auth/authorize/?$|^/_twin/';
+
+/**
+ * The open.tiktokapis.com paths THIS pack serves: the OAuth token/revoke endpoints, the Display
+ * API's user and video reads and the Content Posting API's four calls. open.tiktokapis.com is the
+ * ENTIRE TikTok open platform host — Research, Data Portability, Commercial Content, Business and
+ * the photo post besides — and nothing this pack does not model is claimed: an unmodelled TikTok
+ * call must refuse loudly rather than land in a twin that cannot serve it.
+ */
+const TIKTOK_API_PATHS = '^/v2/(?:oauth/(?:token|revoke)|user/info|video/(?:list|query)|post/publish/(?:creator_info/query|video/init|inbox/video/init|status/fetch))/?$|^/_twin/';
+
+/**
+ * The upload host's path: the Content Posting API's upload_url is `https://open-upload.tiktokapis.com/
+ * video/?upload_id=…&upload_token=…` (the Direct Post and inbox references' own examples). An app in a
+ * World PUTs its chunks there, so the injector must route that host to the twin too. Nothing else on
+ * the upload host is modelled, so nothing else is claimed.
+ */
+const TIKTOK_UPLOAD_PATHS = '^/video/?$';
+
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system, registered on load. A World's POST crosses at `perform`, through the
+  // Content Posting API (creator_info, init, the presigned chunk PUTs, status/fetch); nothing else
+  // does: TikTok publishes no API that creates a developer app, seeds a user or grants a scope —
+  // those are developer-portal and in-app settings actions a person takes in a browser — so
+  // `perform` settles every other entry with that reason.
+  protocol: '2',
+  // The vendor's access token lives 24 hours and its Display API limit is 600/minute, so a served
+  // world can afford a half-hourly pull; `onDemand` throttles a hand-run refresh to one a minute,
+  // well inside that budget.
+  refresh: { every: '30m', onDemand: { atMost: '60s' } },
+  stateSystem: { perform: performTikTokAction, refresh: syncTikTokFromRemote },
+  // The round trip registers a developer app through the twin's OWN door, because the vendor has no
+  // API for it at all — which is the same reason `perform` never crosses. (The Login Kit legs
+  // cannot serve as the round trip: the consent post answers a 302 and the harness fails any step
+  // answering >=300.)
+  roundTrip: {
+    method: 'POST',
+    path: '/_twin/clients',
+    body: { client_key: 'awroundtripapp0001', client_secret: 'round-trip-secret', name: 'Round Trip', redirect_uris: ['https://round.trip.test/callback'] },
+  },
+  parityOrigin: 'http://twin',
+  // shapeParity is NOT held, and the reason is STRUCTURAL rather than a divergence to close: the
+  // refresh reads the ACCOUNT the credential names (`GET /v2/user/info/`), while the only write a
+  // blind round trip can make on this vendor is registering a developer app — which TikTok
+  // publishes no API to read back. Written and observed are different subjects by design, so there
+  // is no pair of shapes to compare. Reaching parity would need the refresh to observe an
+  // oauth_client, and no TikTok endpoint returns one.
+  vendor: 'tiktok',
+  // The SAME object tiktok-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-tiktok',
+  resources: [
+    'oauth_client',
+    'account',
+    'session',
+    'auth_request',
+    'grant',
+    'video',
+    'publish',
+  ],
+  specSource:
+    'developers.tiktok.com, fetched 2026-09-13 — no first-party machine-readable spec exists for '
+    + 'the TikTok open API, so the denominator was authored top-down from the published references: '
+    + 'Login Kit for Web (the authorize URL, its parameters and the callback parameters), User '
+    + 'Access Token Management (token / refresh / revoke request + response tables and examples), '
+    + 'Client Access Token Management (the client_credentials grant), Login Kit for Desktop (PKCE: '
+    + 'hex-encoded SHA-256, S256 only), the Scopes Overview, Get User Info (the field x scope '
+    + 'table), the Video Object / Video List / Video Query references, the OAuth error-handling '
+    + 'reference (the ten flat `error` values) and the API v2 error-handling reference (the seven '
+    + 'nested `error.code` values with their HTTP statuses) and rate-limit reference (600/minute, '
+    + 'one-minute sliding window, 429 + rate_limit_exceeded); and, fetched 2026-09-27, the Content '
+    + 'Posting references (Query Creator Info, Direct Post, Upload to inbox, Get Post Status and the '
+    + 'Media Transfer Guide: chunk rules, the upload_url PUT with Content-Range, per-token minute limits).',
+  description:
+    "TikTok twin — the real tiktok.com authorization page, the full Login Kit OAuth round trip "
+    + '(token, refresh, revoke, client_credentials) and the Display API user/video reads with '
+    + "TikTok's own comma-separated scopes, per-app open_id, field-level scope gating and both of "
+    + 'its error envelopes; and the Content Posting API — creator_info, Direct Post and inbox uploads '
+    + 'through a signed upload URL in chunks, status/fetch by World time — with a tiktok.com-style '
+    + "profile and vertical player over the posted videos, and a perform that posts a World's video "
+    + 'to TikTok.',
+  adoption: {
+    // TikTok publishes NO first-party npm client for Login Kit or the Display API: its own
+    // reference material is curl and raw fetch, which is exactly how the motivating application
+    // (Dub) calls it. The community `tiktok` package on npm is deliberately NOT claimed — it is
+    // not a TikTok-published client, and `adoption.sdks` is for official clients only (the bitly
+    // precedent). Interception is therefore host-based, which is why `hosts` below is the whole
+    // adoption story for this vendor.
+    sdks: [],
+    // No official Python distribution either. `tiktok-business-api-sdk` (PyPI and npm) is
+    // first-party but speaks the BUSINESS/Ads API on business-api.tiktok.com — a different half of
+    // the vendor that this pack does not serve, so claiming it would over-claim coverage.
+    pypi: [],
+    // TIKTOK_CLIENT_ID / TIKTOK_CLIENT_SECRET are exactly the pair Dub reads, and TIKTOK_CLIENT_KEY
+    // is the vendor's own name for the same value. The `TIKTOKBUSINESS` stem is deliberately left
+    // to the packless registry: it names the Business API this pack does not model.
+    envStems: ['TIKTOK'],
+  },
+  hosts: [
+    { host: 'www.tiktok.com', pathPattern: TIKTOK_AUTHORIZE_PATHS },
+    { host: 'open.tiktokapis.com', pathPattern: TIKTOK_API_PATHS },
+    { host: 'open-upload.tiktokapis.com', pathPattern: TIKTOK_UPLOAD_PATHS },
+  ],
+  // Dub HARDCODES both hosts — `https://open.tiktokapis.com/v2` in its TikTokClient and the
+  // authorize/token URLs in its provider table — and TikTok publishes no official SDK with a
+  // base-URL option, so there is no env var an app reads that a world could point at the twin.
+  // Inventing a TIKTOK_BASE_URL would make `covers` report the world covered while the app still
+  // talked to the real vendor; interception through the two `hosts` entries above is the whole
+  // mechanism.
+  endpointEnvNone:
+    'no app-read base-URL env exists: TikTok publishes no official SDK with a base-URL option and '
+    + 'integrations (Dub included) hardcode www.tiktok.com and open.tiktokapis.com, so interception '
+    + 'is the path-scoped hosts entries above.',
+  // A browser is REDIRECTED to www.tiktok.com/v2/auth/authorize — the loader host is the consent
+  // host and the prefix is the Login Kit path root.
+  browserRouting: { apiPathPrefix: '/v2/auth/', loaderHost: 'https://www.tiktok.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);