Merge pull request #1 from mqxym/docs-add-jsdoc

Docs add jsdoc: 0.6.1

Author: mqxym

dist/cjs/sls.browser.min.cjs

@@ -1,11 +1,67 @@
 import { SecureDataView } from "../utils/secureDataView";
 import type { IdbConfig } from "../crypto/DeviceKeyProvider";
+/**
+ * Configuration options for initializing SecureLocalStorage.
+ */
 export interface SecureLocalStorageOptions {
-    /** Override the localStorage key (for multi-tenant apps or tests). */
+    /**
+     * Overrides the default key used for storing encrypted data in `localStorage`.
+     * This is useful for multi-tenant applications or for isolating data in tests.
+     * @default "secure-local-storage"
+     */
     storageKey?: string;
-    /** Override IndexedDB configuration (for multi-tenant apps or tests). */
+    /**
+     * Overrides the default IndexedDB configuration for storing the device-specific key.
+     * This is useful for multi-tenant applications or for isolating data in tests.
+     */
     idbConfig?: Partial<IdbConfig>;
 }
+/**
+ * Provides a secure, client-side storage solution that encrypts data before persisting it.
+ *
+ * `SecureLocalStorage` offers two primary modes of operation:
+ * 1.  **Device-bound Mode**: (Default) Data is encrypted with a key that is stored in
+ *     the browser's IndexedDB. This key is unique to the device and profile, making it
+ *     difficult to access from other devices. Data is automatically unlocked when the
+ *     class is instantiated.
+ * 2.  **Master Password Mode**: Data is encrypted with a key derived from a user-provided
+ *     master password. The data can only be accessed by providing the correct password,
+ *     allowing for portability across devices but requiring user interaction to unlock.
+ *
+ * The class handles key management, encryption, and data serialization, providing a
+ * simple `getData`/`setData` interface for application use. It also supports features
+ * like key rotation, data export/import, and changing or removing the master password.
+ *
+ * @example
+ * ```typescript
+ * // Initialize in device-bound mode
+ * const sls = new SecureLocalStorage();
+ *
+ * // Set some data
+ * await sls.setData({ mySecret: "hello world" });
+ *
+ * // Get the data back
+ * const dataView = await sls.getData();
+ * console.log(dataView.value.mySecret); // "hello world"
+ *
+ * // Wipe the plaintext from memory
+ * dataView.wipe();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize and set a master password
+ * const sls = new SecureLocalStorage();
+ * await sls.setMasterPassword("my-strong-password-123");
+ *
+ * // Later, in a new session
+ * const sls2 = new SecureLocalStorage();
+ * await sls2.unlock("my-strong-password-123");
+ * const data = await sls2.getData();
+ * // ... use data
+ * sls2.lock(); // clear session keys
+ * ```
+ */
 export declare class SecureLocalStorage {
     private readonly store;
     private readonly enc;
@@ -14,39 +70,134 @@ export declare class SecureLocalStorage {
     private dek;
     private ready;
     private readonly idbConfig;
+    /**
+     * The current version of the data structure format.
+     */
     readonly DATA_VERSION: number;
+    /**
+     * Initializes a new instance of SecureLocalStorage.
+     *
+     * The constructor immediately begins an asynchronous initialization process.
+     * Public methods will await this process, so you don't need to manually wait
+     * for it to complete.
+     *
+     * @param opts - Optional configuration to customize storage keys.
+     */
     constructor(opts?: SecureLocalStorageOptions);
+    /**
+     * Checks if the storage is currently protected by a master password.
+     * @returns `true` if a master password is set, `false` otherwise.
+     */
     isUsingMasterPassword(): boolean;
-    /** Unlock session with master password (no-op in device mode / no data available ). */
+    /**
+     * Unlocks the data encryption key (DEK) using the provided master password.
+     * This is required to access data when in master password mode.
+     * If the store is in device-bound mode or is already unlocked, this method does nothing.
+     *
+     * @param masterPassword - The user's master password.
+     * @throws {ValidationError} If the master password is an empty string or invalid.
+     */
     unlock(masterPassword: string): Promise<void>;
-    /** Set a master password (switch from device mode to master mode). */
+    /**
+     * Sets a master password, switching from device-bound mode to master password mode.
+     * This re-encrypts the data encryption key (DEK) with a new key derived from the password.
+     *
+     * @param masterPassword - The new master password to set. Must be a non-empty string.
+     * @throws {ModeError} If a master password is already set.
+     * @throws {ValidationError} If the master password is an empty string.
+     */
     setMasterPassword(masterPassword: string): Promise<void>;
-    /** Remove master password, re-wrapping DEK with device-bound KEK. Requires unlocked session. */
+    /**
+     * Removes the master password, switching back to device-bound mode.
+     * The DEK is re-encrypted using the device-specific key.
+     * Requires the session to be unlocked.
+     *
+     * @throws {ModeError} If no master password is set.
+     * @throws {LockedError} If the session is locked.
+     */
     removeMasterPassword(): Promise<void>;
-    /** Rotate master password atomically. */
+    /**
+     * Atomically changes the master password.
+     * If not in master password mode, it will set the new password.
+     *
+     * @param oldMasterPassword - The current master password.
+     * @param newMasterPassword - The new master password. Must be a non-empty string.
+     * @throws {ValidationError} If the new password is empty or if the old password is incorrect.
+     * @throws {LockedError} If the session is locked.
+     */
     rotateMasterPassword(oldMasterPassword: string, newMasterPassword: string): Promise<void>;
-    /** Lock the session (clears derived KEK & DEK from memory). */
+    /**
+     * Locks the session by clearing the cached Key Encryption Key (KEK) and
+     * Data Encryption Key (DEK) from memory.
+     * After locking, `unlock()` must be called to perform further operations.
+     */
     lock(): void;
-    /** Rotate DEK and device KEK. Allowed only in password-less mode. */
+    /**
+     * Rotates the Data Encryption Key (DEK) and the device-specific Key Encryption Key (KEK).
+     * This enhances security by replacing the keys used to protect the data.
+     * This operation is only allowed in device-bound mode.
+     *
+     * @throws {ModeError} If a master password is set.
+     */
     rotateKeys(): Promise<void>;
-    /** Get decrypted data as a wipeable view object. */
+    /**
+     * Retrieves the decrypted data.
+     *
+     * @returns A promise that resolves to a `SecureDataView`, a wrapper around the
+     *          decrypted data object that includes a `wipe()` method to securely
+     *          clear the plaintext data from memory.
+     * @throws {LockedError} If the session is locked.
+     * @throws {ValidationError} If the stored data is not a plain object.
+     * @template T The expected type of the stored data object.
+     */
     getData<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<SecureDataView<T>>;
-    /** Replace data with the provided plain object. */
+    /**
+     * Encrypts and persists the provided data object, replacing any existing data.
+     *
+     * @param value The plain JavaScript object to store. It must be serializable.
+     * @throws {LockedError} If the session is locked.
+     * @throws {ValidationError} If the provided value is not a plain object.
+     */
     setData<T extends Record<string, unknown>>(value: T): Promise<void>;
     /**
-     * Export the encrypted bundle as JSON string.
-     * - If `customExportPassword` provided: derive export KEK (Argon2id) and rewrap DEK accordingly (mPw=false).
-     * - If absent and in master mode: exports current config wrapped with master password (mPw=true).
+     * Exports the encrypted data bundle as a JSON string.
+     *
+     * There are two export modes:
+     * 1.  **Master Password Mode**: If no `customExportPassword` is provided and a master
+     *     password is set, the bundle is exported using the existing master password.
+     * 2.  **Custom Password Mode**: If a `customExportPassword` is provided, the bundle
+     *     is re-encrypted with a key derived from this password. This is required when
+     *     in device-bound mode.
+     *
+     * @param customExportPassword - An optional password to protect the exported data.
+     *        Required if not in master password mode.
+     * @returns A JSON string representing the encrypted data bundle.
+     * @throws {ExportError} If a password is required but not provided, or if the
+     *         provided password is invalid.
      */
     exportData(customExportPassword?: string): Promise<string>;
     /**
-     * Import previously exported JSON.
-     * - If bundle.mPw===true OR header.rounds>1 and no mPw flag: expects master password.
-     * - Else expects export password.
-     * After import, rewrap to device mode if using export password.
+     * Imports a previously exported data bundle.
+     *
+     * The method determines whether to use a master password or an export password
+     * based on the bundle's metadata. After a successful import using an export
+     * password, the data is re-encrypted into device-bound mode. If imported with a
+     * master password, it remains in master password mode.
+     *
+     * @param serialized - The JSON string of the exported data bundle.
+     * @param password - The password required to decrypt the bundle (master or export).
+     * @returns A promise that resolves to 'masterPassword' or 'customExportPassword'
+     *          indicating which type of password was used for the import.
+     * @throws {ImportError} If the JSON is invalid, the bundle is corrupted, the
+     *         password is required but missing, or the password is incorrect.
      */
     importData(serialized: string, password?: string): Promise<string>;
-    /** Clear all data (localStorage + IndexedDB KEK) and reinitialize fresh empty store in device mode. */
+    /**
+     * Clears all stored data, including the encrypted bundle from `localStorage` and
+     * the device key from `IndexedDB`.
+     * After clearing, the instance is reinitialized to a fresh, empty state in
+     * device-bound mode.
+     */
     clear(): Promise<void>;
     private initialize;
     private persist;

dist/cjs/sls.browser.min.js.map

@@ -2,11 +2,28 @@ import { SecureLocalStorage, type SecureLocalStorageOptions } from "./api/Secure
 export type { SecureLocalStorageOptions } from "./api/SecureLocalStorage";
 export { SecureLocalStorage } from "./api/SecureLocalStorage";
 /**
- * Factory per your API:
+ * Creates and initializes a new `SecureLocalStorage` instance.
  *
- * ```ts
- * const sls = secureLocalStorage(); // init
- * await sls.setData({ value1: 123 });
+ * This factory function is the recommended way to get started with the library.
+ * It provides a convenient shorthand for `new SecureLocalStorage(opts)`.
+ *
+ * @param {SecureLocalStorageOptions} [opts] - Optional configuration to customize storage keys and other behavior.
+ * @returns {SecureLocalStorage} A new instance of the `SecureLocalStorage` class.
+ * @example
+ * ```typescript
+ * import secureLocalStorage from 'secure-local-storage';
+ *
+ * // Initialize with default options
+ * const sls = secureLocalStorage();
+ *
+ * async function main() {
+ *   await sls.setData({ secret: 'This is a secret' });
+ *   const data = await sls.getData();
+ *   console.log(data.value.secret); // "This is a secret"
+ *   data.wipe();
+ * }
+ *
+ * main();
  * ```
  */
 export default function secureLocalStorage(opts?: SecureLocalStorageOptions): SecureLocalStorage;

dist/esm/sls.browser.min.js

@@ -1,6 +1,6 @@
 {
   "name": "@mqxym/secure-local-storage",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Secure arbitrary objects in localStorage using AES-GCM envelope encryption with device-bound KEK (IndexedDB) or Argon2id-derived KEK (master password).",
   "license": "MIT",
   "author": "mqxym",