locked-storage

🔐 Locked Storage

A lightweight JavaScript library that provides cryptographically encrypted localStorage and sessionStorage with automatic key/value encryption.

Features

• 🔒 Full Encryption: Both keys and values are encrypted before storage
• 🌐 Universal: Works in browsers, Node.js, and all JavaScript environments
• ⚡ Simple API: Drop-in replacement for localStorage/sessionStorage
• 🛡️ Secure: Uses PBKDF2 key derivation and AES-GCM encryption
• 📦 Tiny: Minimal footprint with no external dependencies
• 🔄 Dual Storage: Supports both localStorage and sessionStorage

Installation

npm install locked-storage

Quick Start

import { createLockedLocalStorage } from 'locked-storage';

// Create an encrypted localStorage instance
const lockedStorage = createLockedLocalStorage('your-secret-master-key');

// Use it just like regular localStorage
lockedStorage.setItem('username', 'john_doe');
const username = lockedStorage.getItem('username'); // 'john_doe'

Usage Examples

Browser (ES6 Modules)

import { createLockedLocalStorage, createLockedSessionStorage } from 'locked-storage';

// localStorage with encryption
const secureLocal = createLockedLocalStorage('my-secret-key');
secureLocal.setItem('sensitive-data', 'confidential-value');

// sessionStorage with encryption  
const secureSession = createLockedSessionStorage('my-secret-key');
secureSession.setItem('session-token', 'abc-123-xyz');

Browser (Script Tag)

<!-- Include crypto-js first -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>
<script src="node_modules/locked-storage/index.js"></script>
<script>
  const lockedStorage = LockedStorage.createLockedLocalStorage('my-key');
  
  lockedStorage.setItem('data', 'value');
  const data = lockedStorage.getItem('data');
  console.log(data); // 'value'
</script>

Node.js (CommonJS)

const { createLockedLocalStorage } = require('locked-storage');

const storage = createLockedLocalStorage('my-secret-key');

storage.setItem('config', JSON.stringify({ theme: 'dark' }));
const config = storage.getItem('config');
console.log(JSON.parse(config)); // { theme: 'dark' }

Advanced Usage

import { LockedStorage } from 'locked-storage';

// Custom instance with explicit storage type
const customStorage = new LockedStorage('master-key', 'sessionStorage');

// Store complex data (serialize first)
const userData = { id: 123, name: 'Alice', roles: ['admin'] };
customStorage.setItem('user', JSON.stringify(userData));

// Retrieve and parse
const stored = customStorage.getItem('user');
const parsed = JSON.parse(stored);
console.log(parsed.name); // 'Alice'

// Clean up
customStorage.removeItem('user');
customStorage.clear(); // Removes all locked-storage items

API Reference

createLockedLocalStorage(masterKey)

Creates a new encrypted localStorage instance.

• masterKey string - The master key for encryption/decryption
• Returns LockedStorage - Encrypted localStorage instance

createLockedSessionStorage(masterKey)

Creates a new encrypted sessionStorage instance.

• masterKey string - The master key for encryption/decryption
• Returns LockedStorage - Encrypted sessionStorage instance

LockedStorage Class

constructor(masterKey, storageType?)

• masterKey string - Master key for encryption
• storageType 'localStorage' | 'sessionStorage' - Storage type (default: 'localStorage')

setItem(key, value)

Encrypts and stores a key-value pair.

• key string - The key (will be encrypted)
• value string - The value (will be encrypted)
• Returns void

getItem(key)

Retrieves and decrypts a value by key.

• key string - The key to look up
• Returns string | null - Decrypted value or null if not found

removeItem(key)

Removes an encrypted item by key.

• key string - The key to remove
• Returns void

clear()

Removes all items created by locked-storage.

• Returns void

Security

• Encryption: AES-GCM 256-bit encryption (Node.js) / AES-CBC 256-bit with HMAC authentication (Browser)
• Key Derivation: PBKDF2 with 100,000 iterations and SHA-256
• Authentication: Built-in authentication via GCM mode (Node.js) / HMAC-SHA256 (Browser)
• Salt: Unique salt generated for each item
• IV: Unique initialization vector for each encryption operation
• Dependencies: Uses Node.js built-in crypto module and crypto-js library for browsers

Browser Support

• Chrome 37+
• Firefox 34+
• Safari 7+
• Edge 12+
• IE 11+

Node.js Support

• Node.js 14.0.0+

TypeScript

Full TypeScript support included with type definitions.

import { LockedStorage, createLockedLocalStorage } from 'locked-storage';

const storage: LockedStorage = createLockedLocalStorage('key');
const value: string | null = storage.getItem('myKey');

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © PackageReleaser

Changelog

2.0.0

• BREAKING CHANGE: All methods are now synchronous (removed async/await requirement)
• Simplified encryption implementation for better browser compatibility
• Updated TypeScript definitions to reflect synchronous API
• Improved performance with synchronous operations

1.0.0

• Initial release
• Full encryption for keys and values
• Support for localStorage and sessionStorage
• Universal JavaScript compatibility
• TypeScript definitions included