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