@volter/twin-tiktok 0.1.36 → 1.0.0

package/src/index.ts

@@ -1,270 +1,15 @@
-// @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);
+// @volter/twin-tiktok — the tiktok twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { manifest as businessManifest } from '../business/src/manifest.ts';
+import businessSurface from '../business/src/generated/surface.gen.json' with { type: 'json' };
+import { manifest as openManifest } from '../open/src/manifest.ts';
+import openSurface from '../open/src/generated/surface.gen.json' with { type: 'json' };
+
+export { createTiktokFetch } from './fetch.ts';
+export { createTiktokTwinServer } from './server.ts';
+export { manifest };
+
+export const pack = registerPack(packOf(manifest, { "business": { manifest: businessManifest, surface: businessSurface as unknown as DerivedSurface }, "open": { manifest: openManifest, surface: openSurface as unknown as DerivedSurface } }));

package/src/manifest.ts

@@ -0,0 +1,33 @@
+// TikTok's manifest: a vendor of two APIs, each a lane (architecture, "Other wires: lanes"): the open platform
+// (`open`: Login Kit's token, the Content Posting API, the Display API, the upload host and the authorize page on
+// www.tiktok.com), and the API for Business (`business`, business-api.tiktok.com). Postiz calls both.
+import type { VendorManifest } from '@volter/world-core';
+
+export const manifest: VendorManifest = {
+  vendor: 'tiktok',
+  discovery: {
+    twinOf: "TikTok's open platform: an app's authorize page and tokens, posting videos and photos (direct and to the inbox) with their upload host and status, and a user's profile, stats and videos",
+    stores: "the developer site's apps and URL properties, TikTok's people, authorization codes and tokens (by their SHA-256), posts and their uploads, and videos",
+  },
+  lanes: {
+    routes: [
+      { lane: 'business', host: '^business-api\\.tiktok\\.com$' },
+      { lane: 'open', host: '^(open\\.tiktokapis\\.com|open-upload\\.tiktokapis\\.com|upload\\.us\\.tiktokapis\\.com|www\\.tiktok\\.com)$' },
+    ],
+    default: 'open',
+  },
+  descriptor: {
+    protocol: '3',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-tiktok',
+    resources: ['publish', 'video'],
+    specSource: 'written from the API reference pages of developers.tiktok.com (open/spec/openapi.json, provenance in open/spec/SOURCE.md)',
+    description: "TikTok twin — Login Kit's authorize page and tokens, the Content Posting API (direct and inbox videos by chunked upload, photos pulled from verified URLs, post status) and the Display API (user info and stats, video list and query), as Postiz calls them.",
+    adoption: { sdks: [], envStems: ['TIKTOK'] },
+    hosts: [{ host: 'business-api.tiktok.com' }, { host: 'open.tiktokapis.com' }, { host: 'open-upload.tiktokapis.com' }, { host: 'upload.us.tiktokapis.com' }, { host: 'www.tiktok.com', pathPattern: '^/v2/auth/authorize' }],
+    endpointEnvNone: 'Postiz calls open.tiktokapis.com and sends people to www.tiktok.com; the World claims the hosts',
+    clientCasesNone: 'Postiz uses fetch for both TikTok APIs; no official SDK behaviour is required.',
+    credentialDoor: { path: '/_twin/app-credentials', body: {}, fill: { TIKTOK_CLIENT_ID: 'client_key', TIKTOK_CLIENT_SECRET: 'client_secret', TIKTOK_BUSINESS_CLIENT_ID: 'business_client_id', TIKTOK_BUSINESS_CLIENT_SECRET: 'business_client_secret' } },
+  },
+};

package/src/semantics/shared.ts

@@ -0,0 +1,78 @@
+// What TikTok's lanes share (a lane imports its vendor's shared helpers): the developer sites' apps, TikTok's people,
+// the codes and tokens an app holds for a person (each kept by its SHA-256, drawn from ctx.secret), posts and videos,
+// and the World's numbering and placeholder images.
+import { placeholderPng, type HandlerContext } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+export const APP = '_app';
+export const PERSON = '_person';
+export const CODE = '_code';
+export const ACCESS = '_access_token';
+export const REFRESH = '_refresh_token';
+export const PUBLISH = 'publish';
+export const VIDEO = 'video';
+export const CHUNK = '_chunk';
+
+export const sha256 = (ctx: Pick<HandlerContext, 'crypto'>, v: string): string => ctx.crypto.digest('sha256', v, 'hex');
+export const seconds = (iso: string): number => Math.floor(Date.parse(iso) / 1000);
+const obj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+export const bodyOf = (ctx: Pick<HandlerContext, 'body'>): Row => obj(ctx.body);
+
+// ── apps and people ────────────────────────────────────────────────────────────────────────────
+
+/** An app's client secret, drawn from the World's secret under its id. */
+export const clientSecret = async (ctx: Pick<HandlerContext, 'secret' | 'crypto'>, app: Row): Promise<string> =>
+  ctx.crypto.digest('sha256', await ctx.secret(`tiktok-client-secret:${String(app.id)}`), 'hex').slice(0, 32);
+export const appByKey = (ctx: Pick<HandlerContext, 'rowsRaw'>, key: unknown): Row | undefined => ctx.rowsRaw(APP).find((a) => a.deleted !== true && a.client_key === key);
+
+/** A person's id in an app ("The unique identification of the user in the current application"), and across the
+ *  developer's apps (union_id): derived from the ids they name, both public. */
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info "The unique identification of the user in the current application."
+export const openIdOf = (ctx: Pick<HandlerContext, 'crypto'>, app: Row, person: Row): string => ctx.crypto.uuidFrom(`tiktok-open-id:${String(app.id)}:${String(person.id)}`);
+export const unionIdOf = (ctx: Pick<HandlerContext, 'crypto'>, person: Row): string => ctx.crypto.uuidFrom(`tiktok-union-id:${String(person.id)}`);
+
+/** A placeholder image the World's CDN serves (a person's avatar, a video's cover): the kernel's placeholder PNG. */
+export const mediaUrl = (ctx: Pick<HandlerContext, 'publicBase'>, name: string): string => `${ctx.publicBase.replace(/\/$/, '')}/_twin/media/${name}.png`;
+export const mediaBytes = (name: string): Uint8Array => placeholderPng({ width: 720, height: 1280 }, `tiktok:${name}`, `placeholder image from the TikTok twin: ${name}`);
+
+// ── tokens ─────────────────────────────────────────────────────────────────────────────────────
+// source: https://developers.tiktok.com/doc/oauth-user-access-token-management "It is valid for 24 hours after initial issuance."
+export const ACCESS_TTL = 86400;
+// source: https://developers.tiktok.com/doc/oauth-user-access-token-management "It is valid for 365 days after the initial issuance."
+export const REFRESH_TTL = 31536000;
+
+/** A credential of TikTok's form (`act.…`, `rft.…`), drawn from the World's secret under its minted id. */
+export async function credential(ctx: HandlerContext, type: string, prefix: string, fields: Row): Promise<{ id: string; value: string }> {
+  const id = ctx.mint(type);
+  const value = `${prefix}.${(await ctx.secret(`tiktok:${type}:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 36)}!${(await ctx.secret(`tiktok:${type}:${id}:n`)).replace(/\D/g, '').padEnd(4, '0').slice(0, 4)}`;
+  await ctx.record(type, { ...fields, sha256: sha256(ctx, value), created: ctx.occurredAt }, id);
+  return { id, value };
+}
+export const bySha = (ctx: Pick<HandlerContext, 'rowsRaw' | 'crypto'>, type: string, value: string): Row | undefined =>
+  ctx.rowsRaw(type).find((r) => r.deleted !== true && r.sha256 === sha256(ctx, value));
+
+/** The World's next number in a sequence (an id's number, a nonce): issued from the tree over the declared
+ *  `_seq_<what>` (ctx.issue), never a row count. */
+export const next = async (ctx: Pick<HandlerContext, 'issue'>, what: 'publish' | 'video'): Promise<number> => Number(await ctx.issue(`_seq_${what}`));
+
+/** A video's moment, the position its creator's list pages by: the World's clock in milliseconds, one past the creator's
+ *  latest video's when the clock has not moved past it, so two videos never share a cursor. From the subject's history,
+ *  never an accumulator. */
+export const videoMoment = (ctx: Pick<HandlerContext, 'rowsRaw' | 'occurredAt'>, person: string): number =>
+  Math.max(Date.parse(ctx.occurredAt), ...ctx.rowsRaw(VIDEO).filter((v) => v._person === person).map((v) => Number(v._moment) + 1));
+
+/** A creator's public videos newest first, the page before a cursor (a moment; none is the newest), and the cursor
+ *  the page answers (its last video's moment). */
+export function videoPage(ctx: Pick<HandlerContext, 'rowsRaw'>, person: string, cursor: number, max: number): { page: Row[]; cursor: number; more: boolean } {
+  const mine = ctx.rowsRaw(VIDEO).filter((v) => v.deleted !== true && v._person === person && v._public === true && Number(v._moment) < cursor)
+    .sort((a, z) => Number(z._moment) - Number(a._moment));
+  const page = mine.slice(0, max);
+  return { page, cursor: page.length ? Number(page.at(-1)!._moment) : 0, more: mine.length > max };
+}
+
+/** The privacy levels a creator may post at: "If the TikTok creator account is public, the available options are:
+ *  PUBLIC_TO_EVERYONE MUTUAL_FOLLOW_FRIENDS SELF_ONLY"; a private one's, FOLLOWER_OF_CREATOR in place of the first. */
+// source: https://developers.tiktok.com/doc/content-posting-api-reference-query-creator-info "If the TikTok creator account is public, the available options are:"
+export const privacyOptions = (p: Row): string[] => (p.private === true ? ['FOLLOWER_OF_CREATOR', 'MUTUAL_FOLLOW_FRIENDS', 'SELF_ONLY'] : ['PUBLIC_TO_EVERYONE', 'MUTUAL_FOLLOW_FRIENDS', 'SELF_ONLY']);
+
+export { publish } from "../../open/src/semantics/states.ts";

package/src/server.ts

@@ -0,0 +1,8 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp, type PackFetchOptions } from '@volter/world-core';
+import { createTiktokFetch } from './fetch.ts';
+
+export async function createTiktokTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createTiktokFetch(options) });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/client/tiktok-consent.tsx

@@ -1,154 +0,0 @@
-// TikTok's AUTHORIZATION PAGE, as React — the vendor's own product UI, not a dashboard mirror.
-//
-// These components are the ONE renderer for the screen: the twin server-renders them with
-// `renderToStaticMarkup` to answer `GET https://www.tiktok.com/v2/auth/authorize`, the capability
-// verifies render the SAME exported components over the SAME projection, and the Playwright
-// journey drives the HTML they emit. There is no second implementation to drift from.
-//
-// NO BROWSER BUNDLE, DELIBERATELY. The whole screen is a plain `<form>`: one checkbox per
-// requested scope and two submit buttons. Nothing on it needs JavaScript, so this pack ships no
-// browser entry and no committed bundle — the served page is server-rendered markup plus an
-// inline stylesheet (`tiktok-consent-ui.ts`). That keeps the serve path free of a bundler
-// (runtime contract R12b) and free of a generated artifact to drift, and it means `curl`,
-// redirect-following HTTP libraries and headless browsers all complete an OAuth round trip
-// against this twin identically.
-//
-// WHY THE CHECKBOXES ARE THE DESIGN. TikTok's documented callback carries a `scopes` parameter —
-// "the authorization scope(s) which the user has granted" — and the token response's `scope` is
-// "the scopes the user has agreed to authorize". Both are only meaningful if the granted set can
-// be a SUBSET of the requested set, so the decision this page collects is per scope. LAYOUT
-// PROVENANCE: the app/account header, the permission list and the Cancel/Continue pair reproduce
-// TikTok's authorization sheet as widely screenshotted; the live DOM was not captured from a
-// vendor artefact, so visual fidelity is certified by the journey filmstrip review and pinned by
-// `tiktok.consent.optional_scope_toggles` / `tiktok.consent.button_wording` (todo), never
-// asserted as vendor fact.
-
-export type ConsentAccount = {
-  /** The account's `union_id` — the twin's subject key for a TikTok human. */
-  unionId: string;
-  username: string;
-  displayName: string;
-};
-// NO `avatarUrl` HERE, deliberately (§9 nit): the state builder used to carry one that nothing
-// rendered — a field on the view model that no pixel depends on is a data-coupling claim with
-// nothing behind it. The live sheet does show an avatar; serving one would mean an `<img>` at a
-// tiktokcdn.com URL, and a twin never reaches a vendor CDN (see TikTokMark, drawn rather than
-// fetched). When the avatar is worth rendering it comes back as bytes the twin serves, with a
-// data-coupled UI capability that asserts the seeded persona's own image — not before.
-
-export type ConsentScopeRow = {
-  scope: string;
-  label: string;
-  product: string;
-  known: boolean;
-};
-
-export type ConsentApp = {
-  clientKey: string;
-  name: string;
-};
-
-export type ConsentView = {
-  requestId: string;
-  /** Where the twin is reachable — the form action posts back here. */
-  origin: string;
-  app: ConsentApp;
-  /** The tiktok.com session this browser is signed in as — the account that will consent. */
-  account: ConsentAccount;
-  scopes: ConsentScopeRow[];
-  /** Host of the validated redirect_uri, shown in the "you'll be redirected to" notice. */
-  redirectHost: string;
-};
-
-/** The TikTok note mark, drawn rather than fetched — a twin never reaches out to a vendor CDN. */
-function TikTokMark() {
-  return (
-    <span className="tt-mark" aria-hidden="true">
-      ♪
-    </span>
-  );
-}
-
-/** The authorization page — TikTok's consent sheet for the app named by the pending request. */
-export function ConsentPage({ view }: { view: ConsentView }) {
-  const appName = view.app.name;
-  return (
-    <div className="card">
-      <header className="tt-header">
-        <TikTokMark />
-        <span className="tt-wordmark">TikTok</span>
-      </header>
-      <div className="signed-in">
-        <span className="account-text">
-          {/* A partially-pulled persona may lack a display name or handle; the fallback shows the
-              REAL union id rather than an empty pill or a bare "@" (never an invented placeholder). */}
-          <span className="account-name">{view.account.displayName || view.account.username || view.account.unionId}</span>
-          {view.account.username ? <span className="account-username">@{view.account.username}</span> : null}
-        </span>
-      </div>
-      <h1 className="title">
-        <strong className="app-name">{appName}</strong> would like to access your TikTok account
-      </h1>
-      <form method="POST" action={`${view.origin}/_twin/consent`} className="consent-form">
-        <input type="hidden" name="auth_request" value={view.requestId} />
-        <p className="scope-lead">This will allow {appName} to:</p>
-        <ul className="scope-list">
-          {view.scopes.map((row) => (
-            <li key={row.scope} className="scope-row">
-              <label className="scope-label">
-                <input className="scope-check" type="checkbox" name="scope" value={row.scope} defaultChecked />
-                <span className="scope-text">{row.label}</span>
-              </label>
-              {row.known ? null : <span className="scope-tag scope-tag-unknown">not in the twin&apos;s scope catalog</span>}
-            </li>
-          ))}
-        </ul>
-        <div className="actions">
-          <button className="btn btn-secondary" type="submit" name="decision" value="deny">
-            Cancel
-          </button>
-          <button className="btn btn-primary" type="submit" name="decision" value="allow">
-            Continue
-          </button>
-        </div>
-      </form>
-      <p className="legal">
-        You&apos;ll be redirected to <strong className="redirect-host">{view.redirectHost}</strong>. You can remove this
-        app at any time from Manage app permissions in your TikTok settings.
-      </p>
-    </div>
-  );
-}
-
-export type ErrorPageProps = {
-  status: number;
-  /** The OAuth error code the failure classifies as (e.g. `invalid_request`). */
-  code: string;
-  detail: string;
-  /** The offending parameter, echoed for the developer. */
-  requestParam?: string;
-};
-
-/**
- * The authorize-endpoint error PAGE — what a browser sees when the twin cannot trust the
- * redirect_uri (unknown client_key, unregistered callback) and therefore must not bounce the error
- * back to it. TikTok's live page for this case was not captured, so this page states the failure
- * plainly and machine-readably rather than imitating unverified vendor prose
- * (`tiktok.authorize.error_page_fidelity`, todo).
- */
-export function ErrorPage({ status, code, detail, requestParam }: ErrorPageProps) {
-  return (
-    <div className="card card-error">
-      <header className="tt-header">
-        <TikTokMark />
-        <span className="tt-wordmark">TikTok</span>
-      </header>
-      <h1 className="title">Something went wrong</h1>
-      <p className="error-detail">You weren&apos;t able to give access to the app. {detail}</p>
-      <p className="error-code">
-        Error {status}: {code}
-      </p>
-      {requestParam ? <p className="error-request">Request details: {requestParam}</p> : null}
-    </div>
-  );
-}