spd-lib 1.2.9 → 1.3.1

package/index.d.mts

@@ -0,0 +1,213 @@
+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>>;
+    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>;
+    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 };

package/index.d.ts

@@ -0,0 +1,213 @@
+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>>;
+    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>;
+    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 };