secure-envx

secure-envx is an encrypted environment variable manager that uses AES-256-GCM and supports role-based access (dev, staging, prod, ci).

Supported platforms: Windows, macOS, Linux (Node.js 14+)

See INSTALL.md for detailed platform-specific installation instructions.

Features

• AES-256-GCM encryption for secrets
• Role-based keys and master passphrase protection
• CLI: init, set, load, rotate-key, audit
• Decrypts only in memory and injects into process.env
• Never writes plaintext secrets to disk

Installation

Prerequisites

• Node.js 14.0.0 or higher
• npm 5.2.0 or higher

Check your versions:

node --version
npm --version

Option 1: Global Install via npm (Recommended for users)

Windows (Command Prompt or PowerShell)

npm install -g secure-envx
secure-envx --version

macOS (Terminal)

npm install -g secure-envx
secure-envx --version

Linux (Terminal)

npm install -g secure-envx
secure-envx --version

Or with sudo if needed:

sudo npm install -g secure-envx
sudo npm link

Option 2: Local Install for a Project

Windows

npm install secure-envx --save-dev
npx secure-envx --version

macOS

npm install secure-envx --save-dev
npx secure-envx --version

Linux

npm install secure-envx --save-dev
npx secure-envx --version

Option 3: From Source (Development / Contributing)

Windows (PowerShell)

git clone https://github.com/yourusername/secure-envx.git
cd secure-envx
npm install
npm run build
npm link
secure-envx --version

macOS (Terminal / Bash / Zsh)

git clone https://github.com/yourusername/secure-envx.git
cd secure-envx
npm install
npm run build
npm link
secure-envx --version

The postinstall script automatically sets executable permissions on the CLI.

Linux (Terminal / Bash / Zsh / Fish)

git clone https://github.com/yourusername/secure-envx.git
cd secure-envx
npm install
npm run build
npm link
secure-envx --version

Or with sudo:

git clone https://github.com/yourusername/secure-envx.git
cd secure-envx
npm install
npm run build
sudo npm link
secure-envx --version

The postinstall script automatically sets executable permissions.

Troubleshooting Installation

"command not found: secure-envx"

On macOS/Linux, ensure npm's global bin is in your PATH:

# Check where npm installs global packages
npm config get prefix

# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

# Then reload your shell
source ~/.bashrc    # for bash
source ~/.zshrc     # for zsh

"EACCES: permission denied" on macOS/Linux

Option A: Use sudo

sudo npm install -g secure-envx

Option B: Fix npm permissions (https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)

Windows: npm not found

Ensure Node.js is installed and in PATH. Restart your terminal or computer if needed.

Quickstart

1. Initialize (all platforms)

secure-envx init
# or with npx:
npx secure-envx init

When prompted, enter a passphrase (will not be echoed):

Passphrase (will not be echoed): [type your passphrase]

Result: .secure-envx/keys.json and .secure-envx/secrets.json are created.

2. Set Secrets

Windows (PowerShell):

secure-envx set --role dev --name DATABASE_URL --value "postgres://localhost/mydb"
secure-envx set --role dev --name API_KEY --value "sk-abc123xyz"

# Or pipe the value
"my-secret-value" | secure-envx set --role dev --name SECRET

macOS (Terminal/Bash):

secure-envx set --role dev --name DATABASE_URL --value "postgres://localhost/mydb"
secure-envx set --role dev --name API_KEY --value "sk-abc123xyz"

# Or pipe the value
echo "my-secret-value" | secure-envx set --role dev --name SECRET

Linux (Terminal/Bash):

secure-envx set --role dev --name DATABASE_URL --value "postgres://localhost/mydb"
secure-envx set --role dev --name API_KEY --value "sk-abc123xyz"

# Or pipe the value
echo "my-secret-value" | secure-envx set --role dev --name SECRET

When prompted, enter your passphrase (same as init).

3. View Audit (all platforms)

secure-envx audit
secure-envx audit --role dev

4. Load Secrets into process.env (all platforms)

secure-envx load --role dev

When prompted, enter your passphrase. Secrets are now in process.env (decrypted in memory only).

5. Rotate Key (all platforms)

secure-envx rotate-key --role dev

This re-encrypts all secrets under a new role key.

Security notes

• The CLI prompts for a master passphrase used to derive a master key (scrypt). Role keys are encrypted with the master key and stored at .secure-envx/keys.json.
• Secrets are stored encrypted at .secure-envx/secrets.json and contain only ciphertext plus metadata. Plaintext is never written to disk by the library.
• Rotate keys periodically with rotate-key to re-encrypt secrets under a fresh role key.

Testing

See TESTING.md for:

• Automated unit tests (npm test)
• Interactive CLI testing guide
• Non-interactive quicktest script
• Programmatic API testing examples
• Troubleshooting tips

CLI Commands Reference

All commands work on Windows, macOS, and Linux.

# Display help
secure-envx --help
secure-envx --version

# Initialize secure storage
secure-envx init

# Set a secret
secure-envx set --role <role> --name <name> --value <value>

# Load secrets for a role (decrypt into process.env)
secure-envx load --role <role>

# Rotate encryption key for a role
secure-envx rotate-key --role <role>

# View audit information
secure-envx audit
secure-envx audit --role <role>

Supported roles: dev, staging, prod, ci

API Usage

Use secure-envx as a library in your Node.js application.

Windows Example

import { loadIntoProcessEnv } from 'secure-envx';

async function main() {
  // Load secrets for production (decrypts in memory)
  await loadIntoProcessEnv('prod', 'my-passphrase');
  
  // Now access secrets from process.env
  const dbUrl = process.env.DATABASE_URL;
  const apiKey = process.env.API_KEY;
  
  console.log('Database:', dbUrl);
  console.log('API Key:', apiKey);
}

main().catch(console.error);

macOS Example

# Install as dependency
npm install secure-envx

# Create app.ts
cat > app.ts << 'EOF'
import { loadIntoProcessEnv } from 'secure-envx';

async function main() {
  await loadIntoProcessEnv('dev', 'my-passphrase');
  console.log(process.env.DATABASE_URL);
}

main().catch(console.error);
EOF

# Run with ts-node or compile with tsc
npx ts-node app.ts

Linux Example

# Install as dependency
npm install secure-envx

# Create app.js
cat > app.js << 'EOF'
const { loadIntoProcessEnv } = require('secure-envx');

async function main() {
  await loadIntoProcessEnv('dev', 'my-passphrase');
  console.log(process.env.DATABASE_URL);
}

main().catch(console.error);
EOF

# Run
node app.js