vhsm - Virtual HSM

Virtual HSM is a secure wrapper for dotenvx that provides pluggable key decryption mechanisms for local development environments. It ensures that dotenvx private keys are never stored in plaintext and are only decrypted in memory at runtime.

Features

- 🔐 Secure Key Decryption: Password (AES-256-GCM), Windows DPAPI, FIDO2, and TPM2 providers built-in
- 💾 In-Memory Only: Decrypted keys never touch disk or logs
- 🔌 Pluggable Architecture: Easily extend with your own provider
- ⏱️ Session Caching: Optional in-memory cache with timeout to reduce repeated prompts
- 🛡️ Secure Defaults: Built-in best practices for cryptographic key handling
- 🪟 Native Windows Support: DPAPI ties secrets to the signed-in Windows user
- 🔑 Hardware Backed Security: FIDO2 (Windows Hello, security keys, mobile keys) and TPM2 with beautiful, guided UI
- 🚫 No Secret Leakage: Error handling sanitizes messages to prevent information disclosure
- 🔧 Developer-Friendly: Simple CLI workflow that integrates seamlessly with dotenvx
- ⚡ Programmatic Execution: vhsm.exec() allows secure function execution with automatic env variable injection
- 📄 JSON File Encryption: Encrypt entire JSON configuration files and access values with dot notation

Installation

``bash
npm install -g vhsm


or


npm install --save-dev vhsm
`

Prerequisites: None! vhsm includes @dotenvx/dotenvx as a dependency, so no separate installation is needed.

Quick Start

$3

Run vhsm encrypt from your project root. Choose a provider:

| Scenario | Command |
| --- | --- |
| Cross-platform / CI friendly | vhsm encrypt (password) |
| Windows workstation | vhsm encrypt -p dpapi |
| Hardware-backed (FIDO2) | vhsm encrypt -p fido2 |
| Hardware-backed (TPM2) | vhsm encrypt -p tpm2 |

Each provider automatically runs dotenvx encrypt first, then:

- password: prompts for an 8+ char passphrase and stores encrypted:...
- dpapi: no password prompts; Windows ties data to the signed-in user
- fido2: opens a local browser page for authentication (Windows Hello, security keys, mobile keys, etc.)
- tpm2: uses TPM 2.0 hardware chip (Linux/macOS only, or Docker on Windows)

Output is written to .env.keys.encrypted (600 perms). Remove plaintext .env.keys unless --no-delete.

$3

Instead of using dotenvx run directly, use vhsm run:

`bash
vhsm run -- npm start


or

vhsm run -- node server.js

or with custom encrypted key file

vhsm run -ef custom/path/.env.keys.encrypted -- npm start
`

Note: Always use -- to separate vhsm options from your command.

vhsm will:
1. Automatically detect the provider from the encrypted key file (password, dpapi, fido2, or tpm2)
2. Prompt for authentication if needed (passphrase, FIDO2 touch, etc.)
3. Decrypt the key in memory
4. Inject it as DOTENV_PRIVATE_KEY environment variable
5. Execute dotenvx run with your command

$3

By default, vhsm caches decrypted keys in memory for 1 hour to avoid repeated prompts:

`bash


Disable caching

vhsm run --no-cache -- npm start

Custom cache timeout (in milliseconds)

vhsm run --cache-timeout 1800000 -- npm start # 30 minutes
`

Clear the cache manually:
`bash
vhsm clear-cache
`

Configuration

$3

Create a .vhsmrc.json or .vhsm.json file in your project root:

`json
{
"provider": "password",
"cacheTimeout": 3600000,
"enableCache": true,
"allowExec": false,
"providerConfig": {}
}
`

- Set "provider": "dpapi" on Windows to default to DPAPI.
- Set "provider": "fido2" if you always want the FIDO2 flow.

Environment variable overrides:
- VHSM_PROVIDER: password, dpapi, or fido2
- VHSM_CACHE_TIMEOUT: Milliseconds (default 3600000)
- VHSM_ENABLE_CACHE: true / false
- VHSM_ALLOW_EXEC: true / false - Enable vhsm.exec() function (default: false for security)

$3

#### vhsm run

`bash
vhsm run [options]

Options:
-ef, --encrypted-key Path to encrypted private key file (default: .env.keys.encrypted)
-pw, --password Password/passphrase for decryption (for testing, password/tpm2 providers only)
-nc, --no-cache Disable session caching
-ct, --cache-timeout Cache timeout in milliseconds (default: 3600000)

Note: Provider is automatically detected from the encrypted key file. No need to specify -p.
`

#### vhsm encrypt

`bash
vhsm encrypt [options]

Options:
-o, --output Output path for encrypted key (default: .env.keys.encrypted)
-pw, --password Password/passphrase for encryption (for testing)
-nd, --no-delete Do not delete the original .env.keys file after encryption
-fk, --env-keys-file Path to plaintext private key file (default: .env.keys)

# Pass-through options for dotenvx encrypt:
-f, --env-file Path(s) to your env file(s)
-k, --key Key(s) to encrypt (default: all keys in file)
-ek, --exclude-key Key(s) to exclude from encryption (default: none)
`

#### vhsm decrypt

`bash
vhsm decrypt [options]

Options:
-ef, --encrypted-key Path to encrypted private key file (default: .env.keys.encrypted)
-pw, --password Password/passphrase for decryption (for testing, password/tpm2 providers only)
-nc, --no-cache Disable session caching
-ct, --cache-timeout Cache timeout in milliseconds (default: 3600000)
-r, --restore Restore the decrypted key to a .env.keys file
-fk, --env-keys-file Output path for restored key file (used with --restore) (default: .env.keys)

Note: Provider is automatically detected from the encrypted key file. No need to specify -p.

# Pass-through options for dotenvx decrypt:
-f, --env-file Path(s) to your env file(s)
-k, --key Key(s) to decrypt (default: all keys in file)
-ek, --exclude-key Key(s) to exclude from decryption (default: none)
`

Security Best Practices

$3

1. Never commit encrypted keys to version control
- Add .env.keys.encrypted to your .gitignore
- Use secure secret management for team sharing

2. Secure file permissions
- Encrypted key files are created with mode 600 (owner read/write only)
- Verify permissions: chmod 600 .env.keys.encrypted

3. Strong passphrases
- Use a strong, unique passphrase (minimum 12+ characters recommended)
- Consider using a password manager
- Never reuse passphrases from other systems

4. Environment isolation
- Use different encrypted keys for different environments
- Rotate keys periodically

$3

- Decrypted keys exist only in process memory
- Keys are cleared from memory after spawning dotenvx (best effort)
- Session cache is in-memory only and expires automatically
- No keys are written to disk or logs

$3

- Error messages are sanitized to prevent secret leakage
- Stack traces are limited to prevent information disclosure
- Failed decryption attempts don't reveal key structure

Providers

| Provider | Platforms | Interaction | Best For |
| --- | --- | --- | --- |
| password (default) | All | Passphrase prompt | Portability, CI, team sharing |
| dpapi | Windows 10/11+ | None | Individual Windows workstations |
| fido2 | All | FIDO2 authentication (Windows Hello, security keys, mobile) | Hardware-backed secrets |
| tpm2 | Linux/macOS | Optional PIN | Hardware TPM chip protection |

👉 See FIDO2-QUICKSTART.md or FIDO2-GUIDE.md for screenshots, troubleshooting, and architecture details.

$3

- Encrypt: vhsm encrypt -p dpapi
- Run: vhsm run -- npm start (auto-detects provider)
- Keys can only be decrypted by the same Windows user profile.
- Great for local dev; not suitable for CI or shared servers.

$3

- Encrypt: vhsm encrypt -p fido2
- Run: vhsm run -- npm start (auto-detects provider)
- Browser flow opens automatically (http://localhost:8765) with polished UI.
- Supports Windows Hello (PIN/biometric), hardware security keys (YubiKey, etc.), and mobile keys (Face ID via QR code).
- One credential protects multiple env files; authenticate once per session to decrypt.
- Works cross-platform as long as a browser + FIDO2 authenticator is present.

$3

- Encrypt: vhsm encrypt -p tpm2
- Run: vhsm run -- npm start (auto-detects provider)
- Uses TPM 2.0 hardware chip for hardware-backed encryption.
- Optional authorization password for additional security layer.
- Linux/macOS only (or use Docker on Windows - see test-app/DOCKER.md).

Architecture

$3

vhsm uses a pluggable provider architecture. The built-in providers satisfy most workflows, but you can register custom ones.

Additional Guides

- QUICKSTART.md – Get started quickly with password or FIDO2 providers.
- FIDO2-QUICKSTART.md – FIDO2 test flow, screenshots, troubleshooting.
- FIDO2-GUIDE.md – Deep dive into FIDO2 security model, remote access tips, FAQs.
- EXEC-FEATURE.md – Complete guide to vhsm.exec() programmatic function execution.
- PUBLISHING.md – Instructions for shipping vhsm to npm.

#### Creating Custom Providers

Implement the KeyDecryptionProvider interface:

`typescript
import type { KeyDecryptionProvider } from 'vhsm';

export class MyCustomProvider implements KeyDecryptionProvider {
readonly name = 'my-provider';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
// Your decryption logic here
return decryptedKey;
}
}
`

Register your provider:

`typescript
import { registerProvider } from 'vhsm';
import { MyCustomProvider } from './my-provider.js';

registerProvider(new MyCustomProvider());
`

Future Provider Integrations

The architecture is designed to support various key management backends:

$3

`typescript
export class DockerSecretsProvider implements KeyDecryptionProvider {
readonly name = 'docker-secrets';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
const secretPath = process.env.DOCKER_SECRET_PATH || '/run/secrets/dotenvx-key';
const secret = await readFile(secretPath, 'utf-8');
// Decrypt using secret
return decrypt(encryptedKey, secret);
}
}
`

$3

`typescript
import { execSync } from 'child_process';

export class WindowsDPAPIProvider implements KeyDecryptionProvider {
readonly name = 'windows-dpapi';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
// Use PowerShell to decrypt with DPAPI
const script = [System.Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect([System.Convert]::FromBase64String('${encryptedKey}'), $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser));
return execSync(powershell -Command "${script}", { encoding: 'utf-8' }).trim();
}
}
`

$3

`typescript
import { execSync } from 'child_process';

export class KeychainProvider implements KeyDecryptionProvider {
readonly name = 'keychain';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
// Use security command to retrieve from Keychain
const service = 'vhsm';
const account = 'dotenvx-key';
const password = execSync(
security find-generic-password -s ${service} -a ${account} -w,
{ encoding: 'utf-8' }
).trim();
return decrypt(encryptedKey, password);
}
}
`

$3

`typescript
import { Tpm2Tools } from 'tpm2-tools';

export class TPMProvider implements KeyDecryptionProvider {
readonly name = 'tpm';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
// Use TPM to unwrap the key
const tpm = new Tpm2Tools();
const handle = process.env.TPM_KEY_HANDLE || '0x81000000';
return await tpm.unseal(encryptedKey, handle);
}
}
`

$3

`typescript
import { PKCS11 } from 'pkcs11';

export class HSMProvider implements KeyDecryptionProvider {
readonly name = 'hsm';
readonly requiresInteraction = false;

async decrypt(encryptedKey: string): Promise {
const session = await PKCS11.openSession({
library: process.env.PKCS11_LIB,
slot: parseInt(process.env.PKCS11_SLOT || '0'),
pin: process.env.PKCS11_PIN,
});

const key = await session.getKey(process.env.HSM_KEY_ID);
return await key.decrypt(encryptedKey);
}
}
`

API Reference

$3

#### Provider API

`typescript
import { getProvider, SessionCache, createKeyId } from 'vhsm';

// Get a provider
const provider = getProvider('password');

// Decrypt a key
const decrypted = await provider.decrypt(encryptedKey);

// Use session cache
const cache = new SessionCache(3600000); // 1 hour timeout
const keyId = createKeyId(encryptedKey);
cache.set(keyId, decrypted);
const cached = cache.get(keyId);
`

#### Secure Function Execution (vhsm.exec())

vhsm.exec() allows you to execute functions with automatic decryption and injection of environment variables. This feature is disabled by default for security - you must explicitly enable it via admin-controlled settings.

Enable exec() (admin-controlled):

1. Environment variable: export VHSM_ALLOW_EXEC=true
2. Config file: Add "allowExec": true to .vhsmrc.json

⚠️ Security Note: exec() cannot be enabled programmatically via options. This is by design to prevent malicious code or compromised dependencies from bypassing admin restrictions.

Basic Example:

`typescript
import { exec } from 'vhsm';

// Enable exec() via environment variable first
// export VHSM_ALLOW_EXEC=true

const result = await exec(
async ({ message, apiKey }) => {
// apiKey is automatically decrypted from @vhsm API_KEY
return signMessage(message, apiKey);
},
{
message: 'Hello, World!',
apiKey: '@vhsm API_KEY' // Automatically decrypted from .env
},
{
encryptedKeysFile: '.env.keys.encrypted',
envFile: '.env',
}
);
`

Nested Execution:

`typescript
// exec() calls can be nested - useful for loading wallets, signing transactions, etc.
const result = await exec(
async ({ wallet }) => {
// wallet is loaded via nested exec()
return wallet.signTransaction(tx);
},
{
wallet: await exec(
loadWallet,
{ mnemonic: '@vhsm CRYPTO_WALLET' }
)
}
);
`

Features:
- ✅ Automatic env variable decryption and injection
- ✅ Memory cleanup of sensitive data after execution
- ✅ Nested/recursive execution support
- ✅ Session caching support
- ✅ Security gate (disabled by default)

👉 See EXEC-FEATURE.md for complete documentation and examples.

Test Application

A complete test application is included in the test-app/ directory to demonstrate the vhsm workflow.

$3

Windows (PowerShell):
`powershell
.\test-app\demo-flow.ps1
`

Linux/Mac:
`bash
bash test-app/demo-flow.sh
`

$3

`bash


1. Install test app dependencies

cd test-app
npm install

2. Create .env file

node create-env.js

3. Generate dotenvx key

dotenvx encrypt

4. Encrypt the key (from project root)

cd ..
node dist/cli.js encrypt test-app/.env.keys -o test-app/.env.keys.encrypted

5. Run the test server

node dist/cli.js run -ef test-app/.env.keys.encrypted -- node test-app/server.js
`

$3

`bash
cd test-app
node verify-setup.js
`

See test-app/README.md and test-app/QUICKSTART.md for detailed instructions.

JSON File Encryption

vHSM now supports encrypting entire JSON configuration files! This is perfect for storing structured configuration data securely.

$3

`bash


Encrypt a JSON file

vhsm encrypt config.json

Decrypt it

vhsm decrypt config.encrypted.json
`

$3

`typescript
import { loadFile, getJsonValue, exec } from 'vhsm';

// Load entire JSON file
const config = await loadFile('./config.encrypted.json');

// Get specific value with dot notation
const dbPassword = await getJsonValue(
'./config.encrypted.json',
'database.credentials.password'
);

// Use in exec() with @vhsm syntax
// (Requires VHSM_ALLOW_EXEC=true environment variable)
const result = await exec(
async ({ userName, apiKey }) => {
console.log(User: ${userName}, Key: ${apiKey});
},
{
userName: '@vhsm config.encrypted.json user.name',
apiKey: '@vhsm config.encrypted.json apiKeys.primary',
}
);
`

📚 See JSON-ENCRYPTION.md for complete documentation and examples.

Troubleshooting

$3

- Ensure the encrypted key file exists at the specified path
- Check file permissions (should be readable by current user)
- Verify the path is correct (use -k option to specify custom path)

$3

- Verify you're using the correct passphrase
- Ensure the encrypted key file wasn't corrupted
- Try re-encrypting the key: vhsm encrypt .env.keys -o .env.keys.encrypted

$3

This shouldn't happen as vhsm includes dotenvx as a dependency. If you see this error:
- Reinstall vhsm: npm install -g vhsm
- Check that vhsm's dependencies installed correctly

$3

- Check that caching is enabled: vhsm run --cache-timeout 3600000
- Verify the key ID hasn't changed (different encrypted keys = different cache entries)
- Clear cache and retry: vhsm clear-cache`

Contributing

Contributions are welcome! Areas for improvement:

- Additional provider implementations (Docker, DPAPI, Keychain, TPM, HSM)
- Enhanced error messages (while maintaining security)
- Performance optimizations
- Additional security features

License

MIT

Acknowledgments

- Built for use with dotenvx
- Inspired by best practices from HSM and key management systems