config.example.yaml

# Copyright 2026 CloudBlue LLC
# SPDX-License-Identifier: Apache-2.0

# Chaperone Configuration Example
# ================================
# This file demonstrates all available configuration options.
# Copy to config.yaml and customize for your deployment.
#
# Environment variables override YAML values using the pattern:
# CHAPERONE_<SECTION>_<KEY> (uppercase, underscore separator)
# Example: CHAPERONE_SERVER_ADDR=":9443"

server:
  # Traffic port - main proxy endpoint
  # Default: ":443"
  # Env: CHAPERONE_SERVER_ADDR
  addr: ":8443"

  # Admin port - metrics and health endpoints
  # Default: ":9090"
  # Env: CHAPERONE_SERVER_ADMIN_ADDR
  admin_addr: ":9090"

  # Maximum time to drain in-flight requests during graceful shutdown.
  # Default: 30s
  # Env: CHAPERONE_SERVER_SHUTDOWN_TIMEOUT
  shutdown_timeout: 30s

  tls:
    # Enable TLS/mTLS (mutual TLS)
    # Default: true
    # Env: CHAPERONE_SERVER_TLS_ENABLED
    enabled: true

    # Path to server certificate (PEM format)
    # Default: "/certs/server.crt"
    # Env: CHAPERONE_SERVER_TLS_CERT_FILE
    cert_file: "certs/server.crt"

    # Path to server private key (PEM format)
    # Default: "/certs/server.key"
    # Env: CHAPERONE_SERVER_TLS_KEY_FILE
    key_file: "certs/server.key"

    # Path to CA certificate for client verification (PEM format)
    # Default: "/certs/ca.crt"
    # Env: CHAPERONE_SERVER_TLS_CA_FILE
    ca_file: "certs/ca.crt"

    # Enable automatic certificate rotation
    # Default: true
    # Env: CHAPERONE_SERVER_TLS_AUTO_ROTATE
    auto_rotate: true

upstream:
  # Header prefix for context headers (ADR-005)
  # Affects: X-{prefix}-Target-URL, X-{prefix}-Marketplace-ID, etc.
  # Default: "X-Connect"
  # Env: CHAPERONE_UPSTREAM_HEADER_PREFIX
  header_prefix: "X-Connect"

  # Correlation ID header name (ADR-005)
  # Default: "Connect-Request-ID"
  # Env: CHAPERONE_UPSTREAM_TRACE_HEADER
  trace_header: "Connect-Request-ID"

  # Allow-list for target URLs (REQUIRED)
  # Security: This is mandatory - empty means deny all requests.
  # Format: hostname[:port] -> list of path patterns
  # Port rules:
  #   - If host key omits port, only scheme default port is allowed
  #     (HTTPS=443, HTTP=80)
  #   - To allow non-default ports, include explicit :port in host key
  #   - HTTP targets require a build with allowInsecureTargets=true
  # Patterns:
  #   * = single-level wildcard (within segment)
  #   ** = multi-level/recursive wildcard
  allow_list:
    # Example: Allow all paths under api.vendor.com
    "api.vendor.com":
      - "/v1/**"
      - "/v2/**"
    # Example: Allow specific paths only
    "payments.example.com":
      - "/api/charge"
      - "/api/refund"
    # Example: Explicit non-default port (dev/private endpoint)
    "localhost:8000":
      - "/api/v1/**"

  timeouts:
    # Connection establishment timeout
    # Default: 5s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_CONNECT
    connect: 5s

    # Maximum time waiting for response headers
    # Default: 30s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_READ
    read: 30s

    # Maximum time for writing the response
    # Default: 30s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_WRITE
    write: 30s

    # Keep-alive connection timeout
    # Default: 120s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_IDLE
    idle: 120s

    # Interval between TCP keep-alive probes on idle upstream connections.
    # Detects dead peers before the idle timeout fires.
    # Default: 30s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_KEEP_ALIVE
    keep_alive: 30s

    # Maximum time for a plugin to return credentials.
    # If a plugin (e.g., Vault lookup, OAuth token exchange) takes longer
    # than this, the request fails with 504 Gateway Timeout.
    # Default: 10s
    # Env: CHAPERONE_UPSTREAM_TIMEOUTS_PLUGIN
    plugin: 10s

observability:
  # Logging level
  # Valid values: debug, info, warn, error
  # Default: "info"
  # Env: CHAPERONE_OBSERVABILITY_LOG_LEVEL
  log_level: "info"

  # Enable /debug/pprof endpoint on admin port
  # Security: Should be false in production
  # Default: false
  # Env: CHAPERONE_OBSERVABILITY_ENABLE_PROFILING
  enable_profiling: false

  # Enable OpenTelemetry distributed tracing
  # When true, spans are exported via OTLP. Exporter configuration
  # (endpoint, headers, TLS) uses standard OTEL_* environment variables:
  #   OTEL_EXPORTER_OTLP_ENDPOINT  - Collector endpoint (e.g., http://localhost:4318)
  #   OTEL_EXPORTER_OTLP_HEADERS   - Auth headers for the collector
  #   OTEL_SERVICE_NAME             - Override service name (default: chaperone)
  #   OTEL_SDK_DISABLED=true        - Force-disable the OTel SDK (always wins)
  # Default: false
  # Env: CHAPERONE_OBSERVABILITY_ENABLE_TRACING
  enable_tracing: false

  # Controls how much of the upstream target URL is reported in the
  # `target_addr` log field. The same value is applied uniformly to every
  # log line that references the target (request completed, upstream
  # response, allow-list events, plugin errors, etc.).
  #
  # Valid values:
  #   "host" (default) - Authority only (host[:port]). No scheme, no path,
  #                       no query. Safest. Example: "api.vendor.com:8443".
  #   "path"           - scheme://host[:port]/path. Path appears, query
  #                       stripped. Example: "https://api.vendor.com/v1/users".
  #                       Useful for "what endpoint was called" auditing.
  #   "full"           - Full URL including query. Userinfo (user:pass@) is
  #                       always stripped, in every mode.
  #                       Example: "https://api.vendor.com/v1/users?key=val".
  #
  # SECURITY: "path" and "full" can leak sensitive information. Path
  # segments may contain PII (e.g., emails or IDs); query strings are a
  # common location for tokens and API keys. The proxy emits a startup
  # WARN when "full" is enabled. Use "host" unless an audit/debugging
  # requirement justifies the extra detail.
  #
  # Default: "host"
  # Env: CHAPERONE_OBSERVABILITY_LOG_TARGET_ADDR
  log_target_addr: "host"

  # Additional headers to redact from logs and strip from responses.
  # These are MERGED with the built-in defaults which are always included:
  #   Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-API-Key, X-Auth-Token
  # You only need to list headers beyond the defaults.
  # Duplicates are ignored (case-insensitive).
  sensitive_headers: []
    # - "X-Custom-Secret"
    # - "X-Vendor-Token"