# ADR-0001: Env-Aware YAML Resolution with Env-Final Precedence

- Status: Accepted
- Date: 2026-05-14
- Deciders: athena-auth maintainers

## Context

`athena-auth` runtime configuration is loaded from `config.yaml` (or `ATHENA_AUTH_CONFIG_FILE`) and environment variables. Before this change, env handling was field-specific and inconsistent:

- Some values were YAML-first with env fallback.
- Some values merged env + YAML.
- There was no generic env override convention for all YAML keys.
- YAML values could not reference env vars inline.

The requested behavior is:

1. Config remains backward compatible.
2. YAML can use hardcoded values or explicit env templates.
3. Environment variables are final and cannot be overridden by YAML.
4. The mechanism should be generic across discovered config keys.

## Decision

Introduce a generic `ConfigResolver` in `src/bin/server.rs` that:

1. Parses raw YAML into a value tree.
2. Collects config fields (dot-paths) from that tree.
3. Resolves inline templates in string values:
   - `${ENV_NAME}`
   - `${ENV_NAME:-fallback}`
4. Applies env overrides per discovered config field path using canonical env keys:
   - `ATHENA_AUTH_CONFIG__<PATH_SEGMENT_1>__<PATH_SEGMENT_2>...`
5. Preserves compatibility aliases for existing env contracts:
   - `BASE_URL`, `AUTH_BASE_PATH`, `TRUSTED_ORIGINS`
6. Deserializes the resolved YAML into `ServerConfigFile`.

Additionally, `load_config()` was aligned so core auth runtime values (`base_url`, `base_path`, `trusted_origins`) treat env vars as final precedence.

## Consequences

### Positive

- Consistent precedence model: env always wins.
- Generic override mechanism for all config keys present in YAML.
- Supports explicit env templating directly in YAML values.
- Backward compatible with existing environment variable usage.

### Negative / Trade-offs

- Slightly more complex config loading path.
- Type coercion for env overrides must be validated per scalar/list/object shape.
- Missing envs in required `${ENV_NAME}` templates now fail fast.

## Validation

Added/updated unit tests in `src/bin/server.rs` covering:

- Path-to-env-key derivation.
- Field discovery from YAML value trees.
- `${ENV}` and `${ENV:-default}` expansion.
- Error on unresolved required env template.
- Canonical and legacy env overrides.
- CSV list override behavior for sequence fields.
