tunnelfetch 1.0.0

package/src/errors.js

@@ -0,0 +1,181 @@
+// Typed errors.
+//
+// Discipline: an error must be specific enough that one log line decides whether a missing
+// feature is worth implementing. "unsupported cipher" is useless; "server selected 0xc02f
+// (TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256) under TLS 1.2, not implemented" is actionable.
+// Every throw site therefore carries the concrete value the peer asked for, in `detail`.
+
+/**
+ * One of the stable machine-readable codes in {@link codes}. Exported as a named union so a
+ * caller can exhaustively switch on `err.code` and have the compiler point at the case they
+ * forgot when a release adds one.
+ * @typedef {(typeof codes)[keyof typeof codes]} ErrorCode
+ */
+
+/** Base for everything this package throws. Never thrown directly. */
+export class TunnelFetchError extends Error {
+  /**
+   * @param {string} code stable machine-readable code, normally an {@link ErrorCode}. Typed as
+   *   string because one internal code (`UNEXPECTED_EOF`, from the byte layer) deliberately
+   *   lives outside the public table.
+   * @param {string} message human-readable, must name concrete values
+   * @param {Record<string, unknown>} [detail]
+   */
+  constructor(code, message, detail) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    if (detail) this.detail = detail;
+  }
+}
+
+/** Proxy handshake failed: CONNECT refused, SOCKS5 rejected, auth required. */
+export class ProxyError extends TunnelFetchError {}
+
+/** HTTP/1.1 wire format: malformed message, ambiguous framing, truncated body. */
+export class HttpError extends TunnelFetchError {}
+
+/** TLS record layer, handshake, or a peer alert. */
+export class TlsError extends TunnelFetchError {}
+
+/**
+ * HTTP/2 framing, streams, flow control, HPACK, or a peer GOAWAY/RST_STREAM. Separate from
+ * HttpError because the wire format and its failure modes are entirely different: an HTTP/1.1
+ * message is text framed by lengths and CRLFs, an HTTP/2 stream is a state machine over binary
+ * frames sharing one connection, and a caller distinguishing "the /1.1 parser choked" from "an
+ * h2 stream was reset" wants two codes, not one.
+ */
+export class Http2Error extends TunnelFetchError {}
+
+/**
+ * The peer offered something we deliberately do not implement.
+ * Separate from TlsError so "we cannot talk to this server" is distinguishable from
+ * "the connection broke", which is the difference between a feature request and a bug report.
+ */
+export class TlsUnsupportedError extends TlsError {}
+
+/** Certificate chain, trust anchor, name matching, validity, or constraint failure. */
+export class CertificateError extends TunnelFetchError {}
+
+/** A deadline elapsed. `phase` says which one, because the fix differs per phase. */
+export class TimeoutError extends TunnelFetchError {}
+
+/** A configured limit was exceeded (response size, header size, redirect count). */
+export class LimitError extends TunnelFetchError {}
+
+/** The caller asked for something the chosen transport cannot honour. */
+export class ConfigError extends TunnelFetchError {}
+
+export const codes = /** @type {const} */ ({
+  // proxy
+  PROXY_CONNECT_REFUSED: 'PROXY_CONNECT_REFUSED',
+  PROXY_AUTH_REQUIRED: 'PROXY_AUTH_REQUIRED',
+  PROXY_AUTH_FAILED: 'PROXY_AUTH_FAILED',
+  PROXY_PROTOCOL: 'PROXY_PROTOCOL',
+  PROXY_UNREACHABLE: 'PROXY_UNREACHABLE',
+  SOCKS5_NO_ACCEPTABLE_AUTH: 'SOCKS5_NO_ACCEPTABLE_AUTH',
+  SOCKS5_REPLY: 'SOCKS5_REPLY',
+  SOCKS5_ADDR_TYPE: 'SOCKS5_ADDR_TYPE',
+
+  // http/1.1
+  HTTP_REQUEST_LINE: 'HTTP_REQUEST_LINE',
+  HTTP_STATUS_LINE: 'HTTP_STATUS_LINE',
+  HTTP_HEADER: 'HTTP_HEADER',
+  HTTP_FRAMING_AMBIGUOUS: 'HTTP_FRAMING_AMBIGUOUS',
+  HTTP_CHUNK: 'HTTP_CHUNK',
+  HTTP_BODY_TRUNCATED: 'HTTP_BODY_TRUNCATED',
+  HTTP_TRAILER: 'HTTP_TRAILER',
+  HTTP_UPGRADE_UNEXPECTED: 'HTTP_UPGRADE_UNEXPECTED',
+
+  // tls
+  TLS_RECORD: 'TLS_RECORD',
+  TLS_ALERT: 'TLS_ALERT',
+  TLS_HANDSHAKE: 'TLS_HANDSHAKE',
+  TLS_TRUNCATED: 'TLS_TRUNCATED',
+  TLS_VERSION_UNSUPPORTED: 'TLS_VERSION_UNSUPPORTED',
+  TLS_CIPHER_UNSUPPORTED: 'TLS_CIPHER_UNSUPPORTED',
+  TLS_GROUP_UNSUPPORTED: 'TLS_GROUP_UNSUPPORTED',
+  TLS_SIGALG_UNSUPPORTED: 'TLS_SIGALG_UNSUPPORTED',
+  TLS_EXTENSION_UNSUPPORTED: 'TLS_EXTENSION_UNSUPPORTED',
+  TLS_ALPN: 'TLS_ALPN',
+  // Session resumption. TLS_PSK is a pre_shared_key negotiation violation (a selected identity
+  // that was not offered, a suite whose hash disagrees with the PSK, a selection with no offer);
+  // TLS_TICKET is an unusable NewSessionTicket or resumption ticket. Split because the first
+  // means the server broke the protocol mid-handshake and the second means a credential was bad.
+  TLS_PSK: 'TLS_PSK',
+  TLS_TICKET: 'TLS_TICKET',
+
+  // http/2 (RFC 9113) and HPACK (RFC 7541). Every one names the concrete wire value that
+  // triggered it — a frame type, a stream id, a table index — because "h2 error" alone decides
+  // nothing about whether a peer is broken, hostile, or speaking a feature we declined.
+  HTTP2_PROTOCOL: 'HTTP2_PROTOCOL', // generic connection PROTOCOL_ERROR: preface, frame on wrong stream, ...
+  HTTP2_FRAME_SIZE: 'HTTP2_FRAME_SIZE', // a frame length the type or our SETTINGS forbids
+  HTTP2_SETTINGS: 'HTTP2_SETTINGS', // malformed SETTINGS, or a value out of its legal range
+  HTTP2_FLOW_CONTROL: 'HTTP2_FLOW_CONTROL', // a window overflowed 2^31-1, or the peer overran ours
+  HTTP2_STREAM_STATE: 'HTTP2_STREAM_STATE', // a frame illegal for the stream's current state
+  HTTP2_STREAM_CLOSED: 'HTTP2_STREAM_CLOSED', // the peer RST_STREAM'd, or closed a stream we were using
+  HTTP2_GOAWAY: 'HTTP2_GOAWAY', // the peer is going away and did not (or will not) serve this stream
+  HTTP2_COMPRESSION: 'HTTP2_COMPRESSION', // HPACK: bad index, bad integer, invalid Huffman padding, ...
+  HTTP2_HEADER: 'HTTP2_HEADER', // a decoded header list that h2 forbids (uppercase, bad pseudo-header)
+  HTTP2_PUSH_UNEXPECTED: 'HTTP2_PUSH_UNEXPECTED', // PUSH_PROMISE despite our SETTINGS_ENABLE_PUSH = 0
+  HTTP2_TRAILER: 'HTTP2_TRAILER', // a trailing header block that is malformed or carries pseudo-headers
+
+  // trust
+  CERT_PARSE: 'CERT_PARSE',
+  CERT_CHAIN_INCOMPLETE: 'CERT_CHAIN_INCOMPLETE',
+  CERT_UNTRUSTED_ROOT: 'CERT_UNTRUSTED_ROOT',
+  CERT_SIGNATURE_INVALID: 'CERT_SIGNATURE_INVALID',
+  CERT_SIGNATURE_WEAK: 'CERT_SIGNATURE_WEAK',
+  CERT_SIGNATURE_UNSUPPORTED: 'CERT_SIGNATURE_UNSUPPORTED',
+  CERT_EXPIRED: 'CERT_EXPIRED',
+  CERT_NOT_YET_VALID: 'CERT_NOT_YET_VALID',
+  CERT_NAME_MISMATCH: 'CERT_NAME_MISMATCH',
+  CERT_CONSTRAINT: 'CERT_CONSTRAINT',
+  CERT_PIN_MISMATCH: 'CERT_PIN_MISMATCH',
+
+  // revocation, via stapled OCSP (RFC 6960 over RFC 6066/8446 status_request)
+  OCSP_PARSE: 'OCSP_PARSE',
+  OCSP_UNVERIFIED: 'OCSP_UNVERIFIED',
+  OCSP_MISMATCH: 'OCSP_MISMATCH',
+  OCSP_STALE: 'OCSP_STALE',
+  OCSP_REVOKED: 'OCSP_REVOKED',
+  OCSP_UNKNOWN: 'OCSP_UNKNOWN',
+  OCSP_REQUIRED: 'OCSP_REQUIRED',
+
+  // client semantics
+  HTTP_CONTENT_ENCODING: 'HTTP_CONTENT_ENCODING',
+  HTTP_CHARSET: 'HTTP_CHARSET',
+  REDIRECT_INVALID_LOCATION: 'REDIRECT_INVALID_LOCATION',
+  REDIRECT_LOOP: 'REDIRECT_LOOP',
+  REDIRECT_SCHEME: 'REDIRECT_SCHEME',
+  COOKIE_INVALID: 'COOKIE_INVALID',
+  POOL_CLOSED: 'POOL_CLOSED',
+  CONNECTION_CLOSED: 'CONNECTION_CLOSED',
+
+  // deadlines and limits
+  TIMEOUT_CONNECT: 'TIMEOUT_CONNECT',
+  TIMEOUT_HANDSHAKE: 'TIMEOUT_HANDSHAKE',
+  TIMEOUT_HEADERS: 'TIMEOUT_HEADERS',
+  TIMEOUT_IDLE: 'TIMEOUT_IDLE',
+  TIMEOUT_TOTAL: 'TIMEOUT_TOTAL',
+  LIMIT_BODY: 'LIMIT_BODY',
+  LIMIT_HEADER: 'LIMIT_HEADER',
+  LIMIT_REDIRECTS: 'LIMIT_REDIRECTS',
+
+  // configuration
+  CONFIG_UNSATISFIABLE: 'CONFIG_UNSATISFIABLE',
+  CONFIG_INVALID: 'CONFIG_INVALID',
+});
+
+/**
+ * Format a byte as 0xNN, for error messages that must name a concrete wire value.
+ * @param {number} n
+ * @returns {string}
+ */
+export const hex8 = (n) => `0x${(n & 0xff).toString(16).padStart(2, '0')}`;
+/**
+ * Format a 16-bit wire value as 0xNNNN (cipher suites, groups, signature schemes).
+ * @param {number} n
+ * @returns {string}
+ */
+export const hex16 = (n) => `0x${(n & 0xffff).toString(16).padStart(4, '0')}`;

package/src/http1/chunked.js

@@ -0,0 +1,289 @@
+// Chunked transfer-coding decoder (RFC 9112 §7.1).
+//
+// Chunked framing is the only place in HTTP/1.1 where the peer controls both the lengths and
+// the delimiters, which makes it the classic smuggling surface. The rules here are therefore
+// grammar-exact: a chunk size is HEX digits and nothing else (no sign, no leading whitespace,
+// no `0x`), chunk data must be followed by exactly CRLF, and any deviation is an error rather
+// than a resynchronisation attempt. A decoder that "recovers" from a framing error has silently
+// agreed to a different message boundary than the sender — that is how one response's bytes
+// become the next response's head.
+//
+// The data phase is driven purely by the declared length, never by delimiter scanning, so
+// payload bytes that happen to contain CRLF (or another chunk header) are inert.
+
+import { HttpError, LimitError, codes } from '../errors.js';
+import { latin1, utf8, UnexpectedEofError } from '../util/bytes.js';
+
+const LF = utf8('\n');
+
+// RFC 9110 token, for trailer field names. Kept local: importing it from response.js would
+// create a cycle (response.js imports this module for body framing).
+const TOKEN_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+
+// chunk-size [chunk-ext]: hex digits, then optionally BWS and a `;`-introduced extension we
+// discard. The alternation is anchored so `+1`, `-1`, ` 1`, `0x1` and a bare trailing space
+// all fail to match instead of parsing as a number.
+const SIZE_LINE_RE = /^([0-9A-Fa-f]+)(?:[ \t]*;.*)?$/;
+
+// field-value content: HTAB / SP / VCHAR / obs-text. Excludes NUL, CR, LF and other controls.
+const FIELD_VALUE_RE = /^[\t\x20-\x7e\x80-\xff]*$/;
+
+// A chunk-size line has no business being long: 13 hex digits already cover every size a safe
+// integer can hold, and extensions are ignored. The bound stops a peer from streaming an
+// unbounded "extension" that we would otherwise buffer while looking for its CRLF.
+const CHUNK_LINE_MAX = 1024;
+
+/** A promise with its settle functions exposed, pre-detached so an unobserved rejection
+ * (caller consumed the stream but never awaited `trailers`) cannot crash the process. */
+function deferred() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  promise.catch(() => {});
+  return { promise, resolve, reject };
+}
+
+/** Read one CRLF-terminated line for chunk framing, mapping low-level failures to HTTP codes. */
+async function readChunkLine(reader, what) {
+  let raw;
+  try {
+    raw = await reader.readUntil(LF, CHUNK_LINE_MAX, what);
+  } catch (e) {
+    if (e instanceof UnexpectedEofError) {
+      throw new HttpError(codes.HTTP_BODY_TRUNCATED, `stream ended inside ${what}`, {
+        what,
+        got: e.detail?.got,
+      });
+    }
+    if (e instanceof LimitError) {
+      // readUntil reports LIMIT_HEADER, but an endless chunk-size line is a framing attack,
+      // not an oversized header block; keep the code honest.
+      throw new HttpError(codes.HTTP_CHUNK, `${what} exceeded ${CHUNK_LINE_MAX} bytes`, { what });
+    }
+    throw e;
+  }
+  const line = latin1(raw);
+  if (line.length < 2 || !line.endsWith('\r\n')) {
+    throw new HttpError(codes.HTTP_CHUNK, `${what} ended with bare LF, expected CRLF`, {
+      what,
+      line,
+    });
+  }
+  return line.slice(0, -2);
+}
+
+/**
+ * Read the trailer section: zero or more `name: value` lines, then an empty line.
+ * The empty line doubles as the terminal CRLF of the whole chunked body.
+ */
+async function readTrailers(reader, maxTrailerBytes) {
+  const trailers = new Headers();
+  let left = maxTrailerBytes;
+  for (;;) {
+    let raw;
+    try {
+      // The budget shrinks per line so the whole section is bounded, and readUntil's own
+      // LIMIT_HEADER is the right code here: trailers are header fields.
+      raw = await reader.readUntil(LF, left, 'trailer section');
+    } catch (e) {
+      if (e instanceof UnexpectedEofError) {
+        throw new HttpError(
+          codes.HTTP_BODY_TRUNCATED,
+          'stream ended inside the trailer section, before the terminal CRLF',
+        );
+      }
+      throw e;
+    }
+    left -= raw.byteLength;
+    const line = latin1(raw);
+    if (line.length < 2 || !line.endsWith('\r\n')) {
+      throw new HttpError(codes.HTTP_TRAILER, 'trailer line ended with bare LF, expected CRLF', {
+        line,
+      });
+    }
+    const s = line.slice(0, -2);
+    if (s === '') return trailers;
+    if (s[0] === ' ' || s[0] === '\t') {
+      // obs-fold; deprecated, and a folded line is exactly how a smuggled field hides.
+      throw new HttpError(codes.HTTP_TRAILER, 'trailer line starts with whitespace (obs-fold)', {
+        line: s,
+      });
+    }
+    const colon = s.indexOf(':');
+    if (colon <= 0) {
+      throw new HttpError(codes.HTTP_TRAILER, `trailer line ${JSON.stringify(s)} has no name`, {
+        line: s,
+      });
+    }
+    const name = s.slice(0, colon);
+    if (!TOKEN_RE.test(name)) {
+      throw new HttpError(
+        codes.HTTP_TRAILER,
+        `trailer name ${JSON.stringify(name)} is not an RFC 9110 token`,
+        { name },
+      );
+    }
+    const value = s.slice(colon + 1).replace(/^[ \t]+|[ \t]+$/g, '');
+    if (!FIELD_VALUE_RE.test(value)) {
+      throw new HttpError(
+        codes.HTTP_TRAILER,
+        `trailer ${name} value contains a control byte`,
+        { name, value },
+      );
+    }
+    // Framing cannot be re-litigated here: the body length was already decided, so even a
+    // trailer named Content-Length is inert data and is stored, not interpreted.
+    trailers.append(name, value);
+  }
+}
+
+/**
+ * Every cap is fail-closed: the peer controls chunk sizes and counts, so each one bounds what
+ * a hostile sender can make us buffer.
+ * @typedef {object} ChunkedOptions
+ * @property {number} [maxBytes] total payload cap, default unlimited
+ * @property {number} [maxChunkSize] per-chunk cap, default 64 MiB
+ * @property {number} [maxTrailerBytes] trailer-section cap, default 8192
+ */
+
+/**
+ * Decode a chunked body from `reader`.
+ *
+ * Returns `{ stream, trailers }`:
+ * - `stream`: ReadableStream<Uint8Array> of the decoded payload octets.
+ * - `trailers`: Promise<Headers|null>. Resolves with the trailer fields once the terminal
+ *   chunk and its trailing CRLF have been fully consumed — i.e. the reader is positioned
+ *   exactly after the body, which is the signal a connection pool needs before reuse.
+ *   Resolves null if the stream is cancelled before that point (position unknown, do not
+ *   reuse). Rejects with the same error the stream errors with on a protocol violation.
+ *
+ * Reads only what the chunked grammar covers; any bytes after the terminal CRLF stay in
+ * `reader` for the next message.
+ *
+ * @param {import('../util/bytes.js').ByteReader} reader
+ * @param {ChunkedOptions} [opts]
+ * @returns {{ stream: ReadableStream<Uint8Array>, trailers: Promise<Headers | null> }}
+ */
+export function decodeChunked(
+  reader,
+  { maxBytes = Infinity, maxChunkSize = 64 * 1024 * 1024, maxTrailerBytes = 8192 } = {},
+) {
+  let state = 'size'; // 'size' -> 'data' -> 'data-crlf' -> 'size' ... -> 'done'
+  let remaining = 0; // data bytes left in the current chunk
+  let total = 0; // payload bytes delivered so far, for maxBytes
+  const t = deferred();
+
+  // Loop until we have enqueued payload or closed; a pull that returns without either would
+  // just be re-invoked by the stream machinery, so we save the round-trips.
+  async function drive(c) {
+    for (;;) {
+      if (state === 'size') {
+        const line = await readChunkLine(reader, 'chunk size line');
+        const m = SIZE_LINE_RE.exec(line);
+        if (!m) {
+          throw new HttpError(
+            codes.HTTP_CHUNK,
+            `malformed chunk size line ${JSON.stringify(line)}`,
+            { line },
+          );
+        }
+        const size = parseInt(m[1], 16);
+        if (!Number.isSafeInteger(size)) {
+          throw new HttpError(
+            codes.HTTP_CHUNK,
+            `chunk size 0x${m[1]} overflows a safe integer`,
+            { hex: m[1] },
+          );
+        }
+        if (size > maxChunkSize) {
+          throw new HttpError(
+            codes.HTTP_CHUNK,
+            `chunk size ${size} exceeds maxChunkSize ${maxChunkSize}`,
+            { size, limit: maxChunkSize },
+          );
+        }
+        if (size === 0) {
+          const trailers = await readTrailers(reader, maxTrailerBytes);
+          state = 'done';
+          t.resolve(trailers);
+          c.close();
+          return;
+        }
+        // Checked at the size line, before any data is buffered, so an over-limit body is
+        // rejected for the price of one line rather than maxBytes of transfer.
+        if (total + size > maxBytes) {
+          throw new LimitError(
+            codes.LIMIT_BODY,
+            `chunked body reached ${total + size} bytes, over the ${maxBytes} byte limit`,
+            { limit: maxBytes },
+          );
+        }
+        remaining = size;
+        state = 'data';
+      } else if (state === 'data') {
+        // Length-driven, and capped at `remaining` so we can never consume past the chunk
+        // into the framing that follows it.
+        const chunk = await reader.readSome(Math.min(remaining, 65536));
+        if (chunk === null) {
+          throw new HttpError(
+            codes.HTTP_BODY_TRUNCATED,
+            `stream ended with ${remaining} bytes of a chunk unread`,
+            { remaining },
+          );
+        }
+        remaining -= chunk.byteLength;
+        total += chunk.byteLength;
+        if (remaining === 0) state = 'data-crlf';
+        c.enqueue(chunk);
+        return;
+      } else if (state === 'data-crlf') {
+        let two;
+        try {
+          two = await reader.readExactly(2, 'CRLF after chunk data');
+        } catch (e) {
+          if (e instanceof UnexpectedEofError) {
+            throw new HttpError(codes.HTTP_BODY_TRUNCATED, 'stream ended after chunk data, ' +
+              'before its CRLF');
+          }
+          throw e;
+        }
+        if (two[0] !== 0x0d || two[1] !== 0x0a) {
+          // The sender's size and its actual data disagree. Resynchronising here would mean
+          // guessing where the message really ends, so this is fatal.
+          const got = `0x${two[0].toString(16)} 0x${two[1].toString(16)}`;
+          throw new HttpError(
+            codes.HTTP_CHUNK,
+            `chunk data not followed by CRLF (got ${got})`,
+            { got: [two[0], two[1]] },
+          );
+        }
+        state = 'size';
+      } else {
+        c.close();
+        return;
+      }
+    }
+  }
+
+  const stream = new ReadableStream({
+    async pull(c) {
+      try {
+        await drive(c);
+      } catch (e) {
+        state = 'done';
+        t.reject(e);
+        c.error(e);
+      }
+    },
+    cancel() {
+      // Cancellation abandons the connection at an unknown byte position; `null` tells the
+      // caller there are no trailers and, implicitly, that the socket must not be reused.
+      state = 'done';
+      t.resolve(null);
+    },
+  });
+
+  return { stream, trailers: t.promise };
+}

package/src/http1/index.js

@@ -0,0 +1,10 @@
+// HTTP/1.1 wire layer: serialise request heads, parse response heads, frame bodies.
+//
+// This layer owns message boundaries and nothing else. It does not manage connections, follow
+// redirects, or decode content codings; it guarantees exactly one thing — that the bytes it
+// attributes to a message are precisely the bytes the framing rules assign to it, and that any
+// ambiguity about where a message ends is an error instead of a guess.
+
+export { serializeRequestHead } from './request.js';
+export { readResponseHead, bodyFraming, readResponseBody } from './response.js';
+export { decodeChunked } from './chunked.js';

package/src/http1/request.js

@@ -0,0 +1,143 @@
+// HTTP/1.1 request head serialiser.
+//
+// This is a pure function from a description to bytes. It adds nothing implicitly — no Host, no
+// Content-Length, no Connection — because framing and connection management are decisions that
+// belong to the layer that owns the socket. A serialiser with hidden defaults cannot be tested
+// byte-for-byte, and byte-for-byte tests are the only kind that catch request-splitting bugs.
+//
+// Everything the caller provides is validated against the RFC 9110 grammar before it is allowed
+// anywhere near the wire. A header value containing CR or LF is not "escaped" or "sanitised" —
+// it is rejected, because a value that needs sanitising is an injection attempt, and quietly
+// rewriting it turns a loud failure into a silent vulnerability.
+
+import { HttpError, codes } from '../errors.js';
+
+// RFC 9110 token: 1*tchar. This is the exact alphabet; anything else in a field name or method
+// is either a typo or a smuggling attempt, and both deserve the same rejection.
+const TOKEN_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+
+// request-target: printable ASCII with no whitespace. Covers origin-form (`/path?q`),
+// absolute-form (`http://host/path`, required when talking through a forward proxy for
+// plain http), authority-form (`host:port` for CONNECT) and asterisk-form (`*`).
+// A space or control character in the target splits the request line.
+const TARGET_RE = /^[\x21-\x7e]+$/;
+
+// The only versions this layer speaks. Serialising `HTTP/2` framing as text would produce
+// garbage a peer might partially interpret, which is worse than failing here.
+const VERSIONS = new Set(['1.0', '1.1']);
+
+/** Encode a string whose char codes are all <= 0xFF as raw octets (inverse of bytes.js latin1). */
+function latin1Bytes(s) {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+/**
+ * A request head as this serialiser consumes it. Nothing optional is invented: what is absent
+ * here is absent on the wire.
+ * @typedef {object} RequestHead
+ * @property {string} method RFC 9110 token, sent verbatim (no case-folding)
+ * @property {string} target request-target, already encoded: origin-form (`/path?q`),
+ *   absolute-form, authority-form (CONNECT) or `*`
+ * @property {Headers | Iterable<[string, string]>} [headers]
+ * @property {'1.0' | '1.1'} [httpVersion] default '1.1'
+ */
+
+/**
+ * Serialise a request head: request line, header fields, terminating blank line.
+ * Throws HttpError on any input the RFC 9110 grammar rejects — notably CR/LF in a value,
+ * which is header injection, never something to sanitise.
+ *
+ * `headers` may be a WHATWG Headers instance or any iterable of [name, value] pairs.
+ * Pair iterables are written in caller order, unsorted — order can matter to real servers.
+ * Note that a Headers instance has already lost the caller's order by spec (it iterates
+ * lowercased and sorted); we serialise its iteration order as-is.
+ *
+ * @param {RequestHead} req
+ * @returns {Uint8Array}
+ */
+export function serializeRequestHead({ method, target, headers = [], httpVersion = '1.1' }) {
+  if (typeof method !== 'string' || !TOKEN_RE.test(method)) {
+    throw new HttpError(
+      codes.HTTP_REQUEST_LINE,
+      `method ${JSON.stringify(method)} is not an RFC 9110 token`,
+      { method },
+    );
+  }
+  if (typeof target !== 'string' || !TARGET_RE.test(target)) {
+    throw new HttpError(
+      codes.HTTP_REQUEST_LINE,
+      `request-target ${JSON.stringify(target)} contains whitespace, control bytes, or ` +
+        'non-ASCII; targets must arrive here already encoded',
+      { target },
+    );
+  }
+  if (!VERSIONS.has(httpVersion)) {
+    throw new HttpError(
+      codes.HTTP_REQUEST_LINE,
+      `httpVersion ${JSON.stringify(httpVersion)} is not supported (only 1.0 and 1.1)`,
+      { httpVersion },
+    );
+  }
+  if (headers === null || typeof headers[Symbol.iterator] !== 'function') {
+    throw new HttpError(
+      codes.HTTP_HEADER,
+      'headers must be a Headers instance or an iterable of [name, value] pairs',
+    );
+  }
+
+  let head = `${method} ${target} HTTP/${httpVersion}\r\n`;
+  for (const entry of headers) {
+    const name = String(entry[0]);
+    const rawValue = String(entry[1]);
+    if (!TOKEN_RE.test(name)) {
+      throw new HttpError(
+        codes.HTTP_HEADER,
+        `header name ${JSON.stringify(name)} is not an RFC 9110 token`,
+        { name },
+      );
+    }
+    // The request-splitting defence. Checked on the raw value BEFORE trimming, so a value like
+    // 'x\r\n' is rejected rather than quietly repaired into something send-safe.
+    if (/[\r\n\0]/.test(rawValue)) {
+      throw new HttpError(
+        codes.HTTP_HEADER,
+        `header ${name} value ${JSON.stringify(rawValue)} contains CR, LF, or NUL ` +
+          '(header injection rejected)',
+        { name, value: rawValue },
+      );
+    }
+    // Field values are opaque octets; a char code over 0xFF has no octet representation and
+    // guessing an encoding for it would send bytes the caller never wrote.
+    for (let i = 0; i < rawValue.length; i++) {
+      if (rawValue.charCodeAt(i) > 0xff) {
+        throw new HttpError(
+          codes.HTTP_HEADER,
+          `header ${name} value contains U+${rawValue.codePointAt(i).toString(16)} which is not ` +
+            'representable as a single octet',
+          { name, value: rawValue },
+        );
+      }
+    }
+    // Beyond CR/LF/NUL, the RFC 9110 field-value grammar admits only HTAB, SP through '~', and
+    // obs-text (0x80-0xFF). The remaining control bytes — 0x01-0x08, VT, FF, 0x0E-0x1F and DEL —
+    // are not send-safe: the response parser refuses them on receipt (FIELD_VALUE_RE), and a
+    // serialiser laxer than the parser is a hole in the same fail-closed grammar. Reject rather
+    // than emit a byte the caller almost certainly did not mean and a proxy may mishandle.
+    if (/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(rawValue)) {
+      throw new HttpError(
+        codes.HTTP_HEADER,
+        `header ${name} value contains a control byte the RFC 9110 field-value grammar forbids`,
+        { name, value: rawValue },
+      );
+    }
+    // Leading/trailing OWS is meaningless on the wire (the peer must strip it) and Headers
+    // instances arrive pre-trimmed; trimming pair-iterable input keeps both paths identical.
+    const value = rawValue.replace(/^[ \t]+|[ \t]+$/g, '');
+    head += `${name}: ${value}\r\n`;
+  }
+  head += '\r\n';
+  // Every part was validated to char codes <= 0xFF, so latin1 encoding is exact.
+  return latin1Bytes(head);
+}