@volter/twin-tiktok 0.1.0

package/src/tiktok-consent-ui.ts

@@ -0,0 +1,146 @@
+// TikTok twin — the SERVER HALF of the authorization page.
+//
+// Named `-consent-ui` rather than `-mirror-ui` on purpose (the googleoauth/xidentity class
+// doctrine): a dashboard mirror is a SECOND renderer this repo writes over a vendor's data,
+// whereas this is the vendor's OWN page, on the vendor's OWN path, in the middle of the vendor's
+// OWN protocol. The mirror DISCIPLINE still applies in full — one renderer, data-coupled to the
+// projection, driven by a real browser journey.
+//
+// The pieces:
+//   • `tiktokConsentState` — THE STATE BUILDER. Everything on screen is derived here, from the
+//     kernel projection, and nowhere else. It is the seam `scripts/mutation-test.ts` sabotages in
+//     the mirror phase (TWIN-20/B9): with it dead the screen has no app name, no account and no
+//     scopes, so every UI capability must go red while the write/handler path stays real.
+//   • `consentPageHtml` / `errorPageHtml` — server-render the REAL exported React components with
+//     `renderToStaticMarkup`. There is no template string of vendor markup anywhere.
+//   • `CONSENT_CSS` — the stylesheet, INLINE. This pack ships no browser bundle (the whole screen
+//     is a plain form; see client/tiktok-consent.tsx), so there is no build on the serve path
+//     (R12b) and no generated asset to drift — the page is one self-contained document.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import {
+  ConsentPage,
+  ErrorPage,
+  type ConsentAccount,
+  type ConsentScopeRow,
+  type ConsentView,
+  type ErrorPageProps,
+} from '../client/tiktok-consent.tsx';
+import { describeScopes, parseScopeParam, sortScopesForConsent } from './tiktok-scopes.ts';
+import { readOne, type Row } from './tiktok-store.ts';
+
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from '../client/tiktok-consent.tsx';
+
+function toConsentAccount(row: Row): ConsentAccount {
+  return {
+    unionId: row.id,
+    username: String(row.username ?? ''),
+    displayName: String(row.displayName ?? ''),
+  };
+}
+
+/**
+ * THE STATE BUILDER — the authorization page's entire view model, folded out of the kernel
+ * projection. Returns `null` when the authorize request is unknown or already settled, or when the
+ * app or the signed-in account no longer exists (the caller renders the error page); it never
+ * invents an app name, an account or a scope row.
+ */
+export function tiktokConsentState(opts: {
+  root?: string;
+  requestId: string;
+  origin: string;
+}): ConsentView | null {
+  const authRequest = readOne(opts.root, 'auth_request', opts.requestId);
+  if (!authRequest || authRequest.settled === true) return null;
+  const client = readOne(opts.root, 'oauth_client', String(authRequest.clientKey));
+  if (!client) return null;
+  const account = readOne(opts.root, 'account', String(authRequest.accountId ?? ''));
+  if (!account) return null;
+
+  const requested = sortScopesForConsent(parseScopeParam(String(authRequest.scope ?? '')));
+  const scopes: ConsentScopeRow[] = describeScopes(requested).map((s) => ({
+    scope: s.scope,
+    label: s.label,
+    product: s.product,
+    known: s.known,
+  }));
+
+  let redirectHost = '';
+  try {
+    redirectHost = new URL(String(authRequest.redirectUri)).host;
+  } catch {
+    redirectHost = String(authRequest.redirectUri);
+  }
+
+  return {
+    requestId: opts.requestId,
+    origin: opts.origin,
+    app: { clientKey: client.id, name: String(client.name ?? '') },
+    account: toConsentAccount(account),
+    scopes,
+    redirectHost,
+  };
+}
+
+/** The authorization page's stylesheet, served inline. Static text: no clock, no state, no build. */
+export const CONSENT_CSS = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+  background: #f1f1f2; color: #161823; padding: 24px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+.card {
+  background: #fff; width: 100%; max-width: 440px; border-radius: 12px; padding: 28px 28px 22px;
+  box-shadow: 0 2px 12px rgba(0,0,0,.10); border: 1px solid rgba(22,24,35,.10);
+}
+.tt-header { display: flex; align-items: center; gap: 8px; margin-bottom: 20px; }
+.tt-mark { font-size: 26px; line-height: 1; color: #fe2c55; }
+.tt-wordmark { font-size: 18px; font-weight: 700; letter-spacing: -0.4px; }
+.signed-in { display: flex; align-items: center; gap: 8px; margin-bottom: 14px; }
+.account-text { display: flex; align-items: baseline; gap: 8px; font-size: 14px; }
+.account-name { font-weight: 600; }
+.account-username { color: rgba(22,24,35,.60); }
+.title { font-size: 20px; line-height: 1.35; font-weight: 600; margin: 0 0 18px; }
+.app-name { font-weight: 700; }
+.scope-lead { font-size: 14px; color: rgba(22,24,35,.72); margin: 0 0 10px; }
+.scope-list { list-style: none; margin: 0 0 22px; padding: 0; display: flex; flex-direction: column; gap: 12px; }
+.scope-row { display: flex; flex-direction: column; gap: 4px; }
+.scope-label { display: flex; align-items: flex-start; gap: 10px; font-size: 14px; line-height: 1.45; cursor: pointer; }
+.scope-check { margin-top: 3px; accent-color: #fe2c55; width: 16px; height: 16px; flex: none; }
+.scope-tag { align-self: flex-start; font-size: 11px; border-radius: 999px; padding: 2px 8px; margin-left: 26px; }
+.scope-tag-unknown { background: #fff1f3; color: #b3082f; border: 1px solid #ffd3db; }
+.actions { display: flex; gap: 10px; justify-content: flex-end; }
+.btn { font: inherit; font-weight: 600; border-radius: 6px; padding: 10px 20px; cursor: pointer; border: 1px solid transparent; }
+.btn-primary { background: #fe2c55; color: #fff; }
+.btn-secondary { background: #fff; color: #161823; border-color: rgba(22,24,35,.20); }
+.legal { font-size: 12px; line-height: 1.5; color: rgba(22,24,35,.55); margin: 18px 0 0; }
+.redirect-host { color: rgba(22,24,35,.80); }
+.card-error .title { margin-bottom: 12px; }
+.error-detail { font-size: 14px; line-height: 1.5; margin: 0 0 12px; }
+.error-code { font-size: 13px; font-weight: 600; color: #b3082f; margin: 0 0 6px; }
+.error-request { font-size: 12px; color: rgba(22,24,35,.55); word-break: break-all; margin: 0; }
+`.trim();
+
+function page(title: string, bodyMarkup: string): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title><style>${CONSENT_CSS}</style></head>
+<body><div id="root">${bodyMarkup}</div></body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Render the authorization page from a view model. */
+export function consentPageHtml(view: ConsentView): string {
+  const markup = renderToStaticMarkup(createElement(ConsentPage, { view }));
+  return page(`Authorize ${view.app.name} | TikTok`, markup);
+}
+
+/** Render the authorize-endpoint error page (an un-redirectable failure). */
+export function errorPageHtml(props: ErrorPageProps): string {
+  return page(`Error ${props.status}: ${props.code} | TikTok`, renderToStaticMarkup(createElement(ErrorPage, props)));
+}

package/src/tiktok-errors.ts

@@ -0,0 +1,197 @@
+// TikTok's TWO error envelopes, kept distinct because they really are two different contracts and
+// an integration branches on them (Dub's own code does: the OAuth leg reads `response.ok` plus
+// `access_token`, the Display leg parses `data.user` through a Zod schema).
+//
+//   1. THE OAUTH FAMILY — `/v2/oauth/token/` and `/v2/oauth/revoke/`. A FLAT body:
+//        { "error": "invalid_request",
+//          "error_description": "Redirect_uri is not matched with the uri when requesting code.",
+//          "log_id": "202206221854370101130062072500FFA2" }
+//      Verbatim from the User Access Token Management guide
+//      (developers.tiktok.com/doc/oauth-user-access-token-management, fetched 2026-09-13). The
+//      `error` values are the ten the OAuth error-handling reference publishes
+//      (developers.tiktok.com/docs/en/oauth-error-handling) — access_denied, invalid_client,
+//      invalid_grant, invalid_request, invalid_scope, unauthorized_client, unsupported_grant_type,
+//      unsupported_response_type, server_error, temporarily_unavailable — each with the
+//      description that page gives it.
+//
+//      EVIDENCE BOUNDARY — THE HTTP STATUS. That reference publishes the codes and descriptions
+//      and NO status column, and no fetched artefact shows the status line of a TikTok OAuth
+//      failure. The twin answers RFC 6749 §5.2's statuses (400, or 401 for invalid_client),
+//      which is the reading every OAuth client library assumes; `tiktok.token.error_http_status`
+//      (todo) pins the live one. Marked here rather than dressed up as a vendor fact.
+//
+//   2. THE API FAMILY — `/v2/user/info/`, `/v2/video/list/`, `/v2/video/query/`. A NESTED error
+//      object that is present on SUCCESS TOO:
+//        { "data": { ... }, "error": { "code": "ok", "message": "", "log_id": "…" } }
+//      Verbatim from the Get User Info reference. The codes are the seven the v2 error-handling
+//      reference publishes WITH their HTTP statuses: access_token_invalid (401), internal_error
+//      (500), invalid_file_upload (400), invalid_params (400), rate_limit_exceeded (429),
+//      scope_not_authorized (401), scope_permission_missed (400).
+//
+// `log_id` is deterministic here (see tiktok-ids.ts) because it is served content: runtime
+// contract R9 forbids a clock or entropy in a served byte, and a twin whose every response
+// carried a fresh random id would fail the two-fresh-roots replay on every single read.
+import { logId } from './tiktok-ids.ts';
+
+export type TikTokResponse = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+/** TikTok's own curl examples set `Cache-Control: no-cache` on the request; the twin refuses to
+ *  let a credential-bearing reply be cached on the way back. */
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+const JSON_CT = { 'content-type': 'application/json; charset=utf-8' };
+
+// ── family 1: the OAuth endpoints (flat body) ───────────────────────────────────────────────────
+
+/** The ten `error` values the OAuth error-handling reference publishes, with its descriptions
+ *  verbatim. Exported so a verify can assert against the vendor's list rather than the twin's. */
+export const OAUTH_ERRORS: Record<string, string> = {
+  access_denied: 'The resource owner or authorization server denied the request.',
+  invalid_client: 'Client authentication failed (for example, unknown client, no client authentication included, or unsupported authentication method).',
+  invalid_grant: 'The provided authorization grant (for example, authorization code or resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.',
+  invalid_request: 'The request misses a required parameter or is otherwise malformed.',
+  invalid_scope: 'The requested scope is invalid, unknown, or malformed.',
+  unauthorized_client: 'The client is not authorized to request an authorization code using this method.',
+  unsupported_grant_type: 'The authorization grant type is not supported by the authorization server.',
+  unsupported_response_type: 'The authorization server does not support obtaining an authorization code using this method.',
+  server_error: 'Other internal server errors.',
+  temporarily_unavailable: 'Service is temporarily unavailable.',
+};
+
+/**
+ * An OAuth-endpoint refusal. `status` defaults to RFC 6749 §5.2's 400 — see the EVIDENCE BOUNDARY
+ * in this file's header; the live status is unpinned.
+ */
+export function oauthError(error: string, description: string, occurredAt: string, status = 400): TikTokResponse {
+  return {
+    status,
+    body: { error, error_description: description, log_id: logId(occurredAt, `oauth:${error}:${description}`) },
+    headers: { ...NOSTORE, ...JSON_CT },
+  };
+}
+
+/** A refusal whose description is the vendor's OWN published one for that code. */
+export function oauthErrorCode(error: keyof typeof OAUTH_ERRORS & string, occurredAt: string, status = 400): TikTokResponse {
+  return oauthError(error, OAUTH_ERRORS[error] ?? 'The request misses a required parameter or is otherwise malformed.', occurredAt, status);
+}
+
+/** The vendor's own wording for a malformed request — the literal string its refresh/revoke
+ *  examples show ("The request parameters are malformed."). */
+export function malformedRequest(occurredAt: string, detail?: string): TikTokResponse {
+  return oauthError('invalid_request', detail ?? 'The request parameters are malformed.', occurredAt);
+}
+
+/**
+ * The ONE answer an unusable authorization code or refresh token gets. Unknown, already redeemed,
+ * expired, minted for another client, wrong redirect_uri pairing or failed PKCE are deliberately
+ * indistinguishable — telling them apart would leak which codes exist — and `invalid_grant` is the
+ * code the vendor's own reference assigns to exactly that family ("The provided authorization
+ * grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in
+ * the authorization request, or was issued to another client").
+ */
+export function invalidGrant(occurredAt: string): TikTokResponse {
+  return oauthErrorCode('invalid_grant', occurredAt);
+}
+
+/** Client authentication failed at the token/revoke endpoint (RFC 6749 §5.2: 401). */
+export function invalidClient(occurredAt: string): TikTokResponse {
+  return oauthErrorCode('invalid_client', occurredAt, 401);
+}
+
+// ── family 2: the v2 API endpoints (nested error object, present on success too) ─────────────────
+
+/**
+ * The seven codes the v2 error-handling reference publishes, with their documented HTTP status.
+ * `ok` is the success value the same envelope carries.
+ *
+ * EVIDENCE BOUNDARY ON THE MESSAGES, so a reader can tell a quotation from twin prose. VERBATIM
+ * from the vendor's table: `access_token_invalid`, `invalid_file_upload`, `rate_limit_exceeded`
+ * and `scope_not_authorized`. TWIN PROSE, because the reference describes those rows rather than
+ * quoting a message ("generic TikTok internal error; refer to message for details", "one or more
+ * request fields are invalid", "access token lacks required scopes"): `internal_error`,
+ * `invalid_params` and `scope_permission_missed`. The CODES and the STATUSES are the vendor's for
+ * all seven, which is what `tiktok.errors.api_codes_and_statuses_match_vendor_table` asserts.
+ */
+export const API_ERRORS: Record<string, { status: number; message: string }> = {
+  access_token_invalid: { status: 401, message: 'The access token is invalid or not found in the request. Please refresh the token and retry.' },
+  internal_error: { status: 500, message: 'Server internal error. Please retry later.' },
+  invalid_file_upload: { status: 400, message: 'The uploaded file does not meet API specifications. Please correct the file and try again.' },
+  invalid_params: { status: 400, message: 'One or more request fields are invalid.' },
+  rate_limit_exceeded: { status: 429, message: 'The API rate limit was exceeded. Please try again later.' },
+  scope_not_authorized: { status: 401, message: 'The user did not authorize the scope required for completing this request. Please ask the user to authorize and then retry.' },
+  scope_permission_missed: { status: 400, message: 'The access token does not carry the scopes required by this request.' },
+};
+
+/** The success envelope: the `data` the endpoint computed, plus `error: {code:"ok", message:"", log_id}`. */
+export function apiOk(data: unknown, occurredAt: string, seed: string): TikTokResponse {
+  return {
+    status: 200,
+    body: { data, error: { code: 'ok', message: '', log_id: logId(occurredAt, `api:ok:${seed}`) } },
+    headers: { ...NOSTORE, ...JSON_CT },
+  };
+}
+
+/**
+ * An API-endpoint refusal. The status comes from the vendor's own published table, so a caller
+ * that branches on the status and a caller that branches on `error.code` agree by construction.
+ * `message` may be overridden to carry the specific detail the vendor's message field carries
+ * ("consult the error message for specifics" is what its own reference says of `invalid_params`).
+ */
+export function apiError(code: keyof typeof API_ERRORS & string, occurredAt: string, message?: string): TikTokResponse {
+  const spec = API_ERRORS[code]!;
+  return {
+    status: spec.status,
+    body: { error: { code, message: message ?? spec.message, log_id: logId(occurredAt, `api:${code}:${message ?? ''}`) } },
+    headers: { ...NOSTORE, ...JSON_CT },
+  };
+}
+
+/**
+ * The Content Posting API's OWN codes, with the HTTP status each reference page gives them
+ * (developers.tiktok.com content-posting-api-reference-direct-post, -upload-video,
+ * -query-creator-info and -get-video-status, fetched 2026-09-27). Note the SINGULAR `invalid_param`:
+ * the posting references spell it that way while the v2 error table spells `invalid_params`, and a
+ * client that branches on the code must meet the spelling of the endpoint it called. Messages are
+ * the reference's descriptions, lightly completed into sentences (twin prose); codes and statuses are
+ * the vendor's.
+ */
+export const POSTING_ERRORS: Record<string, { status: number; message: string }> = {
+  invalid_param: { status: 400, message: 'The request contains an invalid parameter. Check the error message for details.' },
+  spam_risk_too_many_posts: { status: 403, message: 'The daily post cap for this user has been reached.' },
+  spam_risk_user_banned_from_posting: { status: 403, message: 'This user is banned from making new posts.' },
+  reached_active_user_cap: { status: 403, message: 'The daily quota for active publishing users from this client has been reached.' },
+  unaudited_client_can_only_post_to_private_accounts: { status: 403, message: 'Unaudited clients can only post to a private account.' },
+  url_ownership_unverified: { status: 403, message: 'To use PULL_FROM_URL, the developer must verify ownership of the URL prefix or domain.' },
+  privacy_level_option_mismatch: { status: 403, message: 'The privacy_level is not one of the privacy_level_options this creator has.' },
+  spam_risk_too_many_pending_share: { status: 403, message: 'This user has too many pending shares in the last 24 hours.' },
+  invalid_publish_id: { status: 400, message: 'The publish_id does not exist.' },
+  token_not_authorized_for_specified_publish_id: { status: 400, message: 'The access token is not authorized to read the status of this publish_id.' },
+};
+
+/** A Content Posting refusal, in the same nested envelope as the rest of the v2 API. */
+export function postingError(code: keyof typeof POSTING_ERRORS & string, occurredAt: string, message?: string): TikTokResponse {
+  const spec = POSTING_ERRORS[code]!;
+  return {
+    status: spec.status,
+    body: { error: { code, message: message ?? spec.message, log_id: logId(occurredAt, `posting:${code}:${message ?? ''}`) } },
+    headers: { ...NOSTORE, ...JSON_CT },
+  };
+}
+
+/**
+ * An UNMODELLED path on a twinned TikTok host fails like the vendor rather than faking a success.
+ * TikTok publishes no 404 body for an unknown v2 route, so the twin answers the API family's own
+ * `invalid_params` shape with a message that names the route — an honest refusal in the envelope
+ * the surrounding endpoints speak. `tiktok.errors.unknown_route_pin` (todo) pins the live answer.
+ */
+export function unknownRoute(method: string, path: string, occurredAt: string): TikTokResponse {
+  return apiError('invalid_params', occurredAt, `${method} ${path} is not a TikTok open API endpoint this twin serves`);
+}
+
+/** A contained unexpected failure. Never exposes local exception text. */
+export function internalError(occurredAt: string): TikTokResponse {
+  return apiError('internal_error', occurredAt);
+}

package/src/tiktok-ids.ts

@@ -0,0 +1,51 @@
+// Deterministic id material for the TikTok twin — the ONE place a served identifier's bytes are
+// derived, shared by the credential minting in `tiktok-store.ts` and the `log_id` every TikTok
+// response carries (`tiktok-errors.ts`).
+//
+// WHY IT IS PURE (runtime contract R9): every value minted here is SERVED — the authorization
+// code rides the callback redirect, the `act.`/`rft.`/`clt.` tokens ride the token reply, and
+// `log_id` is in the envelope of literally every TikTok v2 response, success or failure. A served
+// response must be a pure function of (request, stored state), so there is no clock read and no
+// entropy in this module: callers pass the world instant and a state-derived seed.
+//
+// A twin's credentials are stand-ins, not secrets. Determinism is the contract and predictability
+// from public state is not a threat model a twin has; UNIQUENESS is, and the callers carry it by
+// seeding with the row COUNT of the type being minted (which advances on every mint) plus the
+// subject the credential is issued for.
+
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend/xidentity exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+export function stableHex(seed: string, n: number): string {
+  let out = '';
+  for (let round = 0; out.length < n; round += 1) {
+    let h = 0x811c9dc5;
+    const s = `${round}:${seed}`;
+    for (let i = 0; i < s.length; i += 1) {
+      h ^= s.charCodeAt(i);
+      h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    out += h.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, n);
+}
+
+/** `yyyyMMddHHmmss` in UTC — the leading 14 digits of TikTok's own `log_id` examples. */
+export function logTimestamp(occurredAt: string): string {
+  const d = new Date(occurredAt);
+  const p = (n: number, w = 2) => String(n).padStart(w, '0');
+  return `${p(d.getUTCFullYear(), 4)}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
+}
+
+/**
+ * A TikTok `log_id` — "the unique id associated with every request for debugging purposes"
+ * (developers.tiktok.com error-handling reference, fetched 2026-09-13).
+ *
+ * SHAPE, from the vendor's own two published examples
+ * (`20220829194722CBE87ED59D524E727021`, `202206221854370101130062072500FFA2`): 14 digits of UTC
+ * `yyyyMMddHHmmss` followed by 20 UPPERCASE hex characters — 34 characters total. The twin
+ * reproduces the shape (an integration's log scraper may key on it); the trailing bytes are a
+ * stable hash of the request coordinates, never entropy, because the value is served (R9).
+ */
+export function logId(occurredAt: string, seed: string): string {
+  return `${logTimestamp(occurredAt)}${stableHex(`log:${occurredAt}:${seed}`, 20).toUpperCase()}`;
+}