@honeybbq/teamspeak-client 0.3.1 → 1.0.0-beta.2

package/src/handshake/license.fuzz.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import fc from "fast-check";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { MAX_LICENSE_BLOCKS, parseLicenses } from "./license.js";
+
+// The license chain is the server's, sent before the handshake has proved
+// anything: any bytes can arrive in it. Reading it must end in a chain of a
+// bounded number of blocks or in an Error, and deriving a key from a chain
+// that read must give a key or an Error, never anything else.
+
+const BASE_POINT = ed25519.Point.BASE.toBytes();
+
+const key = fc.oneof(fc.constant(BASE_POINT), fc.uint8Array({ minLength: 32, maxLength: 32 }));
+const times = fc
+  .tuple(fc.nat(0xffff_ffff), fc.nat(0xffff_ffff))
+  .map(([a, b]): [number, number] => [Math.min(a, b), Math.max(a, b)]);
+const issuer = fc.uint8Array({ maxLength: 12 }).map((bytes) => bytes.map((b) => b || 1));
+
+/** One block, laid out as the parser reads its type, with a length that fits it. */
+const block = fc
+  .tuple(
+    key,
+    times,
+    fc.constantFrom(0, 2, 8, 32, 7),
+    fc.uint8Array({ minLength: 6, maxLength: 6 }),
+    issuer,
+    fc.array(fc.uint8Array({ maxLength: 6 }), { maxLength: 4 }),
+  )
+  .map(([point, [before, after], type, fixed, name, properties]) => {
+    const head = new Uint8Array(42);
+    head.set(point, 1);
+    head[33] = type;
+    new DataView(head.buffer).setUint32(34, before, false);
+    new DataView(head.buffer).setUint32(38, after, false);
+    const text = Uint8Array.from([...name, 0]);
+    switch (type) {
+      case 0:
+        return Uint8Array.from([...head, ...fixed.subarray(0, 4), ...text]);
+      case 2:
+        return Uint8Array.from([...head, ...fixed.subarray(0, 5), ...text]);
+      case 8:
+        return Uint8Array.from([
+          ...head,
+          fixed[0]!,
+          properties.length,
+          ...properties.flatMap((p) => [p.length, ...p]),
+        ]);
+      default:
+        return head;
+    }
+  });
+
+const chain = fc
+  .tuple(fc.constantFrom(1, 1, 1, 0, 2), fc.array(block, { maxLength: MAX_LICENSE_BLOCKS + 1 }))
+  .map(([version, blocks]) => Uint8Array.from([version, ...blocks.flatMap((b) => [...b])]));
+
+/** A well-formed chain with some bytes changed or cut off. */
+const damaged = fc
+  .tuple(chain, fc.array(fc.tuple(fc.nat(400), fc.nat(255)), { maxLength: 4 }), fc.nat(400))
+  .map(([data, edits, cut]) => {
+    const out = Uint8Array.from(data);
+    for (const [at, byte] of edits) if (at < out.length) out[at] = byte;
+    return cut < out.length && cut % 3 === 0 ? out.subarray(0, cut) : out;
+  });
+
+describe("a license chain from the server", () => {
+  it("reads to a bounded chain or an Error, and derives a key or an Error", () => {
+    fc.assert(
+      fc.property(fc.oneof(chain, damaged, fc.uint8Array({ maxLength: 200 })), (data) => {
+        let parsed;
+        try {
+          parsed = parseLicenses(data);
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          return;
+        }
+        expect(parsed.blocks.length).toBeLessThanOrEqual(MAX_LICENSE_BLOCKS);
+        try {
+          expect(parsed.deriveKey()).toHaveLength(32);
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+        }
+      }),
+      { numRuns: 300 },
+    );
+  });
+});

package/src/handshake/license.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { MAX_LICENSE_BLOCKS, parseLicenses } from "./license.js";
+
+const BASE_POINT = ed25519.Point.BASE.toBytes();
+const EPHEMERAL_BLOCK_LEN = 42;
+
+/** A version byte and `count` ephemeral blocks, the smallest a block can be. */
+function ephemeralChain(count: number): Uint8Array {
+  const data = new Uint8Array(1 + count * EPHEMERAL_BLOCK_LEN);
+  data[0] = 1;
+  for (let i = 0; i < count; i++) {
+    const offset = 1 + i * EPHEMERAL_BLOCK_LEN;
+    data[offset] = 0; // key kind
+    data.set(BASE_POINT, offset + 1);
+    data[offset + 33] = 32; // ephemeral
+  }
+  return data;
+}
+
+describe("parseLicenses", () => {
+  it(`takes a chain of up to ${MAX_LICENSE_BLOCKS} blocks`, () => {
+    const chain = parseLicenses(ephemeralChain(MAX_LICENSE_BLOCKS));
+    expect(chain.blocks).toHaveLength(MAX_LICENSE_BLOCKS);
+    expect(chain.deriveKey()).toHaveLength(32);
+  });
+
+  // Every block costs a point multiplication to derive: a thousand of them
+  // held the event loop for seconds.
+  it("rejects a longer chain before deriving anything", () => {
+    expect(() => parseLicenses(ephemeralChain(MAX_LICENSE_BLOCKS + 1))).toThrow(/longer than/);
+    expect(() => parseLicenses(ephemeralChain(1000))).toThrow(/longer than/);
+  });
+
+  it("rejects a block that declares more than the license holds", () => {
+    // A TS5 server block whose property count, at byte 43, is cut off.
+    const ts5 = ephemeralChain(1);
+    ts5[34] = 8;
+    expect(() => parseLicenses(ts5)).toThrow(/longer than the license/);
+
+    // One whose property claims 200 bytes when 1 follows.
+    const property = new Uint8Array(1 + 42 + 4);
+    property.set(ephemeralChain(1));
+    property[34] = 8;
+    property[44] = 1; // one property
+    property[45] = 200;
+    expect(() => parseLicenses(property)).toThrow(/too short/);
+  });
+});

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,137 @@
+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.handler.receivedFinalInitAck();
+  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";