🔐 Secure Vault SDK

A 100% offline, on-device encryption vault SDK for Node.js. Store sensitive data securely with AES-256-GCM encryption, PBKDF2 key derivation, and zero cloud dependencies.

✨ Features

| Feature | Description | |---------|-------------| | 🔒 100% Offline | Data never leaves the device - no cloud, no network | | 🛡️ AES-256-GCM | Industry-standard encryption with tamper detection | | 🔑 PBKDF2 Key Derivation | 100k iterations - brute-force resistant | | ⏱️ Auto-Lock Timeout | Key cleared from memory after inactivity | | 📁 Secure Permissions | Vault files readable only by owner (600) | | 🧩 Zero Dependencies | No npm bloat, no supply chain risk | | ✅ 63 Tests | Comprehensive test coverage |

📦 Installation

# Clone the repository
git clone https://github.com/your-org/secure-vault-sdk.git
cd secure-vault-sdk

# No npm install needed - zero dependencies!

🚀 Quick Start

import { createVault, unlockVault, deleteVault } from './src/index.js';

// Create a new vault
const vault = await createVault('my-app', 'SecurePass123!');

// Store secrets
await vault.set('api_key', 'sk-12345-abcde');
await vault.set('config', { debug: false, maxRetries: 3 });

// Retrieve secrets
const apiKey = await vault.get('api_key');
console.log(apiKey); // 'sk-12345-abcde'

// List all keys
const keys = await vault.list();
console.log(keys); // ['api_key', 'config']

// Lock vault when done (clears key from memory)
vault.lock();

📖 API Reference

createVault(name, password, options?)

Creates a new encrypted vault.

const vault = await createVault('my-vault', 'SecurePass123!', {
  autoLockMs: 300000  // Auto-lock after 5 minutes (default)
});

| Parameter | Type | Description | |-----------|------|-------------| | name | string | Unique vault name (alphanumeric, dashes, underscores) | | password | string | Master password (min 8 chars, requires variety) | | options.autoLockMs | number \| null | Auto-lock timeout in ms. null to disable |

Throws: If vault already exists, password is weak, or name is invalid.

unlockVault(name, password, options?)

Unlocks an existing vault.

const vault = await unlockVault('my-vault', 'SecurePass123!');

Throws: If vault not found, password is wrong, or vault is corrupted.

deleteVault(name)

Permanently deletes a vault.

await deleteVault('my-vault');

Vault Instance Methods

| Method | Description | |--------|-------------| | vault.set(key, value) | Store a secret (string, object, array, etc.) | | vault.get(key) | Retrieve a secret (returns null if not found) | | vault.list() | List all secret keys | | vault.remove(key) | Delete a secret | | vault.lock() | Lock vault and clear key from memory |

🛡️ Security Features

This SDK has been hardened against 9 security vulnerabilities:

| # | Vulnerability | Protection | |---|---------------|------------| | 1 | Key in memory | lock() zeros out encryption key | | 2 | Race conditions | Mutex serializes concurrent writes | | 3 | Weak passwords | Min 8 chars, variety required, common passwords blocked | | 4 | Path traversal | Vault names validated, special chars rejected | | 5 | Corrupted vaults | Structure validation with clear error messages | | 6 | Silent overwrite | Existence check prevents accidental data loss | | 7 | Prototype pollution | Dangerous keys (__proto__, etc.) rejected | | 8 | Unsafe permissions | Files: 600, directories: 700 | | 9 | No auto-lock | Configurable timeout, resets on activity |

⚙️ Configuration

Password Requirements

• Minimum 8 characters
• At least 2 of: lowercase, uppercase, number, special character
• Not a common password (e.g., password, 123456)

Auto-Lock Options

// Default: 5 minutes
const vault = await createVault('my-vault', 'Pass123!');

// Custom timeout: 1 minute
const vault = await createVault('my-vault', 'Pass123!', { autoLockMs: 60000 });

// Disable auto-lock
const vault = await createVault('my-vault', 'Pass123!', { autoLockMs: null });

🧪 Testing

# Run all 63 tests
npm test

# Or directly with Node.js
node --test tests/*.test.js

Test Coverage

| Category | Tests | |----------|-------| | Core (crypto, keyDerivation, vault) | 19 | | Security faults (#1-#9) | 29 | | Edge cases | 15 | | Total | 63 |

📁 Project Structure

secure-vault-sdk/
├── src/
│   ├── index.js              # SDK entry point
│   ├── vault.js              # High-level vault API
│   ├── crypto.js             # AES-256-GCM encryption
│   ├── keyDerivation.js      # PBKDF2 key derivation
│   ├── storage.js            # File I/O with permissions
│   ├── mutex.js              # Race condition prevention
│   ├── passwordValidator.js  # Password strength checks
│   ├── secretKeyValidator.js # Prototype pollution prevention
│   └── vaultNameValidator.js # Path traversal prevention
├── tests/                    # 63 test files
├── examples/
│   └── demo.js               # Usage example
├── CHANGELOG.md              # Development history
└── README.md

🔐 Where Are Vaults Stored?

Vaults are stored in ~/.secure-vault/ with secure permissions:

~/.secure-vault/
├── my-app.vault      # Encrypted vault file (mode: 600)
└── another-app.vault

📝 Use Cases

• API Key Storage - Securely store third-party API keys
• Configuration Secrets - Database passwords, JWT secrets
• User Credentials - Local password managers
• IoT Devices - Offline secret storage
• Field Applications - Works without internet connectivity
• Compliance - GDPR/HIPAA-friendly (data stays on device)

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Write tests for your changes
4. Ensure all 63+ tests pass (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing)
7. Open a Pull Request

Built with security-first principles. Zero dependencies. 100% offline.