spd-lib 1.4.1 → 1.4.3

package/index.d.mts

@@ -1366,4 +1366,186 @@ declare class SPDShamir {
     static decodeShare(encoded: string): SPDShamirShare;
 }
 
-export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };
+/**
+ * SPDHandshake — Hybrid post-quantum ephemeral key agreement for SPD sessions.
+ *
+ * ## Cryptographic design
+ *
+ * Uses a **X25519 + ML-KEM-768 hybrid** construction:
+ *
+ *   x25519_ss  = X25519(myPriv, theirPub)          — classical ECDH
+ *   mlkem_ss   = ML-KEM-768 encap/decap             — post-quantum KEM (NIST FIPS 203)
+ *   transcript = SHA3-512(loNonce ∥ hiNonce)        — session-binding salt
+ *   sessionKey = HKDF-SHA-512(
+ *                  IKM  = x25519_ss ∥ mlkem_ss,
+ *                  salt = transcript,
+ *                  info = 'spd-hs-session-v1'
+ *                )
+ *
+ * Breaking the session key requires breaking **both** X25519 (hard classically)
+ * **and** ML-KEM-768 (hard for quantum computers) simultaneously.
+ *
+ * ## Security properties
+ *
+ * | Property                        | Mechanism                                              |
+ * |---------------------------------|--------------------------------------------------------|
+ * | Classical hardness              | X25519 ECDH — ~2^128 classical operations              |
+ * | Quantum hardness                | ML-KEM-768 — NIST FIPS 203, ~2^178 quantum ops        |
+ * | Perfect forward secrecy         | All keypairs ephemeral, zeroed after derive()          |
+ * | Memory safety                   | Private keys XOR-blinded immediately after creation    |
+ * | Key commitment (CMT-4)          | SHA3-256(sessionKey ∥ transcript) — verify before use  |
+ * | Cross-session binding           | 32-byte CSPRNG nonce per session mixed into HKDF       |
+ * | Domain separation               | Distinct HKDF info strings per key purpose             |
+ * | Timing safety                   | timingSafeEqual for all sensitive comparisons          |
+ * | Low-order point rejection       | All-zero DH output rejected before HKDF                |
+ * | Input validation                | Type + length checked on all inputs                    |
+ * | Zero-on-free                    | All key material zeroed explicitly via sodium.memzero  |
+ *
+ * ## Handshake flow
+ *
+ * The initiator (e.g. client) drives ML-KEM encapsulation:
+ *
+ * ```
+ *  INITIATOR                              RESPONDER
+ *  ─────────────────────────────────────────────────────
+ *  hs = SPDHandshake.createInitiator()
+ *  send → { x25519Pub, kemPub, nonce }
+ *                                         hs = await SPDHandshake.createResponder(
+ *                                                initiatorHello)
+ *                                         send → { x25519Pub, kemCt, nonce }
+ *  result = await hs.finalizeInitiator(
+ *             responderHello)
+ *                                         result = hs.responderResult()
+ *  // result.commitment === responderResult.commitment
+ *  // exchange commitments to confirm matching keys
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { SPDHandshake, SPD } from 'spd-lib';
+ *
+ * // ── Initiator (client) ───────────────────────────────────────────────────────
+ * const init = await SPDHandshake.createInitiator();
+ * socket.send(JSON.stringify(init.hello));         // { x25519Pub, kemPub, nonce }
+ *
+ * const respHello = JSON.parse(await socket.recv());
+ * const initResult = await init.finalizeInitiator(respHello);
+ *
+ * // ── Responder (server) ───────────────────────────────────────────────────────
+ * const resp = await SPDHandshake.createResponder(initHello);
+ * socket.send(JSON.stringify(resp.hello));         // { x25519Pub, kemCt, nonce }
+ * const respResult = resp.responderResult();
+ *
+ * // ── Both sides: verify commitment matches before using key ───────────────────
+ * // exchange initResult.commitment <→ respResult.commitment over the wire
+ * // if they match, both sides have the same session key
+ *
+ * const spd = new SPD();
+ * spd.setKeyProfile('standard');   // session key is already 256-bit entropy
+ * await spd.setPassKey(initResult.sessionKey);
+ * initResult.destroy();            // zero raw key bytes from memory
+ * ```
+ */
+/** Message sent during the handshake exchange. */
+interface SPDHandshakeHello {
+    /** Base64url-encoded X25519 public key (32 bytes). */
+    x25519Pub: string;
+    /**
+     * Initiator hello: base64url-encoded ML-KEM-768 public key (1184 bytes).
+     * Responder hello: base64url-encoded ML-KEM-768 ciphertext (1088 bytes).
+     */
+    kemData: string;
+    /** Base64url-encoded random session nonce (32 bytes). */
+    nonce: string;
+}
+/**
+ * Completed handshake result.
+ * Call `destroy()` immediately after passing `sessionKey` to `spd.setPassKey()`.
+ */
+declare class SPDHandshakeResult {
+    /**
+     * 64-character hex session passphrase (256 bits of entropy).
+     * Pass directly to `spd.setPassKey()`.
+     */
+    readonly sessionKey: string;
+    /**
+     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ transcriptHash).
+     * Base64url-encoded (32 bytes).
+     *
+     * Exchange this with the other party and verify they match BEFORE using
+     * `sessionKey`. If they differ, abort — a MITM substituted a key.
+     */
+    readonly commitment: string;
+    private _raw;
+    /** @internal */
+    constructor(raw: Buffer, transcript: Buffer);
+    /**
+     * Zero the raw session key bytes from memory.
+     * The `sessionKey` hex string may still exist in the JS heap
+     * (strings are immutable in V8); call this as soon as `setPassKey()` is done.
+     */
+    destroy(): void;
+}
+/** Initiator state returned by `SPDHandshake.createInitiator()`. */
+declare class SPDHandshakeInitiator {
+    /** Send this to the responder. */
+    readonly hello: SPDHandshakeHello;
+    private _x25519Priv;
+    private _kemSecretMask;
+    private _blindedKemSK;
+    private _nonceRaw;
+    private _done;
+    /** @internal */
+    constructor(x25519PrivRaw: Buffer, x25519PubRaw: Buffer, kemSecretKey: Uint8Array, kemPublicKey: Uint8Array, nonce: Buffer);
+    /**
+     * Complete the initiator side of the handshake using the responder's hello.
+     *
+     * @param responderHello  The `hello` object received from the responder.
+     * @returns  `SPDHandshakeResult` — call `.destroy()` after `setPassKey()`.
+     * @throws   If already called, or if any input is malformed.
+     */
+    finalizeInitiator(responderHello: SPDHandshakeHello): Promise<SPDHandshakeResult>;
+    /** Zero all key material. Call if abandoning the handshake. */
+    destroy(): void;
+}
+/** Responder state returned by `SPDHandshake.createResponder()`. */
+declare class SPDHandshakeResponder {
+    /** Send this to the initiator. */
+    readonly hello: SPDHandshakeHello;
+    private _result;
+    /** @internal */
+    constructor(hello: SPDHandshakeHello, result: SPDHandshakeResult);
+    /**
+     * Return the completed session result.
+     * The responder derives its key during `createResponder()` — call this
+     * after sending `hello` to the initiator.
+     */
+    responderResult(): SPDHandshakeResult;
+}
+declare class SPDHandshake {
+    private constructor();
+    /**
+     * Create the initiator side of the handshake.
+     *
+     * Generates an ephemeral X25519 keypair and ML-KEM-768 keypair.
+     * Send `initiator.hello` to the responder.
+     *
+     * @returns  `SPDHandshakeInitiator` instance.
+     */
+    static createInitiator(): Promise<SPDHandshakeInitiator>;
+    /**
+     * Create the responder side of the handshake from the initiator's hello.
+     *
+     * Generates an ephemeral X25519 keypair, encapsulates against the
+     * initiator's ML-KEM public key, and derives the session key.
+     * Send `responder.hello` to the initiator.
+     *
+     * @param initiatorHello  The `hello` object received from the initiator.
+     * @returns  `SPDHandshakeResponder` instance.
+     * @throws   If any input is malformed or a low-order point is detected.
+     */
+    static createResponder(initiatorHello: SPDHandshakeHello): Promise<SPDHandshakeResponder>;
+}
+
+export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, SPDHandshake, type SPDHandshakeHello, SPDHandshakeInitiator, SPDHandshakeResponder, SPDHandshakeResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };

package/index.d.ts

@@ -1366,4 +1366,186 @@ declare class SPDShamir {
     static decodeShare(encoded: string): SPDShamirShare;
 }
 
-export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };
+/**
+ * SPDHandshake — Hybrid post-quantum ephemeral key agreement for SPD sessions.
+ *
+ * ## Cryptographic design
+ *
+ * Uses a **X25519 + ML-KEM-768 hybrid** construction:
+ *
+ *   x25519_ss  = X25519(myPriv, theirPub)          — classical ECDH
+ *   mlkem_ss   = ML-KEM-768 encap/decap             — post-quantum KEM (NIST FIPS 203)
+ *   transcript = SHA3-512(loNonce ∥ hiNonce)        — session-binding salt
+ *   sessionKey = HKDF-SHA-512(
+ *                  IKM  = x25519_ss ∥ mlkem_ss,
+ *                  salt = transcript,
+ *                  info = 'spd-hs-session-v1'
+ *                )
+ *
+ * Breaking the session key requires breaking **both** X25519 (hard classically)
+ * **and** ML-KEM-768 (hard for quantum computers) simultaneously.
+ *
+ * ## Security properties
+ *
+ * | Property                        | Mechanism                                              |
+ * |---------------------------------|--------------------------------------------------------|
+ * | Classical hardness              | X25519 ECDH — ~2^128 classical operations              |
+ * | Quantum hardness                | ML-KEM-768 — NIST FIPS 203, ~2^178 quantum ops        |
+ * | Perfect forward secrecy         | All keypairs ephemeral, zeroed after derive()          |
+ * | Memory safety                   | Private keys XOR-blinded immediately after creation    |
+ * | Key commitment (CMT-4)          | SHA3-256(sessionKey ∥ transcript) — verify before use  |
+ * | Cross-session binding           | 32-byte CSPRNG nonce per session mixed into HKDF       |
+ * | Domain separation               | Distinct HKDF info strings per key purpose             |
+ * | Timing safety                   | timingSafeEqual for all sensitive comparisons          |
+ * | Low-order point rejection       | All-zero DH output rejected before HKDF                |
+ * | Input validation                | Type + length checked on all inputs                    |
+ * | Zero-on-free                    | All key material zeroed explicitly via sodium.memzero  |
+ *
+ * ## Handshake flow
+ *
+ * The initiator (e.g. client) drives ML-KEM encapsulation:
+ *
+ * ```
+ *  INITIATOR                              RESPONDER
+ *  ─────────────────────────────────────────────────────
+ *  hs = SPDHandshake.createInitiator()
+ *  send → { x25519Pub, kemPub, nonce }
+ *                                         hs = await SPDHandshake.createResponder(
+ *                                                initiatorHello)
+ *                                         send → { x25519Pub, kemCt, nonce }
+ *  result = await hs.finalizeInitiator(
+ *             responderHello)
+ *                                         result = hs.responderResult()
+ *  // result.commitment === responderResult.commitment
+ *  // exchange commitments to confirm matching keys
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { SPDHandshake, SPD } from 'spd-lib';
+ *
+ * // ── Initiator (client) ───────────────────────────────────────────────────────
+ * const init = await SPDHandshake.createInitiator();
+ * socket.send(JSON.stringify(init.hello));         // { x25519Pub, kemPub, nonce }
+ *
+ * const respHello = JSON.parse(await socket.recv());
+ * const initResult = await init.finalizeInitiator(respHello);
+ *
+ * // ── Responder (server) ───────────────────────────────────────────────────────
+ * const resp = await SPDHandshake.createResponder(initHello);
+ * socket.send(JSON.stringify(resp.hello));         // { x25519Pub, kemCt, nonce }
+ * const respResult = resp.responderResult();
+ *
+ * // ── Both sides: verify commitment matches before using key ───────────────────
+ * // exchange initResult.commitment <→ respResult.commitment over the wire
+ * // if they match, both sides have the same session key
+ *
+ * const spd = new SPD();
+ * spd.setKeyProfile('standard');   // session key is already 256-bit entropy
+ * await spd.setPassKey(initResult.sessionKey);
+ * initResult.destroy();            // zero raw key bytes from memory
+ * ```
+ */
+/** Message sent during the handshake exchange. */
+interface SPDHandshakeHello {
+    /** Base64url-encoded X25519 public key (32 bytes). */
+    x25519Pub: string;
+    /**
+     * Initiator hello: base64url-encoded ML-KEM-768 public key (1184 bytes).
+     * Responder hello: base64url-encoded ML-KEM-768 ciphertext (1088 bytes).
+     */
+    kemData: string;
+    /** Base64url-encoded random session nonce (32 bytes). */
+    nonce: string;
+}
+/**
+ * Completed handshake result.
+ * Call `destroy()` immediately after passing `sessionKey` to `spd.setPassKey()`.
+ */
+declare class SPDHandshakeResult {
+    /**
+     * 64-character hex session passphrase (256 bits of entropy).
+     * Pass directly to `spd.setPassKey()`.
+     */
+    readonly sessionKey: string;
+    /**
+     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ transcriptHash).
+     * Base64url-encoded (32 bytes).
+     *
+     * Exchange this with the other party and verify they match BEFORE using
+     * `sessionKey`. If they differ, abort — a MITM substituted a key.
+     */
+    readonly commitment: string;
+    private _raw;
+    /** @internal */
+    constructor(raw: Buffer, transcript: Buffer);
+    /**
+     * Zero the raw session key bytes from memory.
+     * The `sessionKey` hex string may still exist in the JS heap
+     * (strings are immutable in V8); call this as soon as `setPassKey()` is done.
+     */
+    destroy(): void;
+}
+/** Initiator state returned by `SPDHandshake.createInitiator()`. */
+declare class SPDHandshakeInitiator {
+    /** Send this to the responder. */
+    readonly hello: SPDHandshakeHello;
+    private _x25519Priv;
+    private _kemSecretMask;
+    private _blindedKemSK;
+    private _nonceRaw;
+    private _done;
+    /** @internal */
+    constructor(x25519PrivRaw: Buffer, x25519PubRaw: Buffer, kemSecretKey: Uint8Array, kemPublicKey: Uint8Array, nonce: Buffer);
+    /**
+     * Complete the initiator side of the handshake using the responder's hello.
+     *
+     * @param responderHello  The `hello` object received from the responder.
+     * @returns  `SPDHandshakeResult` — call `.destroy()` after `setPassKey()`.
+     * @throws   If already called, or if any input is malformed.
+     */
+    finalizeInitiator(responderHello: SPDHandshakeHello): Promise<SPDHandshakeResult>;
+    /** Zero all key material. Call if abandoning the handshake. */
+    destroy(): void;
+}
+/** Responder state returned by `SPDHandshake.createResponder()`. */
+declare class SPDHandshakeResponder {
+    /** Send this to the initiator. */
+    readonly hello: SPDHandshakeHello;
+    private _result;
+    /** @internal */
+    constructor(hello: SPDHandshakeHello, result: SPDHandshakeResult);
+    /**
+     * Return the completed session result.
+     * The responder derives its key during `createResponder()` — call this
+     * after sending `hello` to the initiator.
+     */
+    responderResult(): SPDHandshakeResult;
+}
+declare class SPDHandshake {
+    private constructor();
+    /**
+     * Create the initiator side of the handshake.
+     *
+     * Generates an ephemeral X25519 keypair and ML-KEM-768 keypair.
+     * Send `initiator.hello` to the responder.
+     *
+     * @returns  `SPDHandshakeInitiator` instance.
+     */
+    static createInitiator(): Promise<SPDHandshakeInitiator>;
+    /**
+     * Create the responder side of the handshake from the initiator's hello.
+     *
+     * Generates an ephemeral X25519 keypair, encapsulates against the
+     * initiator's ML-KEM public key, and derives the session key.
+     * Send `responder.hello` to the initiator.
+     *
+     * @param initiatorHello  The `hello` object received from the initiator.
+     * @returns  `SPDHandshakeResponder` instance.
+     * @throws   If any input is malformed or a low-order point is detected.
+     */
+    static createResponder(initiatorHello: SPDHandshakeHello): Promise<SPDHandshakeResponder>;
+}
+
+export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, SPDHandshake, type SPDHandshakeHello, SPDHandshakeInitiator, SPDHandshakeResponder, SPDHandshakeResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };