vaultbox

vaultbox

Encrypted secrets for Next.js. No vault needed.

Store encrypted secrets in your repo. Decrypt them at runtime with a single key. Zero external dependencies beyond Node.js built-in crypto.

Install

npm install vaultbox

Quick Start

# 1. Initialize lockbox in your project
npx lockbox init

# 2. Store secrets
npx lockbox set DATABASE_URL "postgresql://user:pass@host/db"
npx lockbox set API_KEY "sk-secret-key" --env production

# 3. Use in your code

import { createLockbox } from "vaultbox";

const box = createLockbox();

// Get a secret (returns undefined if missing)
const dbUrl = box.secret("DATABASE_URL");

// Get a secret (throws if missing)
const apiKey = box.require("API_KEY");

// Get all secrets for the current NODE_ENV
const all = box.secrets();

CLI Reference

lockbox init

Generates a .lockbox-key file (random 256-bit key), creates the .secrets/ directory, and adds .lockbox-key to .gitignore.

lockbox set <name> <value> [--env ENV]

Encrypts a secret and stores it in .secrets/{env}.json. Default environment: development.

lockbox set STRIPE_KEY sk_live_abc123
lockbox set STRIPE_KEY sk_test_xyz789 --env production

lockbox get <name> [--env ENV]

Decrypts and prints a single secret.

lockbox get STRIPE_KEY
lockbox get STRIPE_KEY --env production

lockbox list [--env ENV]

Lists stored secret names (values are not shown).

lockbox list
lockbox list --env production

lockbox env [--env ENV]

Outputs all secrets in .env format. Useful for piping:

lockbox env --env production > .env.local

lockbox rotate

Generates a new encryption key and re-encrypts all secrets across all environments.

lockbox rotate

lockbox import <file> [--env ENV]

Imports secrets from an existing .env file.

lockbox import .env
lockbox import .env.production --env production

Programmatic API

createLockbox(config?)

Creates a lockbox instance that reads secrets for the current NODE_ENV.

import { createLockbox } from "vaultbox";

const box = createLockbox();
// Or with custom paths:
const box = createLockbox({
  keyPath: ".lockbox-key",   // default
  secretsDir: ".secrets",    // default
});

Methods:

Method	Returns	Description
secret(name)	string | undefined	Get a decrypted secret
require(name)	string	Get a secret; throws if missing
secrets()	Record<string, string>	All secrets for current env
encrypt(plaintext)	EncryptedEnvelope	Encrypt arbitrary text
decrypt(envelope)	string	Decrypt an envelope
rotate()	string	Re-encrypt everything; returns new key

generateKey()

Generate a random 256-bit encryption key as a hex string.

import { generateKey } from "vaultbox";
const key = generateKey(); // 64-char hex string

How It Works

• lockbox init generates a random 256-bit master key and writes it to .lockbox-key
• When you set a secret, lockbox:
  • Generates a random 128-bit IV and 256-bit salt
  • Derives an encryption key from the master key + salt using PBKDF2-SHA512 (100,000 iterations)
  • Encrypts the value with AES-256-GCM
  • Stores the envelope (IV, salt, ciphertext, auth tag) in .secrets/{env}.json
• When you read a secret at runtime, lockbox reverses the process using the same master key
• Each secret gets its own random IV and salt, so identical values produce different ciphertexts

Git Workflow

Commit these files (encrypted, safe to share):

• .secrets/development.json
• .secrets/production.json

Never commit (added to .gitignore by lockbox init):

• .lockbox-key

Share the key with your team via a secure channel (1Password, Slack DM, etc). In CI/CD, set the LOCKBOX_KEY environment variable.

# CI/CD example
LOCKBOX_KEY=your-hex-key-here npm run build

Key Rotation

lockbox rotate

This generates a new key, re-encrypts every secret in every environment, and writes the new key to .lockbox-key. Distribute the new key to your team and update CI/CD.

Migration from .env

# Import your existing .env file
lockbox import .env

# Import production secrets
lockbox import .env.production --env production

# Verify
lockbox list
lockbox list --env production

# Remove the old .env files
rm .env .env.production

License

MIT