@volter/twin-tiktok 0.1.0 → 0.1.2

package/dist/client/tiktok-mirror.js

@@ -15,6 +15,15 @@ const SESSION_TOKEN = 'tiktok-mirror.token';
 function readSession() {
     if (typeof sessionStorage === 'undefined')
         return null;
+    // the World signed these screens in as the account its config names (`signIn.as`): taken once, as a sign-in would
+    // (off the page once taken, and not again in this tab once the person signs out)
+    const w = window;
+    const given = sessionStorage.getItem('volter.signedOut') ? undefined : w.__VOLTER_SIGN_IN__;
+    delete w.__VOLTER_SIGN_IN__;
+    if (given && !sessionStorage.getItem(SESSION_TOKEN)) {
+        sessionStorage.setItem(SESSION_HANDLE, given.account);
+        sessionStorage.setItem(SESSION_TOKEN, given.token);
+    }
     const handle = sessionStorage.getItem(SESSION_HANDLE);
     const token = sessionStorage.getItem(SESSION_TOKEN);
     return handle && token ? { handle, token } : null;
@@ -270,6 +279,7 @@ function App() {
     const signOut = useCallback(() => {
         sessionStorage.removeItem(SESSION_HANDLE);
         sessionStorage.removeItem(SESSION_TOKEN);
+        sessionStorage.setItem('volter.signedOut', '1');
         setSession(null);
         setMe(null);
         go('login');

package/dist/client/tiktok-mirror.tsx

@@ -22,6 +22,11 @@ type Wire = { status: number; body: TtRow };
 
 function readSession(): Session | null {
   if (typeof sessionStorage === 'undefined') return null;
+  // the World signed these screens in as the account its config names (`signIn.as`): taken once, as a sign-in would
+  // (off the page once taken, and not again in this tab once the person signs out)
+  const w = window as { __VOLTER_SIGN_IN__?: { account: string; token: string } };
+  const given = sessionStorage.getItem('volter.signedOut') ? undefined : w.__VOLTER_SIGN_IN__; delete w.__VOLTER_SIGN_IN__;
+  if (given && !sessionStorage.getItem(SESSION_TOKEN)) { sessionStorage.setItem(SESSION_HANDLE, given.account); sessionStorage.setItem(SESSION_TOKEN, given.token); }
   const handle = sessionStorage.getItem(SESSION_HANDLE);
   const token = sessionStorage.getItem(SESSION_TOKEN);
   return handle && token ? { handle, token } : null;
@@ -442,7 +447,7 @@ function App() {
 
   const signOut = useCallback(() => {
     sessionStorage.removeItem(SESSION_HANDLE);
-    sessionStorage.removeItem(SESSION_TOKEN);
+    sessionStorage.removeItem(SESSION_TOKEN); sessionStorage.setItem('volter.signedOut', '1');
     setSession(null);
     setMe(null);
     go('login');

package/dist/src/tiktok-mirror-ui.d.ts

@@ -47,3 +47,15 @@ export declare function createTiktokMirrorServer(options: {
 export declare function tiktokMirrorHtml(): string;
 /** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
 export declare function tiktokMirrorStyles(): Promise<string>;
+/** The account `as` names (a username, with or without its @) and a user access token minted for it: what TikTok's
+ *  screens log in with when the World's config says `signIn: { as }` (the World hands them over, served-world.ts).
+ *  The token is issued through the twin's own door (`/_twin/tokens`), as the World's seed does; a stored bearer is
+ *  never read back. Like every TikTok user access token it lives 24 hours of World time (the door sets no other
+ *  life); the screens then log out on the 401. Null when the World holds no such account, or the door refuses. */
+export declare function tiktokMirrorSignIn(as: string, ctx: {
+    root: string;
+    twin: (path: string, init?: RequestInit) => Promise<Response>;
+}): Promise<{
+    account: string;
+    token: string;
+} | null>;

package/dist/src/tiktok-mirror-ui.js

@@ -20,10 +20,11 @@
 // PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's own
 // fetch adapter as its API backend and reads every byte of state back over the wire.
 import { readFile } from 'node:fs/promises';
-import { bundleClient, fileResponse, serveHttp } from '@volter/world-core';
+import { twinResources, filePathOf, bundleClient, fileResponse, serveHttp } from '@volter/world-core';
 import { createTikTokTwinFetch } from "./tiktok-server.js";
-const CLIENT_ENTRY = () => new URL('../client/tiktok-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
-const CLIENT_CSS = () => new URL('../client/tiktok-mirror.css', import.meta.url).pathname; // lazy: same reason
+import { DEFAULT_CLIENT_KEY } from "./tiktok-store.js";
+const CLIENT_ENTRY = () => filePathOf(new URL('../client/tiktok-mirror.tsx', import.meta.url)); // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => filePathOf(new URL('../client/tiktok-mirror.css', import.meta.url)); // lazy: same reason
 /** The user fields the profile reads — every one the Display API gates behind the three user scopes. */
 export const PROFILE_FIELDS = 'open_id,union_id,avatar_url,display_name,username,bio_description,is_verified,follower_count,following_count,likes_count,video_count';
 /** The fields a token holding only user.info.basic may ask for (the header then carries no counts). */
@@ -157,3 +158,30 @@ export function tiktokMirrorHtml() {
 export function tiktokMirrorStyles() {
     return readFile(CLIENT_CSS(), 'utf8');
 }
+/** The account `as` names (a username, with or without its @) and a user access token minted for it: what TikTok's
+ *  screens log in with when the World's config says `signIn: { as }` (the World hands them over, served-world.ts).
+ *  The token is issued through the twin's own door (`/_twin/tokens`), as the World's seed does; a stored bearer is
+ *  never read back. Like every TikTok user access token it lives 24 hours of World time (the door sets no other
+ *  life); the screens then log out on the 401. Null when the World holds no such account, or the door refuses. */
+export async function tiktokMirrorSignIn(as, ctx) {
+    const wanted = as.trim().replace(/^@/, '').toLowerCase();
+    const account = twinResources('tiktok', ctx.root).find((r) => r.type === 'account' && r.deleted !== true && String(r.username ?? '').toLowerCase() === wanted);
+    if (!account)
+        return null;
+    // only what the screens read, and only what the app's grant for this account already holds: minting unions its scopes
+    // into that grant, and opening a page must never widen what the app under test was granted
+    const grant = twinResources('tiktok', ctx.root).find((r) => r.type === 'grant' && r.id === `${DEFAULT_CLIENT_KEY}:${account.id}`);
+    const held = Array.isArray(grant?.scopes) ? grant.scopes.map(String) : [];
+    const scopes = ['user.info.basic', 'user.info.profile', 'user.info.stats', 'video.list'].filter((s) => held.includes(s));
+    if (!scopes.includes('user.info.basic'))
+        return null;
+    const res = await ctx.twin('/_twin/tokens', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ union_id: account.id, scopes }),
+    });
+    if (!res.ok)
+        return null;
+    const body = await res.json().catch(() => null);
+    return typeof body?.access_token === 'string' ? { account: String(account.username), token: body.access_token } : null;
+}

package/dist/src/tiktok-server.js

@@ -11,7 +11,8 @@
 //
 // 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 { isReadOnlyRequest, serveHttp, statefulTwinManifest, twinPublicBase, withRequestScopes, worldNow } from '@volter/world-core';
+import { oauthErrorCode } from "./tiktok-errors.js";
 import { UPLOAD_PATH } from "./tiktok-posting.js";
 import { handleTikTokTwinRequest } from "./tiktok-twin.js";
 /**
@@ -23,8 +24,12 @@ import { handleTikTokTwinRequest } from "./tiktok-twin.js";
  * 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) {
+    // a read-only request (x-volter-read-only, a World's read token) is a request to a read-only twin: the
+    // authorize page never signs anyone in or mints a code, no token is minted or revoked, the Display
+    // API reads are served without spending the app's rate window (D3), and the kernel refuses any write
+    // that slips past as TikTok's own flat OAuth error
+    return withRequestScopes(async function tiktokTwinFetch(request) {
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
         const url = new URL(request.url);
         // GET /twin — the discovery manifest (education inside the twin).
         if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
@@ -71,7 +76,12 @@ export function createTikTokTwinFetch(options = {}) {
         }
         out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
         return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
-    };
+    }, {
+        refuse: () => {
+            const refused = oauthErrorCode('temporarily_unavailable', worldNow(), 405);
+            return new Response(JSON.stringify(refused.body), { status: refused.status, headers: refused.headers });
+        },
+    });
 }
 export async function createTikTokTwinServer(options) {
     const server = await serveHttp({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-tiktok",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local TikTok twin — the real tiktok.com authorization page, the full Login Kit OAuth round trip (token, refresh, revoke, client_credentials) and the Display API user/video reads with TikTok's own comma-separated scopes, per-app open_id, field-level scope gating and both of its error envelopes, so an unmodified TikTok integration completes sign-in-with-TikTok against it. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -57,14 +57,14 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "typescript": "^5.9.0"
   },

package/src/tiktok-mirror-ui.ts

@@ -20,11 +20,12 @@
 // PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's own
 // fetch adapter as its API backend and reads every byte of state back over the wire.
 import { readFile } from 'node:fs/promises';
-import { bundleClient, fileResponse, serveHttp } from '@volter/world-core';
+import { twinResources, filePathOf, bundleClient, fileResponse, serveHttp } from '@volter/world-core';
 import { createTikTokTwinFetch } from './tiktok-server.ts';
+import { DEFAULT_CLIENT_KEY } from './tiktok-store.ts';
 
-const CLIENT_ENTRY = () => new URL('../client/tiktok-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects a top-level relative import.meta.url
-const CLIENT_CSS = () => new URL('../client/tiktok-mirror.css', import.meta.url).pathname;    // lazy: same reason
+const CLIENT_ENTRY = () => filePathOf(new URL('../client/tiktok-mirror.tsx', import.meta.url));  // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => filePathOf(new URL('../client/tiktok-mirror.css', import.meta.url));    // lazy: same reason
 
 // ---------------------------------------------------------------------------
 // Pure, dependency-free helpers (importable by the React client; Bun tree-shakes the server-only
@@ -165,3 +166,28 @@ export function tiktokMirrorHtml(): string {
 export function tiktokMirrorStyles(): Promise<string> {
   return readFile(CLIENT_CSS(), 'utf8');
 }
+
+/** The account `as` names (a username, with or without its @) and a user access token minted for it: what TikTok's
+ *  screens log in with when the World's config says `signIn: { as }` (the World hands them over, served-world.ts).
+ *  The token is issued through the twin's own door (`/_twin/tokens`), as the World's seed does; a stored bearer is
+ *  never read back. Like every TikTok user access token it lives 24 hours of World time (the door sets no other
+ *  life); the screens then log out on the 401. Null when the World holds no such account, or the door refuses. */
+export async function tiktokMirrorSignIn(as: string, ctx: { root: string; twin: (path: string, init?: RequestInit) => Promise<Response> }): Promise<{ account: string; token: string } | null> {
+  const wanted = as.trim().replace(/^@/, '').toLowerCase();
+  const account = twinResources('tiktok', ctx.root).find((r) => r.type === 'account' && r.deleted !== true && String(r.username ?? '').toLowerCase() === wanted);
+  if (!account) return null;
+  // only what the screens read, and only what the app's grant for this account already holds: minting unions its scopes
+  // into that grant, and opening a page must never widen what the app under test was granted
+  const grant = twinResources('tiktok', ctx.root).find((r) => r.type === 'grant' && r.id === `${DEFAULT_CLIENT_KEY}:${account.id}`);
+  const held = Array.isArray(grant?.scopes) ? (grant.scopes as unknown[]).map(String) : [];
+  const scopes = ['user.info.basic', 'user.info.profile', 'user.info.stats', 'video.list'].filter((s) => held.includes(s));
+  if (!scopes.includes('user.info.basic')) return null;
+  const res = await ctx.twin('/_twin/tokens', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ union_id: account.id, scopes }),
+  });
+  if (!res.ok) return null;
+  const body = await res.json().catch(() => null) as { access_token?: unknown } | null;
+  return typeof body?.access_token === 'string' ? { account: String(account.username), token: body.access_token } : null;
+}

package/src/tiktok-server.ts

@@ -11,7 +11,8 @@
 //
 // 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 { isReadOnlyRequest, serveHttp, statefulTwinManifest, twinPublicBase, withRequestScopes, worldNow } from '@volter/world-core';
+import { oauthErrorCode } from './tiktok-errors.ts';
 import { UPLOAD_PATH } from './tiktok-posting.ts';
 import { handleTikTokTwinRequest } from './tiktok-twin.ts';
 
@@ -30,8 +31,12 @@ export interface TikTokTwinFetchOptions {
  * are the SAME code — there is no second HTTP adaptation to drift.
  */
 export function createTikTokTwinFetch(options: TikTokTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  const readOnly = options.readOnly ?? false;
-  return async function tiktokTwinFetch(request: Request): Promise<Response> {
+  // a read-only request (x-volter-read-only, a World's read token) is a request to a read-only twin: the
+  // authorize page never signs anyone in or mints a code, no token is minted or revoked, the Display
+  // API reads are served without spending the app's rate window (D3), and the kernel refuses any write
+  // that slips past as TikTok's own flat OAuth error
+  return withRequestScopes(async function tiktokTwinFetch(request: Request): Promise<Response> {
+    const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
     const url = new URL(request.url);
     // GET /twin — the discovery manifest (education inside the twin).
     if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
@@ -80,7 +85,12 @@ export function createTikTokTwinFetch(options: TikTokTwinFetchOptions = {}): (re
     }
     out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
     return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
-  };
+  }, {
+    refuse: () => {
+      const refused = oauthErrorCode('temporarily_unavailable', worldNow(), 405);
+      return new Response(JSON.stringify(refused.body), { status: refused.status, headers: refused.headers });
+    },
+  });
 }
 
 export async function createTikTokTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {