spd-lib 1.3.0 → 1.3.2

package/index.d.ts

@@ -0,0 +1,263 @@
+import sodium from 'libsodium-wrappers';
+
+type HashAlgorithm = 'sha3-512' | 'sha256' | 'sha512';
+type SupportedDataType = 'string' | 'number' | 'boolean' | 'object' | 'Array' | 'Uint8Array' | 'Uint16Array' | 'Uint32Array' | 'BigInt64Array' | 'BigUint64Array' | 'Float32Array' | 'Float64Array' | 'Map' | 'Set' | 'Date' | 'RegExp' | 'Error';
+interface EncryptedDataEntry {
+    dataName: string;
+    nonce: Buffer;
+    data: Buffer;
+    hash: string;
+    dataType: SupportedDataType;
+}
+interface SerializedDataEntry {
+    dataName: string;
+    nonce: number[];
+    data: number[];
+    hash: string;
+    dataType: SupportedDataType;
+}
+interface SPDPayload {
+    data: SerializedDataEntry[];
+    encryptedSalt: number[];
+    saltNonce: number[];
+    wrapSalt: number[];
+    version: number;
+    hashAlgorithm?: string;
+    argon2Memory?: number;
+    argon2Time?: number;
+}
+interface SPDLegacyPayload {
+    data: SerializedDataEntry[];
+    salt: number[];
+}
+interface WrappedPayload {
+    payload: Buffer;
+    mac: Buffer;
+}
+interface SerializedWrappedPayload {
+    payload: number[];
+    mac: number[];
+}
+interface PQCKey {
+    privateKey: Uint8Array;
+    publicKey?: Uint8Array;
+}
+interface PQCKeyResult {
+    pqcKey: PQCKey;
+    salt: Uint8Array;
+}
+interface PBKResult {
+    pbk: Buffer;
+    salt: Uint8Array;
+}
+interface EncryptedSaltResult {
+    encryptedSalt: number[];
+    saltNonce: number[];
+    wrapSalt: number[];
+}
+interface DataInput {
+    name: string;
+    data: unknown;
+}
+interface SPDChunkManifest {
+    totalChunks: number;
+    chunkSize: number;
+    totalBytes: number;
+    version: 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 class SPD {
+    private data;
+    private keyPair?;
+    private userKey?;
+    private macKey?;
+    private salt?;
+    private hash;
+    private compressionLevel;
+    private assertReady;
+    init(): Promise<void>;
+    changePasscode(oldPasscode: string, newPasscode: string): Promise<void>;
+    /**
+     * Derives a 512-bit master secret via Argon2id and splits it into:
+     *   aeadKey (32 B) — XChaCha20-Poly1305 encryption key (256-bit, 128-bit PQ)
+     *   macKey  (32 B) — HMAC-SHA3-512 authentication key (domain-separated)
+     */
+    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number): Promise<{
+        aeadKey: Uint8Array;
+        macKey: Uint8Array;
+    }>;
+    private static computeMAC;
+    checkPasscodeStrength(passcode: string): boolean;
+    setPassKey(passcode: string): Promise<void>;
+    setHash(hash?: HashAlgorithm): void;
+    setCompressionLevel(level?: number): void;
+    getSodium(): typeof sodium;
+    sanitizeName(dataName: string): string;
+    addData(dataName: string, value: unknown): Promise<void>;
+    addMany(items: DataInput[]): Promise<void>;
+    extractData(): Promise<Record<string, unknown>>;
+    /**
+     * Memory-efficient streaming extraction.
+     *
+     * For each encrypted entry, this method:
+     *   1. Decrypts and decompresses the entry into a temp file in `tmpDir`
+     *      (named `<entryName>.ssf`, mode 0600)
+     *   2. Reads the .ssf file and calls your `callback` with the name + value
+     *   3. Immediately deletes the .ssf file before moving to the next entry
+     *
+     * At most one entry's decrypted bytes exist on disk or in RAM at a time,
+     * so this works for arbitrarily large SPD files as long as a single entry
+     * fits in memory (which is always the case — entries are discrete values).
+     *
+     * @param tmpDir   Directory to write temp files into (must exist, mode 0700 recommended)
+     * @param callback Called once per entry in order. Await is respected — the next
+     *                 entry won't be processed until your callback resolves.
+     *
+     * @example
+     * await spd.extractDataStreaming('/tmp/spd_scratch', async (name, value) => {
+     *   console.log(name, value);
+     * });
+     */
+    extractDataStreaming(tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | void): Promise<void>;
+    destroy(): void;
+    clearCache(): void;
+    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)]
+     */
+    saveToFileStreaming(outputPath: string, passcode: string): Promise<void>;
+    saveData(passcode?: string): Promise<string>;
+    /**
+     * Splits the payload into base64 chunks for chunked internet transfer.
+     * The manifest (last element) records totalChunks/totalBytes for validation.
+     * Reassemble with `SPD.loadFromChunks(chunks, passcode)`.
+     */
+    saveDataChunked(passcode: string, chunkSize?: number): Promise<string[]>;
+    static loadFromFile(filePath: string, passcode: string): Promise<SPD>;
+    static loadFromFileStreaming(filePath: string, passcode: string): Promise<SPD>;
+    /**
+     * True constant-memory streaming extract from a binary SPD file.
+     *
+     * Unlike `loadFromFileStreaming` (which buffers the entire plaintext into RAM),
+     * this method pipes the inflate stream through a byte-by-byte parser that:
+     *   1. Reads and verifies the file header + MAC
+     *   2. Parses the metadata block to derive keys
+     *   3. Processes one entry at a time:
+     *      a. Writes the encrypted entry to `<name>_enc.ssf` in `tmpDir` (mode 0600)
+     *      b. Decrypts it, writes the plaintext to `<name>_dec.ssf`
+     *      c. Reads the `.ssf` file and calls your `callback`
+     *      d. Deletes both `.ssf` files before touching the next entry
+     *
+     * Peak RAM usage is proportional to the largest single entry, not the file size.
+     * Files of any size are supported as long as individual entries fit in memory.
+     *
+     * @param filePath Path to the `.spd` file written by `saveToFileStreaming`
+     * @param passcode Passcode used when the file was saved
+     * @param tmpDir   Scratch directory for temp files (must exist, mode 0700 recommended)
+     * @param callback Called once per entry in order. Next entry waits for this to resolve.
+     *
+     * @example
+     * await SPD.extractFromFileStreaming('./huge.spd', 'MyPass!', '/tmp/spd', async (name, value) => {
+     *   console.log(name, typeof value);
+     * });
+     */
+    static extractFromFileStreaming(filePath: string, passcode: string, tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | void): Promise<void>;
+    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): 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 toBase64(data: Uint8Array | Buffer): string;
+    static fromBase64(data: string): Uint8Array;
+    private buildSerializedPayload;
+    private static parseSerializedPayload;
+    private buildBinaryPayload;
+    private static parseBinaryPayload;
+    private detectType;
+    private isTypedArray;
+    private isCollectionType;
+    private convertInputToString;
+    private convertStringToInput;
+}
+
+/**
+ * Legacy SPD class for backwards compatibility.
+ * Uses older cryptographic methods (crypto_secretbox instead of AEAD).
+ */
+declare class SPDLegacy {
+    private data;
+    private keyPair?;
+    private userKey?;
+    private salt?;
+    constructor();
+    init(): Promise<void>;
+    setPassKey(passcode: string): Promise<void>;
+    addData(dataName: string, value: unknown): Promise<void>;
+    saveToFile(outputPath: string): void;
+    static loadFromFile(filePath: string, passcode: string): Promise<SPDLegacy>;
+    extractData(): Promise<Record<string, unknown>>;
+    static derivePBK(passcode: string, salt: Uint8Array): Promise<PBKResult>;
+    saveData(): Buffer;
+    static loadFromString(data: string, passcode: string): Promise<SPDLegacy>;
+    private convertPasscodeToPQCKeySalted;
+    convertPasscodeToPQCKey(passcode: string): Promise<PQCKeyResult>;
+    private detectType;
+    private isTypedArray;
+    private isCollectionType;
+    private isSpecialType;
+    private convertInputToString;
+    private convertStringToInput;
+}
+
+/**
+ * In-memory key vault with automatic expiration.
+ * Keys are automatically deleted after the specified timeout.
+ */
+declare class SPDVault {
+    private keys;
+    private timers;
+    private timeoutMs;
+    constructor(timeoutMs?: number);
+    /**
+     * Generate a random key string.
+     */
+    private generateRandomKey;
+    /**
+     * Reset the expiration timer for a key.
+     */
+    private resetTimer;
+    /**
+     * Generate and store a new random key.
+     */
+    genKey(keyId?: string): void;
+    /**
+     * Store a custom key.
+     */
+    pushKey(keyId?: string, key?: string): void;
+    /**
+     * Retrieve a key by ID.
+     * Returns undefined if the key doesn't exist.
+     */
+    pullKey(keyId?: string): string | undefined;
+    /**
+     * Delete a key by ID.
+     */
+    destroyKey(keyId?: string): void;
+    /**
+     * Update a key if the old value matches.
+     */
+    updateKey(keyId: string, oldValue?: string, newValue?: string): void;
+    /**
+     * Stop all expiration timers.
+     */
+    stop(): void;
+    /**
+     * Clear all keys and timers.
+     */
+    destroy(): void;
+}
+
+export { type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDChunkManifest, SPDLegacy, type SPDLegacyPayload, type SPDPayload, SPDVault, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };