@honeybbq/teamspeak-client 0.3.0 → 1.0.0-beta.1

package/src/handshake/license.ts

@@ -0,0 +1,208 @@
+import { hash512 } from "../crypto/identity.js";
+import { clampScalar, scalarMultFull, bytesToBigIntLE } from "../crypto/primitives.js";
+import { ed25519 } from "@noble/curves/ed25519.js";
+
+// The root key is a 33-byte Ed25519 point
+const LICENSE_ROOT_KEY = new Uint8Array([
+  0xcd, 0x0d, 0xe2, 0xae, 0xd4, 0x63, 0x45, 0x50, 0x9a, 0x7e, 0x3c, 0xfd, 0x8f, 0x68, 0xb3, 0xdc,
+  0x75, 0x55, 0xb2, 0x9d, 0xcc, 0xec, 0x73, 0xcd, 0x18, 0x75, 0x0f, 0x99, 0x38, 0x12, 0x40, 0x8a,
+]);
+
+const enum LicenseBlockType {
+  Intermediate = 0,
+  Server = 2,
+  Ts5Server = 8,
+  Ephemeral = 32,
+}
+
+interface LicenseBlock {
+  readonly key: Uint8Array; // 32-byte Ed25519 point
+  readonly hash: Uint8Array; // SHA-512 truncated to 32 bytes
+  properties: Uint8Array[];
+  issuer: string;
+  notValidBefore: Date;
+  notValidAfter: Date;
+  blockType: LicenseBlockType;
+  serverType: number;
+}
+
+export class LicenseChain {
+  readonly blocks: LicenseBlock[];
+
+  constructor(blocks: LicenseBlock[]) {
+    this.blocks = blocks;
+  }
+
+  /**
+   * Derive the session key by chaining Ed25519 point arithmetic starting from
+   * the root key through each license block.
+   */
+  deriveKey(): Uint8Array<ArrayBuffer> {
+    let round: Uint8Array<ArrayBuffer> = Uint8Array.from(LICENSE_ROOT_KEY);
+    for (const block of this.blocks) {
+      round = deriveKeyFromBlock(block, round);
+    }
+    return round;
+  }
+}
+
+/**
+ * The most blocks a license chain may have. Real chains have two or three —
+ * root-issued intermediate, server, ephemeral — and every block costs a
+ * point multiplication to derive, so a server's chain of thousands would hold
+ * the event loop for seconds.
+ */
+export const MAX_LICENSE_BLOCKS = 8;
+
+export function parseLicenses(data: Uint8Array): LicenseChain {
+  if (data.length < 1) throw new Error("license too short");
+  if (data[0] !== 1) throw new Error("unsupported license version");
+
+  let remaining = data.slice(1);
+  const blocks: LicenseBlock[] = [];
+
+  while (remaining.length > 0) {
+    if (blocks.length === MAX_LICENSE_BLOCKS) {
+      throw new Error(`license chain longer than ${MAX_LICENSE_BLOCKS} blocks`);
+    }
+    const { block, consumed } = parseLicenseBlock(remaining);
+    blocks.push(block);
+    remaining = remaining.slice(consumed);
+  }
+
+  return new LicenseChain(blocks);
+}
+
+function parseLicenseBlock(data: Uint8Array): { block: LicenseBlock; consumed: number } {
+  const MIN_BLOCK_LEN = 42;
+  if (data.length < MIN_BLOCK_LEN) throw new Error("license too short");
+  if (data[0] !== 0) throw new Error(`wrong key kind in license: ${data[0]}`);
+
+  const blockType = data[33] as LicenseBlockType;
+
+  // Timestamps are seconds since Unix epoch offset by 0x50e22700
+  const UNIX_OFFSET = 0x50e22700;
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const notValidBefore = new Date((view.getUint32(34, false) + UNIX_OFFSET) * 1000);
+  const notValidAfter = new Date((view.getUint32(38, false) + UNIX_OFFSET) * 1000);
+
+  if (notValidAfter < notValidBefore) {
+    throw new Error("license times are invalid");
+  }
+
+  const key = Uint8Array.from(data.slice(1, 33));
+
+  const { payload, payloadRead } = parseBlockPayload(blockType, data, MIN_BLOCK_LEN);
+
+  const allLen = MIN_BLOCK_LEN + payloadRead;
+  if (allLen > data.length) throw new Error("license block longer than the license");
+  const hashInput = data.slice(1, allLen);
+  const hashFull = hash512(Uint8Array.from(hashInput));
+  const hash = Uint8Array.from(hashFull.slice(0, 32));
+
+  return {
+    block: {
+      key,
+      hash,
+      properties: payload.properties,
+      issuer: payload.issuer,
+      notValidBefore,
+      notValidAfter,
+      blockType,
+      serverType: payload.serverType,
+    },
+    consumed: allLen,
+  };
+}
+
+interface BlockPayload {
+  issuer: string;
+  serverType: number;
+  properties: Uint8Array[];
+  read: number;
+}
+
+function parseBlockPayload(
+  blockType: LicenseBlockType,
+  data: Uint8Array,
+  minBlockLen: number,
+): { payload: BlockPayload; payloadRead: number } {
+  switch (blockType) {
+    case LicenseBlockType.Intermediate: {
+      const { str, read } = readNullString(data.slice(46));
+      return {
+        payload: { issuer: str, serverType: 0, properties: [], read: 5 + read },
+        payloadRead: 5 + read,
+      };
+    }
+    case LicenseBlockType.Server: {
+      const { str, read } = readNullString(data.slice(47));
+      return {
+        payload: { issuer: str, serverType: data[42] ?? 0, properties: [], read: 6 + read },
+        payloadRead: 6 + read,
+      };
+    }
+    case LicenseBlockType.Ts5Server: {
+      const propCount = data[43] !== undefined ? data[43] : 0;
+      let pos = 44;
+      const properties: Uint8Array[] = [];
+      for (let i = 0; i < propCount; i++) {
+        if (pos >= data.length) throw new Error("license too short");
+        const propLen = data[pos++]!;
+        if (pos + propLen > data.length) throw new Error("license too short");
+        properties.push(Uint8Array.from(data.slice(pos, pos + propLen)));
+        pos += propLen;
+      }
+      return {
+        payload: { issuer: "", serverType: data[42] ?? 0, properties, read: pos - minBlockLen },
+        payloadRead: pos - minBlockLen,
+      };
+    }
+    case LicenseBlockType.Ephemeral:
+      return { payload: { issuer: "", serverType: 0, properties: [], read: 0 }, payloadRead: 0 };
+    default:
+      throw new Error(`invalid license block type: ${blockType}`);
+  }
+}
+
+/**
+ * Scan for a null-terminated string and return its content and the index
+ * of the null byte (NOT including it in the count, matching Go behaviour).
+ * The parent formulas (`5 + read`, `6 + read`) already add 1 for the null.
+ */
+function readNullString(data: Uint8Array): { str: string; read: number } {
+  for (let i = 0; i < data.length; i++) {
+    if (data[i] === 0) {
+      return { str: new TextDecoder().decode(data.slice(0, i)), read: i };
+    }
+  }
+  throw new Error("non-null-terminated issuer string");
+}
+
+/**
+ * Derive the next key given a parent key and a license block.
+ * Mirrors Go's licenseBlock.deriveKey.
+ */
+function deriveKeyFromBlock(block: LicenseBlock, parent: Uint8Array): Uint8Array<ArrayBuffer> {
+  const scalarBytes = Uint8Array.from(block.hash);
+  clampScalar(scalarBytes);
+
+  // Use raw scalar WITHOUT reducing mod n — NaCl's ge_scalarmult_vartime
+  // uses the raw 256-bit scalar. Reducing mod n changes the result when
+  // the point has a small-order component (Ed25519 cofactor = 8).
+  const scalar = bytesToBigIntLE(scalarBytes);
+
+  const pub = ed25519.Point.fromBytes(block.key);
+  const negPub = pub.negate();
+
+  const par = ed25519.Point.fromBytes(parent);
+  const negPar = par.negate();
+
+  const res = scalarMultFull(negPub, scalar).add(negPar);
+  const raw = res.toBytes();
+  const final = new Uint8Array(raw.length) as Uint8Array<ArrayBuffer>;
+  final.set(raw);
+  final[31] = (final[31] !== undefined ? final[31] : 0) ^ 0x80;
+
+  return final;
+}

package/src/handshake.ts

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+import { buildCommandOrdered, buildCommand } from "@honeybbq/teamspeak-core/internal";
+import { sign, generateTemporaryKey } from "./crypto/primitives.js";
+import { identityPrivateKey } from "./crypto/identity.js";
+import { parseServerCapabilities } from "./capabilities.js";
+import { cryptoInit2 } from "./handshake/crypt-init2.js";
+import { PacketType } from "./transport/packet.js";
+import type { ClientInternals } from "./client.js";
+
+/** Handle the `clientinitiv` message (P-256 based crypto path). */
+export function handleHandshakeInitIV(
+  client: ClientInternals,
+  params: Record<string, string>,
+): void {
+  const alpha = params["alpha"] ?? "";
+  const beta = params["beta"] ?? "";
+  const omega = params["omega"] ?? "";
+
+  client.crypt.initCrypto(alpha, beta, omega);
+  client.logger.info("crypto initialized (P-256 path), sending clientinit");
+  sendClientInit(client);
+}
+
+/** Handle the `initivexpand2` message (Ed25519 / TS3 crypto path). */
+export function handleHandshakeExpand2(
+  client: ClientInternals,
+  params: Record<string, string>,
+): void {
+  client.logger.info("received initivexpand2");
+  client.handler.receivedFinalInitAck();
+
+  const license = params["l"] ?? "";
+  const omega = params["omega"] ?? "";
+  const proof = params["proof"] ?? "";
+  const beta = params["beta"] ?? "";
+
+  const privateKey = sendClientEkPacket(client, beta);
+  cryptoInit2(client.crypt, license, omega, proof, beta, privateKey);
+  sendClientInit(client);
+}
+
+/** Handle `initserver` — marks the client as connected. */
+export function handleInitServer(client: ClientInternals, params: Record<string, string>): void {
+  const idStr = params["aclid"] ?? params["clid"] ?? "";
+  const clid = idStr ? parseInt(idStr, 10) : 0;
+
+  if (clid > 0) {
+    client.clid = clid;
+    client.handler.setClientID(clid);
+  }
+
+  // initserver is the only place the server names itself, and it determines how
+  // the server hashes our public key into client_unique_identifier: SHA-1 on
+  // TS3, SHA-256 on TS6. Recording the whole capability set here keeps callers
+  // from re-deriving it, or assuming one server generation.
+  client.capabilities = parseServerCapabilities(params);
+
+  client.logger.info("connected to server", { selfId: client.clid });
+  client.markConnected();
+
+  // Inform the server about mute state
+  setImmediate(() => {
+    const updateCmd = buildCommand("clientupdate", {
+      client_input_muted: "0",
+      client_output_muted: "0",
+    });
+    client.execNoWait(updateCmd).catch(() => {});
+  });
+}
+
+function sendClientEkPacket(client: ClientInternals, beta: string): Uint8Array {
+  const [publicKey, privateKey] = generateTemporaryKey();
+  const ekBase64 = Buffer.from(publicKey).toString("base64");
+  const clientProof = buildClientEkProof(client, publicKey, beta);
+
+  const clientEk = buildCommandOrdered("clientek", [
+    ["ek", ekBase64],
+    ["proof", clientProof],
+  ]);
+  client.handler.sendPacket(PacketType.Command, Buffer.from(clientEk), 0);
+  return privateKey;
+}
+
+function buildClientEkProof(client: ClientInternals, publicKey: Uint8Array, beta: string): string {
+  const betaBytes = Buffer.from(beta, "base64");
+  const toSign = new Uint8Array(86);
+  toSign.set(publicKey.slice(0, 32));
+  toSign.set(betaBytes.slice(0, Math.min(54, betaBytes.length)), 32);
+  const sig = sign(identityPrivateKey(client.crypt.identity), toSign);
+  return Buffer.from(sig).toString("base64");
+}
+
+/**
+ * Encode a password field for the command protocol.
+ *
+ * TeamSpeak expects password fields as base64(sha1(password)) — server and
+ * channel passwords during the handshake, the `clientmove` channel password,
+ * and the `cpw` field of the file transfer commands. Sending the plain text
+ * instead makes the server reject correct passwords with error 781.
+ */
+export function prepareClientPassword(password: string): string {
+  if (password === "") return "";
+  return createHash("sha1").update(password).digest().toString("base64");
+}
+
+export function sendClientInit(client: ClientInternals): void {
+  const cmd = buildClientInitCommand(client);
+  client.handler.sendPacket(PacketType.Command, Buffer.from(cmd), 0);
+}
+
+function buildClientInitCommand(client: ClientInternals): string {
+  const pubKeyBase64 = client.crypt.identity.publicKey();
+  const initOptions = client.initOptions;
+  // HWID should match TS3 client UID format: base64(SHA1(publicKey()))
+  const hwid = createHash("sha1").update(pubKeyBase64).digest().toString("base64");
+
+  return buildCommandOrdered("clientinit", [
+    ["client_nickname", client.nickname],
+    ["client_version", "3.?.? [Build: 5680278000]"],
+    ["client_platform", "Windows"],
+    ["client_input_hardware", "1"],
+    ["client_output_hardware", "1"],
+    ["client_default_channel", initOptions.defaultChannel],
+    ["client_default_channel_password", initOptions.defaultChannelPasswordHash],
+    ["client_server_password", initOptions.serverPasswordHash],
+    ["client_meta_data", ""],
+    [
+      "client_version_sign",
+      "DX5NIYLvfJEUjuIbCidnoeozxIDRRkpq3I9vVMBmE9L2qnekOoBzSenkzsg2lC9CMv8K5hkEzhr2TYUYSwUXCg==",
+    ],
+    ["client_key_offset", String(client.crypt.identity.offset)],
+    ["client_nickname_phonetic", ""],
+    ["client_default_token", ""],
+    ["hwid", hwid],
+  ]);
+}

package/src/helpers.ts

@@ -0,0 +1,10 @@
+/**
+ * Reports whether `actual` equals `expected` or equals `expected` followed by
+ * only digits — the pattern TeamSpeak uses when a nickname is already taken.
+ */
+export function isAutoNicknameMatch(expected: string, actual: string): boolean {
+  if (actual === expected) return true;
+  if (!actual.startsWith(expected)) return false;
+  const suffix = actual.slice(expected.length);
+  return /^\d+$/.test(suffix);
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * A clean-room TeamSpeak client: it connects over the voice protocol, the way
+ * the TeamSpeak application does.
+ *
+ * Everything in `@honeybbq/teamspeak-core` — the typed commands, ids, errors —
+ * is re-exported here, so this is the only package a voice client needs.
+ */
+
+export * from "@honeybbq/teamspeak-core";
+
+// The client
+export { Client, ClientStatus } from "./client.js";
+
+export type {
+  TextMessageEvent,
+  ClientMovedEvent,
+  ClientLeaveEvent,
+  KickedEvent,
+  NotificationEvent,
+  ClientEnterEvent,
+  PokeEvent,
+  VoiceDataEvent,
+  EventMap,
+  EventMiddleware,
+  Listener,
+  ServerEvent,
+  ServerEventName,
+  Unsubscribe,
+  AddrResolver,
+  ClientOptions,
+  ResolvedAddr,
+  DatagramSocket,
+  SocketFactory,
+  FileTransferSocketFactory,
+} from "./types.js";
+
+export {
+  AlreadyConnectedError,
+  FileTransferError,
+  CryptoInitError,
+  InvalidAddressError,
+  InvalidIdentityError,
+  RemovedError,
+  ConnectionTimeoutError,
+} from "./errors.js";
+
+// Commands only the voice protocol has.
+export * from "./api/voice.js";
+
+// File transfer data
+export { dialFileTransfer, uploadFileData, downloadFileData } from "./transfer.js";
+export type { FileTransferOptions } from "./transfer.js";
+
+// Server capabilities, read from the handshake
+export { unknownServerCapabilities } from "./capabilities.js";
+export type { ServerCapabilities, ServerFamily } from "./capabilities.js";
+
+// Tracing points for diagnostics_channel subscribers
+export { commandChannel, packetChannel } from "./diagnostics.js";
+export type { CommandTrace, PacketTrace } from "./diagnostics.js";
+
+// Reconnection policy
+export { backoffDelay, defaultShouldRetry, defaultBackoffPolicy } from "./reconnect.js";
+export type { ReconnectOptions, BackoffPolicy } from "./reconnect.js";
+
+// Identity
+export {
+  Identity,
+  parseIdentity,
+  generateIdentity,
+  generateIdentitySync,
+  uidFromPublicKey,
+} from "./crypto/index.js";
+export type { UIDAlgorithm } from "./crypto/index.js";

package/src/notifications.ts

@@ -0,0 +1,136 @@
+import type { Command } from "@honeybbq/teamspeak-core/internal";
+import type {
+  ClientEnterEvent,
+  ClientLeaveEvent,
+  ClientMovedEvent,
+  TextMessageEvent,
+  PokeEvent,
+} from "./types.js";
+import {
+  parseClient,
+  parseUint64,
+  parseUint16,
+  parseInt10,
+} from "@honeybbq/teamspeak-core/internal";
+import { asChannelID, asClientID, asUID } from "@honeybbq/teamspeak-core";
+
+export type NotificationResult =
+  | { kind: "clientEnter"; info: ClientEnterEvent }
+  | { kind: "clientLeave"; event: ClientLeaveEvent; isSelf: boolean }
+  | { kind: "clientMoved"; event: ClientMovedEvent; reasonMessage: string }
+  | { kind: "textMessage"; message: TextMessageEvent }
+  | { kind: "poked"; event: PokeEvent }
+  | { kind: "unknown" };
+
+export function handleNotification(
+  cmd: Command,
+  selfCLID: number,
+  clients: Map<number, ClientEnterEvent>,
+  _nickname: string,
+): NotificationResult {
+  switch (cmd.name) {
+    case "notifycliententerview":
+      return handleClientEnterView(cmd, clients);
+    case "notifyclientleftview":
+      return handleClientLeftView(cmd, selfCLID, clients);
+    case "notifyclientmoved":
+      return handleClientMoved(cmd, clients);
+    case "notifytextmessage":
+      return handleTextMessage(cmd, clients);
+    case "notifyclientpoke":
+      return handleClientPoked(cmd);
+    default:
+      return { kind: "unknown" };
+  }
+}
+
+function handleClientEnterView(
+  cmd: Command,
+  clients: Map<number, ClientEnterEvent>,
+): NotificationResult {
+  const info = parseClient(cmd.params);
+  // No client has id 0: a row without one describes nobody.
+  if (info.id === 0) return { kind: "unknown" };
+  clients.set(info.id, info);
+  return { kind: "clientEnter", info };
+}
+
+function handleClientLeftView(
+  cmd: Command,
+  selfCLID: number,
+  clients: Map<number, ClientEnterEvent>,
+): NotificationResult {
+  const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
+  if (clid === 0) return { kind: "unknown" };
+  const isSelf = clid === selfCLID;
+  clients.delete(clid);
+  return {
+    kind: "clientLeave",
+    event: {
+      clientID: clid,
+      reason: parseInt10(cmd.params["reasonid"] ?? ""),
+      reasonMessage: cmd.params["reasonmsg"] ?? "",
+      invokerID: asClientID(parseUint16(cmd.params["invokerid"] ?? "")),
+      invokerName: cmd.params["invokername"] ?? "",
+      invokerUID: asUID(cmd.params["invokeruid"] ?? ""),
+    },
+    isSelf,
+  };
+}
+
+function handleClientMoved(
+  cmd: Command,
+  clients: Map<number, ClientEnterEvent>,
+): NotificationResult {
+  const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
+  const ctid = asChannelID(parseUint64(cmd.params["ctid"] ?? ""));
+  if (clid === 0) return { kind: "unknown" };
+
+  const existing = clients.get(clid);
+  if (existing) clients.set(clid, { ...existing, channelID: ctid });
+
+  return {
+    kind: "clientMoved",
+    event: {
+      clientID: clid,
+      targetChannelID: ctid,
+      reason: parseInt10(cmd.params["reasonid"] ?? ""),
+      invokerID: asClientID(parseUint16(cmd.params["invokerid"] ?? "")),
+      invokerName: cmd.params["invokername"] ?? "",
+      invokerUID: asUID(cmd.params["invokeruid"] ?? ""),
+    },
+    reasonMessage: cmd.params["reasonmsg"] ?? "",
+  };
+}
+
+function handleTextMessage(
+  cmd: Command,
+  clients: Map<number, ClientEnterEvent>,
+): NotificationResult {
+  const invokerID = asClientID(parseUint16(cmd.params["invokerid"] ?? ""));
+  const invokerInfo = clients.get(invokerID);
+
+  const message: TextMessageEvent = {
+    targetMode: parseInt10(cmd.params["targetmode"] ?? ""),
+    targetID: asClientID(parseUint16(cmd.params["target"] ?? "")),
+    invokerID,
+    invokerName: cmd.params["invokername"] ?? "",
+    invokerUID: asUID(cmd.params["invokeruid"] ?? invokerInfo?.uid ?? ""),
+    message: cmd.params["msg"] ?? "",
+    invokerGroups: invokerInfo?.serverGroups ?? [],
+  };
+
+  return { kind: "textMessage", message };
+}
+
+function handleClientPoked(cmd: Command): NotificationResult {
+  return {
+    kind: "poked",
+    event: {
+      invokerID: asClientID(parseUint16(cmd.params["invokerid"] ?? "")),
+      invokerName: cmd.params["invokername"] ?? "",
+      invokerUID: asUID(cmd.params["invokeruid"] ?? ""),
+      message: cmd.params["msg"] ?? "",
+    },
+  };
+}