secrets

# 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](assets/env-example-template.txt) as a starting point)
3. Add secret-related entries to `.gitignore` (use [gitignore-secrets](assets/gitignore-secrets.txt) 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](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