@claude-agent/envcheck 1.3.0 → 1.4.0

package/README.md

@@ -269,6 +269,55 @@ ADMIN_EMAIL=admin@example.com
 | `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
@@ -308,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
 
@@ -320,6 +369,7 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 | **CI/CD integration** | ✅ GitHub Action | ❌ | ❌ |
 | **Pre-commit hook** | ✅ | ❌ | ❌ |
 | 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 and type errors in CI, not in production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.3.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

@@ -87,6 +87,108 @@ const typeValidators = {
   }
 };
 
+/**
+ * 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
@@ -326,7 +428,7 @@ function validateType(value, type) {
  * @returns {Object} Validation result
  */
 function validate(filePath, options = {}) {
-  const { required = [], noEmpty = false, types = {}, validateTypes = false } = options;
+  const { required = [], noEmpty = false, types = {}, validateTypes = false, detectSecrets = false } = options;
 
   const env = readEnvFile(filePath);
 
@@ -406,6 +508,20 @@ function validate(filePath, options = {}) {
     }
   }
 
+  // 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({
@@ -432,7 +548,8 @@ function check(envPath, options = {}) {
     noExtra = false,
     strict = false,
     types = {},
-    validateTypes = false
+    validateTypes = false,
+    detectSecrets = false
   } = options;
 
   const result = {
@@ -456,12 +573,13 @@ function check(envPath, options = {}) {
   // Merge type hints: example hints < explicit types
   const mergedTypes = { ...exampleTypeHints, ...types };
 
-  // First validate the env file (including type validation)
+  // 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
+    validateTypes: validateTypes || Object.keys(mergedTypes).length > 0,
+    detectSecrets
   });
 
   if (!validation.valid) {
@@ -573,6 +691,9 @@ module.exports = {
   validate,
   validateType,
   typeValidators,
+  detectSecret,
+  secretPatterns,
+  isPlaceholder,
   check,
   generate,
   list,