🛡️ env-vault-guard

A compile-time and runtime environment variable auditor and leak prevention shield for JavaScript/TypeScript projects. It protects your application against accidental exposure of secrets (like database URLs, private API keys, JWT secrets) in client-side bundles, unapproved logging destinations, and outbound HTTP requests.

Features

• 🧬 Runtime Proxy Guard: Intercepts process.env lookups. Automatically errors if secret keys are accessed in client-side/browser environments.
• 🔍 Zero-Config Auto-detection: Automatically registers keys containing keyword patterns like SECRET, KEY, TOKEN, PASSWORD, DATABASE, PASS, AUTH, PWD, DSN as secrets.
• 📡 Leak Prevention Interceptors: Monkey-patches outbound network calls (fetch, XMLHttpRequest, Node.js http/https requests) and logging utilities (console.*, process.stdout.write, process.stderr.write) to detect and block secret data leakages.
• 🛠️ Customizable Actions: Configure individual or global actions for detected leaks:
  • throw: Terminate the operation immediately with a security error.
  • warn: Report the leak with a safe console warning without exposing the actual secret value.
  • mask: Replace secret values in payloads/logs in-place with [REDACTED_SECRET_KEY] and continue safely.
• 🔗 Whitelisted Destinations: Permit specific secrets to be sent to designated domains or API endpoints (e.g. Stripe credentials to api.stripe.com).
• 🏗️ Compile-time Bundler Plugins: Vite, Rollup, and Webpack plugins that fail build steps if secret references or literal secret values are discovered inside your frontend bundle.

Installation

npm install env-vault-guard --save-dev

Quick Start (Zero Config)

Simply import and activate the guard at the absolute entry point of your application (before any other code or HTTP requests are made):

import { guardEnv } from 'env-vault-guard';

// Initializes the shield and auto-detects secrets in process.env
guardEnv();

Detailed Usage & Configuration

Runtime Configuration

You can customize exactly which variables are secrets, public-facing, whitelisted destinations, and the default actions to take on detection:

import { guardEnv } from 'env-vault-guard';

guardEnv({
  // Specify explicit secrets and customized configurations
  secrets: {
    STRIPE_SECRET_KEY: {
      action: 'mask', // Redact this secret in logs instead of throwing
      allowedUrls: ['https://api.stripe.com'], // Only allow fetch/http to Stripe API
    },
    DATABASE_URL: {
      action: 'throw', // Always block database URL leaks
      allowedUrls: [], // Cannot be sent over any network request
    }
  },
  
  // Variables explicitly allowed anywhere
  public: [
    'NEXT_PUBLIC_API_URL',
    'VITE_APP_ENV'
  ],

  // Default action when a leak is detected: 'throw' | 'warn' | 'mask'
  defaultAction: 'throw',

  // Custom callback for telemetry/alerts
  onLeakDetected: (context) => {
    console.warn(`[Audit Log] Leak attempted! key=${context.key} sink=${context.sink}`);
    // return 'mask'; // Optionally override default action dynamically
  }
});

Compile-time Bundler Plugins

Prevent secrets from being packaged into client bundles at compile-time by adding bundler plugins to your build configs.

⚡ Vite / Rollup

Add the plugin to your vite.config.ts or rollup.config.js:

import { defineConfig } from 'vite';
import { envVaultGuardVite } from 'env-vault-guard';

export default defineConfig({
  plugins: [
    envVaultGuardVite({
      // Explicit secrets to block, defaults to auto-detected secrets from .env
      secrets: ['STRIPE_SECRET_KEY', 'JWT_SECRET'],
      // Exclude files from source reference scanning (output chunks are always scanned)
      excludeFiles: [/node_modules/],
      // Fail the build if a leak is detected (otherwise warns)
      errorOnLeak: true,
    })
  ]
});

📦 Webpack

Add the plugin to your webpack.config.js:

const { EnvVaultGuardWebpack } = require('env-vault-guard');

module.exports = {
  plugins: [
    new EnvVaultGuardWebpack({
      secrets: ['STRIPE_SECRET_KEY', 'DATABASE_URL'],
      errorOnLeak: true,
    })
  ]
};

Development and Testing

Run unit tests using Vitest:

npm run test

Build the package (generates both CommonJS and ESM outputs under dist/):

npm run build

License

MIT