nlcurl 0.7.0 → 0.9.0

package/dist/tls/ocsp.d.ts

@@ -0,0 +1,55 @@
+/** OCSP response status codes (RFC 6960). */
+export declare enum OCSPResponseStatus {
+    SUCCESSFUL = 0,
+    MALFORMED_REQUEST = 1,
+    INTERNAL_ERROR = 2,
+    TRY_LATER = 3,
+    SIG_REQUIRED = 5,
+    UNAUTHORIZED = 6
+}
+/** Certificate revocation status from an OCSP response. */
+export declare enum OCSPCertStatus {
+    GOOD = 0,
+    REVOKED = 1,
+    UNKNOWN = 2
+}
+/** Parsed result of an OCSP response. */
+export interface OCSPResult {
+    /** Overall OCSP response status. */
+    status: OCSPResponseStatus;
+    /** Revocation status of the queried certificate. */
+    certStatus?: OCSPCertStatus;
+    /** Start of the validity window for this response. */
+    thisUpdate?: Date;
+    /** End of the validity window for this response. */
+    nextUpdate?: Date;
+    /** Time when the OCSP responder produced this response. */
+    producedAt?: Date;
+}
+/**
+ * Parse a DER-encoded OCSP response.
+ *
+ * @param {Buffer} derResponse - Raw DER bytes.
+ * @returns {OCSPResult} Parsed OCSP result.
+ */
+export declare function parseOCSPResponse(derResponse: Buffer): OCSPResult;
+/**
+ * Check whether an OCSP result indicates the certificate is valid.
+ *
+ * @param {OCSPResult} result - Parsed OCSP result.
+ * @returns {boolean} `false` only if the certificate is explicitly revoked.
+ */
+export declare function isOCSPValid(result: OCSPResult): boolean;
+/**
+ * Validate OCSP stapling on a TLS socket.
+ *
+ * @param {{ once(event: string, handler: (...args: any[]) => void): void }} socket - Socket emitter that fires an `"OCSPResponse"` event.
+ * @param {{ timeout?: number }} [options] - Optional timeout configuration.
+ * @returns {Promise<OCSPResult|undefined>} Parsed OCSP result, or `undefined` if no stapled response.
+ */
+export declare function validateOCSPStapling(socket: {
+    once(event: string, handler: (...args: any[]) => void): void;
+}, options?: {
+    timeout?: number;
+}): Promise<OCSPResult | undefined>;
+//# sourceMappingURL=ocsp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ocsp.d.ts","sourceRoot":"","sources":["../../src/tls/ocsp.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,oBAAY,kBAAkB;IAC5B,UAAU,IAAI;IACd,iBAAiB,IAAI;IACrB,cAAc,IAAI;IAClB,SAAS,IAAI;IACb,YAAY,IAAI;IAChB,YAAY,IAAI;CACjB;AAED,2DAA2D;AAC3D,oBAAY,cAAc;IACxB,IAAI,IAAI;IACR,OAAO,IAAI;IACX,OAAO,IAAI;CACZ;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,oDAAoD;IACpD,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,sDAAsD;IACtD,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,oDAAoD;IACpD,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAuCjE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAQvD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;CAAE,EAAE,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAoB9K"}

package/dist/tls/ocsp.js

@@ -0,0 +1,131 @@
+/** OCSP response status codes (RFC 6960). */
+export var OCSPResponseStatus;
+(function (OCSPResponseStatus) {
+    OCSPResponseStatus[OCSPResponseStatus["SUCCESSFUL"] = 0] = "SUCCESSFUL";
+    OCSPResponseStatus[OCSPResponseStatus["MALFORMED_REQUEST"] = 1] = "MALFORMED_REQUEST";
+    OCSPResponseStatus[OCSPResponseStatus["INTERNAL_ERROR"] = 2] = "INTERNAL_ERROR";
+    OCSPResponseStatus[OCSPResponseStatus["TRY_LATER"] = 3] = "TRY_LATER";
+    OCSPResponseStatus[OCSPResponseStatus["SIG_REQUIRED"] = 5] = "SIG_REQUIRED";
+    OCSPResponseStatus[OCSPResponseStatus["UNAUTHORIZED"] = 6] = "UNAUTHORIZED";
+})(OCSPResponseStatus || (OCSPResponseStatus = {}));
+/** Certificate revocation status from an OCSP response. */
+export var OCSPCertStatus;
+(function (OCSPCertStatus) {
+    OCSPCertStatus[OCSPCertStatus["GOOD"] = 0] = "GOOD";
+    OCSPCertStatus[OCSPCertStatus["REVOKED"] = 1] = "REVOKED";
+    OCSPCertStatus[OCSPCertStatus["UNKNOWN"] = 2] = "UNKNOWN";
+})(OCSPCertStatus || (OCSPCertStatus = {}));
+/**
+ * Parse a DER-encoded OCSP response.
+ *
+ * @param {Buffer} derResponse - Raw DER bytes.
+ * @returns {OCSPResult} Parsed OCSP result.
+ */
+export function parseOCSPResponse(derResponse) {
+    if (!derResponse || derResponse.length < 3) {
+        return { status: OCSPResponseStatus.MALFORMED_REQUEST };
+    }
+    let offset = 0;
+    if (derResponse[offset] !== 0x30) {
+        return { status: OCSPResponseStatus.MALFORMED_REQUEST };
+    }
+    offset++;
+    const { value: outerLen, bytesRead: outerLenBytes } = readASN1Length(derResponse, offset);
+    if (outerLen === -1)
+        return { status: OCSPResponseStatus.MALFORMED_REQUEST };
+    offset += outerLenBytes;
+    if (derResponse[offset] !== 0x0a) {
+        return { status: OCSPResponseStatus.MALFORMED_REQUEST };
+    }
+    offset++;
+    const statusLen = derResponse[offset];
+    offset++;
+    if (statusLen !== 1 || offset >= derResponse.length) {
+        return { status: OCSPResponseStatus.MALFORMED_REQUEST };
+    }
+    const responseStatus = derResponse[offset];
+    offset++;
+    if (responseStatus !== OCSPResponseStatus.SUCCESSFUL) {
+        return { status: responseStatus };
+    }
+    const result = { status: responseStatus };
+    const certStatusResult = findCertStatus(derResponse, offset);
+    if (certStatusResult !== undefined) {
+        result.certStatus = certStatusResult;
+    }
+    return result;
+}
+/**
+ * Check whether an OCSP result indicates the certificate is valid.
+ *
+ * @param {OCSPResult} result - Parsed OCSP result.
+ * @returns {boolean} `false` only if the certificate is explicitly revoked.
+ */
+export function isOCSPValid(result) {
+    if (result.status !== OCSPResponseStatus.SUCCESSFUL) {
+        return true;
+    }
+    if (result.certStatus === OCSPCertStatus.REVOKED) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validate OCSP stapling on a TLS socket.
+ *
+ * @param {{ once(event: string, handler: (...args: any[]) => void): void }} socket - Socket emitter that fires an `"OCSPResponse"` event.
+ * @param {{ timeout?: number }} [options] - Optional timeout configuration.
+ * @returns {Promise<OCSPResult|undefined>} Parsed OCSP result, or `undefined` if no stapled response.
+ */
+export function validateOCSPStapling(socket, options) {
+    return new Promise((resolve) => {
+        const timeout = options?.timeout ?? 5000;
+        let timer;
+        const onResponse = (response) => {
+            if (timer)
+                clearTimeout(timer);
+            if (!response || response.length === 0) {
+                resolve(undefined);
+                return;
+            }
+            resolve(parseOCSPResponse(response));
+        };
+        socket.once("OCSPResponse", onResponse);
+        timer = setTimeout(() => {
+            resolve(undefined);
+        }, timeout);
+    });
+}
+function readASN1Length(buf, offset) {
+    if (offset >= buf.length)
+        return { value: -1, bytesRead: 0 };
+    const first = buf[offset];
+    if (first < 0x80) {
+        return { value: first, bytesRead: 1 };
+    }
+    const numBytes = first & 0x7f;
+    if (numBytes === 0 || numBytes > 4 || offset + numBytes >= buf.length) {
+        return { value: -1, bytesRead: 0 };
+    }
+    let value = 0;
+    for (let i = 0; i < numBytes; i++) {
+        value = (value << 8) | buf[offset + 1 + i];
+    }
+    return { value, bytesRead: 1 + numBytes };
+}
+function findCertStatus(buf, startOffset) {
+    for (let i = startOffset; i < buf.length - 2; i++) {
+        const tag = buf[i];
+        if (tag === 0x80 && buf[i + 1] === 0x00) {
+            return OCSPCertStatus.GOOD;
+        }
+        if (tag === 0xa1) {
+            return OCSPCertStatus.REVOKED;
+        }
+        if (tag === 0x82 && buf[i + 1] === 0x00) {
+            return OCSPCertStatus.UNKNOWN;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=ocsp.js.map

package/dist/tls/ocsp.js.map

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

package/dist/tls/pin-verification.d.ts

@@ -1,9 +1,10 @@
 /**
- * Verifies that the leaf certificate's SPKI SHA-256 hash matches at least
- * one of the supplied pins. Throws {@link TLSError} on mismatch.
+ * Verify that a certificate's SPKI hash matches at least one expected pin.
  *
- * @param certDer  DER-encoded leaf certificate bytes.
- * @param pins     One or more pins in `"sha256//base64hash"` format.
+ * Throws a {@link TLSError} if no pin matches.
+ *
+ * @param {Buffer} certDer - DER-encoded X.509 certificate.
+ * @param {string|string[]} pins - One or more `sha256//` base64-encoded SPKI pins.
  */
 export declare function verifyPinnedPublicKey(certDer: Buffer, pins: string | string[]): void;
 //# sourceMappingURL=pin-verification.d.ts.map

package/dist/tls/pin-verification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pin-verification.d.ts","sourceRoot":"","sources":["../../src/tls/pin-verification.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAiBpF"}
+{"version":3,"file":"pin-verification.d.ts","sourceRoot":"","sources":["../../src/tls/pin-verification.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAiBpF"}

package/dist/tls/pin-verification.js

@@ -1,18 +1,12 @@
-/**
- * Certificate public key pinning (RFC 7469 concept, curl-style format).
- *
- * Verifies that a server's leaf certificate matches one of a set of
- * SHA-256 hashes computed over the DER-encoded Subject Public Key Info
- * (SPKI). Pin format: `"sha256//base64hash"` (same as curl `--pinnedpubkey`).
- */
 import { createHash, X509Certificate } from "node:crypto";
 import { TLSError } from "../core/errors.js";
 /**
- * Verifies that the leaf certificate's SPKI SHA-256 hash matches at least
- * one of the supplied pins. Throws {@link TLSError} on mismatch.
+ * Verify that a certificate's SPKI hash matches at least one expected pin.
+ *
+ * Throws a {@link TLSError} if no pin matches.
  *
- * @param certDer  DER-encoded leaf certificate bytes.
- * @param pins     One or more pins in `"sha256//base64hash"` format.
+ * @param {Buffer} certDer - DER-encoded X.509 certificate.
+ * @param {string|string[]} pins - One or more `sha256//` base64-encoded SPKI pins.
  */
 export function verifyPinnedPublicKey(certDer, pins) {
     const pinArray = typeof pins === "string" ? [pins] : pins;

package/dist/tls/pin-verification.js.map

@@ -1 +1 @@
-{"version":3,"file":"pin-verification.js","sourceRoot":"","sources":["../../src/tls/pin-verification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,IAAuB;IAC5E,MAAM,QAAQ,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElC,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACjF,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,WAAW,IAAI,EAAE,CAAC;IAElC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QACpC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9C,OAAO,GAAG,KAAK,OAAO,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,oDAAoD,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC"}
+{"version":3,"file":"pin-verification.js","sourceRoot":"","sources":["../../src/tls/pin-verification.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,IAAuB;IAC5E,MAAM,QAAQ,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElC,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACjF,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,WAAW,IAAI,EAAE,CAAC;IAElC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QACpC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9C,OAAO,GAAG,KAAK,OAAO,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,oDAAoD,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/tls/session-cache.d.ts

@@ -1,70 +1,58 @@
-/**
- * TLS session ticket cache for session resumption (RFC 5077 / RFC 8446 §4.6.1).
- * Stores session tickets keyed by origin (`host:port`) and evicts expired
- * entries automatically. Used by both {@link NodeTLSEngine} and
- * {@link StealthTLSEngine} to enable 0-RTT and abbreviated handshakes.
- */
-/**
- * A cached TLS session ticket with its expiration metadata.
- *
- * @typedef  {Object} SessionTicketEntry
- * @property {Buffer} ticket    - Opaque session ticket bytes.
- * @property {number} expiresAt - Unix timestamp (ms) at which the ticket is no longer valid.
- * @property {string} [alpn]    - ALPN protocol negotiated during the original handshake.
- */
+/** Cached TLS session ticket with expiry and ALPN metadata. */
 export interface SessionTicketEntry {
+    /** Serialized session ticket bytes. */
     ticket: Buffer;
+    /** Timestamp (ms since epoch) when this entry expires. */
     expiresAt: number;
+    /** ALPN protocol negotiated during the original handshake. */
     alpn?: string;
 }
-/**
- * Options for constructing a {@link TLSSessionCache}.
- *
- * @typedef  {Object} SessionCacheOptions
- * @property {number} [maxEntries=256]      - Maximum number of tickets to store.
- * @property {number} [defaultLifetimeMs=7200000] - Default ticket lifetime in ms when server doesn't specify.
- */
+/** Configuration for the TLS session ticket cache. */
 export interface SessionCacheOptions {
+    /** Maximum number of cached entries. */
     maxEntries?: number;
+    /** Default ticket lifetime in milliseconds. */
     defaultLifetimeMs?: number;
 }
-/**
- * In-memory LRU cache for TLS session tickets. Thread-safe for single-threaded
- * Node.js usage. Keys are `host:port` origin strings. Only valid (non-expired)
- * tickets are returned on lookup.
- */
+/** LRU cache for TLS session tickets enabling session resumption. */
 export declare class TLSSessionCache {
     private readonly maxEntries;
     private readonly defaultLifetimeMs;
     private readonly entries;
+    /**
+     * Create a new session cache.
+     *
+     * @param {SessionCacheOptions} [options] - Cache size and lifetime configuration.
+     */
     constructor(options?: SessionCacheOptions);
     /**
-     * Stores a session ticket for the given origin.
+     * Store a session ticket for the given origin.
      *
-     * @param {string} origin   - Origin key in `host:port` form.
-     * @param {Buffer} ticket   - Opaque session ticket bytes.
-     * @param {number} [lifetimeMs] - Ticket lifetime in ms; uses default if omitted.
-     * @param {string} [alpn]   - ALPN protocol from the original handshake.
+     * @param {string} origin - Origin key (e.g. `"example.com:443"`).
+     * @param {Buffer} ticket - Serialized session ticket.
+     * @param {number} [lifetimeMs] - Optional custom lifetime in milliseconds.
+     * @param {string} [alpn] - Negotiated ALPN protocol.
      */
     set(origin: string, ticket: Buffer, lifetimeMs?: number, alpn?: string): void;
     /**
-     * Retrieves a valid, non-expired session ticket for the given origin.
-     * Returns `undefined` if no ticket exists or the ticket has expired.
+     * Retrieve a cached session ticket.
      *
-     * @param {string} origin - Origin key in `host:port` form.
-     * @returns {SessionTicketEntry | undefined}
+     * Expired entries are evicted automatically.
+     *
+     * @param {string} origin - Origin key.
+     * @returns {SessionTicketEntry|undefined} Cached entry, or `undefined` if not found or expired.
      */
     get(origin: string): SessionTicketEntry | undefined;
     /**
-     * Removes a specific ticket from the cache.
+     * Remove a cached entry by origin.
      *
      * @param {string} origin - Origin key.
-     * @returns {boolean} Whether an entry was removed.
+     * @returns {boolean} `true` if an entry was removed.
      */
     delete(origin: string): boolean;
-    /** Removes all entries from the cache. */
+    /** Remove all cached session tickets. */
     clear(): void;
-    /** Returns the number of entries currently cached. */
+    /** Number of entries currently in the cache. */
     get size(): number;
 }
 //# sourceMappingURL=session-cache.d.ts.map

package/dist/tls/session-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/tls/session-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;gBAErD,OAAO,GAAE,mBAAwB;IAK7C;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAc7E;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAcnD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI/B,0CAA0C;IAC1C,KAAK,IAAI,IAAI;IAIb,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
+{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/tls/session-cache.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qEAAqE;AACrE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;OAIG;gBACS,OAAO,GAAE,mBAAwB;IAK7C;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAc7E;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAcnD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI/B,yCAAyC;IACzC,KAAK,IAAI,IAAI;IAIb,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/tls/session-cache.js

@@ -1,31 +1,26 @@
-/**
- * TLS session ticket cache for session resumption (RFC 5077 / RFC 8446 §4.6.1).
- * Stores session tickets keyed by origin (`host:port`) and evicts expired
- * entries automatically. Used by both {@link NodeTLSEngine} and
- * {@link StealthTLSEngine} to enable 0-RTT and abbreviated handshakes.
- */
 const DEFAULT_MAX_ENTRIES = 256;
 const DEFAULT_LIFETIME_MS = 7200_000;
-/**
- * In-memory LRU cache for TLS session tickets. Thread-safe for single-threaded
- * Node.js usage. Keys are `host:port` origin strings. Only valid (non-expired)
- * tickets are returned on lookup.
- */
+/** LRU cache for TLS session tickets enabling session resumption. */
 export class TLSSessionCache {
     maxEntries;
     defaultLifetimeMs;
     entries = new Map();
+    /**
+     * Create a new session cache.
+     *
+     * @param {SessionCacheOptions} [options] - Cache size and lifetime configuration.
+     */
     constructor(options = {}) {
         this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
         this.defaultLifetimeMs = options.defaultLifetimeMs ?? DEFAULT_LIFETIME_MS;
     }
     /**
-     * Stores a session ticket for the given origin.
+     * Store a session ticket for the given origin.
      *
-     * @param {string} origin   - Origin key in `host:port` form.
-     * @param {Buffer} ticket   - Opaque session ticket bytes.
-     * @param {number} [lifetimeMs] - Ticket lifetime in ms; uses default if omitted.
-     * @param {string} [alpn]   - ALPN protocol from the original handshake.
+     * @param {string} origin - Origin key (e.g. `"example.com:443"`).
+     * @param {Buffer} ticket - Serialized session ticket.
+     * @param {number} [lifetimeMs] - Optional custom lifetime in milliseconds.
+     * @param {string} [alpn] - Negotiated ALPN protocol.
      */
     set(origin, ticket, lifetimeMs, alpn) {
         if (this.entries.size >= this.maxEntries) {
@@ -41,11 +36,12 @@ export class TLSSessionCache {
         });
     }
     /**
-     * Retrieves a valid, non-expired session ticket for the given origin.
-     * Returns `undefined` if no ticket exists or the ticket has expired.
+     * Retrieve a cached session ticket.
      *
-     * @param {string} origin - Origin key in `host:port` form.
-     * @returns {SessionTicketEntry | undefined}
+     * Expired entries are evicted automatically.
+     *
+     * @param {string} origin - Origin key.
+     * @returns {SessionTicketEntry|undefined} Cached entry, or `undefined` if not found or expired.
      */
     get(origin) {
         const entry = this.entries.get(origin);
@@ -60,19 +56,19 @@ export class TLSSessionCache {
         return entry;
     }
     /**
-     * Removes a specific ticket from the cache.
+     * Remove a cached entry by origin.
      *
      * @param {string} origin - Origin key.
-     * @returns {boolean} Whether an entry was removed.
+     * @returns {boolean} `true` if an entry was removed.
      */
     delete(origin) {
         return this.entries.delete(origin);
     }
-    /** Removes all entries from the cache. */
+    /** Remove all cached session tickets. */
     clear() {
         this.entries.clear();
     }
-    /** Returns the number of entries currently cached. */
+    /** Number of entries currently in the cache. */
     get size() {
         return this.entries.size;
     }

package/dist/tls/session-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-cache.js","sourceRoot":"","sources":["../../src/tls/session-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAcrC;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACT,UAAU,CAAS;IACnB,iBAAiB,CAAS;IAC1B,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEjE,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,mBAAmB,CAAC;IAC5E,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,MAAc,EAAE,MAAc,EAAE,UAAmB,EAAE,IAAa;QACpE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;YACvB,MAAM;YACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,iBAAiB,CAAC;YAC9D,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,MAAc;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,0CAA0C;IAC1C,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,sDAAsD;IACtD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"session-cache.js","sourceRoot":"","sources":["../../src/tls/session-cache.ts"],"names":[],"mappings":"AAUA,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAUrC,qEAAqE;AACrE,MAAM,OAAO,eAAe;IACT,UAAU,CAAS;IACnB,iBAAiB,CAAS;IAC1B,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEjE;;;;OAIG;IACH,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,mBAAmB,CAAC;IAC5E,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,MAAc,EAAE,MAAc,EAAE,UAAmB,EAAE,IAAa;QACpE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;YACvB,MAAM;YACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,iBAAiB,CAAC;YAC9D,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,MAAc;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,yCAAyC;IACzC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/tls/stealth/client-hello.d.ts

@@ -1,75 +1,56 @@
 import type { BrowserProfile } from "../../fingerprints/types.js";
 import type { ECHEncryptionParams } from "../ech.js";
-/**
- * An ephemeral key share generated for a specific named group, used during
- * TLS 1.3 key exchange. Contains both the public key to advertise in the
- * ClientHello and the private key required to compute the shared secret.
- *
- * @typedef  {Object} KeyShareEntry
- * @property {number} group      - Named group code (e.g. `NamedGroup.X25519`).
- * @property {Buffer} publicKey  - Raw public key bytes to include in the key_share extension.
- * @property {Buffer} privateKey - Raw private key bytes used for ECDH computation.
- */
+/** Key exchange entry containing the group identifier and key material. */
 export interface KeyShareEntry {
+    /** Named group identifier. */
     group: number;
+    /** Public key bytes. */
     publicKey: Buffer;
+    /** Private key bytes. */
     privateKey: Buffer;
 }
 /**
- * Generates an ephemeral key pair for the specified named group. Supports
- * X25519, SECP256R1, SECP384R1, and SECP521R1.
- *
- * @param {number} group - Named group code from the {@link NamedGroup} enum.
- * @returns {KeyShareEntry} The generated key pair with group identifier.
- * @throws {Error} If the specified group is not supported.
- */
-export declare function generateKeyShare(group: number): KeyShareEntry;
-/**
- * Carries the outputs of {@link buildClientHello} that must be retained
- * for subsequent handshake processing.
+ * Generate a key pair for the specified TLS named group.
  *
- * @typedef  {Object}           ClientHelloResult
- * @property {Buffer}           record            - The complete TLS record containing the ClientHello.
- * @property {KeyShareEntry[]}  keyShares          - Generated key shares (private keys needed for key derivation).
- * @property {Buffer}           clientRandom       - 32-byte client random included in the ClientHello body.
- * @property {Buffer}           sessionId          - Legacy session ID bytes (may be empty).
- * @property {Buffer}           handshakeMessage   - The raw handshake message body (used for transcript hashing).
+ * @param {number} group - Named group identifier (e.g. X25519, SECP256R1).
+ * @returns {KeyShareEntry} Key share entry with public and private key material.
  */
+export declare function generateKeyShare(group: number): KeyShareEntry | null;
+/** Result of building a TLS ClientHello message. */
 export interface ClientHelloResult {
+    /** Complete TLS record containing the ClientHello. */
     record: Buffer;
+    /** Generated key share entries. */
     keyShares: KeyShareEntry[];
+    /** Client random bytes. */
     clientRandom: Buffer;
+    /** Session ID bytes (may be empty). */
     sessionId: Buffer;
+    /** Raw handshake message (without record layer). */
     handshakeMessage: Buffer;
 }
 /**
- * Constructs a binary TLS 1.3 ClientHello record that mirrors the exact byte
- * structure produced by the given browser profile, including GREASE injection,
- * key share generation, and extension ordering.
+ * Build a TLS ClientHello record matching a browser fingerprint profile.
  *
- * @param {BrowserProfile} profile  - The browser profile whose TLS fingerprint to replicate.
- * @param {string}         hostname - The SNI hostname to include in the server_name extension.
- * @returns {ClientHelloResult} The encoded record alongside key material needed for the handshake.
+ * @param {BrowserProfile} profile - Browser profile with TLS extension ordering and cipher suites.
+ * @param {string} hostname - Server hostname for SNI.
+ * @returns {ClientHelloResult} ClientHello result with record bytes and key material.
  */
 export declare function buildClientHello(profile: BrowserProfile, hostname: string): ClientHelloResult;
-/**
- * Result of building an ECH-encrypted ClientHello pair.
- */
+/** Extended ClientHello result with Encrypted Client Hello inner message. */
 export interface ClientHelloECHResult extends ClientHelloResult {
-    /** Inner ClientHello handshake message (used for transcript if ECH is accepted). */
+    /** Raw inner ClientHello handshake message before encryption. */
     innerHandshakeMessage: Buffer;
-    /** Inner client random (used for ECH accept confirmation check). */
+    /** Client random used in the inner ClientHello. */
     innerRandom: Buffer;
 }
 /**
- * Builds a ClientHello pair with ECH encryption: an outer ClientHello
- * (with the encrypted inner ClientHello in the ECH extension) and the
- * inner ClientHello needed for transcript computation upon acceptance.
+ * Build a TLS ClientHello with Encrypted Client Hello (ECH) wrapping.
  *
- * @param profile     Browser profile whose fingerprint to replicate.
- * @param hostname    Real server hostname (used in the inner ClientHello SNI).
- * @param echParams   ECH config and raw bytes for HPKE encryption.
- * @returns The outer record to send plus the inner message for the transcript.
+ * @param {BrowserProfile} profile - Browser fingerprint profile.
+ * @param {string} hostname - True server hostname (encrypted in the inner ClientHello).
+ * @param {ECHEncryptionParams} echParams - ECH encryption parameters.
+ * @returns {ClientHelloECHResult} Extended result with both outer and inner handshake data.
  */
 export declare function buildClientHelloWithECH(profile: BrowserProfile, hostname: string, echParams: ECHEncryptionParams): ClientHelloECHResult;
 //# sourceMappingURL=client-hello.d.ts.map

package/dist/tls/stealth/client-hello.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-hello.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/client-hello.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,6BAA6B,CAAC;AACnF,OAAO,KAAK,EAAa,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOhE;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAyB7D;AAiBD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA2E7F;AA6CD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,oFAAoF;IACpF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,GAAG,oBAAoB,CA8DvI"}
+{"version":3,"file":"client-hello.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/client-hello.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,6BAA6B,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOrD,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAyBpE;AAiBD,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA2E7F;AA6CD,6EAA6E;AAC7E,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,GAAG,oBAAoB,CA8DvI"}