@volter/twin-tiktok 0.1.0

package/dist/src/tiktok-sample-mp4.js

@@ -0,0 +1,55 @@
+// A real video, as data only — the one sample file the pack's conformance probes, capability verifies
+// and gate replay upload. Kept apart from the handler so the dev-plane gate can read it without
+// importing the code it exists to sabotage.
+/**
+ * A REAL video the posting probes upload: one second of 360x640 black at 24 FPS, H.264 in MP4
+ * (`ffmpeg -f lavfi -i color=c=black:size=360x640:rate=24 -t 1 -crf 51 -movflags +faststart`), the
+ * smallest file TikTok's checks accept — the twin reads its duration, picture size and frame rate,
+ * and a file it cannot read fails with file_format_check_failed.
+ */
+export const TINY_MP4 = Uint8Array.from(atob(''
+    + 'AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAQHbW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAA+gAAQAAAQAA'
+    + 'AAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAA'
+    + 'AzF0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAA+gAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAA'
+    + 'AAAAAAAAAAAAAABAAAAAAWgAAAKAAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAAAPoAAAEAAABAAAAAAKpbWRpYQAAACBtZGhk'
+    + 'AAAAAAAAAAAAAAAAAAAwAAAAMABVxAAAAAAALWhkbHIAAAAAAAAAAHZpZGUAAAAAAAAAAAAAAABWaWRlb0hhbmRsZXIAAAACVG1p'
+    + 'bmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQAAAAx1cmwgAAAAAQAAAhRzdGJsAAAAxHN0c2QA'
+    + 'AAAAAAAAAQAAALRhdmMxAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAWgCgABIAAAASAAAAAAAAAABFUxhdmM2Mi4yOC4xMDIgbGli'
+    + 'eDI2NAAAAAAAAAAAAAAAGP//AAAAOmF2Y0MBZAAf/+EAHGdkAB+scgRBcFHl8BEAAAMAAQAAAwAwDxgxhGABAAdo6EOBlLIs/fj4'
+    + 'AAAAABBwYXNwAAAAAQAAAAEAAAAUYnRydAAAAAAAACVYAAAAAAAAABhzdHRzAAAAAAAAAAEAAAAYAAACAAAAABRzdHNzAAAAAAAA'
+    + 'AAEAAAABAAAAeGN0dHMAAAAAAAAADQAAAAEAAAQAAAAAAQAAFAAAAAABAAAIAAAAAAMAAAAAAAAABAAAAgAAAAABAAAUAAAAAAEA'
+    + 'AAgAAAAAAwAAAAAAAAAEAAACAAAAAAEAAAwAAAAAAQAABAAAAAABAAAAAAAAAAIAAAIAAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAAY'
+    + 'AAAAAQAAAHRzdHN6AAAAAAAAAAAAAAAYAAADCQAAABIAAAARAAAAEQAAABEAAAARAAAAEQAAABEAAAARAAAAEQAAABcAAAASAAAA'
+    + 'EgAAABIAAAASAAAAEgAAABIAAAASAAAAEgAAABkAAAASAAAAEgAAABIAAAASAAAAFHN0Y28AAAAAAAAAAQAABDcAAABidWR0YQAA'
+    + 'AFptZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAC1pbHN0AAAAJal0b28AAAAdZGF0YQAAAAEAAAAA'
+    + 'TGF2ZjYyLjEyLjEwMgAAAAhmcmVlAAAEs21kYXQAAAKxBgX//63cRem95tlIt5Ys2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIy'
+    + 'IGIzNTYwNWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQgMjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xh'
+    + 'bi5vcmcveDI2NC5odG1sIC0gb3B0aW9uczogY2FiYWM9MSByZWY9MTYgZGVibG9jaz0xOjA6MCBhbmFseXNlPTB4MzoweDEzMyBt'
+    + 'ZT11bWggc3VibWU9MTAgcHN5PTEgcHN5X3JkPTEuMDA6MC4wMCBtaXhlZF9yZWY9MSBtZV9yYW5nZT0yNCBjaHJvbWFfbWU9MSB0'
+    + 'cmVsbGlzPTIgOHg4ZGN0PTEgY3FtPTAgZGVhZHpvbmU9MjEsMTEgZmFzdF9wc2tpcD0xIGNocm9tYV9xcF9vZmZzZXQ9LTIgdGhy'
+    + 'ZWFkcz0xOCBsb29rYWhlYWRfdGhyZWFkcz0zIHNsaWNlZF90aHJlYWRzPTAgbnI9MCBkZWNpbWF0ZT0xIGludGVybGFjZWQ9MCBi'
+    + 'bHVyYXlfY29tcGF0PTAgY29uc3RyYWluZWRfaW50cmE9MCBiZnJhbWVzPTggYl9weXJhbWlkPTIgYl9hZGFwdD0yIGJfYmlhcz0w'
+    + 'IGRpcmVjdD0zIHdlaWdodGI9MSBvcGVuX2dvcD0wIHdlaWdodHA9MiBrZXlpbnQ9MjUwIGtleWludF9taW49MjQgc2NlbmVjdXQ9'
+    + 'NDAgaW50cmFfcmVmcmVzaD0wIHJjX2xvb2thaGVhZD02MCByYz1jcmYgbWJ0cmVlPTEgY3JmPTUxLjAgcWNvbXA9MC42MCBxcG1p'
+    + 'bj0wIHFwbWF4PTY5IHFwc3RlcD00IGlwX3JhdGlvPTEuNDAgYXE9MToxLjAwAIAAAABQZYiBAAT/Hru//lSYAAADAAAKEgzs1poj'
+    + 'pAAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAAwAAC7kAAAAOQZoJLYhP/wAAAwAAEnAA'
+    + 'AAANQZ4QhxCPAAADAAA1IQAAAA0BnhgmiL8AAAMAADegAAAADQGeGEaIvwAAAwAAN6EAAAANAZ4YZoi/AAADAAA3oQAAAA0Bnhit'
+    + 'SL8AAAMAADehAAAADQGeGM1IvwAAAwAAN6EAAAANAZ4Y7Ui/AAADAAA3oAAAAA0BnhkNSL8AAAMAADegAAAAE0GaGkk1AgLRMpgQ'
+    + 'jwAAAwAAFTEAAAAOQZ4hpcQj/wAAAwAANSAAAAAOAZ4pRaIv/wAAAwAAN6AAAAAOAZ4pZaIv/wAAAwAAN6EAAAAOAZ4phaIv/wAA'
+    + 'AwAAN6EAAAAOAZ4pzJIv/wAAAwAAN6EAAAAOAZ4p7JIv/wAAAwAAN6AAAAAOAZ4qDJIv/wAAAwAAN6AAAAAOAZ4qLJIv/wAAAwAA'
+    + 'N6EAAAAVQZoq6bUCAtrRMpgBF/8AAAMAAB6QAAAADkGeMoSxH/8AAAMAADZgAAAADgGeOmSoi/8AAAMAADehAAAADgGeOqzSL/8A'
+    + 'AAMAADegAAAADgGeOszSL/8AAAMAADeh'), (c) => c.charCodeAt(0));
+/** TINY_MP4 grown to exactly `size` bytes by a trailing `free` box (ISO BMFF's padding box): still a
+ *  valid, readable MP4, for the probes that need a video past TikTok's 5 MB chunk floor. */
+export function paddedMp4(size) {
+    const pad = size - TINY_MP4.length;
+    if (pad < 8)
+        throw new Error(`paddedMp4: ${size} is below ${TINY_MP4.length + 8}`);
+    const out = new Uint8Array(size);
+    out.set(TINY_MP4);
+    new DataView(out.buffer).setUint32(TINY_MP4.length, pad);
+    out.set([0x66, 0x72, 0x65, 0x65], TINY_MP4.length + 4);
+    for (let i = TINY_MP4.length + 8; i < size; i += 1)
+        out[i] = (i * 31 + (i >> 11)) & 0xff;
+    return out;
+}

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

@@ -0,0 +1,29 @@
+export type ScopeProduct = 'user' | 'video' | 'portability' | 'research' | 'local';
+export type ScopeInfo = {
+    scope: string;
+    /** The vendor's own published description of the scope. */
+    label: string;
+    product: ScopeProduct;
+    /** In the vendor catalog? An unknown scope is still displayed, flagged, so a typo is visible. */
+    known: boolean;
+};
+/** The scopes TikTok's scopes-overview page publishes, keyed by scope id. */
+export declare const SCOPE_CATALOG: Record<string, {
+    label: string;
+    product: ScopeProduct;
+}>;
+export declare const KNOWN_SCOPES: readonly string[];
+/**
+ * Comma-separated scope param -> ordered unique scope list.
+ *
+ * Whitespace around a comma is tolerated because a caller that pretty-prints its scope constant
+ * would otherwise send a scope literally named " video.list". The SEPARATOR the twin requires is
+ * still the comma: a space-separated X-style string parses as ONE unknown scope and renders
+ * flagged on the screen, which is the integration bug a developer needs to see.
+ */
+export declare function parseScopeParam(raw: string | null): string[];
+/** The wire form: comma-separated, no spaces (the docs' own `user.info.basic,video.list`). */
+export declare function formatScopeParam(scopes: readonly string[]): string;
+export declare function describeScope(scope: string): ScopeInfo;
+export declare function describeScopes(scopes: readonly string[]): ScopeInfo[];
+export declare function sortScopesForConsent(scopes: readonly string[]): string[];

package/dist/src/tiktok-scopes.js

@@ -0,0 +1,106 @@
+// TikTok OAuth scopes — the vendor's own catalog, transcribed from the TikTok for Developers
+// "Scopes Overview" page (https://developers.tiktok.com/doc/tiktok-api-scopes/, fetched
+// 2026-09-13) together with the per-product reference pages the overview links to.
+//
+// TWO THINGS THIS VENDOR DOES THAT THE X / GOOGLE CONSENT MODELS DO NOT:
+//
+//   1. The scope parameter is COMMA-separated (`scope=user.info.basic,user.info.profile`), not
+//      space-separated. That is documented on the Login Kit for Web parameter table ("A comma (,)
+//      separated string of authorization scope(s)") and it is exactly how Dub builds its authorize
+//      URL. A twin that accepted only spaces would refuse the vendor's own callers.
+//
+//   2. Consent is GRANULAR, not all-or-nothing. The documented callback carries a `scopes`
+//      parameter — "A comma-separated (,) string of authorization scope(s), which the user has
+//      granted" — which only has meaning if the granted set can be a SUBSET of the requested set,
+//      and the token response's `scope` is likewise "the scopes the user has agreed to authorize".
+//      So the authorize screen this twin serves offers one checkbox per requested scope and the
+//      granted set is what came back checked. EVIDENCE BOUNDARY: the two parameters above are
+//      documented; the SHAPE of the live affordance (per-scope toggles, which scopes are
+//      mandatory, what the buttons say) was not captured from a vendor artefact and is pinned by
+//      `tiktok.consent.optional_scope_toggles` and `tiktok.consent.button_wording` (todo).
+//
+// EVIDENCE BOUNDARY on the LABELS, and it is NOT uniform — say which is which rather than let a
+// "verbatim" claim cover the lot. THREE labels are the Scopes Overview's own published text, word
+// for word, and are asserted as such by `tiktok.scopes.catalog_matches_vendor_list`:
+// `user.info.basic`, `user.info.profile` and `video.list`. The other EIGHTEEN are TWIN PARAPHRASES
+// written from the overview's per-product descriptions — accurate in substance, not quotations —
+// because the overview publishes those rows as product prose rather than as a scope string. Every
+// label is developer-facing either way, never a capture of the live consent sheet, so
+// `tiktok.scopes.consent_wording` (todo) pins the strings a person actually reads. The SCOPE IDS,
+// by contrast, are all twenty-one exactly as published, and that set is what the capability
+// asserts a bijection against.
+/** The scopes TikTok's scopes-overview page publishes, keyed by scope id. */
+export const SCOPE_CATALOG = {
+    // ── User Info API ──
+    // VERBATIM marks a label that is the Scopes Overview's own published text, word for word;
+    // every unmarked label is a TWIN PARAPHRASE of that page's product prose (see the header).
+    // VERBATIM
+    'user.info.basic': { label: "Read a user's profile info (open id, avatar, display name...)", product: 'user' },
+    // VERBATIM
+    'user.info.profile': { label: 'Read access to profile_web_link, profile_deep_link, bio_description, is_verified', product: 'user' },
+    'user.info.stats': { label: 'Read your engagement metrics: follower count, following count, likes count and video count', product: 'user' },
+    // ── Display API / Content Posting API ──
+    // VERBATIM
+    'video.list': { label: "Read a user's public videos on TikTok", product: 'video' },
+    'video.upload': { label: 'Share videos to your account as drafts, for you to edit before posting', product: 'video' },
+    'video.publish': { label: "Directly post content to a user's TikTok profile", product: 'video' },
+    // ── Data Portability API ──
+    'portability.activity.ongoing': { label: 'Export your activity data on an ongoing basis', product: 'portability' },
+    'portability.activity.single': { label: 'Export your activity data once', product: 'portability' },
+    'portability.all.ongoing': { label: 'Export your complete data archive on an ongoing basis', product: 'portability' },
+    'portability.all.single': { label: 'Export your complete data archive once', product: 'portability' },
+    'portability.directmessages.ongoing': { label: 'Export your direct messages on an ongoing basis', product: 'portability' },
+    'portability.directmessages.single': { label: 'Export your direct messages once', product: 'portability' },
+    'portability.postsandprofile.ongoing': { label: 'Export your posts and profile data on an ongoing basis', product: 'portability' },
+    'portability.postsandprofile.single': { label: 'Export your posts and profile data once', product: 'portability' },
+    // ── Research API ──
+    'research.data.basic': { label: 'Access public data for research purposes', product: 'research' },
+    'research.data.u18eu': { label: 'Access data of European users under 18 for research purposes', product: 'research' },
+    'research.data.vra': { label: 'Access vetted-researcher provisioned data', product: 'research' },
+    'research.adlib.basic': { label: 'Access commercial content data for research purposes', product: 'research' },
+    // ── Local Services API ──
+    'local.product.manage': { label: 'Manage the products of your local services account', product: 'local' },
+    'local.shop.manage': { label: 'Manage the shops of your local services account', product: 'local' },
+    'local.voucher.manage': { label: 'Manage the vouchers of your local services account', product: 'local' },
+};
+export const KNOWN_SCOPES = Object.keys(SCOPE_CATALOG);
+/**
+ * Comma-separated scope param -> ordered unique scope list.
+ *
+ * Whitespace around a comma is tolerated because a caller that pretty-prints its scope constant
+ * would otherwise send a scope literally named " video.list". The SEPARATOR the twin requires is
+ * still the comma: a space-separated X-style string parses as ONE unknown scope and renders
+ * flagged on the screen, which is the integration bug a developer needs to see.
+ */
+export function parseScopeParam(raw) {
+    if (!raw)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const piece of raw.split(',')) {
+        const s = piece.trim();
+        if (!s || seen.has(s))
+            continue;
+        seen.add(s);
+        out.push(s);
+    }
+    return out;
+}
+/** The wire form: comma-separated, no spaces (the docs' own `user.info.basic,video.list`). */
+export function formatScopeParam(scopes) {
+    return scopes.join(',');
+}
+export function describeScope(scope) {
+    const known = SCOPE_CATALOG[scope];
+    return known
+        ? { scope, label: known.label, product: known.product, known: true }
+        : { scope, label: scope, product: 'user', known: false };
+}
+export function describeScopes(scopes) {
+    return scopes.map(describeScope);
+}
+/** Screen order: the vendor's own product order, stable so the page is byte-identical on reload. */
+const PRODUCT_ORDER = { user: 0, video: 1, portability: 2, research: 3, local: 4 };
+export function sortScopesForConsent(scopes) {
+    return [...scopes].sort((a, b) => PRODUCT_ORDER[describeScope(a).product] - PRODUCT_ORDER[describeScope(b).product]);
+}

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

@@ -0,0 +1,28 @@
+/** Options every TikTok-twin HTTP surface needs, independent of who owns the socket. */
+export interface TikTokTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createTikTokTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted surfaces
+ * are the SAME code — there is no second HTTP adaptation to drift.
+ */
+export declare function createTikTokTwinFetch(options?: TikTokTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createTikTokTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/**
+ * The authorization page is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-tiktok mirror` command and the journey
+ * harness have the conventional entry point, and it returns the very same server.
+ */
+export declare const createTikTokConsentServer: typeof createTikTokTwinServer;

package/dist/src/tiktok-server.js

@@ -0,0 +1,89 @@
+// TikTok twin HTTP server — ONE server for the whole vendor surface, because Login Kit is one
+// product spread over two hosts. Point `www.tiktok.com` (the authorization page) and
+// `open.tiktokapis.com` (the OAuth + Display API endpoints) here and an unmodified TikTok
+// integration completes a full authorization-code round trip against it.
+//
+// Two things this server does that a JSON-only twin server does not:
+//   • it can answer with HTML and with 302 redirects — the authorization page and the callback
+//     bounce are the protocol, not decoration, so the handler's `headers` (content-type, location)
+//     pass straight through rather than being flattened into a JSON envelope;
+//   • it tells the handler its OWN origin, so the consent form's action points BACK AT THE TWIN.
+//
+// The page needs no assets: the stylesheet is inlined and the screen ships no JavaScript, so there
+// is no bundler and no disk read anywhere on the serve path (runtime contract R12b, R9).
+import { serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+import { UPLOAD_PATH } from "./tiktok-posting.js";
+import { handleTikTokTwinRequest } from "./tiktok-twin.js";
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createTikTokTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted surfaces
+ * are the SAME code — there is no second HTTP adaptation to drift.
+ */
+export function createTikTokTwinFetch(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    return async function tiktokTwinFetch(request) {
+        const url = new URL(request.url);
+        // GET /twin — the discovery manifest (education inside the twin).
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(statefulTwinManifest({
+                vendor: 'tiktok',
+                twinOf: 'TikTok Login Kit, the Display API and the Content Posting API',
+                stores: 'developer apps, TikTok accounts and their videos (with the posted media), authorization codes, user access/refresh tokens, the authorization-page round trip and Content Posting publishes',
+            }));
+        }
+        // the upload URL's chunk PUT carries BYTES; every other body is text (form or JSON)
+        const upload = url.pathname.replace(/\/+$/, '') === UPLOAD_PATH;
+        const raw = request.method === 'GET' || request.method === 'HEAD' ? new Uint8Array(0) : new Uint8Array(await request.arrayBuffer());
+        const body = upload ? '' : new TextDecoder().decode(raw);
+        const headers = {};
+        request.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        const res = await handleTikTokTwinRequest({
+            method: request.method,
+            path: url.pathname + (url.search || ''),
+            body,
+            headers,
+            readOnly,
+            occurredAt: worldNow(),
+            origin: twinPublicBase(request),
+            callbackOrigin: url.origin,
+            ...(upload ? { bytes: raw } : {}),
+            ...(headers['x-volter-twin-original-host'] ? { originalHost: headers['x-volter-twin-original-host'].toLowerCase() } : {}),
+            ...(options.root !== undefined ? { root: options.root } : {}),
+        });
+        const out = { ...(res.headers ?? {}) };
+        // a post's bytes (the media route): a range as bytes, a whole file as a stream of ranged reads;
+        // HEAD answers the headers alone
+        if (res.body instanceof Uint8Array || res.body instanceof ReadableStream) {
+            const media = request.method === 'HEAD' ? null : res.body;
+            return new Response(media, { status: res.status, headers: out });
+        }
+        // A string body is already rendered (HTML, or the empty body of a 302); anything else is the
+        // vendor's JSON.
+        if (typeof res.body === 'string') {
+            if (!out['content-type'] && res.body)
+                out['content-type'] = 'text/html; charset=utf-8';
+            return new Response(res.body, { status: res.status, headers: out });
+        }
+        out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
+        return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
+    };
+}
+export async function createTikTokTwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createTikTokTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+/**
+ * The authorization page is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-tiktok mirror` command and the journey
+ * harness have the conventional entry point, and it returns the very same server.
+ */
+export const createTikTokConsentServer = createTikTokTwinServer;

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

@@ -0,0 +1,164 @@
+import { type TwinResource } from '@volter/world-core';
+/** A credential as the log keeps it: its SHA-256 (hex), never the credential. */
+export declare function secretKey(value: string): string;
+export declare const SERVICE = "tiktok";
+/**
+ * THE CREDENTIAL ROWS ARE BOOKKEEPING, AND THEY NEVER NAME THEIR CREDENTIAL. An authorization code,
+ * an access / refresh / client token and a rate window are the twin's own records: nothing about them
+ * crosses to TikTok, so they are `_`-prefixed (world-core `isTwinBookkeeping`) and never deployed or
+ * pushed. Each is keyed by the SHA-256 of the credential (`secretKey`), never the credential — the
+ * YouTube `_token` pattern — so no event log, resource record or changeset a World keeps holds a
+ * bearer in the clear. A presented credential is hashed and looked up.
+ */
+export declare const BK_CODE = "_authorization_code";
+export declare const BK_ACCESS = "_access_token";
+export declare const BK_REFRESH = "_refresh_token";
+export declare const BK_CLIENT = "_client_token";
+export declare const BK_RATE = "_rate_window";
+export declare const RESOURCE_TYPES: readonly ["oauth_client", "account", "session", "auth_request", "_authorization_code", "_access_token", "_refresh_token", "_client_token", "grant", "video", "publish", "_rate_window"];
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+export type Row = TwinResource & Record<string, any>;
+export declare function readAll(root: string | undefined): Row[];
+export declare function readType(root: string | undefined, type: ResourceType): Row[];
+export declare function readOne(root: string | undefined, type: ResourceType, id: string): Row | undefined;
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export declare function nextRev(root: string | undefined, type: ResourceType, id: string): number;
+/** The next revision from a snapshot already held under the kernel projection lock. */
+export declare function nextRevIn(resources: readonly TwinResource[], type: ResourceType, id: string): number;
+export type WriteOpts = {
+    root?: string;
+    occurredAt?: string;
+};
+/** Seeding also needs the origin the twin was reached on, so the demo app's registered callback
+ *  points back at THIS twin rather than at a baked-in port (runtime contract R7). */
+export type SeedOpts = WriteOpts & {
+    origin?: string;
+};
+export declare function write(type: ResourceType, id: string, operation: string, fields: Record<string, unknown>, opts: WriteOpts): Promise<Row>;
+/** A state-dependent one-row update whose read/revision/write decision is one kernel transaction. */
+export declare function writeAtomic(type: ResourceType, id: string, operation: string, fields: (resources: readonly TwinResource[]) => Record<string, unknown>, opts: WriteOpts): Promise<Row>;
+/**
+ * A TikTok user access token. The vendor's own example is `act.example12345Example12345Example`
+ * (User Access Token Management guide) — a dotted prefix plus an opaque tail, and integrations do
+ * key on the prefix. The twin reproduces the shape; the bytes are not the vendor's.
+ */
+export declare const mintAccessToken: (root: string | undefined, at: number, subject: string) => string;
+/** A TikTok refresh token — the docs' `rft.example12345Example12345Example`. */
+export declare const mintRefreshToken: (root: string | undefined, at: number, subject: string) => string;
+/** An app-only client access token — the client-credentials guide's `clt.example12345…`. */
+export declare const mintClientToken: (root: string | undefined, at: number, subject: string) => string;
+/**
+ * An authorization code.
+ *
+ * EXTRAPOLATION, and a deliberate one. The token endpoint's parameter table says the `code` is
+ * "The authorization code from the web, iOS, Android or desktop authorization callback" and the
+ * summary page says it must be "URL decoded" — a note that is only meaningful if the code carries
+ * characters a query string must percent-encode. TikTok's codes are widely reported to end in a
+ * `*!<n>!` marker (`…%2A%211%21` on the wire), so the twin mints that shape: an integration that
+ * forgets to decode the callback parameter then fails HERE, locally, instead of against the real
+ * vendor. The exact live format is pinned by `tiktok.token.code_format` (todo).
+ */
+export declare const mintAuthorizationCode: (root: string | undefined, at: number, subject: string) => string;
+/**
+ * A Content Posting `publish_id`, in the two shapes the references print: `v_pub_file~v2-1.123456789`
+ * for a Direct Post and `v_inbox_file~v2.123456789` for an upload to the creator's inbox.
+ */
+export declare const mintPublishId: (mode: "direct" | "inbox") => string;
+/** The upload_id in an upload_url's query (the references print `upload_id=67890`). */
+export declare const mintUploadId: () => string;
+/** A published post's id — the 19-digit item id the Video Object carries and status/fetch reports in
+ *  `publicaly_available_post_id`. */
+export declare const mintPostId: () => string;
+/** A TikTok client key — the developer portal hands out an `aw…` string for a web app. */
+export declare const mintClientKey: (root: string | undefined, instant: string) => string;
+/**
+ * The `open_id` a given app sees a given account as — PER (client_key, account) and STABLE, which
+ * is the whole distinction the vendor draws between `open_id` ("The TikTok user's unique
+ * identifier", app-scoped) and `union_id` (the same human across one developer's apps). No count
+ * and no instant enter this seed: re-authorizing must hand the app back the SAME open_id, and two
+ * different apps must see two different ones.
+ */
+export declare const openIdFor: (clientKey: string, accountId: string) => string;
+/**
+ * Twin-internal handle for an authorize screen in flight (never leaves the twin's own pages) —
+ * `ar_` + 32 hex, a pure function of (request, stored state).
+ *
+ * An authorize request whose parameters ALREADY name an unsettled pending row reuses that row's
+ * id: pressing reload on the authorize screen is the same screen, not a new one.
+ */
+export declare function authRequestIdFor(root: string | undefined, occurredAt: string, fields: Record<string, unknown>): string;
+/** The seeded demo app's client key. TikTok web apps are issued an `aw…` key by the developer
+ *  portal; a world running a real integration registers ITS OWN key through `POST /_twin/clients`
+ *  (there is no TikTok API that creates an app, so this is the only honest door). */
+export declare const DEFAULT_CLIENT_KEY = "awtwindemoapp00001";
+export declare const DEFAULT_CLIENT_SECRET = "twin-demo-client-secret-000000000000";
+export type SeedAccount = {
+    /** The subject id: the account's `union_id`, which is the vendor's own cross-app user key. */
+    unionId: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string;
+    avatarUrl100: string;
+    avatarLargeUrl: string;
+    bioDescription: string;
+    profileDeepLink: string;
+    isVerified: boolean;
+    followerCount: number;
+    followingCount: number;
+    likesCount: number;
+    videoCount: number;
+};
+/**
+ * TikTok `union_id`s are v4-shaped UUIDs. The seeded personas take the ALL-ZERO corner of that
+ * space (`00000000-0000-4000-8000-…`), which a real v4 generator will not produce, so a locally
+ * seeded persona can never collide with a pulled real account (the datadog EVENT_ID_BASE / xidentity
+ * 9e18 precedent: the kernel projects twin-side writes over observations, so a colliding id would
+ * keep serving the local row).
+ */
+export declare const DEFAULT_ACCOUNTS: SeedAccount[];
+export type SeedVideo = {
+    id: string;
+    ownerUnionId: string;
+    title: string;
+    videoDescription: string;
+    /** UTC unix epoch SECONDS — the vendor's own `create_time` unit. */
+    createTime: number;
+    duration: number;
+    height: number;
+    width: number;
+    likeCount: number;
+    commentCount: number;
+    shareCount: number;
+    viewCount: number;
+};
+/** TikTok video ids ("also called item_id") are 19-digit numeric strings. The seeded ones start at
+ *  7.0e18, inside the shape but pinned to constants so the Display API reads are deterministic. */
+export declare const DEFAULT_VIDEOS: SeedVideo[];
+/**
+ * The redirect URIs the seeded demo app registers.
+ *
+ * Runtime contract R7: a twin NEVER bakes a port into served content or config. The callbacks are
+ * DERIVED from the origin the twin was actually reached on (`TikTokRequest.origin`, which
+ * tiktok-server fills from the URL the request arrived at). A caller that declares no origin — an
+ * in-process call — seeds no callbacks at all and registers its own through the twin door.
+ */
+export declare function defaultRedirectUris(origin?: string): string[];
+/**
+ * Materialise the default app + accounts + videos + session once per root. Idempotent by subject
+ * id: re-running it over a seeded root writes nothing new, and it NEVER overwrites an
+ * operator-registered app, account, video or session choice.
+ */
+export declare function ensureSeed(opts: SeedOpts): Promise<void>;
+/** The account the tiktok.com browser session is signed in as (the one the sheet consents). */
+export declare function sessionAccount(root: string | undefined): Row | undefined;
+/**
+ * Is `candidate` a registered Redirect URI for this app? TikTok's parameter table says the
+ * redirect_uri "must match one of the redirect URIs you registered", so the twin compares exactly.
+ *
+ * EVIDENCE BOUNDARY: the docs do not state whether the comparison is exact or prefix-based, nor
+ * whether TikTok's documented desktop-only allowance for `http://127.0.0.1:*` wildcards extends to
+ * web apps. Exact is the strict reading, and a loosely-matching twin would hide the single most
+ * common Login Kit integration bug; `tiktok.authorize.redirect_uri_matching` (todo) pins the live
+ * rule and `tiktok.authorize.redirect_uri_scheme_rules` pins the scheme/port restrictions.
+ */
+export declare function redirectUriAllowed(client: Row, candidate: string): boolean;