@awish/env-guardian 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# 🛡️ env-guardian
+
+> A lightweight, zero-dependency, and highly secure environment variable validation library for Node.js.
+
+[![npm version](https://img.shields.io/npm/v/env-guardian.svg)](https://www.npmjs.com/package/env-guardian)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node requirement](https://img.shields.io/node/v/env-guardian.svg)](https://nodejs.org/)
+
+**env-guardian** enforces strict schemas on your `.env` files and runtime environment variables. It prevents prototype pollution, masks sensitive secrets from crash logs, and guarantees that your app never boots with missing or invalid configurations.
+
+---
+
+## ✨ Features
+
+- **🔒 Security First:** Actively scans for prototype pollution attempts (`__proto__`, `constructor`) and blocks them.
+- **🤫 Secret Masking:** Automatically prevents sensitive keys (e.g., `PASSWORD`, `API_KEY`, `TOKEN`) from leaking in error traces.
+- **🛡️ Type Safety:** Casts string variables into actual booleans and numbers.
+- **✅ Schema Validation:** Enforce `required` variables, apply `default` fallbacks, and restrict to `allowedValues`.
+- **🚀 Zero Dependencies:** Tiny footprint. Built entirely with native Node.js APIs.
+- **💻 CLI Included:** Verify your environments directly from the terminal or CI/CD pipelines.
+
+---
+
+## 📦 Installation
+
+To install the package, run the following command in your project directory:
+
+```bash
+npm install env-guardian
+```
+
+*(Note: If the package name is scoped, replace this with `npm install @your-username/env-guardian`)*
+
+---
+
+## 💻 Usage
+
+Create a validation schema and pass it to `loadAndValidate()`. If the validation fails, it throws an early, descriptive error—preventing your app from running in a broken state.
+
+### 1. Basic Example
+
+```javascript
+import { loadAndValidate } from 'env-guardian';
+
+// Define how your environment should look
+const schema = {
+  PORT: { 
+    type: 'number', 
+    required: true, 
+    default: 3000 
+  },
+  NODE_ENV: { 
+    type: 'string', 
+    allowedValues: ['development', 'staging', 'production'],
+    default: 'development'
+  },
+  DB_PASSWORD: { 
+    type: 'string', 
+    required: true 
+  },
+  ENABLE_FEATURE_X: { 
+    type: 'boolean', 
+    default: false 
+  }
+};
+
+// Validate! 
+// This automatically loads from '.env' by default and applies your schema
+const env = loadAndValidate(schema);
+
+// Your variables are now safely typed and guaranteed to be present
+console.log(typeof env.PORT); // "number"
+console.log(env.ENABLE_FEATURE_X); // true or false boolean
+```
+
+### 2. Error Handling & Secret Masking
+
+If a developer configured something incorrectly, `env-guardian` provides clear errors. However, it will **never** leak secrets in the stack trace.
+
+```javascript
+// A developer accidentally typed `DB_PASSWORD=12345` instead of a string...
+
+try {
+  const env = loadAndValidate(schema);
+} catch (error) {
+  console.error(error.message); 
+  // Output: "Invalid value for DB_PASSWORD (value masked for security)"
+}
+```
+
+---
+
+## 🛠️ Configuration Options
+
+The `loadAndValidate` method accepts an optional second argument for configuration:
+
+```javascript
+const env = loadAndValidate(schema, {
+  path: './config/.env.production', // Load a custom file path
+  skipDotenv: true,                 // Don't read from disk, just validate process.env
+});
+```
+
+---
+
+## 🖥 CLI Tool
+
+Want to validate your `.env` without writing any code? **env-guardian** includes a terminal tool perfect for CI/CD pipelines (like GitHub Actions) to catch bad environment configurations before deployment.
+
+1. Ensure you have an `env-schema.json` file in your root directory:
+```json
+{
+  "PORT": { "type": "number", "required": true },
+  "API_KEY": { "type": "string", "required": true }
+}
+```
+
+2. Run the guardian:
+```bash
+npx env-guardian
+```
+
+**Output:**
+```
+✅ Environment configuration is valid and secure.
+```
+*(Will exit with code `1` and print errors if the configuration is invalid).*
+
+---
+
+## 🧪 Testing
+
+To run the internal test suite:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@awish/env-guardian",
+    "version": "1.0.0",
+    "description": "Secure environment variable validation library",
+    "main": "./src/index.js",
+    "exports": {
+        ".": {
+            "import": "./src/index.js",
+            "require": "./src/index.js"
+        }
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "bin": "./src/cli.js",
+    "scripts": {
+        "test": "node --test"
+    },
+    "keywords": [
+        "env",
+        "environment",
+        "variable",
+        "validation",
+        "security"
+    ],
+    "author": "",
+    "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { loadAndValidate } from './index.js'
+
+const schemaPath = path.resolve(process.cwd(), 'env-schema.json');
+
+if(!fs.existsSync(schemaPath)) {
+    console.error('Error: env-schema.json not found in current directory.')
+    process.exit(1);
+}
+
+try {
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+    loadAndValidate(schema);
+    console.log('✅ Environment configuration is valid and secure.');
+} catch (err) {
+    console.error(`❌ Validation Failed:\n${err.message}`)
+    process.exit(1)
+}

package/src/errors.js

@@ -0,0 +1,20 @@
+export class EnvValidationError extends Error {
+    constructor(message, property) {
+        let safeMessage = message;
+
+        if(property && /PASSWORD|TOKEN|API_KEY/i.test(property)) {
+            safeMessage = `Invalid value for ${property} (value masked for security)`
+        }
+
+        super(safeMessage);
+        this.name = 'EnvValidationError';
+        this.property = property;
+    }
+}
+
+export class EnvSecurityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvSecurityError';
+    }
+}

package/src/index.js

@@ -0,0 +1,16 @@
+import { parseEnvFile } from "./parser.js";
+import { validateEnv } from "./validator.js";
+import { checkSecurity } from "./security.js";
+
+export const loadAndValidate = (schema, options = {}) => {
+    const parsed = options.skipDotenv ? {} : parseEnvFile(options.path || '.env');
+    const combinedEnv = { ...process.env, ...parsed};
+    
+    checkSecurity(combinedEnv);
+
+    return validateEnv(schema, combinedEnv);
+};
+
+export { validateEnv } from './validator.js';
+export { parseEnvFile as parseDotenv } from './parser.js';
+export { EnvValidationError, EnvSecurityError } from './errors.js';

package/src/parser.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_FILE_SIZE = 1024 * 1024; // 1MB
+
+const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'];
+
+const isValidKey = (key) => {
+    if (DANGEROUS_KEYS.includes(key.toLowerCase())) return false;
+    return /^[a-zA-Z0-9_]+$/.test(key);
+};
+
+export const parseEnvFile = (filePath) => {
+    const fullPath = path.resolve(process.cwd(), filePath);
+
+    let stats;
+    try {
+        stats = fs.statSync(fullPath);
+    } catch (err) {
+        if (err.code === 'ENOENT') return {};
+        throw err;
+    }
+
+    if (stats.size > MAX_FILE_SIZE) {
+        throw new Error('Environment file exceeds maximum allowed size of 1MB');
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    const result = Object.create(null);
+
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+
+        const match = trimmed.match(/^([^=]+)=(.*)$/);
+        if (!match) continue;
+
+        const key = match[1].trim();
+        let value = match[2].trim();
+
+        if (!isValidKey(key)) {
+            throw new Error(`Invalid or dangerous key detected: ${key}`);
+        }
+
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+
+        result[key] = value;
+    }
+
+    return result;
+};

package/src/security.js

@@ -0,0 +1,15 @@
+import { EnvSecurityError } from "./errors.js";
+
+export const checkSecurity = (env) => {
+    const dangerousKeys = [
+        '__PROTO__',
+        'CONSTRUCTOR',
+        'PROTOTYPE'
+    ];
+
+    for (const key of dangerousKeys) {
+        if (key.toUpperCase() in env || key.toLowerCase() in env) {
+            throw new EnvSecurityError(`Potentially dangerous environment variable detected: ${key}`)
+        }
+    }
+};

package/src/types.js

@@ -0,0 +1,26 @@
+export const parseType = (value, type) => {
+    if (value === undefined || value === null) {
+        return value;
+    }
+
+    if (type === 'string') {
+        return String(value);
+    }
+
+    if (type === 'number') {
+        const num = Number(value)
+        if (Number.isNaN(num)) {
+            throw new Error('Must be a valid number.')
+        }
+        return num;
+    }
+
+    if (type === 'boolean') {
+        const normalized = String(value).trim().toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+        if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+        throw new Error('Must be a boolean (true/false) | (1/0) | (yes/no)')
+    }
+
+    throw new Error(`Unknown type: ${type}`)
+};

package/src/validator.js

@@ -0,0 +1,45 @@
+import { EnvValidationError } from "./errors.js";
+import { parseType } from "./types.js";
+
+export const validateEnv = (schema, sourceEnv = process.env) => {
+    const validated = {};
+    const errors = [];
+
+    for (const [key, rules] of Object.entries(schema)) {
+        let rawValue = sourceEnv[key];
+
+        if (rawValue === undefined && rules.default !== undefined) {
+            rawValue = rules.default;
+        }
+
+        if (rules.required && (rawValue === undefined || rawValue === '')) {
+            errors.push(new EnvValidationError(`Missing required environment variable: ${key}`, key));
+            continue;
+        }
+
+        if (rawValue === undefined) {
+            continue;
+        }
+
+        try {
+            let parsedValue = rawValue;
+            if (rules.type) {
+                parsedValue = parseType(rawValue, rules.type);
+            }
+
+            if (rules.allowedValues && !rules.allowedValues.includes(parsedValue)) {
+                throw new Error(`Must be one of: ${rules.allowedValues.join(', ')}`);                
+            }
+            validated[key] = parsedValue;
+        } catch (err) {
+            errors.push(new EnvValidationError(`Invalid value for ${key}: ${err.message}`, key));
+        }
+    }
+
+    if (errors.length > 0) {
+        const errorMessage = errors.map(e => `-${e.message}`).join('\n');
+        throw new EnvValidationError(`Environment validation failed:\n${errorMessage}`);
+    }
+    
+    return validated;
+};

package/tests/index.test.js

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { validateEnv } from '../src/validator.js';
+import { checkSecurity } from '../src/security.js';
+
+test('Validator: Detects missing required variables', () => {
+    const schema = { PORT: { required: true } };
+    assert.throws(() => validateEnv(schema, {}), /Missing required environment variable/);
+});
+
+test('Validator: Applies default values', () => {
+    const schema = { HOST: { default: 'localhost' } };
+    const validated = validateEnv(schema, {});
+    assert.strictEqual(validated.HOST, 'localhost');
+});
+
+test('Validator: Enforces allowed values', () => {
+    const schema = { NODE_ENV: { allowedValues: ['development', 'production'] } };
+    assert.throws(() => validateEnv(schema, { NODE_ENV: 'testing' }), /Must be one of/);
+});
+
+test('Security: Detects prototype pollution keys', () => {
+    assert.throws(() => checkSecurity({ '__PROTO__': 'malicious' }), /potentially dangerous environment variable detected/i);
+});
+
+test('Security: Masks sensitive error messages', () => {
+    const schema = { DB_PASSWORD: { type: 'number' } }; 
+    assert.throws(() => validateEnv(schema, { DB_PASSWORD: 'my_secret_password' }), /value masked for security/);
+});