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

package/src/commands.ts

@@ -0,0 +1,193 @@
+import { parseCommand } from "@honeybbq/teamspeak-core/internal";
+import { ServerError } from "@honeybbq/teamspeak-core";
+import { parseErrorCode } from "@honeybbq/teamspeak-core/internal";
+
+import type { ResponseSpec } from "@honeybbq/teamspeak-core/internal";
+
+export interface CommandResult {
+  err: Error | null;
+  data: Record<string, string>[];
+}
+
+/** A row waiting for the `error` that says which command it answered. */
+interface BufferedRow {
+  /** The notification that carried it, or "" for a nameless data row. */
+  readonly source: string;
+  readonly params: Record<string, string>;
+}
+
+interface PendingCommand {
+  readonly resolve: (result: CommandResult) => void;
+  readonly spec: ResponseSpec | undefined;
+  /** The request's value for `spec.correlated.key`, when there is one. */
+  readonly correlation: string | undefined;
+  /** Correlated answers that arrived before the command's own `error`. */
+  readonly correlated: Record<string, string>[];
+  /** The command's `error` result, held while its correlated answer is due. */
+  settled?: CommandResult;
+}
+
+/**
+ * Matches the server's answers to the commands that asked for them.
+ *
+ * The server handles one client's commands in order and closes each answer
+ * with `error … return_code=N`, so every row seen since the previous `error`
+ * belongs to command N. Rows are therefore held, tagged with where they came
+ * from, until that `error` says whose they are — attributing them on arrival
+ * would mean guessing which in-flight command the server is answering, and a
+ * command can be registered here well before it is sent (it first waits on the
+ * throttle and the middleware chain).
+ *
+ * A nameless row always belongs to the command. A notification row belongs to
+ * it only if the command declared that notification as its answer (see
+ * command/responses.ts): the same `notifyclientmoved` that answers nothing can
+ * arrive between any two commands.
+ *
+ * The welcome sequence is the exception. The server pushes channellist,
+ * channelgrouplist and the rest unprompted right after the handshake, before
+ * `channellistfinished`; without the gate they would land in the first
+ * command's answer as duplicate rows and a phantom cid=0.
+ */
+export class CommandTracker {
+  readonly #pending = new Map<number, PendingCommand>();
+  readonly #ownClientID: () => number;
+  #nextRC = 0;
+  #buffer: BufferedRow[] = [];
+  #welcomeComplete = false;
+
+  /** @param ownClientID the client's clid, for answers filtered by invoker. */
+  constructor(ownClientID: () => number = () => 0) {
+    this.#ownClientID = ownClientID;
+  }
+
+  register(
+    spec?: ResponseSpec,
+    correlation?: string,
+  ): [rc: number, promise: Promise<CommandResult>] {
+    this.#nextRC++;
+    const rc = this.#nextRC;
+    const promise = new Promise<CommandResult>((resolve) => {
+      this.#pending.set(rc, { resolve, spec, correlation, correlated: [] });
+    });
+    return [rc, promise];
+  }
+
+  unregister(rc: number): void {
+    this.#pending.delete(rc);
+  }
+
+  /** Marks the end of the welcome sequence and drops what it left behind. */
+  signalWelcomeComplete(): void {
+    this.#welcomeComplete = true;
+    this.#buffer = [];
+  }
+
+  /** Whether some in-flight command declared `name` as its answer. */
+  expects(name: string): boolean {
+    for (const p of this.#pending.values()) {
+      if (p.spec?.notifications?.includes(name)) return true;
+      if (p.spec?.correlated?.notifications.includes(name)) return true;
+    }
+    return false;
+  }
+
+  /** Hold a row until the next `error` says which command it answered. */
+  buffer(params: Record<string, string>, source = ""): void {
+    if (!this.#welcomeComplete) return;
+    if (this.#pending.size === 0) return;
+    this.#buffer.push({ source, params });
+  }
+
+  /**
+   * Offer a notification to commands answered after their `error`.
+   *
+   * Matching is on the echoed request field, so it does not matter whether the
+   * notification beats the `error` or follows it.
+   */
+  offerCorrelated(name: string, params: Record<string, string>): void {
+    for (const [rc, p] of this.#pending) {
+      const c = p.spec?.correlated;
+      if (!c || p.correlation === undefined || !c.notifications.includes(name)) continue;
+      if (params[c.key] !== p.correlation) continue;
+
+      if (name === c.failure && (params["status"] ?? "0") !== "0") {
+        const err = new ServerError(parseErrorCode(params["status"]), params["msg"] ?? "", {
+          extraMessage: params["extra_msg"] || undefined,
+        });
+        this.#settle(rc, p, { err, data: [] });
+        return;
+      }
+      p.correlated.push(params);
+      if (p.settled) this.#settle(rc, p, { err: null, data: [...p.settled.data, ...p.correlated] });
+      return;
+    }
+  }
+
+  resolve(rc: number, err: Error | null): void {
+    const rows = this.#buffer;
+    this.#buffer = [];
+    const p = this.#pending.get(rc);
+    if (!p) return;
+
+    const data = rows.filter((row) => this.#answers(p, row)).map((row) => row.params);
+    if (err) {
+      this.#settle(rc, p, { err, data });
+      return;
+    }
+    // Answered after the error: hold the result until the answer arrives, or
+    // the caller's timeout gives up on it.
+    if (p.spec?.correlated && p.correlation !== undefined && p.correlated.length === 0) {
+      p.settled = { err: null, data };
+      return;
+    }
+    this.#settle(rc, p, { err: null, data: [...data, ...p.correlated] });
+  }
+
+  discardBuffer(): void {
+    this.#buffer = [];
+  }
+
+  /**
+   * Forget every command and fail it with `err`.
+   *
+   * Dropping them silently would leave each caller waiting out its full
+   * timeout for an answer that can no longer come.
+   */
+  reset(err: Error): void {
+    const pending = [...this.#pending.values()];
+    this.#pending.clear();
+    for (const p of pending) p.resolve({ err, data: [] });
+    this.#buffer = [];
+    this.#welcomeComplete = false;
+    this.#nextRC = 0;
+  }
+
+  #answers(p: PendingCommand, row: BufferedRow): boolean {
+    if (row.source === "") return true;
+    if (!p.spec?.notifications?.includes(row.source)) return false;
+    if (!p.spec.ownRowsOnly) return true;
+    return row.params["invokerid"] === String(this.#ownClientID());
+  }
+
+  #settle(rc: number, p: PendingCommand, result: CommandResult): void {
+    this.#pending.delete(rc);
+    p.resolve(result);
+  }
+}
+
+/**
+ * Append the tracker's return_code to a command.
+ *
+ * The return_code belongs to the tracker: it is how an answer finds its
+ * command, so a caller-supplied one would detach the command from its answer.
+ * Checked as a parameter rather than as text, because a message body that
+ * merely contains "return_code=" used to suppress the real one and time the
+ * command out.
+ */
+export function appendReturnCode(cmd: string, rc: number): string {
+  const params = parseCommand(cmd)?.params ?? {};
+  if (Object.hasOwn(params, "return_code")) {
+    throw new TypeError("commands must not carry their own return_code; the client assigns it");
+  }
+  return `${cmd} return_code=${rc}`;
+}

package/src/crypto/crypt-ops.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-exports the key/nonce derivation and encrypt/decrypt from Crypt.
+ * This file exists to mirror the Go crypt_ops.go structure.
+ */
+export type { KeyNonce } from "./crypt.js";
+export { Crypt } from "./crypt.js";

package/src/crypto/crypt.ts

@@ -0,0 +1,274 @@
+import { createHash, createECDH, randomBytes } from "node:crypto";
+import { CryptoInitError, FakeSignatureMismatchError } from "../errors.js";
+import type { Identity } from "./identity.js";
+import { identityPrivateKey, importPublicKey } from "./identity.js";
+import { EAX } from "./eax.js";
+
+const FAKE_SIGNATURE_SIZE = 8;
+const IV_ALPHA_SIZE = 10;
+const INIT1_PACKET_TYPE = 8;
+const PACKET_TYPE_MASK = 0x0f;
+
+const INIT1_MAC = Buffer.from("TS3INIT1");
+
+/**
+ * The most squarings the Init1 puzzle may ask for. TS3 3.13 and TS6 6.0 both
+ * ask for 10000; a level far beyond that is a server trying to pin the event
+ * loop, since the squarings run synchronously.
+ */
+export const MAX_RSA_CHALLENGE_LEVEL: number = 100_000;
+
+export interface KeyNonce {
+  key: Uint8Array;
+  nonce: Uint8Array;
+  gen: number;
+}
+
+/** Precomputed dummy key/nonce matching the TS3 client pre-crypto placeholder. */
+const DUMMY_KEY = Buffer.from("c:\\windows\\syste");
+const DUMMY_NONCE = Buffer.from("m\\firewall32.cpl");
+
+/**
+ * A connection's encryption state. The session material — the IV the keys
+ * derive from — lives in private fields, so it shows in no `util.inspect()`
+ * or `JSON.stringify()` of anything holding a Crypt.
+ */
+export class Crypt {
+  readonly identity: Identity;
+
+  #ivStruct: Uint8Array = new Uint8Array(0);
+  #fakeSignature: Uint8Array = new Uint8Array(FAKE_SIGNATURE_SIZE);
+  #alpha: Uint8Array = new Uint8Array(0);
+  #cryptoInitComplete = false;
+
+  readonly #cachedKeys = new Map<bigint, KeyNonce>();
+
+  constructor(identity: Identity) {
+    this.identity = identity;
+  }
+
+  /** Whether the session keys are set up; until then packets use the dummy key. */
+  get cryptoInitComplete(): boolean {
+    return this.#cryptoInitComplete;
+  }
+
+  /** The signature unencrypted packets carry: zeros until crypto init completes. */
+  get fakeSignature(): Uint8Array {
+    return this.#fakeSignature;
+  }
+
+  /** The client's random contribution to the IV, sent in clientinitiv; empty before. */
+  get alpha(): Uint8Array {
+    return this.#alpha;
+  }
+
+  /** Choose the client's random contribution to the IV, and return it. */
+  newAlpha(): Uint8Array {
+    this.#alpha = new Uint8Array(randomBytes(IV_ALPHA_SIZE));
+    return this.#alpha;
+  }
+
+  solveRsaChallenge(data: Uint8Array, offset: number, level: number): Uint8Array {
+    if (!Number.isInteger(level) || level < 0 || level > MAX_RSA_CHALLENGE_LEVEL) {
+      throw new CryptoInitError(`RSA challenge level ${level} out of range`);
+    }
+
+    const xBytes = data.slice(offset, offset + 64);
+    const nBytes = data.slice(offset + 64, offset + 128);
+
+    let y = bytesToBigInt(xBytes);
+    const n = bytesToBigInt(nBytes);
+    if (n === 0n) throw new CryptoInitError("RSA challenge modulus is zero");
+
+    for (let i = 0; i < level; i++) {
+      y = (y * y) % n;
+    }
+
+    return bigIntToBytes(y, 64);
+  }
+
+  initCrypto(alpha: string, beta: string, omega: string): void {
+    const alphaBytes = Buffer.from(alpha, "base64");
+    const betaBytes = Buffer.from(beta, "base64");
+    const omegaBytes = Buffer.from(omega, "base64");
+
+    let sharedSecret: Uint8Array;
+    try {
+      sharedSecret = this.#getSharedSecret(importPublicKey(omegaBytes));
+    } catch (error) {
+      throw new CryptoInitError("the server's public key is invalid", { cause: error });
+    }
+
+    this.setSharedSecret(alphaBytes, betaBytes, sharedSecret);
+  }
+
+  setSharedSecret(alpha: Uint8Array, beta: Uint8Array, sharedKey: Uint8Array): void {
+    this.#ivStruct = new Uint8Array(IV_ALPHA_SIZE + beta.length);
+    for (let i = 0; i < IV_ALPHA_SIZE; i++) {
+      const a = sharedKey[i];
+      const b = alpha[i];
+      this.#ivStruct[i] = ((a !== undefined ? a : 0) ^ (b !== undefined ? b : 0)) & 0xff;
+    }
+    for (let i = 0; i < beta.length; i++) {
+      const a = sharedKey[IV_ALPHA_SIZE + i];
+      const b = beta[i];
+      this.#ivStruct[IV_ALPHA_SIZE + i] =
+        ((a !== undefined ? a : 0) ^ (b !== undefined ? b : 0)) & 0xff;
+    }
+
+    // Keys derive from the IV: any cached before it changed belong to another
+    // IV, the empty one before crypto init in particular, which is public.
+    this.#cachedKeys.clear();
+
+    const digest = createHash("sha1").update(this.#ivStruct).digest();
+    this.#fakeSignature = new Uint8Array(digest.buffer, digest.byteOffset, FAKE_SIGNATURE_SIZE);
+    this.#cryptoInitComplete = true;
+  }
+
+  getKeyNonce(
+    fromServer: boolean,
+    packetID: number,
+    generationID: number,
+    packetType: number,
+    dummy: boolean,
+  ): [key: Uint8Array, nonce: Uint8Array] {
+    if (dummy) {
+      return [Uint8Array.from(DUMMY_KEY), Uint8Array.from(DUMMY_NONCE)];
+    }
+    // Before crypto init there is no IV, and a key derived from the empty one
+    // is a key anyone can compute.
+    if (!this.#cryptoInitComplete) {
+      throw new CryptoInitError("no session key before crypto init completes");
+    }
+
+    const cacheKey = makeCacheKey(fromServer, packetType, generationID);
+    let kn = this.#cachedKeys.get(cacheKey);
+
+    if (kn === undefined) {
+      const tmpToHash = new Uint8Array(6 + this.#ivStruct.length);
+      tmpToHash[0] = fromServer ? 0x30 : 0x31;
+      tmpToHash[1] = packetType & PACKET_TYPE_MASK;
+      new DataView(tmpToHash.buffer).setUint32(2, generationID, false);
+      tmpToHash.set(this.#ivStruct, 6);
+
+      const hash = createHash("sha256").update(tmpToHash).digest();
+      kn = {
+        key: Uint8Array.from(hash.slice(0, 16)),
+        nonce: Uint8Array.from(hash.slice(16, 32)),
+        gen: generationID,
+      };
+      this.#cachedKeys.set(cacheKey, kn);
+    }
+
+    const key = Uint8Array.from(kn.key);
+    key[0] = (key[0] !== undefined ? key[0] : 0) ^ ((packetID >> 8) & 0xff);
+    key[1] = (key[1] !== undefined ? key[1] : 0) ^ (packetID & 0xff);
+
+    return [key, kn.nonce];
+  }
+
+  encrypt(
+    packetType: number,
+    packetID: number,
+    generationID: number,
+    header: Uint8Array,
+    plaintext: Uint8Array,
+    dummy: boolean,
+    unencrypted: boolean,
+  ): [ciphertext: Uint8Array, mac: Uint8Array] {
+    if (packetType === INIT1_PACKET_TYPE) {
+      return [plaintext, INIT1_MAC];
+    }
+    if (unencrypted) {
+      return [plaintext, this.#fakeSignature];
+    }
+
+    const [key, nonce] = this.getKeyNonce(false, packetID, generationID, packetType, dummy);
+    const eax = new EAX(key);
+    return eax.encrypt(nonce, header, plaintext);
+  }
+
+  decrypt(
+    packetType: number,
+    packetID: number,
+    generationID: number,
+    header: Uint8Array,
+    ciphertext: Uint8Array,
+    tag: Uint8Array,
+    dummy: boolean,
+    unencrypted: boolean,
+  ): Uint8Array {
+    if (packetType === INIT1_PACKET_TYPE) {
+      return ciphertext;
+    }
+    if (unencrypted) {
+      const fsSub = tag.slice(0, FAKE_SIGNATURE_SIZE);
+      if (!Buffer.from(fsSub).equals(Buffer.from(this.#fakeSignature))) {
+        throw new FakeSignatureMismatchError();
+      }
+      return ciphertext;
+    }
+
+    const [key, nonce] = this.getKeyNonce(true, packetID, generationID, packetType, dummy);
+    const eax = new EAX(key);
+    return eax.decrypt(nonce, header, ciphertext, tag);
+  }
+
+  #getSharedSecret(serverPubKey: import("node:crypto").KeyObject): Uint8Array {
+    const privJwk = identityPrivateKey(this.identity).export({ format: "jwk" }) as {
+      d: string;
+    };
+    const pubJwk = serverPubKey.export({ format: "jwk" }) as {
+      x: string;
+      y: string;
+    };
+
+    const ecdh = createECDH("prime256v1");
+    const dBytes = Buffer.from(privJwk.d, "base64url");
+    ecdh.setPrivateKey(dBytes);
+
+    const xBytes = base64UrlToBytes(pubJwk.x, 32);
+    const yBytes = base64UrlToBytes(pubJwk.y, 32);
+    const uncompressed = Buffer.alloc(65);
+    uncompressed[0] = 0x04;
+    xBytes.copy(uncompressed, 1);
+    yBytes.copy(uncompressed, 33);
+
+    const rawSecret = ecdh.computeSecret(uncompressed);
+    return createHash("sha1").update(rawSecret).digest();
+  }
+}
+
+// ---- Helpers ----------------------------------------------------------------
+
+function makeCacheKey(fromServer: boolean, packetType: number, generationID: number): bigint {
+  let key = 0n;
+  if (fromServer) key |= 1n << 40n;
+  key |= BigInt(packetType & PACKET_TYPE_MASK) << 32n;
+  key |= BigInt(generationID);
+  return key;
+}
+
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (const b of bytes) result = (result << 8n) | BigInt(b);
+  return result;
+}
+
+function bigIntToBytes(value: bigint, size: number): Uint8Array {
+  const result = new Uint8Array(size);
+  let v = value;
+  for (let i = size - 1; i >= 0; i--) {
+    result[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return result;
+}
+
+function base64UrlToBytes(b64url: string, size: number): Buffer {
+  const buf = Buffer.from(b64url, "base64url");
+  if (buf.length === size) return buf;
+  const padded = Buffer.alloc(size);
+  buf.copy(padded, size - buf.length);
+  return padded;
+}

package/src/crypto/eax.ts

@@ -0,0 +1,152 @@
+import { createCipheriv, timingSafeEqual } from "node:crypto";
+import { EAXTagMismatchError } from "../errors.js";
+
+const EAX_TAG_SIZE = 8;
+const EAX_BLOCK_SIZE = 16;
+
+/**
+ * AES-EAX AEAD implementation for TS3 (64-bit tag, AES-128).
+ * Uses AES-CMAC for authentication and AES-CTR for encryption.
+ */
+export class EAX {
+  readonly #key: Uint8Array;
+
+  constructor(key: Uint8Array) {
+    if (key.length !== 16) throw new Error("EAX requires a 16-byte key");
+    this.#key = key;
+  }
+
+  encrypt(
+    nonce: Uint8Array,
+    header: Uint8Array,
+    plaintext: Uint8Array,
+  ): [ciphertext: Uint8Array, tag: Uint8Array] {
+    const nStar = this.#cmac(0, nonce);
+    const hStar = this.#cmac(1, header);
+
+    const ciphertext = aesCtr(this.#key, nStar, plaintext);
+
+    const cStar = this.#cmac(2, ciphertext);
+
+    const tag = new Uint8Array(EAX_TAG_SIZE);
+    for (let i = 0; i < EAX_TAG_SIZE; i++) {
+      tag[i] = nStar[i]! ^ hStar[i]! ^ cStar[i]!;
+    }
+
+    return [ciphertext, tag];
+  }
+
+  decrypt(
+    nonce: Uint8Array,
+    header: Uint8Array,
+    ciphertext: Uint8Array,
+    tag: Uint8Array,
+  ): Uint8Array {
+    const nStar = this.#cmac(0, nonce);
+    const hStar = this.#cmac(1, header);
+    const cStar = this.#cmac(2, ciphertext);
+
+    const expected = new Uint8Array(EAX_TAG_SIZE);
+    for (let i = 0; i < EAX_TAG_SIZE; i++) {
+      expected[i] = nStar[i]! ^ hStar[i]! ^ cStar[i]!;
+    }
+
+    if (!timingSafeEqual(Buffer.from(expected), Buffer.from(tag.slice(0, EAX_TAG_SIZE)))) {
+      throw new EAXTagMismatchError();
+    }
+
+    return aesCtr(this.#key, nStar, ciphertext);
+  }
+
+  /**
+   * AES-CMAC per RFC 4493:
+   *   input = [0…0 tag] ++ data   (one block prefix)
+   */
+  #cmac(tagByte: number, data: Uint8Array): Uint8Array {
+    const input = new Uint8Array(EAX_BLOCK_SIZE + data.length);
+    // first block: zeros then tag byte at the last position
+    input[EAX_BLOCK_SIZE - 1] = tagByte;
+    input.set(data, EAX_BLOCK_SIZE);
+
+    return aesCmac(this.#key, input);
+  }
+}
+
+// ---- AES-CTR ----------------------------------------------------------------
+
+function aesCtr(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Uint8Array {
+  const cipher = createCipheriv("aes-128-ctr", Buffer.from(key), Buffer.from(iv));
+  return Buffer.concat([cipher.update(Buffer.from(data)), cipher.final()]);
+}
+
+// ---- AES-CMAC (RFC 4493) ----------------------------------------------------
+
+function aesEcb(key: Uint8Array, block: Uint8Array): Uint8Array {
+  // Node.js does not expose ECB directly; simulate via CTR with zero IV and
+  // a zero-input (CTR of 0-block XOR with input = ECB)
+  const cipher = createCipheriv("aes-128-ecb", Buffer.from(key), null);
+  cipher.setAutoPadding(false);
+  return Buffer.concat([cipher.update(Buffer.from(block)), cipher.final()]);
+}
+
+function xorBlock(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(EAX_BLOCK_SIZE);
+  for (let i = 0; i < EAX_BLOCK_SIZE; i++) out[i] = a[i]! ^ b[i]!;
+  return out;
+}
+
+function shiftLeft1(b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(EAX_BLOCK_SIZE);
+  let carry = 0;
+  for (let i = EAX_BLOCK_SIZE - 1; i >= 0; i--) {
+    const shifted = ((b[i]! << 1) | carry) & 0xff;
+    carry = b[i]! >> 7;
+    out[i] = shifted;
+  }
+  return out;
+}
+
+const RB = new Uint8Array(EAX_BLOCK_SIZE);
+RB[EAX_BLOCK_SIZE - 1] = 0x87;
+
+function generateSubkeys(key: Uint8Array): [Uint8Array, Uint8Array] {
+  const zero = new Uint8Array(EAX_BLOCK_SIZE);
+  const L = aesEcb(key, zero);
+
+  let K1 = shiftLeft1(L);
+  if ((L[0]! & 0x80) !== 0) K1 = xorBlock(K1, RB);
+
+  let K2 = shiftLeft1(K1);
+  if ((K1[0]! & 0x80) !== 0) K2 = xorBlock(K2, RB);
+
+  return [K1, K2];
+}
+
+export function aesCmac(key: Uint8Array, message: Uint8Array): Uint8Array {
+  const [K1, K2] = generateSubkeys(key);
+
+  const n = Math.max(1, Math.ceil(message.length / EAX_BLOCK_SIZE));
+  const lastBlockComplete = message.length > 0 && message.length % EAX_BLOCK_SIZE === 0;
+
+  let X: Uint8Array = new Uint8Array(EAX_BLOCK_SIZE);
+
+  for (let i = 0; i < n - 1; i++) {
+    const block = message.slice(i * EAX_BLOCK_SIZE, (i + 1) * EAX_BLOCK_SIZE);
+    X = Uint8Array.from(aesEcb(key, xorBlock(X, block)));
+  }
+
+  const lastBlock = new Uint8Array(EAX_BLOCK_SIZE);
+  const lastStart = (n - 1) * EAX_BLOCK_SIZE;
+  const lastSlice = message.slice(lastStart);
+  lastBlock.set(lastSlice);
+
+  let Mn: Uint8Array;
+  if (lastBlockComplete) {
+    Mn = xorBlock(lastBlock, K1);
+  } else {
+    if (lastSlice.length < EAX_BLOCK_SIZE) lastBlock[lastSlice.length] = 0x80;
+    Mn = xorBlock(lastBlock, K2);
+  }
+
+  return Uint8Array.from(aesEcb(key, xorBlock(X, Mn)));
+}