env.example

# ==============================================================================
# TRAQORA CENTRAL ENVIRONMENT VARIABLES EXAMPLE
# ==============================================================================
# Copy this file to '.env' at the repository root or configure your environment
# managers accordingly. This file documents all available environment variables
# for the Traqora monorepo (backend and frontend/client).
#
# Types: [String], [Number], [Boolean], [Enum], [URL]
# ==============================================================================

# ------------------------------------------------------------------------------
# CLIENT / FRONTEND CONFIGURATION (packages/client)
# ------------------------------------------------------------------------------

# The base URL of the Traqora backend API.
# Type: [URL] | Default: http://localhost:3001
NEXT_PUBLIC_API_URL=http://localhost:3001


# ------------------------------------------------------------------------------
# BACKEND CONFIGURATION (packages/backend)
# ------------------------------------------------------------------------------

# ==============================================================================
# 1. SERVER CONFIGURATION
# ==============================================================================

# The port the backend server will listen on.
# Type: [Number] | Default: 3001
PORT=3001

# The application environment.
# Type: [Enum: development | staging | production | test] | Default: development
NODE_ENV=development

# Allowed origin for CORS headers.
# Type: [URL] | Default: http://localhost:3000
CORS_ORIGIN=http://localhost:3000

# Trust reverse proxy headers (e.g., X-Forwarded-For). Set to true when behind Cloudflare, Nginx, etc.
# Type: [Boolean] | Default: false
TRUST_PROXY=false


# ==============================================================================
# 2. STELLAR & SOROBAN CONFIGURATION
# ==============================================================================

# The Stellar network to connect to.
# Type: [Enum: production | testnet | standalone] | Default: testnet
STELLAR_NETWORK=testnet

# The private key of the Stellar account used by the backend for transactions.
# Type: [String] | Default: (None - Generate a secure key for staging/production)
STELLAR_SECRET_KEY=

# The URL of the Horizon server.
# Type: [URL] | Default: https://horizon-testnet.stellar.org
HORIZON_URL=https://horizon-testnet.stellar.org

# The URL of the Soroban RPC endpoint.
# Type: [URL] | Default: https://soroban-testnet.stellar.org
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org


# ==============================================================================
# 3. SMART CONTRACT ADDRESSES (SOROBAN CONTRACT IDS)
# ==============================================================================
# Required. These must be deployed contract IDs on the selected network.

# The contract ID for the Flight Booking contract.
# Type: [String] | Default: DEFAULT_ID
BOOKING_CONTRACT_ID=DEFAULT_ID

# The contract ID for the Airline management contract.
# Type: [String] | Default: DEFAULT_ID
AIRLINE_CONTRACT_ID=DEFAULT_ID

# The contract ID for the Refund automation contract.
# Type: [String] | Default: DEFAULT_ID
REFUND_CONTRACT_ID=DEFAULT_ID

# The contract ID for the Loyalty reward contract.
# Type: [String] | Default: DEFAULT_ID
LOYALTY_CONTRACT_ID=DEFAULT_ID

# The contract ID for the Governance voting contract.
# Type: [String] | Default: DEFAULT_ID
GOVERNANCE_CONTRACT_ID=DEFAULT_ID

# The contract ID for the native/custom Utility Token.
# Type: [String] | Default: DEFAULT_ID
TOKEN_CONTRACT_ID=DEFAULT_ID

# The contract ID for the Flight Registry contract.
# Type: [String] | Default: DEFAULT_ID
FLIGHT_REGISTRY_CONTRACT_ID=DEFAULT_ID


# ==============================================================================
# 4. DATABASE & CACHE STACK CONFIGURATION
# ==============================================================================

# Database Connection URL. Supports SQLite, PostgreSQL, etc.
# Type: [String] | Default: sqlite::memory:
# Example (Postgres): postgres://postgres:postgres@localhost:5432/traqora
DATABASE_URL=sqlite::memory:

# Redis Connection URL for caching and rate limiting.
# Type: [URL] | Default: redis://localhost:6379
REDIS_URL=redis://localhost:6379

# MongoDB Connection URI (optional, for specific logging or read-models).
# Type: [String] | Default: (None)
MONGO_URI=


# ==============================================================================
# 5. SECURITY & JWT CONFIGURATION
# ==============================================================================

# Secret key for signing Access JWTs. Must be at least 32 characters long.
# Type: [String] | Default: your-secret-key-at-least-32-chars-long
JWT_SECRET=your-secret-key-at-least-32-chars-long

# Expiration time for Access JWTs (e.g., '15m', '1h', '1d').
# Type: [String] | Default: 1h
JWT_EXPIRES_IN=1h

# Secret key for signing Refresh JWTs. Must be at least 32 characters long.
# Type: [String] | Default: your-refresh-secret-at-least-32-chars-long
JWT_REFRESH_SECRET=your-refresh-secret-at-least-32-chars-long

# Expiration time for Refresh JWTs (e.g., '7d', '30d').
# Type: [String] | Default: 7d
JWT_REFRESH_EXPIRES_IN=7d

# Admin API Key for accessing administrative endpoints. Must be at least 12 characters.
# Type: [String] | Default: dev-admin-key-at-least-16-chars
ADMIN_API_KEY=dev-admin-key-at-least-16-chars


# ==============================================================================
# 6. LOGGING & NONCE EXPIRY
# ==============================================================================

# Minimum log level.
# Type: [Enum: debug | info | warn | error] | Default: info
LOG_LEVEL=info

# Enable audit logging for critical operations.
# Type: [Boolean] | Default: false
AUDIT_LOG_ENABLED=false

# Expiration time for wallet login nonces in seconds.
# Type: [Number] | Default: 300
NONCE_EXPIRY_SECONDS=300


# ==============================================================================
# 7. TELEMETRY & OPEN-TELEMETRY (OTEL) TRACING
# ==============================================================================

# Enable distributed tracing and metric collection.
# Type: [Boolean] | Default: false
ENABLE_TRACING=false

# Disable OpenTelemetry SDK explicitly if needed.
# Type: [Enum: true | false] | Default: true
OTEL_SDK_DISABLED=true

# Service name reported to the OTEL collector.
# Type: [String] | Default: traqora-backend
OTEL_SERVICE_NAME=traqora-backend

# Version of the service reported.
# Type: [String] | Default: 0.1.0
OTEL_SERVICE_VERSION=0.1.0

# Endpoint to send OpenTelemetry traces.
# Type: [URL] | Default: http://localhost:4318/v1/traces
OTLP_TRACE_URL=http://localhost:4318/v1/traces

# General OTLP collector endpoint. Traces will go to `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`.
# Type: [URL] | Default: (None)
# OTEL_EXPORTER_OTLP_ENDPOINT=

# Specific OTLP trace exporter endpoint (standard OTEL variable).
# Type: [URL] | Default: (None)
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=

# Custom headers for OTLP trace exporter (format: key1=value1,key2=value2).
# Type: [String] | Default: (None)
# OTEL_EXPORTER_OTLP_TRACES_HEADERS=
# OTEL_EXPORTER_OTLP_HEADERS=

# Trace sampling rate. 1.0 means 100% of traces are captured.
# Type: [Number: 0.0 to 1.0] | Default: 1.0
TRACING_SAMPLE_RATE=1.0
# OTEL_TRACES_SAMPLER_ARG=1.0


# ==============================================================================
# 8. RATE LIMITING & SECURITY THRESHOLDS
# ==============================================================================

# General maximum number of requests per window.
# Type: [Number] | Default: 1000
RATE_LIMIT_MAX=1000

# Rate limit window in seconds.
# Type: [Number] | Default: 60
RATE_LIMIT_WINDOW_SEC=60

# Max requests per window for public endpoints.
# Type: [Number] | Default: 100
RATE_LIMIT_PUBLIC_MAX=100

# Max requests per window for standard authenticated users.
# Type: [Number] | Default: 300
RATE_LIMIT_USER_MAX=300

# Max requests per window for premium users.
# Type: [Number] | Default: 1000
RATE_LIMIT_PREMIUM_MAX=1000

# Maximum burst rate before triggering DDOS defense.
# Type: [Number] | Default: 250
DDOS_BURST_MAX=250

# DDOS burst window in seconds.
# Type: [Number] | Default: 60
DDOS_BURST_WINDOW_SEC=60

# Duration in seconds a blocked IP will remain blacklisted.
# Type: [Number] | Default: 900 (15 minutes)
RATE_LIMIT_BLOCK_DURATION_SEC=900

# Number of rate-limit violations before blocking an IP.
# Type: [Number] | Default: 5
RATE_LIMIT_BLOCK_AFTER_VIOLATIONS=5

# Number of violations before requiring CAPTCHA verification.
# Type: [Number] | Default: 3
CAPTCHA_AFTER_VIOLATIONS=3

# Parse Cloudflare headers (CF-Connecting-IP) for client IP.
# Type: [Boolean] | Default: false
USE_CLOUDFLARE_HEADERS=false


# ==============================================================================
# 9. CACHE TTL SETTINGS
# ==============================================================================

# Time-to-live for flight search cache in seconds.
# Type: [Number] | Default: 300
FLIGHT_SEARCH_CACHE_TTL_SECONDS=300

# Time-to-live for flight registry cache in seconds.
# Type: [Number] | Default: 60
FLIGHT_REGISTRY_CACHE_TTL_SECONDS=60


# ==============================================================================
# 10. THIRD-PARTY SERVICES
# ==============================================================================

# SendGrid API key for outbound transactional emails (optional).
# Type: [String] | Default: (None)
SENDGRID_API_KEY=

# Firebase service account credential JSON string or path (optional).
# Type: [String] | Default: (None)
FIREBASE_SERVICE_ACCOUNT=

# Twilio Account SID for SMS integration (optional).
# Type: [String] | Default: (None)
TWILIO_ACCOUNT_SID=

# Twilio Auth Token (optional).
# Type: [String] | Default: (None)
TWILIO_AUTH_TOKEN=

# Twilio Phone Number (optional).
# Type: [String] | Default: (None)
TWILIO_PHONE_NUMBER=


# ==============================================================================
# 11. AMADEUS TRAVEL FLIGHT SEARCH API
# ==============================================================================

# Amadeus API Client ID (optional, needed to pull real flight search data).
# Type: [String] | Default: (None)
AMADEUS_CLIENT_ID=

# Amadeus API Client Secret (optional).
# Type: [String] | Default: (None)
AMADEUS_CLIENT_SECRET=

# Amadeus API Base URL. Use https://test.api.amadeus.com for development.
# Type: [URL] | Default: (None)
AMADEUS_BASE_URL=https://test.api.amadeus.com

# Timeout for Amadeus API requests in milliseconds.
# Type: [Number] | Default: 30000
AMADEUS_TIMEOUT_MS=30000