@lookworld4/secure-browser-storage

localStorage / sessionStorage with transparent AES-256-GCM encryption via the Web Crypto API. Logical keys behave like normal storage keys; values are encrypted at rest.

Install

npm install @lookworld4/secure-browser-storage

Usage

Because encryption uses SubtleCrypto, getItem and setItem are asynchronous (Promise), unlike native Storage.

import {
  createSecureLocalStorage,
  createSecureSessionStorage,
} from "@lookworld4/secure-browser-storage";

const password = "... user passphrase or derived secret ...";

const local = await createSecureLocalStorage({ password });
await local.setItem("access_token", jwt);
const token = await local.getItem("access_token"); // string | null

const session = await createSecureSessionStorage({ password });
await session.setItem("cart", JSON.stringify(cart));

Options

| Option | Description | |--------|-------------| | password | Passphrase for PBKDF2 key derivation (default 250,000 iterations). Required unless you pass cryptoKey. | | cryptoKey | Your own 256-bit AES-GCM CryptoKey (skips PBKDF2 and salt metadata). | | namespace | Isolates salts and entries within the same Storage object (default "default"). | | pbkdf2Iterations | PBKDF2 iteration count (default 250_000). | | subtle | Inject SubtleCrypto (mainly for tests). |

Advanced: custom Storage

import { createSecureStorage } from "@lookworld4/secure-browser-storage";

const store = await createSecureStorage(myStorageImpl, { password: "..." });

Decryption errors

If the password is wrong or data was tampered with, getItem rejects with SecureStorageDecryptError.

Security notes

• Not a substitute for HTTP-only cookies for session tokens when you need strict XSS isolation. Anything in the page can still use this API once your app has derived the key.
• Does materially improve confidentiality of data at rest in the browser profile (disk, backups, casual inspection of Application storage) compared to plaintext JWTs or PII.
• Client-side encryption cannot hide secrets from malicious code running in the same origin; combine with CSP, sanitization, and short-lived tokens as appropriate.

Requirements

Browsers (or environments) with localStorage / sessionStorage and crypto.subtle where you need them. Secure contexts (HTTPS or localhost) are required for SubtleCrypto in browsers.

License

MIT