🔐 SecureStorage

A lightweight, TypeScript-compatible utility for securely storing data in localStorage or sessionStorage using AES encryption and HMAC-based tamper detection.

✨ Features

• AES encryption using crypto-js
• HMAC-SHA256 signature for tamper detection
• Works with both localStorage and sessionStorage
• Optional session-specific secret support
• Fully typed for TypeScript

📦 Installation

npm install secure-storage-lite

🚀 Usage

Import the package

import SecureStorage from "secure-storage-lite";

Basic Usage with a Fixed Secret

const secure = new SecureStorage(localStorage, {
  secret: "my-fixed-secret-key",
});

secure.setItem("user", { id: 1, name: "Vikas" });
const user = secure.getItem("user");
console.log(user); // ➜ { id: 1, name: "Vikas" }

Session-Specific Secret

const secure = new SecureStorage(sessionStorage, {
  useSessionSecret: true,
});

secure.setItem("tempData", { value: 123 });
const data = secure.getItem("tempData");
console.log(data); // ➜ { value: 123 }

⚙️ API

new SecureStorage(storage, options)

| Parameter | Type | Default | Description | |-----------|-------------------|------------------|-----------------------------------------| | storage | Storage | localStorage | Either localStorage or sessionStorage | | options.secret | string | "default_secret" | Secret key used for encryption/decryption | | options.useSessionSecret | boolean | false | If true, generates a new secret per session |

Methods

setItem(key: string, value: any): void

Encrypts and securely stores the item.

getItem<T = any>(key: string): T | null

Retrieves the item, checks for tampering, and parses JSON.

removeItem(key: string): void

Removes the encrypted item.

clear(): void

Clears the entire storage.

🧪 Tamper Detection

Each item is stored with a secure HMAC signature. If any value is modified in DevTools or externally, getItem() will detect it and return null.

🧠 TypeScript Support

Fully typed, with generic support:

const user = secure.getItem<{ id: number; name: string }>("user");

🌐 Browser Compatibility

Compatible with all modern browsers that support Web Storage and JavaScript ES6+.

📄 License

MIT