spd-lib 1.4.0 → 1.4.2

package/index.d.mts

@@ -1366,4 +1366,112 @@ 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 — Ephemeral X25519 ECDH 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
+ *
+ * ## Usage
+ *
+ * ```ts
+ * // ── Server ──────────────────────────────────────────────────────
+ * const server = SPDHandshake.create();
+ * // send to client: { publicKey: server.publicKey, nonce: server.sessionNonce }
+ *
+ * // ── 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);
+ *
+ * // ── Server (after receiving client publicKey + nonce) ────────────
+ * const serverResult = server.derive(client.publicKey, client.sessionNonce);
+ *
+ * // Verify both sides derived the same key (compare commitments over the wire)
+ * // clientResult.commitment === serverResult.commitment  →  true
+ *
+ * // Use session passphrase directly with SPD (already 256-bit entropy)
+ * const spd = new SPD();
+ * spd.setKeyProfile('standard');
+ * await spd.setPassKey(serverResult.sessionKey);
+ *
+ * // Zero the passphrase from memory when done with setup
+ * serverResult.destroy();
+ * ```
+ */
+/**
+ * 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`.
+ */
+declare class SPDHandshakeResult {
+    /** 64-char hex session passphrase (256 bits). Pass 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.
+     */
+    readonly commitment: string;
+    private _raw;
+    /** @internal */
+    constructor(raw: Buffer, nonce: Buffer);
+    /** Zero the raw session key bytes from memory. */
+    destroy(): void;
+}
+/** An ephemeral X25519 handshake participant. */
+declare class SPDHandshake {
+    /**
+     * Base64url-encoded X25519 public key (32 bytes).
+     * Transmit this to the other party.
+     */
+    readonly publicKey: string;
+    /**
+     * 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.
+     */
+    readonly sessionNonce: string;
+    private _blindedPriv;
+    private _privMask;
+    private _nonceRaw;
+    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.
+     *
+     * 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.
+     *
+     * @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.
+     */
+    derive(theirPublicKey: string, theirSessionNonce: string): SPDHandshakeResult;
+    /**
+     * Zero and release all key material.
+     * Called automatically by `derive()`. Call manually if you abandon the
+     * handshake without completing it.
+     */
+    destroy(): void;
+}
+
+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 };

package/index.d.ts

@@ -1366,4 +1366,112 @@ 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 — Ephemeral X25519 ECDH 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
+ *
+ * ## Usage
+ *
+ * ```ts
+ * // ── Server ──────────────────────────────────────────────────────
+ * const server = SPDHandshake.create();
+ * // send to client: { publicKey: server.publicKey, nonce: server.sessionNonce }
+ *
+ * // ── 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);
+ *
+ * // ── Server (after receiving client publicKey + nonce) ────────────
+ * const serverResult = server.derive(client.publicKey, client.sessionNonce);
+ *
+ * // Verify both sides derived the same key (compare commitments over the wire)
+ * // clientResult.commitment === serverResult.commitment  →  true
+ *
+ * // Use session passphrase directly with SPD (already 256-bit entropy)
+ * const spd = new SPD();
+ * spd.setKeyProfile('standard');
+ * await spd.setPassKey(serverResult.sessionKey);
+ *
+ * // Zero the passphrase from memory when done with setup
+ * serverResult.destroy();
+ * ```
+ */
+/**
+ * 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`.
+ */
+declare class SPDHandshakeResult {
+    /** 64-char hex session passphrase (256 bits). Pass 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.
+     */
+    readonly commitment: string;
+    private _raw;
+    /** @internal */
+    constructor(raw: Buffer, nonce: Buffer);
+    /** Zero the raw session key bytes from memory. */
+    destroy(): void;
+}
+/** An ephemeral X25519 handshake participant. */
+declare class SPDHandshake {
+    /**
+     * Base64url-encoded X25519 public key (32 bytes).
+     * Transmit this to the other party.
+     */
+    readonly publicKey: string;
+    /**
+     * 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.
+     */
+    readonly sessionNonce: string;
+    private _blindedPriv;
+    private _privMask;
+    private _nonceRaw;
+    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.
+     *
+     * 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.
+     *
+     * @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.
+     */
+    derive(theirPublicKey: string, theirSessionNonce: string): SPDHandshakeResult;
+    /**
+     * Zero and release all key material.
+     * Called automatically by `derive()`. Call manually if you abandon the
+     * handshake without completing it.
+     */
+    destroy(): void;
+}
+
+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 };