env.example

################################################################################
# a11yhood Backend - PRODUCTION ENVIRONMENT CONFIGURATION
# 
# This file configures the backend for production use with Supabase
# 
# SETUP: Copy this file to .env and fill in your production credentials
#        DO NOT commit .env to git - it contains production secrets
# 
# IMPORTANT: The application supports TWO MODES:
#   - TEST MODE (Supabase test project): Use .env.test for local development + automated tests
#   - PRODUCTION MODE (Supabase production project): Use .env for production deployment
#
# Key difference: This file (.env) points at production. The .env.test points at the test project.
# Set ENV_FILE=.env in your shell to use production config
#
# SECURITY: The backend validates configuration on startup to prevent:
#   - TEST_MODE enabled in production (bypasses authentication)
#   - Default SECRET_KEY in production (weak JWT security)
#   - See SECURITY_AUDIT.md for details
################################################################################

# ============================================================================
# ENVIRONMENT (RECOMMENDED)
# ============================================================================
# Set to 'production', 'staging', or 'development'
# This helps the startup validator detect production environments
ENVIRONMENT=production

# ============================================================================
# SUPABASE DATABASE CONFIGURATION (REQUIRED)
# ============================================================================
#
# Production Supabase PostgreSQL Database credentials
# 
# How to get these values:
# 1. Log in to https://supabase.com/dashboard
# 2. Select your PRODUCTION project
# 3. Go to Settings → API
# 4. Copy the values below
#
# CRITICAL: 
# - SUPABASE_KEY must be the SERVICE_ROLE key (full backend access)
# - NOT the anon key (which has limited RLS access)
# - Never share the service_role key publicly
#
SUPABASE_URL=https://your-production-project.supabase.co
SUPABASE_KEY=sb_secret_your_service_role_key_here_keep_secret
SUPABASE_ANON_KEY=sb_publishable_your_anon_key_here

# Optional direct Postgres connection string for migrations/reset scripts.
# Prefer SUPABASE_DB_URL for administrative commands.
# DATABASE_URL is only used by legacy scripts that still accept a generic DB URL.

# ============================================================================
# APPLICATION MODE (TEST vs PRODUCTION)
# ============================================================================
#
# TEST_MODE controls whether the app uses test data or real OAuth
#
# TEST_MODE=true (used in .env.test only):
#   - Uses the Supabase test project
#   - Uses seeded test users (admin, moderator, user)
#   - Disables real GitHub/Ravelry OAuth
#   - For local development and automated tests
#   - File: backend/.env.test
#
# TEST_MODE=false (used in .env for production):
#   - Uses Supabase database (remote, requires credentials)
#   - Uses real GitHub OAuth for authentication
#   - All user data persists to production database
#   - For local production testing or cloud deployment
#   - File: backend/.env (this file)
#
# IMPORTANT: Always verify TEST_MODE matches your intent!
# Setting TEST_MODE=true in .env enables dev-only auth/test behavior against whichever Supabase project is configured
#
TEST_MODE=false

# ---------------------------------------------------------------
# TEST DATA MUTATION GUARD
# These two values must ALL be set correctly before /api/dev/reset,
# seed routes, or any destructive test endpoints will respond.
# This is intentional to prevent accidental data loss.
#
# How to find your Supabase project ref:
#   Go to your Supabase dashboard → Settings → General
#   It looks like: abcdefghijklmnop
#
# NEVER set ALLOW_TEST_DATA_MUTATION=true against a production database.
# ---------------------------------------------------------------
ALLOW_TEST_DATA_MUTATION=false
ALLOWED_TEST_PROJECT_REFS=your-test-project-ref-here

# TEST_SCRAPER_LIMIT is ONLY used when TEST_MODE=true
# When running scrapers in test mode, limit results for faster tests
# Not applicable or used in production mode
# TEST_SCRAPER_LIMIT=5

# ============================================================================
# OAUTH CONFIGURATION (REQUIRED FOR PRODUCTION)
# ============================================================================
#
# GitHub OAuth (REQUIRED - allows users to log in with GitHub)
#
# Setup Steps:
# 1. Go to https://github.com/settings/developers
# 2. Click "New OAuth App"
# 3. Fill in the form:
#    - Application name: a11yhood
#    - Homepage URL: https://a11yhood.com (your domain)
#    - Authorization callback URL: https://a11yhood.com/auth/callback
# 4. Copy Client ID and Client Secret below
# 5. Keep Client Secret private - never share or commit to git
#
# Without GitHub OAuth, users cannot log in and the app cannot function
#
GITHUB_CLIENT_ID=your-production-github-client-id
GITHUB_CLIENT_SECRET=your-production-github-client-secret

# GitHub API Token (OPTIONAL - improves rate limits)
# Create PAT: https://github.com/settings/tokens
# Click "Generate new token (classic)"
# Scopes: public_repo (to read public repo data, not required)
# Token allows:
#   - Without token: 60 requests/hour per IP
#   - With token: 5000 requests/hour per token
# Recommended for production scraping
GITHUB_TOKEN=your-github-personal-access-token

# Vercel Cron secret for scheduled scraper endpoints
# Generate a long random value and keep it private.
CRON_SECRET=your-long-random-cron-secret # generate with something like openssl rand -hex 32

# ============================================================================
# SECURITY CONFIGURATION
# ============================================================================
#
# SECRET_KEY: Used for signing JWT tokens and other cryptographic operations
#
# CRITICAL REQUIREMENTS:
# 1. Must be RANDOM and UNPREDICTABLE
#    - Generate with: python -c "import secrets; print(secrets.token_hex(32))"
# 2. Must be at least 32 characters (recommended: 64+)
# 3. Never reuse the same key across different environments
# 4. Never commit to git (should already be in .gitignore)
# 5. Never use the dev/test key in production
# 6. Rotate periodically (every 90 days recommended)
#
# STARTUP VALIDATION:
#   The backend will REFUSE TO START if:
#   - SECRET_KEY is the default value in production
#   - SECRET_KEY is shorter than 32 characters in production
#
# If compromised:
# 1. Generate new SECRET_KEY immediately
# 2. Update in .env
# 3. Restart backend (takes effect on next request)
# 4. Consider invalidating all active sessions in database
#
# In production, use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
# instead of storing in .env file
#
SECRET_KEY=your-random-production-secret-key-64-characters-minimum



# ============================================================================
# DEPLOYMENT VERIFICATION CHECKLIST
# ============================================================================
#
# Use this checklist to verify your production configuration before deploying:
#
# DATABASE SETUP:
#   [ ] Created Supabase project at https://supabase.com
#   [ ] Applied supabase-schema.sql to the database (SQL Editor)
#   [ ] Copied SUPABASE_URL from Project Settings → API
#   [ ] Copied SUPABASE_KEY (service_role, NOT anon key)
#   [ ] Copied SUPABASE_ANON_KEY (public key for frontend)
#
# GITHUB OAUTH SETUP:
#   [ ] Created GitHub OAuth app: https://github.com/settings/developers
#   [ ] Set Homepage URL to https://a11yhood.com (or your domain)
#   [ ] Set Authorization callback URL to https://a11yhood.com/auth/callback
#   [ ] Copied GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
#   [ ] Created GitHub Personal Access Token (optional but recommended)
#
# CONFIGURATION:
#   [ ] Verified TEST_MODE=false (NOT true)
#   [ ] Verified CORS_ORIGINS is correct (e.g., https://a11yhood.com or localhost:5173)
#   [ ] Generated random SECRET_KEY (python -c "import secrets; print(secrets.token_hex(32))")
#   [ ] Verified .env file is in .gitignore (should already be there)
#   [ ] Did NOT commit .env to git
#
# BEFORE STARTING:
#   [ ] Run: ENV_FILE=.env uv run python -c "from config import settings; print(f'DB: {settings.SUPABASE_URL}')"
#   [ ] Run health check: curl http://localhost:8000/health (after starting backend)
#   [ ] Check database connection: curl http://localhost:8000/api/sources/supported
#   [ ] Test real OAuth: Log in with GitHub in frontend
#   [ ] Verify data persists in Supabase dashboard