Audit Env VariablesSAFE

Professional slash commands for Claude Code that provide structured workflows for software development tasks including code review, feature creation, security auditing, and architectural analysis.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: audit-env-variables
description: Analyze environment variables in JavaScript/TypeScript projects. Identifies unused variables, infers permission scopes, detects specific services (Stripe, AWS, Supabase), and documents code paths. Includes optional cleanup of unused variables with regression detection. Use when auditing .env files, reviewing security, or documenting project configuration.
argument-hint: "[output-path] [--cleanup]"
allowed-tools: [Read, Grep, Glob, Bash, Write, Edit, AskUserQuestion]
---

<objective>
Perform a comprehensive audit of environment variables in a JS/TS project:

1. **Discovery** - Find all env files and code references
2. **Usage Analysis** - Identify which variables are used vs unused
3. **Service Detection** - Recognize services (Stripe, AWS, Supabase, etc.) and their permission implications
4. **Code Path Mapping** - Document where each variable is used in the codebase
5. **Report Generation** - Output a structured markdown document
6. **Cleanup** (optional) - Safely remove unused variables with user confirmation
7. **Regression Prevention** - Validate no regressions via build/test validation with automatic rollback
</objective>

<quick_start>
**Audit only (default):**
1. Scan for `.env*` files in project root
2. Grep codebase for `process.env.`, `import.meta.env.`, and destructured env patterns
3. Cross-reference declared vs used variables
4. Identify services by naming patterns and categorize permissions
5. Generate markdown report using the template

**With cleanup (`--cleanup` flag):**
6. Check for dynamic access patterns that might hide usage
7. Present unused variables and get user confirmation
8. Create backups, remove confirmed variables
9. Run build/tests to detect regressions
10. Auto-rollback if regressions detected
</quick_start>

<process>
## Step 1: Discover Environment Files

Find all env-related files:
```bash
find . -maxdepth 2 -name ".env*" -o -name "env.d.ts" | grep -v node_modules
```

Common files:
- `.env` - Local development
- `.env.local` - Local overrides
- `.env.development` / `.env.production` - Environment-specific
- `.env.example` - Template for required variables

## Step 2: Extract Declared Variables

Parse each env file for variable declarations:
```
Grep pattern: ^[A-Z][A-Z0-9_]+=
```

Build a list of all declared variables with their source file.

## Step 3: Find Code References

Search for environment variable usage patterns:

**Direct access:**
```
process.env.VARIABLE_NAME
import.meta.env.VARIABLE_NAME
process.env["VARIABLE_NAME"]
```

**Destructured patterns:**
```javascript
const { API_KEY, DATABASE_URL } = process.env
```

**Framework-specific:**
```javascript
// Next.js public vars
NEXT_PUBLIC_*

// Vite
VITE_*
```

Use Grep tool with patterns:
```
process\.env\.([A-Z][A-Z0-9_]+)
import\.meta\.env\.([A-Z][A-Z0-9_]+)
```

## Step 4: Cross-Reference Usage

For each declared variable:
- **Used**: Found in code references
- **Unused**: Declared but no code references found
- **Undeclared**: Referenced in code but not in any env file

Flag potential issues:
- Unused variables (cleanup candidates)
- Undeclared variables (missing from .env.example)
- Variables only in .env but not .env.example (documentation gap)

## Step 5: Detect Services and Infer Permissions

Match variable names against known service patterns. See references/service-patterns.md for the complete list.

**Categories:**
- **Database** - Connection strings, credentials
- **Authentication** - JWT secrets, OAuth credentials
- **Payment** - Stripe, payment processor keys
- **Cloud Services** - AWS, GCP, Azure credentials
- **Third-party APIs** - Various service integrations
- **Feature Flags** - Toggle configurations
- **Application Config** - URLs, ports, modes

**Permission levels:**
- **Critical** - Full account access, billing, admin operations
- **High** - Read/write access to user data
- **Medium** - Limited API access, specific operations
- **Low** - Public keys, non-sensitive configuration

## Step 6: Map Code Paths

For each used variable, document:
- File path where it's used
- Function/component context
- Purpose (inferred from surrounding code)

Example:
```
STRIPE_SECRET_KEY
├── src/lib/stripe.ts:15 - Stripe client initialization
├── src/api/webhooks/stripe.ts:8 - Webhook signature verification
└── src/api/checkout/route.ts:23 - Create checkout session
```

## Step 7: Generate Report

Use the template in templates/env-audit-report.md to generate the final document.

Output to: `ENV_AUDIT.md` in project root (or user-specified location)

## Step 8: Cleanup Unused Variables (Optional)

**Trigger:** User passes `--cleanup` flag or explicitly requests cleanup after reviewing the audit report.

### 8.1 Present Cleanup Candidates

Display unused variables with context:
```
UNUSED VARIABLES (candidates for removal):

1. OLD_API_KEY (.env, .env.local)
   - Last modified: [file date]
   - No code references found

2. DEPRECATED_SERVICE_URL (.env)
   - Last modified: [file date]
   - No code references found
```

### 8.2 Dynamic Access Check

Before confirming removal, search for dynamic access patterns that grep may have missed:

```javascript
// These patterns indicate variables might be used dynamically:
process.env[variableName]        // Dynamic key access
process.env[`${prefix}_KEY`]     // Template literal access
Object.keys(process.env)         // Iteration over all env vars
{ ...process.env }               // Spread operator
```

Use Grep with patterns:
```
process\.env\[
Object\.keys\(process\.env\)
Object\.entries\(process\.env\)
\.\.\.process\.env
```

**If dynamic access patterns found:** Flag affected variables for manual review and warn user.

### 8.3 User Confirmation

Use AskUserQuestion to confirm each removal:

```
The following variables appear unused. Select which to remove:

[ ] OLD_API_KEY - Remove from .env, .env.local
[ ] DEPRECATED_SERVICE_URL - Remove from .env
[ ] Skip cleanup

⚠️ Variables will be backed up before rem

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

| `SUPABASE_SERVICE_ROLE_KEY` | Supabase | Critical | Bypasses RLS, full access |

Gates applied: no_behavioural_pass, no_license.