typed-env-vault

A secure environment variable validator and vault that encrypts secrets on disk and hides them from console.log() statements while keeping them fully accessible in your code.

Features

• Secure Vault Mode: Automatically encrypts your .env file to .env.vault while the server is running.
• Log Protection: Environment variables are protected from accidental console.log(env) leakage. Values are automatically masked as [PROTECTED_SECRET].
• Auto-Restore: When your Node.js process closes gracefully, the .env.vault is safely decrypted back to its plain-text .env state.
• Type Validation: Powered by zod, ensures your environment variables match expected types, enums, and required statuses.

Installation

npm install typed-env-vault

Usage

Create a .env file in your project root:

PORT=3000
DATABASE_URL=mongodb://localhost:27017/mydb
NODE_ENV=development

In your application entry point (e.g., index.ts or server.ts):

import { createEnv, initSecureEnv } from 'typed-env-vault';

async function bootstrap() {
    // 1. Initialize the secure vault (encrypts .env and prepares auto-restore)
    await initSecureEnv({
        targetFile: '.env',
        enableSecureMode: process.env.NODE_ENV !== 'development' // or true for testing
    });

    // 2. Validate and retrieve your environment variables
    const env = createEnv({
        PORT: { type: 'number', default: 3000 },
        DATABASE_URL: { type: 'url', required: true },
        NODE_ENV: { type: 'string', enum: ['development', 'production', 'test'] }
    }, {
        secureMode: true // Enables console.log masking
    });

    // 3. Use your variables!
    // They work exactly like strings, but console.log hides them!
    
    // Outputs: Database URL: [HIDDEN_VALUE_SECURE_MODE_ACTIVE]
    console.log("Database URL:", env.DATABASE_URL); 

    // Connect securely: Mongoose uses the raw string automatically!
    // await mongoose.connect(env.DATABASE_URL);
}

bootstrap();

How It Works

1. When the app starts: initSecureEnv reads .env, encrypts it to .env.vault, and truncates .env.
2. In memory: Variables are loaded into process.env, but createEnv returns them wrapped in a smart proxy object. This object acts completely like a standard string (so database drivers and string concatenations can use the real secret) but overrides util.inspect and toJSON() so console.log never leaks the secret.
3. When the app stops: The process listens for exit, SIGINT, etc. and instantly decrypts the vault back to .env.