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

package/src/discovery/index.ts

@@ -0,0 +1 @@
+export { Resolver } from "./resolver.js";

package/src/discovery/resolver.ts

@@ -0,0 +1,272 @@
+import { resolveSrv } from "node:dns/promises";
+import { createConnection } from "node:net";
+import type { ResolvedAddr } from "../types.js";
+import { isIpAddress, joinHostPort, splitHostPort } from "../address.js";
+import { abortable } from "../abort.js";
+
+const TS_DNS_DEFAULT_PORT = 41144;
+const NICKNAME_LOOKUP_URL = "https://named.myteamspeak.com/lookup";
+const CACHE_TTL_MS = 10 * 60 * 1000;
+/**
+ * How long resolution may take in all; past it, the address is used as given.
+ * A Client holds any resolver, its own or a custom one, to the same budget.
+ *
+ * @internal
+ */
+export const RESOLVE_BUDGET_MS = 10_000;
+/** How long one TSDNS server may take to answer. */
+const TSDNS_TIMEOUT_MS = 3_000;
+
+/**
+ * The most a TSDNS server or the nickname service is read for. Either answers
+ * with one short line; without a bound, one that kept sending would be held in
+ * memory until the resolution budget ran out.
+ */
+export const MAX_DISCOVERY_RESPONSE: number = 8 * 1024;
+
+/** How the default resolver resolves. */
+export interface ResolverOptions {
+  /** Look dot-less names up at named.myteamspeak.com; off by default. */
+  readonly resolveNicknames?: boolean | undefined;
+}
+
+export class Resolver {
+  readonly #cache = new Map<string, ResolvedAddr[]>();
+  readonly #resolveNicknames: boolean;
+
+  constructor(options: ResolverOptions = {}) {
+    this.#resolveNicknames = options.resolveNicknames ?? false;
+  }
+
+  /**
+   * Resolve as the TeamSpeak application does: a server nickname (only with
+   * `resolveNicknames`), then SRV, then TSDNS, then the address as given. The
+   * whole resolution is bounded: past the budget, or when a step fails, the
+   * address as given is the answer.
+   */
+  async resolve(
+    inputAddr: string,
+    options: { readonly signal?: AbortSignal | undefined } = {},
+  ): Promise<ResolvedAddr[]> {
+    if (!inputAddr) throw new Error("empty address");
+    const budget = AbortSignal.timeout(RESOLVE_BUDGET_MS);
+    const signal = options.signal ? AbortSignal.any([options.signal, budget]) : budget;
+    try {
+      return await this.#resolve(inputAddr, signal, true);
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      if (!budget.aborted) throw error;
+      const { host, port } = splitHostPort(inputAddr);
+      return [{ addr: joinHostPort(host, port), source: "Direct" }];
+    }
+  }
+
+  async #resolve(
+    inputAddr: string,
+    signal: AbortSignal,
+    nicknames: boolean,
+  ): Promise<ResolvedAddr[]> {
+    const cached = this.#getValidCache(inputAddr);
+    if (cached) return cached;
+
+    const { host, port } = splitHostPort(inputAddr);
+
+    if (isIpAddress(host)) {
+      return [{ addr: joinHostPort(host, port), source: "Direct" }];
+    }
+
+    // A dot-less name may be a server nickname, which only the TeamSpeak
+    // service can answer: asking it sends the name to a third party, so it is
+    // opt-in. Otherwise the name is resolved like any host.
+    if (nicknames && this.#resolveNicknames && !host.includes(".") && host !== "localhost") {
+      const nickAddr = await resolveNickname(host, signal);
+      signal.throwIfAborted();
+      if (nickAddr) return this.#resolve(nickAddr, signal, false);
+    }
+
+    // SRV _ts3._udp.<host>
+    const srvResults = await this.#resolveSRV(host, signal);
+    if (srvResults) return this.#setCache(inputAddr, srvResults);
+
+    const domainList = getDomainList(host);
+
+    // TSDNS via SRV _tsdns._tcp.<domain>
+    const tsdnsSrv = await this.#resolveTSDNSSRV(domainList, host, signal);
+    if (tsdnsSrv) {
+      return this.#setCache(inputAddr, [{ addr: tsdnsSrv, source: "TSDNS-SRV" }]);
+    }
+
+    // TSDNS direct :41144
+    const tsdnsDirect = await this.#resolveTSDNSDirect(domainList, host, signal);
+    if (tsdnsDirect) {
+      return this.#setCache(inputAddr, [{ addr: tsdnsDirect, source: "TSDNS-Direct" }]);
+    }
+
+    signal.throwIfAborted();
+    // Plain DNS fallback
+    const fallback: ResolvedAddr[] = [{ addr: joinHostPort(host, port), source: "Direct" }];
+    return this.#setCache(inputAddr, fallback);
+  }
+
+  #getValidCache(inputAddr: string): ResolvedAddr[] | null {
+    const cached = this.#cache.get(inputAddr);
+    if (!cached || cached.length === 0) return null;
+    const first = cached[0]!;
+    if (first.expiry !== undefined && Date.now() > first.expiry.getTime()) return null;
+    return cached;
+  }
+
+  #setCache(key: string, results: ResolvedAddr[]): ResolvedAddr[] {
+    const expiry = new Date(Date.now() + CACHE_TTL_MS);
+    const withExpiry = results.map((r) => ({ ...r, expiry }));
+    this.#cache.set(key, withExpiry);
+    return withExpiry;
+  }
+
+  async #resolveSRV(host: string, signal?: AbortSignal): Promise<ResolvedAddr[] | null> {
+    try {
+      const srvs = await abortable(resolveSrv(`_ts3._udp.${host}`), signal);
+      if (!srvs || srvs.length === 0) return null;
+      return srvs.map((srv) => ({
+        addr: joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port)),
+        source: "SRV",
+      }));
+    } catch {
+      return null;
+    }
+  }
+
+  async #resolveTSDNSSRV(
+    domains: string[],
+    queryHost: string,
+    signal?: AbortSignal,
+  ): Promise<string | null> {
+    for (const domain of domains) {
+      try {
+        const srvs = await abortable(resolveSrv(`_tsdns._tcp.${domain}`), signal);
+        if (!srvs || srvs.length === 0) continue;
+        for (const srv of srvs) {
+          const tsdnsAddr = joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port));
+          const result = await queryTSDNS(tsdnsAddr, queryHost, signal);
+          if (result) return result;
+        }
+      } catch {
+        continue;
+      }
+    }
+    return null;
+  }
+
+  async #resolveTSDNSDirect(
+    domains: string[],
+    queryHost: string,
+    signal?: AbortSignal,
+  ): Promise<string | null> {
+    // Asked at once rather than in turn, so the probes cost one timeout in
+    // all; the most specific domain's answer wins.
+    const answers = await Promise.all(
+      domains.map((domain) =>
+        queryTSDNS(joinHostPort(domain, String(TS_DNS_DEFAULT_PORT)), queryHost, signal),
+      ),
+    );
+    return answers.find((answer) => answer !== null) ?? null;
+  }
+}
+
+// ---- Helpers ----------------------------------------------------------------
+
+/** @internal Ask the nickname service for `nickname`'s address. */
+export async function resolveNickname(
+  nickname: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  try {
+    const url = new URL(NICKNAME_LOOKUP_URL);
+    url.searchParams.set("name", nickname);
+    const init: RequestInit = signal ? { signal } : {};
+    const resp = await fetch(url.toString(), init);
+    if (!resp.ok) return null;
+    const text = await readLimited(resp, MAX_DISCOVERY_RESPONSE);
+    const line = text.split("\n")[0]?.trim();
+    return line || null;
+  } catch {
+    return null;
+  }
+}
+
+/** A response body's first `limit` bytes, as text; the rest is not read. */
+async function readLimited(resp: Response, limit: number): Promise<string> {
+  if (resp.body === null) return "";
+  const reader = resp.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (size < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const part = value.subarray(0, limit - size);
+      chunks.push(part);
+      size += part.length;
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** @internal Ask the TSDNS server at `tsdnsAddr` for `queryHost`'s address. */
+export function queryTSDNS(
+  tsdnsAddr: string,
+  queryHost: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const [host, portStr] = splitHostPortParts(tsdnsAddr);
+  const port = parseInt(portStr, 10);
+
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve(null);
+    const finish = (answer: string | null): void => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      socket.destroy();
+      resolve(answer);
+    };
+    const onAbort = (): void => finish(null);
+    const timeout = setTimeout(() => finish(null), TSDNS_TIMEOUT_MS);
+
+    const socket = createConnection({ host, port, timeout: 2_000 }, () => {
+      socket.write(`${queryHost}\n`);
+    });
+
+    let buf = "";
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString("latin1");
+      const idx = buf.indexOf("\n");
+      if (idx >= 0 && idx < MAX_DISCOVERY_RESPONSE) {
+        const line = Buffer.from(buf.slice(0, idx), "latin1").toString("utf8").trim();
+        finish(!line || line === "404" || line === "errors" ? null : line);
+      } else if (buf.length >= MAX_DISCOVERY_RESPONSE) {
+        // No answer is that long.
+        finish(null);
+      }
+    });
+
+    socket.on("error", () => finish(null));
+    socket.on("timeout", () => finish(null));
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function splitHostPortParts(addr: string): [string, string] {
+  const { host, port } = splitHostPort(addr);
+  return [host, port];
+}
+
+function getDomainList(host: string): string[] {
+  const parts = host.split(".");
+  const list: string[] = [];
+  for (let i = 0; i < parts.length - 1; i++) {
+    list.push(parts.slice(i).join("."));
+  }
+  return list.slice(0, 3);
+}

package/src/errors.ts

@@ -0,0 +1,156 @@
+import { Reason, TeamspeakError } from "@honeybbq/teamspeak-core";
+
+/** `connect()` was called on a client that is connecting or connected. */
+export class AlreadyConnectedError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "AlreadyConnectedError";
+
+  constructor() {
+    super("already connecting or connected");
+    this.name = "AlreadyConnectedError";
+  }
+}
+
+/**
+ * The address a client was given cannot be connected to: no host, a host with
+ * characters no host name or IP address has, or a port outside 1–65535.
+ * `connect()` rejects with it before it starts, and the client stays
+ * disconnected. A name that does not resolve is not this: that fails with a
+ * TeamspeakError whose `cause` is the lookup's error, since DNS failures are
+ * often transient.
+ */
+export class InvalidAddressError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "InvalidAddressError";
+
+  /** The address as given. */
+  readonly address: string;
+
+  constructor(address: string, reason: string) {
+    super(`invalid address ${JSON.stringify(address)}: ${reason}`);
+    this.name = "InvalidAddressError";
+    this.address = address;
+  }
+}
+
+/**
+ * A packet failed authentication: it was corrupted, or not from the server.
+ * Internal: the packet is dropped, and this never reaches a caller.
+ */
+export class EAXTagMismatchError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "EAXTagMismatchError";
+
+  constructor() {
+    super("EAX tag mismatch");
+    this.name = "EAXTagMismatchError";
+  }
+}
+
+/**
+ * An unencrypted packet failed its integrity check. Internal: the packet is
+ * dropped, and this never reaches a caller.
+ */
+export class FakeSignatureMismatchError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "FakeSignatureMismatchError";
+
+  constructor() {
+    super("fake signature mismatch");
+    this.name = "FakeSignatureMismatchError";
+  }
+}
+
+/** A file transfer connection failed: it could not be opened, or broke during the transfer. */
+export class FileTransferError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "FileTransferError";
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "FileTransferError";
+  }
+}
+
+/**
+ * The handshake failed on what the server sent: a malformed or out-of-range
+ * Init1 step, public key, license or proof. `connect()` rejects with it, the
+ * underlying failure as its `cause`.
+ */
+export class CryptoInitError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "CryptoInitError";
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CryptoInitError";
+  }
+}
+
+/** An identity string `parseIdentity()` cannot read. */
+export class InvalidIdentityError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "InvalidIdentityError";
+
+  constructor(message = "invalid identity format", options?: ErrorOptions) {
+    super(message, options);
+    this.name = "InvalidIdentityError";
+  }
+}
+
+/**
+ * The server stopped answering: nothing arrived, or a packet went
+ * unacknowledged, for a minute.
+ */
+export class ConnectionTimeoutError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "ConnectionTimeoutError";
+
+  constructor() {
+    super("connection timed out: the server stopped answering");
+    this.name = "ConnectionTimeoutError";
+  }
+}
+
+/**
+ * The server ended this client's session: a kick, a ban, or the server
+ * stopping. The default reconnect policy retries a server that stopped, but
+ * not a kick or a ban.
+ */
+export class RemovedError extends TeamspeakError {
+  /** {@inheritDoc TeamspeakError.kind} */
+  static override readonly kind: string = "RemovedError";
+
+  /** Why: `Reason.KickServer`, `KickServerBan`, `ServerStop` or `ServerShutdown`. */
+  readonly reason: number;
+  /** The reason the server or the invoker gave, if any. */
+  readonly reasonMessage: string;
+  /** Who removed the client, for a kick or a ban. */
+  readonly invokerName: string;
+
+  constructor(reason: number, reasonMessage: string, invokerName: string) {
+    let message = `removed from the server: ${reasonName(reason)}`;
+    if (invokerName) message += ` by ${invokerName}`;
+    if (reasonMessage) message += `: ${reasonMessage}`;
+    super(message);
+    this.name = "RemovedError";
+    this.reason = reason;
+    this.reasonMessage = reasonMessage;
+    this.invokerName = invokerName;
+  }
+}
+
+function reasonName(reason: number): string {
+  switch (reason) {
+    case Reason.KickServer:
+      return "kicked from server";
+    case Reason.KickServerBan:
+      return "banned from server";
+    case Reason.ServerStop:
+      return "server stopped";
+    case Reason.ServerShutdown:
+      return "server shut down";
+    default:
+      return `reason ${reason}`;
+  }
+}

package/src/events.ts

@@ -0,0 +1,28 @@
+import type { EventMiddleware, ServerEvent } from "./types.js";
+import type { CommandExecutor, CommandMiddleware } from "@honeybbq/teamspeak-core";
+
+/**
+ * Compose a chain of middlewares around a base handler.
+ * Rightmost middleware wraps the base first.
+ */
+export function buildCommandChain(
+  middlewares: readonly CommandMiddleware[],
+  base: CommandExecutor["send"],
+): CommandExecutor["send"] {
+  let handler = base;
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    handler = middlewares[i]!(handler);
+  }
+  return handler;
+}
+
+export function buildEventChain(
+  middlewares: EventMiddleware[],
+  base: (event: ServerEvent) => void,
+): (event: ServerEvent) => void {
+  let handler = base;
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    handler = middlewares[i]!(handler);
+  }
+  return handler;
+}

package/src/handshake/crypt-handshake.ts

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { buildCommandOrdered } from "@honeybbq/teamspeak-core/internal";
+import type { Crypt } from "../crypto/crypt.js";
+import { CryptoInitError } from "../errors.js";
+
+export const INIT_VERSION = 1566914096; // 3.5.0 [Stable]
+
+const INIT_VERSION_LEN = 4;
+const INIT_TYPE_LEN = 1;
+const INIT_STEP_LEN = 21;
+
+/** The RSA challenge each connection attempt, by its Crypt, has answered. */
+const answeredChallenges = new WeakMap<
+  Crypt,
+  { readonly challenge: Uint8Array; readonly answer: Uint8Array }
+>();
+
+/**
+ * Handle the TS3INIT1 handshake steps.
+ * Returns the response bytes to send, or null if nothing should be sent.
+ * Throws a CryptoInitError for a step that cannot be answered.
+ */
+export function processInit1(crypt: Crypt, data: Uint8Array | null): Uint8Array | null {
+  if (data === null || (data.length >= 1 && data[0] === 0x7f)) {
+    return buildInit1StartPacket();
+  }
+  if (data.length === 0) throw new CryptoInitError("empty Init1 packet");
+
+  switch (data[0]) {
+    case 0:
+      return buildInit1Step1Packet(data);
+    case 1:
+      return buildInit1Step2Packet(data);
+    case 2:
+      return buildInit1Step3Packet(data);
+    case 3:
+      return buildInit1Step4Packet(crypt, data);
+    default:
+      return null;
+  }
+}
+
+function buildInit1StartPacket(): Uint8Array {
+  const sendData = new Uint8Array(INIT_VERSION_LEN + INIT_TYPE_LEN + 4 + 4 + 8);
+  const view = new DataView(sendData.buffer);
+
+  view.setUint32(0, INIT_VERSION, false);
+  sendData[4] = 0x00;
+
+  const nowSec = Math.floor(Date.now() / 1000);
+  const clampedNow = Math.max(0, Math.min(nowSec, 0xffff_ffff));
+  view.setUint32(5, clampedNow, false);
+
+  const rng = randomBytes(4);
+  sendData.set(rng, 9);
+
+  return sendData;
+}
+
+function buildInit1Step1Packet(data: Uint8Array): Uint8Array | null {
+  if (data.length !== INIT_STEP_LEN) return null;
+
+  const sendData = new Uint8Array(INIT_TYPE_LEN + 16 + 4);
+  sendData[0] = 0x01;
+
+  // TS rand: little-endian uint32 at offset [INIT_VERSION_LEN + INIT_TYPE_LEN + 4]
+  const tsRandOffset = INIT_VERSION_LEN + INIT_TYPE_LEN + 4;
+  const tsRand =
+    data[tsRandOffset]! |
+    (data[tsRandOffset + 1]! << 8) |
+    (data[tsRandOffset + 2]! << 16) |
+    (data[tsRandOffset + 3]! << 24);
+
+  new DataView(sendData.buffer).setUint32(INIT_TYPE_LEN + 16, tsRand >>> 0, false);
+  return sendData;
+}
+
+function buildInit1Step2Packet(data: Uint8Array): Uint8Array | null {
+  if (data.length !== INIT_STEP_LEN) return null;
+
+  const sendData = new Uint8Array(INIT_VERSION_LEN + INIT_TYPE_LEN + 16 + 4);
+  new DataView(sendData.buffer).setUint32(0, INIT_VERSION, false);
+  sendData[4] = 0x02;
+  sendData.set(data.slice(1, 21), 5);
+  return sendData;
+}
+
+function buildInit1Step3Packet(data: Uint8Array): Uint8Array | null {
+  if (data.length !== INIT_VERSION_LEN + INIT_TYPE_LEN + 16 + 4) return null;
+
+  const sendData = new Uint8Array(INIT_TYPE_LEN + 64 + 64 + 4 + 100);
+  sendData[0] = 0x03;
+  sendData[INIT_TYPE_LEN + 64 - 1] = 1;
+  sendData[INIT_TYPE_LEN + 64 + 64 - 1] = 1;
+  new DataView(sendData.buffer).setUint32(INIT_TYPE_LEN + 64 + 64, 1, false);
+  return sendData;
+}
+
+function buildInit1Step4Packet(crypt: Crypt, data: Uint8Array): Uint8Array | null {
+  if (data.length !== INIT_TYPE_LEN + 64 + 64 + 4 + 100) return null;
+  // One challenge per connection attempt, whose Crypt is its own. Each answer
+  // costs up to a second of synchronous squarings, and a second would choose a
+  // new alpha behind the clientinitiv already sent. The same challenge again
+  // means our answer was lost — the transport does not resend it — so it gets
+  // the same answer, without solving anything; a different one gets none.
+  const answered = answeredChallenges.get(crypt);
+  if (answered !== undefined) {
+    return Buffer.from(answered.challenge).equals(Buffer.from(data)) ? answered.answer : null;
+  }
+
+  const level = new DataView(data.buffer, data.byteOffset).getUint32(1 + 128, false);
+  const y = crypt.solveRsaChallenge(data, 1, level);
+
+  const alphaB64 = Buffer.from(crypt.newAlpha()).toString("base64");
+  const omegaB64 = crypt.identity.publicKey();
+
+  const cmd = buildCommandOrdered("clientinitiv", [
+    ["alpha", alphaB64],
+    ["omega", omegaB64],
+    ["ot", "1"],
+    ["ip", ""],
+  ]);
+  const cmdBytes = Buffer.from(cmd);
+
+  const sendData = new Uint8Array(INIT_VERSION_LEN + INIT_TYPE_LEN + 232 + 64 + cmdBytes.length);
+  const view = new DataView(sendData.buffer);
+  view.setUint32(0, INIT_VERSION, false);
+  sendData[4] = 0x04;
+  sendData.set(data.slice(1, 233), 5);
+  sendData.set(y.slice(0, 64), 5 + 232);
+  sendData.set(cmdBytes, 5 + 232 + 64);
+
+  answeredChallenges.set(crypt, { challenge: Uint8Array.from(data), answer: sendData });
+  return sendData;
+}

package/src/handshake/crypt-init2.ts

@@ -0,0 +1,48 @@
+import type { KeyObject } from "node:crypto";
+import type { Crypt } from "../crypto/crypt.js";
+import { importPublicKey } from "../crypto/identity.js";
+import { verifySign, getSharedSecret2 } from "../crypto/primitives.js";
+import { parseLicenses } from "./license.js";
+import { CryptoInitError } from "../errors.js";
+
+/**
+ * CryptoInit2 performs the second stage of crypto initialization (Ed25519 ECDH).
+ * Mirrors Go's handshake.CryptoInit2.
+ */
+export function cryptoInit2(
+  crypt: Crypt,
+  license: string,
+  omega: string,
+  proof: string,
+  beta: string,
+  privateKey: Uint8Array,
+): void {
+  if (crypt.alpha.length === 0) {
+    throw new CryptoInitError("initivexpand2 arrived before clientinitiv was sent");
+  }
+
+  const licenseBytes = Buffer.from(license, "base64");
+  const omegaBytes = Buffer.from(omega, "base64");
+  const proofBytes = Buffer.from(proof, "base64");
+  const betaBytes = Buffer.from(beta, "base64");
+
+  let serverPubKey: KeyObject;
+  try {
+    serverPubKey = importPublicKey(omegaBytes);
+  } catch (error) {
+    throw new CryptoInitError("the server's public key is invalid", { cause: error });
+  }
+  if (!verifySign(serverPubKey, licenseBytes, proofBytes)) {
+    throw new CryptoInitError("the server's license proof is not valid");
+  }
+
+  let sharedSecret: Uint8Array;
+  try {
+    const key = parseLicenses(licenseBytes).deriveKey();
+    sharedSecret = getSharedSecret2(key, privateKey);
+  } catch (error) {
+    throw new CryptoInitError("the server's license is invalid", { cause: error });
+  }
+
+  crypt.setSharedSecret(crypt.alpha, betaBytes, sharedSecret);
+}

package/src/handshake/index.ts

@@ -0,0 +1,3 @@
+export { processInit1, INIT_VERSION } from "./crypt-handshake.js";
+export { cryptoInit2 } from "./crypt-init2.js";
+export { LicenseChain, parseLicenses } from "./license.js";

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/);
+  });
+});