Documentation

# Node.js
npm install vault-env

# Python
pip install vault-env

npx vault-env init --name my-app

npx vault-env push --env production

# Node.js
- require('dotenv').config()
+ require('vault-env').config()

# Python
- from dotenv import load_dotenv
- load_dotenv()
+ from vaultdotenv import load_vault
+ load_vault()

┌──────────────────────────────────┐
│          Your Application        │
│                                  │
│  require('vault-env').config()   │
│         or load_vault()          │
└──────────────┬───────────────────┘
               │
               │ 1. Read VAULT_KEY from .env or environment
               │ 2. Derive auth key via HKDF
               │ 3. Sign request with HMAC-SHA256
               ▼
┌──────────────────────────────────┐
│      api.vaultdotenv.io          │
│     (Cloudflare Worker + D1)     │
│                                  │
│  • Validates HMAC signature      │
│  • Validates device hash         │
│  • Returns encrypted blob        │
│  • Logs access in audit table    │
│  • NEVER sees the decryption key │
└──────────────┬───────────────────┘
               │
               │ 4. Encrypted blob returned
               ▼
┌──────────────────────────────────┐
│         Client (local)           │
│                                  │
│  • Derives decryption key from   │
│    VAULT_KEY + device secret     │
│  • Decrypts with AES-256-GCM    │
│  • Injects into process.env     │
│    (or os.environ in Python)     │
│  • Caches encrypted blob locally │
└──────────────────────────────────┘

npm install vault-env

// Async (recommended) — pulls fresh secrets from the vault
await require('vault-env').config();

// Options
await require('vault-env').config({
  path: '.env',               // Path to .env file (default: .env)
  environment: 'production',  // Environment name (default: NODE_ENV or 'development')
  vaultUrl: 'https://...',    // Vault server URL (default: api.vaultdotenv.io)
  override: false,            // Override existing env vars (default: false)
  cache: true,                // Cache secrets locally for offline fallback (default: true)
});

// Sync — reads from local encrypted cache only (no network call)
// Useful for scripts or tools that can't be async
require('vault-env').configSync();

pip install vault-env

from vaultdotenv import load_vault

# Pulls secrets from vault and injects into os.environ
load_vault()

# With options
load_vault(
    path=".env",               # Path to .env file
    environment="production",  # Environment name
    vault_url="https://...",   # Vault server URL
    override=False,            # Override existing env vars
    cache=True,                # Enable local cache fallback
)

from vaultdotenv import load_vault_sync

# Reads from local encrypted cache only — no network call
load_vault_sync()

# Safe fallback — works even without vault-env installed
try:
    from vaultdotenv import load_vault
    load_vault()
except Exception:
    from dotenv import load_dotenv
    load_dotenv()

# Initialize a new project
npx vault-env init [--name my-project]

# Push secrets to vault
npx vault-env push [--env production] [--file .env.production]

# Pull secrets from vault
npx vault-env pull [--env staging] [--output .env.staging]

# List version history
npx vault-env versions [--env production]

# Rollback to a previous version
npx vault-env rollback --version 3 [--env production]

# Device management
npx vault-env register-device [--name "CI Server"]
npx vault-env approve-device --id <device-uuid>
npx vault-env list-devices
npx vault-env revoke-device --id <device-uuid>

key_material = HMAC-SHA256(vault_key, device_secret)
encryption_key = HKDF(key_material, salt="vault-encrypt-v1")

# Push to different environments
npx vault-env push --env development
npx vault-env push --env staging
npx vault-env push --env production

# Pull from a specific environment
npx vault-env pull --env staging

const vault = require('vault-env');

await vault.config();

// Start watching (polls every 30s by default)
vault.watch({
  interval: 30000,
  environment: 'production',
  onChange(changed, allSecrets) {
    console.log('Secrets updated:', Object.keys(changed));
    // Reconnect services, refresh configs, etc.
  },
  onError(err) {
    console.error('Watch error:', err);
  },
});

// Stop watching when done
vault.unwatch();

import vaultdotenv

vaultdotenv.load_vault()

vaultdotenv.watch(
    interval=30.0,  # seconds
    on_change=lambda changed, all_secrets: print("Updated:", list(changed.keys())),
    on_error=lambda err: print(f"Error: {err}"),
)

# Stop watching
vaultdotenv.unwatch()

# Docker
docker run -e VAULT_KEY=vk_... -e VAULT_DEVICE_SECRET=abc123... -e ENVIRONMENT=production myapp

# GitHub Actions
env:
  VAULT_KEY: ${{ secrets.VAULT_KEY }}
  VAULT_DEVICE_SECRET: ${{ secrets.VAULT_DEVICE_SECRET }}

# Any CI/CD
export VAULT_KEY=vk_...
export VAULT_DEVICE_SECRET=abc123...
export ENVIRONMENT=production

.vault-cache

Input Key Material (IKM):
  If device secret exists:  HMAC-SHA256(vault_key, device_secret)
  If no device secret:      vault_key (raw bytes)

Derived Keys:
  Encryption key = HKDF-SHA256(IKM, salt="vault-encrypt-v1", info="", length=32)
  Auth key       = HKDF-SHA256(IKM, salt="vault-auth-v1",    info="", length=32)
  Device hash    = SHA-256(device_secret)

1. Derive 256-bit encryption key
2. Generate random 96-bit IV
3. Encrypt: AES-256-GCM(key, iv, plaintext_json)
4. Pack: base64(iv || auth_tag || ciphertext)
5. Send packed blob to server

1. Derive 256-bit encryption key (same derivation)
2. Unpack: base64 decode → iv (12 bytes) || auth_tag (16 bytes) || ciphertext
3. Decrypt: AES-256-GCM(key, iv, ciphertext, auth_tag)
4. Parse JSON → key-value pairs

1. Derive auth key: HKDF(vault_key, salt="vault-auth-v1")
2. Compute: HMAC-SHA256(auth_key, request_body + timestamp)
3. Header: X-Vault-Signature: v=<timestamp>,d=<hex_digest>
4. Server verifies against stored auth_key_hash (max age: 5 minutes)

projects
  id          TEXT (UUID, primary key)
  name        TEXT
  key_hash    TEXT (hex-encoded auth key hash)
  created_at  DATETIME

environments
  id          TEXT (UUID, primary key)
  project_id  TEXT (FK → projects)
  name        TEXT (development/staging/production/custom)
  created_at  DATETIME

secret_versions
  id              INTEGER (auto-increment)
  environment_id  TEXT (FK → environments)
  version         INTEGER
  encrypted_blob  TEXT (base64-encoded AES-256-GCM ciphertext)
  changed_keys    TEXT (JSON array of key names — not values)
  created_at      DATETIME

devices
  id            TEXT (UUID, primary key)
  project_id    TEXT (FK → projects)
  device_name   TEXT
  device_hash   TEXT (SHA-256 of device secret)
  status        TEXT (pending/approved/revoked)
  created_at    DATETIME
  approved_at   DATETIME
  last_seen_at  DATETIME

audit_log
  id              INTEGER (auto-increment)
  project_id      TEXT
  environment_id  TEXT
  action          TEXT (pull/push/rollback/device_register)
  ip              TEXT
  user_agent      TEXT
  created_at      DATETIME