1
/**
2
 * A STUN message decoder: paste a STUN message, as hex or as a capture's hex dump, and see every field, the
3
 * addresses un-XORed, and the checks a receiver would run.
4
 *
5
 * STUN (RFC 8489) is what ICE's connectivity checks and TURN's control messages are made of, so the same twenty-byte
6
 * header turns up in all three. This reads the header, splits the 14-bit type into its method and class, walks the
7
 * attributes, and does the things a list of fields cannot: it un-XORs XOR-MAPPED-ADDRESS and its relatives back into
8
 * the address they carry, and it checks the integrity attributes. FINGERPRINT is a CRC-32 anyone can verify.
9
 * MESSAGE-INTEGRITY and MESSAGE-INTEGRITY-SHA256 are HMACs keyed with a credential, so they are verified when the
10
 * reader gives the password: the password itself for ICE and other short-term credentials, MD5 of
11
 * "username:realm:password" for TURN's long-term ones.
12
 *
13
 * It leads with what the message is, the address or error it carries and whether its integrity holds, then what
14
 * to fix, because the question behind a paste is usually "why did this fail", not "what is in byte 24".
15
 *
16
 * References: RFC 8489 (STUN), RFC 8445 (ICE's attributes), RFC 8656 (TURN's), RFC 5769 (the test vectors).
17
 */
18
import type { ByteRange, Cell, Field, Output, Tool } from "@toolbench/sdk";
19

20
type Input = { message: string; password: string; username: string; realm: string; view: string };
21

22
class ParseError extends Error {
23
  readonly at: number | undefined;
24
  readonly len: number | undefined;
25
  constructor(message: string, at?: number, len?: number) {
26
    super(message);
27
    this.at = at;
28
    this.len = len;
29
  }
30
}
31

32
const MAGIC = 0x2112a442;
33

34
// ---------------------------------------------------------------------------
35
// Reading what was pasted
36
// ---------------------------------------------------------------------------
37

38
/** Separators people put between hex bytes: spaces, colons, commas, dashes. Not dots: a dump's ASCII column is dots. */
39
const HEX_SEGMENT = /^(?:0x|[0-9a-f]|[\s:,-])+$/i;
40
/** A dump line: an offset of 4 to 8 hex digits, then a colon or at least two spaces, then a byte. */
41
const DUMP_LINE = /^\s*(?:0x)?([0-9a-f]{4,8})(?::\s*|\s{2,})(?=[0-9a-f]{2})/i;
42

43
/** The hex digits of a run of text that should be nothing but hex, or an error naming what else is in it. */
44
function hexOf(segment: string): string {
45
  const strays = [...new Set(segment.replace(/0x/gi, "").replace(/[0-9a-f\s:,-]/gi, ""))];
46
  if (strays.length > 0) {
47
    throw new ParseError(
48
      `This is not hex: it contains ${strays.map((c) => `"${c}"`).join(", ")}. Expected hex digits, optionally separated by spaces, colons or commas.`,
49
    );
50
  }
51
  return segment.replace(/0x/gi, "").replace(/[^0-9a-f]/gi, "");
52
}
53

54
/**
55
 * Hex, however it was copied: a plain string, bytes separated by spaces, colons or commas, `0x` or `\x` prefixes, or a
56
 * dump with offsets down the left and the ASCII column on the right, from Wireshark, tcpdump -X, hexdump -C or xxd.
57
 *
58
 * ⚠️ A dump's ASCII column can look like hex ("abcd" is printable and hex alike), so it is not left to the parser to
59
 * tell apart. Each line is cut at the first gap of two or more spaces that is followed by something that is not hex,
60
 * and a dump's bytes per line are capped by the difference between one offset and the next, which is exact whatever
61
 * the ASCII column holds. The same gap rule lets a paste from an RFC's figure keep its notes ("Magic cookie") beside
62
 * the bytes.
63
 */
64
function readHex(text: string): { bytes: Uint8Array; dump: boolean } {
65
  const lines = text.replace(/\\x/gi, " ").split(/\r?\n/);
66
  const dump = lines.some((l) => DUMP_LINE.test(l));
67
  const rows: { offset?: number; digits: string }[] = [];
68
  for (const raw of lines) {
69
    let line = raw.replace(/\|[^|]*\|\s*$/, "");
70
    let offset: number | undefined;
71
    if (dump) {
72
      const m = DUMP_LINE.exec(line);
73
      if (!m) {
74
        if (line.trim()) rows.push({ digits: hexOf(line) });
75
        continue;
76
      }
77
      offset = Number.parseInt(m[1]!, 16);
78
      line = line.slice(m[0].length);
79
    }
80
    const segments = line.split(/\s{2,}/);
81
    let digits = "";
82
    for (const [i, segment] of segments.entries()) {
83
      if (segment === "" || HEX_SEGMENT.test(segment)) {
84
        digits += segment.replace(/0x/gi, "").replace(/[^0-9a-f]/gi, "");
85
        continue;
86
      }
87
      // The first segment is the bytes themselves, so anything odd in it is an error rather than a note.
88
      if (i === 0) digits += hexOf(segment);
89
      break;
90
    }
91
    rows.push({ ...(offset !== undefined ? { offset } : {}), digits });
92
  }
93
  if (dump) {
94
    for (let i = 0; i < rows.length - 1; i++) {
95
      const here = rows[i]!.offset;
96
      const next = rows[i + 1]!.offset;
97
      if (here !== undefined && next !== undefined && next > here) rows[i]!.digits = rows[i]!.digits.slice(0, (next - here) * 2);
98
    }
99
  }
100
  const cleaned = rows.map((r) => r.digits).join("");
101
  if (cleaned.length === 0) throw new ParseError("No hex digits found. Paste a STUN message as hex, or a hex dump from Wireshark.");
102
  if (cleaned.length % 2 !== 0) throw new ParseError(`There is an odd number of hex digits (${cleaned.length}), and a byte needs two.`);
103
  const bytes = new Uint8Array(cleaned.length / 2);
104
  for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(cleaned.slice(i * 2, i * 2 + 2), 16);
105
  return { bytes, dump };
106
}
107

108
const u16 = (b: Uint8Array, at: number) => (b[at]! << 8) | b[at + 1]!;
109
const u32 = (b: Uint8Array, at: number) => b[at]! * 0x1000000 + ((b[at + 1]! << 16) | (b[at + 2]! << 8) | b[at + 3]!);
110
const hex = (n: number, width: number) => `0x${n.toString(16).toUpperCase().padStart(width, "0")}`;
111
const hexBytes = (b: Uint8Array) => [...b].map((x) => x.toString(16).padStart(2, "0")).join(" ");
112
const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
113

114
/** A plausible STUN header at `p`: two zero bits, the cookie, a length that is a multiple of 4 and fits. */
115
const headerAt = (b: Uint8Array, p: number) =>
116
  p + 20 <= b.length && (b[p]! & 0xc0) === 0 && u32(b, p + 4) === MAGIC && u16(b, p + 2) % 4 === 0 && p + 20 + u16(b, p + 2) <= b.length;
117

118
/**
119
 * Where the STUN message starts. A hex dump of a captured frame begins with the Ethernet, IP and UDP headers, and
120
 * asking a reader to count off 42 bytes by hand is exactly the job a tool is for. The cookie at byte 4 of a header is
121
 * what makes this safe: a random 32-bit match is a one in four billion chance at each offset. A message whose own
122
 * cookie is at byte 4 is never moved, even when its length is wrong, so that error is still reported against it.
123
 */
124
function locate(b: Uint8Array): number {
125
  if (b.length < 8 || u32(b, 4) === MAGIC) return 0;
126
  for (let p = 1; p + 20 <= b.length; p++) if (headerAt(b, p)) return p;
127
  return 0;
128
}
129

130
/** What the bytes before a located message were, in words, when they parse as the usual headers. */
131
function describePrefix(b: Uint8Array, skip: number): string {
132
  const ip = (at: number): number | undefined => {
133
    if (at + 40 > b.length) return undefined;
134
    const v = b[at]! >> 4;
135
    if (v === 4 && b[at + 9] === 17) return at + (b[at]! & 0x0f) * 4;
136
    if (v === 6 && b[at + 6] === 17) return at + 40;
137
    return undefined;
138
  };
139
  const family = (at: number) => (b[at]! >> 4 === 4 ? "IPv4" : "IPv6");
140
  const ether = b.length > 14 && (u16(b, 12) === 0x0800 || u16(b, 12) === 0x86dd) ? ip(14) : undefined;
141
  if (ether !== undefined && ether + 8 === skip) return `the Ethernet, ${family(14)} and UDP headers of a captured frame`;
142
  const raw = ip(0);
143
  if (raw !== undefined && raw + 8 === skip) return `the ${family(0)} and UDP headers of a captured packet`;
144
  return "bytes that are not STUN, most likely the headers of a captured packet";
145
}
146

147
function need(bytes: Uint8Array, at: number, len: number, what: string): void {
148
  if (at + len > bytes.length) {
149
    throw new ParseError(
150
      `The message is cut short: ${what} needs ${len} byte${len === 1 ? "" : "s"} at offset ${at}, but the message ends at ${bytes.length}.`,
151
      at,
152
      Math.max(1, bytes.length - at),
153
    );
154
  }
155
}
156

157
// ---------------------------------------------------------------------------
158
// CRC-32, MD5, SHA-1, SHA-256 and their HMACs, small and synchronous, because a pure tool cannot call SubtleCrypto
159
// ---------------------------------------------------------------------------
160

161
const CRC_TABLE = (() => {
162
  const t = new Uint32Array(256);
163
  for (let n = 0; n < 256; n++) {
164
    let c = n;
165
    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
166
    t[n] = c >>> 0;
167
  }
168
  return t;
169
})();
170

171
export function crc32(b: Uint8Array): number {
172
  let c = 0xffffffff;
173
  for (const x of b) c = CRC_TABLE[(c ^ x) & 0xff]! ^ (c >>> 8);
174
  return (c ^ 0xffffffff) >>> 0;
175
}
176

177
const rotl = (x: number, n: number) => ((x << n) | (x >>> (32 - n))) >>> 0;
178
const rotr = (x: number, n: number) => ((x >>> n) | (x << (32 - n))) >>> 0;
179

180
/** Merkle-Damgard padding: a 1 bit, zeros, and the length in bits, big-endian for SHA, little-endian for MD5. */
181
function pad(msg: Uint8Array, littleEndian: boolean): DataView {
182
  const padded = new Uint8Array(((msg.length + 9 + 63) >> 6) << 6);
183
  padded.set(msg);
184
  padded[msg.length] = 0x80;
185
  const view = new DataView(padded.buffer);
186
  const bits = msg.length * 8;
187
  const hi = Math.floor(bits / 2 ** 32);
188
  if (littleEndian) {
189
    view.setUint32(padded.length - 8, bits >>> 0, true);
190
    view.setUint32(padded.length - 4, hi, true);
191
  } else {
192
    view.setUint32(padded.length - 4, bits >>> 0);
193
    view.setUint32(padded.length - 8, hi);
194
  }
195
  return view;
196
}
197

198
export function sha1(msg: Uint8Array): Uint8Array {
199
  const view = pad(msg, false);
200
  let [h0, h1, h2, h3, h4] = [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476, 0xc3d2e1f0];
201
  const w = new Uint32Array(80);
202
  for (let off = 0; off < view.byteLength; off += 64) {
203
    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
204
    for (let i = 16; i < 80; i++) w[i] = rotl(w[i - 3]! ^ w[i - 8]! ^ w[i - 14]! ^ w[i - 16]!, 1);
205
    let [a, b, c, d, e] = [h0, h1, h2, h3, h4];
206
    for (let i = 0; i < 80; i++) {
207
      const [f, k] =
208
        i < 20
209
          ? [(b & c) | (~b & d), 0x5a827999]
210
          : i < 40
211
            ? [b ^ c ^ d, 0x6ed9eba1]
212
            : i < 60
213
              ? [(b & c) | (b & d) | (c & d), 0x8f1bbcdc]
214
              : [b ^ c ^ d, 0xca62c1d6];
215
      const t = (rotl(a, 5) + (f >>> 0) + e + k + w[i]!) >>> 0;
216
      [e, d, c, b, a] = [d, c, rotl(b, 30), a, t];
217
    }
218
    [h0, h1, h2, h3, h4] = [(h0 + a) >>> 0, (h1 + b) >>> 0, (h2 + c) >>> 0, (h3 + d) >>> 0, (h4 + e) >>> 0];
219
  }
220
  const out = new Uint8Array(20);
221
  const ov = new DataView(out.buffer);
222
  [h0, h1, h2, h3, h4].forEach((h, i) => ov.setUint32(i * 4, h));
223
  return out;
224
}
225

226
/** The first 32 bits of the fractional parts of the cube roots of the first 64 primes (FIPS 180-4 section 4.2.2). */
227
const K256 = new Uint32Array([
228
  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
229
  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
230
  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
231
  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
232
  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
233
  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
234
]);
235

236
/** SHA-256, for MESSAGE-INTEGRITY-SHA256 and the SHA-256 long-term key of RFC 8489. */
237
export function sha256(msg: Uint8Array): Uint8Array {
238
  const view = pad(msg, false);
239
  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
240
  const w = new Uint32Array(64);
241
  for (let off = 0; off < view.byteLength; off += 64) {
242
    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
243
    for (let i = 16; i < 64; i++) {
244
      const s0 = rotr(w[i - 15]!, 7) ^ rotr(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
245
      const s1 = rotr(w[i - 2]!, 17) ^ rotr(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
246
      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
247
    }
248
    let [a, b, c, d, e, f, g, hh] = [h[0]!, h[1]!, h[2]!, h[3]!, h[4]!, h[5]!, h[6]!, h[7]!];
249
    for (let i = 0; i < 64; i++) {
250
      const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K256[i]! + w[i]!) >>> 0;
251
      const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
252
      [hh, g, f, e, d, c, b, a] = [g, f, e, (d + t1) >>> 0, c, b, a, (t1 + t2) >>> 0];
253
    }
254
    [a, b, c, d, e, f, g, hh].forEach((x, i) => {
255
      h[i] = (h[i]! + x) >>> 0;
256
    });
257
  }
258
  const out = new Uint8Array(32);
259
  const ov = new DataView(out.buffer);
260
  h.forEach((x, i) => ov.setUint32(i * 4, x));
261
  return out;
262
}
263

264
const MD5_S = [7, 12, 17, 22, 5, 9, 14, 20, 4, 11, 16, 23, 6, 10, 15, 21];
265
const MD5_K = Array.from({ length: 64 }, (_, i) => Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32) >>> 0);
266

267
/** MD5, which TURN's long-term credential still uses for its key (RFC 8489 section 9.2.2). */
268
export function md5(msg: Uint8Array): Uint8Array {
269
  const view = pad(msg, true);
270
  let [a0, b0, c0, d0] = [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476];
271
  for (let off = 0; off < view.byteLength; off += 64) {
272
    let [a, b, c, d] = [a0, b0, c0, d0];
273
    for (let i = 0; i < 64; i++) {
274
      const [f, g] =
275
        i < 16
276
          ? [(b & c) | (~b & d), i]
277
          : i < 32
278
            ? [(d & b) | (~d & c), (5 * i + 1) % 16]
279
            : i < 48
280
              ? [b ^ c ^ d, (3 * i + 5) % 16]
281
              : [c ^ (b | ~d), (7 * i) % 16];
282
      const sum = (a + (f >>> 0) + MD5_K[i]! + view.getUint32(off + g * 4, true)) >>> 0;
283
      [a, d, c] = [d, c, b];
284
      b = (b + rotl(sum, MD5_S[(i >> 4) * 4 + (i % 4)]!)) >>> 0;
285
    }
286
    [a0, b0, c0, d0] = [(a0 + a) >>> 0, (b0 + b) >>> 0, (c0 + c) >>> 0, (d0 + d) >>> 0];
287
  }
288
  const out = new Uint8Array(16);
289
  const ov = new DataView(out.buffer);
290
  [a0, b0, c0, d0].forEach((x, i) => ov.setUint32(i * 4, x, true));
291
  return out;
292
}
293

294
function hmac(hash: (m: Uint8Array) => Uint8Array, size: number, key: Uint8Array, msg: Uint8Array): Uint8Array {
295
  const k = key.length > 64 ? hash(key) : key;
296
  const block = new Uint8Array(64);
297
  block.set(k);
298
  const inner = new Uint8Array(64 + msg.length);
299
  const outer = new Uint8Array(64 + size);
300
  for (let i = 0; i < 64; i++) {
301
    inner[i] = block[i]! ^ 0x36;
302
    outer[i] = block[i]! ^ 0x5c;
303
  }
304
  inner.set(msg, 64);
305
  outer.set(hash(inner), 64);
306
  return hash(outer);
307
}
308

309
export const hmacSha1 = (key: Uint8Array, msg: Uint8Array) => hmac(sha1, 20, key, msg);
310
export const hmacSha256 = (key: Uint8Array, msg: Uint8Array) => hmac(sha256, 32, key, msg);
311

312
/**
313
 * SASLprep (RFC 4013), which a long-term password goes through, to the extent that changes a real password:
314
 * characters "commonly mapped to nothing" are removed, other spaces become a plain space, and the result is
315
 * NFKC-normalised. RFC 5769's long-term vector is exactly this case: "The<U+00AD>M<U+00AA>tr<U+2168>" becomes
316
 * "TheMatrIX". The prohibited-character and bidi checks are left out: they reject a password, and a tool checking a
317
 * message someone else signed is better off trying it.
318
 */
319
export function saslprep(password: string): string {
320
  return password
321
    .replace(/[\u00AD\u034F\u1806\u180B-\u180D\u200B-\u200D\u2060\uFE00-\uFE0F\uFEFF]/g, "")
322
    .replace(/[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/g, " ")
323
    .normalize("NFKC");
324
}
325

326
/** A copy of the message up to `end`, with its length field set as if the message ended just after `end + extra`. */
327
function withLength(bytes: Uint8Array, end: number, extra: number): Uint8Array {
328
  const out = bytes.slice(0, end);
329
  const len = end - 20 + extra;
330
  out[2] = (len >> 8) & 0xff;
331
  out[3] = len & 0xff;
332
  return out;
333
}
334

335
// ---------------------------------------------------------------------------
336
// Types and attributes
337
// ---------------------------------------------------------------------------
338

339
const METHODS: Record<number, string> = {
340
  0x001: "Binding",
341
  0x003: "Allocate",
342
  0x004: "Refresh",
343
  0x006: "Send",
344
  0x007: "Data",
345
  0x008: "CreatePermission",
346
  0x009: "ChannelBind",
347
};
348
const CLASSES = ["request", "indication", "success response", "error response"];
349

350
const ATTRIBUTES: Record<number, string> = {
351
  0x0001: "MAPPED-ADDRESS",
352
  0x0006: "USERNAME",
353
  0x0008: "MESSAGE-INTEGRITY",
354
  0x0009: "ERROR-CODE",
355
  0x000a: "UNKNOWN-ATTRIBUTES",
356
  0x000c: "CHANNEL-NUMBER",
357
  0x000d: "LIFETIME",
358
  0x0012: "XOR-PEER-ADDRESS",
359
  0x0013: "DATA",
360
  0x0014: "REALM",
361
  0x0015: "NONCE",
362
  0x0016: "XOR-RELAYED-ADDRESS",
363
  0x0019: "REQUESTED-TRANSPORT",
364
  0x001c: "MESSAGE-INTEGRITY-SHA256",
365
  0x001d: "PASSWORD-ALGORITHM",
366
  0x001e: "USERHASH",
367
  0x0020: "XOR-MAPPED-ADDRESS",
368
  0x0024: "PRIORITY",
369
  0x0025: "USE-CANDIDATE",
370
  0x8022: "SOFTWARE",
371
  0x8023: "ALTERNATE-SERVER",
372
  0x8028: "FINGERPRINT",
373
  0x8029: "ICE-CONTROLLED",
374
  0x802a: "ICE-CONTROLLING",
375
};
376

377
const TYPE_PREFS: Record<number, string> = { 126: "host", 110: "peer-reflexive", 100: "server-reflexive", 0: "relayed" };
378

379
/**
380
 * What to do about an error response, by code: RFC 8489 section 14.8 and RFC 8656 section 19. Only the codes whose
381
 * remedy is specific; any other gets a pointer to the RFCs.
382
 */
383
const ERROR_ACTIONS: Record<number, string> = {
384
  300: "Try the server named in ALTERNATE-SERVER instead.",
385
  400: "The server could not parse the request. Decode the request you sent with this tool and look for what it marks.",
386
  401: "Send the request again with USERNAME, and the REALM and NONCE from this response, signed with MESSAGE-INTEGRITY keyed with MD5 of username:realm:password.",
387
  403: "The server refuses this request with these credentials. Check that the account may use TURN, and that the peer address is allowed.",
388
  420: "The server does not understand the attributes listed in UNKNOWN-ATTRIBUTES. Send the request again without them.",
389
  437: "The server has no allocation for this client address and port, or a different one. Start again with a new Allocate.",
390
  438: "The nonce has expired. Send the request again with the NONCE from this response.",
391
  441: "The credentials do not match the allocation. Use the same username as the Allocate that created it.",
392
  442: "The server does not relay this transport. Ask for UDP (17) in REQUESTED-TRANSPORT.",
393
  486: "This user has as many allocations as the server allows. Free one with a Refresh of lifetime 0, or wait for one to expire.",
394
  487: "Both ICE agents claim the same role. Switch roles as RFC 8445 section 7.2.5.1 says, and send the check again.",
395
  500: "The server failed. Retry after a short wait.",
396
  508: "The server has no relay capacity left. Try another TURN server.",
397
};
398

399
type Tone = "good" | "warn" | "bad";
400

401
interface Attr {
402
  at: number;
403
  type: number;
404
  len: number;
405
  name: string;
406
  value: string;
407
  note?: string;
408
  tone?: Tone;
409
}
410

411
/** One integrity check: what it is, whether it passed, and, when it could not be run, why. */
412
interface Check {
413
  name: string;
414
  at: number;
415
  result: "pass" | "fail" | "unchecked";
416
  detail: string;
417
}
418

419
function address(bytes: Uint8Array, at: number, len: number, xor: boolean, txid: Uint8Array): { value: string; note: string; tone?: Tone } {
420
  const family = bytes[at + 1];
421
  const rawPort = u16(bytes, at + 2);
422
  const port = xor ? rawPort ^ (MAGIC >>> 16) : rawPort;
423
  if (family === 0x01 && len >= 8) {
424
    const raw = u32(bytes, at + 4);
425
    const ip = xor ? (raw ^ MAGIC) >>> 0 : raw;
426
    const text = [24, 16, 8, 0].map((s) => (ip >>> s) & 0xff).join(".");
427
    return {
428
      value: `${text}:${port}`,
429
      note: xor ? `IPv4. The port is ${hex(rawPort, 4)} XOR 0x2112 and the address ${hex(raw, 8)} XOR 0x2112A442.` : "IPv4, sent in the clear.",
430
    };
431
  }
432
  if (family === 0x02 && len >= 20) {
433
    const mask = new Uint8Array(16);
434
    new DataView(mask.buffer).setUint32(0, MAGIC);
435
    mask.set(txid, 4);
436
    const words: string[] = [];
437
    for (let i = 0; i < 16; i += 2) words.push((((bytes[at + 4 + i]! ^ (xor ? mask[i]! : 0)) << 8) | (bytes[at + 5 + i]! ^ (xor ? mask[i + 1]! : 0))).toString(16));
438
    return { value: `[${words.join(":")}]:${port}`, note: xor ? "IPv6. It is XORed with the cookie followed by the transaction ID." : "IPv6, sent in the clear." };
439
  }
440
  return { value: `family ${family}`, note: "This is not an address family STUN defines.", tone: "warn" };
441
}
442

443
interface Credentials {
444
  password: string;
445
  username: string;
446
  realm: string;
447
}
448

449
function decode(bytes: Uint8Array, creds: Credentials) {
450
  need(bytes, 0, 20, "the STUN header");
451
  const type = u16(bytes, 0);
452
  if (type & 0xc000) throw new ParseError(`The first two bits are ${type >> 14}, but a STUN message's are always 00. This is probably not a STUN message.`, 0, 1);
453
  const length = u16(bytes, 2);
454
  const cookie = u32(bytes, 4);
455
  if (cookie !== MAGIC) {
456
    throw new ParseError(
457
      `The magic cookie is ${hex(cookie, 8)}, but STUN's is always 0x2112A442. This is probably not a STUN message, or it is the older RFC 3489 kind.`,
458
      4,
459
      4,
460
    );
461
  }
462
  if (length % 4 !== 0) throw new ParseError(`The length is ${length}, but STUN attributes are padded to 4 bytes, so it is always a multiple of 4.`, 2, 2);
463
  if (20 + length > bytes.length) throw new ParseError(`The header says ${length} bytes of attributes follow, but only ${bytes.length - 20} do.`, 2, 2);
464
  const method = (type & 0x000f) | ((type & 0x00e0) >> 1) | ((type & 0x3e00) >> 2);
465
  const klass = ((type & 0x0010) >> 4) | ((type & 0x0100) >> 7);
466
  const txid = bytes.slice(8, 20);
467

468
  const attrs: Attr[] = [];
469
  const checks: Check[] = [];
470
  const text = (v: number, len: number) => new TextDecoder().decode(bytes.slice(v, v + len));
471
  const attrText = (t: number): string | undefined => {
472
    const a = attrs.find((x) => x.type === t);
473
    return a ? text(a.at + 4, a.len) : undefined;
474
  };
475
  let errorCode: number | undefined;
476

477
  /*
478
   * The key for both integrity attributes. Long-term when there is a realm to use, from the message or from the
479
   * reader: a TURN server's success response does not repeat USERNAME or REALM, so the reader has to give them.
480
   * Short-term otherwise, which is every ICE check. The message's own values win over the reader's.
481
   */
482
  const key = (): { key: Uint8Array; how: string } | { missing: string } => {
483
    const realm = attrText(0x0014) ?? creds.realm;
484
    const prepped = saslprep(creds.password);
485
    const changed = prepped !== creds.password ? `, after SASLprep turned the password into "${prepped}"` : "";
486
    if (!realm) return { key: new TextEncoder().encode(prepped), how: `the password itself, a short-term credential as ICE uses${changed}` };
487
    const username = attrText(0x0006) ?? creds.username;
488
    if (!username) return { missing: "This is a long-term credential and the message has no USERNAME. Enter the username to check it." };
489
    const sha = attrs.some((x) => x.type === 0x001d && x.len >= 2 && u16(bytes, x.at + 4) === 0x0002);
490
    const input = new TextEncoder().encode(`${username}:${realm}:${prepped}`);
491
    return sha
492
      ? { key: sha256(input), how: `SHA-256 of "${username}:${realm}:password", a long-term credential, as PASSWORD-ALGORITHM asks${changed}` }
493
      : { key: md5(input), how: `MD5 of "${username}:${realm}:password", a long-term credential as TURN uses${changed}` };
494
  };
495

496
  let at = 20;
497
  while (at < 20 + length) {
498
    need(bytes, at, 4, "an attribute header");
499
    const aType = u16(bytes, at);
500
    const aLen = u16(bytes, at + 2);
501
    need(bytes, at + 4, aLen, `attribute ${hex(aType, 4)}`);
502
    const v = at + 4;
503
    const name = ATTRIBUTES[aType] ?? (aType < 0x8000 ? "unknown, must be understood" : "unknown, may be ignored");
504
    let value = `${aLen} bytes`;
505
    let note: string | undefined;
506
    let tone: Tone | undefined;
507
    switch (aType) {
508
      case 0x0001:
509
      case 0x0020:
510
      case 0x0012:
511
      case 0x0016:
512
      case 0x8023: {
513
        const a = address(bytes, v, aLen, aType !== 0x0001 && aType !== 0x8023, txid);
514
        value = a.value;
515
        note = a.note;
516
        tone = a.tone;
517
        break;
518
      }
519
      case 0x0006: {
520
        value = text(v, aLen);
521
        const parts = value.split(":");
522
        // RFC 8445 section 7.2.2: the receiver's ufrag, a colon, the sender's.
523
        note = parts.length === 2 ? `For ICE, "${parts[0]}" is the receiver's ufrag and "${parts[1]}" the sender's.` : "Who is asking.";
524
        break;
525
      }
526
      case 0x0014:
527
        value = text(v, aLen);
528
        note = "The server's name for the set of accounts the password belongs to.";
529
        break;
530
      case 0x0015:
531
        value = text(v, aLen);
532
        note = "A value the server chose, to be sent back with the next request.";
533
        break;
534
      case 0x8022:
535
        value = text(v, aLen);
536
        note = "The software that sent this message.";
537
        break;
538
      case 0x0009: {
539
        errorCode = (bytes[v + 2]! & 0x07) * 100 + bytes[v + 3]!;
540
        value = `${errorCode} ${text(v + 4, aLen - 4)}`;
541
        note = `Class ${bytes[v + 2]! & 0x07} and number ${bytes[v + 3]}, then the reason phrase.`;
542
        break;
543
      }
544
      case 0x000d:
545
        value = `${u32(bytes, v)} s`;
546
        note = "How long the allocation lasts unless it is refreshed.";
547
        break;
548
      case 0x0019:
549
        value = bytes[v] === 17 ? "UDP (17)" : `protocol ${bytes[v]}`;
550
        note = "The transport the client wants the relay to use towards peers.";
551
        break;
552
      case 0x000c:
553
        value = hex(u16(bytes, v), 4);
554
        break;
555
      case 0x001d:
556
        value = u16(bytes, v) === 2 ? "SHA-256 (2)" : u16(bytes, v) === 1 ? "MD5 (1)" : `algorithm ${u16(bytes, v)}`;
557
        note = "The hash used to make the long-term key.";
558
        break;
559
      case 0x0024: {
560
        const p = u32(bytes, v);
561
        const tp = Math.floor(p / 2 ** 24);
562
        value = String(p);
563
        note = `Type preference ${tp}${TYPE_PREFS[tp] ? `, which is ${TYPE_PREFS[tp]} in RFC 8445's recommended values` : ""}. Local preference ${(p >>> 8) & 0xffff}, component ${256 - (p & 0xff)}.`;
564
        break;
565
      }
566
      case 0x0025:
567
        value = "present";
568
        note = "The controlling agent nominates this pair for the call.";
569
        break;
570
      case 0x8029:
571
      case 0x802a:
572
        value = hexBytes(bytes.slice(v, v + aLen));
573
        note = `The sender says it is the ${aType === 0x802a ? "controlling" : "controlled"} agent. The number breaks a tie if both sides claim the same role.`;
574
        break;
575
      case 0x0008:
576
      case 0x001c: {
577
        value = hexBytes(bytes.slice(v, v + aLen));
578
        const sha = aType === 0x001c;
579
        if (!creds.password) {
580
          note = `An ${sha ? "HMAC-SHA256" : "HMAC-SHA1"} of the message, keyed with a credential. Enter the password to check it.`;
581
          checks.push({ name, at, result: "unchecked", detail: "no password given" });
582
          break;
583
        }
584
        const k = key();
585
        if ("missing" in k) {
586
          note = k.missing;
587
          checks.push({ name, at, result: "unchecked", detail: "no username for the long-term key" });
588
          break;
589
        }
590
        const signed = withLength(bytes, at, aLen + 4);
591
        const expect = sha ? hmacSha256(k.key, signed) : hmacSha1(k.key, signed);
592
        // MESSAGE-INTEGRITY-SHA256 may be truncated to as few as 16 bytes (RFC 8489 section 14.6).
593
        const ok = aLen > 0 && aLen <= expect.length && expect.slice(0, aLen).every((x, i) => x === bytes[v + i]);
594
        note = ok ? `It matches. The key is ${k.how}.` : `It does not match. The key tried is ${k.how}.`;
595
        if (!ok) tone = "bad";
596
        checks.push({ name, at, result: ok ? "pass" : "fail", detail: k.how });
597
        break;
598
      }
599
      case 0x8028: {
600
        const got = u32(bytes, v);
601
        const want = (crc32(withLength(bytes, at, 8)) ^ 0x5354554e) >>> 0;
602
        value = hex(got, 8);
603
        const ok = got === want;
604
        note = ok ? "It matches: the CRC-32 of everything before it, XOR 0x5354554E." : `It does not match. The bytes before it give ${hex(want, 8)}.`;
605
        if (!ok) tone = "bad";
606
        checks.push({ name, at, result: ok ? "pass" : "fail", detail: "" });
607
        break;
608
      }
609
    }
610
    attrs.push({ at, type: aType, len: aLen, name, value, ...(note ? { note } : {}), ...(tone ? { tone } : {}) });
611
    at = v + aLen + ((4 - (aLen % 4)) % 4);
612
  }
613
  return { type, method, klass, length, txid, attrs, checks, errorCode };
614
}
615

616
type Decoded = ReturnType<typeof decode>;
617
type Finding = { level: "bad" | "warn" | "normal"; problem: string; fix: string };
618

619
const LEVEL = { bad: "Fails", warn: "Warning", normal: "Unchecked" } as const;
620

621
/**
622
 * What the message is, in its own fields, and what is wrong with it, worst first.
623
 *
624
 * No tone on the identity: a success response is a message class, not a pass. Only a failed integrity check is
625
 * coloured, because that is the one thing a receiver acts on by dropping the message.
626
 */
627
function assess(m: Decoded, methodName: string): { answer: Field[]; findings: Finding[] } {
628
  const findings: Finding[] = [];
629
  const has = (t: number) => m.attrs.some((a) => a.type === t);
630
  const value = (t: number) => m.attrs.find((a) => a.type === t)?.value;
631
  const failed = m.checks.filter((c) => c.result === "fail");
632
  const passed = m.checks.filter((c) => c.result === "pass");
633
  const unchecked = m.checks.filter((c) => c.result === "unchecked");
634
  const iceCheck = m.method === 0x001 && m.klass === 0 && has(0x0024);
635

636
  for (const c of failed) {
637
    findings.push(
638
      c.name === "FINGERPRINT"
639
        ? {
640
            level: "bad",
641
            problem: "FINGERPRINT: the bytes changed after the sender wrote it, so a receiver drops the message.",
642
            fix: "Copy the packet again. A dump cut short, or bytes from two packets, both do this.",
643
          }
644
        : {
645
            level: "bad",
646
            problem: `${c.name}: the key tried is ${c.detail}.`,
647
            fix: has(0x0014)
648
              ? "Check the TURN password, and the username and realm. All three go into the key."
649
              : "For an ICE check and its answer, use the ice-pwd from the SDP of the side that receives the check, not the sender's.",
650
          },
651
    );
652
  }
653
  if (m.errorCode !== undefined) {
654
    findings.push({
655
      level: "warn",
656
      problem: `The server answered ${value(0x0009)}.`,
657
      fix: ERROR_ACTIONS[m.errorCode] ?? "Look this code up in RFC 8489 section 14.8, or RFC 8656 section 19 for TURN.",
658
    });
659
  }
660
  if (iceCheck && !has(0x8028)) {
661
    findings.push({ level: "warn", problem: "This ICE check has no FINGERPRINT.", fix: "RFC 8445 section 7.2.4 requires FINGERPRINT on every connectivity check. Add it last." });
662
  }
663
  if (iceCheck && !has(0x0008) && !has(0x001c)) {
664
    findings.push({
665
      level: "warn",
666
      problem: "This ICE check has no MESSAGE-INTEGRITY, so the receiver cannot tell it belongs to the call.",
667
      fix: "Sign it with the receiver's ice-pwd, and send USERNAME as the receiver's ufrag, a colon, then the sender's.",
668
    });
669
  }
670
  for (const c of unchecked) {
671
    findings.push({
672
      level: "normal",
673
      problem: `${c.name}: ${c.detail}.`,
674
      fix:
675
        c.detail === "no password given"
676
          ? "Enter the password: for ICE, the ice-pwd of the side receiving the check; for TURN, the account's password."
677
          : "Enter the username the client used, and the realm, both from the request this answers.",
678
    });
679
  }
680
  const order = { bad: 0, warn: 1, normal: 2 };
681
  findings.sort((a, b) => order[a.level] - order[b.level]);
682

683
  const answer: Field[] = [];
684
  const user = value(0x0006)?.split(":");
685
  const what = iceCheck
686
    ? `An ICE connectivity check${user?.length === 2 ? ` from "${user[1]}" to "${user[0]}"` : ""}${has(0x0025) ? " that nominates this pair" : ""}.`
687
    : m.method === 0x001 && m.klass === 0 && m.attrs.length === 0
688
      ? "It asks the server which address it sees, and carries nothing else."
689
      : undefined;
690
  answer.push({ label: "Message", value: `${methodName} ${CLASSES[m.klass]}`, note: `${hex(m.type, 4)}${what ? `. ${what}` : ""}` });
691

692
  if (m.errorCode !== undefined) {
693
    answer.push({ label: "Error", value: value(0x0009) ?? String(m.errorCode) });
694
  } else if (has(0x0016)) {
695
    answer.push({ label: "Relayed address", value: value(0x0016)!, ...(has(0x000d) ? { note: `for ${value(0x000d)}` } : {}) });
696
  } else if (has(0x0020) || has(0x0001)) {
697
    answer.push({ label: "Mapped address", value: (value(0x0020) ?? value(0x0001))!, note: "Where the server saw the sender." });
698
  } else if (has(0x0006) && !iceCheck) {
699
    answer.push({ label: "Username", value: value(0x0006)!, ...(has(0x0014) ? { note: `realm ${value(0x0014)}` } : {}) });
700
  }
701

702
  const names = (cs: typeof m.checks) => cs.map((c) => c.name).join(" and ");
703
  let integrity: Field;
704
  if (failed.length) {
705
    integrity = { label: "Integrity", value: `${names(failed)} ${failed.length === 1 ? "does" : "do"} not match`, tone: "bad" };
706
    if (passed.length) integrity.note = `${names(passed)} ${passed.length === 1 ? "matches" : "match"}.`;
707
  } else if (passed.length) {
708
    integrity = { label: "Integrity", value: `${names(passed)} ${passed.length === 1 ? "matches" : "match"}` };
709
    if (unchecked.length) integrity.note = `${names(unchecked)} not checked.`;
710
  } else if (unchecked.length) {
711
    integrity = { label: "Integrity", value: `${names(unchecked)} not checked` };
712
  } else {
713
    integrity = { label: "Integrity", value: "none present", note: "No FINGERPRINT or MESSAGE-INTEGRITY." };
714
  }
715
  answer.push(integrity);
716
  return { answer, findings };
717
}
718

719
export default {
720
  run({ message, password, username, realm, view }: Input): Output {
721
    try {
722
      const read = readHex(message);
723
      const all = read.bytes;
724
      const skip = locate(all);
725
      const head = all.subarray(skip);
726
      const declared = head.length >= 4 ? 20 + u16(head, 2) : 0;
727
      // Only a message that parses is trimmed to its length: a short one must still fail on its length.
728
      const bytes = head.length >= 20 && u32(head, 4) === MAGIC && head.length > declared ? head.slice(0, declared) : head.slice();
729
      const m = decode(bytes, { password: password.trim(), username: username.trim(), realm: realm.trim() });
730
      const after = head.length - bytes.length;
731
      const methodName = METHODS[m.method] ?? `Method ${hex(m.method, 3)}`;
732
      const { answer, findings } = assess(m, methodName);
733

734
      const method: Field[] = [
735
        {
736
          label: "Message type",
737
          value: hex(m.type, 4),
738
          note: `Method ${hex(m.method, 3)}, ${methodName}, and class ${m.klass}, ${CLASSES[m.klass]}, with their bits interleaved.`,
739
          group: "Header",
740
        },
741
        { label: "Length", value: `${m.length} bytes`, note: "Of attributes, after the 20-byte header.", group: "Header" },
742
        { label: "Magic cookie", value: "0x2112A442", note: "Always the same. It tells STUN apart from the media sharing the port.", group: "Header" },
743
        { label: "Transaction ID", value: hexBytes(m.txid), note: "Random, so the answer can be matched to the request.", group: "Header" },
744
      ];
745
      // Only what the reading changed: a plain hex paste read in full says nothing worth a row.
746
      if (read.dump) method.push({ label: "Read as", value: "a hex dump", mono: false, note: "The offsets and the ASCII column were left out.", group: "Input" });
747
      if (skip > 0) method.push({ label: "Skipped before it", value: `${skip} bytes`, note: `The STUN message starts after ${describePrefix(all, skip)}.`, group: "Input" });
748
      if (after > 0) method.push({ label: "Left out after it", value: plural(after, "byte"), note: "Past the length the header gives.", group: "Input" });
749

750
      const parts: Output[] = [{ kind: "fields", role: "answer", fields: answer }];
751
      if (findings.length) {
752
        parts.push({
753
          kind: "table",
754
          role: "findings",
755
          caption: "What to fix, most serious first",
756
          columns: [
757
            { label: "Severity", wrap: "none" },
758
            { label: "What is wrong", wrap: "prose" },
759
            { label: "What to do", wrap: "prose" },
760
          ],
761
          rows: findings.map((f): Cell[] => [{ text: LEVEL[f.level], ...(f.level !== "normal" ? { tone: f.level } : { tone: "muted" as const }) }, f.problem, f.fix]),
762
        });
763
      }
764
      if (m.attrs.length) {
765
        parts.push({
766
          kind: "table",
767
          role: "decoded",
768
          caption: `${plural(m.attrs.length, "attribute")}, each padded to 4 bytes`,
769
          columns: [
770
            { label: "Offset", align: "end", mono: true, wrap: "none" },
771
            { label: "Attribute", wrap: "none", rowHeader: true },
772
            { label: "Value", mono: true, wrap: "prose" },
773
            { label: "How it was decoded", wrap: "prose" },
774
            { label: "Value bytes", align: "end", mono: true, wrap: "none" },
775
          ],
776
          rows: m.attrs.map((a): Cell[] => [
777
            { text: hex(a.at, 4), mono: true, tone: "muted" },
778
            a.name,
779
            { text: a.value, mono: true, ...(a.tone ? { tone: a.tone } : {}) },
780
            a.note ?? "",
781
            { text: String(a.len), mono: true, tone: "muted" },
782
          ]),
783
        });
784
      }
785
      if (view !== "fields") {
786
        /*
787
         * No tones on the ranges, except a check that failed: each range gets its own series colour from the host,
788
         * which tells neighbours apart, and red is kept for the one range a reader has to look at.
789
         */
790
        const failed = new Set(m.checks.filter((c) => c.result === "fail").map((c) => c.at));
791
        const highlight: ByteRange[] = [
792
          { at: 0, len: 4, label: "Type and length" },
793
          { at: 4, len: 4, label: "Magic cookie" },
794
          { at: 8, len: 12, label: "Transaction ID" },
795
          ...m.attrs.map((a) => ({ at: a.at, len: 4 + a.len, label: a.name, ...(failed.has(a.at) ? { tone: "bad" as const } : {}) })),
796
        ];
797
        parts.push({ kind: "bytes", bytes: [...bytes], caption: "The header, then each attribute in place", highlight });
798
      }
799
      parts.push({ kind: "fields", role: "method", fields: method });
800
      return { kind: "group", parts };
801
    } catch (error) {
802
      if (error instanceof ParseError) return { kind: "error", message: error.message, input: "message", ...(error.at !== undefined ? { at: error.at, len: error.len ?? 1 } : {}) };
803
      throw error;
804
    }
805
  },
806
} satisfies Tool<Input>;