tca-js 0.4.0 → 0.5.0

package/README.md

@@ -86,6 +86,11 @@ await new TikTok().login({ cookies: 'sessionid=…; ttwid=…' }); // header str
 Required cookies: `sessionid`, `sid_tt`, `sid_guard`, `uid_tt`, `ttwid`, `odin_tt`, `store-idc`, `tt-target-idc`.
 A session lasts about 6 months, and logging in does not sign out other devices.
 
+> **Sending needs `ticketGuard`** (since 12/11/2026). TikTok signs `message/send` with a per-login key pair; a session
+> that sends unsigned gets blocked after its first message (`SESSION_BLOCKED`). Cookies alone are enough to READ, but
+> to send use credentials from `loginQR` (which captures `ticketGuard`) and persist them as a whole — including
+> `api.getContext().ticketGuard`. Treat it as secret as the cookies.
+
 ### QR code
 
 `loginQR` opens a headless Chrome on TikTok's QR page, emits the QR image, and resolves with credentials once the code is
@@ -101,7 +106,7 @@ const credentials = await loginQR({
 });
 
 const api = await new TikTok().login(credentials);
-// Save `credentials` to skip scanning next time.
+// Save `credentials` (cookies + ticketGuard) to skip scanning next time — both are secrets.
 ```
 
 | Option       | Type          | Default     | Description                                                                        |
@@ -143,12 +148,13 @@ with `sendMessage(msg, …)`.
 
 ### Session
 
-| Method / property | Description                                                  |
-| ----------------- | ------------------------------------------------------------ |
-| `account`         | Logged-in account: `uid`, `username`, `screenName`, `avatar` |
-| `getOwnId()`      | Own user id                                                  |
-| `getCookies()`    | Current cookies — persist them to resume the session         |
-| `isAlive()`       | `true` while the session is still valid                      |
+| Method / property | Description                                                   |
+| ----------------- | ------------------------------------------------------------- |
+| `account`         | Logged-in account: `uid`, `username`, `screenName`, `avatar`  |
+| `getOwnId()`      | Own user id                                                   |
+| `getCookies()`    | Current cookies — persist them to resume the session          |
+| `getContext()`    | `deviceId`, `userAgent`, `ticketGuard` — persist with cookies |
+| `isAlive()`       | `true` while the session is still valid                       |
 
 ### Message object
 
@@ -184,13 +190,14 @@ api.listener.stop();
 
 All library errors are instances of `TikTokError` with a `code`:
 
-| Code                                | Meaning                                    |
-| ----------------------------------- | ------------------------------------------ |
-| `SESSION_EXPIRED`                   | Cookies are no longer valid — log in again |
-| `IM_ERROR`                          | TikTok rejected the request                |
-| `HTTP_ERROR` · `BAD_RESPONSE`       | Network or unexpected response             |
-| `UPLOAD_FAILED` · `DOWNLOAD_FAILED` | Media transfer failed                      |
-| `LOGIN_FAILED` · `LOGIN_ABORTED`    | QR login failed or was cancelled           |
+| Code                                | Meaning                                                                                                                         |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `SESSION_EXPIRED`                   | Cookies are no longer valid — log in again                                                                                      |
+| `SESSION_BLOCKED`                   | TikTok's gateway refuses this session (JSON `status_code: 7`) — usually sent without `ticketGuard`; log in again with `loginQR` |
+| `IM_ERROR`                          | TikTok rejected the request                                                                                                     |
+| `HTTP_ERROR` · `BAD_RESPONSE`       | Network or unexpected response                                                                                                  |
+| `UPLOAD_FAILED` · `DOWNLOAD_FAILED` | Media transfer failed                                                                                                           |
+| `LOGIN_FAILED` · `LOGIN_ABORTED`    | QR login failed or was cancelled                                                                                                |
 
 ```ts
 import { TikTokError } from 'tca-js';

package/dist/index.d.mts

@@ -44,6 +44,22 @@ interface Credentials {
     /** IM device id (`wid`) — leave empty and `login` asks TikTok using `ttwid`. Only used when that fails. */
     deviceId?: string;
     userAgent?: string;
+    /**
+     * Request-signing material captured at login (`loginQR` fills it). Required to SEND messages since 12/11/2026 —
+     * without it TikTok blocks the session's sends after the first one (`SESSION_BLOCKED`). Keep it with the cookies.
+     */
+    ticketGuard?: TicketGuard;
+}
+/** TikTok "ticket guard" signing material — see `protocol/ticket-guard.ts`. Secret: treat like the session cookie. */
+interface TicketGuard {
+    /** EC P-256 private key, PKCS#8 PEM. */
+    privateKey: string;
+    /** Matching public key, SPKI PEM. */
+    publicKey: string;
+    /** Server-issued `ts_sign` bound to the public key. */
+    tsSign: string;
+    /** Server-issued ticket (plain text). */
+    ticket: string;
 }
 interface TikTokOptions {
     /** Debug logging — silent by default. */
@@ -152,6 +168,8 @@ declare class Context {
      */
     deviceId: string;
     readonly userAgent: string;
+    /** Signing material for `SIGNED_PATHS` — absent for sessions saved before 0.5.0 (sends then go unsigned). */
+    readonly ticketGuard?: TicketGuard;
     ownId: string;
     private seq;
     constructor(creds: Credentials, options?: TikTokOptions);
@@ -166,7 +184,8 @@ declare class Context {
     buildRequest(cmd: number, bodyField: number, body: Buffer): Buffer;
     /**
      * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
-     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 09/11/2026).
+     * NO X-Gnarly/X-Bogus/msToken signature needed. `message/send` additionally needs the ticket-guard headers
+     * (enforced 12/11/2026) — added from `ticketGuard` when present.
      */
     im(path: string, cmd: number, body: Buffer, bodyField?: number): Promise<Msg>;
 }
@@ -230,9 +249,11 @@ declare class API {
         name: string;
         value: string;
     }[];
+    /** Non-cookie session state to save alongside the cookies (pass back into `login`). */
     getContext(): {
         deviceId: string;
         userAgent: string;
+        ticketGuard?: TicketGuard;
     };
     /** Whether the session is still alive — call periodically to detect expiry early. */
     isAlive(): Promise<boolean>;
@@ -307,7 +328,12 @@ declare class TikTokError extends Error {
 }
 type TikTokErrorCode = 
 /** Cookie is no longer logged in — a new session is required. */
-'SESSION_EXPIRED' | 'HTTP_ERROR'
+'SESSION_EXPIRED'
+/**
+ * TikTok's gateway rejects this session for the command (JSON `status_code: 7` instead of protobuf). Seen on
+ * `message/send` while reads keep working — log in again to get a fresh session.
+ */
+ | 'SESSION_BLOCKED' | 'HTTP_ERROR'
 /** IM returned a non-zero `status_code`. */
  | 'IM_ERROR' | 'UPLOAD_FAILED' | 'DOWNLOAD_FAILED' | 'BAD_RESPONSE'
 /** QR login failed (Chrome failed to launch, QR expired, no cookie found…). */
@@ -366,4 +392,4 @@ declare function loginQR(opts: QrLoginOptions): Promise<Credentials>;
 declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
 
 export { API, Listener, MANUAL_CLOSE, MessageType, TikTok, TikTokError, findChrome, loginQR };
-export type { ConversationPage, ConversationRef, CookieInput, Credentials, ImageInput, ListenerEvents, MessagePage, QrLoginEvent, QrLoginOptions, SendResult, TikTokAccount, TikTokConversation, TikTokErrorCode, TikTokImage, TikTokMessage, TikTokOptions, TikTokReaction, TikTokSticker, TikTokUser };
+export type { ConversationPage, ConversationRef, CookieInput, Credentials, ImageInput, ListenerEvents, MessagePage, QrLoginEvent, QrLoginOptions, SendResult, TicketGuard, TikTokAccount, TikTokConversation, TikTokErrorCode, TikTokImage, TikTokMessage, TikTokOptions, TikTokReaction, TikTokSticker, TikTokUser };

package/dist/index.d.ts

@@ -44,6 +44,22 @@ interface Credentials {
     /** IM device id (`wid`) — leave empty and `login` asks TikTok using `ttwid`. Only used when that fails. */
     deviceId?: string;
     userAgent?: string;
+    /**
+     * Request-signing material captured at login (`loginQR` fills it). Required to SEND messages since 12/11/2026 —
+     * without it TikTok blocks the session's sends after the first one (`SESSION_BLOCKED`). Keep it with the cookies.
+     */
+    ticketGuard?: TicketGuard;
+}
+/** TikTok "ticket guard" signing material — see `protocol/ticket-guard.ts`. Secret: treat like the session cookie. */
+interface TicketGuard {
+    /** EC P-256 private key, PKCS#8 PEM. */
+    privateKey: string;
+    /** Matching public key, SPKI PEM. */
+    publicKey: string;
+    /** Server-issued `ts_sign` bound to the public key. */
+    tsSign: string;
+    /** Server-issued ticket (plain text). */
+    ticket: string;
 }
 interface TikTokOptions {
     /** Debug logging — silent by default. */
@@ -152,6 +168,8 @@ declare class Context {
      */
     deviceId: string;
     readonly userAgent: string;
+    /** Signing material for `SIGNED_PATHS` — absent for sessions saved before 0.5.0 (sends then go unsigned). */
+    readonly ticketGuard?: TicketGuard;
     ownId: string;
     private seq;
     constructor(creds: Credentials, options?: TikTokOptions);
@@ -166,7 +184,8 @@ declare class Context {
     buildRequest(cmd: number, bodyField: number, body: Buffer): Buffer;
     /**
      * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
-     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 09/11/2026).
+     * NO X-Gnarly/X-Bogus/msToken signature needed. `message/send` additionally needs the ticket-guard headers
+     * (enforced 12/11/2026) — added from `ticketGuard` when present.
      */
     im(path: string, cmd: number, body: Buffer, bodyField?: number): Promise<Msg>;
 }
@@ -230,9 +249,11 @@ declare class API {
         name: string;
         value: string;
     }[];
+    /** Non-cookie session state to save alongside the cookies (pass back into `login`). */
     getContext(): {
         deviceId: string;
         userAgent: string;
+        ticketGuard?: TicketGuard;
     };
     /** Whether the session is still alive — call periodically to detect expiry early. */
     isAlive(): Promise<boolean>;
@@ -307,7 +328,12 @@ declare class TikTokError extends Error {
 }
 type TikTokErrorCode = 
 /** Cookie is no longer logged in — a new session is required. */
-'SESSION_EXPIRED' | 'HTTP_ERROR'
+'SESSION_EXPIRED'
+/**
+ * TikTok's gateway rejects this session for the command (JSON `status_code: 7` instead of protobuf). Seen on
+ * `message/send` while reads keep working — log in again to get a fresh session.
+ */
+ | 'SESSION_BLOCKED' | 'HTTP_ERROR'
 /** IM returned a non-zero `status_code`. */
  | 'IM_ERROR' | 'UPLOAD_FAILED' | 'DOWNLOAD_FAILED' | 'BAD_RESPONSE'
 /** QR login failed (Chrome failed to launch, QR expired, no cookie found…). */
@@ -366,4 +392,4 @@ declare function loginQR(opts: QrLoginOptions): Promise<Credentials>;
 declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
 
 export { API, Listener, MANUAL_CLOSE, MessageType, TikTok, TikTokError, findChrome, loginQR };
-export type { ConversationPage, ConversationRef, CookieInput, Credentials, ImageInput, ListenerEvents, MessagePage, QrLoginEvent, QrLoginOptions, SendResult, TikTokAccount, TikTokConversation, TikTokErrorCode, TikTokImage, TikTokMessage, TikTokOptions, TikTokReaction, TikTokSticker, TikTokUser };
+export type { ConversationPage, ConversationRef, CookieInput, Credentials, ImageInput, ListenerEvents, MessagePage, QrLoginEvent, QrLoginOptions, SendResult, TicketGuard, TikTokAccount, TikTokConversation, TikTokErrorCode, TikTokImage, TikTokMessage, TikTokOptions, TikTokReaction, TikTokSticker, TikTokUser };

package/dist/index.js

@@ -793,8 +793,9 @@ var API = class {
   getCookies() {
     return [...this.ctx.cookies].map(([name, value]) => ({ name, value }));
   }
+  /** Non-cookie session state to save alongside the cookies (pass back into `login`). */
   getContext() {
-    return { deviceId: this.ctx.deviceId, userAgent: this.ctx.userAgent };
+    return { deviceId: this.ctx.deviceId, userAgent: this.ctx.userAgent, ticketGuard: this.ctx.ticketGuard };
   }
   /** Whether the session is still alive — call periodically to detect expiry early. */
   async isAlive() {
@@ -924,6 +925,56 @@ var API = class {
   }
 };
 
+// src/protocol/ticket-guard.ts
+var import_node_crypto4 = require("crypto");
+var SIGNED_PATHS = /* @__PURE__ */ new Set(["/v1/message/send"]);
+function ticketGuardHeaders(guard, path, now = Date.now()) {
+  const timestamp = Math.floor(now / 1e3);
+  const message = `ticket=${guard.ticket}&path=${path}&timestamp=${timestamp}`;
+  const reqSign = (0, import_node_crypto4.sign)("sha256", Buffer.from(message), (0, import_node_crypto4.createPrivateKey)(guard.privateKey)).toString("base64");
+  const clientData = { ts_sign: guard.tsSign, req_content: "ticket,path,timestamp", req_sign: reqSign, timestamp };
+  return {
+    "tt-ticket-guard-client-data": Buffer.from(JSON.stringify(clientData)).toString("base64"),
+    "tt-ticket-guard-public-key": publicPoint(guard.publicKey),
+    "tt-ticket-guard-version": "2",
+    "tt-ticket-guard-web-version": "1",
+    "tt-ticket-guard-iteration-version": "0"
+  };
+}
+function publicPoint(pem) {
+  const jwk = (0, import_node_crypto4.createPublicKey)(pem).export({ format: "jwk" });
+  return Buffer.concat([
+    Buffer.from([4]),
+    Buffer.from(jwk.x ?? "", "base64url"),
+    Buffer.from(jwk.y ?? "", "base64url")
+  ]).toString("base64");
+}
+var READ_TICKET_GUARD_JS = `(async () => {
+  try {
+    const db = await new Promise((ok, ko) => { const r = indexedDB.open('secure-store'); r.onsuccess = () => ok(r.result); r.onerror = ko; });
+    if (!db.objectStoreNames.contains('cryptvalues')) return null;
+    const get = (k) => new Promise((ok) => { const q = db.transaction('cryptvalues').objectStore('cryptvalues').get(k); q.onsuccess = () => ok(q.result); q.onerror = () => ok(null); });
+    const keysRaw = await get('security-sdk/s_sdk_crypt_sdk');
+    const signRaw = await get('security-sdk/s_sdk_sign_data_key/tt_fetch');
+    if (!keysRaw || !signRaw) return null;
+    const keys = JSON.parse(JSON.parse(keysRaw).data);
+    const signData = JSON.parse(JSON.parse(signRaw).data);
+    if (!keys.ec_privateKey || !keys.ec_publicKey || !signData.ts_sign || !signData.encrypt_ticket) return null;
+    const te = new TextEncoder();
+    const base = await crypto.subtle.importKey('raw', te.encode('tt-ticket-guard-iv'), 'PBKDF2', false, ['deriveKey']);
+    const aes = await crypto.subtle.deriveKey({ name: 'PBKDF2', salt: te.encode('secure-salt'), iterations: 1000, hash: 'SHA-256' }, base, { name: 'AES-GCM', length: 128 }, false, ['decrypt']);
+    const enc = Uint8Array.from(atob(signData.encrypt_ticket), (c) => c.charCodeAt(0));
+    const ticket = new TextDecoder().decode(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: enc.slice(0, 12) }, aes, enc.slice(12)));
+    return { privateKey: keys.ec_privateKey, publicKey: keys.ec_publicKey, tsSign: signData.ts_sign, ticket };
+  } catch (e) {
+    return null;
+  }
+})()`;
+function isTicketGuard(v) {
+  const g = v;
+  return !!g && typeof g.privateKey === "string" && typeof g.publicKey === "string" && typeof g.tsSign === "string" && typeof g.ticket === "string" && g.ticket.length > 0;
+}
+
 // src/protocol/context.ts
 function normalizeCookies(input) {
   const jar = /* @__PURE__ */ new Map();
@@ -945,6 +996,7 @@ var Context = class {
     this.cookies = normalizeCookies(creds.cookies);
     this.deviceId = creds.deviceId ?? "";
     this.userAgent = creds.userAgent || DEFAULT_USER_AGENT;
+    if (isTicketGuard(creds.ticketGuard)) this.ticketGuard = creds.ticketGuard;
   }
   options;
   cookies;
@@ -954,6 +1006,8 @@ var Context = class {
    */
   deviceId;
   userAgent;
+  /** Signing material for `SIGNED_PATHS` — absent for sessions saved before 0.5.0 (sends then go unsigned). */
+  ticketGuard;
   ownId = "";
   seq = 1e4;
   cookieHeader() {
@@ -999,17 +1053,24 @@ var Context = class {
   }
   /**
    * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
-   * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 09/11/2026).
+   * NO X-Gnarly/X-Bogus/msToken signature needed. `message/send` additionally needs the ticket-guard headers
+   * (enforced 12/11/2026) — added from `ticketGuard` when present.
    */
   async im(path, cmd, body, bodyField = cmd) {
     const url = `${IM_API}${path}?aid=${AID_WEB}&version_code=1.0.0&app_name=tiktok_web&device_platform=web_pc`;
     const res = await this.fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/x-protobuf", Accept: "application/x-protobuf" },
+      headers: {
+        "Content-Type": "application/x-protobuf",
+        Accept: "application/x-protobuf",
+        ...this.ticketGuard && SIGNED_PATHS.has(path) ? ticketGuardHeaders(this.ticketGuard, path) : {}
+      },
       body: new Uint8Array(this.buildRequest(cmd, bodyField, body))
     });
     if (!res.ok) throw new TikTokError("HTTP_ERROR", `${path}: HTTP ${res.status}`, res.status);
-    const resp = Msg.tryParse(Buffer.from(await res.arrayBuffer()));
+    const raw = Buffer.from(await res.arrayBuffer());
+    if (/json/i.test(res.headers.get("content-type") ?? "")) throw gatewayError(path, raw);
+    const resp = Msg.tryParse(raw);
     if (!resp) throw new TikTokError("BAD_RESPONSE", `${path}: response is not protobuf`);
     const status = resp.num(Resp.status);
     if (status !== 0) {
@@ -1020,6 +1081,19 @@ var Context = class {
     return resp.msg(Resp.body)?.msg(cmd) ?? resp.msg(Resp.body)?.msg(bodyField) ?? Msg.parse(Buffer.alloc(0));
   }
 };
+function gatewayError(path, raw) {
+  let status;
+  try {
+    status = JSON.parse(raw.toString("utf8")).status_code;
+  } catch {
+  }
+  if (status === 7) return new TikTokError("SESSION_BLOCKED", `${path}: gateway status_code 7 \u2014 session blocked`, 7);
+  return new TikTokError(
+    "BAD_RESPONSE",
+    `${path}: gateway JSON status_code ${String(status)}`,
+    typeof status === "number" ? status : void 0
+  );
+}
 
 // src/client.ts
 var TikTok = class {
@@ -1227,6 +1301,28 @@ async function loginQR(opts) {
           return null;
         }
       };
+      const readTicketGuard = async () => {
+        const read = async () => {
+          const r = await tab.send("Runtime.evaluate", {
+            expression: READ_TICKET_GUARD_JS,
+            awaitPromise: true,
+            returnByValue: true
+          }).catch(() => null);
+          return isTicketGuard(r?.result?.value) ? r.result.value : void 0;
+        };
+        for (let i = 0; i < 8 && !done; i++) {
+          const g = await read();
+          if (g) return g;
+          await new Promise((r) => setTimeout(r, 1e3));
+        }
+        await tab.send("Page.navigate", { url: `${WEB}/messages` }).catch(() => void 0);
+        for (let i = 0; i < 20 && !done; i++) {
+          await new Promise((r) => setTimeout(r, 1e3));
+          const g = await read();
+          if (g) return g;
+        }
+        return void 0;
+      };
       const collectCookies = async () => {
         for (let i = 0; i < 30 && !done; i++) {
           const { cookies } = await tab.send(
@@ -1240,7 +1336,8 @@ async function loginQR(opts) {
             )) {
               byName.set(c.name, { name: c.name, value: c.value });
             }
-            return finish(null, { cookies: [...byName.values()], userAgent });
+            const ticketGuard = await readTicketGuard();
+            return finish(null, { cookies: [...byName.values()], userAgent, ...ticketGuard ? { ticketGuard } : {} });
           }
           await new Promise((r) => setTimeout(r, 1e3));
         }