nlcurl 0.1.0 → 0.2.0

package/dist/tls/stealth/engine.d.ts

@@ -1,16 +1,24 @@
-/**
- * Stealth TLS engine.
- *
- * Implements ITLSEngine using raw TCP sockets and manual TLS 1.3
- * handshake construction.  This gives 100% control over the
- * ClientHello bytes, enabling perfect JA3 fingerprint matching.
- *
- * After the handshake completes, wraps the raw socket in a Duplex
- * stream that transparently encrypts/decrypts application data.
- */
 import type { ITLSEngine, TLSConnectOptions, TLSSocket } from '../types.js';
 import type { BrowserProfile } from '../../fingerprints/types.js';
+/**
+ * TLS engine that performs a fully custom TLS 1.3 handshake at the byte
+ * level, producing ClientHello messages that exactly match the fingerprint
+ * of the given browser profile — including GREASE values, extension ordering,
+ * key share groups, and cipher suite ordering. Unlike {@link NodeTLSEngine},
+ * this engine bypasses Node.js’s native `tls` module entirely.
+ */
 export declare class StealthTLSEngine implements ITLSEngine {
+    /**
+     * Establishes a TLS 1.3 connection using the custom stealth handshake engine.
+     * Opens a raw TCP socket (or reuses a pre-connected socket from `options.socket`),
+     * performs the full TLS 1.3 handshake matching `profile`, and wraps the socket
+     * in an encrypted duplex stream.
+     *
+     * @param {TLSConnectOptions} options  - Connection parameters (host, port, SNI, etc.).
+     * @param {BrowserProfile}    [profile] - Browser profile to impersonate; falls back to `DEFAULT_PROFILE`.
+     * @returns {Promise<TLSSocket>} Resolves with the encrypted duplex stream.
+     * @throws {TLSError} If the handshake fails, times out, or the connection is rejected.
+     */
     connect(options: TLSConnectOptions, profile?: BrowserProfile): Promise<TLSSocket>;
 }
 //# sourceMappingURL=engine.d.ts.map

package/dist/tls/stealth/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAqB,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAyJlE,qBAAa,gBAAiB,YAAW,UAAU;IAC3C,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC;CA2BtB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/engine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAqB,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA8IlE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD;;;;;;;;;;OAUG;IACG,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC;CAwBtB"}

package/dist/tls/stealth/engine.js

@@ -1,13 +1,3 @@
-/**
- * Stealth TLS engine.
- *
- * Implements ITLSEngine using raw TCP sockets and manual TLS 1.3
- * handshake construction.  This gives 100% control over the
- * ClientHello bytes, enabling perfect JA3 fingerprint matching.
- *
- * After the handshake completes, wraps the raw socket in a Duplex
- * stream that transparently encrypts/decrypts application data.
- */
 import * as net from 'node:net';
 import { Duplex } from 'node:stream';
 import { TLSError } from '../../core/errors.js';
@@ -15,10 +5,6 @@ import { performHandshake } from './handshake.js';
 import { wrapEncryptedRecord, unwrapEncryptedRecord, readRecord, } from './record-layer.js';
 import { RecordType } from '../constants.js';
 import { DEFAULT_PROFILE } from '../../fingerprints/database.js';
-/**
- * A Duplex stream that wraps encrypted TLS 1.3 application data
- * over a raw TCP socket.
- */
 class StealthTLSStream extends Duplex {
     rawSocket;
     aead;
@@ -44,7 +30,6 @@ class StealthTLSStream extends Duplex {
             alpnProtocol: handshake.alpnProtocol,
             cipher: handshake.cipher,
         };
-        // Wire up raw socket events
         rawSocket.on('data', (chunk) => this.handleRawData(chunk));
         rawSocket.on('error', (err) => this.destroy(err));
         rawSocket.once('close', () => {
@@ -53,7 +38,6 @@ class StealthTLSStream extends Duplex {
         });
     }
     _read() {
-        // Data is pushed from handleRawData; no action needed
     }
     _write(chunk, _encoding, callback) {
         try {
@@ -93,14 +77,12 @@ class StealthTLSStream extends Duplex {
                         const level = decrypted.plaintext[0];
                         const desc = decrypted.plaintext[1];
                         if (desc === 0) {
-                            // close_notify
                             this.push(null);
                         }
                         else {
                             this.destroy(new TLSError(`TLS alert: level=${level} desc=${desc}`, desc));
                         }
                     }
-                    // Handshake messages (e.g. NewSessionTicket) are silently ignored
                 }
                 catch (err) {
                     this.destroy(err instanceof Error ? err : new Error(String(err)));
@@ -116,23 +98,36 @@ class StealthTLSStream extends Duplex {
                     this.destroy(new TLSError(`Unencrypted alert: desc=${desc}`, desc));
                 }
             }
-            // Ignore other record types
         }
     }
 }
-// ---- Engine ----
+/**
+ * TLS engine that performs a fully custom TLS 1.3 handshake at the byte
+ * level, producing ClientHello messages that exactly match the fingerprint
+ * of the given browser profile — including GREASE values, extension ordering,
+ * key share groups, and cipher suite ordering. Unlike {@link NodeTLSEngine},
+ * this engine bypasses Node.js’s native `tls` module entirely.
+ */
 export class StealthTLSEngine {
+    /**
+     * Establishes a TLS 1.3 connection using the custom stealth handshake engine.
+     * Opens a raw TCP socket (or reuses a pre-connected socket from `options.socket`),
+     * performs the full TLS 1.3 handshake matching `profile`, and wraps the socket
+     * in an encrypted duplex stream.
+     *
+     * @param {TLSConnectOptions} options  - Connection parameters (host, port, SNI, etc.).
+     * @param {BrowserProfile}    [profile] - Browser profile to impersonate; falls back to `DEFAULT_PROFILE`.
+     * @returns {Promise<TLSSocket>} Resolves with the encrypted duplex stream.
+     * @throws {TLSError} If the handshake fails, times out, or the connection is rejected.
+     */
     async connect(options, profile) {
         const effectiveProfile = profile ?? DEFAULT_PROFILE;
         const hostname = options.servername ?? options.host;
-        // Establish TCP connection (or use pre-connected socket)
         const rawSocket = options.socket
             ? options.socket
             : await tcpConnect(options.host, options.port, options.timeout, options.signal);
         try {
-            // Perform TLS 1.3 handshake
             const handshake = await performHandshake(rawSocket, effectiveProfile, hostname, options.insecure ?? false);
-            // Wrap in Duplex stream
             const stream = new StealthTLSStream(rawSocket, handshake);
             return stream;
         }
@@ -142,7 +137,6 @@ export class StealthTLSEngine {
         }
     }
 }
-// ---- TCP connection helper ----
 function tcpConnect(host, port, timeout, signal) {
     return new Promise((resolve, reject) => {
         let settled = false;

package/dist/tls/stealth/engine.js.map

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

package/dist/tls/stealth/handshake.d.ts

@@ -1,15 +1,12 @@
-/**
- * TLS 1.3 handshake state machine.
- *
- * Manages the full TLS 1.3 handshake flow:
- *   ClientHello -> ServerHello -> {EncryptedExtensions, Certificate,
- *   CertificateVerify, Finished} -> client Finished -> Application Data
- *
- * All crypto operations use `node:crypto`; no external dependencies.
- */
 import * as net from 'node:net';
 import type { BrowserProfile } from '../../fingerprints/types.js';
 import { type AEADAlgorithm } from './record-layer.js';
+/**
+ * Tracks the sequential state of a TLS 1.3 handshake as messages are parsed.
+ * Used internally by {@link performHandshake} to enforce message ordering.
+ *
+ * @enum {number}
+ */
 export declare enum HandshakeState {
     Initial = 0,
     WaitingServerHello = 1,
@@ -20,26 +17,43 @@ export declare enum HandshakeState {
     Connected = 6,
     Failed = 7
 }
+/**
+ * The derived key material and negotiated parameters produced by a successful
+ * TLS 1.3 handshake, passed to the record layer to enable encrypted communication.
+ *
+ * @typedef  {Object}       HandshakeResult
+ * @property {string|null}  alpnProtocol - Negotiated ALPN protocol name, or `null` if not negotiated.
+ * @property {string}       cipher       - Negotiated cipher suite name string.
+ * @property {string}       version      - Negotiated TLS version string (e.g. `"TLSv1.3"`).
+ * @property {Buffer}       clientKey    - Derived client application traffic key.
+ * @property {Buffer}       clientIV     - Derived client application traffic IV.
+ * @property {Buffer}       serverKey    - Derived server application traffic key.
+ * @property {Buffer}       serverIV     - Derived server application traffic IV.
+ * @property {AEADAlgorithm} aead        - AEAD algorithm identifier for the record layer.
+ */
 export interface HandshakeResult {
-    /** Negotiated ALPN protocol. */
     alpnProtocol: string | null;
-    /** Negotiated cipher suite. */
     cipher: string;
-    /** TLS version string. */
     version: string;
-    /** Application traffic keys for the client. */
     clientKey: Buffer;
     clientIV: Buffer;
-    /** Application traffic keys for the server. */
     serverKey: Buffer;
     serverIV: Buffer;
-    /** AEAD algorithm. */
     aead: AEADAlgorithm;
 }
 /**
- * Execute a full TLS 1.3 handshake over a TCP socket.
+ * Executes a full TLS 1.3 handshake over the provided raw TCP socket,
+ * matching the fingerprint of the given browser profile. Processes
+ * ServerHello, EncryptedExtensions, Certificate, CertificateVerify, and
+ * Finished messages, and sends the client Finished message to complete
+ * the handshake.
  *
- * Returns the negotiated parameters and application-layer traffic keys.
+ * @param {net.Socket}    socket    - Connected TCP socket to perform the handshake over.
+ * @param {BrowserProfile} profile  - Browser profile that determines the ClientHello fingerprint.
+ * @param {string}        hostname  - SNI hostname used for certificate validation.
+ * @param {boolean}       insecure  - When `true`, skips certificate chain verification.
+ * @returns {Promise<HandshakeResult>} Resolves with derived keys and negotiated parameters on success.
+ * @throws {TLSError} If any handshake message is malformed, the certificate is invalid, or the server sends an alert.
  */
 export declare function performHandshake(socket: net.Socket, profile: BrowserProfile, hostname: string, insecure: boolean): Promise<HandshakeResult>;
 //# sourceMappingURL=handshake.d.ts.map

package/dist/tls/stealth/handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAYhC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAOlE,OAAO,EAML,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAC;AAwH3B,oBAAY,cAAc;IACxB,OAAO,IAAA;IACP,kBAAkB,IAAA;IAClB,0BAA0B,IAAA;IAC1B,kBAAkB,IAAA;IAClB,wBAAwB,IAAA;IACxB,eAAe,IAAA;IACf,SAAS,IAAA;IACT,MAAM,IAAA;CACP;AAED,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,eAAe,CAAC,CA6O1B"}
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/handshake.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAahC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAOlE,OAAO,EAML,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAC;AA8G3B;;;;;GAKG;AACH,oBAAY,cAAc;IACxB,OAAO,IAAA;IACP,kBAAkB,IAAA;IAClB,0BAA0B,IAAA;IAC1B,kBAAkB,IAAA;IAClB,wBAAwB,IAAA;IACxB,eAAe,IAAA;IACf,SAAS,IAAA;IACT,MAAM,IAAA;CACP;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,eAAe,CAAC,CA2O1B"}