Package Exports

vault-inject
vault-inject/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vault-inject) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🔐 Vault Inject

Secure environment variable injection from Hashicorp Vault
A powerful CLI tool that retrieves secrets from Vault KV engines and injects them as environment variables into your applications.

✨ Features

🔒 Secure Secret Management - Retrieve secrets from Hashicorp Vault KV v2 engines
🚀 Zero-Config Injection - Automatically inject secrets as environment variables
🎯 Flexible Command Execution - Run any command with injected secrets
🔍 Verbose Mode - Preview secrets before injection (with security masking)
🐛 Debug Support - Comprehensive debugging and error reporting
⚡ Fast & Lightweight - Built with TypeScript for performance and reliability
🛡️ Security First - Sensitive values are masked in verbose output

📦 Installation

Global Installation (Recommended)

npm install -g vault-inject

Local Installation

npm install vault-inject

Development Installation

git clone https://github.com/AmirGhiassian/vault-inject.git
cd vault-inject
npm install
npm run build

🚀 Quick Start

1. Configure Vault Access

# Set environment variables
export VAULT_ADDR="https://vault.company.com"
export VAULT_TOKEN="your-vault-token"

# Or create a .env file
echo "VAULT_ADDR=https://vault.company.com" > .env
echo "VAULT_TOKEN=your-vault-token" >> .env

2. Store Secrets in Vault

# Enable KV v2 engine (if not already enabled)
vault secrets enable -path=secret kv-v2

# Store application secrets
vault kv put secret/my-app/config \
  DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" \
  API_KEY="sk-1234567890abcdef" \
  JWT_SECRET="super-secret-jwt-key"

3. Run Your Application

# Inject secrets and run your app
vault-inject -k secret -p my-app/config -- node app.js

# Or with explicit parameters
vault-inject \
  --endpoint https://vault.company.com \
  --token your-vault-token \
  --kv-engine secret \
  --path my-app/config \
  -- node app.js

📖 Usage

Basic Syntax

vault-inject [options] <command> [args...]

Command Line Options

Option	Short	Description	Required	Default
`--endpoint`	`-e`	Vault server endpoint URL	No	`http://127.0.0.1:8200`
`--token`	`-t`	Vault authentication token	No*	`$VAULT_TOKEN`
`--kv-engine`	`-k`	KV engine name	Yes	-
`--path`	`-p`	Secret path within KV engine	Yes	-
`--verbose`	`-v`	Show environment variables before injection	No	`false`
`--ca-cert`	-	Path to CA certificate file	No	-
`--client-cert`	-	Path to client certificate file	No	-
`--client-key`	-	Path to client private key file	No	-
`--tls-skip-verify`	-	Skip TLS certificate verification (development only)	No	`false`
`--debug`	-	Enable debug logging	No	`false`
`--help`	`-h`	Display help information	No	-
`--version`	`-V`	Display version number	No	-

*Required if VAULT_TOKEN environment variable is not set.

Environment Variables

Variable	Description	Example
`VAULT_ADDR`	Vault server endpoint	`https://vault.company.com`
`VAULT_TOKEN`	Vault authentication token	`hvs.abc123...`

💡 Examples

Node.js Applications

# Basic Node.js app
vault-inject -k secret -p production/api -- npm start

# Express.js with custom port
vault-inject -k config -p staging/web -- node server.js --port 3000

# Next.js application
vault-inject -k secrets -p prod/nextjs -- npm run build

Python Applications

# Django application
vault-inject -k config -p production/django -- python manage.py runserver

# Flask with custom environment
vault-inject -k secrets -p staging/flask -- python app.py --env production

# FastAPI application
vault-inject -k api -p prod/fastapi -- uvicorn main:app --host 0.0.0.0

Docker & Containerization

# Docker Compose
vault-inject -k secrets -p prod/docker -- docker-compose up -d

# Docker run
vault-inject -k config -p staging/app -- docker run -p 8080:8080 myapp:latest

# Kubernetes (via kubectl)
vault-inject -k k8s -p production/cluster -- kubectl apply -f deployment.yaml

Database Operations

# PostgreSQL migrations
vault-inject -k db -p prod/postgres -- psql -h localhost -d mydb -f migrate.sql

# MySQL operations
vault-inject -k database -p staging/mysql -- mysql -u root -p mydb < backup.sql

# MongoDB operations
vault-inject -k nosql -p prod/mongodb -- mongo mydb --eval "db.users.find()"

Development & Testing

# Run tests with secrets
vault-inject -k test -p dev/secrets -- npm test

# Linting with environment
vault-inject -k config -p dev/lint -- npm run lint

# Build with production secrets
vault-inject -k secrets -p prod/build -- npm run build:prod

Verbose Mode Examples

# Preview secrets before injection
vault-inject -v -k secret -p my-app/config -- echo "Secrets loaded"

# Debug mode with verbose output
vault-inject --debug -v -k config -p staging/api -- node app.js

🔧 Advanced Usage

Multiple Secret Paths

# Load from different paths sequentially
vault-inject -k secret -p app/database -- \
  vault-inject -k secret -p app/redis -- \
  node app.js

Custom Vault Endpoints

# Different Vault instances
vault-inject -e https://vault-dev.company.com -k dev -p config -- node app.js
vault-inject -e https://vault-prod.company.com -k prod -p config -- node app.js

Environment-Specific Configurations

# Development
vault-inject -k config -p dev/app -- npm run dev

# Staging
vault-inject -k config -p staging/app -- npm run start:staging

# Production
vault-inject -k config -p prod/app -- npm run start:prod

TLS Certificate Configuration

# Using custom CA certificate
vault-inject --ca-cert /path/to/ca.pem -k secret -p config -- node app.js

# Using client certificates for mutual TLS
vault-inject \
  --ca-cert /path/to/ca.pem \
  --client-cert /path/to/client.pem \
  --client-key /path/to/client.key \
  -k secret -p config -- node app.js

# Skip TLS verification (development only)
vault-inject --tls-skip-verify -k secret -p config -- node app.js

# Combine with custom endpoint
vault-inject \
  -e https://vault.company.com \
  --ca-cert /etc/ssl/certs/company-ca.pem \
  -k secret -p prod/config -- node app.js

🛠️ Development

Prerequisites

Node.js 16+
npm 7+
TypeScript 5.9+
Hashicorp Vault (for testing)

Setup Development Environment

# Clone repository
git clone https://github.com/AmirGhiassian/vault-inject.git
cd vault-inject

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Test the CLI
node index.ts --help

Available Scripts

npm run build      # Compile TypeScript to JavaScript
npm run start      # Run the application with ts-node
npm run dev        # Run with file watching for development
npm test           # Run tests (when implemented)

Project Structure

vault-inject/
├── index.ts           # Main CLI application
├── tsconfig.json      # TypeScript configuration
├── package.json       # Package configuration
├── README.md          # This documentation
├── example.env        # Example environment file
└── dist/              # Compiled JavaScript output

🔒 Security Considerations

Token Management

Never commit tokens to version control
Use environment variables or secure secret management
Rotate tokens regularly
Use least-privilege access policies

Secret Masking

Verbose mode automatically masks sensitive values
Only first 4 and last 4 characters are shown
Use --debug for troubleshooting (shows full configuration)

Network Security

Use HTTPS endpoints in production
Consider Vault's TLS certificate validation
Use proper firewall rules for Vault access

Best Practices

# ✅ Good: Use environment variables
export VAULT_TOKEN=$(vault write -field=token auth/approle/login role_id=my-role)

# ✅ Good: Use .env files (not committed)
echo "VAULT_TOKEN=your-token" > .env

# ❌ Bad: Hardcode tokens
vault-inject -t "hardcoded-token" -k secret -p config -- node app.js

🐛 Troubleshooting

Common Issues

Connection Refused

# Check Vault server status
curl -s $VAULT_ADDR/v1/sys/health

# Verify endpoint URL
vault-inject --debug -e http://localhost:8200 -k secret -p config -- echo "test"

Authentication Failed

# Verify token validity
vault token lookup

# Check token permissions
vault token capabilities secret/data/my-app/config

Secret Not Found

# List available secrets
vault kv list secret/

# Check specific path
vault kv get secret/my-app/config

Permission Denied

# Check policy permissions
vault policy read my-policy

# Verify token has correct policy
vault token capabilities secret/data/my-app/config

Debug Mode

# Enable debug logging
vault-inject --debug -k secret -p config -- node app.js

# Verbose output with debug
vault-inject -v --debug -k secret -p config -- node app.js

Error Codes

Code	Description	Solution
1	General error	Check logs for specific error message
2	Invalid arguments	Verify command line options
3	Vault connection failed	Check Vault server and network
4	Authentication failed	Verify token and permissions
5	Secret not found	Check KV engine and path

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests (if applicable)
Submit a pull request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🙏 Acknowledgments

Hashicorp Vault for secure secret management
Commander.js for CLI framework
node-vault for Vault client library

📞 Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Contact: GitHub Profile

Made with ❤️ by Amir Ghiassian