nlcurl 0.1.0 → 0.2.0

package/dist/tls/stealth/record-layer.js

@@ -1,23 +1,17 @@
-/**
- * TLS record layer.
- *
- * Handles framing, encryption, and decryption of TLS records.
- * Operates on raw TCP byte streams.
- */
 import { createCipheriv, createDecipheriv, } from 'node:crypto';
 import { BufferWriter } from '../../utils/buffer-writer.js';
 import { RecordType, ProtocolVersion } from '../constants.js';
 import { TLSError } from '../../core/errors.js';
-/** Maximum TLS record payload (2^14 = 16384). */
 const MAX_RECORD_PAYLOAD = 16384;
-/** Maximum ciphertext overhead (tag + content type byte). */
 const MAX_CIPHERTEXT_OVERHEAD = 256;
-// ---- Record reading ----
 /**
- * Read a single TLS record from a buffer.
+ * Attempts to parse a single TLS record from `data` beginning at `offset`.
+ * Returns `null` without consuming the buffer if fewer than 5 bytes are
+ * available or the payload has not been fully received yet.
  *
- * Returns the record and the number of bytes consumed, or `null` if
- * the buffer does not contain a complete record.
+ * @param {Buffer} data   - Buffer containing one or more TLS records.
+ * @param {number} offset - Byte offset within `data` to begin parsing.
+ * @returns {{ record: TLSRecord; bytesRead: number } | null} Parsed record and byte count, or `null` if more data is needed.
  */
 export function readRecord(data, offset) {
     if (data.length - offset < 5)
@@ -34,7 +28,12 @@ export function readRecord(data, offset) {
     };
 }
 /**
- * Write a TLS record (unencrypted) to a buffer.
+ * Serializes a TLS record into its 5-byte header plus payload binary form.
+ *
+ * @param {number} type    - TLS content type byte.
+ * @param {number} version - TLS record version (e.g. `0x0303`).
+ * @param {Buffer} payload - Record payload bytes.
+ * @returns {Buffer} The complete serialized TLS record.
  */
 export function writeRecord(type, version, payload) {
     const w = new BufferWriter(5 + payload.length);
@@ -45,7 +44,12 @@ export function writeRecord(type, version, payload) {
     return w.toBuffer();
 }
 /**
- * Determine AEAD algorithm from cipher suite name.
+ * Maps a cipher suite name string to the corresponding AEAD algorithm
+ * identifier used by the record layer.
+ *
+ * @param {string} cipherName - Cipher suite name from {@link TLSConnectionInfo} (e.g. `"TLS_AES_128_GCM_SHA256"`).
+ * @returns {AEADAlgorithm} The corresponding AEAD algorithm identifier.
+ * @throws {TLSError} If the cipher name does not correspond to a supported AEAD algorithm.
  */
 export function aeadFromCipher(cipherName) {
     if (cipherName.includes('AES_128_GCM') || cipherName.includes('aes-128-gcm')) {
@@ -59,28 +63,34 @@ export function aeadFromCipher(cipherName) {
     }
     throw new TLSError(`Unsupported cipher: ${cipherName}`);
 }
-/** Tag size for all supported AEAD algorithms. */
 const TAG_SIZE = 16;
 /**
- * Build the per-record nonce by XORing the IV with the 64-bit
- * sequence number (zero-padded on the left).
+ * Constructs the per-record nonce by XOR-ing the static IV with the
+ * big-endian 64-bit sequence number (RFC 8446 ¥5.3).
+ *
+ * @param {Buffer} iv             - Static IV of length matching the AEAD algorithm.
+ * @param {bigint} sequenceNumber - Record sequence number (starts at 0, increments by 1).
+ * @returns {Buffer} The per-record nonce.
  */
 export function buildNonce(iv, sequenceNumber) {
     const nonce = Buffer.from(iv);
     const seqBuf = Buffer.alloc(8);
     seqBuf.writeBigUInt64BE(sequenceNumber);
-    // XOR the last 8 bytes of IV with the sequence number
     for (let i = 0; i < 8; i++) {
         nonce[nonce.length - 8 + i] ^= seqBuf[i];
     }
     return nonce;
 }
 /**
- * Encrypt a TLS 1.3 record.
+ * Encrypts `plaintext` using the specified AEAD algorithm and returns the
+ * ciphertext with an appended 16-byte authentication tag.
  *
- * The plaintext is the handshake/application data followed by the
- * content type byte.  The additional data is the record header of the
- * outer (opaque) application_data record.
+ * @param {AEADAlgorithm} algorithm      - AEAD algorithm identifier.
+ * @param {Buffer}        key            - Encryption key.
+ * @param {Buffer}        nonce          - Per-record nonce.
+ * @param {Buffer}        plaintext      - Data to encrypt.
+ * @param {Buffer}        additionalData - Additional authenticated data (AAD).
+ * @returns {Buffer} Ciphertext followed by the 16-byte authentication tag.
  */
 export function encryptRecord(algorithm, key, nonce, plaintext, additionalData) {
     const cipher = createCipheriv(algorithm, key, nonce, { authTagLength: TAG_SIZE });
@@ -91,10 +101,16 @@ export function encryptRecord(algorithm, key, nonce, plaintext, additionalData)
     return Buffer.concat([encrypted, final, tag]);
 }
 /**
- * Decrypt a TLS 1.3 record.
+ * Decrypts and authenticates `ciphertext` using the specified AEAD algorithm.
+ * The last 16 bytes of `ciphertext` are treated as the authentication tag.
  *
- * Returns the decrypted plaintext including the trailing content type
- * byte.  The caller must strip the content type.
+ * @param {AEADAlgorithm} algorithm      - AEAD algorithm identifier.
+ * @param {Buffer}        key            - Decryption key.
+ * @param {Buffer}        nonce          - Per-record nonce.
+ * @param {Buffer}        ciphertext     - Ciphertext including the 16-byte authentication tag.
+ * @param {Buffer}        additionalData - Additional authenticated data (AAD) for tag verification.
+ * @returns {Buffer} Decrypted plaintext bytes.
+ * @throws {TLSError} If the ciphertext is too short or authentication fails.
  */
 export function decryptRecord(algorithm, key, nonce, ciphertext, additionalData) {
     if (ciphertext.length < TAG_SIZE) {
@@ -115,26 +131,33 @@ export function decryptRecord(algorithm, key, nonce, ciphertext, additionalData)
     }
 }
 /**
- * Build the additional data for a TLS 1.3 encrypted record.
+ * Builds the additional authenticated data (AAD) for a TLS 1.3 application
+ * data record, encoded as a 5-byte pseudo-record header per RFC 8446 ¥5.2.
  *
- * For TLS 1.3: the 5-byte record header of the *outer* record
- * (type=application_data, version=0x0303, length).
+ * @param {number} ciphertextLength - Total length of the ciphertext including the AEAD tag.
+ * @returns {Buffer} 5-byte AAD buffer.
  */
 export function buildAdditionalData(ciphertextLength) {
     const w = new BufferWriter(5);
     w.writeUInt8(RecordType.APPLICATION_DATA);
-    w.writeUInt16(ProtocolVersion.TLS_1_2); // TLS 1.3 records use 0x0303 in the header
+    w.writeUInt16(ProtocolVersion.TLS_1_2);
     w.writeUInt16(ciphertextLength);
     return w.toBuffer();
 }
 /**
- * Wrap plaintext into an encrypted TLS 1.3 record.
+ * Encodes a TLS 1.3 inner plaintext (content bytes + content type byte) and
+ * wraps it in an encrypted TLS record with the appropriate AAD, following
+ * RFC 8446 ¥5.2.
  *
- * Appends the real content type byte to the plaintext, encrypts with
- * AEAD, and wraps in a record with type=application_data.
+ * @param {AEADAlgorithm} algorithm     - AEAD algorithm identifier.
+ * @param {Buffer}        key           - Application traffic key.
+ * @param {Buffer}        iv            - Application traffic IV.
+ * @param {bigint}        sequenceNumber - Sequence number for nonce derivation.
+ * @param {number}        contentType   - True content type byte to embed in the inner plaintext.
+ * @param {Buffer}        plaintext     - Application data to encrypt.
+ * @returns {Buffer} The complete TLS application_data record ready to send.
  */
 export function wrapEncryptedRecord(algorithm, key, iv, sequenceNumber, contentType, plaintext) {
-    // Build inner plaintext: data + content_type byte
     const inner = Buffer.alloc(plaintext.length + 1);
     plaintext.copy(inner);
     inner[plaintext.length] = contentType;
@@ -145,15 +168,22 @@ export function wrapEncryptedRecord(algorithm, key, iv, sequenceNumber, contentT
     return writeRecord(RecordType.APPLICATION_DATA, ProtocolVersion.TLS_1_2, ciphertext);
 }
 /**
- * Unwrap an encrypted TLS 1.3 record.
+ * Decrypts a TLS 1.3 application_data record, strips the zero-padding, and
+ * recovers the true content type embedded as the last non-zero byte of the
+ * inner plaintext (RFC 8446 ¥5.2).
  *
- * Returns the decrypted plaintext and the real content type.
+ * @param {AEADAlgorithm} algorithm     - AEAD algorithm identifier.
+ * @param {Buffer}        key           - Application traffic key.
+ * @param {Buffer}        iv            - Application traffic IV.
+ * @param {bigint}        sequenceNumber - Sequence number for nonce derivation.
+ * @param {TLSRecord}     record        - Encrypted TLS record received from the remote party.
+ * @returns {{ contentType: number; plaintext: Buffer }} Recovered content type and decrypted payload.
+ * @throws {TLSError} If decryption or authentication fails, or the record is empty after unpadding.
  */
 export function unwrapEncryptedRecord(algorithm, key, iv, sequenceNumber, record) {
     const nonce = buildNonce(iv, sequenceNumber);
     const aad = buildAdditionalData(record.fragment.length);
     const inner = decryptRecord(algorithm, key, nonce, record.fragment, aad);
-    // Strip trailing zeros and find the real content type
     let i = inner.length - 1;
     while (i >= 0 && inner[i] === 0)
         i--;

package/dist/tls/stealth/record-layer.js.map

@@ -1 +1 @@
-{"version":3,"file":"record-layer.js","sourceRoot":"","sources":["../../../src/tls/stealth/record-layer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"record-layer.js","sourceRoot":"","sources":["../../../src/tls/stealth/record-layer.ts"],"names":[],"mappings":"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"}

package/dist/tls/types.d.ts

@@ -1,58 +1,66 @@
-/**
- * TLS engine types and the ITLSEngine interface that both standard
- * (node:tls) and stealth (raw handshake) engines implement.
- */
 import type { Socket } from 'node:net';
 import type { Duplex } from 'node:stream';
 import type { BrowserProfile } from '../fingerprints/types.js';
 import type { Logger } from '../utils/logger.js';
+/**
+ * Options required to establish a TLS connection to a remote server.
+ *
+ * @typedef  {Object}        TLSConnectOptions
+ * @property {string}        host              - Remote hostname or IP address.
+ * @property {number}        port              - Remote TCP port.
+ * @property {Socket}        [socket]          - Pre-connected TCP socket to upgrade (e.g. after proxy CONNECT).
+ * @property {string}        [servername]      - TLS SNI hostname; defaults to `host`.
+ * @property {boolean}       [insecure]        - Skip TLS certificate verification when `true`.
+ * @property {string[]}      [alpnProtocols]   - ALPN protocol names to advertise (e.g. `['h2', 'http/1.1']`).
+ * @property {number}        [timeout]         - Handshake timeout in milliseconds.
+ * @property {AbortSignal}   [signal]          - Signal used to abort the connection attempt.
+ * @property {4|6}           [family]          - Force IPv4 (`4`) or IPv6 (`6`) for DNS resolution.
+ * @property {Logger}        [logger]          - Optional logger for diagnostic output.
+ */
 export interface TLSConnectOptions {
     host: string;
     port: number;
-    /** Existing TCP socket to wrap (for proxy tunneling). */
     socket?: Socket;
-    /** Server name for SNI. Defaults to `host`. */
     servername?: string;
-    /** Skip certificate verification. */
     insecure?: boolean;
-    /** ALPN protocols to offer. Derived from profile if not given. */
     alpnProtocols?: string[];
-    /** Timeout for the TLS handshake in milliseconds. */
     timeout?: number;
-    /** Abort signal. */
     signal?: AbortSignal;
+    family?: 4 | 6;
     logger?: Logger;
 }
+/**
+ * Metadata describing a successfully negotiated TLS connection.
+ *
+ * @typedef  {Object}       TLSConnectionInfo
+ * @property {string}       version      - Negotiated TLS version string (e.g. `"TLSv1.3"`).
+ * @property {string|null}  alpnProtocol - Negotiated ALPN protocol (e.g. `"h2"`), or `null`.
+ * @property {string}       cipher       - Negotiated cipher suite name.
+ * @property {string}       [ja3Hash]    - JA3 fingerprint hash of the ClientHello, if computed.
+ */
 export interface TLSConnectionInfo {
-    /** Negotiated TLS protocol version, e.g. "TLSv1.3". */
     version: string;
-    /** Negotiated ALPN protocol, e.g. "h2" or "http/1.1". */
     alpnProtocol: string | null;
-    /** Negotiated cipher suite name. */
     cipher: string;
-    /** The JA3 hash of the ClientHello actually sent. */
     ja3Hash?: string;
 }
 /**
- * A TLS-encrypted duplex stream augmented with connection metadata.
+ * A duplex stream representing an established TLS connection. Extends
+ * `Duplex` with connection metadata and a controlled teardown method.
+ *
+ * @typedef  {Duplex}  TLSSocket
+ * @property {TLSConnectionInfo} connectionInfo - Metadata about the negotiated TLS session.
  */
 export interface TLSSocket extends Duplex {
-    /** Connection metadata (available after the handshake completes). */
     connectionInfo: TLSConnectionInfo;
-    /** Gracefully close the TLS connection. */
     destroyTLS(): void;
 }
 /**
- * Both the standard and stealth TLS engines implement this interface.
+ * Contract for TLS engine implementations. Both the standard Node.js TLS
+ * engine and the custom stealth engine implement this interface, allowing
+ * them to be substituted transparently by the {@link ProtocolNegotiator}.
  */
 export interface ITLSEngine {
-    /**
-     * Open a TLS connection to the given host:port.
-     *
-     * If a BrowserProfile is supplied the engine MUST configure TLS
-     * parameters (cipher suites, curves, extensions, ALPN) to match the
-     * profile so that the JA3 fingerprint is correct.
-     */
     connect(options: TLSConnectOptions, profile?: BrowserProfile): Promise<TLSSocket>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/tls/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tls/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,MAAM;IACvC,qEAAqE;IACrE,cAAc,EAAE,iBAAiB,CAAC;IAClC,2CAA2C;IAC3C,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tls/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAU,SAAQ,MAAM;IACvC,cAAc,EAAE,iBAAiB,CAAC;IAClC,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF"}

package/dist/tls/types.js

@@ -1,6 +1,2 @@
-/**
- * TLS engine types and the ITLSEngine interface that both standard
- * (node:tls) and stealth (raw handshake) engines implement.
- */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/tls/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tls/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tls/types.ts"],"names":[],"mappings":""}

package/dist/utils/buffer-reader.d.ts

@@ -1,31 +1,123 @@
 /**
- * Binary reader for parsing TLS records, HTTP/2 frames, and other
- * network protocol structures.  All multi-byte integers are read in
- * network byte order (big-endian) unless stated otherwise.
+ * Stateful cursor for reading typed values from a `Buffer` in big-endian byte
+ * order. Advances an internal position pointer after every read so callers
+ * don't need to track offsets manually.
+ *
+ * @example
+ * const r = new BufferReader(buf);
+ * const version = r.readUInt8();
+ * const length  = r.readUInt16();
+ * const payload = r.readBytes(length);
  */
 export declare class BufferReader {
     private _buf;
     private _pos;
+    /**
+     * Creates a new BufferReader.
+     *
+     * @param {Buffer} buf      - Buffer to read from.
+     * @param {number} [offset=0] - Initial cursor position.
+     */
     constructor(buf: Buffer, offset?: number);
+    /** Current byte offset of the read cursor. */
     get position(): number;
+    /** Number of bytes remaining after the current cursor position. */
     get remaining(): number;
+    /** Total length of the underlying buffer. */
     get length(): number;
+    /** The underlying `Buffer` instance. */
     get buffer(): Buffer;
+    /**
+     * Returns the next `length` bytes without advancing the cursor.
+     *
+     * @param {number} length - Number of bytes to peek at.
+     * @returns {Buffer} A view into the underlying buffer (not a copy).
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     peek(length: number): Buffer;
+    /**
+     * Reads one unsigned 8-bit integer and advances the cursor by 1.
+     *
+     * @returns {number} Unsigned byte value (0–255).
+     * @throws {RangeError} If fewer than 1 byte remains.
+     */
     readUInt8(): number;
+    /**
+     * Reads one big-endian unsigned 16-bit integer and advances the cursor by 2.
+     *
+     * @returns {number} Unsigned 16-bit value (0–65 535).
+     * @throws {RangeError} If fewer than 2 bytes remain.
+     */
     readUInt16(): number;
+    /**
+     * Reads one big-endian unsigned 24-bit integer and advances the cursor by 3.
+     *
+     * @returns {number} Unsigned 24-bit value (0–16 777 215).
+     * @throws {RangeError} If fewer than 3 bytes remain.
+     */
     readUInt24(): number;
+    /**
+     * Reads one big-endian unsigned 32-bit integer and advances the cursor by 4.
+     *
+     * @returns {number} Unsigned 32-bit value (0–4 294 967 295).
+     * @throws {RangeError} If fewer than 4 bytes remain.
+     */
     readUInt32(): number;
+    /**
+     * Reads `length` bytes into a new `Buffer` and advances the cursor.
+     *
+     * @param {number} length - Number of bytes to read.
+     * @returns {Buffer} Copy of the requested bytes.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     readBytes(length: number): Buffer;
-    /** Read a length-prefixed vector with 1-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * one-byte (8-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector8(): Buffer;
-    /** Read a length-prefixed vector with 2-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * big-endian two-byte (16-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector16(): Buffer;
-    /** Read a length-prefixed vector with 3-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * big-endian three-byte (24-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector24(): Buffer;
+    /**
+     * Advances the cursor by `length` bytes without returning the data.
+     *
+     * @param {number} length - Number of bytes to skip.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     skip(length: number): void;
+    /**
+     * Moves the cursor to an absolute byte position within the buffer.
+     *
+     * @param {number} position - Target byte offset (0 to `length` inclusive).
+     * @throws {RangeError} If `position` is negative or beyond the buffer length.
+     */
     seek(position: number): void;
-    /** Create a sub-reader over the next `length` bytes without copying. */
+    /**
+     * Reads `length` bytes from the current position and returns a new
+     * `BufferReader` positioned at offset 0 within that sub-slice. The parent
+     * cursor advances by `length` bytes.
+     *
+     * @param {number} length - Byte count to slice into the sub-reader.
+     * @returns {BufferReader} Reader over the requested sub-slice.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     subReader(length: number): BufferReader;
     private assertAvailable;
 }

package/dist/utils/buffer-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buffer-reader.d.ts","sourceRoot":"","sources":["../../src/utils/buffer-reader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU;IAK3C,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK5B,SAAS,IAAI,MAAM;IAOnB,UAAU,IAAI,MAAM;IAOpB,UAAU,IAAI,MAAM;IASpB,UAAU,IAAI,MAAM;IAOpB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOjC,8DAA8D;IAC9D,WAAW,IAAI,MAAM;IAKrB,8DAA8D;IAC9D,YAAY,IAAI,MAAM;IAKtB,8DAA8D;IAC9D,YAAY,IAAI,MAAM;IAKtB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK1B,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO5B,wEAAwE;IACxE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAOvC,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"buffer-reader.d.ts","sourceRoot":"","sources":["../../src/utils/buffer-reader.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IAErB;;;;;OAKG;gBACS,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU;IAK3C,8CAA8C;IAC9C,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,mEAAmE;IACnE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,6CAA6C;IAC7C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,wCAAwC;IACxC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK5B;;;;;OAKG;IACH,SAAS,IAAI,MAAM;IAOnB;;;;;OAKG;IACH,UAAU,IAAI,MAAM;IAOpB;;;;;OAKG;IACH,UAAU,IAAI,MAAM;IASpB;;;;;OAKG;IACH,UAAU,IAAI,MAAM;IAOpB;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOjC;;;;;;OAMG;IACH,WAAW,IAAI,MAAM;IAKrB;;;;;;OAMG;IACH,YAAY,IAAI,MAAM;IAKtB;;;;;;OAMG;IACH,YAAY,IAAI,MAAM;IAKtB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK1B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAOvC,OAAO,CAAC,eAAe;CAOxB"}

package/dist/utils/buffer-reader.js

@@ -1,43 +1,84 @@
 /**
- * Binary reader for parsing TLS records, HTTP/2 frames, and other
- * network protocol structures.  All multi-byte integers are read in
- * network byte order (big-endian) unless stated otherwise.
+ * Stateful cursor for reading typed values from a `Buffer` in big-endian byte
+ * order. Advances an internal position pointer after every read so callers
+ * don't need to track offsets manually.
+ *
+ * @example
+ * const r = new BufferReader(buf);
+ * const version = r.readUInt8();
+ * const length  = r.readUInt16();
+ * const payload = r.readBytes(length);
  */
 export class BufferReader {
     _buf;
     _pos;
+    /**
+     * Creates a new BufferReader.
+     *
+     * @param {Buffer} buf      - Buffer to read from.
+     * @param {number} [offset=0] - Initial cursor position.
+     */
     constructor(buf, offset = 0) {
         this._buf = buf;
         this._pos = offset;
     }
+    /** Current byte offset of the read cursor. */
     get position() {
         return this._pos;
     }
+    /** Number of bytes remaining after the current cursor position. */
     get remaining() {
         return this._buf.length - this._pos;
     }
+    /** Total length of the underlying buffer. */
     get length() {
         return this._buf.length;
     }
+    /** The underlying `Buffer` instance. */
     get buffer() {
         return this._buf;
     }
+    /**
+     * Returns the next `length` bytes without advancing the cursor.
+     *
+     * @param {number} length - Number of bytes to peek at.
+     * @returns {Buffer} A view into the underlying buffer (not a copy).
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     peek(length) {
         this.assertAvailable(length);
         return this._buf.subarray(this._pos, this._pos + length);
     }
+    /**
+     * Reads one unsigned 8-bit integer and advances the cursor by 1.
+     *
+     * @returns {number} Unsigned byte value (0–255).
+     * @throws {RangeError} If fewer than 1 byte remains.
+     */
     readUInt8() {
         this.assertAvailable(1);
         const v = this._buf[this._pos];
         this._pos += 1;
         return v;
     }
+    /**
+     * Reads one big-endian unsigned 16-bit integer and advances the cursor by 2.
+     *
+     * @returns {number} Unsigned 16-bit value (0–65 535).
+     * @throws {RangeError} If fewer than 2 bytes remain.
+     */
     readUInt16() {
         this.assertAvailable(2);
         const v = this._buf.readUInt16BE(this._pos);
         this._pos += 2;
         return v;
     }
+    /**
+     * Reads one big-endian unsigned 24-bit integer and advances the cursor by 3.
+     *
+     * @returns {number} Unsigned 24-bit value (0–16 777 215).
+     * @throws {RangeError} If fewer than 3 bytes remain.
+     */
     readUInt24() {
         this.assertAvailable(3);
         const b0 = this._buf[this._pos];
@@ -46,44 +87,95 @@ export class BufferReader {
         this._pos += 3;
         return (b0 << 16) | (b1 << 8) | b2;
     }
+    /**
+     * Reads one big-endian unsigned 32-bit integer and advances the cursor by 4.
+     *
+     * @returns {number} Unsigned 32-bit value (0–4 294 967 295).
+     * @throws {RangeError} If fewer than 4 bytes remain.
+     */
     readUInt32() {
         this.assertAvailable(4);
         const v = this._buf.readUInt32BE(this._pos);
         this._pos += 4;
         return v;
     }
+    /**
+     * Reads `length` bytes into a new `Buffer` and advances the cursor.
+     *
+     * @param {number} length - Number of bytes to read.
+     * @returns {Buffer} Copy of the requested bytes.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     readBytes(length) {
         this.assertAvailable(length);
         const slice = Buffer.from(this._buf.subarray(this._pos, this._pos + length));
         this._pos += length;
         return slice;
     }
-    /** Read a length-prefixed vector with 1-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * one-byte (8-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector8() {
         const len = this.readUInt8();
         return this.readBytes(len);
     }
-    /** Read a length-prefixed vector with 2-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * big-endian two-byte (16-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector16() {
         const len = this.readUInt16();
         return this.readBytes(len);
     }
-    /** Read a length-prefixed vector with 3-byte length field. */
+    /**
+     * Reads a length-prefixed byte vector where the length is encoded as a
+     * big-endian three-byte (24-bit) unsigned integer immediately preceding the data.
+     *
+     * @returns {Buffer} The vector payload bytes.
+     * @throws {RangeError} If insufficient bytes remain.
+     */
     readVector24() {
         const len = this.readUInt24();
         return this.readBytes(len);
     }
+    /**
+     * Advances the cursor by `length` bytes without returning the data.
+     *
+     * @param {number} length - Number of bytes to skip.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     skip(length) {
         this.assertAvailable(length);
         this._pos += length;
     }
+    /**
+     * Moves the cursor to an absolute byte position within the buffer.
+     *
+     * @param {number} position - Target byte offset (0 to `length` inclusive).
+     * @throws {RangeError} If `position` is negative or beyond the buffer length.
+     */
     seek(position) {
         if (position < 0 || position > this._buf.length) {
             throw new RangeError(`Seek position ${position} out of bounds [0, ${this._buf.length}]`);
         }
         this._pos = position;
     }
-    /** Create a sub-reader over the next `length` bytes without copying. */
+    /**
+     * Reads `length` bytes from the current position and returns a new
+     * `BufferReader` positioned at offset 0 within that sub-slice. The parent
+     * cursor advances by `length` bytes.
+     *
+     * @param {number} length - Byte count to slice into the sub-reader.
+     * @returns {BufferReader} Reader over the requested sub-slice.
+     * @throws {RangeError} If `length` bytes are not available.
+     */
     subReader(length) {
         this.assertAvailable(length);
         const sub = new BufferReader(this._buf.subarray(this._pos, this._pos + length));