Documentation

Installation

Install env-lock via npm:

npm install @oxog/env-lock

Or using yarn:

yarn add @oxog/env-lock

Quick Start

1. Generate Encryption Key

npx env-lock generate-key

Save this key securely. You'll need it to decrypt your environment variables.

2. Encrypt Your .env File

npx env-lock encrypt --key YOUR_GENERATED_KEY

This creates a .env.lock file that you can safely commit to git.

3. Use in Your Application

// Load at the top of your app (before other imports)
require('@oxog/env-lock').config();

// Now use process.env as normal
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;

4. Set the Decryption Key

Pass the encryption key via environment variable:

OXOG_ENV_KEY=your_key_here node index.js

CLI Commands

generate-key

Generate a cryptographically secure 256-bit encryption key

npx env-lock generate-key

Alias: genkey

encrypt

Encrypt a .env file to .env.lock

npx env-lock encrypt --key YOUR_KEY

# Options:
--key, -k      Encryption key (generates new if not provided)
--input, -i    Input file path (default: .env)
--output, -o   Output file path (default: .env.lock)

Examples:

# Encrypt .env to .env.lock
npx env-lock encrypt --key abc123...

# Encrypt custom file
npx env-lock encrypt -i .env.production -o .env.production.lock -k abc123...

decrypt

Decrypt a .env.lock file

npx env-lock decrypt --key YOUR_KEY

# Options:
--key, -k      Decryption key (or use OXOG_ENV_KEY env var)
--input, -i    Input file path (default: .env.lock)
--output, -o   Output file path (outputs to stdout if not provided)

Examples:

# Decrypt to stdout
npx env-lock decrypt --key abc123...

# Decrypt to file
npx env-lock decrypt -k abc123... -o .env.decrypted

# Use environment variable for key
OXOG_ENV_KEY=abc123... npx env-lock decrypt

help

Display help information

npx env-lock help

API Reference

config([options])

Load and decrypt environment variables from .env.lock

const envLock = require('@oxog/env-lock');

// Load with defaults
envLock.config();

// Load with options
envLock.config({
  path: '.env.production.lock',
  encoding: 'utf8',
  override: true,
  silent: false
});

Options:

  • path - Path to .env.lock file (default: '.env.lock')
  • encoding - File encoding (default: 'utf8')
  • override - Override existing env vars (default: false)
  • silent - Suppress console output (default: true)

generateKey()

Generate a 256-bit encryption key

const { generateKey } = require('@oxog/env-lock');

const key = generateKey();
console.log(key); // 64-character hex string

encrypt(text, key)

Encrypt plaintext using AES-256-GCM

const { encrypt, generateKey } = require('@oxog/env-lock');

const key = generateKey();
const encrypted = encrypt('SECRET_VALUE=my_secret', key);
console.log(encrypted); // IV:TAG:DATA format

decrypt(ciphertext, key)

Decrypt encrypted data

const { decrypt } = require('@oxog/env-lock');

const decrypted = decrypt(encrypted, key);
console.log(decrypted); // Original plaintext

parse(content)

Parse .env file content into an object

const { parse } = require('@oxog/env-lock');

const content = 'DATABASE_URL=postgresql://...\nAPI_KEY=sk_test_123';
const parsed = parse(content);
// { DATABASE_URL: 'postgresql://...', API_KEY: 'sk_test_123' }

stringify(obj)

Convert object to .env file format

const { stringify } = require('@oxog/env-lock');

const obj = { DATABASE_URL: 'postgresql://...', API_KEY: 'sk_test_123' };
const content = stringify(obj);
// DATABASE_URL=postgresql://...\nAPI_KEY=sk_test_123

Security

Encryption Details

  • • Algorithm: AES-256-GCM (Galois/Counter Mode)
  • • Key length: 256 bits (32 bytes)
  • • IV length: 96 bits (12 bytes)
  • • Authentication tag: 128 bits (16 bytes)
  • • Random IV per encryption operation

Best Practices

Keep the encryption key secret

Never commit OXOG_ENV_KEY to version control. Store it in a secure location.

Use different keys for different environments

Separate keys for development, staging, and production.

Rotate keys periodically

Generate new keys and re-encrypt your files regularly.

Use environment-specific .env.lock files

Create .env.production.lock, .env.staging.lock, etc.

Deployment

Docker

# Pass the key at runtime
docker run -e OXOG_ENV_KEY=your_key myapp

# Or via docker-compose
environment:
  OXOG_ENV_KEY: ${OXOG_ENV_KEY}

GitHub Actions

# Add OXOG_ENV_KEY to repository secrets
# Then use in workflow:
- name: Run tests
  run: npm test
  env:
    OXOG_ENV_KEY: ${{ secrets.OXOG_ENV_KEY }}

Kubernetes

# Create secret
kubectl create secret generic env-key \
  --from-literal=OXOG_ENV_KEY=your_key

# Reference in deployment
env:
  - name: OXOG_ENV_KEY
    valueFrom:
      secretKeyRef:
        name: env-key
        key: OXOG_ENV_KEY

Cloud Platforms

Heroku

heroku config:set OXOG_ENV_KEY=your_key

AWS / Azure / GCP

Use platform-specific secret managers and inject OXOG_ENV_KEY as an environment variable