@anhuijie/envguard 1.0.0

package/src/core/security.js

@@ -0,0 +1,128 @@
+/**
+ * Sensitive information detection in environment variables
+ */
+
+// Patterns for detecting secrets and sensitive data
+const SECRET_PATTERNS = [
+  {
+    name: 'AWS Access Key',
+    pattern: /AKIA[0-9A-Z]{16}/,
+    severity: 'critical',
+  },
+  {
+    name: 'AWS Secret Key',
+    pattern: /aws(.{0,20})?(secret|key).{0,20}[A-Za-z0-9/+=]{40}/i,
+    severity: 'critical',
+  },
+  {
+    name: 'GitHub Token',
+    pattern: /gh[ps]_[A-Za-z0-9_]{36,}/,
+    severity: 'critical',
+  },
+  {
+    name: 'GitLab Token',
+    pattern: /glpat-[A-Za-z0-9\-]{20}/,
+    severity: 'critical',
+  },
+  {
+    name: 'Slack Token',
+    pattern: /xox[baprs]-[0-9]{10,}-[A-Za-z0-9]+/,
+    severity: 'critical',
+  },
+  {
+    name: 'Stripe Key',
+    pattern: /sk_live_[A-Za-z0-9]{24,}/,
+    severity: 'critical',
+  },
+  {
+    name: 'Private Key',
+    pattern: /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/,
+    severity: 'critical',
+  },
+  {
+    name: 'JWT Secret',
+    pattern: /jwt(.{0,20})?(secret|key).{0,20}[A-Za-z0-9\-._~+/]+=*/i,
+    severity: 'high',
+  },
+  {
+    name: 'Database URL with Password',
+    pattern: /(mysql|postgres|mongodb|redis):\/\/[^\s:]+:[^\s@]+@[^\s]+/i,
+    severity: 'high',
+  },
+  {
+    name: 'Generic API Key',
+    pattern: /(api[_-]?key|apikey|api[_-]?secret)\s*[=:]\s*['"]?[A-Za-z0-9\-._]{20,}['"]?/i,
+    severity: 'high',
+  },
+  {
+    name: 'Generic Password',
+    pattern: /(password|passwd|pwd)\s*[=:]\s*['"]?[^\s'"]{8,}['"]?/i,
+    severity: 'high',
+  },
+  {
+    name: 'Generic Secret',
+    pattern: /(secret|token|auth)\s*[=:]\s*['"]?[A-Za-z0-9\-._]{20,}['"]?/i,
+    severity: 'medium',
+  },
+];
+
+// Keys that are commonly sensitive by name
+const SENSITIVE_KEY_PATTERNS = [
+  /password/i,
+  /passwd/i,
+  /pwd$/i,
+  /secret/i,
+  /token/i,
+  /api[_-]?key/i,
+  /auth/i,
+  /credential/i,
+  /private[_-]?key/i,
+  /access[_-]?key/i,
+];
+
+function scanForSecrets(envObj, options = {}) {
+  const findings = [];
+  const ignoredKeys = new Set(options.ignoreKeys || []);
+  const minSeverity = options.minSeverity || 'medium';
+  const severityOrder = { low: 0, medium: 1, high: 2, critical: 3 };
+
+  for (const [key, value] of Object.entries(envObj)) {
+    if (ignoredKeys.has(key)) continue;
+    if (value === undefined || value === '') continue;
+
+    // Check value against secret patterns
+    for (const { name, pattern, severity } of SECRET_PATTERNS) {
+      if (severityOrder[severity] < severityOrder[minSeverity]) continue;
+
+      if (pattern.test(value)) {
+        findings.push({
+          key,
+          severity,
+          type: name,
+          message: `Potential ${name} detected in variable "${key}"`,
+        });
+        break; // One finding per variable to avoid duplicates
+      }
+    }
+
+    // Check if key name suggests sensitive data
+    const isSensitiveKey = SENSITIVE_KEY_PATTERNS.some((p) => p.test(key));
+    if (isSensitiveKey && !findings.some((f) => f.key === key)) {
+      findings.push({
+        key,
+        severity: 'medium',
+        type: 'Sensitive Key Name',
+        message: `Variable "${key}" appears to contain sensitive data based on its name`,
+      });
+    }
+  }
+
+  return {
+    findings,
+    hasCritical: findings.some((f) => f.severity === 'critical'),
+    hasHigh: findings.some((f) => f.severity === 'high'),
+    total: findings.length,
+  };
+}
+
+module.exports = { scanForSecrets, SECRET_PATTERNS, SENSITIVE_KEY_PATTERNS };

package/src/core/validator.js

@@ -0,0 +1,170 @@
+/**
+ * Environment variable validation engine
+ */
+
+const validators = {
+  string: (value) => typeof value === 'string',
+
+  number: (value, rule) => {
+    const num = Number(value);
+    if (isNaN(num)) return { valid: false, error: `"${value}" is not a valid number` };
+    if (rule.min !== undefined && num < rule.min) {
+      return { valid: false, error: `${num} is less than minimum ${rule.min}` };
+    }
+    if (rule.max !== undefined && num > rule.max) {
+      return { valid: false, error: `${num} exceeds maximum ${rule.max}` };
+    }
+    return { valid: true };
+  },
+
+  boolean: (value) => {
+    const lower = String(value).toLowerCase();
+    if (['true', 'false', '1', '0', 'yes', 'no'].includes(lower)) {
+      return { valid: true };
+    }
+    return { valid: false, error: `"${value}" is not a valid boolean (true/false, 1/0, yes/no)` };
+  },
+
+  url: (value) => {
+    try {
+      new URL(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, error: `"${value}" is not a valid URL` };
+    }
+  },
+
+  email: (value) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(value)
+      ? { valid: true }
+      : { valid: false, error: `"${value}" is not a valid email address` };
+  },
+
+  json: (value) => {
+    try {
+      JSON.parse(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, error: `"${value}" is not valid JSON` };
+    }
+  },
+
+  regex: (value) => {
+    try {
+      new RegExp(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, error: `"${value}" is not a valid regex pattern` };
+    }
+  },
+
+  port: (value) => {
+    const num = Number(value);
+    if (isNaN(num) || !Number.isInteger(num) || num < 0 || num > 65535) {
+      return { valid: false, error: `"${value}" is not a valid port (0-65535)` };
+    }
+    return { valid: true };
+  },
+};
+
+function validateValue(value, rule) {
+  const type = rule.type || 'string';
+  const validator = validators[type];
+
+  if (!validator) {
+    return { valid: false, error: `Unknown type: ${type}` };
+  }
+
+  const result = validator(value, rule);
+
+  // Validator can return boolean or { valid, error }
+  if (typeof result === 'boolean') {
+    return { valid: result, error: result ? undefined : `Value does not match type "${type}"` };
+  }
+  return result;
+}
+
+function validateEnv(envObj, schema) {
+  const results = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    checked: 0,
+  };
+
+  for (const [key, rule] of Object.entries(schema)) {
+    results.checked++;
+    const value = envObj[key];
+
+    // Check required
+    if (value === undefined || value === '') {
+      if (rule.required) {
+        results.valid = false;
+        results.errors.push({
+          key,
+          type: 'missing',
+          message: `Required variable "${key}" is not set`,
+        });
+      } else if (rule.default !== undefined) {
+        // Will use default, just note it
+        results.warnings.push({
+          key,
+          type: 'default_used',
+          message: `Variable "${key}" not set, will use default: ${rule.default}`,
+        });
+      }
+      continue;
+    }
+
+    // Check type
+    const typeResult = validateValue(value, rule);
+    if (!typeResult.valid) {
+      results.valid = false;
+      results.errors.push({
+        key,
+        type: 'type_mismatch',
+        message: `Variable "${key}": ${typeResult.error}`,
+      });
+      continue;
+    }
+
+    // Check enum
+    if (rule.enum && !rule.enum.includes(value)) {
+      results.valid = false;
+      results.errors.push({
+        key,
+        type: 'enum_mismatch',
+        message: `Variable "${key}": value "${value}" is not one of: ${rule.enum.join(', ')}`,
+      });
+      continue;
+    }
+
+    // Check pattern
+    if (rule.pattern) {
+      const regex = new RegExp(rule.pattern);
+      if (!regex.test(value)) {
+        results.valid = false;
+        results.errors.push({
+          key,
+          type: 'pattern_mismatch',
+          message: `Variable "${key}": value does not match pattern /${rule.pattern}/`,
+        });
+        continue;
+      }
+    }
+
+    // Check deprecation
+    if (rule.deprecated) {
+      results.warnings.push({
+        key,
+        type: 'deprecated',
+        message: `Variable "${key}" is deprecated${rule.replacement ? `, use "${rule.replacement}" instead` : ''}`,
+      });
+    }
+  }
+
+  return results;
+}
+
+module.exports = { validateEnv, validateValue, validators };

package/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * EnvGuard — Environment variable & config validation, security scanning, and documentation generator
+ *
+ * Public API for programmatic usage
+ */
+
+const core = require('./core');
+
+module.exports = core;

package/src/utils/file.js

@@ -0,0 +1,102 @@
+/**
+ * File system utilities for finding and loading .env files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ENV_FILE_PATTERNS = [
+  '.env',
+  '.env.local',
+  '.env.development',
+  '.env.staging',
+  '.env.production',
+  '.env.test',
+];
+
+function findEnvFiles(dir, options = {}) {
+  const recursive = options.recursive || false;
+  const maxDepth = options.maxDepth || 3;
+  const envFiles = [];
+
+  function scan(currentDir, depth) {
+    if (depth > maxDepth) return;
+
+    try {
+      const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.name.startsWith('.') && entry.name.endsWith('.env')) {
+          envFiles.push(path.join(currentDir, entry.name));
+        } else if (entry.name === '.env') {
+          envFiles.push(path.join(currentDir, entry.name));
+        } else if (entry.name.startsWith('.env.')) {
+          envFiles.push(path.join(currentDir, entry.name));
+        }
+
+        // Also check for env files without leading dot
+        if (entry.name === 'env' || entry.name.startsWith('env.')) {
+          envFiles.push(path.join(currentDir, entry.name));
+        }
+
+        if (recursive && entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          scan(path.join(currentDir, entry.name), depth + 1);
+        }
+      }
+    } catch {
+      // Permission denied or other FS errors — skip
+    }
+  }
+
+  scan(dir, 0);
+  return [...new Set(envFiles)];
+}
+
+function findConfigFile(dir) {
+  const configNames = [
+    'envguard.config.js',
+    'envguard.config.cjs',
+    '.envguardrc.js',
+    '.envguardrc.cjs',
+  ];
+
+  for (const name of configNames) {
+    const fullPath = path.join(dir, name);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+
+  return null;
+}
+
+function loadEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const vars = {};
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+
+    // Remove surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    vars[key] = value;
+  }
+
+  return vars;
+}
+
+module.exports = { findEnvFiles, findConfigFile, loadEnvFile, ENV_FILE_PATTERNS };

package/src/utils/format.js

@@ -0,0 +1,68 @@
+/**
+ * Output formatting utilities
+ */
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+};
+
+function colorize(text, color) {
+  if (process.env.NO_COLOR) return text;
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+function formatError(error) {
+  return colorize(`✗ ${error.key}: ${error.message}`, 'red');
+}
+
+function formatWarning(warning) {
+  return colorize(`⚠ ${warning.key}: ${warning.message}`, 'yellow');
+}
+
+function formatSuccess(key) {
+  return colorize(`✓ ${key}`, 'green');
+}
+
+function formatFinding(finding) {
+  const severityColors = {
+    critical: 'red',
+    high: 'magenta',
+    medium: 'yellow',
+    low: 'blue',
+  };
+  const color = severityColors[finding.severity] || 'yellow';
+  const label = colorize(`[${finding.severity.toUpperCase()}]`, color);
+  return `${label} ${finding.message}`;
+}
+
+function printHeader(title) {
+  console.log('');
+  console.log(colorize(`  ${'═'.repeat(40)}`, 'cyan'));
+  console.log(colorize(`  ${title}`, 'bold'));
+  console.log(colorize(`  ${'═'.repeat(40)}`, 'cyan'));
+  console.log('');
+}
+
+function printSummary(results) {
+  console.log('');
+  if (results.valid) {
+    console.log(colorize('  ✓ All checks passed!', 'green'));
+  } else {
+    console.log(colorize(`  ✗ ${results.errors.length} error(s) found`, 'red'));
+  }
+  if (results.warnings && results.warnings.length > 0) {
+    console.log(colorize(`  ⚠ ${results.warnings.length} warning(s)`, 'yellow'));
+  }
+  console.log(`  Checked: ${results.checked} variable(s)`);
+  console.log('');
+}
+
+module.exports = { colorize, formatError, formatWarning, formatSuccess, formatFinding, printHeader, printSummary };