# Explicit path
export GOLF_CONFIG_FILE=/path/to/config.yaml

# Required variable (fails if not set)
api_key: ${GOLF_API_KEY}

# Optional with default
timeout: ${GOLF_TIMEOUT:30}

# In nested structures
servers:
  - name: github-mcp
    url: ${MCP_SERVER_URL:http://localhost:3001}

version: "1.0"                    # Required, only "1.0" supported

control_plane:                    # Presence activates distributed mode
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000

# Optional sections
identity_providers: []
servers: []
gateway_policy: {}
security: {}
oauth_server: {}
exporters: {}

identity_providers:
  - name: auth0-primary
    type: auth0
    issuer: https://myorg.auth0.com/
    jwks_uri: https://myorg.auth0.com/.well-known/jwks.json
    api_identifiers:
      - https://api.example.com
    client_id: ${AUTH0_CLIENT_ID}
    client_secret: ${AUTH0_CLIENT_SECRET}

  - name: descope-corp
    type: descope
    project_id: ${DESCOPE_PROJECT_ID}
    management_key: ${DESCOPE_MANAGEMENT_KEY}
    # issuer and jwks_uri auto-generated for Descope

servers:
  - name: github-mcp
    url: http://github-mcp:3001
    description: "GitHub integration server"
    server_type: third_party
    enabled: true

    # RBAC
    rbac_enabled: true
    rbac_mode: allow
    allowed_groups:
      - engineering
      - devops

    # Capability RBAC
    capability_rbac_enabled: true
    capability_overrides:
      - capability: "tools/delete_repo"
        rbac_enabled: true
        rbac_mode: allow
        allowed_groups: [repo-admins]

    # Per-server PII scrubbing overrides (merged with gateway defaults)
    security:
      enabled: true
      sensitive_fields: [password, token]
      whitelist_fields: [cursor, tool_name]
      recognizers:
        - entity_type: EMAIL_ADDRESS
          enabled: true
          replacement: "[PII_EMAIL]"

    # Per-server threat whitelist
    threat_whitelist_patterns:
      - "GitHub API rate limit exceeded"

    # Identity provider reference
    idp: auth0-primary

gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields:
      - password
      - api_key
    whitelist_fields:
      - connection_id
      - session_id
      - cursor
    custom_rules:
      - pattern: "sk-[a-zA-Z0-9]+"
        method: mask
    recognizers:
      - entity_type: EMAIL_ADDRESS
        enabled: true
      - entity_type: URL
        enabled: false        # Disable URL scrubbing

  server_rbac:
    rbac_enabled: true
    rbac_mode: allow
    allowed_groups: [gateway-users]
    denied_groups: []
    capability_rbac_enabled: false

  capability_rbac:
    read_only:
      default_groups: [all-users]
    destructive:
      default_groups: [power-users]
    unspecified:
      default_groups: [all-users]

  # Gateway-level threat whitelist patterns
  threat_whitelist_patterns:
    - "Rate limit exceeded for tenant [A-Za-z0-9_-]+"

security:
  llm:
    backend: v1                              # v1, v2, or remote
    model_name: qualifire/prompt-injection-jailbreak-sentinel-v2
    confidence_threshold: 0.93
    whitelist_patterns:                      # Content that bypasses threat detection
      - "Unauthorized: Your organization \\(org_[A-Za-z0-9]+\\)"

    # Remote backend config (required when backend: remote)
    # remote:
    #   endpoint: https://my-model.eastus.inference.ml.azure.com/score
    #   api_key_env: GOLF_SECURITY_REMOTE_API_KEY

  replay_protection:
    enabled: true

  rate_limiting:
    enabled: true
    requests_per_minute: 100
    window_seconds: 60

oauth_server:
  token_ttl: 3600
  refresh_token_ttl: 604800
  authorization_code_ttl: 60
  idp_client_id: ${GOLF_OAUTH_SERVER_IDP_CLIENT_ID}
  idp_client_secret: ${GOLF_OAUTH_SERVER_IDP_CLIENT_SECRET}

exporters:
  elasticsearch:
    - name: primary-es
      enabled: true
      url: ${ELASTICSEARCH_URL}
      api_key: ${ELASTICSEARCH_API_KEY}
      index_prefix: golf-gateway
      timeout: 30

  otel:
    - name: primary-otel
      enabled: true
      endpoint: ${OTEL_ENDPOINT}
      protocol: grpc
      service_name: golf-gateway
      export_logs: true

  sentinel:
    - name: azure-sentinel
      enabled: true
      dcr_immutable_id: ${SENTINEL_DCR_ID}
      dcr_endpoint: ${SENTINEL_DCR_ENDPOINT}
      tenant_id: ${AZURE_TENANT_ID}
      client_id: ${AZURE_CLIENT_ID}
      client_secret: ${AZURE_CLIENT_SECRET}

control_plane:
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000
  timeout: 30
  cache_ttl: 300

version: "1.0"

# Control Plane connection (activates distributed mode)
control_plane:
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000

# Identity providers for authentication
identity_providers:
  - name: auth0
    type: auth0
    issuer: https://myorg.auth0.com/
    jwks_uri: https://myorg.auth0.com/.well-known/jwks.json
    api_identifiers:
      - https://api.example.com
    client_id: ${AUTH0_MGMT_CLIENT_ID}
    client_secret: ${AUTH0_MGMT_CLIENT_SECRET}

# MCP servers (YAML is source of truth for servers in distributed mode)
servers:
  - name: github-mcp
    url: http://github-mcp:3001
    server_type: third_party
    rbac_enabled: true
    allowed_groups: [engineering]
    idp: auth0
    security:
      enabled: true
      sensitive_fields: [token]
    threat_whitelist_patterns:
      - "GitHub API rate limit exceeded"

  - name: internal-tools
    url: http://tools-mcp:3002
    server_type: inhouse
    rbac_enabled: false

# OAuth authorization server for third-party server auth flows
oauth_server:
  idp_client_id: ${GOLF_OAUTH_SERVER_IDP_CLIENT_ID}
  idp_client_secret: ${GOLF_OAUTH_SERVER_IDP_CLIENT_SECRET}

# Local policy (merged with org policy from Control Plane)
gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields: [ssn, account_number]
    whitelist_fields: [connection_id, session_id]
  server_rbac:
    rbac_enabled: true
    allowed_groups: [gateway-users]

# Security engine settings
security:
  llm:
    backend: v1
    confidence_threshold: 0.93
  replay_protection:
    enabled: true
  rate_limiting:
    enabled: true
    requests_per_minute: 100

# Audit log exporters
exporters:
  elasticsearch:
    - name: primary
      url: ${ELASTICSEARCH_URL}
      api_key: ${ELASTICSEARCH_API_KEY}

# The gateway validates config on startup
GOLF_CONFIG_FILE=/path/to/config.yaml python -m golf_gateway.main --validate

# Check for undefined environment variables
GOLF_CONFIG_FILE=/path/to/config.yaml python -c "
from golf_gateway.config.yaml_loader import validate_yaml_config
errors = validate_yaml_config('/path/to/config.yaml')
for error in errors:
    print(error)
"