@volter/twin-tiktok 0.1.0

package/src/tiktok-twin.ts

@@ -0,0 +1,1361 @@
+// TikTok twin REQUEST HANDLER — Login Kit + the Display API, served locally.
+//
+// Contract: handleTikTokTwinRequest({method, path, ...}) -> {status, body, headers}. It is the
+// faithful surface an unmodified TikTok integration talks to:
+//
+//   www.tiktok.com        GET  /v2/auth/authorize     → the AUTHORIZATION page (Login Kit)
+//   open.tiktokapis.com   POST /v2/oauth/token/       → authorization_code | refresh_token |
+//                                                       client_credentials grants
+//                         POST /v2/oauth/revoke/      → revoke a user access token
+//                         GET  /v2/user/info/         → the Display API user read
+//                         POST /v2/video/list/        → the Display API video list
+//                         POST /v2/video/query/       → the Display API video lookup
+//                         POST /v2/post/publish/…     → the Content Posting API (tiktok-posting.ts)
+//   open-upload.tiktokapis.com PUT /video/            → the chunked video upload (tiktok-posting.ts)
+//
+// ── WHY THIS PACK IS BROWSER-FACING ─────────────────────────────────────────────────────────────
+// The point of the authorization-code flow is that a browser is redirected to the vendor, a person
+// reads what the app is asking for, and decides. A twin that skipped the page and 302'd straight
+// back would be a bypass, not a twin — every integration bug that lives in the consent leg (an
+// unregistered redirect_uri, a dropped state, a user who cancels, a user who UNCHECKS a scope)
+// would be invisible. So the twin SERVES HTML at the vendor's real path, rendered server-side from
+// its own projection by the SAME React components the pack ships (tiktok-consent-ui.ts). The
+// googleoauth pack is the class precedent; the mirror DISCIPLINE applies in full.
+//
+// ── WHAT THIS VENDOR DOES THAT ITS SIBLINGS DO NOT (the fidelity surface) ───────────────────────
+//   • SCOPES ARE COMMA-SEPARATED, and consent is GRANULAR: the documented callback carries a
+//     `scopes` parameter naming what the user GRANTED, which may be a subset of what was asked.
+//   • PKCE IS OPTIONAL (web) and, when used, its `code_challenge` is HEX-encoded SHA-256, not
+//     RFC 7636's base64url. See tiktok-pkce.ts.
+//   • THE CLIENT AUTHENTICATES IN THE BODY: `client_key` + `client_secret` form fields. TikTok
+//     documents no HTTP Basic alternative, so an Authorization header on the token endpoint is
+//     IGNORED — which matters, because Dub sends one.
+//   • TWO ERROR ENVELOPES, not one: flat `{error, error_description, log_id}` on the OAuth
+//     endpoints and nested `{data, error:{code, message, log_id}}` on the v2 API. See
+//     tiktok-errors.ts.
+//   • `open_id` IS PER-APP while `union_id` is per-human: the same account authorizing two apps
+//     yields two different open_ids and one union_id.
+//
+// ── WHAT IS NOT ─────────────────────────────────────────────────────────────────────────────────
+// The twin authenticates NOBODY: no password, no 2FA, no risk engine. The tiktok.com "signed in"
+// session is a seeded persona row (`POST /_twin/session` switches it) — a deliberate design, not a
+// hidden gap.
+//
+// EVIDENCE BOUNDARIES are marked inline: behaviours grounded in developers.tiktok.com (all fetched
+// 2026-09-13) say so; behaviours derived from RFC 6749/7009 or widely-reported wire captures are
+// marked EXTRAPOLATION with a manifest todo pinning them.
+//
+// State lives in the kernel action log (D1). No real TikTok endpoint is ever called from this path.
+import { applyTwinWriteAtomic, type TwinResource } from '@volter/world-core';
+import { consentPageHtml, errorPageHtml, tiktokConsentState } from './tiktok-consent-ui.ts';
+import {
+  apiError,
+  apiOk,
+  internalError,
+  invalidClient,
+  invalidGrant,
+  malformedRequest,
+  oauthError,
+  oauthErrorCode,
+  unknownRoute,
+  type TikTokResponse,
+} from './tiktok-errors.ts';
+import { formatScopeParam, parseScopeParam, KNOWN_SCOPES } from './tiktok-scopes.ts';
+import { isSupportedChallengeMethod, pkceVerifies } from './tiktok-pkce.ts';
+import { creatorInfo, fetchStatus, initUpload, MEDIA_PREFIX, serveVideo, UPLOAD_PATH, uploadChunk, type PostingContext } from './tiktok-posting.ts';
+import {
+  USER_FIELDS,
+  USER_FIELD_SCOPES,
+  VIDEO_FIELDS,
+  VIDEO_SCOPE,
+  renderUser,
+  renderVideo,
+} from './tiktok-user.ts';
+import {
+  authRequestIdFor,
+  BK_ACCESS,
+  BK_CLIENT,
+  BK_CODE,
+  BK_RATE,
+  BK_REFRESH,
+  secretKey,
+  DEFAULT_CLIENT_KEY,
+  ensureSeed,
+  mintAccessToken,
+  mintAuthorizationCode,
+  mintClientKey,
+  mintClientToken,
+  mintRefreshToken,
+  nextRev,
+  nextRevIn,
+  openIdFor,
+  readAll,
+  readOne,
+  readType,
+  redirectUriAllowed,
+  RESOURCE_TYPES as STORE_RESOURCE_TYPES,
+  sessionAccount,
+  write,
+  writeAtomic,
+  type Row,
+} from './tiktok-store.ts';
+
+export { RESOURCE_TYPES } from './tiktok-store.ts';
+export type { TikTokResponse } from './tiktok-errors.ts';
+export { USER_FIELDS, VIDEO_FIELDS } from './tiktok-user.ts';
+
+/** TikTok's real hosts. The authorization page lives on the web property; the API on the open
+ *  platform host. Both are claimed path-scoped by the pack descriptor. */
+export const AUTHORIZE_ORIGIN = 'https://www.tiktok.com';
+export const API_ORIGIN = 'https://open.tiktokapis.com';
+
+/** "The expiration of `access_token` in seconds. It is valid for 24 hours" (User Access Token
+ *  Management guide) — and the guide's own example body says `"expires_in": 86400`. */
+export const ACCESS_TOKEN_TTL_SECONDS = 86_400;
+/** "The token to refresh `access_token`. It is valid for 365 days"; the example says 31536000. */
+export const REFRESH_TOKEN_TTL_SECONDS = 31_536_000;
+/** The app-only client token: "valid for 2 hours after the initial issuance" (client-credentials
+ *  guide), example `"expires_in": 7200`. */
+export const CLIENT_TOKEN_TTL_SECONDS = 7_200;
+/** EXTRAPOLATION: TikTok publishes no authorization-code lifetime. Ten minutes is the OAuth
+ *  convention (RFC 6749 §4.1.2 recommends ≤10 min); `tiktok.token.code_ttl` (todo) pins the live
+ *  value. The SINGLE-USE rule, by contrast, is hard protocol and is modelled as such. */
+export const AUTH_CODE_TTL_SECONDS = 600;
+
+/** "Request rate calculation is based on a one minute sliding window" and each of /v2/user/info/,
+ *  /v2/video/list/ and /v2/video/query/ is published at 600 (developers.tiktok.com rate-limit
+ *  reference, fetched 2026-09-13). Exceeding one answers HTTP 429 + `rate_limit_exceeded`. */
+export const RATE_LIMIT_PER_WINDOW = 600;
+export const RATE_WINDOW_SECONDS = 60;
+
+/** The metered endpoints, keyed the way the rate rows are. */
+export const METERED_ENDPOINTS = ['user_info', 'video_list', 'video_query', 'creator_info', 'video_init', 'inbox_init', 'post_status'] as const;
+export type MeteredEndpoint = (typeof METERED_ENDPOINTS)[number];
+
+/** Each metered endpoint's allowance per user access_token per minute. The Display API reads are the
+ *  rate-limit reference's 600; the Content Posting ones are each reference's own sentence (fetched
+ *  2026-09-27): creator_info "limited to 20 requests per minute", the Direct Post and inbox inits
+ *  "limited to 6 requests per minute", status/fetch "limited to 30 requests per minute". */
+export const RATE_LIMITS: Record<MeteredEndpoint, number> = {
+  user_info: RATE_LIMIT_PER_WINDOW,
+  video_list: RATE_LIMIT_PER_WINDOW,
+  video_query: RATE_LIMIT_PER_WINDOW,
+  creator_info: 20,
+  video_init: 6,
+  inbox_init: 6,
+  post_status: 30,
+};
+
+export type TikTokRequest = {
+  method: string;
+  /** Path plus query string, e.g. `/v2/auth/authorize?client_key=…`. */
+  path: string;
+  body?: string;
+  /** Lower-cased request headers (authorization / content-type). */
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** Where this twin is reached (`twinPublicBase`: origin plus any served-World mount path) — the
+   *  consent form's action must point back at the twin. Absent (an in-process call), vendor-real
+   *  URLs are used. */
+  origin?: string;
+  /** The bare origin the request arrived at, when it differs from `origin` (a served World mounts
+   *  the twin under a path). The seeded demo app's callbacks derive from it; defaults to `origin`. */
+  callbackOrigin?: string;
+  /** The raw body of a chunk PUT to the upload URL (every other body is text). */
+  bytes?: Uint8Array;
+  /** The vendor host the request named (`x-volter-twin-original-host`), when the injector or a World
+   *  door forwarded it: an upload_url minted for it is on the vendor's own upload host. */
+  originalHost?: string;
+};
+
+const HTML = { 'content-type': 'text/html; charset=utf-8' };
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────────
+
+/** Split path from query and NORMALISE the trailing slash. TikTok's own documentation writes the
+ *  API paths WITH one (`/v2/oauth/token/`) while Dub's authorize URL omits it
+ *  (`/v2/auth/authorize`), so both spellings must reach the same route. */
+function splitPath(raw: string): { path: string; query: URLSearchParams } {
+  const [p, q = ''] = raw.split('?');
+  const path = (p ?? '/').replace(/\/+$/, '') || '/';
+  return { path, query: new URLSearchParams(q) };
+}
+
+/**
+ * The world instant this request happened at. The twin has NO clock of its own (runtime contract
+ * R9: no clock in served content) — `createTikTokTwinFetch` stamps every request with `worldNow()`,
+ * and a caller that names no instant is a DEFECT rather than a cue to read the wall clock. Every
+ * `log_id`, every `expires_in` and every minted credential is derived from this value.
+ */
+function instantOf(occurredAt?: string): string {
+  if (!occurredAt) {
+    throw new Error('tiktok twin: the request carries no occurredAt — this twin has no clock of its own; the server stamps worldNow()');
+  }
+  return occurredAt;
+}
+
+function nowMillis(occurredAt?: string): number {
+  const ms = Date.parse(instantOf(occurredAt));
+  if (Number.isNaN(ms)) throw new Error(`tiktok twin: occurredAt is not a timestamp: ${occurredAt}`);
+  return ms;
+}
+
+function nowSeconds(occurredAt?: string): number {
+  return Math.floor(nowMillis(occurredAt) / 1000);
+}
+
+/**
+ * The authorize endpoint's un-redirectable failure path: until the redirect_uri is proven to
+ * belong to the app there is no address the twin may bounce an error to, so unknown-client and
+ * bad-callback failures render the vendor's error page (200 HTML would hide the failure from
+ * scripts; the page is served WITH the failure's status). EXTRAPOLATION: TikTok's live page and
+ * its HTTP status were not captured — the security boundary itself is RFC 6749 §4.1.2.1's hard
+ * rule. Pinned as `tiktok.authorize.error_page_fidelity` (todo).
+ */
+function errorPage(e: { status: number; code: string; detail: string; requestParam?: string }): TikTokResponse {
+  return { status: e.status, body: errorPageHtml(e), headers: { ...HTML, ...NOSTORE } };
+}
+
+/** A 302 back to a VALIDATED redirect_uri carrying the documented `error`/`error_description`
+ *  callback parameters, plus the caller's `state` when it sent one. */
+function redirectError(redirectUri: string, error: string, description: string, state: string | null): TikTokResponse {
+  const url = new URL(redirectUri);
+  url.searchParams.set('error', error);
+  url.searchParams.set('error_description', description);
+  if (state !== null) url.searchParams.set('state', state);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+/**
+ * The success bounce. TikTok's documented callback table carries `code`, `scopes` and `state` —
+ * `scopes` being "A comma-separated (,) string of authorization scope(s), which the user has
+ * granted", which is what makes granular consent observable to the app before it ever calls the
+ * token endpoint. `state` is echoed only when the caller sent one.
+ */
+function redirectSuccess(redirectUri: string, code: string, grantedScopes: readonly string[], state: string | null): TikTokResponse {
+  const url = new URL(redirectUri);
+  url.searchParams.set('code', code);
+  url.searchParams.set('scopes', formatScopeParam(grantedScopes));
+  if (state !== null) url.searchParams.set('state', state);
+  return { status: 302, body: '', headers: { location: url.toString(), ...NOSTORE } };
+}
+
+/**
+ * Client authentication at the token/revoke endpoints.
+ *
+ * TikTok authenticates the app with the `client_key` and `client_secret` FORM FIELDS — every curl
+ * example in the User Access Token Management guide does exactly that, and the guide documents no
+ * HTTP Basic alternative. So an `Authorization` header here is IGNORED rather than honoured: Dub
+ * sends one (it shares a callback route with its Twitter provider, which needs Basic), and a twin
+ * that required or preferred it would be modelling a different vendor. `tiktok.token.basic_auth`
+ * (todo) pins whether the live endpoint tolerates or refuses the header.
+ *
+ * The missing-secret wording is the vendor's OWN, from the client-credentials guide's error
+ * example: "Client secret is missed in request." The missing-key wording mirrors its shape and is
+ * marked EXTRAPOLATION by `tiktok.token.error_wording` (todo).
+ */
+function authenticateClient(
+  form: URLSearchParams,
+  occurredAt: string,
+  resources: readonly TwinResource[],
+): { client: Row } | { fail: TikTokResponse } {
+  const clientKey = form.get('client_key');
+  if (!clientKey) return { fail: oauthError('invalid_request', 'Client key is missed in request.', occurredAt) };
+  const clientSecret = form.get('client_secret');
+  if (!clientSecret) return { fail: oauthError('invalid_request', 'Client secret is missed in request.', occurredAt) };
+  const client = resources.find((row) => row.type === 'oauth_client' && row.id === clientKey) as Row | undefined;
+  if (!client || client.secretSha256 !== secretKey(clientSecret)) return { fail: invalidClient(occurredAt) };
+  return { client };
+}
+
+// ── the authorization endpoint (the consent page) ───────────────────────────────────────────────
+
+const AUTHORIZE_PATH = '/v2/auth/authorize';
+
+async function authorize(req: TikTokRequest, query: URLSearchParams): Promise<TikTokResponse> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+
+  // 1. client_key — without a trusted app there is no trusted redirect_uri, so failures here
+  //    render the error page.
+  const clientKey = query.get('client_key');
+  if (!clientKey) return errorPage({ status: 400, code: 'invalid_request', detail: 'Missing required parameter: client_key.', requestParam: 'client_key' });
+  const client = readOne(root, 'oauth_client', clientKey);
+  if (!client) return errorPage({ status: 401, code: 'invalid_client', detail: 'The client_key does not name a known TikTok app.', requestParam: `client_key=${clientKey}` });
+
+  // 2. redirect_uri — THE SECURITY BOUNDARY. "It must match one of the redirect URIs you
+  //    registered"; an unregistered one gets the page, never a bounce.
+  const redirectUri = query.get('redirect_uri');
+  if (!redirectUri) return errorPage({ status: 400, code: 'invalid_request', detail: 'Missing required parameter: redirect_uri.', requestParam: 'redirect_uri' });
+  if (!redirectUriAllowed(client, redirectUri)) {
+    return errorPage({
+      status: 400,
+      code: 'invalid_request',
+      detail: 'The redirect_uri does not match any Redirect URI registered for this app.',
+      requestParam: `redirect_uri=${redirectUri}`,
+    });
+  }
+
+  // 3. Everything after the boundary has a trustworthy address, so protocol errors bounce there
+  //    (RFC 6749 §4.1.2.1 — EXTRAPOLATION for TikTok: the docs show no authorize error examples;
+  //    the page-vs-redirect split is pinned by `tiktok.authorize.error_channel`, todo). The
+  //    `error`/`error_description` pair and the codes are the vendor's own.
+  const state = query.get('state');
+  const bounce = (error: string, description: string) => redirectError(redirectUri, error, description, state);
+
+  const responseType = query.get('response_type');
+  if (!responseType) return bounce('invalid_request', 'Missing required parameter: response_type.');
+  // "This value should always be set to `code`" — there is no implicit flow to model, so an
+  // unknown value is the vendor's own unsupported_response_type, not "unmodelled".
+  if (responseType !== 'code') return bounce('unsupported_response_type', `Unsupported response_type: ${responseType}.`);
+
+  const requested = parseScopeParam(query.get('scope'));
+  if (requested.length === 0) return bounce('invalid_request', 'Missing required parameter: scope.');
+  // Every requested scope outside the vendor's catalog: there is nothing to consent to, and
+  // `invalid_scope` is the vendor's own code for "invalid, unknown, or malformed". A MIXED request
+  // still renders, with the unknown entries flagged on the page, so a typo is visible rather than
+  // fatal (`tiktok.scopes.unknown_scope_live`, todo, pins what the live endpoint does).
+  if (!requested.some((s) => KNOWN_SCOPES.includes(s))) {
+    return bounce('invalid_scope', `The requested scope is invalid, unknown, or malformed: ${formatScopeParam(requested)}.`);
+  }
+
+  // PKCE is OPTIONAL on this vendor (required for desktop apps only) and its only method is S256.
+  const codeChallenge = query.get('code_challenge');
+  const rawMethod = query.get('code_challenge_method');
+  if (codeChallenge && !rawMethod) return bounce('invalid_request', 'Missing required parameter: code_challenge_method.');
+  if (!codeChallenge && rawMethod) return bounce('invalid_request', 'Missing required parameter: code_challenge.');
+  if (rawMethod && !isSupportedChallengeMethod(rawMethod)) {
+    return bounce('invalid_request', `Invalid code_challenge_method: ${rawMethod}. TikTok only supports S256.`);
+  }
+
+  // `disable_auto_auth` — documented: "When set to 0, skips the authorization page for valid
+  // sessions. When set to 1, always displays the authorization page." An int, so a non-int value
+  // is malformed input the vendor's own invalid_request covers.
+  const rawAutoAuth = query.get('disable_auto_auth');
+  if (rawAutoAuth !== null && rawAutoAuth !== '0' && rawAutoAuth !== '1') {
+    return bounce('invalid_request', 'Invalid disable_auto_auth: expected 0 or 1.');
+  }
+
+  if (req.readOnly) {
+    return oauthErrorCode('temporarily_unavailable', at, 405);
+  }
+
+  const account = sessionAccount(root);
+  if (!account) {
+    // No signed-in session to consent as. The REAL tiktok.com would show a login screen here; the
+    // twin authenticates nobody, so it states that plainly rather than pretending.
+    return errorPage({ status: 400, code: 'invalid_request', detail: 'No tiktok.com session is signed in on this twin. Seed an account and set /_twin/session.' });
+  }
+
+  // 4. AUTO-AUTH: with `disable_auto_auth=0` and an existing grant that already covers every
+  //    requested KNOWN scope, the vendor skips the page. The twin does the same — and ONLY then:
+  //    the default (parameter absent) is to show the page, because bypassing the human leg is the
+  //    thing this pack exists to make visible and no artefact states the live default
+  //    (`tiktok.authorize.disable_auto_auth_default`, todo).
+  const grantId = `${clientKey}:${account.id}`;
+  const existing = readOne(root, 'grant', grantId);
+  const held: string[] = Array.isArray(existing?.scopes) ? existing.scopes : [];
+  const wantedKnown = requested.filter((s) => KNOWN_SCOPES.includes(s));
+  if (rawAutoAuth === '0' && existing && wantedKnown.every((s) => held.includes(s))) {
+    return settleAuthorization({
+      root,
+      at,
+      clientKey,
+      accountId: account.id,
+      redirectUri,
+      state,
+      granted: wantedKnown,
+      codeChallenge,
+      codeChallengeMethod: rawMethod,
+      requestId: null,
+    });
+  }
+
+  // 5. Record the request, then render the page. The auth_request row is what the Continue/Cancel
+  //    post resolves — the browser never carries the parameters back, so they cannot be tampered
+  //    with between the two legs.
+  const fields = {
+    clientKey,
+    redirectUri,
+    scope: formatScopeParam(requested),
+    state,
+    codeChallenge,
+    codeChallengeMethod: rawMethod,
+    accountId: account.id,
+    settled: false,
+    rev: 1,
+  };
+  const requestId = authRequestIdFor(root, at, fields);
+  await write('auth_request', requestId, 'auth_request.create', fields, { root, occurredAt: at });
+  return renderConsent(req, requestId);
+}
+
+function renderConsent(req: TikTokRequest, requestId: string): TikTokResponse {
+  const view = tiktokConsentState({
+    root: req.root,
+    requestId,
+    origin: req.origin ?? AUTHORIZE_ORIGIN,
+  });
+  if (!view) {
+    return errorPage({ status: 400, code: 'invalid_request', detail: 'Unknown or already-settled authorization request.' });
+  }
+  return { status: 200, body: consentPageHtml(view), headers: { ...HTML, ...NOSTORE } };
+}
+
+/**
+ * Mint the code + grant and bounce. Shared by the auto-auth path (no screen) and the consent post
+ * (a screen the person acted on), so the two can never disagree about what a granted authorization
+ * writes. `requestId` is the pending row to settle, or null when there is none (auto-auth).
+ */
+async function settleAuthorization(opts: {
+  root?: string;
+  at: string;
+  clientKey: string;
+  accountId: string;
+  redirectUri: string;
+  state: string | null;
+  granted: readonly string[];
+  codeChallenge: string | null;
+  codeChallengeMethod: string | null;
+  requestId: string | null;
+}): Promise<TikTokResponse> {
+  const { root, at, clientKey, accountId, requestId } = opts;
+  const issuedMs = Date.parse(at);
+  const code = mintAuthorizationCode(root, issuedMs, requestId ?? `${clientKey}:${accountId}`);
+  const grantId = `${clientKey}:${accountId}`;
+  const openId = openIdFor(clientKey, accountId);
+  const decided = await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      // The settle decision is re-read INSIDE the transaction: two browsers posting the same
+      // screen must not both mint a code (the second sees `settled` and is refused).
+      if (requestId) {
+        const pending = resources.find((row) => row.type === 'auth_request' && row.id === requestId) as Row | undefined;
+        if (!pending || pending.settled === true) {
+          return { kind: 'skip', value: oauthError('invalid_request', 'Unknown, expired, or already-settled authorization request.', at) };
+        }
+      }
+      const grantExists = resources.some((row) => row.type === 'grant' && row.id === grantId);
+      const grantFields = {
+        clientKey,
+        sub: accountId,
+        openId,
+        scopes: [...opts.granted],
+        rev: nextRevIn(resources, 'grant', grantId),
+      };
+      const codeRow = {
+        type: BK_CODE,
+        id: secretKey(code),
+        fields: {
+          clientKey,
+          sub: accountId,
+          openId,
+          scope: formatScopeParam(opts.granted),
+          redirectUri: opts.redirectUri,
+          codeChallenge: opts.codeChallenge,
+          codeChallengeMethod: opts.codeChallengeMethod,
+          consumed: false,
+          expiresAt: Math.floor(issuedMs / 1000) + AUTH_CODE_TTL_SECONDS,
+          rev: 1,
+        },
+      };
+      // The write's SUBJECT is the settled pending request when there is one; on the auto-auth
+      // path there is no screen, so the grant itself is the subject.
+      const base = requestId
+        ? {
+          operation: 'auth_request.settle',
+          subjectType: 'auth_request',
+          subjectId: requestId,
+          fields: { settled: true, rev: nextRevIn(resources, 'auth_request', requestId) },
+        }
+        : { operation: 'grant.auto_authorize', subjectType: 'grant', subjectId: grantId, fields: grantFields };
+      return {
+        kind: 'write',
+        value: redirectSuccess(opts.redirectUri, code, opts.granted, opts.state),
+        write: {
+          ...base,
+          projection: {
+            creates: [
+              ...(requestId && !grantExists ? [{ type: 'grant', id: grantId, fields: grantFields }] : []),
+              codeRow,
+            ],
+            ...(requestId && grantExists ? { updates: [{ type: 'grant', id: grantId, fields: grantFields }] } : {}),
+          },
+          occurredAt: at,
+          actor: { kind: 'human' as const },
+        },
+      };
+    },
+    root,
+  );
+  return decided.value;
+}
+
+/**
+ * The Continue/Cancel post. TWIN-ONLY SURFACE, deliberately namespaced under `/_twin/` and
+ * deliberately ABSENT from the capability manifest: TikTok's authorization sheet posts to an
+ * undocumented internal endpoint, so there is no vendor path to be faithful to here (the
+ * googleoauth `/_twin/consent` precedent, sanctioned by ADDING_A_TWIN.md §6's seed-route rule).
+ *
+ * The checked `scope` fields are the GRANTED set, intersected with what was actually requested so
+ * a hand-crafted post can never widen the grant beyond the screen.
+ */
+async function consentDecision(req: TikTokRequest, form: URLSearchParams): Promise<TikTokResponse> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+  const requestId = form.get('auth_request') ?? '';
+  const authRequest = readOne(root, 'auth_request', requestId);
+  if (!authRequest || authRequest.settled === true) {
+    return oauthError('invalid_request', 'Unknown, expired, or already-settled authorization request.', at);
+  }
+  const redirectUri = String(authRequest.redirectUri);
+  const state = typeof authRequest.state === 'string' ? authRequest.state : null;
+  const requested = parseScopeParam(String(authRequest.scope ?? ''));
+
+  const settleDenial = async (description: string) => {
+    await write('auth_request', requestId, 'auth_request.settle', { settled: true, rev: nextRev(root, 'auth_request', requestId) }, { root, occurredAt: at });
+    return redirectError(redirectUri, 'access_denied', description, state);
+  };
+
+  if (form.get('decision') !== 'allow') {
+    return settleDenial('The resource owner or authorization server denied the request.');
+  }
+  const account = readOne(root, 'account', String(authRequest.accountId ?? ''));
+  if (!account) return oauthError('invalid_request', 'The account shown for this authorization request no longer exists.', at);
+
+  // Only scopes that were REQUESTED and are in the vendor catalog can be granted.
+  const checked = form.getAll('scope').filter((s) => requested.includes(s) && KNOWN_SCOPES.includes(s));
+  if (checked.length === 0) {
+    // Unchecking everything is a refusal, not a zero-scope grant. EXTRAPOLATION on the wire
+    // (`tiktok.consent.no_scope_granted`, todo); what is NOT extrapolated is that a token with no
+    // scope could serve nothing, so minting one would be the fake success §6 forbids.
+    return settleDenial('The resource owner granted none of the requested scopes.');
+  }
+
+  return settleAuthorization({
+    root,
+    at,
+    clientKey: String(authRequest.clientKey),
+    accountId: account.id,
+    redirectUri,
+    state,
+    granted: requested.filter((s) => checked.includes(s)),
+    codeChallenge: typeof authRequest.codeChallenge === 'string' ? authRequest.codeChallenge : null,
+    codeChallengeMethod: typeof authRequest.codeChallengeMethod === 'string' ? authRequest.codeChallengeMethod : null,
+    requestId,
+  });
+}
+
+// ── the token endpoint ──────────────────────────────────────────────────────────────────────────
+
+async function token(req: TikTokRequest): Promise<TikTokResponse> {
+  const at = instantOf(req.occurredAt);
+  // TikTok's token endpoint is `application/x-www-form-urlencoded` (every documented curl). The
+  // twin is deliberately strict about that rather than tolerating a JSON body it has no evidence
+  // the vendor accepts (`tiktok.token.json_body_tolerance`, todo).
+  const form = new URLSearchParams(req.body ?? '');
+  const grantType = form.get('grant_type');
+  if (!grantType) return oauthError('invalid_request', 'Grant type is missed in request.', at);
+  if (grantType === 'authorization_code') return authorizationCodeGrant(req, form, at);
+  if (grantType === 'refresh_token') return refreshTokenGrant(req, form, at);
+  if (grantType === 'client_credentials') return clientCredentialsGrant(req, form, at);
+  return oauthErrorCode('unsupported_grant_type', at);
+}
+
+/** The user-token body, field for field from the guide's own success example. */
+function issuedTokenResponse(accessToken: string, openId: string, scope: string, refreshToken: string): TikTokResponse {
+  return {
+    status: 200,
+    body: {
+      access_token: accessToken,
+      expires_in: ACCESS_TOKEN_TTL_SECONDS,
+      open_id: openId,
+      refresh_expires_in: REFRESH_TOKEN_TTL_SECONDS,
+      refresh_token: refreshToken,
+      scope,
+      token_type: 'Bearer',
+    },
+    headers: { ...NOSTORE, 'content-type': 'application/json; charset=utf-8' },
+  };
+}
+
+async function authorizationCodeGrant(req: TikTokRequest, form: URLSearchParams, at: string): Promise<TikTokResponse> {
+  const root = req.root;
+  const code = form.get('code');
+  if (!code) return oauthError('invalid_request', 'Authorization code is missed in request.', at);
+  const redirectUri = form.get('redirect_uri');
+  if (!redirectUri) return oauthError('invalid_request', 'Redirect uri is missed in request.', at);
+
+  const issuedMs = Date.parse(at);
+  const accessToken = mintAccessToken(root, issuedMs, code);
+  const refreshToken = mintRefreshToken(root, issuedMs, code);
+  const committed = await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      const auth = authenticateClient(form, at, resources);
+      if ('fail' in auth) return { kind: 'skip', value: auth.fail };
+      const row = resources.find((r) => r.type === BK_CODE && r.id === secretKey(code)) as Row | undefined;
+      if (!row || row.clientKey !== auth.client.id || row.consumed === true
+        || (typeof row.expiresAt === 'number' && nowSeconds(at) >= row.expiresAt)) {
+        return { kind: 'skip', value: invalidGrant(at) };
+      }
+      // The redirect_uri "must be the same as the redirect_uri used for requesting code" — the
+      // vendor's own error example for this case is `invalid_request` with "Redirect_uri is not
+      // matched with the uri when requesting code.", so it is NOT folded into invalid_grant.
+      if (redirectUri !== row.redirectUri) {
+        return { kind: 'skip', value: oauthError('invalid_request', 'Redirect_uri is not matched with the uri when requesting code.', at) };
+      }
+      // PKCE binds only when the authorize leg carried a challenge (web apps send none).
+      const challenge = typeof row.codeChallenge === 'string' ? row.codeChallenge : null;
+      if (challenge) {
+        const verifier = form.get('code_verifier');
+        if (!verifier) return { kind: 'skip', value: oauthError('invalid_request', 'Code verifier is missed in request.', at) };
+        if (!pkceVerifies(challenge, verifier)) return { kind: 'skip', value: invalidGrant(at) };
+      }
+      const scope = String(row.scope);
+      const openId = String(row.openId);
+      return {
+        kind: 'write',
+        value: issuedTokenResponse(accessToken, openId, scope, refreshToken),
+        write: {
+          operation: 'authorization_code.redeem',
+          subjectType: BK_CODE,
+          subjectId: secretKey(code),
+          fields: { consumed: true, rev: nextRevIn(resources, BK_CODE, secretKey(code)) },
+          projection: {
+            creates: [
+              {
+                type: BK_ACCESS,
+                id: secretKey(accessToken),
+                fields: { clientKey: auth.client.id, sub: String(row.sub), openId, scope, expiresAt: nowSeconds(at) + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: 1 },
+              },
+              {
+                type: BK_REFRESH,
+                id: secretKey(refreshToken),
+                fields: { clientKey: auth.client.id, sub: String(row.sub), openId, scope, expiresAt: nowSeconds(at) + REFRESH_TOKEN_TTL_SECONDS, revoked: false, rev: 1 },
+              },
+            ],
+          },
+          occurredAt: at,
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+async function refreshTokenGrant(req: TikTokRequest, form: URLSearchParams, at: string): Promise<TikTokResponse> {
+  const root = req.root;
+  const presented = form.get('refresh_token');
+  if (!presented) return oauthError('invalid_request', 'Refresh token is missed in request.', at);
+  const issuedMs = Date.parse(at);
+  const accessToken = mintAccessToken(root, issuedMs, presented);
+  const replacement = mintRefreshToken(root, issuedMs, presented);
+  const committed = await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      const auth = authenticateClient(form, at, resources);
+      if ('fail' in auth) return { kind: 'skip', value: auth.fail };
+      const row = resources.find((r) => r.type === BK_REFRESH && r.id === secretKey(presented)) as Row | undefined;
+      if (!row || row.revoked === true || row.clientKey !== auth.client.id
+        || (typeof row.expiresAt === 'number' && nowSeconds(at) >= row.expiresAt)) {
+        return { kind: 'skip', value: invalidGrant(at) };
+      }
+      const scope = String(row.scope);
+      const openId = String(row.openId);
+      return {
+        kind: 'write',
+        value: issuedTokenResponse(accessToken, openId, scope, replacement),
+        write: {
+          // ROTATION. The guide says "the returned refresh_token may be different than the one
+          // passed in the payload", which makes persisting the returned value mandatory for a
+          // correct client. The twin always rotates and retires the presented token, so an
+          // integration that keeps the old one fails HERE rather than in production
+          // (`tiktok.refresh.rotation`, todo, pins whether the live vendor always rotates).
+          operation: 'refresh_token.rotate',
+          subjectType: BK_REFRESH,
+          subjectId: secretKey(presented),
+          fields: { revoked: true, rev: nextRevIn(resources, BK_REFRESH, secretKey(presented)) },
+          projection: {
+            creates: [
+              { type: BK_ACCESS, id: secretKey(accessToken), fields: { clientKey: auth.client.id, sub: String(row.sub), openId, scope, expiresAt: nowSeconds(at) + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: 1 } },
+              { type: BK_REFRESH, id: secretKey(replacement), fields: { clientKey: auth.client.id, sub: String(row.sub), openId, scope, expiresAt: nowSeconds(at) + REFRESH_TOKEN_TTL_SECONDS, revoked: false, rev: 1 } },
+            ],
+          },
+          occurredAt: at,
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+/**
+ * The APP-ONLY token (client-credentials guide): no user, no open_id, no scope, no refresh token,
+ * and a 2-hour life. Its own example body is `{access_token: "clt.…", expires_in: 7200,
+ * token_type: "Bearer"}` — three fields, and the twin serves exactly three.
+ */
+async function clientCredentialsGrant(req: TikTokRequest, form: URLSearchParams, at: string): Promise<TikTokResponse> {
+  const root = req.root;
+  const issuedMs = Date.parse(at);
+  const clientToken = mintClientToken(root, issuedMs, form.get('client_key') ?? 'client');
+  const committed = await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      const auth = authenticateClient(form, at, resources);
+      if ('fail' in auth) return { kind: 'skip', value: auth.fail };
+      return {
+        kind: 'write',
+        value: {
+          status: 200,
+          body: { access_token: clientToken, expires_in: CLIENT_TOKEN_TTL_SECONDS, token_type: 'Bearer' },
+          headers: { ...NOSTORE, 'content-type': 'application/json; charset=utf-8' },
+        } as TikTokResponse,
+        write: {
+          operation: 'client_token.issue',
+          subjectType: BK_CLIENT,
+          subjectId: secretKey(clientToken),
+          fields: { clientKey: auth.client.id, expiresAt: nowSeconds(at) + CLIENT_TOKEN_TTL_SECONDS, revoked: false, rev: 1 },
+          occurredAt: at,
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+// ── the revoke endpoint ─────────────────────────────────────────────────────────────────────────
+
+async function revoke(req: TikTokRequest): Promise<TikTokResponse> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+  const form = new URLSearchParams(req.body ?? '');
+  const auth = authenticateClient(form, at, readAll(root));
+  if ('fail' in auth) return auth.fail;
+  const { client } = auth;
+
+  const presented = form.get('token');
+  if (!presented) return malformedRequest(at);
+
+  const access = readOne(root, BK_ACCESS, secretKey(presented));
+  const refresh = readOne(root, BK_REFRESH, secretKey(presented));
+  const match = access ?? refresh;
+
+  // An unknown token answers the documented empty success (RFC 7009 §2.2: "invalid tokens do not
+  // cause an error" — answering differently would let an app probe which tokens exist). A token
+  // belonging to ANOTHER app also answers empty, WITHOUT revoking. Which reading TikTok takes is
+  // UNPINNED — `tiktok.revoke.unknown_token` and `tiktok.revoke.cross_client` (todo).
+  if (match && match.clientKey === client.id) {
+    // Revocation is the "remove this app" action, and the GRANT is what dies: every access token,
+    // every refresh token, and the grant itself, whichever half was named. Revoking only the named
+    // token would leave a "disconnected" user's other half alive (`tiktok.revoke.pair_revocation`,
+    // todo, pins the live sweep).
+    const opts = { root, occurredAt: at };
+    const sub = String(match.sub);
+    const clientKey = String(match.clientKey);
+    const grantId = `${clientKey}:${sub}`;
+    const grant = readOne(root, 'grant', grantId);
+    if (grant) {
+      for (const row of readType(root, BK_ACCESS)) {
+        if (row.sub === sub && row.clientKey === clientKey && row.revoked !== true) {
+          await write(BK_ACCESS, row.id, 'access_token.revoke', { revoked: true, rev: nextRev(root, BK_ACCESS, row.id) }, opts);
+        }
+      }
+      for (const row of readType(root, BK_REFRESH)) {
+        if (row.sub === sub && row.clientKey === clientKey && row.revoked !== true) {
+          await write(BK_REFRESH, row.id, 'refresh_token.revoke', { revoked: true, rev: nextRev(root, BK_REFRESH, row.id) }, opts);
+        }
+      }
+      await write('grant', grantId, 'grant.revoke', { clientKey, sub, openId: grant.openId, scopes: [], rev: nextRev(root, 'grant', grantId) }, opts);
+    } else {
+      const type = access ? BK_ACCESS : BK_REFRESH;
+      await write(type, match.id, `${access ? 'access_token' : 'refresh_token'}.revoke`, { revoked: true, rev: nextRev(root, type, match.id) }, opts);
+    }
+  }
+  // "If the request is successful, the response struct will be empty."
+  return { status: 200, body: {}, headers: { ...NOSTORE, 'content-type': 'application/json; charset=utf-8' } };
+}
+
+// ── the Display API reads ───────────────────────────────────────────────────────────────────────
+
+type AuthorizedContext = {
+  resources: readonly TwinResource[];
+  account: Row;
+  openId: string;
+  scopes: string[];
+};
+
+/**
+ * The shared front half of every Display API read: bearer -> live user access token -> the grant's
+ * scope set and open_id -> the account -> the one-minute rate window. The endpoint body then runs
+ * over that context and returns its own response; the rate window is spent only when the read
+ * SUCCEEDS (`tiktok.rate.what_counts`, todo, pins what the live meter counts) and never when the
+ * twin is read-only.
+ */
+async function authorizedRead(
+  req: TikTokRequest,
+  endpoint: MeteredEndpoint,
+  serve: (ctx: AuthorizedContext) => TikTokResponse,
+): Promise<TikTokResponse> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+  const header = req.headers?.authorization ?? '';
+  const bearer = /^bearer\s+(.+)$/i.exec(header)?.[1]?.trim();
+  if (!bearer) return apiError('access_token_invalid', at);
+
+  const evaluate = (resources: readonly TwinResource[]) => {
+    const tokenRow = resources.find((r) => r.type === BK_ACCESS && r.id === secretKey(bearer)) as Row | undefined;
+    if (!tokenRow || tokenRow.revoked === true
+      || (typeof tokenRow.expiresAt === 'number' && nowSeconds(at) >= tokenRow.expiresAt)) {
+      return { response: apiError('access_token_invalid', at) };
+    }
+    const grantId = `${String(tokenRow.clientKey)}:${String(tokenRow.sub)}`;
+    const grant = resources.find((r) => r.type === 'grant' && r.id === grantId) as Row | undefined;
+    // The TOKEN's scope is what was granted when it was minted; the GRANT is the live record and a
+    // revoked grant empties it. The intersection is what the token may still do.
+    const granted: string[] = Array.isArray(grant?.scopes) ? grant.scopes : [];
+    const scopes = parseScopeParam(String(tokenRow.scope ?? '')).filter((s) => granted.includes(s));
+    const account = resources.find((r) => r.type === 'account' && r.id === String(tokenRow.sub)) as Row | undefined;
+    if (!account) return { response: apiError('access_token_invalid', at) };
+
+    const now = nowSeconds(at);
+    const windowId = `${endpoint}:${String(tokenRow.openId ?? '')}`;
+    const rateRow = resources.find((r) => r.type === BK_RATE && r.id === windowId) as Row | undefined;
+    const active = rateRow && typeof rateRow.windowStart === 'number' && now < rateRow.windowStart + RATE_WINDOW_SECONDS;
+    const windowStart = active ? Number(rateRow.windowStart) : now;
+    const before = active && typeof rateRow.used === 'number' ? rateRow.used : 0;
+    if (before >= RATE_LIMITS[endpoint]) return { response: apiError('rate_limit_exceeded', at) };
+
+    const response = serve({ resources, account, openId: String(tokenRow.openId ?? ''), scopes });
+    if (response.status !== 200) return { response };
+    return { response, windowId, windowStart, used: before + 1 };
+  };
+
+  if (req.readOnly) return evaluate(readAll(root)).response;
+  const committed = await applyTwinWriteAtomic(
+    'tiktok',
+    (resources) => {
+      const result = evaluate(resources);
+      if (!result.windowId) return { kind: 'skip', value: result.response };
+      return {
+        kind: 'write',
+        value: result.response,
+        write: {
+          operation: 'rate_window.spend',
+          subjectType: BK_RATE,
+          subjectId: result.windowId,
+          fields: { windowStart: result.windowStart, used: result.used, rev: nextRevIn(resources, BK_RATE, result.windowId) },
+          occurredAt: at,
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return committed.value;
+}
+
+/**
+ * The Content Posting calls' front half: the same bearer -> token -> grant -> account -> rate window
+ * resolution as a Display API read, then the endpoint body, which may stage bytes (so it runs OUTSIDE
+ * the kernel transaction). The window is spent once the endpoint has answered 2xx, and never on a
+ * read-only twin.
+ */
+async function authorizedPosting(
+  req: TikTokRequest,
+  endpoint: MeteredEndpoint,
+  serve: (ctx: PostingContext) => Promise<TikTokResponse> | TikTokResponse,
+): Promise<TikTokResponse> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+  const bearer = /^bearer\s+(.+)$/i.exec(req.headers?.authorization ?? '')?.[1]?.trim();
+  if (!bearer) return apiError('access_token_invalid', at);
+  const resources = readAll(root);
+  const tokenRow = resources.find((r) => r.type === BK_ACCESS && r.id === secretKey(bearer)) as Row | undefined;
+  if (!tokenRow || tokenRow.revoked === true || (typeof tokenRow.expiresAt === 'number' && nowSeconds(at) >= tokenRow.expiresAt)) {
+    return apiError('access_token_invalid', at);
+  }
+  const grant = resources.find((r) => r.type === 'grant' && r.id === `${String(tokenRow.clientKey)}:${String(tokenRow.sub)}`) as Row | undefined;
+  const granted: string[] = Array.isArray(grant?.scopes) ? grant.scopes : [];
+  const scopes = parseScopeParam(String(tokenRow.scope ?? '')).filter((s) => granted.includes(s));
+  const account = resources.find((r) => r.type === 'account' && r.id === String(tokenRow.sub)) as Row | undefined;
+  if (!account) return apiError('access_token_invalid', at);
+  const openId = String(tokenRow.openId ?? '');
+  // The Content Posting references meter "each user access_token", so a posting window is the token's
+  // own — keyed by its hash, never the token
+  const tokenHash = secretKey(bearer);
+  const windowId = `${endpoint}:${tokenHash}`;
+  const windowOf = (rows: readonly TwinResource[]) => {
+    const rateRow = rows.find((r) => r.type === BK_RATE && r.id === windowId) as Row | undefined;
+    const active = rateRow && typeof rateRow.windowStart === 'number' && nowSeconds(at) < rateRow.windowStart + RATE_WINDOW_SECONDS;
+    return { start: active ? Number(rateRow.windowStart) : nowSeconds(at), used: active && typeof rateRow.used === 'number' ? rateRow.used : 0 };
+  };
+  if (windowOf(resources).used >= RATE_LIMITS[endpoint]) return apiError('rate_limit_exceeded', at);
+  const response = await serve({
+    resources,
+    account,
+    openId,
+    scopes,
+    tokenHash,
+    clientKey: String(tokenRow.clientKey),
+    at,
+    ...(root !== undefined ? { root } : {}),
+    ...(req.origin !== undefined ? { origin: req.origin } : {}),
+    ...(req.originalHost !== undefined ? { originalHost: req.originalHost } : {}),
+    ...(req.readOnly ? { readOnly: true } : {}),
+  });
+  if (req.readOnly || response.status < 200 || response.status >= 300) return response;
+  await applyTwinWriteAtomic(
+    'tiktok',
+    (rows) => {
+      const w = windowOf(rows);
+      return {
+        kind: 'write',
+        value: undefined,
+        write: {
+          operation: 'rate_window.spend',
+          subjectType: BK_RATE,
+          subjectId: windowId,
+          fields: { windowStart: w.start, used: w.used + 1, rev: nextRevIn(rows, BK_RATE, windowId) },
+          occurredAt: at,
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    root,
+  );
+  return response;
+}
+
+/** `fields` is REQUIRED on all three Display API reads ("The set of user fields to request for",
+ *  Required: Yes). An unknown name is `invalid_params`, the code the vendor assigns to "one or
+ *  more request fields are invalid". */
+function readFields(query: URLSearchParams, allowed: readonly string[], at: string): { fields: string[] } | { fail: TikTokResponse } {
+  const raw = query.get('fields');
+  if (raw === null || raw.trim() === '') {
+    return { fail: apiError('invalid_params', at, 'The "fields" query parameter is required.') };
+  }
+  const fields = raw.split(',').map((f) => f.trim()).filter((f) => f !== '');
+  const unknown = fields.filter((f) => !allowed.includes(f));
+  if (unknown.length > 0) {
+    return { fail: apiError('invalid_params', at, `Invalid field(s): ${unknown.join(', ')}. Valid fields are: ${allowed.join(', ')}.`) };
+  }
+  return { fields };
+}
+
+/** The documented `scope_not_authorized`: "The user did not authorize the scope required for
+ *  completing this request." Returned as a 401, the status the vendor's own table gives it. */
+function requireScopes(needed: readonly string[], held: readonly string[], at: string): TikTokResponse | null {
+  const missing = needed.filter((s) => !held.includes(s));
+  if (missing.length === 0) return null;
+  return apiError('scope_not_authorized', at, `The user did not authorize the scope(s) required for completing this request: ${missing.join(', ')}.`);
+}
+
+function usersInfo(req: TikTokRequest, query: URLSearchParams): Promise<TikTokResponse> {
+  const at = instantOf(req.occurredAt);
+  return authorizedRead(req, 'user_info', (ctx) => {
+    const asked = readFields(query, USER_FIELDS, at);
+    if ('fail' in asked) return asked.fail;
+    const needed = [...new Set(asked.fields.map((f) => USER_FIELD_SCOPES[f]!))];
+    const refusal = requireScopes(needed, ctx.scopes, at);
+    if (refusal) return refusal;
+    return apiOk({ user: renderUser(ctx.account, ctx.openId, asked.fields) }, at, `user_info:${ctx.openId}:${asked.fields.join(',')}`);
+  });
+}
+
+function parseJsonBody(body: string | undefined): Record<string, unknown> | null {
+  if (body === undefined || body.trim() === '') return {};
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The videos this token's account owns, newest first (the list endpoint's own ordering — its
+ *  cursor is "UTC Unix timestamp in milliseconds… fetches videos posted before that time"). */
+function ownedVideos(resources: readonly TwinResource[], accountId: string, at: string): Row[] {
+  // a Direct Post is on the profile from the instant its processing ends (its create_time), not before
+  const now = nowSeconds(at);
+  // create_time is whole seconds, so two posts of one second tie: the one written later is newer
+  const order = new Map(resources.map((r, i) => [r, i] as const));
+  return (resources.filter((r) => r.type === 'video' && (r as Row).ownerUnionId === accountId && Number((r as Row).createTime ?? 0) <= now) as Row[])
+    .sort((a, b) => Number(b.createTime ?? 0) - Number(a.createTime ?? 0) || (order.get(b) ?? 0) - (order.get(a) ?? 0));
+}
+
+/** Default 10, maximum 20 — the list endpoint's own parameter table. */
+export const VIDEO_LIST_DEFAULT_COUNT = 10;
+export const VIDEO_LIST_MAX_COUNT = 20;
+/** "Up to 20 video IDs can be included per request" — the query endpoint's own limit. */
+export const VIDEO_QUERY_MAX_IDS = 20;
+
+function videoList(req: TikTokRequest, query: URLSearchParams): Promise<TikTokResponse> {
+  const at = instantOf(req.occurredAt);
+  return authorizedRead(req, 'video_list', (ctx) => {
+    const asked = readFields(query, VIDEO_FIELDS, at);
+    if ('fail' in asked) return asked.fail;
+    const refusal = requireScopes([VIDEO_SCOPE], ctx.scopes, at);
+    if (refusal) return refusal;
+    const body = parseJsonBody(req.body);
+    if (body === null) return apiError('invalid_params', at, 'The request body must be a JSON object.');
+    const rawCount = body['max_count'];
+    if (rawCount !== undefined && (typeof rawCount !== 'number' || !Number.isInteger(rawCount) || rawCount < 1 || rawCount > VIDEO_LIST_MAX_COUNT)) {
+      return apiError('invalid_params', at, `max_count must be an integer between 1 and ${VIDEO_LIST_MAX_COUNT}.`);
+    }
+    const rawCursor = body['cursor'];
+    if (rawCursor !== undefined && (typeof rawCursor !== 'number' || !Number.isInteger(rawCursor) || rawCursor < 0)) {
+      return apiError('invalid_params', at, 'cursor must be a UTC Unix timestamp in milliseconds.');
+    }
+    const maxCount = typeof rawCount === 'number' ? rawCount : VIDEO_LIST_DEFAULT_COUNT;
+    const all = ownedVideos(ctx.resources, ctx.account.id, at);
+    const before = typeof rawCursor === 'number' ? all.filter((v) => Number(v.createTime) * 1000 < rawCursor) : all;
+    const page = before.slice(0, maxCount);
+    const last = page[page.length - 1];
+    const cursor = last ? Number(last.createTime) * 1000 : (typeof rawCursor === 'number' ? rawCursor : 0);
+    return apiOk(
+      {
+        videos: page.map((v) => renderVideo(v, String(ctx.account.username ?? ''), asked.fields)),
+        cursor,
+        has_more: before.length > page.length,
+      },
+      at,
+      `video_list:${ctx.openId}:${cursor}`,
+    );
+  });
+}
+
+function videoQuery(req: TikTokRequest, query: URLSearchParams): Promise<TikTokResponse> {
+  const at = instantOf(req.occurredAt);
+  return authorizedRead(req, 'video_query', (ctx) => {
+    const asked = readFields(query, VIDEO_FIELDS, at);
+    if ('fail' in asked) return asked.fail;
+    const refusal = requireScopes([VIDEO_SCOPE], ctx.scopes, at);
+    if (refusal) return refusal;
+    const body = parseJsonBody(req.body);
+    if (body === null) return apiError('invalid_params', at, 'The request body must be a JSON object.');
+    const filters = body['filters'];
+    const ids = filters && typeof filters === 'object' && !Array.isArray(filters)
+      ? (filters as Record<string, unknown>)['video_ids']
+      : undefined;
+    if (!Array.isArray(ids) || ids.length === 0 || ids.some((id) => typeof id !== 'string')) {
+      return apiError('invalid_params', at, 'filters.video_ids must be a non-empty array of video id strings.');
+    }
+    if (ids.length > VIDEO_QUERY_MAX_IDS) {
+      return apiError('invalid_params', at, `Up to ${VIDEO_QUERY_MAX_IDS} video IDs can be included per request.`);
+    }
+    // A video that is not this user's is simply ABSENT from the answer — the endpoint reads "the
+    // videos of the user whose token this is", so a foreign id must not become a 404 that leaks
+    // whether it exists (`tiktok.video.query_foreign_id`, todo, pins the live behaviour).
+    const owned = new Map(ownedVideos(ctx.resources, ctx.account.id, at).map((v) => [v.id, v]));
+    const videos = (ids as string[]).map((id) => owned.get(id)).filter((v): v is Row => v !== undefined);
+    return apiOk(
+      { videos: videos.map((v) => renderVideo(v, String(ctx.account.username ?? ''), asked.fields)) },
+      at,
+      `video_query:${ctx.openId}:${(ids as string[]).join(',')}`,
+    );
+  });
+}
+
+/** Every VENDOR endpoint this twin claims to serve. The conformance check drives one real request
+ *  per entry and grades the OUTCOME, so an entry here is a promise with teeth. Twin-only routes
+ *  (`/_twin/*`) are deliberately absent — they are scaffolding, not vendor surface. */
+export function tiktokTwinSnapshot(): { implementedEndpoints: string[]; resourceTypes: readonly string[]; grantTypes: string[] } {
+  return {
+    implementedEndpoints: [
+      'GET /v2/auth/authorize',
+      'POST /v2/oauth/token',
+      'POST /v2/oauth/revoke',
+      'GET /v2/user/info',
+      'POST /v2/video/list',
+      'POST /v2/video/query',
+      'POST /v2/post/publish/creator_info/query',
+      'POST /v2/post/publish/video/init',
+      'POST /v2/post/publish/inbox/video/init',
+      'POST /v2/post/publish/status/fetch',
+      'PUT /video',
+    ],
+    resourceTypes: STORE_RESOURCE_TYPES,
+    grantTypes: ['authorization_code', 'refresh_token', 'client_credentials'],
+  };
+}
+
+// ── twin-only control routes (NOT vendor surface — see the manifest) ────────────────────────────
+
+async function twinControl(req: TikTokRequest, path: string, form: URLSearchParams): Promise<TikTokResponse | null> {
+  const root = req.root;
+  const at = instantOf(req.occurredAt);
+  const opts = { root, occurredAt: at };
+  const json = () => {
+    try {
+      return JSON.parse(req.body ?? '{}') as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  };
+  if (req.method === 'GET' && path === '/_twin/consent') {
+    const { query } = splitPath(req.path);
+    return renderConsent(req, query.get('auth_request') ?? '');
+  }
+  if (req.method === 'POST' && path === '/_twin/consent') return consentDecision(req, form);
+
+  if (req.method === 'POST' && path === '/_twin/clients') {
+    const b = json();
+    if (!b) return malformedRequest(at, 'A JSON body is required.');
+    // `:` is the grant-id separator (`clientKey:sub`), so a colon in a caller-supplied key could
+    // forge a composite collision (app `A:B` + user `C` vs app `A` + user `B:C`). Real TikTok
+    // client keys are colon-free; the scaffolding refuses the character outright.
+    if (typeof b['client_key'] === 'string' && b['client_key'].includes(':')) {
+      return malformedRequest(at, 'client_key must not contain ":".');
+    }
+    const clientKey = typeof b['client_key'] === 'string' && b['client_key'] ? (b['client_key'] as string) : mintClientKey(root, at);
+    // No secret given: one is drawn from entropy, as the developer portal issues one, and answered ONCE
+    // here — the twin keeps only its hash, so it can never be shown again.
+    const drawn = typeof b['client_secret'] === 'string' && b['client_secret'] !== '' ? null
+      : Array.from(crypto.getRandomValues(new Uint8Array(24)), (x) => x.toString(16).padStart(2, '0')).join('');
+    const clientSecret = drawn ?? (b['client_secret'] as string);
+    const row = await writeAtomic(
+      'oauth_client',
+      clientKey,
+      'oauth_client.create',
+      () => ({
+        name: typeof b['name'] === 'string' ? b['name'] : 'Twin App',
+        // the app's secret is kept as its SHA-256: the token endpoint hashes what it is shown and compares
+        secretSha256: secretKey(clientSecret),
+        redirectUris: Array.isArray(b['redirect_uris']) ? b['redirect_uris'] : [],
+      }),
+      opts,
+    );
+    return { status: 200, body: { ...row, ...(drawn !== null ? { client_secret: drawn } : {}) } };
+  }
+
+  if (req.method === 'POST' && path === '/_twin/accounts') {
+    const b = json();
+    if (!b || typeof b['union_id'] !== 'string' || !b['union_id']) return malformedRequest(at, 'union_id is required');
+    if (b['union_id'].includes(':')) return malformedRequest(at, 'union_id must not contain ":".');
+    const id = b['union_id'] as string;
+    const row = await writeAtomic(
+      'account',
+      id,
+      'account.create',
+      () => ({
+        username: typeof b['username'] === 'string' ? b['username'] : `user_${id}`,
+        displayName: typeof b['display_name'] === 'string' ? b['display_name'] : 'Twin Persona',
+        ...(typeof b['avatar_url'] === 'string' ? { avatarUrl: b['avatar_url'] } : {}),
+        ...(typeof b['avatar_url_100'] === 'string' ? { avatarUrl100: b['avatar_url_100'] } : {}),
+        ...(typeof b['avatar_large_url'] === 'string' ? { avatarLargeUrl: b['avatar_large_url'] } : {}),
+        ...(typeof b['bio_description'] === 'string' ? { bioDescription: b['bio_description'] } : {}),
+        ...(typeof b['profile_deep_link'] === 'string' ? { profileDeepLink: b['profile_deep_link'] } : {}),
+        ...(typeof b['is_verified'] === 'boolean' ? { isVerified: b['is_verified'] } : {}),
+        ...(typeof b['follower_count'] === 'number' ? { followerCount: b['follower_count'] } : {}),
+        ...(typeof b['following_count'] === 'number' ? { followingCount: b['following_count'] } : {}),
+        ...(typeof b['likes_count'] === 'number' ? { likesCount: b['likes_count'] } : {}),
+        ...(typeof b['video_count'] === 'number' ? { videoCount: b['video_count'] } : {}),
+        // what creator_info answers for this creator (tiktok-posting.ts creatorOptions)
+        ...(typeof b['is_private'] === 'boolean' ? { isPrivate: b['is_private'] } : {}),
+        ...(Array.isArray(b['privacy_level_options']) ? { privacyLevelOptions: b['privacy_level_options'] } : {}),
+        ...(typeof b['comment_disabled'] === 'boolean' ? { commentDisabled: b['comment_disabled'] } : {}),
+        ...(typeof b['duet_disabled'] === 'boolean' ? { duetDisabled: b['duet_disabled'] } : {}),
+        ...(typeof b['stitch_disabled'] === 'boolean' ? { stitchDisabled: b['stitch_disabled'] } : {}),
+        ...(typeof b['max_video_post_duration_sec'] === 'number' ? { maxVideoPostDurationSec: b['max_video_post_duration_sec'] } : {}),
+      }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+
+  if (req.method === 'POST' && path === '/_twin/videos') {
+    // A video WITHOUT bytes, for a Display API read to find. A video with its media is posted
+    // through the vendor's own Content Posting API (tiktok-posting.ts); this door seeds the
+    // metadata-only rows a Display API fixture needs (ADDING_A_TWIN.md §6).
+    const b = json();
+    if (!b || typeof b['id'] !== 'string' || !b['id']) return malformedRequest(at, 'id is required');
+    if (typeof b['owner_union_id'] !== 'string' || !b['owner_union_id']) return malformedRequest(at, 'owner_union_id is required');
+    if (!readOne(root, 'account', b['owner_union_id'] as string)) return malformedRequest(at, 'Unknown owner_union_id.');
+    const id = b['id'] as string;
+    const row = await writeAtomic(
+      'video',
+      id,
+      'video.create',
+      () => ({
+        ownerUnionId: b['owner_union_id'],
+        title: typeof b['title'] === 'string' ? b['title'] : '',
+        videoDescription: typeof b['video_description'] === 'string' ? b['video_description'] : '',
+        createTime: typeof b['create_time'] === 'number' ? b['create_time'] : 0,
+        duration: typeof b['duration'] === 'number' ? b['duration'] : 0,
+        height: typeof b['height'] === 'number' ? b['height'] : 0,
+        width: typeof b['width'] === 'number' ? b['width'] : 0,
+        likeCount: typeof b['like_count'] === 'number' ? b['like_count'] : 0,
+        commentCount: typeof b['comment_count'] === 'number' ? b['comment_count'] : 0,
+        shareCount: typeof b['share_count'] === 'number' ? b['share_count'] : 0,
+        viewCount: typeof b['view_count'] === 'number' ? b['view_count'] : 0,
+        ...(typeof b['is_aigc'] === 'boolean' ? { isAigc: b['is_aigc'] } : {}),
+      }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+
+  if (req.method === 'POST' && path === '/_twin/tokens') {
+    // A user access token for an account, as a World issues one in place of running the consent leg
+    // (the X/YouTube `/_twin/tokens` precedent): the grant is widened to the named scopes and a token
+    // carrying them is recorded. The mirror signs in with it, and a Content Posting client posts with it.
+    const b = json();
+    if (!b || typeof b['union_id'] !== 'string' || !b['union_id']) return malformedRequest(at, 'union_id is required');
+    const account = readOne(root, 'account', b['union_id'] as string);
+    if (!account) return malformedRequest(at, 'Unknown account.');
+    const clientKey = typeof b['client_key'] === 'string' && b['client_key'] ? (b['client_key'] as string) : DEFAULT_CLIENT_KEY;
+    if (!readOne(root, 'oauth_client', clientKey)) return malformedRequest(at, 'Unknown client_key.');
+    const rawScopes = Array.isArray(b['scopes']) ? (b['scopes'] as unknown[]).filter((s): s is string => typeof s === 'string') : parseScopeParam(typeof b['scope'] === 'string' ? b['scope'] : '');
+    const scopes = rawScopes.filter((s) => KNOWN_SCOPES.includes(s));
+    if (scopes.length === 0) return malformedRequest(at, `scopes must name at least one of: ${KNOWN_SCOPES.join(', ')}`);
+    if (typeof b['access_token'] === 'string' && !/^act\.[A-Za-z0-9._~-]{8,}$/.test(b['access_token'] as string)) return malformedRequest(at, 'access_token must look like act.<opaque>.');
+    const token = typeof b['access_token'] === 'string' ? (b['access_token'] as string) : mintAccessToken(root, Date.parse(at), `twin:${clientKey}:${account.id}`);
+    const grantId = `${clientKey}:${account.id}`;
+    const openId = openIdFor(clientKey, account.id);
+    const scope = formatScopeParam(scopes);
+    await applyTwinWriteAtomic(
+      'tiktok',
+      (resources) => {
+        const grant = resources.find((r) => r.type === 'grant' && r.id === grantId) as Row | undefined;
+        const held: string[] = Array.isArray(grant?.scopes) ? grant.scopes : [];
+        const grantFields = { clientKey, sub: account.id, openId, scopes: [...new Set([...held, ...scopes])], rev: nextRevIn(resources, 'grant', grantId) };
+        const tokenKey = secretKey(token);
+        return {
+          kind: 'write',
+          value: undefined,
+          write: {
+            operation: 'access_token.issue',
+            subjectType: BK_ACCESS,
+            subjectId: tokenKey,
+            fields: { clientKey, sub: account.id, openId, scope, expiresAt: nowSeconds(at) + ACCESS_TOKEN_TTL_SECONDS, revoked: false, rev: nextRevIn(resources, BK_ACCESS, tokenKey) },
+            projection: grant ? { updates: [{ type: 'grant', id: grantId, fields: grantFields }] } : { creates: [{ type: 'grant', id: grantId, fields: grantFields }] },
+            occurredAt: at,
+            actor: { kind: 'agent' as const },
+          },
+        };
+      },
+      root,
+    );
+    return { status: 200, body: { access_token: token, open_id: openId, scope, expires_in: ACCESS_TOKEN_TTL_SECONDS, token_type: 'Bearer' } };
+  }
+
+  if (req.method === 'POST' && path === '/_twin/session') {
+    const b = json();
+    if (!b || typeof b['union_id'] !== 'string' || !b['union_id']) return malformedRequest(at, 'union_id is required');
+    if (!readOne(root, 'account', b['union_id'] as string)) return malformedRequest(at, 'Unknown account.');
+    const row = await writeAtomic('session', 'current', 'session.switch', () => ({ accountId: b['union_id'] }), opts);
+    return { status: 200, body: row };
+  }
+
+  if (req.method === 'POST' && path === '/_twin/rate_limit') {
+    // Arm a deterministic rate state (the figma armed-429 precedent): set the used count for a window
+    // so a verify can prove the 429 without 600 real reads. A Display API window is the (endpoint,
+    // open_id) pair; a Content Posting window is the token's own, named by `access_token` and kept by
+    // its hash.
+    const b = json();
+    if (!b || typeof b['endpoint'] !== 'string' || typeof b['used'] !== 'number') {
+      return malformedRequest(at, 'endpoint and used are required');
+    }
+    if (!(METERED_ENDPOINTS as readonly string[]).includes(b['endpoint'] as string)) {
+      return malformedRequest(at, `endpoint must be one of ${METERED_ENDPOINTS.join(', ')}`);
+    }
+    const display = ['user_info', 'video_list', 'video_query'].includes(b['endpoint'] as string);
+    const key = display ? b['open_id'] : b['access_token'];
+    if (typeof key !== 'string' || key === '') return malformedRequest(at, display ? 'open_id is required for a Display API window' : 'access_token is required for a Content Posting window');
+    const windowId = `${b['endpoint']}:${display ? key : secretKey(key)}`;
+    const row = await writeAtomic(
+      BK_RATE,
+      windowId,
+      'rate_window.arm',
+      () => ({ windowStart: nowSeconds(at), used: b['used'] }),
+      opts,
+    );
+    return { status: 200, body: row };
+  }
+  return null;
+}
+
+// ── public entry + router ───────────────────────────────────────────────────────────────────────
+
+export async function handleTikTokTwinRequest(req: TikTokRequest): Promise<TikTokResponse> {
+  try {
+    return await routeTikTokTwinRequest(req);
+  } catch (e) {
+    // MALFORMED-REQUEST GUARD (route boundary), the gemini/googleoauth precedent: a residual
+    // TypeError (a wrong-typed field the router walked) or URIError (bad percent-encoding) becomes
+    // the vendor's own 400 envelope instead of escaping as a non-vendor 500 — in the error FAMILY
+    // of the endpoint that failed: the Display API speaks the nested error object, the OAuth
+    // endpoints and the authorize page speak the flat one. Every OTHER error type still propagates
+    // loudly rather than being masked as a caller mistake.
+    const at = typeof req.occurredAt === 'string' ? req.occurredAt : new Date(0).toISOString();
+    const { path } = splitPath(typeof req.path === 'string' ? req.path : '/');
+    const isApi = path === '/v2/user/info' || path === '/v2/video/list' || path === '/v2/video/query' || path.startsWith('/v2/post/publish/');
+    if (e instanceof TypeError || e instanceof URIError) {
+      return isApi
+        ? apiError('invalid_params', at, 'The request contains an invalid argument.')
+        : oauthError('invalid_request', 'The request parameters are malformed.', at);
+    }
+    if (isApi) return internalError(at);
+    if (path === AUTHORIZE_PATH || path === '/_twin/consent') {
+      return errorPage({ status: 500, code: 'server_error', detail: 'The authorization server could not complete the request.' });
+    }
+    return oauthErrorCode('server_error', at, 500);
+  }
+}
+
+async function routeTikTokTwinRequest(req: TikTokRequest): Promise<TikTokResponse> {
+  const method = req.method.toUpperCase();
+  const { path, query } = splitPath(req.path);
+  const at = instantOf(req.occurredAt);
+  const form = new URLSearchParams(method === 'GET' || method === 'HEAD' ? '' : (req.body ?? ''));
+
+  // D3: a read-only twin cannot mint credentials or settle consent. The Display API reads stay
+  // served (they are reads, even though two of them are POSTs), with rate accounting suspended.
+  // The media route is a READ (a player fetching a post's bytes) that lives under the twin prefix; the
+  // Content Posting inits and the chunk PUT refuse on their own, in their own envelopes.
+  const writes = (path.startsWith('/_twin/') && !path.startsWith(MEDIA_PREFIX)) || path === '/v2/oauth/token' || path === '/v2/oauth/revoke';
+  if (req.readOnly && writes) {
+    return oauthErrorCode('temporarily_unavailable', at, 405);
+  }
+
+  // Seeding is idempotent and cheap; doing it at the router boundary means every entry point sees
+  // a world with an app, personas, videos and a signed-in session — what a browser at tiktok.com
+  // has.
+  if (!req.readOnly) await ensureSeed({ root: req.root, occurredAt: at, ...((req.callbackOrigin ?? req.origin) ? { origin: req.callbackOrigin ?? req.origin } : {}) });
+
+  if (path.startsWith(MEDIA_PREFIX)) {
+    return serveVideo({ method, path, query, at, resources: readAll(req.root), ...(req.headers ? { headers: req.headers } : {}), ...(req.root !== undefined ? { root: req.root } : {}) });
+  }
+
+  const control = await twinControl(req, path, form);
+  if (control) return control;
+
+  if (method === 'GET' && path === AUTHORIZE_PATH) return authorize(req, query);
+  if (method === 'POST' && path === '/v2/oauth/token') return token(req);
+  if (method === 'POST' && path === '/v2/oauth/revoke') return revoke(req);
+  if (method === 'GET' && path === '/v2/user/info') return usersInfo(req, query);
+  if (method === 'POST' && path === '/v2/video/list') return videoList(req, query);
+  if (method === 'POST' && path === '/v2/video/query') return videoQuery(req, query);
+
+  // the Content Posting API (tiktok-posting.ts)
+  if (method === 'POST' && path === '/v2/post/publish/creator_info/query') return authorizedPosting(req, 'creator_info', creatorInfo);
+  if (method === 'POST' && path === '/v2/post/publish/video/init') return authorizedPosting(req, 'video_init', (ctx) => initUpload(ctx, 'direct', req.body));
+  if (method === 'POST' && path === '/v2/post/publish/inbox/video/init') return authorizedPosting(req, 'inbox_init', (ctx) => initUpload(ctx, 'inbox', req.body));
+  if (method === 'POST' && path === '/v2/post/publish/status/fetch') return authorizedPosting(req, 'post_status', (ctx) => fetchStatus(ctx, req.body));
+  if (method === 'PUT' && path === UPLOAD_PATH) {
+    return uploadChunk({ method, query, at, ...(req.headers ? { headers: req.headers } : {}), ...(req.bytes ? { bytes: req.bytes } : {}), ...(req.root !== undefined ? { root: req.root } : {}), ...(req.readOnly ? { readOnly: true } : {}) });
+  }
+
+  // An operation the twin does not model fails like the vendor — never a fake success.
+  return unknownRoute(method, path, at);
+}