spd-lib 1.3.5 → 1.3.7

package/index.d.mts

@@ -22,11 +22,46 @@ interface SPDPayload {
     saltNonce: number[];
     wrapSalt: number[];
     version: number;
+    writeCounter?: number;
     hashAlgorithm?: string;
     argon2Memory?: number;
     argon2Time?: number;
     argon2HashLen?: number;
     hashKeyLen?: number;
+    argon2Parallelism?: number;
+    entryRoles?: Record<string, string[]>;
+    maxOpenCount?: number;
+    openCount?: number;
+    keyProfile?: string;
+    keyCommitment?: string;
+    kdfChain?: boolean;
+    scryptN?: number;
+    scryptR?: number;
+    scryptP?: number;
+    wrapArgon2Memory?: number;
+    wrapArgon2Time?: number;
+    fileSignature?: number[];
+    signingPubKey?: number[];
+    ratchetEnabled?: boolean;
+    ratchetCounter?: number;
+    epochNumber?: number;
+    epochSize?: number;
+    merkleRoot?: string;
+    counterHMAC?: string;
+}
+/** PKCS#11 / HSM key provider abstraction. Implement this interface to use hardware keys. */
+interface SPDKeyProvider {
+    /** Derive the 96-byte master secret from a passcode and salt (replaces Argon2id). */
+    deriveKey(passcode: string, salt: Uint8Array, memory: number, time: number): Promise<Uint8Array>;
+    /** Optional: wrap (encrypt) a key for storage — used when exporting key material. */
+    wrapKey?(key: Uint8Array): Promise<Uint8Array>;
+    /** Optional: unwrap (decrypt) a key retrieved from storage. */
+    unwrapKey?(wrapped: Uint8Array): Promise<Uint8Array>;
+}
+/** ML-DSA-65 signing key pair for file authentication. Signatures are 3309 bytes. */
+interface SPDSigningKeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
 }
 interface SPDLegacyPayload {
     data: SerializedDataEntry[];
@@ -82,11 +117,62 @@ interface SPDGetEntryResult {
     dataType: SupportedDataType;
     name: string;
 }
+interface SPDInspectResult {
+    version: number;
+    entryCount: number;
+    writeCounter: number;
+    hashAlgorithm: string;
+    argon2Memory: number;
+    argon2Time: number;
+    fileSize: number;
+    hasIndex: boolean;
+    format: 'binary' | 'json';
+}
+interface SPDVerifyResult {
+    valid: boolean;
+    entryCount: number;
+    indexPresent: boolean;
+    writeCounter: number;
+}
+interface SPDDiffResult {
+    added: string[];
+    removed: string[];
+    modified: string[];
+}
+interface SPDMergeOptions {
+    strategy: 'a-wins' | 'b-wins' | 'newer';
+}
+interface SPDSnapshot {
+    /** Encrypted entries captured at snapshot time (deep copies). */
+    data: EncryptedDataEntry[];
+    writeCounter: number;
+    ts: number;
+}
+interface SPDLogEvent {
+    event: 'key_derived' | 'key_cache_hit' | 'entry_added' | 'entry_updated' | 'entry_deleted' | 'save_start' | 'save_end' | 'load_start' | 'load_end' | 'rollback_detected' | 'lock_acquired' | 'lock_released' | 'wal_flushed' | 'auto_destruct' | 'repair_complete' | 'benchmark_complete' | 'keyfile_generated' | 'keyfile_loaded';
+    ts: number;
+    detail?: Record<string, unknown>;
+}
+interface SPDBenchmarkResult {
+    argon2Ms: number;
+    encryptMs: number;
+    decryptMs: number;
+    macMs: number;
+    entriesPerSecond: number;
+}
+interface SPDRepairResult {
+    recovered: number;
+    skipped: number;
+}
 type TypedArray = Uint8Array | Uint16Array | Uint32Array | BigInt64Array | BigUint64Array | Float32Array | Float64Array;
 type SupportedValue = string | number | boolean | unknown[] | TypedArray | Map<unknown, unknown> | Set<unknown> | Date | RegExp | Error | Record<string, unknown>;
 
 declare const ARGON2_MEMORY_HIGH = 524288;
 declare const ARGON2_TIME_HIGH = 8;
+declare const ARGON2_MEMORY_PARANOID = 2097152;
+declare const ARGON2_TIME_PARANOID = 16;
+/** Key stretching profile names */
+type SPDKeyProfile = 'standard' | 'high' | 'paranoid';
 declare class SPD {
     private data;
     private keyPair?;
@@ -95,8 +181,119 @@ declare class SPD {
     private salt?;
     private hash;
     private compressionLevel;
+    private fileVersion;
+    private writeCounter;
+    private walPath?;
+    private walRecordCount;
+    private static readonly WAL_COMPACT_RECORDS;
+    private static readonly WAL_COMPACT_BYTES;
+    private static globalPepper;
+    private static keyfileBytes;
+    private entryRoles;
+    private currentRole;
+    private maxOpenCount;
+    private openCount;
+    private schemas;
+    private _plogPath?;
+    private keyProfile;
+    private static machineBindingEnabled;
+    private _keyMask?;
+    private _blindedKey?;
+    private _blindedMacKey?;
+    private _keyBlindingEnabled;
+    private _signingKey?;
+    private _verifyKey?;
+    private _ratchetEnabled;
+    private _epochSize;
+    private _epochNumber;
+    private static _keyProvider?;
+    private _kdfChain;
+    private _scryptN;
+    private _scryptR;
+    private _scryptP;
+    private _argon2Parallelism;
+    private _wrapArgon2Memory;
+    private _wrapArgon2Time;
+    private static globalLogger;
+    private static keyCache;
+    private static keyCacheGet;
+    private static keyCacheSet;
+    /** Build a non-secret cache key from the passcode and wrapSalt bytes. */
+    private static buildCacheKey;
+    /** Evict all cached key material immediately (e.g. on pepper change). */
+    static clearKeyCache(): void;
+    private static nameCollisionWarnings;
+    /**
+     * Enable developer warnings when two raw entry names map to the same
+     * sanitized name (e.g. "user.id" and "user_id" → both become "user_id").
+     * Logs to console.warn. Off by default to avoid noise in production.
+     */
+    static enableNameCollisionWarnings(): void;
+    static disableNameCollisionWarnings(): void;
+    /**
+     * Install a global log handler. Called for key lifecycle events so the host
+     * app can feed SPD activity into its own observability pipeline.
+     * Pass `undefined` to remove the handler.
+     */
+    static setLogger(fn: ((e: SPDLogEvent) => void) | undefined): void;
+    private static log;
     private assertReady;
     init(): Promise<void>;
+    /**
+     * Enable in-memory key blinding: keys are stored XOR'd with a random mask.
+     * This reduces the risk of key extraction from memory dumps or cold-boot attacks.
+     * Must be called before `setPassKey()`.
+     */
+    enableKeyBlinding(): void;
+    disableKeyBlinding(): void;
+    private static _xorBufs;
+    /** Blind the current userKey and macKey with a fresh random mask. */
+    private _blindKeys;
+    /** Unblind keys into temporaries, run fn, then re-blind. */
+    private _withKeys;
+    private _withKeysAsync;
+    /**
+     * Set an ML-DSA-65 signing private key. When set, every `saveToFile` /
+     * `saveToFileStreaming` call will embed an ML-DSA-65 signature over the file MAC.
+     */
+    setSigningKey(privateKey: Uint8Array): void;
+    /**
+     * Set an ML-DSA-65 verify public key. When set, `loadFromFile` /
+     * `loadFromFileStreaming` will verify the embedded signature and reject
+     * files that fail verification.
+     */
+    setVerifyKey(publicKey: Uint8Array): void;
+    /** Generate a fresh ML-DSA-65 signing key pair. */
+    static generateSigningKeyPair(): SPDSigningKeyPair;
+    /** Enable the per-save ratchet. Each save derives a new sub-key from the previous. */
+    enableRatchet(): void;
+    disableRatchet(): void;
+    /**
+     * Set the epoch size: every `n` saves, a new random salt is derived and all
+     * entries are re-encrypted under a fresh key. Pass 0 to disable.
+     */
+    setEpochSize(n: number): void;
+    /**
+     * Enable KDF chaining: after Argon2id, pipe output through scrypt for
+     * double-KDF protection. Enabled by default for `high` / `paranoid` profiles.
+     * @param n  scrypt CPU/memory cost (power of 2, default 16384)
+     * @param r  block size (default 8)
+     * @param p  parallelism (default 1)
+     */
+    enableKdfChain(n?: number, r?: number, p?: number): void;
+    disableKdfChain(): void;
+    /**
+     * Override the Argon2id parameters used to derive the salt-wrapping key.
+     * By default, standard params (128 MiB / 6 passes) are used for backward compatibility.
+     * Changing these breaks compatibility with existing files unless you also change the reader.
+     */
+    setWrapKeyProfile(memory: number, time: number): void;
+    /**
+     * Install a global PKCS#11 / HSM key provider. When set, SPD delegates
+     * all key derivation to `provider.deriveKey()` instead of Argon2id+scrypt.
+     * Pass `undefined` to revert to the built-in KDF.
+     */
+    static setKeyProvider(provider: SPDKeyProvider | undefined): void;
     changePasscode(oldPasscode: string, newPasscode: string): Promise<void>;
     /**
      * Derives a master secret via Argon2id and splits it into:
@@ -106,20 +303,250 @@ 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): 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;
     }>;
+    /**
+     * Compute a key commitment token: HMAC-SHA3-256(aeadKey, "spd-key-commit-v1").
+     * Stored in the file meta and verified on load before decryption begins.
+     * Closes key-commitment attacks where an adversary crafts a ciphertext that
+     * "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.
+     *
+     * Each entry is encrypted under a unique key = HKDF(masterKey, salt=entryName, info="spd-entry-v27").
+     * This means:
+     *   - Compromise of one entry's ciphertext reveals nothing about other entries' keys
+     *   - The master key never touches AEAD directly
+     *   - 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;
     getSodium(): typeof sodium;
+    /**
+     * Restrict an entry to one or more roles. `extractData`, `getEntry`, and the
+     * lazy `entries()` iterator will throw if `setRole()` has not been called with
+     * a matching role.  Pass an empty array to remove all restrictions.
+     */
+    restrictEntry(name: string, roles: string[]): void;
+    /**
+     * Set the active role for this instance.  Entries restricted to roles that
+     * don't include this value will be inaccessible until the role is changed.
+     * Pass `undefined` to clear the role (only unrestricted entries will be readable).
+     */
+    setRole(role: string | undefined): void;
+    /**
+     * Set the Argon2id cost profile for this instance.
+     * - `'standard'`  — 128 MiB / 6 passes (default, ~500 ms on modern hardware)
+     * - `'high'`      — 512 MiB / 8 passes (~2 s)
+     * - `'paranoid'`  — 1 GiB  / 12 passes + machine-secret post-KDF (~4–8 s)
+     *
+     * Must be set before `setPassKey()`.  The chosen profile's params are embedded
+     * in the file so loads always re-derive with the same cost.
+     */
+    setKeyProfile(profile: SPDKeyProfile): void;
+    /**
+     * Enable machine binding: mixes a stable machine-specific secret (derived
+     * from `/etc/machine-id`, `hostname`, or a UUID sidecar) into every key
+     * derivation via an extra HMAC step.  The resulting key is only reproducible
+     * on the originating machine, dramatically raising the cost of offline attacks
+     * with a stolen file.
+     *
+     * Enabling this globally affects all SPD instances in the process.
+     * Must be called before `setPassKey()` / `loadFromFile()` / `getEntry()`.
+     */
+    static enableMachineBinding(): void;
+    static disableMachineBinding(): void;
+    /** Reads or creates the machine secret (16-byte hex stored in ~/.spd-machine-id). */
+    private static getMachineSecret;
+    /**
+     * Post-KDF machine binding: HMAC-SHA3-512(machineSecret, rawKey)[0..keyLen].
+     * Applied to both aeadKey and macKey when machine binding is enabled.
+     */
+    private static applyMachineBinding;
+    /** Resolve Argon2id params from a profile name. */
+    static profileParams(profile: SPDKeyProfile): {
+        memory: number;
+        time: number;
+    };
+    /** Returns true if the current role is allowed to read `name`. */
+    private canReadEntry;
+    /**
+     * Configure a maximum open count for auto-destruct.
+     * After this many successful `loadFromFile` / `loadFromFileStreaming` calls the
+     * file is securely wiped and an error is thrown on the exceeding open.
+     * Set to 0 to disable (default).
+     */
+    setMaxOpenCount(n: number): void;
+    /**
+     * Persist the max-open-count limit to a `.maxcount` sidecar alongside `filePath`.
+     * Must be called after `saveToFile`/`saveToFileStreaming` so the sidecar is
+     * co-located with the file that was actually written.
+     * Callers who set a limit should call this immediately after saving.
+     */
+    static setFileMaxOpenCount(filePath: string, n: number): void;
+    /**
+     * Set the path to the passcode rotation audit log (.plog) sidecar file.
+     * A JSON-lines record `{ts, event}` is appended whenever `changePasscode` is
+     * called.  The file is created if it does not exist (mode 0600).
+     * Pass `undefined` to disable.
+     */
+    setPlogPath(p: string | undefined): void;
+    /**
+     * Attach a validator function to an entry name.
+     * Called before encryption in `addData` and `updateEntry`.
+     * Throw or return `false` to reject the value.
+     */
+    setSchema(name: string, validator: (v: unknown) => boolean): void;
+    /** Remove a previously registered schema validator. */
+    removeSchema(name: string): void;
+    private applySchema;
+    /**
+     * Returns an immutable snapshot of the current encrypted entries.
+     * No key material is included — use `restoreSnapshot` to apply.
+     */
+    snapshot(): SPDSnapshot;
+    /**
+     * Replaces the current encrypted entries with those from a snapshot.
+     * Key material is unchanged — the snapshot must have been taken from an
+     * instance with the same passcode.
+     */
+    restoreSnapshot(snap: SPDSnapshot): void;
     sanitizeName(dataName: string): string;
     addData(dataName: string, value: unknown): Promise<void>;
     addMany(items: DataInput[]): Promise<void>;
     extractData(): Promise<Record<string, unknown>>;
+    /** Returns true if an entry with the given name exists. No decryption. */
+    has(name: string): boolean;
+    /** Returns all entry names in insertion order. No decryption. */
+    keys(): string[];
+    /**
+     * Lazy decryption iterator — yields `{name, value, dataType}` one entry at a
+     * time without loading all entries into memory simultaneously.  Respects entry
+     * ACL roles; skips (does not throw) decoy entries silently.
+     *
+     * @example
+     * for await (const {name, value} of spd.entries()) {
+     *   console.log(name, value);
+     * }
+     */
+    entries(): AsyncGenerator<{
+        name: string;
+        value: unknown;
+        dataType: string;
+    }>;
+    /**
+     * Insert `count` fake encrypted entries whose names are derived from `prefix`.
+     * Decoys are indistinguishable from real entries in the binary/JSON file.
+     * They are silently skipped by `entries()` and flagged as `_decoy` type so
+     * callers that inspect `dataType` can filter them.
+     */
+    addDecoy(prefix: string, count?: number): Promise<void>;
+    /**
+     * Removes an entry by name. Throws if not found.
+     * Does NOT re-save to disk — call saveToFile/saveToFileStreaming after.
+     */
+    deleteEntry(name: string): void;
+    /**
+     * Renames an entry. Re-encrypts the blob under the new name's derived key + AAD.
+     * Throws if `oldName` is not found or `newName` already exists.
+     * Does NOT re-save to disk — call saveToFile/saveToFileStreaming after.
+     */
+    renameEntry(oldName: string, newName: string): Promise<void>;
+    /**
+     * Replaces an entry's value in place. Equivalent to deleteEntry + addData
+     * but preserves insertion order.
+     * Throws if the entry is not found.
+     * Does NOT re-save to disk — call saveToFile/saveToFileStreaming after.
+     */
+    updateEntry(name: string, value: unknown): Promise<void>;
+    /**
+     * Returns a new SPD instance (with the same key material) containing only the
+     * entries whose sanitized names match `pattern`.  The returned instance is
+     * ready for `saveToFile` / `saveToFileStreaming` — it shares no mutable state
+     * with the original.
+     *
+     * @param pattern  RegExp tested against each sanitized entry name.
+     * @returns        A new SPD instance carrying the matching encrypted entries.
+     */
+    exportEntries(pattern: RegExp): SPD;
+    /**
+     * Copies all entries from `source` into this instance.
+     * - Both instances must use the same passcode / key material.
+     * - If an entry name already exists it is overwritten.
+     * - Does NOT re-save to disk.
+     *
+     * @param source  Another SPD instance (must share the same AEAD / HMAC keys).
+     */
+    importEntries(source: SPD): void;
+    /** Returns the number of stored entries. */
+    count(): number;
     /**
      * Memory-efficient streaming extraction.
      *
@@ -143,32 +570,174 @@ declare class SPD {
      * });
      */
     extractDataStreaming(tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | void): Promise<void>;
+    /**
+     * Enables the write-ahead log. Once enabled, every `addData` / `addMany` call
+     * appends the encrypted entry to `walPath` atomically. On the next
+     * `loadFromFile` / `loadFromFileStreaming`, any existing WAL is replayed
+     * automatically before returning. `saveToFile` / `saveToFileStreaming` merges
+     * and then deletes the WAL.
+     *
+     * WAL record format (binary, appended):
+     *   [4B magic "SPDW"][1B version][1B nameLen][nameLen B name]
+     *   [1B typeLen][typeLen B type][2B hashLen][hashLen B hash]
+     *   [3B nonceLen][nonceLen B nonce][8B dataLen][dataLen B encData]
+     */
+    enableWal(walPath: string): void;
+    /** Disable WAL without deleting the file. */
+    disableWal(): void;
+    /** Append a single encrypted entry to the WAL file. Auto-compacts when thresholds are exceeded. */
+    private appendToWal;
+    /**
+     * Internal: called by setImmediate when WAL thresholds are exceeded.
+     * Requires a `walCompactPath` to be set; does nothing otherwise.
+     * Users should call `flushDelta(outputPath, passcode)` explicitly —
+     * auto-compaction only fires when `walCompactPath` is configured via `enableWal`.
+     */
+    private _walAutoCompact;
+    private _walCompactPath?;
+    private _walCompactPasscode?;
+    /**
+     * Configures the output path and passcode used for WAL auto-compaction.
+     * Must be called after `enableWal()` for auto-compaction to fire.
+     */
+    setWalCompactTarget(outputPath: string, passcode: string): void;
+    /**
+     * Reads and replays all entries from an existing WAL file into `this.data`.
+     * Skips duplicate names (WAL entry wins over existing). Returns entry count replayed.
+     */
+    static replayWal(walPath: string, target: SPD): number;
+    /**
+     * Merges any pending WAL entries, saves the full file, then deletes the WAL.
+     * Use this instead of `saveToFile` when WAL is enabled to ensure the WAL
+     * is atomically cleared only after a successful save.
+     */
+    flushDelta(outputPath: string, passcode: string, streaming?: boolean): Promise<void>;
     destroy(): void;
     clearCache(): void;
+    /**
+     * Sets a global pepper mixed into all Argon2id key derivations.
+     * Never stored in the file — both save and load sides must set the same pepper.
+     * Must be set before setPassKey / loadFromFile / loadFromString / getEntry.
+     */
+    static setPepper(pepper: string | Buffer): void;
+    /**
+     * Generate a cryptographically random 64-byte (512-bit) keyfile and write it
+     * to `filePath`.  The keyfile should be stored separately from the SPD file
+     * (e.g. USB drive, password manager, or HSM) so that an attacker who obtains
+     * the SPD file alone cannot attempt password guessing — the keyfile bytes are
+     * required as a second factor and are mixed into every Argon2id derivation.
+     *
+     * Never store the keyfile in the same directory as the SPD file.
+     *
+     * @example
+     * await SPD.generateKeyfile('/mnt/usb/my.key');
+     * SPD.loadKeyfile('/mnt/usb/my.key');
+     * const spd = new SPD();
+     * await spd.setPassKey('anything'); // passcode quality no longer matters
+     */
+    static generateKeyfile(filePath: string): void;
+    /**
+     * Load a keyfile previously created with `generateKeyfile()`.
+     * Must be called before `setPassKey()`, `loadFromFile()`, and any other
+     * operation that derives key material.
+     *
+     * The keyfile bytes are mixed into every Argon2id derivation via
+     * HMAC-SHA3-512(keyfileBytes, fileSalt || passcode), so:
+     *  - The same keyfile + any passcode ≠ the same keyfile + different passcode
+     *  - The same keyfile + same passcode on a different SPD file (different salt) ≠ same key
+     *  - Without the keyfile, no amount of passcode guessing succeeds
+     *
+     * @param filePath  Path to the keyfile (64 bytes of random data).
+     */
+    static loadKeyfile(filePath: string): void;
+    /**
+     * Unload the current keyfile so subsequent operations use passcode-only derivation.
+     * Call this when you are done with the SPD instance and want to remove the
+     * keyfile material from memory.
+     */
+    static unloadKeyfile(): void;
+    /**
+     * Generate a cryptographically random diceware passphrase from the EFF short
+     * wordlist (1296 words, ~10.3 bits of entropy per word).
+     *
+     * Default: 9 words → ~72 bits of entropy (256-word list, 8 bits/word) — resistant
+     * Argon2id-capable ASICs, and **centuries** at the `high` or `paranoid` profile.
+     *
+     * With a keyfile loaded alongside, the passphrase entropy is irrelevant — the
+     * keyfile provides 512 bits regardless. The passphrase then acts only as a
+     * second authentication factor.
+     *
+     * @param words  Number of words (minimum 5 = ~51 bits; default 7 = ~72 bits).
+     * @returns      A space-separated passphrase string, e.g. "apple cargo drum fence grain helm iris"
+     *
+     * @example
+     * const pass = SPD.generatePassphrase();
+     * // → "timber rivet angle plumb comet drift spark"
+     * const spd = new SPD();
+     * await spd.setPassKey(pass);
+     */
+    static generatePassphrase(words?: number): string;
+    /**
+  
+    /**
+     * Acquires an advisory lock for `filePath` by creating `filePath.lock`.
+     * The lock file contains JSON with PID and timestamp so stale locks
+     * (process dead or >30 s old) are automatically broken.
+     *
+     * If the lock is held by a live process, retries every 50 ms until
+     * `lockTimeoutMs` has elapsed (default 5 000 ms) before throwing `ESPD_LOCKED`.
+     */
+    static acquireLock(filePath: string, lockTimeoutMs?: number): void;
+    /** Releases the advisory lock for `filePath` (deletes `filePath.lock`). */
+    static releaseLock(filePath: string): void;
+    /** Path of the sequence sidecar file for `filePath`. */
+    private static seqPath;
+    /**
+     * Reads the last-seen write counter from the `.seq` sidecar.
+     * Returns -1 if no sidecar exists (first load — any counter is accepted).
+     */
+    private static readSeqCounter;
+    /** Writes the new write counter to the `.seq` sidecar (atomic rename). */
+    private static writeSeqCounter;
+    /**
+     * Verifies that a file's embedded write counter is ≥ the last-seen counter
+     * stored in the `.seq` sidecar.  Call after key derivation (needs plaintext
+     * meta) but before returning the loaded SPD instance.
+     * Throws if the counter indicates a rollback attack.
+     */
+    private static checkRollback;
     saveToFile(outputPath: string, passcode: string): Promise<void>;
     /**
      * Saves to file using streaming I/O — supports files larger than 2 GB.
      * Format: [8B LE uint64 plaintext length][64B HMAC-SHA3-512][zlib(plaintext)]
      *
-     * Also writes a `.spdi` index sidecar alongside the output file that allows
-     * `SPD.getEntry()` to locate entries without decrypting the whole file.
+     * Embeds a tail index (SPDx) for fast on-demand `getEntry()` lookups.
+     * Acquires an advisory lock on `outputPath` and releases it after save.
+     *
+     * @param onProgress  Optional callback — called with (bytesWritten, totalBytes)
+     *                    as plaintext bytes are fed through the deflate pipeline.
      */
-    saveToFileStreaming(outputPath: string, passcode: string): Promise<void>;
+    saveToFileStreaming(outputPath: string, passcode: string, onProgress?: (bytesWritten: number, totalBytes: number) => void): Promise<void>;
     /**
      * Computes the decompressed byte offset of each entry within a binary plaintext buffer.
      * The offset points to the start of that entry's nameLen byte.
      */
     private static buildOffsetIndex;
     /**
-     * Writes a `.spdi` index sidecar file for fast on-demand entry lookup.
-     * Format:
-     *   [4B magic "SPDI"][4B version][8B entryCount][32B HMAC-SHA3-256 of body]
-     *   for each entry: [1B nameLen][name bytes][8B LE uint64 decompressedOffset]
+     * Appends the entry offset index to the end of an already-written .spd file.
+     * Tail format: [32B HMAC-SHA3-256 of body][body: N×(1B nameLen + name + 8B offset)][8B indexStart][4B "SPDx"]
+     * The indexStart is the byte offset from the start of the file to the 32B HMAC.
      */
-    private static writeIndexFile;
+    private static embedIndexInFile;
     /**
-     * Reads and validates a `.spdi` index sidecar.
-     * Returns null if the file doesn't exist or the HMAC fails (falls back to scan).
+     * Writes a `.spdi` sidecar index file (same body format as the embedded tail
+     * but stored externally so it can be pre-warmed without modifying the `.spd`).
+     * Format: [4B "SPDI"][32B HMAC-SHA3-256 of body][body]
+     */
+    private static writeSidecarIndex;
+    /**
+     * Reads and validates the embedded tail index from a `.spd` file.
+     * Returns null if the file doesn't exist, has no embedded index, or the HMAC fails (falls back to scan).
      */
     private static readIndexFile;
     saveData(passcode?: string): Promise<string>;
@@ -183,8 +752,13 @@ declare class SPD {
      *   - Rounded up to the nearest 64 KB boundary for alignment
      */
     saveDataChunked(passcode: string, chunkSize?: number): Promise<string[]>;
-    static loadFromFile(filePath: string, passcode: string): Promise<SPD>;
-    static loadFromFileStreaming(filePath: string, passcode: string): Promise<SPD>;
+    static loadFromFile(filePath: string, passcode: string, verifyKey?: Uint8Array): Promise<SPD>;
+    static loadFromFileStreaming(filePath: string, passcode: string, onProgress?: (bytesRead: number, totalBytes: number) => void, verifyKey?: Uint8Array): Promise<SPD>;
+    /**
+     * Auto-destruct helper: reads/increments the open count sidecar (.ocount).
+     * If `maxOpenCount` is set and the new count exceeds it, wipes the file and throws.
+     */
+    private static checkAndIncrementOpenCount;
     /**
      * True constant-memory streaming extract from a binary SPD file.
      *
@@ -211,7 +785,7 @@ declare class SPD {
      *   console.log(name, typeof value);
      * });
      */
-    static extractFromFileStreaming(filePath: string, passcode: string, tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | void): Promise<void>;
+    static extractFromFileStreaming(filePath: string, passcode: string, tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | void, onProgress?: (bytesRead: number, totalBytes: number) => void): Promise<void>;
     /**
      * On-demand disk lookup — decrypts and returns a single named entry from a
      * binary `.spd` file (written by `saveToFileStreaming`) without loading the
@@ -227,13 +801,48 @@ declare class SPD {
      * RAM usage is bounded to ~one entry's worth of bytes at any time.
      */
     static getEntry(filePath: string, passcode: string, name: string): Promise<SPDGetEntryResult>;
+    /**
+     * Reads file metadata without any key derivation or decryption.
+     *
+     * For binary `.spd` files (written by `saveToFileStreaming` / `SPDWriter`):
+     *   reads the 72-byte header + decompresses just the meta block.
+     * For JSON `.spd` files (written by `saveToFile`):
+     *   decompresses and parses the outer JSON + payload JSON.
+     *
+     * No passcode required. Returns format, version, entry count, Argon2 params,
+     * file size, and whether a tail index (SPDx) is embedded.
+     */
+    static inspect(filePath: string): Promise<SPDInspectResult>;
+    /**
+     * Verifies file integrity (MAC check) without decrypting any entry values.
+     * Derives keys from passcode, verifies the HMAC over the entire plaintext,
+     * and returns a result object. Does not call any decrypt operation on entries.
+     *
+     * Useful for backup health checks: fast, safe, no plaintext produced.
+     */
+    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): Promise<EncryptedSaltResult>;
+    static encryptSalt(salt: Uint8Array, passcode: string, memory?: number, time?: number): Promise<EncryptedSaltResult>;
     static toBase64(data: Uint8Array | Buffer): string;
     static fromBase64(data: string): Uint8Array;
+    /**
+     * Build a SHA3-256 Merkle tree over an array of leaf hashes (hex strings).
+     * Returns the root hash as a hex string. Empty input returns the hash of "".
+     */
+    private static buildMerkleRoot;
+    private static computeCounterHMAC;
+    private _applyRatchet;
+    /** When ratchet is enabled, rotate to a fresh salt+keys before each save,
+     * re-encrypting all entries under the new key.
+     * Forward secrecy is achieved because each save uses a different salt.
+     */
+    private _maybeRatchetSalt;
+    private _maybeRotateEpoch;
+    /** Get the effective AEAD and MAC keys (handles blinding). */
+    private _getKeys;
     private buildSerializedPayload;
     private static parseSerializedPayload;
     private buildBinaryPayload;
@@ -243,6 +852,64 @@ declare class SPD {
     private isCollectionType;
     private convertInputToString;
     private convertStringToInput;
+    /**
+     * Compares two SPD files by entry name and hash — no entry decryption.
+     * Only key derivation is performed (to verify MACs before trusting hashes).
+     *
+     * @returns `{added, removed, modified}` arrays of sanitized entry names.
+     *   `added`    — names present in `fileB` but not `fileA`
+     *   `removed`  — names present in `fileA` but not `fileB`
+     *   `modified` — names present in both but with different ciphertext hashes
+     */
+    static diff(fileA: string, fileB: string, passcode: string): Promise<SPDDiffResult>;
+    /**
+     * Merges two SPD files into a new in-memory instance.
+     * - `'a-wins'` : conflicting entries keep file A's version.
+     * - `'b-wins'` : conflicting entries keep file B's version.
+     * - `'newer'`  : keeps the version from the file with the higher `writeCounter`
+     *                (file-level granularity, not per-entry).
+     *
+     * The returned instance uses file A's key material.  Call `saveToFile` /
+     * `saveToFileStreaming` to persist.
+     */
+    static merge(fileA: string, fileB: string, passcode: string, options?: SPDMergeOptions): Promise<SPD>;
+    /**
+     * Attempts partial recovery of a corrupt SPD file.
+     * Reads entries sequentially until the first parse/decrypt failure, then saves
+     * whatever was recovered to `outputPath`.
+     *
+     * Returns `{recovered, skipped}` counts.  If the file is a valid JSON payload
+     * it uses the JSON loader; otherwise it attempts binary streaming entry-by-entry.
+     */
+    static repair(filePath: string, passcode: string, outputPath: string): Promise<SPDRepairResult>;
+    /**
+     * Runs an in-memory self-test and returns timing/throughput numbers.
+     * Useful for choosing `argon2Memory`/`argon2Time` on the target hardware.
+     *
+     * Does NOT write any files or use any persistent state.
+     */
+    static benchmark(): Promise<SPDBenchmarkResult>;
+    /**
+     * Watches `filePath` for external changes and calls `cb` with the freshly
+     * loaded SPD instance and a diff report each time the file is modified.
+     *
+     * ```ts
+     * const stop = SPD.watch('/data/secrets.spd', 'pass', (spd, diff) => {
+     *   console.log('added:', diff.added);
+     * });
+     * // … later:
+     * stop();
+     * ```
+     *
+     * - Uses `fs.watchFile` (stat polling, 1 s interval) so it works on NFS /
+     *   Docker volumes where `fs.watch` inotify events are unreliable.
+     * - Re-loads via `SPD.loadFromFile` (JSON) with a `SPD.loadFromFileStreaming`
+     *   fallback for binary files.
+     * - If the reload throws, the error is swallowed and `cb` is **not** called
+     *   (avoids crashing the host process on transient FS errors).
+     * - Returns a `stop()` function; call it to un-watch and stop polling.
+     */
+    static watch(filePath: string, passcode: string, cb: (spd: SPD, diff: SPDDiffResult) => void): () => void;
 }
 
 /**
@@ -336,8 +1003,8 @@ declare class SPDVault {
  *   await writer.addEntry('config', { theme: 'dark' });
  *   await writer.finalize();
  *
- * After finalize(), a `.spdi` index sidecar is written alongside the output
- * file so that `SPD.getEntry()` can locate entries without a full scan.
+ * After finalize(), an index tail is embedded in the file itself so that
+ * `SPD.getEntry()` can locate entries without a full scan (no sidecar file).
  */
 
 declare class SPDWriter {
@@ -374,7 +1041,329 @@ declare class SPDWriter {
     destroy(): void;
     /** Write bytes to the deflate stream and update the rolling HMAC + offset. */
     private writeToPlaintext;
-    private writeIndexSidecar;
+    /**
+     * Appends the entry offset index to the end of the output file.
+     * Format: [32B HMAC-SHA3-256 of body][body][8B indexStart][4B "SPDx"]
+     * NOTE: macKey is still valid here — zeroed by finalize() AFTER this call.
+     */
+    private embedIndexTail;
+}
+
+/**
+ * SPDTransport — authenticated, forward-secret client↔server secure channel.
+ *
+ * ## Protocol versions
+ *
+ *  V1 (original): ephemeral Curve25519 ECDH only
+ *  V2 (v29+):     hybrid Curve25519 + ML-KEM-768, ML-DSA-65 certificate pinning,
+ *                 PSK session resumption
+ *
+ * ## What it provides
+ *
+ *  - **Ephemeral ECDH handshake** (Curve25519 via libsodium `crypto_kx`) so
+ *    every session produces a fresh pair of symmetric session keys.
+ *  - **ML-KEM-768 hybrid**: client additionally encapsulates to the server's
+ *    ML-KEM public key; the KEM shared secret is XOR-combined with the ECDH
+ *    secret so that breaking EITHER primitive does not compromise the session.
+ *  - **ML-DSA-65 certificate pinning**: the server's long-term identity can
+ *    include an ML-DSA-65 signing key pair; clients pin the ML-DSA public key
+ *    and the server signs each ServerHello, preventing MitM.
+ *  - **PSK session resumption**: a 32-byte pre-shared key can be mixed into
+ *    the session key derivation, allowing clients to resume a prior session
+ *    with an additional secret layer.
+ *  - **Forward secrecy**: all ephemeral key material is zeroed after handshake.
+ *  - **Two independent session streams**: `clientToServer` and `serverToClient`,
+ *    each with a monotonic 64-bit counter mixed into the XChaCha20-Poly1305
+ *    nonce — prevents nonce reuse and blocks replay attacks.
+ *  - **Message authentication**: every frame carries a Poly1305 tag.
+ *  - **Optional SPD payload wrapping**: `wrapSPD` / `unwrapSPD` let you
+ *    transmit an in-memory SPD binary payload over the channel.
+ *
+ * ## Threat model
+ *
+ *  ✅ Network eavesdropper — cannot read any session payload
+ *  ✅ Replay attack — monotonic counter prevents replaying old frames
+ *  ✅ Past-session decryption after key compromise — forward secrecy
+ *  ✅ 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
+ *
+ * ## 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
+ *
+ * ```ts
+ * // ── Server side ──────────────────────────────────────────────────────────
+ * const serverIdentity = await SPDTransport.generateServerIdentity();
+ * // Optional: add ML-DSA-65 signing
+ * const signingPair    = SPDTransport.generateCertKeyPair();
+ * serverIdentity.signingPrivKey = signingPair.privateKey;
+ * serverIdentity.signingPubKey  = signingPair.publicKey;
+ *
+ * const { session, serverHello } = await SPDTransport.serverAccept(serverIdentity, clientHello);
+ * session.decrypt(encryptedFrame);
+ * session.encrypt(responseBytes);
+ *
+ * // ── Client side ──────────────────────────────────────────────────────────
+ * const { session, clientHello } = await SPDTransport.clientConnect(serverPublicKey, {
+ *   pinnedSigningKey: serverSigningPubKey,  // optional cert pin
+ *   psk:             sharedSecret32,        // optional PSK
+ * });
+ * send(clientHello);
+ * const serverHello = receive(); // get serverHello from server
+ * await session.processServerHello(serverHello);
+ * session.encrypt(payload);
+ *
+ * // ── PSK session resumption ────────────────────────────────────────────────
+ * const psk = session.exportPSK();   // save after first handshake
+ * // next connection:
+ * const { session: session2, clientHello: ch2 } = await SPDTransport.clientConnect(
+ *   serverPublicKey, { psk }
+ * );
+ * ```
+ */
+
+interface SPDServerIdentity {
+    /** Curve25519 public key — distribute to clients out-of-band. */
+    publicKey: Uint8Array;
+    /** Curve25519 private key — keep secret, never transmit. */
+    privateKey: Uint8Array;
+    /** Optional ML-DSA-65 signing private key for certificate authentication. */
+    signingPrivKey?: Uint8Array;
+    /** Optional ML-DSA-65 signing public key — pin this on the client side. */
+    signingPubKey?: Uint8Array;
+}
+/** Options for `clientConnect`. */
+interface SPDClientConnectOptions {
+    /**
+     * Use V2 protocol (ML-KEM hybrid).  Default: true when server supports it.
+     * Set to false to force V1 (legacy interop).
+     */
+    v2?: boolean;
+    /**
+     * Pinned ML-DSA-65 public key.  When set, the client will verify the
+     * server's signature in the ServerHello and reject if verification fails.
+     */
+    pinnedSigningKey?: Uint8Array;
+    /**
+     * Pre-shared key (32 bytes) mixed into session key derivation.
+     * 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.
+ * Maintains independent monotonic counters for each direction.
+ */
+interface SPDSession {
+    /**
+     * Encrypt `plaintext` for transmission in this session's direction.
+     * 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
+     * outside the 64-entry sliding replay window.
+     */
+    decrypt(frame: Buffer): Buffer;
+    /**
+     * Serialize `spd` to its binary format in memory and encrypt the result as a
+     * single transport frame.  The SPD is NOT written to disk.
+     */
+    wrapSPD(spd: SPD, passcode: string): Promise<Buffer>;
+    /**
+     * Decrypt a frame produced by `wrapSPD` and load the embedded SPD binary.
+     * Returns a ready-to-use SPD instance.
+     */
+    unwrapSPD(frame: Buffer, passcode: string): Promise<SPD>;
+    /**
+     * Export a 32-byte PSK derived from the session key material.
+     * Store this to enable fast PSK resumption on the next connection.
+     */
+    exportPSK(): Uint8Array;
+    /** Zero all session key material.  Call when the session is complete. */
+    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).
+     * Distribute `publicKey` to clients out-of-band.
+     */
+    static generateServerIdentity(): Promise<SPDServerIdentity>;
+    /**
+     * Generate an ML-DSA-65 certificate key pair for server signing.
+     * Set `signingPrivKey` + `signingPubKey` on the server identity, and
+     * distribute `publicKey` to clients as a pinned cert.
+     */
+    static generateCertKeyPair(): {
+        privateKey: Uint8Array;
+        publicKey: Uint8Array;
+    };
+    /**
+     * Save a server identity to files:
+     *   `<path>.pub`  (Curve25519 public key, safe to distribute)
+     *   `<path>.key`  (Curve25519 private key, mode 0600)
+     *   `<path>.cert` (ML-DSA-65 public key, safe to distribute; optional)
+     *   `<path>.csig` (ML-DSA-65 private key, mode 0600; optional)
+     */
+    static saveServerIdentity(basePath: string, identity: SPDServerIdentity): void;
+    /**
+     * Load a server identity previously saved with `saveServerIdentity`.
+     */
+    static loadServerIdentity(basePath: string): SPDServerIdentity;
+    /**
+     * Initiate a new V2 session as the client (ML-KEM-768 hybrid + optional PSK + cert pinning).
+     *
+     * Returns `{ session, clientHello }`.  After receiving the ServerHello, call
+     * `await session.processServerHello(serverHello)` to complete the handshake.
+     *
+     * @param serverPublicKey  The server's Curve25519 long-term public key.
+     * @param options          Optional: pinnedSigningKey, psk, v2 flag.
+     */
+    static clientConnect(serverPublicKey: Uint8Array, options?: SPDClientConnectOptions): Promise<{
+        session: SPDClientHandshake;
+        clientHello: Buffer;
+    }>;
+    /** V1 legacy clientConnect */
+    private static _clientConnectV1;
+    /**
+     * Accept an incoming client connection (supports both V1 and V2 ClientHello).
+     *
+     * For V2: returns `{ session, serverHello }`.  Send `serverHello` to the client
+     * so it can finalize key derivation.
+     *
+     * @param serverIdentity  The server's long-term key pair.
+     * @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, padding?: boolean): Promise<{
+        session: SPDSession;
+        serverHello?: Buffer;
+    }>;
+    /** V1 legacy serverAccept */
+    private static _serverAcceptV1;
+    /** V2 serverAccept: hybrid ECDH + ML-KEM, optional ML-DSA-65 signing */
+    private static _serverAcceptV2;
+    /**
+     * Convenience: generate a random 32-byte session token suitable for use as
+     * an application-level session ID (e.g. HTTP cookie, WebSocket session key).
+     */
+    static generateSessionToken(): string;
+    /**
+     * Verify that a ClientHello buffer has the correct structure and version
+     * without performing the full key exchange.
+     */
+    static validateClientHello(clientHello: Buffer): boolean;
+}
+/**
+ * Intermediate object returned by `clientConnect` (V2).
+ * Call `processServerHello(serverHello)` to finalize key derivation.
+ * After that, use `encrypt` / `decrypt` normally.
+ */
+interface SPDClientHandshake extends SPDSession {
+    /**
+     * Process the ServerHello received from the server and finalize session keys.
+     * Must be called before `encrypt` or `decrypt`.
+     * @param serverHello  Raw bytes received from `serverAccept`.
+     */
+    processServerHello(serverHello: Buffer): void;
+}
+
+/**
+ * SPDShamir — Shamir's Secret Sharing over GF(256).
+ *
+ * Splits a byte-array secret into `n` shares, any `k` of which can
+ * reconstruct the original (k-of-n threshold scheme).
+ *
+ * ## Security properties
+ *  - Information-theoretically secure: fewer than `k` shares reveal
+ *    nothing about the secret.
+ *  - Each share is the same length as the secret + 1 byte (x-coordinate).
+ *  - Arithmetic is done in GF(2^8) with the irreducible polynomial
+ *    x^8 + x^4 + x^3 + x + 1 (0x11b — same as AES).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { SPDShamir } from 'spd-lib-ts';
+ *
+ * const secret = Buffer.from('my 32-byte secret key material!');
+ * const shares = SPDShamir.split(secret, 5, 3);   // 5 shares, 3 required
+ * const rebuilt = SPDShamir.combine(shares.slice(1, 4)); // any 3
+ * // rebuilt.equals(secret) === true
+ * ```
+ *
+ * ## Wire format
+ *
+ * Each `SPDShamirShare` is a `Uint8Array` where:
+ *   - `share[0]` = x-coordinate (1..255, never 0)
+ *   - `share[1..]` = f(x) evaluated for each byte of the secret
+ *
+ * Shares may be base64-encoded for storage / transmission.
+ */
+type SPDShamirShare = Uint8Array;
+declare class SPDShamir {
+    /**
+     * Split `secret` into `n` shares with threshold `k`.
+     * Any `k` shares can reconstruct the secret; fewer than `k` reveal nothing.
+     *
+     * @param secret  The byte-array to protect (any length > 0).
+     * @param n       Total number of shares to generate (2 ≤ n ≤ 255).
+     * @param k       Reconstruction threshold (2 ≤ k ≤ n).
+     * @returns       Array of `n` shares, each with `x` in `[0]` and `f(x)` in `[1..]`.
+     */
+    static split(secret: Uint8Array | Buffer, n: number, k: number): SPDShamirShare[];
+    /**
+     * Combine `k` (or more) shares to reconstruct the original secret.
+     *
+     * @param shares  Array of at least `k` shares.  Order does not matter.
+     * @returns       The reconstructed secret as a `Uint8Array`.
+     */
+    static combine(shares: SPDShamirShare[]): Uint8Array;
+    /**
+     * Encode a share to a base64url string for safe storage/transmission.
+     */
+    static encodeShare(share: SPDShamirShare): string;
+    /**
+     * Decode a base64url-encoded share back to `Uint8Array`.
+     */
+    static decodeShare(encoded: string): SPDShamirShare;
 }
 
-export { ARGON2_MEMORY_HIGH, ARGON2_TIME_HIGH, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDChunkManifest, type SPDGetEntryResult, type SPDIndexEntry, SPDLegacy, type SPDLegacyPayload, type SPDPayload, SPDVault, 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, 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 };