nlcurl 0.1.0 → 0.2.0

package/dist/tls/stealth/key-schedule.d.ts

@@ -1,55 +1,91 @@
 /**
- * TLS 1.3 key schedule.
+ * Hash algorithm identifiers supported by the TLS 1.3 key schedule.
  *
- * Implements the HKDF-based key derivation defined in RFC 8446 section 7.
- * Uses only `node:crypto` -- zero external dependencies.
+ * @typedef {'sha256'|'sha384'} HashAlgorithm
  */
 export type HashAlgorithm = 'sha256' | 'sha384';
-/** Hash output length in bytes. */
+/**
+ * Returns the output length in bytes for the given hash algorithm.
+ *
+ * @param {HashAlgorithm} alg - Hash algorithm identifier.
+ * @returns {number} Output length: `32` for `sha256`, `48` for `sha384`.
+ */
 export declare function hashLength(alg: HashAlgorithm): number;
 /**
- * HKDF-Extract (RFC 5869 section 2.2).
+ * Performs the HKDF-Extract step (RFC 5869 §2.2): computes `HMAC-Hash(salt, IKM)`.
  *
- * Returns a pseudo-random key of `hashLength(alg)` bytes.
+ * @param {HashAlgorithm} alg  - Hash algorithm for the HMAC computation.
+ * @param {Buffer}        salt - Salt value (used as HMAC key).
+ * @param {Buffer}        ikm  - Input keying material.
+ * @returns {Buffer} Pseudorandom key (PRK) of length `hashLength(alg)`.
  */
 export declare function hkdfExtract(alg: HashAlgorithm, salt: Buffer, ikm: Buffer): Buffer;
 /**
- * HKDF-Expand-Label (RFC 8446 section 7.1).
- *
- *   HKDF-Expand-Label(Secret, Label, Context, Length) =
- *     HKDF-Expand(Secret, HkdfLabel, Length)
+ * Performs the TLS 1.3 HKDF-Expand-Label operation (RFC 8446 §7.1),
+ * deriving a key of `length` bytes from `secret` using the given label
+ * and context hash.
  *
- *   struct {
- *     uint16 length = Length;
- *     opaque label<7..255> = "tls13 " + Label;
- *     opaque context<0..255> = Context;
- *   } HkdfLabel;
+ * @param {HashAlgorithm} alg     - Hash algorithm for HKDF.
+ * @param {Buffer}        secret  - Input secret (PRK from HKDF-Extract).
+ * @param {string}        label   - TLS 1.3 label string (without the `"tls13 "` prefix).
+ * @param {Buffer}        context - Transcript hash, or empty buffer for simple derivations.
+ * @param {number}        length  - Desired output length in bytes.
+ * @returns {Buffer} Derived key material of the specified length.
  */
 export declare function hkdfExpandLabel(alg: HashAlgorithm, secret: Buffer, label: string, context: Buffer, length: number): Buffer;
 /**
- * Derive-Secret (RFC 8446 section 7.1).
+ * Derives a secret with a transcript hash context using HKDF-Expand-Label
+ * (RFC 8446 §7.1). This is the canonical `Derive-Secret` function of the
+ * TLS 1.3 key schedule.
  *
- *   Derive-Secret(Secret, Label, Messages) =
- *     HKDF-Expand-Label(Secret, Label, Transcript-Hash(Messages), Hash.length)
+ * @param {HashAlgorithm} alg            - Hash algorithm for HKDF.
+ * @param {Buffer}        secret         - Input PRK.
+ * @param {string}        label          - TLS 1.3 label string.
+ * @param {Buffer}        transcriptHash - Current transcript hash value.
+ * @returns {Buffer} Derived secret of length `hashLength(alg)`.
  */
 export declare function deriveSecret(alg: HashAlgorithm, secret: Buffer, label: string, transcriptHash: Buffer): Buffer;
-/**
- * Compute transcript hash incrementally.
- */
 export { createHash } from 'node:crypto';
 /**
- * Zero-length secret for the initial extract stage.
+ * Returns a zero-filled `Buffer` whose length equals the output size of
+ * `alg` — used as the IKM or salt argument in HKDF-Extract calls that
+ * require a zero-length secret at the start of the TLS 1.3 key schedule.
+ *
+ * @param {HashAlgorithm} alg - Hash algorithm that determines buffer length.
+ * @returns {Buffer} Zero-filled buffer of `hashLength(alg)` bytes.
  */
 export declare function zeroKey(alg: HashAlgorithm): Buffer;
+/**
+ * Key material derived during the handshake phase of TLS 1.3 key schedule,
+ * used to decrypt EncryptedExtensions, Certificate, CertificateVerify, and
+ * Finished messages from the server.
+ *
+ * @typedef  {Object} HandshakeKeys
+ * @property {Buffer}  clientHandshakeKey - Client handshake traffic key.
+ * @property {Buffer}  clientHandshakeIV  - Client handshake traffic IV.
+ * @property {Buffer}  serverHandshakeKey - Server handshake traffic key.
+ * @property {Buffer}  serverHandshakeIV  - Server handshake traffic IV.
+ * @property {Buffer}  handshakeSecret    - TLS 1.3 handshake secret (intermediate key schedule value).
+ * @property {Buffer}  masterSecret       - TLS 1.3 master secret used to derive application keys.
+ */
 export interface HandshakeKeys {
     clientHandshakeKey: Buffer;
     clientHandshakeIV: Buffer;
     serverHandshakeKey: Buffer;
     serverHandshakeIV: Buffer;
     handshakeSecret: Buffer;
-    /** Master secret (used to derive application keys after Finished). */
     masterSecret: Buffer;
 }
+/**
+ * Application traffic key material derived after handshake completion,
+ * used to encrypt and decrypt application data records.
+ *
+ * @typedef  {Object} ApplicationKeys
+ * @property {Buffer}  clientKey - Client application traffic key.
+ * @property {Buffer}  clientIV  - Client application traffic IV.
+ * @property {Buffer}  serverKey - Server application traffic key.
+ * @property {Buffer}  serverIV  - Server application traffic IV.
+ */
 export interface ApplicationKeys {
     clientKey: Buffer;
     clientIV: Buffer;
@@ -57,29 +93,50 @@ export interface ApplicationKeys {
     serverIV: Buffer;
 }
 /**
- * Key and IV length for a cipher suite.
+ * Returns the key and IV byte lengths for the given AEAD cipher name.
+ *
+ * @param {string} cipherName - AEAD cipher name (e.g. `"TLS_AES_128_GCM_SHA256"`).
+ * @returns {{ keyLen: number; ivLen: number }} Key length and IV length in bytes.
  */
 export declare function keyIVLengths(cipherName: string): {
     keyLen: number;
     ivLen: number;
 };
 /**
- * Derive handshake traffic keys from the shared secret and transcript hash.
+ * Derives TLS 1.3 handshake traffic keys from the ECDH shared secret and
+ * the transcript hash of the ClientHello and ServerHello messages
+ * (RFC 8446 §7.1).
  *
- * This implements the Early Secret -> Handshake Secret portion of the
- * RFC 8446 key schedule.
+ * @param {HashAlgorithm} alg          - Hash algorithm specified by the negotiated cipher suite.
+ * @param {Buffer}        sharedSecret - ECDH shared secret from key exchange.
+ * @param {Buffer}        helloHash    - Transcript hash over ClientHello..ServerHello.
+ * @param {number}        keyLen       - Required key byte length.
+ * @param {number}        ivLen        - Required IV byte length.
+ * @returns {HandshakeKeys} Derived handshake keys and intermediate secrets.
  */
 export declare function deriveHandshakeKeys(alg: HashAlgorithm, sharedSecret: Buffer, helloHash: Buffer, keyLen: number, ivLen: number): HandshakeKeys;
 /**
- * Derive application traffic keys from the master secret and the
- * full handshake transcript hash.
+ * Derives TLS 1.3 application traffic keys from the master secret and the
+ * full handshake transcript hash (RFC 8446 §7.1). These keys are used to
+ * encrypt and decrypt all application data after the handshake completes.
+ *
+ * @param {HashAlgorithm} alg           - Hash algorithm specified by the negotiated cipher suite.
+ * @param {Buffer}        masterSecret  - TLS 1.3 master secret from {@link deriveHandshakeKeys}.
+ * @param {Buffer}        handshakeHash - Transcript hash over the complete handshake.
+ * @param {number}        keyLen        - Required key byte length.
+ * @param {number}        ivLen         - Required IV byte length.
+ * @returns {ApplicationKeys} Derived application traffic keys.
  */
 export declare function deriveApplicationKeys(alg: HashAlgorithm, masterSecret: Buffer, handshakeHash: Buffer, keyLen: number, ivLen: number): ApplicationKeys;
 /**
- * Build the Finished verify_data.
+ * Computes the `verify_data` for a TLS 1.3 Finished message (RFC 8446 §4.4.4)
+ * as `HMAC(finished_key, transcript_hash)`, where `finished_key` is derived
+ * from the base traffic secret using HKDF-Expand-Label.
  *
- *   finished_key = HKDF-Expand-Label(BaseKey, "finished", "", Hash.length)
- *   verify_data  = HMAC(finished_key, Transcript-Hash(Handshake Context))
+ * @param {HashAlgorithm} alg            - Hash algorithm for HMAC.
+ * @param {Buffer}        baseSecret     - Base traffic secret (client or server handshake secret).
+ * @param {Buffer}        transcriptHash - Current transcript hash at the point of Finished.
+ * @returns {Buffer} The `verify_data` bytes to include in or validate against the Finished message.
  */
 export declare function computeFinishedVerifyData(alg: HashAlgorithm, baseSecret: Buffer, transcriptHash: Buffer): Buffer;
 //# sourceMappingURL=key-schedule.d.ts.map

package/dist/tls/stealth/key-schedule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-schedule.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/key-schedule.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAeR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,MAAM,CAER;AAED;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAElD;AAID,MAAM,WAAW,aAAa;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQlF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,aAAa,CAgCf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,eAAe,CAUjB;AAWD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CASR"}
+{"version":3,"file":"key-schedule.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/key-schedule.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAeR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,MAAM,CAER;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,aAAa,CA0Bf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,eAAe,CAUjB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CASR"}

package/dist/tls/stealth/key-schedule.js

@@ -1,33 +1,35 @@
+import { createHmac, hkdfSync } from 'node:crypto';
 /**
- * TLS 1.3 key schedule.
+ * Returns the output length in bytes for the given hash algorithm.
  *
- * Implements the HKDF-based key derivation defined in RFC 8446 section 7.
- * Uses only `node:crypto` -- zero external dependencies.
+ * @param {HashAlgorithm} alg - Hash algorithm identifier.
+ * @returns {number} Output length: `32` for `sha256`, `48` for `sha384`.
  */
-import { createHmac, hkdfSync } from 'node:crypto';
-/** Hash output length in bytes. */
 export function hashLength(alg) {
     return alg === 'sha256' ? 32 : 48;
 }
 /**
- * HKDF-Extract (RFC 5869 section 2.2).
+ * Performs the HKDF-Extract step (RFC 5869 §2.2): computes `HMAC-Hash(salt, IKM)`.
  *
- * Returns a pseudo-random key of `hashLength(alg)` bytes.
+ * @param {HashAlgorithm} alg  - Hash algorithm for the HMAC computation.
+ * @param {Buffer}        salt - Salt value (used as HMAC key).
+ * @param {Buffer}        ikm  - Input keying material.
+ * @returns {Buffer} Pseudorandom key (PRK) of length `hashLength(alg)`.
  */
 export function hkdfExtract(alg, salt, ikm) {
     return Buffer.from(createHmac(alg, salt).update(ikm).digest());
 }
 /**
- * HKDF-Expand-Label (RFC 8446 section 7.1).
+ * Performs the TLS 1.3 HKDF-Expand-Label operation (RFC 8446 §7.1),
+ * deriving a key of `length` bytes from `secret` using the given label
+ * and context hash.
  *
- *   HKDF-Expand-Label(Secret, Label, Context, Length) =
- *     HKDF-Expand(Secret, HkdfLabel, Length)
- *
- *   struct {
- *     uint16 length = Length;
- *     opaque label<7..255> = "tls13 " + Label;
- *     opaque context<0..255> = Context;
- *   } HkdfLabel;
+ * @param {HashAlgorithm} alg     - Hash algorithm for HKDF.
+ * @param {Buffer}        secret  - Input secret (PRK from HKDF-Extract).
+ * @param {string}        label   - TLS 1.3 label string (without the `"tls13 "` prefix).
+ * @param {Buffer}        context - Transcript hash, or empty buffer for simple derivations.
+ * @param {number}        length  - Desired output length in bytes.
+ * @returns {Buffer} Derived key material of the specified length.
  */
 export function hkdfExpandLabel(alg, secret, label, context, length) {
     const fullLabel = Buffer.from('tls13 ' + label, 'ascii');
@@ -43,26 +45,36 @@ export function hkdfExpandLabel(alg, secret, label, context, length) {
     return Buffer.from(hkdfSync(alg, secret, hkdfLabel, Buffer.alloc(0), length));
 }
 /**
- * Derive-Secret (RFC 8446 section 7.1).
+ * Derives a secret with a transcript hash context using HKDF-Expand-Label
+ * (RFC 8446 §7.1). This is the canonical `Derive-Secret` function of the
+ * TLS 1.3 key schedule.
  *
- *   Derive-Secret(Secret, Label, Messages) =
- *     HKDF-Expand-Label(Secret, Label, Transcript-Hash(Messages), Hash.length)
+ * @param {HashAlgorithm} alg            - Hash algorithm for HKDF.
+ * @param {Buffer}        secret         - Input PRK.
+ * @param {string}        label          - TLS 1.3 label string.
+ * @param {Buffer}        transcriptHash - Current transcript hash value.
+ * @returns {Buffer} Derived secret of length `hashLength(alg)`.
  */
 export function deriveSecret(alg, secret, label, transcriptHash) {
     return hkdfExpandLabel(alg, secret, label, transcriptHash, hashLength(alg));
 }
-/**
- * Compute transcript hash incrementally.
- */
 export { createHash } from 'node:crypto';
 /**
- * Zero-length secret for the initial extract stage.
+ * Returns a zero-filled `Buffer` whose length equals the output size of
+ * `alg` — used as the IKM or salt argument in HKDF-Extract calls that
+ * require a zero-length secret at the start of the TLS 1.3 key schedule.
+ *
+ * @param {HashAlgorithm} alg - Hash algorithm that determines buffer length.
+ * @returns {Buffer} Zero-filled buffer of `hashLength(alg)` bytes.
  */
 export function zeroKey(alg) {
     return Buffer.alloc(hashLength(alg));
 }
 /**
- * Key and IV length for a cipher suite.
+ * Returns the key and IV byte lengths for the given AEAD cipher name.
+ *
+ * @param {string} cipherName - AEAD cipher name (e.g. `"TLS_AES_128_GCM_SHA256"`).
+ * @returns {{ keyLen: number; ivLen: number }} Key length and IV length in bytes.
  */
 export function keyIVLengths(cipherName) {
     if (cipherName.includes('AES_128')) {
@@ -74,27 +86,27 @@ export function keyIVLengths(cipherName) {
     return { keyLen: 16, ivLen: 12 };
 }
 /**
- * Derive handshake traffic keys from the shared secret and transcript hash.
+ * Derives TLS 1.3 handshake traffic keys from the ECDH shared secret and
+ * the transcript hash of the ClientHello and ServerHello messages
+ * (RFC 8446 §7.1).
  *
- * This implements the Early Secret -> Handshake Secret portion of the
- * RFC 8446 key schedule.
+ * @param {HashAlgorithm} alg          - Hash algorithm specified by the negotiated cipher suite.
+ * @param {Buffer}        sharedSecret - ECDH shared secret from key exchange.
+ * @param {Buffer}        helloHash    - Transcript hash over ClientHello..ServerHello.
+ * @param {number}        keyLen       - Required key byte length.
+ * @param {number}        ivLen        - Required IV byte length.
+ * @returns {HandshakeKeys} Derived handshake keys and intermediate secrets.
  */
 export function deriveHandshakeKeys(alg, sharedSecret, helloHash, keyLen, ivLen) {
-    // 1. Early secret = HKDF-Extract(salt=0, IKM=0)
     const earlySecret = hkdfExtract(alg, Buffer.alloc(hashLength(alg)), zeroKey(alg));
-    // 2. Derive salt for handshake secret
     const derivedSalt = deriveSecret(alg, earlySecret, 'derived', emptyHash(alg));
-    // 3. Handshake secret = HKDF-Extract(salt=derived, IKM=shared_secret)
     const handshakeSecret = hkdfExtract(alg, derivedSalt, sharedSecret);
-    // 4. Client/server handshake traffic secrets
     const clientSecret = deriveSecret(alg, handshakeSecret, 'c hs traffic', helloHash);
     const serverSecret = deriveSecret(alg, handshakeSecret, 's hs traffic', helloHash);
-    // 5. Traffic keys
     const clientHandshakeKey = hkdfExpandLabel(alg, clientSecret, 'key', Buffer.alloc(0), keyLen);
     const clientHandshakeIV = hkdfExpandLabel(alg, clientSecret, 'iv', Buffer.alloc(0), ivLen);
     const serverHandshakeKey = hkdfExpandLabel(alg, serverSecret, 'key', Buffer.alloc(0), keyLen);
     const serverHandshakeIV = hkdfExpandLabel(alg, serverSecret, 'iv', Buffer.alloc(0), ivLen);
-    // 6. Master secret derivation
     const derivedMasterSalt = deriveSecret(alg, handshakeSecret, 'derived', emptyHash(alg));
     const masterSecret = hkdfExtract(alg, derivedMasterSalt, zeroKey(alg));
     return {
@@ -107,8 +119,16 @@ export function deriveHandshakeKeys(alg, sharedSecret, helloHash, keyLen, ivLen)
     };
 }
 /**
- * Derive application traffic keys from the master secret and the
- * full handshake transcript hash.
+ * Derives TLS 1.3 application traffic keys from the master secret and the
+ * full handshake transcript hash (RFC 8446 §7.1). These keys are used to
+ * encrypt and decrypt all application data after the handshake completes.
+ *
+ * @param {HashAlgorithm} alg           - Hash algorithm specified by the negotiated cipher suite.
+ * @param {Buffer}        masterSecret  - TLS 1.3 master secret from {@link deriveHandshakeKeys}.
+ * @param {Buffer}        handshakeHash - Transcript hash over the complete handshake.
+ * @param {number}        keyLen        - Required key byte length.
+ * @param {number}        ivLen         - Required IV byte length.
+ * @returns {ApplicationKeys} Derived application traffic keys.
  */
 export function deriveApplicationKeys(alg, masterSecret, handshakeHash, keyLen, ivLen) {
     const clientSecret = deriveSecret(alg, masterSecret, 'c ap traffic', handshakeHash);
@@ -120,19 +140,19 @@ export function deriveApplicationKeys(alg, masterSecret, handshakeHash, keyLen,
         serverIV: hkdfExpandLabel(alg, serverSecret, 'iv', Buffer.alloc(0), ivLen),
     };
 }
-/**
- * Hash of empty string -- used for the Derive-Secret("derived", "")
- * step in the key schedule.
- */
 function emptyHash(alg) {
     const { createHash } = require('node:crypto');
     return createHash(alg).digest();
 }
 /**
- * Build the Finished verify_data.
+ * Computes the `verify_data` for a TLS 1.3 Finished message (RFC 8446 §4.4.4)
+ * as `HMAC(finished_key, transcript_hash)`, where `finished_key` is derived
+ * from the base traffic secret using HKDF-Expand-Label.
  *
- *   finished_key = HKDF-Expand-Label(BaseKey, "finished", "", Hash.length)
- *   verify_data  = HMAC(finished_key, Transcript-Hash(Handshake Context))
+ * @param {HashAlgorithm} alg            - Hash algorithm for HMAC.
+ * @param {Buffer}        baseSecret     - Base traffic secret (client or server handshake secret).
+ * @param {Buffer}        transcriptHash - Current transcript hash at the point of Finished.
+ * @returns {Buffer} The `verify_data` bytes to include in or validate against the Finished message.
  */
 export function computeFinishedVerifyData(alg, baseSecret, transcriptHash) {
     const finishedKey = hkdfExpandLabel(alg, baseSecret, 'finished', Buffer.alloc(0), hashLength(alg));

package/dist/tls/stealth/key-schedule.js.map

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

package/dist/tls/stealth/record-layer.d.ts

@@ -1,8 +1,10 @@
 /**
- * TLS record layer.
+ * A single parsed TLS record as defined in RFC 8446 ¥5.1.
  *
- * Handles framing, encryption, and decryption of TLS records.
- * Operates on raw TCP byte streams.
+ * @typedef  {Object} TLSRecord
+ * @property {number} type     - Content type byte (see {@link RecordType}).
+ * @property {number} version  - Legacy record version (e.g. `0x0303` for TLS 1.2 compatibility).
+ * @property {Buffer} fragment - Raw payload bytes of the record.
  */
 export interface TLSRecord {
     type: number;
@@ -10,62 +12,111 @@ export interface TLSRecord {
     fragment: Buffer;
 }
 /**
- * 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 declare function readRecord(data: Buffer, offset: number): {
     record: TLSRecord;
     bytesRead: number;
 } | null;
 /**
- * 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 declare function writeRecord(type: number, version: number, payload: Buffer): Buffer;
+/**
+ * AEAD algorithm identifiers supported by the record layer. Corresponds to
+ * the TLS 1.3 mandatory cipher suites.
+ *
+ * @typedef {'aes-128-gcm'|'aes-256-gcm'|'chacha20-poly1305'} AEADAlgorithm
+ */
 export type AEADAlgorithm = 'aes-128-gcm' | 'aes-256-gcm' | 'chacha20-poly1305';
 /**
- * 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 declare function aeadFromCipher(cipherName: string): AEADAlgorithm;
 /**
- * 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 declare function buildNonce(iv: Buffer, sequenceNumber: bigint): Buffer;
 /**
- * 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 declare function encryptRecord(algorithm: AEADAlgorithm, key: Buffer, nonce: Buffer, plaintext: Buffer, additionalData: Buffer): Buffer;
 /**
- * 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 declare function decryptRecord(algorithm: AEADAlgorithm, key: Buffer, nonce: Buffer, ciphertext: Buffer, additionalData: Buffer): Buffer;
 /**
- * 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 declare function buildAdditionalData(ciphertextLength: number): Buffer;
 /**
- * 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 declare function wrapEncryptedRecord(algorithm: AEADAlgorithm, key: Buffer, iv: Buffer, sequenceNumber: bigint, contentType: number, plaintext: Buffer): Buffer;
 /**
- * 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 declare function unwrapEncryptedRecord(algorithm: AEADAlgorithm, key: Buffer, iv: Buffer, sequenceNumber: bigint, record: TLSRecord): {
     contentType: number;

package/dist/tls/stealth/record-layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-layer.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/record-layer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAexG;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOlF;AAID,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEhF;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAWhE;AAKD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CASrE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAYR;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,SAAS,GAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAgB5C"}
+{"version":3,"file":"record-layer.d.ts","sourceRoot":"","sources":["../../../src/tls/stealth/record-layer.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAexG;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOlF;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAWhE;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAuBR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAWR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,SAAS,GAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAe5C"}