spd-lib 1.3.6 → 1.3.7

package/index.d.mts

@@ -28,6 +28,7 @@ interface SPDPayload {
     argon2Time?: number;
     argon2HashLen?: number;
     hashKeyLen?: number;
+    argon2Parallelism?: number;
     entryRoles?: Record<string, string[]>;
     maxOpenCount?: number;
     openCount?: number;
@@ -168,8 +169,8 @@ type SupportedValue = string | number | boolean | unknown[] | TypedArray | Map<u
 
 declare const ARGON2_MEMORY_HIGH = 524288;
 declare const ARGON2_TIME_HIGH = 8;
-declare const ARGON2_MEMORY_PARANOID = 1048576;
-declare const ARGON2_TIME_PARANOID = 12;
+declare const ARGON2_MEMORY_PARANOID = 2097152;
+declare const ARGON2_TIME_PARANOID = 16;
 /** Key stretching profile names */
 type SPDKeyProfile = 'standard' | 'high' | 'paranoid';
 declare class SPD {
@@ -210,6 +211,7 @@ declare class SPD {
     private _scryptN;
     private _scryptR;
     private _scryptP;
+    private _argon2Parallelism;
     private _wrapArgon2Memory;
     private _wrapArgon2Time;
     private static globalLogger;
@@ -301,7 +303,7 @@ declare class SPD {
      * v27+: hashLen=96, macKeyLen=64 (full SHA3-512 output width = 128-bit PQ forgery resistance)
      * v26:  hashLen=64, macKeyLen=32 (legacy — pass these explicitly when reading old files)
      */
-    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number, kdfChain?: boolean, scryptN?: number, scryptR?: number, scryptP?: number): Promise<{
+    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number, kdfChain?: boolean, scryptN?: number, scryptR?: number, scryptP?: number, parallelism?: number): Promise<{
         aeadKey: Uint8Array;
         macKey: Uint8Array;
     }>;
@@ -312,6 +314,37 @@ declare class SPD {
      * "decrypts" under two different keys.
      */
     static computeKeyCommitment(aeadKey: Uint8Array): string;
+    /**
+     * CMT-4 block size: SHA3-256(key || nonce) prepended to every ciphertext.
+     * 32 bytes = one SHA3-256 output.
+     */
+    private static readonly CMT_BLOCK_BYTES;
+    /**
+     * CMT-4 encrypt: encrypt plaintext with XChaCha20-Poly1305, then prepend
+     * H(key || nonce) so that the correct key is the *only* key that can produce
+     * a valid commitment.  Closes the USENIX 2022 partitioning oracle attack.
+     *
+     * Stored layout: [ 32-byte cmt | xchacha20-poly1305 ciphertext ]
+     */
+    private static aeadEncrypt;
+    /**
+     * CMT-4 decrypt: verify the prepended commitment block, then decrypt.
+     * Throws on commitment mismatch or AEAD authentication failure.
+     */
+    private static aeadDecrypt;
+    /**
+     * Pad `data` to a multiple of `blockSize` bytes before compression.
+     * A 4-byte LE prefix records the original length so the receiver can strip padding.
+     * Using random padding bytes ensures the pad bytes themselves don't compress.
+     *
+     * This defeats CRIME/BREACH-class compression oracle attacks: the AEAD
+     * ciphertext length is now quantised to `blockSize`-byte steps regardless of
+     * plaintext content, so an attacker who can observe ciphertext lengths learns
+     * nothing about the plaintext.
+     */
+    private static readonly COMPRESS_PAD_BLOCK;
+    private static padForCompression;
+    private static unpadAfterDecompression;
     private static computeMAC;
     /**
      * Derives a per-entry 32-byte AEAD key from the master AEAD key using HKDF-SHA3-512.
@@ -323,7 +356,35 @@ declare class SPD {
      *   - Zero performance impact: HKDF is ~microseconds vs ~1s for Argon2id
      */
     static deriveEntryKey(masterAeadKey: Uint8Array, entryName: string): Uint8Array;
+    /**
+     * Derive a dedicated 32-byte name-encryption key from the master AEAD key.
+     * Domain-separated from entry data keys via a distinct info string.
+     * Used to encrypt entry names in the binary index so the plaintext index
+     * does not leak entry names to an attacker who has the file but not the passcode.
+     */
+    static deriveNameKey(masterAeadKey: Uint8Array): Uint8Array;
+    /**
+     * Encrypt an entry name.
+     * Returns [24-byte nonce || XChaCha20-Poly1305+CMT ciphertext].
+     */
+    private static _encryptEntryName;
+    /**
+     * Decrypt an entry name.
+     * Expects [24-byte nonce || ciphertext] as produced by _encryptEntryName.
+     */
+    private static _decryptEntryName;
+    /**
+     * Normalize l33t-speak substitutions so common bypasses are caught.
+     * Maps: @→a, 0→o, 3→e, 1→i, 5→s, $→s, !→i, 4→a, 7→t
+     */
+    private static normalizeLeet;
     checkPasscodeStrength(passcode: string): boolean;
+    /**
+     * Compute a bigram-frequency penalty factor [0, 0.5].
+     * Returns higher values for text heavy in common English bigrams.
+     * A factor of 0.3 means the entropy estimate is reduced by 30%.
+     */
+    private static _bigramPenalty;
     setPassKey(passcode: string): Promise<void>;
     setHash(hash?: HashAlgorithm): void;
     setCompressionLevel(level?: number): void;
@@ -762,7 +823,7 @@ declare class SPD {
     static verify(filePath: string, passcode: string): Promise<SPDVerifyResult>;
     static loadFromString(data: string, passcode: string): Promise<SPD>;
     static loadFromChunks(chunks: string[], passcode: string): Promise<SPD>;
-    static derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number): Promise<PBKResult>;
+    static derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, parallelism?: number): Promise<PBKResult>;
     static decryptSalt(encryptedSalt: number[], saltNonce: number[], wrapSalt: number[], passcode: string, memory?: number, time?: number): Promise<Uint8Array>;
     static encryptSalt(salt: Uint8Array, passcode: string, memory?: number, time?: number): Promise<EncryptedSaltResult>;
     static toBase64(data: Uint8Array | Buffer): string;
@@ -1026,20 +1087,25 @@ declare class SPDWriter {
  *  ✅ Active MitM — ML-DSA-65 certificate pinning + ECDH server auth
  *  ✅ Harvest-now-decrypt-later (quantum) — ML-KEM-768 hybrid
  *  ✅ PSK gives additional session binding layer for high-security deployments
+ *  ✅ Key commitment token prevents key mismatch from going undetected
+ *  ✅ Sliding window replay protection tolerates mild network reordering (window=64)
+ *  ✅ Traffic analysis resistance — optional 64-byte block padding
  *
  * ## V2 ClientHello wire format (1249 bytes)
  *
- *  [1B   version         ]  = TRANSPORT_VERSION_V2 (2)
- *  [32B  ecdhEphemeralPub]  client's ephemeral Curve25519 public key
- *  [32B  sessionSalt     ]  random HKDF salt (public)
- *  [1184B kemEphemeralPub]  client's ephemeral ML-KEM-768 public key
+ *  [1B    version         ]  = TRANSPORT_VERSION_V2 (2)
+ *  [32B   ecdhEphemeralPub]  client's ephemeral Curve25519 public key
+ *  [32B   sessionSalt     ]  random HKDF salt (public)
+ *  [1184B kemEphemeralPub ]  client's ephemeral ML-KEM-768 public key
  *
- * ## V2 ServerHello wire format (1 + 1088 + 3309 = 4398 bytes)
+ * ## V2 ServerHello wire format (1 + 1088 + 3309 + 32 = 4430 bytes)
  *
  *  [1B    version        ]  = TRANSPORT_VERSION_V2 (2)
  *  [1088B kemCiphertext  ]  ML-KEM-768 ciphertext (encapsulated by server to client's kemPub)
  *  [3309B signature      ]  ML-DSA-65 signature over (kemCiphertext || sessionSalt || ecdhEphemeralPub)
  *                           — present only if server has a signing key; all zeros if absent
+ *  [32B   keyCommitment  ]  HMAC-SHA3-256(c2sKey||s2cKey, "spd-transport-key-commit-v1")
+ *                           — client verifies this to detect key mismatch / active MitM
  *
  * ## Usage
  *
@@ -1101,6 +1167,12 @@ interface SPDClientConnectOptions {
      * Provides an extra secret layer for PSK session resumption.
      */
     psk?: Uint8Array;
+    /**
+     * Enable frame padding to hide payload sizes (traffic analysis resistance).
+     * Pads plaintext to the next multiple of 64 bytes before encryption.
+     * Default: false.
+     */
+    padding?: boolean;
 }
 /**
  * A live, established session between two peers.
@@ -1109,13 +1181,14 @@ interface SPDClientConnectOptions {
 interface SPDSession {
     /**
      * Encrypt `plaintext` for transmission in this session's direction.
-     * Returns a self-contained frame: [1B version][8B counter][24B nonce][ciphertext+tag]
+     * Returns a self-contained frame: [1B version][8B counter][ciphertext+tag]
+     * Nonce is derived from counter (not transmitted) to save 24 bytes per frame.
      */
     encrypt(plaintext: Uint8Array | Buffer): Buffer;
     /**
      * Decrypt a frame received from the remote peer.
-     * Throws if the tag is invalid, the version is wrong, or the counter is not
-     * strictly greater than the last seen counter (replay protection).
+     * Throws if the tag is invalid, the version is wrong, or the counter is
+     * outside the 64-entry sliding replay window.
      */
     decrypt(frame: Buffer): Buffer;
     /**
@@ -1137,6 +1210,16 @@ interface SPDSession {
     destroy(): void;
 }
 declare class SPDTransport {
+    /**
+     * When strict mode is enabled, `serverAccept` will reject any V2 ClientHello
+     * unless the server identity has a signing key pair (ML-DSA-65), and the
+     * server will always include a real signature in the ServerHello.
+     * Clients must pin the signing key; unsigned ServerHellos will be rejected
+     * by the client if it has a pinned signing key (standard behavior).
+     */
+    private static _strictMode;
+    static setStrictMode(enabled: boolean): void;
+    static isStrictMode(): boolean;
     /**
      * Generate a long-term Curve25519 server identity key pair.
      * Store `privateKey` securely (e.g. in a hardware key store or SPD vault).
@@ -1189,7 +1272,7 @@ declare class SPDTransport {
      * @param clientHello     The raw bytes sent by the client.
      * @param psk             Optional PSK (must match client's PSK for session to work).
      */
-    static serverAccept(serverIdentity: SPDServerIdentity, clientHello: Buffer, psk?: Uint8Array): Promise<{
+    static serverAccept(serverIdentity: SPDServerIdentity, clientHello: Buffer, psk?: Uint8Array, padding?: boolean): Promise<{
         session: SPDSession;
         serverHello?: Buffer;
     }>;

package/index.d.ts

@@ -28,6 +28,7 @@ interface SPDPayload {
     argon2Time?: number;
     argon2HashLen?: number;
     hashKeyLen?: number;
+    argon2Parallelism?: number;
     entryRoles?: Record<string, string[]>;
     maxOpenCount?: number;
     openCount?: number;
@@ -168,8 +169,8 @@ type SupportedValue = string | number | boolean | unknown[] | TypedArray | Map<u
 
 declare const ARGON2_MEMORY_HIGH = 524288;
 declare const ARGON2_TIME_HIGH = 8;
-declare const ARGON2_MEMORY_PARANOID = 1048576;
-declare const ARGON2_TIME_PARANOID = 12;
+declare const ARGON2_MEMORY_PARANOID = 2097152;
+declare const ARGON2_TIME_PARANOID = 16;
 /** Key stretching profile names */
 type SPDKeyProfile = 'standard' | 'high' | 'paranoid';
 declare class SPD {
@@ -210,6 +211,7 @@ declare class SPD {
     private _scryptN;
     private _scryptR;
     private _scryptP;
+    private _argon2Parallelism;
     private _wrapArgon2Memory;
     private _wrapArgon2Time;
     private static globalLogger;
@@ -301,7 +303,7 @@ declare class SPD {
      * v27+: hashLen=96, macKeyLen=64 (full SHA3-512 output width = 128-bit PQ forgery resistance)
      * v26:  hashLen=64, macKeyLen=32 (legacy — pass these explicitly when reading old files)
      */
-    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number, kdfChain?: boolean, scryptN?: number, scryptR?: number, scryptP?: number): Promise<{
+    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number, kdfChain?: boolean, scryptN?: number, scryptR?: number, scryptP?: number, parallelism?: number): Promise<{
         aeadKey: Uint8Array;
         macKey: Uint8Array;
     }>;
@@ -312,6 +314,37 @@ declare class SPD {
      * "decrypts" under two different keys.
      */
     static computeKeyCommitment(aeadKey: Uint8Array): string;
+    /**
+     * CMT-4 block size: SHA3-256(key || nonce) prepended to every ciphertext.
+     * 32 bytes = one SHA3-256 output.
+     */
+    private static readonly CMT_BLOCK_BYTES;
+    /**
+     * CMT-4 encrypt: encrypt plaintext with XChaCha20-Poly1305, then prepend
+     * H(key || nonce) so that the correct key is the *only* key that can produce
+     * a valid commitment.  Closes the USENIX 2022 partitioning oracle attack.
+     *
+     * Stored layout: [ 32-byte cmt | xchacha20-poly1305 ciphertext ]
+     */
+    private static aeadEncrypt;
+    /**
+     * CMT-4 decrypt: verify the prepended commitment block, then decrypt.
+     * Throws on commitment mismatch or AEAD authentication failure.
+     */
+    private static aeadDecrypt;
+    /**
+     * Pad `data` to a multiple of `blockSize` bytes before compression.
+     * A 4-byte LE prefix records the original length so the receiver can strip padding.
+     * Using random padding bytes ensures the pad bytes themselves don't compress.
+     *
+     * This defeats CRIME/BREACH-class compression oracle attacks: the AEAD
+     * ciphertext length is now quantised to `blockSize`-byte steps regardless of
+     * plaintext content, so an attacker who can observe ciphertext lengths learns
+     * nothing about the plaintext.
+     */
+    private static readonly COMPRESS_PAD_BLOCK;
+    private static padForCompression;
+    private static unpadAfterDecompression;
     private static computeMAC;
     /**
      * Derives a per-entry 32-byte AEAD key from the master AEAD key using HKDF-SHA3-512.
@@ -323,7 +356,35 @@ declare class SPD {
      *   - Zero performance impact: HKDF is ~microseconds vs ~1s for Argon2id
      */
     static deriveEntryKey(masterAeadKey: Uint8Array, entryName: string): Uint8Array;
+    /**
+     * Derive a dedicated 32-byte name-encryption key from the master AEAD key.
+     * Domain-separated from entry data keys via a distinct info string.
+     * Used to encrypt entry names in the binary index so the plaintext index
+     * does not leak entry names to an attacker who has the file but not the passcode.
+     */
+    static deriveNameKey(masterAeadKey: Uint8Array): Uint8Array;
+    /**
+     * Encrypt an entry name.
+     * Returns [24-byte nonce || XChaCha20-Poly1305+CMT ciphertext].
+     */
+    private static _encryptEntryName;
+    /**
+     * Decrypt an entry name.
+     * Expects [24-byte nonce || ciphertext] as produced by _encryptEntryName.
+     */
+    private static _decryptEntryName;
+    /**
+     * Normalize l33t-speak substitutions so common bypasses are caught.
+     * Maps: @→a, 0→o, 3→e, 1→i, 5→s, $→s, !→i, 4→a, 7→t
+     */
+    private static normalizeLeet;
     checkPasscodeStrength(passcode: string): boolean;
+    /**
+     * Compute a bigram-frequency penalty factor [0, 0.5].
+     * Returns higher values for text heavy in common English bigrams.
+     * A factor of 0.3 means the entropy estimate is reduced by 30%.
+     */
+    private static _bigramPenalty;
     setPassKey(passcode: string): Promise<void>;
     setHash(hash?: HashAlgorithm): void;
     setCompressionLevel(level?: number): void;
@@ -762,7 +823,7 @@ declare class SPD {
     static verify(filePath: string, passcode: string): Promise<SPDVerifyResult>;
     static loadFromString(data: string, passcode: string): Promise<SPD>;
     static loadFromChunks(chunks: string[], passcode: string): Promise<SPD>;
-    static derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number): Promise<PBKResult>;
+    static derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, parallelism?: number): Promise<PBKResult>;
     static decryptSalt(encryptedSalt: number[], saltNonce: number[], wrapSalt: number[], passcode: string, memory?: number, time?: number): Promise<Uint8Array>;
     static encryptSalt(salt: Uint8Array, passcode: string, memory?: number, time?: number): Promise<EncryptedSaltResult>;
     static toBase64(data: Uint8Array | Buffer): string;
@@ -1026,20 +1087,25 @@ declare class SPDWriter {
  *  ✅ Active MitM — ML-DSA-65 certificate pinning + ECDH server auth
  *  ✅ Harvest-now-decrypt-later (quantum) — ML-KEM-768 hybrid
  *  ✅ PSK gives additional session binding layer for high-security deployments
+ *  ✅ Key commitment token prevents key mismatch from going undetected
+ *  ✅ Sliding window replay protection tolerates mild network reordering (window=64)
+ *  ✅ Traffic analysis resistance — optional 64-byte block padding
  *
  * ## V2 ClientHello wire format (1249 bytes)
  *
- *  [1B   version         ]  = TRANSPORT_VERSION_V2 (2)
- *  [32B  ecdhEphemeralPub]  client's ephemeral Curve25519 public key
- *  [32B  sessionSalt     ]  random HKDF salt (public)
- *  [1184B kemEphemeralPub]  client's ephemeral ML-KEM-768 public key
+ *  [1B    version         ]  = TRANSPORT_VERSION_V2 (2)
+ *  [32B   ecdhEphemeralPub]  client's ephemeral Curve25519 public key
+ *  [32B   sessionSalt     ]  random HKDF salt (public)
+ *  [1184B kemEphemeralPub ]  client's ephemeral ML-KEM-768 public key
  *
- * ## V2 ServerHello wire format (1 + 1088 + 3309 = 4398 bytes)
+ * ## V2 ServerHello wire format (1 + 1088 + 3309 + 32 = 4430 bytes)
  *
  *  [1B    version        ]  = TRANSPORT_VERSION_V2 (2)
  *  [1088B kemCiphertext  ]  ML-KEM-768 ciphertext (encapsulated by server to client's kemPub)
  *  [3309B signature      ]  ML-DSA-65 signature over (kemCiphertext || sessionSalt || ecdhEphemeralPub)
  *                           — present only if server has a signing key; all zeros if absent
+ *  [32B   keyCommitment  ]  HMAC-SHA3-256(c2sKey||s2cKey, "spd-transport-key-commit-v1")
+ *                           — client verifies this to detect key mismatch / active MitM
  *
  * ## Usage
  *
@@ -1101,6 +1167,12 @@ interface SPDClientConnectOptions {
      * Provides an extra secret layer for PSK session resumption.
      */
     psk?: Uint8Array;
+    /**
+     * Enable frame padding to hide payload sizes (traffic analysis resistance).
+     * Pads plaintext to the next multiple of 64 bytes before encryption.
+     * Default: false.
+     */
+    padding?: boolean;
 }
 /**
  * A live, established session between two peers.
@@ -1109,13 +1181,14 @@ interface SPDClientConnectOptions {
 interface SPDSession {
     /**
      * Encrypt `plaintext` for transmission in this session's direction.
-     * Returns a self-contained frame: [1B version][8B counter][24B nonce][ciphertext+tag]
+     * Returns a self-contained frame: [1B version][8B counter][ciphertext+tag]
+     * Nonce is derived from counter (not transmitted) to save 24 bytes per frame.
      */
     encrypt(plaintext: Uint8Array | Buffer): Buffer;
     /**
      * Decrypt a frame received from the remote peer.
-     * Throws if the tag is invalid, the version is wrong, or the counter is not
-     * strictly greater than the last seen counter (replay protection).
+     * Throws if the tag is invalid, the version is wrong, or the counter is
+     * outside the 64-entry sliding replay window.
      */
     decrypt(frame: Buffer): Buffer;
     /**
@@ -1137,6 +1210,16 @@ interface SPDSession {
     destroy(): void;
 }
 declare class SPDTransport {
+    /**
+     * When strict mode is enabled, `serverAccept` will reject any V2 ClientHello
+     * unless the server identity has a signing key pair (ML-DSA-65), and the
+     * server will always include a real signature in the ServerHello.
+     * Clients must pin the signing key; unsigned ServerHellos will be rejected
+     * by the client if it has a pinned signing key (standard behavior).
+     */
+    private static _strictMode;
+    static setStrictMode(enabled: boolean): void;
+    static isStrictMode(): boolean;
     /**
      * Generate a long-term Curve25519 server identity key pair.
      * Store `privateKey` securely (e.g. in a hardware key store or SPD vault).
@@ -1189,7 +1272,7 @@ declare class SPDTransport {
      * @param clientHello     The raw bytes sent by the client.
      * @param psk             Optional PSK (must match client's PSK for session to work).
      */
-    static serverAccept(serverIdentity: SPDServerIdentity, clientHello: Buffer, psk?: Uint8Array): Promise<{
+    static serverAccept(serverIdentity: SPDServerIdentity, clientHello: Buffer, psk?: Uint8Array, padding?: boolean): Promise<{
         session: SPDSession;
         serverHello?: Buffer;
     }>;