.env.example

# Server Configuration
SERVER_ADDR=:8080
BASE_URL=http://localhost:8080

# Environment Mode
# Options: production, development (default)
# In production mode: session cookies require HTTPS, stricter security headers
ENVIRONMENT=development

# Security
JWT_SECRET=your-256-bit-secret-change-in-production
SESSION_SECRET=session-secret-change-in-production

# JWT Signing Algorithm
# Options: HS256 (default, symmetric), RS256 (RSA), ES256 (ECDSA P-256)
# JWT_SIGNING_ALGORITHM=HS256
# JWT_PRIVATE_KEY_PATH=            # Required for RS256/ES256: path to PEM private key
# JWT_KEY_ID=                      # Optional: kid header value (auto-generated from key fingerprint)

# JWT Token Expiration
# JWT_EXPIRATION=10h               # Access token lifetime (default: 10h). Supports Go duration format: 5m, 1h, 10h
# JWT_EXPIRATION_JITTER=30m        # Max random jitter added to access token expiry (default: 30m)
#                                  # Prevents thundering herd when many tokens expire simultaneously
#                                  # Example: JWT_EXPIRATION=8h + JWT_EXPIRATION_JITTER=30m → token lifetime [8h, 8h30m)

# Database
DATABASE_DRIVER=sqlite
DATABASE_DSN=oauth.db

# PostgreSQL Example (uncomment to use):
# For local development/testing only (no TLS):
# DATABASE_DRIVER=postgres
# DATABASE_DSN="host=localhost user=authgate password=secret dbname=authgate port=5432 sslmode=disable"

# For production, enable TLS (example uses sslmode=require; configure certificates as needed):
# DATABASE_DRIVER=postgres
# DATABASE_DSN="host=your-prod-host user=authgate password=change-me dbname=authgate port=5432 sslmode=require"
# DATABASE_DSN="host=db.example.com user=authgate password=change-me dbname=authgate port=5432 sslmode=verify-full sslrootcert=/path/to/root.crt"

# Database Log Level
# GORM log level: "silent", "error", "warn" (default), "info"
# Set to "info" to print all SQL queries (useful for debugging)
# DB_LOG_LEVEL=warn

# Default Admin User
# Set a custom password for the default admin user created on first startup
# If not set, a random 16-character password will be generated and written to authgate-credentials.txt
# DEFAULT_ADMIN_PASSWORD=your-secure-admin-password

# Authentication Mode
# Options: local, http_api
# Default: local
AUTH_MODE=local

# HTTP API Authentication (when AUTH_MODE=http_api)
HTTP_API_URL=https://auth.example.com/api/verify
HTTP_API_TIMEOUT=10s
HTTP_API_INSECURE_SKIP_VERIFY=false

# HTTP API Retry Configuration
# Automatic retry with exponential backoff for failed requests
HTTP_API_MAX_RETRIES=3           # Maximum retry attempts (default: 3, set 0 to disable)
HTTP_API_RETRY_DELAY=1s          # Initial retry delay (default: 1s)
HTTP_API_MAX_RETRY_DELAY=10s     # Maximum retry delay (default: 10s)

# OAuth Configuration
# GitHub OAuth (optional)
GITHUB_OAUTH_ENABLED=false
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URL=http://localhost:8080/auth/callback/github
GITHUB_SCOPES=user:email

# Gitea OAuth (optional)
GITEA_OAUTH_ENABLED=false
GITEA_URL=https://gitea.example.com
GITEA_CLIENT_ID=your_gitea_client_id
GITEA_CLIENT_SECRET=your_gitea_client_secret
GITEA_REDIRECT_URL=http://localhost:8080/auth/callback/gitea
GITEA_SCOPES=read:user

# Microsoft Entra ID (Azure AD) OAuth (optional)
MICROSOFT_OAUTH_ENABLED=false
MICROSOFT_TENANT_ID=common
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
MICROSOFT_REDIRECT_URL=http://localhost:8080/auth/callback/microsoft
MICROSOFT_SCOPES=openid,profile,email,User.Read

# OAuth Settings
OAUTH_AUTO_REGISTER=true         # Allow OAuth to auto-create accounts (default: true)
OAUTH_TIMEOUT=15s                # HTTP client timeout for OAuth requests (default: 15s)
OAUTH_INSECURE_SKIP_VERIFY=false # Skip TLS verification for OAuth (dev/testing only, default: false)

# Rate Limiting
# Protect against brute force attacks and API abuse
ENABLE_RATE_LIMIT=true                  # Enable rate limiting (default: true)
RATE_LIMIT_STORE=memory                 # Store type: "memory" (single instance) or "redis" (multi-pod)
RATE_LIMIT_CLEANUP_INTERVAL=5m          # How often to cleanup old rate limiters (default: 5m)

# Redis Configuration (only used when RATE_LIMIT_STORE=redis)
# For multi-pod deployments, Redis provides shared rate limiting state
REDIS_ADDR=localhost:6379               # Redis server address
REDIS_PASSWORD=                         # Redis password (leave empty for no auth)
REDIS_DB=0                              # Redis database number (default: 0)

# Login endpoint rate limiting
LOGIN_RATE_LIMIT=5                      # Requests per minute for /login (default: 5)
LOGIN_RATE_LIMIT_BURST=2                # Burst size for /login (default: 2, ignored for redis)

# Device authorization code endpoint
DEVICE_CODE_RATE_LIMIT=10               # Requests per minute for /oauth/device/code (default: 10)
DEVICE_CODE_RATE_LIMIT_BURST=3          # Burst size for device code (default: 3, ignored for redis)

# Token exchange endpoint (includes polling)
TOKEN_RATE_LIMIT=20                     # Requests per minute for /oauth/token (default: 20)
TOKEN_RATE_LIMIT_BURST=5                # Burst size for token endpoint (default: 5, ignored for redis)

# Device verification endpoint
DEVICE_VERIFY_RATE_LIMIT=10             # Requests per minute for /device/verify (default: 10)
DEVICE_VERIFY_RATE_LIMIT_BURST=3        # Burst size for device verify (default: 3, ignored for redis)

# Audit Logging
# Comprehensive audit logging for security and compliance
ENABLE_AUDIT_LOGGING=true               # Enable audit logging (default: true)
AUDIT_LOG_RETENTION=2160h               # Retention period: 90 days (default: 90 days = 2160h)
AUDIT_LOG_BUFFER_SIZE=1000              # Async buffer size (default: 1000)
AUDIT_LOG_CLEANUP_INTERVAL=24h          # Cleanup frequency (default: 24h)

# Expired Token / Device Code Cleanup
ENABLE_EXPIRED_TOKEN_CLEANUP=false      # Purge expired tokens and device codes periodically (default: false)
EXPIRED_TOKEN_CLEANUP_INTERVAL=1h      # How often to run the cleanup (default: 1h)

# Prometheus Metrics
# Expose metrics for monitoring with Prometheus (disabled by default)
# METRICS_ENABLED=false                     # Enable /metrics endpoint (default: false)
# METRICS_TOKEN=                            # Bearer token for authentication (optional, leave empty for no auth)
#                                           # Generate with: openssl rand -base64 48
#                                           # Usage: curl -H "Authorization: Bearer <token>" http://localhost:8080/metrics

# Gauge Metrics Update Configuration
# METRICS_GAUGE_UPDATE_ENABLED=true         # Enable gauge metric updates (default: true)
#                                           # In multi-replica deployments, enable on only ONE instance or use max()/avg() aggregation
# METRICS_GAUGE_UPDATE_INTERVAL=5m          # Update interval for gauge metrics (default: 5m, reduced from 30s)
#                                           # Longer intervals reduce database load; recommended: 5m for production

# Metrics Cache Configuration
# Cache database query results to reduce load in multi-instance deployments
# Cache backend: "memory", "redis", or "redis-aside" (default: memory)
# - memory: Single-instance (no external dependencies)
# - redis: Basic Redis caching (2-5 instances)
# - redis-aside: Client-side caching with auto-invalidation (5+ instances)
# METRICS_CACHE_TYPE=memory

# Local cache TTL for redis-aside mode (default: 30s)
# Only applies when METRICS_CACHE_TYPE=redis-aside
# METRICS_CACHE_CLIENT_TTL=30s

# Client-side cache size per connection in MB (default: 32MB)
# Only applies when METRICS_CACHE_TYPE=redis-aside
# Total memory = cache_size × connections (~10 based on GOMAXPROCS)
# Default: 32MB × 10 = ~320MB total memory usage
# METRICS_CACHE_SIZE_PER_CONN=32

# ============================================================
# User Cache Configuration
# ============================================================
# Cache GetUserByID results to reduce DB load under high traffic / DDoS scenarios
# Called on every protected request (RequireAuth + RequireAdmin middlewares)
# Cache backend: "memory", "redis", or "redis-aside" (default: memory)
# - memory: Single-instance, zero external dependencies (default)
# - redis: Multi-instance deployments (2-5 pods), shared cache across pods
# - redis-aside: High-load / multi-pod DDoS protection with client-side caching (5+ pods)
# USER_CACHE_TYPE=memory

# Cache TTL for user objects (default: 5m)
# User data refreshes after this period — balance security vs. DB load
# Shorter (e.g., 1m): Password/role changes take effect faster
# Longer (e.g., 15m): More aggressive DB protection
# USER_CACHE_TTL=5m

# Client-side cache TTL for redis-aside mode only (default: 30s)
# USER_CACHE_CLIENT_TTL=30s

# Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
# Total memory per pod = cache_size × connections (~10 based on GOMAXPROCS) → default ~320MB
# USER_CACHE_SIZE_PER_CONN=32

# ============================================================
# Client Count Cache Settings (pending badge in admin navbar)
# ============================================================
# Cache backend for the pending-client count shown in the admin navbar badge.
# In single-instance deployments "memory" is sufficient.
# In multi-pod deployments use "redis" or "redis-aside" so every pod shares the same
# store — otherwise a mutation on Pod A won't invalidate the stale count on Pod B.
# CLIENT_COUNT_CACHE_TYPE=memory

# Server-side cache lifetime for the pending count (default: 1h)
# Lower values reduce badge staleness in edge cases; mutations always invalidate immediately.
# CLIENT_COUNT_CACHE_TTL=1h

# Client-side cache TTL for redis-aside mode only (default: 10m)
# CLIENT_COUNT_CACHE_CLIENT_TTL=10m

# Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
# CLIENT_COUNT_CACHE_SIZE_PER_CONN=32

# ============================================================
# Client Cache Settings (caches OAuth client lookups by client_id)
# ============================================================
# Cache backend for OAuth client lookups. Every OAuth flow (device code, authorization code,
# token exchange) queries the client record. Caching reduces DB load significantly.
# In single-instance deployments "memory" is sufficient.
# In multi-pod deployments use "redis" or "redis-aside" for shared cache with invalidation.
# CLIENT_CACHE_TYPE=memory

# Server-side cache lifetime for client records (default: 5m)
# Mutations (create, update, delete, approve, reject, secret regeneration) always invalidate immediately.
# CLIENT_CACHE_TTL=5m

# Client-side cache TTL for redis-aside mode only (default: 30s)
# CLIENT_CACHE_CLIENT_TTL=30s

# Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
# CLIENT_CACHE_SIZE_PER_CONN=32

# ============================================================
# Token Cache Settings
# ============================================================
# Cache layer for token verification to reduce DB queries.
# Disabled by default; enable for high-traffic or multi-node deployments.
# TOKEN_CACHE_ENABLED=false

# Cache backend: memory (single instance), redis, or redis-aside (default: memory)
# TOKEN_CACHE_TYPE=memory

# Cache lifetime (default: 10h, matches JWT_EXPIRATION). Token revocation uses explicit cache
# invalidation (Redis DEL + RESP3 push), so this TTL is only a fallback for rare invalidation
# failures. Setting this equal to JWT_EXPIRATION avoids unnecessary DB re-queries.
# TOKEN_CACHE_TTL=10h

# Client-side cache TTL for redis-aside mode only (default: 1h)
# RESP3 handles real-time invalidation; this TTL is a fallback for missed notifications.
# TOKEN_CACHE_CLIENT_TTL=1h

# Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
# TOKEN_CACHE_SIZE_PER_CONN=32

# ============================================================
# Bootstrap and Shutdown Timeout Settings
# ============================================================
# Configure timeout durations for application lifecycle operations
# All values use Go duration format (e.g., 30s, 1m, 5m30s)

# Database Initialization and Shutdown
# DB_INIT_TIMEOUT=30s          # Database connection and migration timeout (default: 30s)
# DB_CLOSE_TIMEOUT=5s          # Database connection close timeout (default: 5s)

# Redis Connection and Shutdown
# REDIS_CONN_TIMEOUT=5s        # Redis connection health check timeout (default: 5s)
# REDIS_CLOSE_TIMEOUT=5s       # Redis connection close timeout (default: 5s)

# Cache Initialization and Shutdown
# CACHE_INIT_TIMEOUT=5s        # Cache initialization timeout (default: 5s)
# CACHE_CLOSE_TIMEOUT=5s       # Cache close timeout (default: 5s)

# Server Graceful Shutdown
# SERVER_SHUTDOWN_TIMEOUT=5s   # HTTP server graceful shutdown timeout (default: 5s)
# AUDIT_SHUTDOWN_TIMEOUT=10s   # Audit service shutdown timeout (default: 10s)

# Production Recommendations:
# - Increase DB_INIT_TIMEOUT (e.g., 60s) for large databases or slow networks
# - Increase AUDIT_SHUTDOWN_TIMEOUT (e.g., 30s) if audit buffer is large
# - Keep close timeouts short (5s) to prevent hanging on shutdown
# - All operations support cancellation with Ctrl+C during startup

# ============================================================
# CORS (Cross-Origin Resource Sharing)
# ============================================================
# Enable CORS for /oauth/* API endpoints so SPA frontends (React, Vue, etc.)
# can call token, introspect, and device code endpoints from a different origin.
# Disabled by default — HTML page endpoints are never affected.
# CORS_ENABLED=false
# CORS_ALLOWED_ORIGINS=http://localhost:3000,https://app.example.com
# CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
# CORS_ALLOWED_HEADERS=Origin,Content-Type,Authorization
# CORS_MAX_AGE=12h