@claude-agent/envcheck 1.2.0 → 1.4.0

package/README.md

@@ -233,6 +233,111 @@ curl -o .git/hooks/pre-commit https://raw.githubusercontent.com/claude-agent-too
 chmod +x .git/hooks/pre-commit
 ```
 
+## Type Validation
+
+envcheck supports **static type validation** - validate variable formats without running your app.
+
+### Using Type Hints in .env.example
+
+Add type hints as comments above variables:
+
+```bash
+# type: url
+DATABASE_URL=postgres://localhost/mydb
+
+# @type port
+PORT=3000
+
+# type: boolean
+DEBUG=false
+
+# type: email
+ADMIN_EMAIL=admin@example.com
+```
+
+### Supported Types
+
+| Type | Description | Examples |
+|------|-------------|----------|
+| `url` | Valid URL | `https://example.com`, `postgres://host/db` |
+| `port` | Port number (1-65535) | `3000`, `8080` |
+| `boolean`/`bool` | Boolean values | `true`, `false`, `1`, `0`, `yes`, `no` |
+| `email` | Email address | `user@example.com` |
+| `number` | Any number | `42`, `3.14`, `-10` |
+| `integer`/`int` | Whole numbers | `42`, `-10` |
+| `json` | Valid JSON | `{"key":"value"}`, `[1,2,3]` |
+| `uuid` | UUID format | `550e8400-e29b-41d4-a716-446655440000` |
+| `string`/`str` | Any string (no validation) | anything |
+
+## Secret Detection
+
+envcheck can warn you if your `.env` file contains values that look like real secrets:
+
+```javascript
+const result = check('.env', {
+  examplePath: '.env.example',
+  detectSecrets: true  // Warns about potential secrets
+});
+```
+
+### Detected Secret Patterns
+
+- AWS Access Keys (`AKIA...`)
+- GitHub Tokens (`ghp_...`, `gho_...`, etc.)
+- Stripe Keys (`sk_live_...`, `rk_live_...`)
+- Private Keys (`-----BEGIN PRIVATE KEY-----`)
+- Slack Tokens (`xox...`)
+- Twilio Credentials
+- SendGrid API Keys
+- Google API Keys
+- High-entropy hex strings (with sensitive key names)
+
+### Placeholder Detection
+
+envcheck won't warn about obvious placeholders like:
+- `your-api-key`, `my-secret`
+- `changeme`, `placeholder`
+- `xxx`, `...`
+- `example`, `test`, `dummy`
+
+### API Usage with Secrets
+
+```javascript
+const { check, validate, detectSecret } = require('@claude-agent/envcheck');
+
+// Enable secret detection
+const result = check('.env', {
+  examplePath: '.env.example',
+  detectSecrets: true  // Warns about potential secrets
+});
+
+// Check a single value
+const secret = detectSecret('API_KEY', 'sk_live_abc123...');
+if (secret) {
+  console.log(`Warning: ${secret.description} detected`);
+}
+```
+
+### API Usage with Types
+
+```javascript
+const { check, validate } = require('@claude-agent/envcheck');
+
+// Explicit type validation
+const result = validate('.env', {
+  types: {
+    DATABASE_URL: 'url',
+    PORT: 'port',
+    DEBUG: 'boolean'
+  }
+});
+
+// Types from example file are used automatically
+const result2 = check('.env', {
+  examplePath: '.env.example'  // Type hints in example are used
+});
+```
+
 ## .env File Format
 
 Supports standard .env syntax:
@@ -252,7 +357,7 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 - **Auto-detection** - Finds .env.example automatically
 - **CI-friendly** - Exit codes and JSON output
 - **Comprehensive** - Parse, validate, compare, generate
-- **Well-tested** - 46 tests covering edge cases
+- **Well-tested** - 72 tests covering edge cases
 
 ## vs. dotenv-safe / envalid
 
@@ -263,10 +368,11 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 | **Static validation** | ✅ | ❌ | ❌ |
 | **CI/CD integration** | ✅ GitHub Action | ❌ | ❌ |
 | **Pre-commit hook** | ✅ | ❌ | ❌ |
-| Type validation | ❌ | ❌ | ✅ |
+| Type validation | ✅ (static) | ❌ | ✅ (runtime) |
+| **Secret detection** | ✅ | ❌ | ❌ |
 | Zero dependencies | ✅ | ❌ | ❌ |
 
-**Key difference:** envcheck validates *before* deployment (shift-left), while dotenv-safe and envalid validate at runtime when your app starts. Catch missing env vars in CI, not in production.
+**Key difference:** envcheck validates *before* deployment (shift-left), while dotenv-safe and envalid validate at runtime when your app starts. Catch missing env vars and type errors in CI, not in production.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Validate .env files, compare with .env.example, find missing or empty variables",
   "main": "src/index.js",
   "bin": {
@@ -20,7 +20,9 @@
     "github-action",
     "ci-cd",
     "pre-commit",
-    "git-hooks"
+    "git-hooks",
+    "secrets",
+    "security"
   ],
   "author": "Claude Agent <claude-agent@agentmail.to>",
   "license": "MIT",

package/src/index.js

@@ -3,6 +3,192 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Type validators for environment variables
+ */
+const typeValidators = {
+  url: (value) => {
+    if (!value) return { valid: true };
+    try {
+      new URL(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, message: 'must be a valid URL' };
+    }
+  },
+
+  port: (value) => {
+    if (!value) return { valid: true };
+    const num = parseInt(value, 10);
+    if (isNaN(num) || num < 1 || num > 65535 || String(num) !== value) {
+      return { valid: false, message: 'must be a valid port number (1-65535)' };
+    }
+    return { valid: true };
+  },
+
+  boolean: (value) => {
+    if (!value) return { valid: true };
+    const lower = value.toLowerCase();
+    const valid = ['true', 'false', '1', '0', 'yes', 'no', 'on', 'off'].includes(lower);
+    if (!valid) {
+      return { valid: false, message: 'must be a boolean (true/false/1/0/yes/no)' };
+    }
+    return { valid: true };
+  },
+  bool: (value) => typeValidators.boolean(value),
+
+  email: (value) => {
+    if (!value) return { valid: true };
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+      return { valid: false, message: 'must be a valid email address' };
+    }
+    return { valid: true };
+  },
+
+  number: (value) => {
+    if (!value) return { valid: true };
+    if (isNaN(parseFloat(value))) {
+      return { valid: false, message: 'must be a number' };
+    }
+    return { valid: true };
+  },
+
+  integer: (value) => {
+    if (!value) return { valid: true };
+    const num = parseInt(value, 10);
+    if (isNaN(num) || String(num) !== value) {
+      return { valid: false, message: 'must be an integer' };
+    }
+    return { valid: true };
+  },
+  int: (value) => typeValidators.integer(value),
+
+  string: () => ({ valid: true }),
+  str: () => ({ valid: true }),
+
+  json: (value) => {
+    if (!value) return { valid: true };
+    try {
+      JSON.parse(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, message: 'must be valid JSON' };
+    }
+  },
+
+  uuid: (value) => {
+    if (!value) return { valid: true };
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(value)) {
+      return { valid: false, message: 'must be a valid UUID' };
+    }
+    return { valid: true };
+  }
+};
+
+/**
+ * Secret detection patterns
+ * Each pattern has: regex, description, and optional keyPattern (for key-specific checks)
+ */
+const secretPatterns = [
+  // AWS
+  { regex: /^AKIA[0-9A-Z]{16}$/, description: 'AWS Access Key ID' },
+  { regex: /^[A-Za-z0-9/+=]{40}$/, description: 'AWS Secret Access Key', keyPattern: /aws.*secret|secret.*key/i },
+
+  // Private keys
+  { regex: /-----BEGIN (?:RSA |DSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/, description: 'Private key' },
+  { regex: /-----BEGIN CERTIFICATE-----/, description: 'Certificate' },
+
+  // GitHub
+  { regex: /^ghp_[a-zA-Z0-9]{36}$/, description: 'GitHub Personal Access Token' },
+  { regex: /^gho_[a-zA-Z0-9]{36}$/, description: 'GitHub OAuth Access Token' },
+  { regex: /^ghu_[a-zA-Z0-9]{36}$/, description: 'GitHub User-to-Server Token' },
+  { regex: /^ghs_[a-zA-Z0-9]{36}$/, description: 'GitHub Server-to-Server Token' },
+  { regex: /^ghr_[a-zA-Z0-9]{36}$/, description: 'GitHub Refresh Token' },
+
+  // Slack
+  { regex: /^xox[baprs]-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24}$/, description: 'Slack Token' },
+
+  // Stripe
+  { regex: /^sk_live_[a-zA-Z0-9]{24,}$/, description: 'Stripe Live Secret Key' },
+  { regex: /^rk_live_[a-zA-Z0-9]{24,}$/, description: 'Stripe Live Restricted Key' },
+
+  // Twilio
+  { regex: /^AC[a-f0-9]{32}$/, description: 'Twilio Account SID' },
+  { regex: /^SK[a-f0-9]{32}$/, description: 'Twilio API Key' },
+
+  // SendGrid
+  { regex: /^SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}$/, description: 'SendGrid API Key' },
+
+  // Google
+  { regex: /^AIza[0-9A-Za-z_-]{35}$/, description: 'Google API Key' },
+
+  // Generic high-entropy (likely real secrets)
+  { regex: /^[a-f0-9]{32}$/, description: 'Hex string (32 chars)', keyPattern: /api.*key|secret|token|password/i },
+  { regex: /^[a-f0-9]{64}$/, description: 'Hex string (64 chars)', keyPattern: /api.*key|secret|token|password/i },
+];
+
+/**
+ * Placeholder patterns that are NOT secrets
+ */
+const placeholderPatterns = [
+  /^your[-_]?/i,
+  /^my[-_]?/i,
+  /^xxx+$/i,
+  /^placeholder/i,
+  /^example/i,
+  /^test[-_]?/i,
+  /^dummy/i,
+  /^fake/i,
+  /^sample/i,
+  /^changeme/i,
+  /^replace[-_]?/i,
+  /^insert[-_]?/i,
+  /^todo/i,
+  /^\*+$/,
+  /^\.\.\.$/,
+];
+
+/**
+ * Check if a value looks like a placeholder
+ * @param {string} value - Value to check
+ * @returns {boolean} True if it looks like a placeholder
+ */
+function isPlaceholder(value) {
+  if (!value || value.length < 3) return true;
+  return placeholderPatterns.some(pattern => pattern.test(value));
+}
+
+/**
+ * Detect potential secrets in environment variables
+ * @param {string} key - Variable name
+ * @param {string} value - Variable value
+ * @returns {Object|null} Detection result or null if no secret detected
+ */
+function detectSecret(key, value) {
+  if (!value || isPlaceholder(value)) {
+    return null;
+  }
+
+  for (const pattern of secretPatterns) {
+    // If pattern has keyPattern, only check if key matches
+    if (pattern.keyPattern && !pattern.keyPattern.test(key)) {
+      continue;
+    }
+
+    if (pattern.regex.test(value)) {
+      return {
+        detected: true,
+        description: pattern.description,
+        message: `may contain a real ${pattern.description}`
+      };
+    }
+  }
+
+  return null;
+}
+
 /**
  * Parse a .env file into an object
  * @param {string} content - File content
@@ -13,18 +199,30 @@ function parseEnv(content) {
     variables: {},
     errors: [],
     warnings: [],
-    lineInfo: {}
+    lineInfo: {},
+    typeHints: {}  // NEW: Store type hints from comments
   };
 
   const lines = content.split('\n');
+  let pendingTypeHint = null;
 
   for (let i = 0; i < lines.length; i++) {
     const lineNum = i + 1;
     const line = lines[i];
     const trimmed = line.trim();
 
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) {
+    // Check for type hint in comments: # type: url OR # @type url
+    if (trimmed.startsWith('#')) {
+      const typeMatch = trimmed.match(/^#\s*(?:type:|@type)\s*(\w+)/i);
+      if (typeMatch) {
+        pendingTypeHint = typeMatch[1].toLowerCase();
+      }
+      continue;
+    }
+
+    // Skip empty lines
+    if (!trimmed) {
+      pendingTypeHint = null;
       continue;
     }
 
@@ -74,6 +272,12 @@ function parseEnv(content) {
 
     result.variables[key] = value;
     result.lineInfo[key] = lineNum;
+
+    // Store type hint if present
+    if (pendingTypeHint) {
+      result.typeHints[key] = pendingTypeHint;
+      pendingTypeHint = null;
+    }
   }
 
   return result;
@@ -129,7 +333,8 @@ function readEnvFile(filePath) {
       variables: {},
       errors: [{ message: `File not found: ${absolutePath}` }],
       warnings: [],
-      lineInfo: {}
+      lineInfo: {},
+      typeHints: {}
     };
   }
 
@@ -202,6 +407,20 @@ function compare(envPath, examplePath) {
   return result;
 }
 
+/**
+ * Validate a value against a type
+ * @param {string} value - Value to validate
+ * @param {string} type - Type name
+ * @returns {Object} Validation result {valid, message}
+ */
+function validateType(value, type) {
+  const validator = typeValidators[type.toLowerCase()];
+  if (!validator) {
+    return { valid: true, message: `Unknown type '${type}'` };
+  }
+  return validator(value);
+}
+
 /**
  * Validate an env file
  * @param {string} filePath - Path to .env file
@@ -209,7 +428,7 @@ function compare(envPath, examplePath) {
  * @returns {Object} Validation result
  */
 function validate(filePath, options = {}) {
-  const { required = [], noEmpty = false } = options;
+  const { required = [], noEmpty = false, types = {}, validateTypes = false, detectSecrets = false } = options;
 
   const env = readEnvFile(filePath);
 
@@ -271,6 +490,38 @@ function validate(filePath, options = {}) {
     }
   }
 
+  // Type validation (from options.types or env.typeHints)
+  if (validateTypes || Object.keys(types).length > 0) {
+    const allTypes = { ...env.typeHints, ...types }; // options.types override hints
+    for (const [key, typeName] of Object.entries(allTypes)) {
+      if (key in env.variables && env.variables[key] !== '') {
+        const typeResult = validateType(env.variables[key], typeName);
+        if (!typeResult.valid) {
+          result.valid = false;
+          result.issues.push({
+            type: 'error',
+            line: env.lineInfo[key],
+            message: `Variable '${key}' ${typeResult.message} (got: ${env.variables[key]})`
+          });
+        }
+      }
+    }
+  }
+
+  // Secret detection
+  if (detectSecrets) {
+    for (const [key, value] of Object.entries(env.variables)) {
+      const secretResult = detectSecret(key, value);
+      if (secretResult) {
+        result.issues.push({
+          type: 'warning',
+          line: env.lineInfo[key],
+          message: `Variable '${key}' ${secretResult.message}`
+        });
+      }
+    }
+  }
+
   // Add warnings
   for (const warning of env.warnings) {
     result.issues.push({
@@ -295,7 +546,10 @@ function check(envPath, options = {}) {
     required = [],
     noEmpty = false,
     noExtra = false,
-    strict = false
+    strict = false,
+    types = {},
+    validateTypes = false,
+    detectSecrets = false
   } = options;
 
   const result = {
@@ -307,8 +561,26 @@ function check(envPath, options = {}) {
     }
   };
 
-  // First validate the env file
-  const validation = validate(envPath, { required, noEmpty });
+  // Get type hints from example file if provided
+  let exampleTypeHints = {};
+  if (examplePath) {
+    const example = readEnvFile(examplePath);
+    if (example.exists) {
+      exampleTypeHints = example.typeHints || {};
+    }
+  }
+
+  // Merge type hints: example hints < explicit types
+  const mergedTypes = { ...exampleTypeHints, ...types };
+
+  // First validate the env file (including type validation and secret detection)
+  const validation = validate(envPath, {
+    required,
+    noEmpty,
+    types: mergedTypes,
+    validateTypes: validateTypes || Object.keys(mergedTypes).length > 0,
+    detectSecrets
+  });
 
   if (!validation.valid) {
     result.valid = false;
@@ -417,6 +689,11 @@ module.exports = {
   readEnvFile,
   compare,
   validate,
+  validateType,
+  typeValidators,
+  detectSecret,
+  secretPatterns,
+  isPlaceholder,
   check,
   generate,
   list,