spd-lib 1.3.3 → 1.3.5

package/README.md

@@ -219,17 +219,20 @@ const spd = await SPD.loadFromString(b64, 'MyStr0ng!Passphrase#2024');
 Split a payload into chunks for HTTP uploads or any transport with a body-size limit.
 
 ```ts
-// Sender
-const chunks = await spd.saveDataChunked('MyStr0ng!Passphrase#2024', 512 * 1024); // 512 KB chunks
+// Sender — chunk size is chosen automatically
+const chunks = await spd.saveDataChunked('MyStr0ng!Passphrase#2024');
 // chunks is string[] — send each element, then the manifest (last element) last
 
+// Override chunk size when you have a strict body limit (e.g. 256 KB per request)
+const chunks = await spd.saveDataChunked('MyStr0ng!Passphrase#2024', 256 * 1024);
+
 // Receiver — pass all chunks in order including the manifest
 const spd = await SPD.loadFromChunks(chunks, 'MyStr0ng!Passphrase#2024');
 ```
 
 The last element of the array is always a JSON manifest (`{ totalChunks, chunkSize, totalBytes, version }`). The receiver validates chunk count and byte count before decrypting.
 
-Default chunk size is **1 MB**. Tune down for strict API body limits.
+**Auto chunk size** (when `chunkSize` is omitted): targets ~32 chunks, clamped between 64 KB and 8 MB, rounded to the nearest 64 KB boundary. Pass an explicit `chunkSize` to override (e.g. `256 * 1024` for strict API body limits).
 
 ---
 

package/index.d.mts

@@ -25,6 +25,8 @@ interface SPDPayload {
     hashAlgorithm?: string;
     argon2Memory?: number;
     argon2Time?: number;
+    argon2HashLen?: number;
+    hashKeyLen?: number;
 }
 interface SPDLegacyPayload {
     data: SerializedDataEntry[];
@@ -65,9 +67,26 @@ interface SPDChunkManifest {
     totalBytes: number;
     version: number;
 }
+interface SPDIndexEntry {
+    name: string;
+    decompressedOffset: bigint;
+}
+interface SPDWriterOptions {
+    compressionLevel?: number;
+    hashAlgorithm?: HashAlgorithm;
+    argon2Memory?: number;
+    argon2Time?: number;
+}
+interface SPDGetEntryResult {
+    value: unknown;
+    dataType: SupportedDataType;
+    name: string;
+}
 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 class SPD {
     private data;
     private keyPair?;
@@ -80,11 +99,14 @@ declare class SPD {
     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)
+     * Derives a master secret via Argon2id and splits it into:
+     *   aeadKey (32 B)     — XChaCha20-Poly1305 encryption key
+     *   macKey  (32/64 B)  — HMAC-SHA3-512 authentication key (domain-separated)
+     *
+     * 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): Promise<{
+    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number): Promise<{
         aeadKey: Uint8Array;
         macKey: Uint8Array;
     }>;
@@ -127,13 +149,38 @@ declare class SPD {
     /**
      * 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.
      */
     saveToFileStreaming(outputPath: string, passcode: string): 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]
+     */
+    private static writeIndexFile;
+    /**
+     * Reads and validates a `.spdi` index sidecar.
+     * Returns null if the file doesn't exist or the HMAC fails (falls back to scan).
+     */
+    private static readIndexFile;
     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)`.
+     *
+     * If `chunkSize` is omitted (or 0), a size is computed automatically:
+     *   - Targets ~32 chunks so the manifest stays small
+     *   - Clamped between 64 KB (min) and 8 MB (max)
+     *   - 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>;
@@ -165,9 +212,24 @@ declare class SPD {
      * });
      */
     static extractFromFileStreaming(filePath: string, passcode: string, tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | 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
+     * whole file into RAM.
+     *
+     * Uses a `.spdi` index sidecar (written alongside by `saveToFileStreaming`)
+     * for fast offset lookup when present. Falls back to a sequential scan if
+     * the sidecar is missing or its HMAC fails.
+     *
+     * The full plaintext MAC is always verified before any entry is decrypted —
+     * unauthenticated reads are never returned.
+     *
+     * RAM usage is bounded to ~one entry's worth of bytes at any time.
+     */
+    static getEntry(filePath: string, passcode: string, name: string): Promise<SPDGetEntryResult>;
     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 derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: 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;
@@ -260,4 +322,59 @@ declare class SPDVault {
     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 };
+/**
+ * SPDWriter — streaming, disk-backed binary SPD writer.
+ *
+ * Writes entries one at a time to disk as they are encrypted, so the full
+ * plaintext never exists in RAM simultaneously. Works on any device regardless
+ * of available memory.
+ *
+ * Usage:
+ *   const writer = new SPDWriter('./output.spd', 'MyStr0ng!Passphrase#2024');
+ *   await writer.init();
+ *   await writer.addEntry('username', 'alice');
+ *   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.
+ */
+
+declare class SPDWriter {
+    private outputPath;
+    private passcode;
+    private opts;
+    private aeadKey?;
+    private macKey?;
+    private salt?;
+    private deflate?;
+    private outStream?;
+    private hmac?;
+    private plaintextOffset;
+    private entryCount;
+    private indexEntries;
+    private finalized;
+    private initialized;
+    constructor(outputPath: string, passcode: string, opts?: SPDWriterOptions);
+    /**
+     * Derives keys, opens the output file, and writes the meta block.
+     * Must be called before addEntry().
+     */
+    init(): Promise<void>;
+    /**
+     * Encrypts one entry and streams it to disk.
+     */
+    addEntry(name: string, value: unknown): Promise<void>;
+    /**
+     * Flushes the deflate stream, computes the HMAC, patches the file header,
+     * and writes the `.spdi` index sidecar.
+     */
+    finalize(): Promise<void>;
+    /** Zero keys and remove the partial output file if finalize() was never called. */
+    destroy(): void;
+    /** Write bytes to the deflate stream and update the rolling HMAC + offset. */
+    private writeToPlaintext;
+    private writeIndexSidecar;
+}
+
+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 };

package/index.d.ts

@@ -25,6 +25,8 @@ interface SPDPayload {
     hashAlgorithm?: string;
     argon2Memory?: number;
     argon2Time?: number;
+    argon2HashLen?: number;
+    hashKeyLen?: number;
 }
 interface SPDLegacyPayload {
     data: SerializedDataEntry[];
@@ -65,9 +67,26 @@ interface SPDChunkManifest {
     totalBytes: number;
     version: number;
 }
+interface SPDIndexEntry {
+    name: string;
+    decompressedOffset: bigint;
+}
+interface SPDWriterOptions {
+    compressionLevel?: number;
+    hashAlgorithm?: HashAlgorithm;
+    argon2Memory?: number;
+    argon2Time?: number;
+}
+interface SPDGetEntryResult {
+    value: unknown;
+    dataType: SupportedDataType;
+    name: string;
+}
 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 class SPD {
     private data;
     private keyPair?;
@@ -80,11 +99,14 @@ declare class SPD {
     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)
+     * Derives a master secret via Argon2id and splits it into:
+     *   aeadKey (32 B)     — XChaCha20-Poly1305 encryption key
+     *   macKey  (32/64 B)  — HMAC-SHA3-512 authentication key (domain-separated)
+     *
+     * 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): Promise<{
+    static deriveKeys(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: number, macKeyLen?: number): Promise<{
         aeadKey: Uint8Array;
         macKey: Uint8Array;
     }>;
@@ -127,13 +149,38 @@ declare class SPD {
     /**
      * 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.
      */
     saveToFileStreaming(outputPath: string, passcode: string): 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]
+     */
+    private static writeIndexFile;
+    /**
+     * Reads and validates a `.spdi` index sidecar.
+     * Returns null if the file doesn't exist or the HMAC fails (falls back to scan).
+     */
+    private static readIndexFile;
     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)`.
+     *
+     * If `chunkSize` is omitted (or 0), a size is computed automatically:
+     *   - Targets ~32 chunks so the manifest stays small
+     *   - Clamped between 64 KB (min) and 8 MB (max)
+     *   - 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>;
@@ -165,9 +212,24 @@ declare class SPD {
      * });
      */
     static extractFromFileStreaming(filePath: string, passcode: string, tmpDir: string, callback: (name: string, value: unknown) => Promise<void> | 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
+     * whole file into RAM.
+     *
+     * Uses a `.spdi` index sidecar (written alongside by `saveToFileStreaming`)
+     * for fast offset lookup when present. Falls back to a sequential scan if
+     * the sidecar is missing or its HMAC fails.
+     *
+     * The full plaintext MAC is always verified before any entry is decrypted —
+     * unauthenticated reads are never returned.
+     *
+     * RAM usage is bounded to ~one entry's worth of bytes at any time.
+     */
+    static getEntry(filePath: string, passcode: string, name: string): Promise<SPDGetEntryResult>;
     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 derivePBK(passcode: string, salt: Uint8Array, memory?: number, time?: number, hashLen?: 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;
@@ -260,4 +322,59 @@ declare class SPDVault {
     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 };
+/**
+ * SPDWriter — streaming, disk-backed binary SPD writer.
+ *
+ * Writes entries one at a time to disk as they are encrypted, so the full
+ * plaintext never exists in RAM simultaneously. Works on any device regardless
+ * of available memory.
+ *
+ * Usage:
+ *   const writer = new SPDWriter('./output.spd', 'MyStr0ng!Passphrase#2024');
+ *   await writer.init();
+ *   await writer.addEntry('username', 'alice');
+ *   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.
+ */
+
+declare class SPDWriter {
+    private outputPath;
+    private passcode;
+    private opts;
+    private aeadKey?;
+    private macKey?;
+    private salt?;
+    private deflate?;
+    private outStream?;
+    private hmac?;
+    private plaintextOffset;
+    private entryCount;
+    private indexEntries;
+    private finalized;
+    private initialized;
+    constructor(outputPath: string, passcode: string, opts?: SPDWriterOptions);
+    /**
+     * Derives keys, opens the output file, and writes the meta block.
+     * Must be called before addEntry().
+     */
+    init(): Promise<void>;
+    /**
+     * Encrypts one entry and streams it to disk.
+     */
+    addEntry(name: string, value: unknown): Promise<void>;
+    /**
+     * Flushes the deflate stream, computes the HMAC, patches the file header,
+     * and writes the `.spdi` index sidecar.
+     */
+    finalize(): Promise<void>;
+    /** Zero keys and remove the partial output file if finalize() was never called. */
+    destroy(): void;
+    /** Write bytes to the deflate stream and update the rolling HMAC + offset. */
+    private writeToPlaintext;
+    private writeIndexSidecar;
+}
+
+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 };