Secrets Management

Core Rules

1. NEVER hardcode secrets, API keys, OAuth2 client IDs/secrets, tokens, passwords, or credentials in source code
2. ALWAYS store secrets in .env files (or platform-native equivalents like local.properties, .xcconfig)
3. ALWAYS load secrets from environment variables at runtime
4. ALWAYS add .env to .gitignore before first commit
5. ALWAYS provide a .env.example documenting required variables (with empty values)

Workflow

When Writing Code That Uses Secrets

1. Detect the platform/framework from the project files
2. Check if .env and .gitignore are set up — if not, create them
3. Load secrets from environment variables using the platform's standard pattern
4. Never use string literals for secret values — always reference process.env.*, os.getenv(), etc.
5. Add the variable name to .env.example with an empty value and a descriptive comment
6. Run the scan script to verify no secrets leaked: python3 scripts/scan_secrets.py .

When Setting Up a New Project

1. Create .env with required variables
2. Create .env.example mirroring .env structure with empty values (use env-example-template as a starting point)
3. Add secret-related entries to .gitignore (use gitignore-secrets as reference)
4. Install the .env loading library for the platform
5. Add loading code at the application entry point

When Reviewing Code

Run python3 scripts/scan_secrets.py <project-directory> to detect:

• Hardcoded API keys, tokens, and passwords
• OAuth2 client secrets in source
• AWS keys, Google API keys, Stripe keys, GitHub tokens
• Embedded private keys
• Connection strings with credentials
• Missing .gitignore entries for .env
• Missing .env.example

Quick Reference by Platform

For platform-specific .env loading patterns (install, load, access, framework variants), see references/platforms.md. Covers:

• JavaScript/TypeScript: Node.js, Next.js, Vite, React, Nuxt, Remix, Express, NestJS
• Python: Django, Flask, FastAPI
• Ruby: Rails
• Go: godotenv
• Java/Kotlin: Spring Boot
• PHP: Laravel
• Rust: dotenvy
• Swift/iOS: Xcode .xcconfig, Vapor
• Android/Kotlin: local.properties + BuildConfig
• Flutter/Dart: flutter_dotenv
• C#/.NET: DotNetEnv, User Secrets
• Docker: --env-file, docker-compose env_file
• CI/CD: GitHub Actions, GitLab CI, Vercel, Netlify, AWS, GCP, Azure

Anti-Patterns to Block

Never generate code like:

# BAD - hardcoded secrets
api_key = "sk-1234567890abcdef"
client_secret = "my-oauth-secret"
DATABASE_URL = "postgres://user:password@host/db"
const token = "ghp_xxxxxxxxxxxxxxxxxxxx";

Always generate code like:

# GOOD - loaded from environment
api_key = os.getenv("API_KEY")
const token = process.env.GITHUB_TOKEN;

Mobile Platform Notes

• iOS: Use .xcconfig files (gitignored) referenced from Xcode build settings — not .env at runtime
• Android: Use local.properties (gitignored by default) injected via buildConfigField — not .env at runtime
• Flutter: flutter_dotenv bundles .env into the app binary. For truly sensitive secrets, use a backend proxy instead of embedding in the mobile app