![](\"./docs/resources/encrypt-storage-logo.png\"){kind=logo}
\n\n\n\n[](https://github.com/michelonsouza/encrypt-storage)  [](https://github.com/sponsors/michelonsouza) [](https://github.com/michelonsouza/encrypt-storage/blob/main/LICENSE)\n\n[](https://github.com/michelonsouza/encrypt-storage/blob/main/package.json#L3) [](https://www.npmjs.com/package/encrypt-storage) [](https://www.jsdelivr.com/package/npm/encrypt-storage)\n\n   [](https://github.com/michelonsouza/encrypt-storage)\n\n[](https://codecov.io/github/michelonsouza/encrypt-storage) [](https://badge.socket.dev/npm/package/encrypt-storage/3.0.0) [](https://github.com/michelonsouza/encrypt-storage/actions/workflows/code-quality-verify.yml) [](https://github.com/michelonsouza/encrypt-storage/actions/workflows/ci.yml) [](https://github.com/michelonsouza/encrypt-storage/actions/workflows/ci.yml)\n\n# Encrypt Storage\n\n`encrypt-storage` wraps the browser Storage API with transparent encryption. Store objects, strings, or any serializable value in `localStorage`, `sessionStorage`, or browser cookies while keeping the same familiar Storage-like API.\n\nChoose between a **fully synchronous** implementation powered by **@noble/ciphers** or the native **Web Crypto API**, select an AES algorithm, and keep your application compatible with modern browsers and frameworks.\n\n> [!NOTE]\n> ## ๐ Welcome to Encrypt Storage v3\n>\n> Version 3 is the most significant release in the project's history.\n>\n> This release is a complete overhaul of the library, focused on performance, security, and compatibility with today's JavaScript ecosystem.\n>\n> ### What's new?\n>\n> - โก Replaced **CryptoJS** with modern cryptography powered by **Web Crypto API** and **Noble Ciphers/Hashes**\n> - ๐ Improved compatibility with modern browser-based frameworks such as **Next.js, Astro, Vite, Nuxt**, and more\n> - โณ **New built-in TTL (Time-To-Live) API** featuring dedicated methods such as `setTTL`, `getTTL`, `hasTTL`, `refreshTTL`, `removeTTL`, and more for managing expiring data\n> - ๐ Stronger key derivation using **PBKDF2**\n> - ๐ Smaller bundle size and improved tree-shaking\n> - ๐ง Lazy initialization for better SSR compatibility\n> - ๐ฆ Modern ESM-first distribution with full TypeScript support\n> - ๐งช Rewritten test suite and improved code quality\n> - ๐ ๏ธ Modernized build pipeline, tooling, and CI\n>\n> While this is a major release internally, the public API remains familiar, making migration from v2 straightforward for most projects.\n>\n> Thank you to everyone who has supported Encrypt Storage over the years. โค๏ธ\n\n> [!IMPORTANT]\n> **Browser-side encryption is not a substitute for server-side security.**\n>\n> Secrets shipped to the client can always be extracted by a sufficiently motivated attacker. Encrypt Storage protects data **at rest** inside browser storage and helps prevent casual inspection, but it must not be considered a replacement for authentication, authorization, or server-side secret management.\n\n## Features\n\n- ๐ Encrypt values stored in `localStorage`, `sessionStorage`, and browser cookies.\n- โก Choose between synchronous (`@noble/ciphers`) and asynchronous (native Web Crypto API) encryption engines.\n- โณ Built-in TTL (Time-To-Live) support.\n- ๐งฉ Familiar Storage-like API with bulk operations, pattern matching, and utility methods.\n- ๐ฆ Automatic serialization/deserialization.\n- ๐ท๏ธ Prefix namespaces.\n- ๐๏ธ Compatible with Redux Persist, Vuex Persist, Pinia Persist and other Storage-based integrations.\n\n## Table of contents\n\n- [Encrypt Storage](#encrypt-storage)\n - [Features](#features)\n - [Table of contents](#table-of-contents)\n - [Built with](#built-with)\n - [Installation](#installation)\n - [Using a CDN](#using-a-cdn)\n - [unpkg](#unpkg)\n - [jsDelivr](#jsdelivr)\n - [Version and runtime support](#version-and-runtime-support)\n - [Migration to version 3](#migration-to-version-3)\n - [Choose an encryption engine](#choose-an-encryption-engine)\n - [Factory or direct class imports](#factory-or-direct-class-imports)\n - [Usage](#usage)\n - [Noble (synchronous)](#noble-synchronous)\n - [Web Crypto API (asynchronous)](#web-crypto-api-asynchronous)\n - [AsyncEncryptStorage (fully promise-based)](#asyncencryptstorage-fully-promise-based)\n - [Multiple instances](#multiple-instances)\n - [Server-side rendering](#server-side-rendering)\n - [Next.js Client Components](#nextjs-client-components)\n - [getStorage alternative](#getstorage-alternative)\n - [Options](#options)\n - [Validation](#validation)\n - [Storage methods](#storage-methods)\n - [Write and read values](#write-and-read-values)\n - [Bulk operations](#bulk-operations)\n - [Pattern operations](#pattern-operations)\n - [Storage utilities](#storage-utilities)\n - [Encrypt, decrypt, and hash](#encrypt-decrypt-and-hash)\n - [Cookies](#cookies)\n - [Noble cookies (synchronous)](#noble-cookies-synchronous)\n - [Web Crypto cookies (asynchronous)](#web-crypto-cookies-asynchronous)\n - [Cookie API reference](#cookie-api-reference)\n - [TTL (Time-To-Live)](#ttl-time-to-live)\n - [Store a value with TTL](#store-a-value-with-ttl)\n - [Read a TTL value](#read-a-ttl-value)\n - [Check TTL state](#check-ttl-state)\n - [TTL metadata and remaining time](#ttl-metadata-and-remaining-time)\n - [Refresh and remove TTL](#refresh-and-remove-ttl)\n - [TTL with Web Crypto (asynchronous)](#ttl-with-web-crypto-asynchronous)\n - [State management persisters](#state-management-persisters)\n - [Vuex Persist](#vuex-persist)\n - [Zustand Persist](#zustand-persist)\n - [Redux Persist](#redux-persist)\n - [Pinia persist plugins](#pinia-persist-plugins)\n - [Notifications](#notifications)\n - [Error handling](#error-handling)\n - [InvalidSecretKeyError](#invalidsecretkeyerror)\n - [IsNotBrowserEnvironmentError](#isnotbrowserenvironmenterror)\n - [NullValueError](#nullvalueerror)\n - [UndefinedValueError](#undefinedvalueerror)\n - [License](#license)\n - [Help project](#help-project)\n\n## Built with\n\n| Category | Technology |\n| --- | --- |\n| Language | [TypeScript](https://www.typescriptlang.org/) |\n| Encryption (sync) | [@noble/ciphers](https://github.com/paulmillr/noble-ciphers) โ AES-GCM, AES-CBC, AES-CTR |\n| Hashing | [@noble/hashes](https://github.com/paulmillr/noble-hashes) โ SHA-256, PBKDF2 |\n| Encryption (async) | [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) โ AES-GCM, AES-CBC, AES-CTR |\n| Bundler | [Vite+](https://viteplus.dev/) (Vite + Rolldown + tsdown) |\n| Test runner | [Vitest](https://vitest.dev/) |\n| Coverage | [v8](https://v8.dev/blog/javascript-code-coverage) via `@vitest/coverage-v8` |\n| Linter | [Oxlint](https://oxc.rs/) |\n| Formatter | [Oxfmt](https://oxc.rs/) |\n| Package manager | [pnpm](https://pnpm.io/) |\n| Git hooks | [Vite+ staged hooks](https://viteplus.dev/) + [commitlint](https://commitlint.js.org/) |\n| CI | [GitHub Actions](https://github.com/features/actions) |\n\n## Installation\n\n```bash\nnpm install encrypt-storage\n```\n\n```bash\nyarn add encrypt-storage\n```\n\n```bash\npnpm add encrypt-storage\n```\n\nThe package is intended for bundlers and supports ESM and CommonJS imports. A modern Node.js runtime such as `>=20` is recommended for local development and package tooling.\n\n### Using a CDN\n\nFor browser-only projects, load the ESM build from a CDN. Version 3 uses the factory API, so create an instance with `EncryptStorage.create()`.\n\n#### unpkg\n\n```html\n\n```\n\n#### jsDelivr\n\n```html\n\n```\n\nFor production, pin the package to a specific version instead of using `@latest`.\n\n## Version and runtime support\n\n| Encrypt Storage version | Status | Documentation |\n| --- | --- | --- |\n| `3.x` | Current API. Requires explicit engine{name ?? 'Anonymous'}
;\n}\n```\n\nImporting a Client Component from a Server Component is fine. The important rule is that any code creating or using a storage instance must stay inside a file marked with `'use client'`, or otherwise run only in the browser.\n\n#### getStorage alternative\n\nFor shared modules, the Pages Router, or situations where a client-only component is not appropriate, keep the `getStorage()` guard. It returns `null` during SSR and an instance in the browser.\n\n```ts\nimport { EncryptStorage } from 'encrypt-storage';\n\nexport const getStorage = () => {\n if (typeof window === 'undefined') return null;\n\n return EncryptStorage.create('secret-key-value', {\n engine: 'noble',\n prefix: '@app',\n });\n};\n```\n\nFor client-side framework variables, use the framework's public environment-variable convention. Do not expose a server-only secret in browser code.\n\n## Options\n\nPass an options object as the second argument to `EncryptStorage.create()`.\n\n| Property | Default | Applies to | Description |\n| --- | --- | --- | --- |\n| `engine` | โ | all | **Required.** `'noble'` or `'web-crypto'`. |\n| `prefix` | `''` | all | Prefix added to every storage key as `prefix:key`. |\n| `storageType` | `'localStorage'` | all | Browser storage target: `'localStorage'` or `'sessionStorage'`. |\n| `stateManagementUse` | `false` | all | Returns raw strings without automatic parsing; required by persisters. Use only with `noble` for persisters. |\n| `doNotEncryptValues` | `false` | all | Stores values without encryption. Prefixes and storage helpers still apply. |\n| `doNotParseValues` | `false` | all | Disables automatic `JSON.stringify`/`JSON.parse` conversion. |\n| `notifyHandler` | `undefined` | all | Callback invoked after supported storage operations. |\n| `validation` | `undefined` | all | Value validation rules applied on `setItem`. See [Validation](#validation). |\n| `encAlgorithm` | `'AES-GCM'` | all | Encryption algorithm. Applies to both engines. |\n\nSupported algorithms: `AES-GCM`, `AES-CBC`, and `AES-CTR`.\n\n`doNotParseValues` expects string-compatible values. With its default `false`, objects are serialized on write and parsed on read; scalar values are recovered when valid JSON.\n\n### Validation\n\nPass a `validation` object to enforce value constraints on every `setItem` call. When a validation rule is violated, an error is thrown synchronously, preventing the value from being written to storage.\n\n```ts\nconst encryptStorage = EncryptStorage.create('secret-key-value', {\n engine: 'noble',\n prefix: '@app',\n validation: {\n allowNull: false,\n allowUndefined: false,\n },\n});\n\n// Throws NullValueError\nencryptStorage.setItem('key', null);\n\n// Throws UndefinedValueError\nencryptStorage.setItem('key', undefined);\n```\n\n| Property | Default | Description |\n| --- | --- | --- |\n| `allowNull` | `true` | When `false`, storing `null` throws `NullValueError`. |\n| `allowUndefined` | `false` | When `false`, storing `undefined` throws `UndefinedValueError`. |\n| `strict` | `false` | When `true`, overrides both `allowNull` and `allowUndefined` to `false`. Neither `null` nor `undefined` can be stored. |\n\nThe `strict` option is a shorthand. It takes precedence over individual settings:\n\n```ts\nconst encryptStorage = EncryptStorage.create('secret-key-value', {\n engine: 'noble',\n validation: { strict: true },\n});\n\n// Both throw โ strict disallows null and undefined regardless of other settings\nencryptStorage.setItem('key', null); // NullValueError\nencryptStorage.setItem('key', undefined); // UndefinedValueError\n```\n\nBy default (no `validation` option), `null` is allowed and `undefined` is not. This matches standard JSON serialization behavior where `null` is a valid JSON value but `undefined` is not.\n\nValidation applies to `setItem` and, by extension, to any method that calls it internally (`setMultipleItems`, `setTTL`).\n\n## Storage methods\n\nThe examples below use a synchronous noble instance. Prefixes are added to physical browser-storage keys but are omitted from method parameters and returned pattern keys.\n\n| Method | Parameters | Return (`noble`) | Return (`web-crypto`) |\n| --- | --- | --- | --- |\n| `setItem` | `(key: string, value: any, doNotEncrypt?: boolean)` | `void` | `Promise