tunnelfetch 1.0.0

package/src/tls/tickets.js

@@ -0,0 +1,145 @@
+// The resumption ticket store: per-Client, keyed like the connection pool, single-use.
+//
+// A ticket is a credential. Presenting one tells the server "treat this connection as a
+// continuation of the session you issued it on", and the server will — without sending a
+// certificate, without this client re-validating anything. So the one property this store must
+// never lose is that a ticket can only ever be OFFERED under the exact configuration it was
+// OBTAINED under. The pool solved the identical problem for sockets: poolKey() folds scheme,
+// host, port, proxy, trust policy and TLS options into the key precisely so a connection
+// validated under one policy cannot serve a request that asked for another. Tickets are keyed
+// by the caller with that same key, for that same reason. Keying by hostname alone is the
+// canonical mistake here: it lets a request that asked for certificate pinning resume — and
+// silently skip the pin check — on the strength of a session that was never pinned at all.
+//
+// Three smaller policies, each deliberate:
+//
+//   * Single use. A ticket is consumed by take() whether or not the resumption succeeds.
+//     RFC 8446 appendix C.4 wants tickets used at most once (reuse lets a passive observer
+//     correlate connections), servers commonly enforce it, and a second offer of a spent ticket
+//     would burn a round trip to be declined. Servers that want chains of resumption issue a
+//     fresh ticket on every connection, including resumed ones.
+//   * Lifetimes are honoured on both ends: a ticket_lifetime of zero is discarded on arrival
+//     (s4.6.1 says exactly that), everything is capped at the protocol's seven-day ceiling
+//     (clients MUST NOT cache longer, whatever the server claimed), and take() re-checks age at
+//     the moment of use, so a ticket that expired while stored is dropped, not offered.
+//   * The clock is injected. Ages are wall-clock quantities, and on the target runtime the
+//     clock is frozen within a synchronous slice — tests need to move time, and nothing else in
+//     the TLS layer reads a clock at all.
+
+import { TlsError, codes } from '../errors.js';
+import { hashLength } from './keyschedule.js';
+
+/** RFC 8446 s4.6.1: servers MUST NOT exceed this, and clients MUST NOT cache beyond it. */
+const MAX_LIFETIME_SEC = 604800; // seven days
+
+export class TicketStore {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.maxPerKey] tickets retained per key, default 2 — the number a typical
+   *   server flight issues; older tickets are evicted first
+   * @param {() => number} [opts.now] epoch-ms source, injectable for tests
+   */
+  constructor({ maxPerKey = 2, now = () => Date.now() } = {}) {
+    /** @type {Map<string, Array<StoredTicket>>} */
+    this._byKey = new Map();
+    this._maxPerKey = maxPerKey;
+    this._now = now;
+  }
+
+  /**
+   * @typedef {object} StoredTicket
+   * @property {Uint8Array} identity
+   * @property {Uint8Array} psk
+   * @property {import('./keyschedule.js').ScheduleHash} hash
+   * @property {number} ageAdd
+   * @property {number} lifetimeMs already clamped to the seven-day ceiling
+   * @property {number} receivedAtMs
+   * @property {object} peer
+   * @property {number} cipherSuite
+   */
+
+  /** Total tickets currently held, for tests and diagnostics. */
+  get size() {
+    let n = 0;
+    for (const list of this._byKey.values()) n += list.length;
+    return n;
+  }
+
+  /**
+   * Store a captured ticket under `key`. Returns whether it was retained: a zero (or negative)
+   * lifetime is a server instruction to discard immediately and is honoured silently — that is
+   * the server's prerogative, not an error — while a structurally unusable capture (no PSK, no
+   * identity, unknown hash) throws, because the only producer is this package's own driver and
+   * a malformed capture is a bug, not an input.
+   *
+   * @param {string} key the pool key of the connection the ticket arrived on
+   * @param {import('./connect.js').CapturedTicket} captured
+   * @returns {boolean}
+   */
+  put(key, captured) {
+    const { identity, psk, hash, lifetimeSec, ageAdd } = captured;
+    hashLength(hash); // throws on anything but SHA-256/SHA-384
+    if (!(identity instanceof Uint8Array) || identity.byteLength === 0 ||
+        !(psk instanceof Uint8Array) || psk.byteLength === 0) {
+      throw new TlsError(codes.TLS_TICKET,
+        'a captured ticket needs a non-empty identity and PSK; refusing to store a blank credential');
+    }
+    if (!Number.isInteger(lifetimeSec) || !Number.isInteger(ageAdd)) {
+      throw new TlsError(codes.TLS_TICKET,
+        `ticket lifetime ${lifetimeSec} / age_add ${ageAdd} are not integers`,
+        { lifetimeSec, ageAdd });
+    }
+    if (lifetimeSec <= 0) return false; // s4.6.1: zero means discard immediately
+    const lifetimeMs = Math.min(lifetimeSec, MAX_LIFETIME_SEC) * 1000;
+    const list = this._byKey.get(key) ?? [];
+    list.push({
+      identity, psk, hash, ageAdd, lifetimeMs,
+      receivedAtMs: this._now(),
+      peer: captured.peer ?? null,
+      cipherSuite: captured.cipherSuite,
+    });
+    while (list.length > this._maxPerKey) list.shift();
+    this._byKey.set(key, list);
+    return true;
+  }
+
+  /**
+   * Take the freshest usable ticket for `key` as a ready-to-offer PSK, or null. The ticket is
+   * removed either way it goes from here — single use — and expired tickets encountered on the
+   * way are dropped rather than offered: a server checks obfuscated_ticket_age against the
+   * lifetime it granted, and offering a stale ticket is a round trip spent being refused.
+   *
+   * @param {string} key MUST be built from the same inputs as the connection's pool key; this
+   *   equality is the entire trust story of resumption (see the module comment)
+   * @returns {import('./connect.js').ResumptionOffer | null}
+   */
+  take(key) {
+    const list = this._byKey.get(key);
+    if (!list) return null;
+    while (list.length > 0) {
+      const t = /** @type {StoredTicket} */ (list.pop());
+      const age = this._now() - t.receivedAtMs;
+      if (age >= t.lifetimeMs) continue; // expired in storage: drop it, try the next-newest
+      if (list.length === 0) this._byKey.delete(key);
+      return {
+        identity: t.identity,
+        psk: t.psk,
+        hash: t.hash,
+        peer: t.peer,
+        // s4.2.11.1: obfuscated_ticket_age = age-in-ms + ticket_age_add, mod 2^32, current at
+        // the moment each hello is built (a HelloRetryRequest builds a second one later).
+        obfuscatedTicketAge: () => {
+          const ms = Math.max(0, this._now() - t.receivedAtMs);
+          return (ms + t.ageAdd) % 0x100000000;
+        },
+      };
+    }
+    this._byKey.delete(key);
+    return null;
+  }
+
+  /** Drop everything; a closed Client must not keep credentials alive. */
+  clear() {
+    this._byKey.clear();
+  }
+}

package/src/tls/transcript.js

@@ -0,0 +1,101 @@
+// Running handshake transcript hash (RFC 8446 s4.4.1).
+//
+// WebCrypto has no streaming digest, so the raw handshake messages are buffered and re-digested
+// on every hash() call. That tradeoff is deliberate: the transcript covers handshake messages
+// only, which a real handshake bounds at a few hundred KB of certificates, and hash() is called
+// a handful of times per connection — buffering costs one transcript-sized allocation, while a
+// hand-rolled incremental SHA-2 in JS would be a fresh piece of security-critical code to get
+// wrong. The buffer is still capped so a peer streaming an absurd certificate chain cannot make
+// us hold unbounded memory; the record layer's per-message cap fires first in practice.
+
+import { TlsError, codes } from '../errors.js';
+import { concat, u8, u24 } from '../util/bytes.js';
+import { HANDSHAKE_TYPE } from './constants.js';
+import { hashLength } from './keyschedule.js';
+
+export class Transcript {
+  /**
+   * @param {import('./keyschedule.js').ScheduleHash} hash fixed once the cipher suite is known
+   * @param {{ maxBytes?: number }} [opts] transcript buffer cap, default 1 MiB
+   */
+  constructor(hash, { maxBytes = 1 << 20 } = {}) {
+    hashLength(hash); // validate eagerly: a typo'd hash name must not surface at first hash()
+    this._hash = hash;
+    /** @type {Uint8Array[]} */
+    this._chunks = [];
+    this._len = 0;
+    this._maxBytes = maxBytes;
+    /** @type {Uint8Array | null} digest cache, invalidated by update() */
+    this._cached = null;
+  }
+
+  get bytesBuffered() {
+    return this._len;
+  }
+
+  /**
+   * Append raw handshake message bytes (including the 4-byte message header — the transcript
+   * is over complete Handshake structs, never record framing).
+   * @param {Uint8Array} bytes
+   */
+  update(bytes) {
+    if (bytes.byteLength === 0) return;
+    if (this._len + bytes.byteLength > this._maxBytes) {
+      throw new TlsError(codes.TLS_HANDSHAKE,
+        `handshake transcript would exceed ${this._maxBytes} bytes`,
+        { buffered: this._len, adding: bytes.byteLength, limit: this._maxBytes });
+    }
+    // Copy: callers hand us subarrays aliasing record buffers they will reuse.
+    this._chunks.push(bytes.slice());
+    this._len += bytes.byteLength;
+    this._cached = null;
+  }
+
+  /**
+   * Digest of everything appended so far. Does not consume; call as often as needed.
+   * @returns {Promise<Uint8Array>}
+   */
+  async hash() {
+    if (!this._cached) {
+      this._cached = new Uint8Array(
+        await crypto.subtle.digest(this._hash, concat(this._chunks, this._len)),
+      );
+    }
+    return this._cached;
+  }
+
+  /**
+   * Digest of everything appended so far PLUS `extra`, without appending it.
+   *
+   * Exists for exactly one caller: the PSK binder after a HelloRetryRequest, which is an HMAC
+   * over Transcript-Hash(message_hash(CH1) || HRR || Truncate(CH2)) (RFC 8446 s4.2.11.2). The
+   * truncated ClientHello2 must be hashed as a continuation of the real transcript but must
+   * never BECOME part of it — the transcript proper gets the full ClientHello2 with its binder,
+   * and folding the truncated form in even transiently would leave a window where the two
+   * bookkeepings disagree.
+   * @param {Uint8Array} extra
+   * @returns {Promise<Uint8Array>}
+   */
+  async hashWith(extra) {
+    return new Uint8Array(
+      await crypto.subtle.digest(this._hash, concat([...this._chunks, extra], this._len + extra.byteLength)),
+    );
+  }
+
+  /**
+   * HelloRetryRequest transcript substitution (RFC 8446 s4.4.1): when a ServerHello is an HRR,
+   * the transcript restarts as a synthetic handshake message
+   *
+   *   message_hash(0xFE) || uint24 Hash.length || Hash(ClientHello1)
+   *
+   * so that a stateless server need only remember the hash of the first ClientHello. Call this
+   * after ClientHello1 is the only message in the transcript, before appending the HRR itself.
+   * @returns {Promise<void>}
+   */
+  async replaceWithMessageHash() {
+    const digest = await this.hash();
+    this._chunks = [concat([u8(HANDSHAKE_TYPE.message_hash), u24(digest.byteLength), digest])];
+    this._len = this._chunks[0].byteLength;
+    this._cached = null;
+  }
+}

package/src/tls/wire.js

@@ -0,0 +1,224 @@
+// TLS wire primitives: length-prefixed vectors, in both directions.
+//
+// TLS is almost entirely nested length-prefixed vectors, and nearly every historical parsing CVE
+// in TLS stacks comes from trusting one of those lengths. So the reader here has exactly one
+// policy: a length that does not fit inside its parent is an error, and a structure with bytes
+// left over when it should be exhausted is an error. Never "read what you can".
+
+import { TlsError, codes } from '../errors.js';
+import { concat, u8, u16, u24 } from '../util/bytes.js';
+
+/** Sequential reader over a byte range with hard bounds. */
+export class Cursor {
+  /**
+   * @param {Uint8Array} bytes
+   * @param {string} what named in every error so a failure says which structure was malformed
+   */
+  constructor(bytes, what = 'structure') {
+    this.bytes = bytes;
+    this.pos = 0;
+    this.what = what;
+  }
+
+  get remaining() {
+    return this.bytes.byteLength - this.pos;
+  }
+
+  get done() {
+    return this.pos >= this.bytes.byteLength;
+  }
+
+  /**
+   * @param {number} n
+   * @param {string} field
+   */
+  _need(n, field) {
+    if (n < 0 || this.remaining < n) {
+      throw new TlsError(
+        codes.TLS_HANDSHAKE,
+        `${this.what}: needed ${n} bytes for ${field} but only ${this.remaining} remain ` +
+          `at offset ${this.pos} of ${this.bytes.byteLength}`,
+        { what: this.what, field, needed: n, remaining: this.remaining, offset: this.pos },
+      );
+    }
+  }
+
+  /**
+   * @param {string} [field]
+   * @returns {number}
+   */
+  u8(field = 'uint8') {
+    this._need(1, field);
+    return this.bytes[this.pos++];
+  }
+
+  /**
+   * @param {string} [field]
+   * @returns {number}
+   */
+  u16(field = 'uint16') {
+    this._need(2, field);
+    const v = (this.bytes[this.pos] << 8) | this.bytes[this.pos + 1];
+    this.pos += 2;
+    return v;
+  }
+
+  /**
+   * @param {string} [field]
+   * @returns {number}
+   */
+  u24(field = 'uint24') {
+    this._need(3, field);
+    const v =
+      (this.bytes[this.pos] << 16) | (this.bytes[this.pos + 1] << 8) | this.bytes[this.pos + 2];
+    this.pos += 3;
+    return v;
+  }
+
+  /**
+   * @param {string} [field]
+   * @returns {number}
+   */
+  u32(field = 'uint32') {
+    this._need(4, field);
+    const b = this.bytes;
+    const v =
+      ((b[this.pos] << 24) | (b[this.pos + 1] << 16) | (b[this.pos + 2] << 8) | b[this.pos + 3]) >>>
+      0;
+    this.pos += 4;
+    return v;
+  }
+
+  /**
+   * Fixed-length opaque bytes. Returns a view into the original buffer, never a copy.
+   * @param {number} n
+   * @param {string} [field]
+   * @returns {Uint8Array}
+   */
+  take(n, field = 'opaque') {
+    this._need(n, field);
+    const out = this.bytes.subarray(this.pos, this.pos + n);
+    this.pos += n;
+    return out;
+  }
+
+  /**
+   * A vector whose length is carried in `lenBytes` (1, 2 or 3) leading octets.
+   * @param {1 | 2 | 3} lenBytes
+   * @param {string} [field]
+   * @returns {Uint8Array}
+   */
+  vector(lenBytes, field = 'vector') {
+    const n = lenBytes === 1 ? this.u8(`${field} length`)
+      : lenBytes === 2 ? this.u16(`${field} length`)
+      : this.u24(`${field} length`);
+    return this.take(n, field);
+  }
+
+  /**
+   * Like `vector`, but hands back a Cursor so nested structures inherit the bound.
+   * @param {1 | 2 | 3} lenBytes
+   * @param {string} [field]
+   * @returns {Cursor}
+   */
+  sub(lenBytes, field = 'vector') {
+    return new Cursor(this.vector(lenBytes, field), `${this.what}.${field}`);
+  }
+
+  /**
+   * Assert nothing is left. Trailing data inside a length-delimited structure means our idea of
+   * the structure and the peer's disagree, which is exactly when to stop rather than guess.
+   * @param {string} [field]
+   */
+  end(field = 'structure') {
+    if (!this.done) {
+      throw new TlsError(
+        codes.TLS_HANDSHAKE,
+        `${this.what}: ${this.remaining} trailing bytes after ${field}`,
+        { what: this.what, field, trailing: this.remaining },
+      );
+    }
+  }
+}
+
+/** Accumulating writer. Kept dumb: correctness of lengths comes from `vector()` below. */
+export class Builder {
+  constructor() {
+    /** @type {Uint8Array[]} */
+    this.parts = [];
+    this.length = 0;
+  }
+
+  /**
+   * @param {Uint8Array} bytes
+   * @returns {this}
+   */
+  push(bytes) {
+    if (bytes.byteLength) {
+      this.parts.push(bytes);
+      this.length += bytes.byteLength;
+    }
+    return this;
+  }
+
+  /** @param {number} n @returns {this} */
+  u8(n) {
+    return this.push(u8(n));
+  }
+  /** @param {number} n @returns {this} */
+  u16(n) {
+    return this.push(u16(n));
+  }
+  /** @param {number} n @returns {this} */
+  u24(n) {
+    return this.push(u24(n));
+  }
+
+  /**
+   * Write `body` prefixed by its length in `lenBytes` octets. Taking the body as bytes rather
+   * than back-patching a placeholder means a length can never drift from what follows it.
+   * @param {1 | 2 | 3} lenBytes
+   * @param {Uint8Array} body
+   * @returns {this}
+   */
+  vector(lenBytes, body) {
+    const n = body.byteLength;
+    const max = lenBytes === 1 ? 0xff : lenBytes === 2 ? 0xffff : 0xffffff;
+    if (n > max) {
+      throw new TlsError(
+        codes.TLS_HANDSHAKE,
+        `vector of ${n} bytes does not fit in a ${lenBytes}-byte length prefix (max ${max})`,
+        { length: n, lenBytes, max },
+      );
+    }
+    if (lenBytes === 1) this.u8(n);
+    else if (lenBytes === 2) this.u16(n);
+    else this.u24(n);
+    return this.push(body);
+  }
+
+  /** @returns {Uint8Array} */
+  build() {
+    return concat(this.parts, this.length);
+  }
+}
+
+/**
+ * Convenience: build a length-prefixed vector standalone.
+ * @param {1 | 2 | 3} lenBytes
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function vector(lenBytes, body) {
+  return new Builder().vector(lenBytes, body).build();
+}
+
+/**
+ * Encode a handshake message: 1-byte type, 3-byte length, body.
+ * @param {number} type
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function handshakeMessage(type, body) {
+  return new Builder().u8(type).vector(3, body).build();
+}