spd-lib 1.4.2 → 1.4.3

package/index.d.mts

@@ -1367,111 +1367,185 @@ declare class SPDShamir {
 }
 
 /**
- * SPDHandshake — Ephemeral X25519 ECDH key agreement for SPD sessions.
+ * SPDHandshake — Hybrid post-quantum ephemeral key agreement for SPD sessions.
  *
- * Aligns with SPD v29 security model:
- *  - X25519 ECDH ephemeral keypair — perfect forward secrecy
- *  - Private key blinded in memory (XOR mask) between create() and derive()
- *  - HKDF-SHA-512 with SHA3-512 transcript hash as salt (domain-separated,
- *    consistent with SPD's spd-aead-key-v1 / spd-mac-key-v1 pattern)
- *  - Session nonce mixed into HKDF — prevents cross-session reuse attacks
- *  - CMT-4 key commitment: SHA3-256(sessionKey ∥ sessionNonce) returned so
- *    both sides can verify they derived the same key without revealing it
- *  - timingSafeEqual for all public key comparisons
- *  - All key material zeroed immediately after use
+ * ## 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
- * // ── Server ──────────────────────────────────────────────────────
- * const server = SPDHandshake.create();
- * // send to client: { publicKey: server.publicKey, nonce: server.sessionNonce }
+ * import { SPDHandshake, SPD } from 'spd-lib';
  *
- * // ── Client (after receiving server publicKey + nonce) ────────────
- * const client = SPDHandshake.create();
- * // send to server: { publicKey: client.publicKey, nonce: client.sessionNonce }
- * const clientResult = client.derive(server.publicKey, server.sessionNonce);
+ * // ── Initiator (client) ───────────────────────────────────────────────────────
+ * const init = await SPDHandshake.createInitiator();
+ * socket.send(JSON.stringify(init.hello));         // { x25519Pub, kemPub, nonce }
  *
- * // ── Server (after receiving client publicKey + nonce) ────────────
- * const serverResult = server.derive(client.publicKey, client.sessionNonce);
+ * const respHello = JSON.parse(await socket.recv());
+ * const initResult = await init.finalizeInitiator(respHello);
  *
- * // Verify both sides derived the same key (compare commitments over the wire)
- * // clientResult.commitment === serverResult.commitment  →  true
+ * // ── Responder (server) ───────────────────────────────────────────────────────
+ * const resp = await SPDHandshake.createResponder(initHello);
+ * socket.send(JSON.stringify(resp.hello));         // { x25519Pub, kemCt, nonce }
+ * const respResult = resp.responderResult();
  *
- * // Use session passphrase directly with SPD (already 256-bit entropy)
- * const spd = new SPD();
- * spd.setKeyProfile('standard');
- * await spd.setPassKey(serverResult.sessionKey);
+ * // ── 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
  *
- * // Zero the passphrase from memory when done with setup
- * serverResult.destroy();
+ * 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;
+}
 /**
- * Result of a completed handshake derivation.
- * Holds the session passphrase and key commitment.
- * Call `destroy()` once the passphrase has been handed to SPD's `setPassKey`.
+ * Completed handshake result.
+ * Call `destroy()` immediately after passing `sessionKey` to `spd.setPassKey()`.
  */
 declare class SPDHandshakeResult {
-    /** 64-char hex session passphrase (256 bits). Pass to `spd.setPassKey()`. */
+    /**
+     * 64-character hex session passphrase (256 bits of entropy).
+     * Pass directly to `spd.setPassKey()`.
+     */
     readonly sessionKey: string;
     /**
-     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ sessionNonce).
-     * Base64url-encoded, 32 bytes.  Share over the wire so both parties can
-     * verify they derived the same secret without revealing the secret itself.
+     * 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, nonce: Buffer);
-    /** Zero the raw session key bytes from memory. */
+    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;
 }
-/** An ephemeral X25519 handshake participant. */
-declare class SPDHandshake {
+/** 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);
     /**
-     * Base64url-encoded X25519 public key (32 bytes).
-     * Transmit this to the other party.
+     * 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.
      */
-    readonly publicKey: string;
+    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);
     /**
-     * Cryptographically random session nonce (32 bytes, base64url).
-     * Transmit this alongside `publicKey`. Mixed into HKDF to prevent
-     * cross-session key reuse even if the same ephemeral keypair were
-     * somehow reused.
+     * Return the completed session result.
+     * The responder derives its key during `createResponder()` — call this
+     * after sending `hello` to the initiator.
      */
-    readonly sessionNonce: string;
-    private _blindedPriv;
-    private _privMask;
-    private _nonceRaw;
+    responderResult(): SPDHandshakeResult;
+}
+declare class SPDHandshake {
     private constructor();
     /**
-     * Create a new ephemeral participant with a freshly generated X25519 keypair
-     * and a random session nonce.
-     */
-    static create(): SPDHandshake;
-    /**
-     * Derive the shared session key from the other party's public key and nonce.
+     * Create the initiator side of the handshake.
      *
-     * Both parties must call `derive()` with each other's `publicKey` and
-     * `sessionNonce`. The resulting `SPDHandshakeResult.commitment` values will
-     * match if and only if both sides derived the same key.
+     * Generates an ephemeral X25519 keypair and ML-KEM-768 keypair.
+     * Send `initiator.hello` to the responder.
      *
-     * @param theirPublicKey   The other party's `publicKey` string.
-     * @param theirSessionNonce  The other party's `sessionNonce` string.
-     * @returns  `SPDHandshakeResult` containing the session passphrase and
-     *           CMT-4 key commitment. Call `.destroy()` after handing the
-     *           passphrase to `spd.setPassKey()`.
-     * @throws   If `derive()` has already been called on this instance.
-     * @throws   If the public key is malformed or the low-order point check fails.
+     * @returns  `SPDHandshakeInitiator` instance.
      */
-    derive(theirPublicKey: string, theirSessionNonce: string): SPDHandshakeResult;
+    static createInitiator(): Promise<SPDHandshakeInitiator>;
     /**
-     * Zero and release all key material.
-     * Called automatically by `derive()`. Call manually if you abandon the
-     * handshake without completing it.
+     * 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.
      */
-    destroy(): void;
+    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, 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 };
+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

@@ -1367,111 +1367,185 @@ declare class SPDShamir {
 }
 
 /**
- * SPDHandshake — Ephemeral X25519 ECDH key agreement for SPD sessions.
+ * SPDHandshake — Hybrid post-quantum ephemeral key agreement for SPD sessions.
  *
- * Aligns with SPD v29 security model:
- *  - X25519 ECDH ephemeral keypair — perfect forward secrecy
- *  - Private key blinded in memory (XOR mask) between create() and derive()
- *  - HKDF-SHA-512 with SHA3-512 transcript hash as salt (domain-separated,
- *    consistent with SPD's spd-aead-key-v1 / spd-mac-key-v1 pattern)
- *  - Session nonce mixed into HKDF — prevents cross-session reuse attacks
- *  - CMT-4 key commitment: SHA3-256(sessionKey ∥ sessionNonce) returned so
- *    both sides can verify they derived the same key without revealing it
- *  - timingSafeEqual for all public key comparisons
- *  - All key material zeroed immediately after use
+ * ## 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
- * // ── Server ──────────────────────────────────────────────────────
- * const server = SPDHandshake.create();
- * // send to client: { publicKey: server.publicKey, nonce: server.sessionNonce }
+ * import { SPDHandshake, SPD } from 'spd-lib';
  *
- * // ── Client (after receiving server publicKey + nonce) ────────────
- * const client = SPDHandshake.create();
- * // send to server: { publicKey: client.publicKey, nonce: client.sessionNonce }
- * const clientResult = client.derive(server.publicKey, server.sessionNonce);
+ * // ── Initiator (client) ───────────────────────────────────────────────────────
+ * const init = await SPDHandshake.createInitiator();
+ * socket.send(JSON.stringify(init.hello));         // { x25519Pub, kemPub, nonce }
  *
- * // ── Server (after receiving client publicKey + nonce) ────────────
- * const serverResult = server.derive(client.publicKey, client.sessionNonce);
+ * const respHello = JSON.parse(await socket.recv());
+ * const initResult = await init.finalizeInitiator(respHello);
  *
- * // Verify both sides derived the same key (compare commitments over the wire)
- * // clientResult.commitment === serverResult.commitment  →  true
+ * // ── Responder (server) ───────────────────────────────────────────────────────
+ * const resp = await SPDHandshake.createResponder(initHello);
+ * socket.send(JSON.stringify(resp.hello));         // { x25519Pub, kemCt, nonce }
+ * const respResult = resp.responderResult();
  *
- * // Use session passphrase directly with SPD (already 256-bit entropy)
- * const spd = new SPD();
- * spd.setKeyProfile('standard');
- * await spd.setPassKey(serverResult.sessionKey);
+ * // ── 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
  *
- * // Zero the passphrase from memory when done with setup
- * serverResult.destroy();
+ * 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;
+}
 /**
- * Result of a completed handshake derivation.
- * Holds the session passphrase and key commitment.
- * Call `destroy()` once the passphrase has been handed to SPD's `setPassKey`.
+ * Completed handshake result.
+ * Call `destroy()` immediately after passing `sessionKey` to `spd.setPassKey()`.
  */
 declare class SPDHandshakeResult {
-    /** 64-char hex session passphrase (256 bits). Pass to `spd.setPassKey()`. */
+    /**
+     * 64-character hex session passphrase (256 bits of entropy).
+     * Pass directly to `spd.setPassKey()`.
+     */
     readonly sessionKey: string;
     /**
-     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ sessionNonce).
-     * Base64url-encoded, 32 bytes.  Share over the wire so both parties can
-     * verify they derived the same secret without revealing the secret itself.
+     * 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, nonce: Buffer);
-    /** Zero the raw session key bytes from memory. */
+    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;
 }
-/** An ephemeral X25519 handshake participant. */
-declare class SPDHandshake {
+/** 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);
     /**
-     * Base64url-encoded X25519 public key (32 bytes).
-     * Transmit this to the other party.
+     * 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.
      */
-    readonly publicKey: string;
+    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);
     /**
-     * Cryptographically random session nonce (32 bytes, base64url).
-     * Transmit this alongside `publicKey`. Mixed into HKDF to prevent
-     * cross-session key reuse even if the same ephemeral keypair were
-     * somehow reused.
+     * Return the completed session result.
+     * The responder derives its key during `createResponder()` — call this
+     * after sending `hello` to the initiator.
      */
-    readonly sessionNonce: string;
-    private _blindedPriv;
-    private _privMask;
-    private _nonceRaw;
+    responderResult(): SPDHandshakeResult;
+}
+declare class SPDHandshake {
     private constructor();
     /**
-     * Create a new ephemeral participant with a freshly generated X25519 keypair
-     * and a random session nonce.
-     */
-    static create(): SPDHandshake;
-    /**
-     * Derive the shared session key from the other party's public key and nonce.
+     * Create the initiator side of the handshake.
      *
-     * Both parties must call `derive()` with each other's `publicKey` and
-     * `sessionNonce`. The resulting `SPDHandshakeResult.commitment` values will
-     * match if and only if both sides derived the same key.
+     * Generates an ephemeral X25519 keypair and ML-KEM-768 keypair.
+     * Send `initiator.hello` to the responder.
      *
-     * @param theirPublicKey   The other party's `publicKey` string.
-     * @param theirSessionNonce  The other party's `sessionNonce` string.
-     * @returns  `SPDHandshakeResult` containing the session passphrase and
-     *           CMT-4 key commitment. Call `.destroy()` after handing the
-     *           passphrase to `spd.setPassKey()`.
-     * @throws   If `derive()` has already been called on this instance.
-     * @throws   If the public key is malformed or the low-order point check fails.
+     * @returns  `SPDHandshakeInitiator` instance.
      */
-    derive(theirPublicKey: string, theirSessionNonce: string): SPDHandshakeResult;
+    static createInitiator(): Promise<SPDHandshakeInitiator>;
     /**
-     * Zero and release all key material.
-     * Called automatically by `derive()`. Call manually if you abandon the
-     * handshake without completing it.
+     * 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.
      */
-    destroy(): void;
+    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, 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 };
+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 };