.env.example

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# RoboLearn Auth Server - Environment Configuration
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# Copy this file to `.env.local` and configure with your values.
# See docs/environment-variables.md for complete reference.
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔑 Core Authentication Settings (REQUIRED)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Database connection string (PostgreSQL)
# Get free database: https://neon.tech
DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=require

# Secret key for JWT signing and encryption (MUST be 32+ characters)
# Generate: openssl rand -base64 32
# IMPORTANT: Use different secrets for dev/production
BETTER_AUTH_SECRET=your-secret-key-minimum-32-characters-long

# Auth server URL (backend endpoint)
# Development: http://localhost:3001
# Production: https://auth.yourdomain.com
BETTER_AUTH_URL=http://localhost:3001

# Environment mode
NODE_ENV=development

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🌐 CORS & Client Configuration (REQUIRED)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Allowed origins for CORS (comma-separated, no spaces)
# Include all domains that will authenticate through this server
# Example: http://localhost:3000,https://app.example.com,https://admin.example.com
ALLOWED_ORIGINS=http://localhost:3000,https://your-production-domain.com

# Auth server URL (client-side, publicly accessible)
# MUST match BETTER_AUTH_URL (duplicated for Next.js client-side access)
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3001

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🎨 Branding & White-Label Configuration (OPTIONAL)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Customize the auth server UI with your brand
# All branding variables are optional - defaults shown below

# Application name (shown in UI headers and page titles)
NEXT_PUBLIC_APP_NAME=Panaversity SSO

# Application description (shown in UI subtitles)
NEXT_PUBLIC_APP_DESCRIPTION=Secure Single Sign-On

# Organization name (shown in footers, emails, security messages)
NEXT_PUBLIC_ORG_NAME=Panaversity

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔗 Continue URL (OPTIONAL)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Where users go after authentication (used for "Continue to Application" button)
# This is a manual fallback link, NOT used for OAuth redirect security
# Example: https://app.yourdomain.com
NEXT_PUBLIC_CONTINUE_URL=http://localhost:3000

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📧 Email Configuration (OPTIONAL - Choose ONE provider)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Email is used for verification, password reset, and notifications
# If omitted, email features will be disabled

# ─────────────────────────────────────────────────────────────────────
# Option 1: SMTP (Gmail, Custom SMTP servers)
# ─────────────────────────────────────────────────────────────────────
# For Gmail:
#   1. Enable 2FA: Google Account > Security > 2-Step Verification
#   2. Create App Password: Security > App passwords > Mail
#   3. Use the 16-character password below

# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USER=your@gmail.com
# SMTP_PASS=your-16-char-app-password
# SMTP_SECURE=false
# EMAIL_FROM=your@gmail.com

# ─────────────────────────────────────────────────────────────────────
# Option 2: Resend (Modern transactional email API)
# ─────────────────────────────────────────────────────────────────────
# Get API key: https://resend.com/api-keys
# Free tier: 100 emails/day

# RESEND_API_KEY=re_xxxxxxxxx
# RESEND_FROM_EMAIL=onboarding@resend.dev

# ─────────────────────────────────────────────────────────────────────
# Priority: If both are configured, SMTP is used first
# ─────────────────────────────────────────────────────────────────────

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ⚡ Redis Rate Limiting (OPTIONAL - Multi-Instance Deployments)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Redis is used for distributed rate limiting across multiple server instances
# If omitted, rate limiting uses in-memory storage (single instance only)
#
# When to use:
#   ✅ Multiple auth-server instances (Cloud Run, Kubernetes auto-scaling)
#   ✅ Horizontal scaling with load balancer
#   ❌ Single instance deployment (memory storage is sufficient)
#
# Recommended Provider: Upstash (serverless Redis with free tier)
#   1. Sign up: https://upstash.com/
#   2. Create Redis database (Global preferred for low latency)
#   3. Copy REST API credentials below
#   4. Free tier: 10,000 commands/day (sufficient for most use cases)

# Upstash Redis REST API endpoint
# Example: https://worthy-condor-12345.upstash.io
# REDIS_URL=

# Upstash Redis REST API token
# Example: AYasASQgxxx...
# REDIS_TOKEN=

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📋 Audit Logging (OPTIONAL - Enterprise/Compliance)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Audit logging tracks security-critical events for compliance (SOC2, ISO 27001, GDPR)
# Different from error monitoring (Sentry) - audit logs are for investigations
#
# When to enable:
#   ✅ Enterprise B2B customers (compliance requirement)
#   ✅ SOC2, ISO 27001, HIPAA, GDPR compliance needed
#   ✅ Security investigations and forensics required
#   ❌ Early-stage products (adds DB load)
#   ❌ Consumer apps without compliance requirements
#
# Expected Database Load:
#   100 users:     ~50-100 inserts/day
#   1,000 users:   ~500-700 inserts/day
#   10,000 users:  ~5,000-7,000 inserts/day
#   20,000 users:  ~10,000-15,000 inserts/day
#
# Events logged (5 critical actions only):
#   - User registration (user.created)
#   - Login events (session.created)
#   - Role changes (role.updated)
#   - Organization membership changes (member.added, member.removed)
#   - Failed login attempts (captured by rate limiting)
#
# Note: This is separate from Sentry (error monitoring)
#   - Sentry: Track exceptions, crashes, performance issues
#   - Audit Logs: Track user actions for compliance and investigations
#   - Both should be used together in production
#
# Enable audit logging (set to "true" to enable)
# ENABLE_AUDIT_LOGGING=false

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔐 OAuth Client Management
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OAuth clients are managed via Admin UI at /admin/clients
# No environment variables needed for client configuration!
#
# To manage OAuth redirect URLs:
#   1. Seed clients: pnpm run seed:prod
#   2. Edit via Admin UI: http://localhost:3001/admin/clients
#   3. Add/remove redirect URLs as needed (great for testing!)
#
# See README.md for complete OAuth setup instructions
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔒 Security Best Practices
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ✅ DO:
#   - Use different BETTER_AUTH_SECRET for dev/staging/production
#   - Rotate secrets periodically (every 90 days recommended)
#   - Use HTTPS in production (BETTER_AUTH_URL, NEXT_PUBLIC_BETTER_AUTH_URL)
#   - Restrict ALLOWED_ORIGINS to known domains only
#   - Keep .env.local in .gitignore (never commit secrets!)
#
# ❌ DON'T:
#   - Share secrets between environments
#   - Commit .env.local to version control
#   - Use weak or short secrets (<32 characters)
#   - Allow wildcard CORS origins in production
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📚 Additional Resources
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# - Full Documentation: docs/environment-variables.md
# - Setup Guide: README.md
# - OAuth Integration: docs/pkce-flow.md
# - Troubleshooting: docs/troubleshooting.md
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━