.env.example

# ═══════════════════════════════════════════════════════════════════════════════
# MUNIFY Delegator - Environment Configuration
# ═══════════════════════════════════════════════════════════════════════════════
# Copy this file to .env and replace the values with your own.
# Variables marked [REQUIRED] must be set for the application to start.
# Variables marked [OPTIONAL] have sensible defaults or enable optional features.
# ═══════════════════════════════════════════════════════════════════════════════

# ───────────────────────────────────────────────────────────────────────────────
# CORE APPLICATION
# ───────────────────────────────────────────────────────────────────────────────

# [REQUIRED] Session encryption secret - use a strong random string
# Generate with: openssl rand -hex 32
SECRET=your-secret-key-here

# [REQUIRED] Application environment
# Values: development | production | test
NODE_ENV=development

# [OPTIONAL] Server port (default: 3000)
PORT=3000

# [OPTIONAL] Public origin of the application (e.g. https://delegator.munify.cloud)
# SvelteKit uses this for CSRF protection on form submissions and POST requests.
# If not set, SvelteKit infers it from the Host header, which works when your reverse
# proxy forwards headers correctly (e.g. Traefik, Caddy). If you're self-hosting behind
# a proxy that doesn't reliably set the Host header, set this to your public URL to
# prevent CSRF validation failures.
# ORIGIN=https://delegator.munify.cloud

# ───────────────────────────────────────────────────────────────────────────────
# DATABASE
# ───────────────────────────────────────────────────────────────────────────────

# [REQUIRED] PostgreSQL connection string
# Format: postgres://USER:PASSWORD@HOST:PORT/DATABASE
DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

# ───────────────────────────────────────────────────────────────────────────────
# AUTHENTICATION (OIDC)
# ───────────────────────────────────────────────────────────────────────────────
# Supports any OpenID Connect provider (recommended: Logto — https://logto.io/)
#
# ┌─── Logto Setup Guide ───────────────────────────────────────────────────────┐
# │                                                                             │
# │  1. Create a "Traditional Web" application in Logto Console                 │
# │  2. Set the redirect URI to: <your-domain>/auth/login-callback              │
# │  3. Copy the App ID → PUBLIC_OIDC_CLIENT_ID                                │
# │  4. Copy the App Secret → OIDC_CLIENT_SECRET                               │
# │                                                                             │
# │  Custom JWT Claims (required):                                              │
# │  Go to Logto Console → JWT Customizer → User access token and add:         │
# │                                                                             │
# │    const getCustomJwtClaims = async ({                                      │
# │      token, context, environmentVariables, api                              │
# │    }) => {                                                                  │
# │      return {                                                               │
# │        roles: context.user.roles,                                           │
# │        mfa: context.user.mfaVerificationFactors,                            │
# │        password: context.user.hasPassword,                                  │
# │        sso_identities: context.user.ssoIdentities,                          │
# │        social_identities:                                                   │
# │          Object.keys(context.user.identities) ?? []                         │
# │      };                                                                     │
# │    }                                                                        │
# │                                                                             │
# │  This exposes user roles, MFA status, and identity provider info            │
# │  in the access token so the application can use them for                    │
# │  authorization and UI display.                                              │
# │                                                                             │
# └─────────────────────────────────────────────────────────────────────────────┘

# [REQUIRED] OIDC Discovery URL (usually ends with /.well-known/openid-configuration)
# Local mock: http://localhost:8080/default/.well-known/openid-configuration
# Logto: https://<your-tenant>.logto.app/oidc/.well-known/openid-configuration
PUBLIC_OIDC_AUTHORITY=http://localhost:8080/default/.well-known/openid-configuration

# [REQUIRED] OAuth2 Client ID from your OIDC provider
PUBLIC_OIDC_CLIENT_ID=default

# [OPTIONAL] OAuth2 Client Secret (only needed for confidential clients)
# OIDC_CLIENT_SECRET=your-client-secret

# [REQUIRED] OAuth2 scopes to request
# These scopes control ID token and userinfo claims, NOT the access token.
# Access token claims are set via the JWT Customizer script above.
#
# openid          — required by OIDC spec
# profile         — user name, picture, etc.
# offline_access  — enables refresh tokens
# email           — user email address
# phone           — user phone number
# identity        — Logto scope: linked social & SSO identities
# role            — Logto scope: user roles for authorization
# custom_data     — Logto scope: custom user data
OIDC_SCOPES="openid profile offline_access email phone identity role custom_data"

# [OPTIONAL] JWT claim path for user roles
# Used to determine team member permissions
# With the custom JWT claims above, roles are available at the "roles" claim
OIDC_ROLE_CLAIM=roles

# [OPTIONAL] OIDC resource indicator for your application's API
# When set, this is passed as the `resource` parameter during authorization and token requests,
# and used as the expected `audience` when verifying access tokens.
# Required for features that need API access tokens (e.g. reading resources with "resource:read"
# scopes). Without it, Logto issues opaque tokens instead of JWTs, and access token verification
# will be skipped.
# Set this to the API resource indicator you configured in Logto Console → API Resources.
# OIDC_RESOURCE=https://delegator.munify.cloud/api

# [OPTIONAL] Machine-to-machine app credentials for Logto Management API
# Required for user impersonation feature (token exchange via subject tokens)
# Create an M2M app in Logto Console with access to the Management API resource
# OIDC_M2M_CLIENT_ID=your-m2m-app-id
# OIDC_M2M_CLIENT_SECRET=your-m2m-app-secret
# [OPTIONAL] Logto Management API resource indicator (audience claim in the M2M token)
# This is NOT the API URL — the actual API URL is always derived from PUBLIC_OIDC_AUTHORITY.
# For Logto Cloud: https://<tenant-id>.logto.app/api
# For self-hosted: check your Logto API Resources settings (typically https://default.logto.app/api)
# If not set, derived from PUBLIC_OIDC_AUTHORITY by replacing /oidc with /api
# OIDC_M2M_RESOURCE=https://default.logto.app/api

# ───────────────────────────────────────────────────────────────────────────────
# APPLICATION FEATURES
# ───────────────────────────────────────────────────────────────────────────────

# [OPTIONAL] Default locale for the application (default: de)
# Values: de | en
# PUBLIC_DEFAULT_LOCALE=de

# [OPTIONAL] Enable global user notes visible to team members (default: false)
PUBLIC_GLOBAL_USER_NOTES_ACTIVE=true

# [OPTIONAL] Show OIDC migration notice before login (default: false)
# TEMPORARY: Enable during identity provider migration to warn users
# PUBLIC_OIDC_MIGRATION_NOTICE=false

# [OPTIONAL] Maximum character length for application motivation text (default: 1200)
PUBLIC_MAX_APPLICATION_TEXT_LENGTH=1200

# [OPTIONAL] Maximum character length for school name field (default: 100)
# PUBLIC_MAX_APPLICATION_SCHOOL_LENGTH=100

# [OPTIONAL] URL to external feedback/bug reporting tool
PUBLIC_FEEDBACK_URL=https://fb-delegator.dmun.de

# [OPTIONAL] Support email address displayed on error pages (default: support@dmun.de)
# PUBLIC_SUPPORT_EMAIL=support@dmun.de

# [OPTIONAL] Organization domain for team invitations
# When set, shows a warning when inviting emails from other domains
# PUBLIC_TEAM_ORGANIZATION_DOMAIN=dmun.de

# ───────────────────────────────────────────────────────────────────────────────
# CERTIFICATES
# ───────────────────────────────────────────────────────────────────────────────

# [REQUIRED] Secret key for signing participation certificates (HMAC-SHA256)
# Generate with: openssl rand -base64 32
CERTIFICATE_SECRET="your-certificate-secret-here"

# ───────────────────────────────────────────────────────────────────────────────
# MAINTENANCE WINDOWS
# ───────────────────────────────────────────────────────────────────────────────
# Display a maintenance banner to users during scheduled maintenance

# [OPTIONAL] Maintenance window start time (ISO 8601 format with timezone)
# PUBLIC_MAINTENANCE_WINDOW_START=2025-10-22T00:00:00Z

# [OPTIONAL] Maintenance window end time (ISO 8601 format with timezone)
# PUBLIC_MAINTENANCE_WINDOW_END=2025-10-22T04:00:00Z

# ───────────────────────────────────────────────────────────────────────────────
# EMAIL (SMTP)
# ───────────────────────────────────────────────────────────────────────────────
# Transactional email for notifications (e.g., paper review notifications)
# For local development, use Mailpit: localhost:1025 (SMTP), localhost:8025 (Web UI)

# [OPTIONAL] SMTP server hostname (default: localhost)
SMTP_HOST=localhost

# [OPTIONAL] SMTP server port (default: 1025)
SMTP_PORT=1025

# [OPTIONAL] Use TLS/SSL connection (default: false)
# Set to "true" for production SMTP servers that require encryption
SMTP_SECURE=false

# [OPTIONAL] SMTP authentication username
SMTP_USER=

# [OPTIONAL] SMTP authentication password
SMTP_PASSWORD=

# [OPTIONAL] Sender email address (default: noreply@munify.cloud)
SMTP_FROM_ADDRESS=noreply@munify.cloud

# [OPTIONAL] Sender display name (default: MUNIFY Delegator)
SMTP_FROM_NAME=MUNIFY Delegator

# ───────────────────────────────────────────────────────────────────────────────
# OBSERVABILITY (OpenTelemetry)
# ───────────────────────────────────────────────────────────────────────────────
# Distributed tracing for performance monitoring

# [OPTIONAL] OpenTelemetry collector endpoint URL
# OTEL_ENDPOINT_URL=http://localhost:4318/v1/traces

# [OPTIONAL] Service name for traces (default: MUNIFY-DELEGATOR)
# OTEL_SERVICE_NAME=MUNIFY-DELEGATOR

# [OPTIONAL] Service version for traces
# OTEL_SERVICE_VERSION=1.0.0

# [OPTIONAL] Authorization header for authenticated OTEL collectors
# OTEL_AUTHORIZATION_HEADER=Bearer your-token

# ───────────────────────────────────────────────────────────────────────────────
# ERROR TRACKING (Sentry/Bugsink)
# ───────────────────────────────────────────────────────────────────────────────
# Error monitoring and crash reporting
# For local development, use Bugsink: http://localhost:8000

# [OPTIONAL] Sentry/Bugsink DSN for server-side error tracking
# SENTRY_DSN=http://your-key@localhost:8000/1

# [OPTIONAL] Sentry/Bugsink DSN for client-side error tracking
# PUBLIC_SENTRY_DSN=http://your-key@localhost:8000/1

# [OPTIONAL] Include PII (user IPs, etc.) in error reports (default: false)
# SENTRY_SEND_DEFAULT_PII=false
# PUBLIC_SENTRY_SEND_DEFAULT_PII=false

# ───────────────────────────────────────────────────────────────────────────────
# EXTERNAL INTEGRATIONS
# ───────────────────────────────────────────────────────────────────────────────

# --- Badge Generator ---
# [OPTIONAL] URL to external badge/name tag generator service
# When set, adds a "Generate Badge" button in participant management
# PUBLIC_BADGE_GENERATOR_URL=https://badges.example.com

# --- Listmonk (Newsletter) ---
# [OPTIONAL] Listmonk API URL for newsletter subscription management
# LISTMONK_API_URL=http://localhost:9000/api

# [OPTIONAL] Listmonk API username
# LISTMONK_API_USER=api

# [OPTIONAL] Listmonk API key
# LISTMONK_API_KEY=your-api-key

# --- Slack Notifications ---
# [OPTIONAL] Slack webhook URL for general notifications
# SLACK_NOTIFICATION_WEBHOOK=https://hooks.slack.com/services/...

# [OPTIONAL] Slack webhook URL for error alerts
# SLACK_ERROR_WEBHOOK=https://hooks.slack.com/services/...

# ───────────────────────────────────────────────────────────────────────────────
# BUILD-TIME VARIABLES (set automatically during CI/CD)
# ───────────────────────────────────────────────────────────────────────────────
# These are typically set by CI/CD and should not be manually configured

# [AUTO] Application version
# PUBLIC_VERSION=1.0.0

# [AUTO] Git commit SHA
# PUBLIC_SHA=abc123