fix(config): reject unknown config keys and log provider origins (#511)

* fix(config): reject unknown config keys and log provider origins

A misindented `providers:` section parses as a null section plus unknown
top-level keys. yaml.Unmarshal discarded those silently, so the gateway
booted with none of the operator's providers and no error — the fault only
surfaced once an env-provisioned provider was removed and startup failed
with "no providers were successfully registered".

Parse the YAML layer with KnownFields(true) so an unknown key fails startup,
naming the file and every offending line. This also catches ordinary typos
(`prot:` for `port:`, `bass_url:` for `base_url:`).

The env layer declares the same structures as JSON and overrides YAML entry
by entry, so a typo there would silently win over a correct YAML entry.
Decode VIRTUAL_MODELS, SET_RATE_LIMIT_*, and SET_BUDGET_* with
DisallowUnknownFields for the same reason.

Two fixes fall out of that:

- BudgetLimitConfig had no json tags, unlike its RateLimitRuleConfig
  neighbour which added them for exactly this env form, so `period_seconds`
  in a SET_BUDGET_* JSON array was silently dropped and produced a limit
  with no window. Add the tags.
- `failover.overrides` is a removed key that old config files still carry
  and that strict parsing would now reject. Model it as an explicitly
  ignored field, upgrading it from silently ignored to a logged deprecation
  pointing at `disabled_models`.

A config path that exists but cannot be read — a directory bind-mounted
where a file was expected — was indistinguishable from a missing file and
fell back to defaults. Report it instead.

Finally, log one line at boot showing how many providers came from the
config file versus environment discovery, with their names, so an operator
can see at a glance that a config file contributed nothing.

Closes #509

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(config): add CONFIG_STRICT escape hatch for unknown keys

Strict parsing is the right default — a dropped providers, rate_limits,
budgets, or guardrails entry silently changes routing, cost, or security —
but it blocks one legitimate case: rolling a binary back under a config file
written for a newer version, where an unknown key is expected rather than a
typo.

CONFIG_STRICT=false downgrades unknown keys to warnings that name the file,
line, and field, then boots without them. The default stays true.

Unknown keys are always detected: lax mode still decodes with
KnownFields(true) and inspects the resulting TypeError, so it can report each
ignored key instead of dropping it in silence the way yaml.Unmarshal did.

The flag relaxes which keys are accepted, never whether a value makes sense.
A malformed value (`port: [9999, 8080]`) and a YAML syntax error stay fatal
in both modes, and a file mixing an unknown key with a malformed value still
fails. The same rule applies to the JSON env layer, where only
encoding/json's unknown-field error is downgraded.

Entity-level validation is unaffected: a virtual model whose target names a
provider that does not exist still fails startup even when the key that would
have declared that provider was ignored with a warning.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(config): reject trailing data after declarative JSON and YAML values

Swapping json.Unmarshal for a json.Decoder to get DisallowUnknownFields
regressed a check nobody asked for but everybody relied on: Decode stops
after the first JSON value and leaves the rest unread, so

    VIRTUAL_MODELS='[{"source":"a"}] {"targts":[]}'

booted happily while ignoring the suffix. json.Unmarshal rejects trailing
data; silently applying half an env var is precisely the failure this path
exists to prevent. Require io.EOF after the decoded value.

The YAML layer had the same hole, pre-dating this branch: both yaml.Unmarshal
and yaml.Decoder read one document, so every key after a `---` separator was
applied nowhere. Reject a second document.

Both are structural faults, not unknown keys, so they stay fatal under
CONFIG_STRICT=false.

Also correct the misindentation gotcha in the docs, whose prose counted keys
the sample did not contain. The sample now carries two providers and the
quoted error is the binary's verbatim output.

Reported by Greptile and CodeRabbit on #511.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* build: bump Go to 1.26.5 for GO-2026-5856

govulncheck reports the Encrypted Client Hello privacy leak in crypto/tls
(GO-2026-5856), fixed in go1.26.5. It reproduces on pristine main at e0eb0ee,
so CI is red independently of this branch; the reachable traces are the
dashboard, redis, and mongo TLS paths, none of them new.

Bump every pin so the shipped binary is patched, not just CI:

  .github/workflows/test.yml     GO_VERSION 1.26.4 -> 1.26.5
  .github/workflows/release.yml  go-version 1.26.4 -> 1.26.5
  Dockerfile                     golang:1.26.4-alpine3.23 -> 1.26.5
  go.mod                         go 1.26.4 -> go 1.26.5

Verified: govulncheck reports no vulnerabilities with and without the swagger
tag; unit, contract, e2e, and integration suites pass; golangci-lint is clean
across all build tags; and the release image builds and reports go1.26.5.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: SantiagoDePolonia

.env.template

@@ -5,6 +5,14 @@
 # Header used to read/write request user_path values (default: X-GoModel-User-Path)
 # USER_PATH_HEADER=X-GoModel-User-Path
 
+# Reject unknown keys in config.yaml and in the JSON env vars that declare the same
+# structures (VIRTUAL_MODELS, SET_RATE_LIMIT_*, SET_BUDGET_*). Default: true, so a
+# typo or a misindented section fails startup instead of silently dropping providers,
+# rate limits, budgets, or guardrails. Set false to downgrade unknown keys to
+# warnings — intended for rolling a binary back under a newer config file. Malformed
+# values stay fatal in either mode.
+# CONFIG_STRICT=true
+
 # Tagging based on headers: label every request from the listed headers (numbered
 # from 1). Labels are recorded in usage tracking and audit logs. A header value can
 # carry several labels split by the delimiter (default: ","). The optional prefix is

.github/workflows/release.yml

@@ -155,7 +155,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version: 1.26.4
+          go-version: 1.26.5
           cache: true
 
       - name: Run GoReleaser

.github/workflows/test.yml

@@ -12,7 +12,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  GO_VERSION: "1.26.4"
+  GO_VERSION: "1.26.5"
 
 # Restrict token permissions to minimum required
 permissions:

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage — run on the build host's native arch for speed, cross-compile for target
-FROM --platform=$BUILDPLATFORM golang:1.26.4-alpine3.23 AS builder
+FROM --platform=$BUILDPLATFORM golang:1.26.5-alpine3.23 AS builder
 
 ARG TARGETOS
 ARG TARGETARCH

config/budget.go

@@ -30,20 +30,21 @@ type BudgetUserPathConfig struct {
 }
 
 // BudgetLimitConfig declares one spend limit for a reset period.
+// The json tags support the JSON-array form of SET_BUDGET_* env values.
 type BudgetLimitConfig struct {
 	// Period accepts hourly, daily, weekly, or monthly. The resolved period is
 	// persisted as PeriodSeconds in the database.
-	Period string `yaml:"period"`
+	Period string `yaml:"period" json:"period"`
 
 	// PeriodSeconds can be set directly instead of Period. Standard values are
 	// 3600, 86400, 604800, and 2592000.
-	PeriodSeconds int64 `yaml:"period_seconds"`
+	PeriodSeconds int64 `yaml:"period_seconds" json:"period_seconds"`
 
 	// Amount is the maximum allowed tracked provider spend for the period.
-	Amount float64 `yaml:"amount"`
+	Amount float64 `yaml:"amount" json:"amount"`
 }
 
-func applyBudgetEnv(cfg *Config) error {
+func applyBudgetEnv(cfg *Config, strict bool) error {
 	if cfg == nil {
 		return nil
 	}
@@ -54,7 +55,7 @@ func applyBudgetEnv(cfg *Config) error {
 		cfg.Budgets.UserPaths,
 		"SET_BUDGET_",
 		func(entry BudgetUserPathConfig) string { return entry.Path },
-		parseBudgetEnvLimits,
+		func(raw string) ([]BudgetLimitConfig, error) { return parseBudgetEnvLimits(raw, strict) },
 		func(path string, limits []BudgetLimitConfig) BudgetUserPathConfig {
 			return BudgetUserPathConfig{Path: path, Limits: limits}
 		},
@@ -66,7 +67,7 @@ func applyBudgetEnv(cfg *Config) error {
 	return nil
 }
 
-func parseBudgetEnvLimits(raw string) ([]BudgetLimitConfig, error) {
+func parseBudgetEnvLimits(raw string, strict bool) ([]BudgetLimitConfig, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
 		return nil, nil
@@ -89,7 +90,7 @@ func parseBudgetEnvLimits(raw string) ([]BudgetLimitConfig, error) {
 	}
 	if strings.HasPrefix(raw, "[") {
 		var limits []BudgetLimitConfig
-		if err := json.Unmarshal([]byte(raw), &limits); err != nil {
+		if err := decodeIaCJSON("SET_BUDGET_*", raw, &limits, strict); err != nil {
 			return nil, err
 		}
 		return limits, nil

config/budget_test.go

@@ -0,0 +1,34 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+// The JSON-array form of SET_BUDGET_* decodes through json tags. Without them
+// period_seconds was silently dropped, yielding a limit with no window.
+func TestParseBudgetEnvLimits_JSONArray(t *testing.T) {
+	limits, err := parseBudgetEnvLimits(`[{"period_seconds":7200,"amount":5}]`, true)
+	if err != nil {
+		t.Fatalf("parseBudgetEnvLimits() error = %v", err)
+	}
+	if len(limits) != 1 {
+		t.Fatalf("len(limits) = %d, want 1", len(limits))
+	}
+	if limits[0].PeriodSeconds != 7200 {
+		t.Fatalf("PeriodSeconds = %d, want 7200", limits[0].PeriodSeconds)
+	}
+	if limits[0].Amount != 5 {
+		t.Fatalf("Amount = %v, want 5", limits[0].Amount)
+	}
+}
+
+func TestParseBudgetEnvLimits_RejectsUnknownField(t *testing.T) {
+	_, err := parseBudgetEnvLimits(`[{"period":"daily","ammount":5}]`, true)
+	if err == nil {
+		t.Fatal("parseBudgetEnvLimits() error = nil, want unknown-field error")
+	}
+	if !strings.Contains(err.Error(), "ammount") {
+		t.Fatalf("parseBudgetEnvLimits() error = %q, want it to name the unknown field", err)
+	}
+}

config/config.go

@@ -2,8 +2,15 @@
 package config
 
 import (
+	"errors"
 	"fmt"
+	"io"
+	"io/fs"
+	"log/slog"
 	"os"
+	"regexp"
+	"strconv"
+	"strings"
 	"time"
 
 	"gopkg.in/yaml.v3"
@@ -152,7 +159,12 @@ func buildDefaultConfig() *Config {
 func Load() (*LoadResult, error) {
 	cfg := buildDefaultConfig()
 
-	rawProviders, err := applyYAML(cfg)
+	strict, err := resolveConfigStrict()
+	if err != nil {
+		return nil, err
+	}
+
+	rawProviders, err := applyYAML(cfg, strict)
 	if err != nil {
 		return nil, err
 	}
@@ -168,7 +180,7 @@ func Load() (*LoadResult, error) {
 	if err := applyEnvOverrides(cfg); err != nil {
 		return nil, err
 	}
-	if err := applyVirtualModelsEnv(cfg); err != nil {
+	if err := applyVirtualModelsEnv(cfg, strict); err != nil {
 		return nil, err
 	}
 	if err := applyTaggingEnv(cfg); err != nil {
@@ -178,13 +190,13 @@ func Load() (*LoadResult, error) {
 		return nil, err
 	}
 	applyBudgetDependencies(cfg)
-	if err := applyBudgetEnv(cfg); err != nil {
+	if err := applyBudgetEnv(cfg, strict); err != nil {
 		return nil, err
 	}
 	if err := validateBudgetConfig(&cfg.Budgets); err != nil {
 		return nil, err
 	}
-	if err := applyRateLimitEnv(cfg); err != nil {
+	if err := applyRateLimitEnv(cfg, strict); err != nil {
 		return nil, err
 	}
 	if err := validateRateLimitConfig(&cfg.RateLimits); err != nil {
@@ -225,32 +237,56 @@ func Load() (*LoadResult, error) {
 	}, nil
 }
 
-// applyYAML reads an optional config.yaml and overlays it onto cfg.
+// configFilePaths are searched in order; the first readable file wins.
+var configFilePaths = []string{
+	"config/config.yaml",
+	"config.yaml",
+}
+
+const envConfigStrict = "CONFIG_STRICT"
+
+// resolveConfigStrict reads CONFIG_STRICT, which defaults to true: an unknown key
+// in declarative config aborts startup rather than being ignored, because a
+// dropped providers, rate_limits, budgets, or guardrails entry silently changes
+// routing, cost, or security. Set it to false to downgrade unknown keys to
+// warnings — useful when rolling a binary back under a newer config file.
+//
+// It is read directly from the environment because it governs the parse of the
+// YAML layer, which runs before the env-tag overrides are applied.
+func resolveConfigStrict() (bool, error) {
+	raw := strings.TrimSpace(os.Getenv(envConfigStrict))
+	if raw == "" {
+		return true, nil
+	}
+	strict, err := strconv.ParseBool(raw)
+	if err != nil {
+		return false, fmt.Errorf("invalid %s: %q is not a boolean", envConfigStrict, raw)
+	}
+	if !strict {
+		slog.Warn("CONFIG_STRICT=false: unknown config keys are ignored with a warning instead of aborting startup")
+	}
+	return strict, nil
+}
+
+// applyYAML reads an optional config file and overlays it onto cfg.
 // Returns the raw provider map parsed from the providers: YAML section.
 // If no config file is found, this is a no-op (not an error).
-func applyYAML(cfg *Config) (map[string]RawProviderConfig, error) {
-	paths := []string{
-		"config/config.yaml",
-		"config.yaml",
-	}
-
-	var data []byte
-	for _, p := range paths {
-		raw, err := os.ReadFile(p)
-		if err == nil {
-			data = raw
-			break
-		}
+//
+// When strict, an unknown key is an error rather than a silently ignored one. A
+// misindented section — the classic `providers:` followed by entries at column
+// zero — otherwise parses as a null section plus unknown top-level keys, and the
+// gateway boots with none of the operator's providers. CONFIG_STRICT=false
+// downgrades unknown keys to warnings; malformed values stay fatal either way.
+func applyYAML(cfg *Config, strict bool) (map[string]RawProviderConfig, error) {
+	path, data, err := readConfigFile()
+	if err != nil {
+		return nil, err
 	}
-
-	rawProviders := make(map[string]RawProviderConfig)
-
 	if data == nil {
-		return rawProviders, nil
+		slog.Info("no config file found; using defaults and environment", "searched", configFilePaths)
+		return map[string]RawProviderConfig{}, nil
 	}
 
-	expanded := expandString(string(data))
-
 	// yamlTarget is a local struct that mirrors Config for YAML unmarshaling,
 	// using RawProviderConfig for providers so nullable resilience overrides are preserved.
 	type yamlTarget struct {
@@ -259,13 +295,121 @@ func applyYAML(cfg *Config) (map[string]RawProviderConfig, error) {
 	}
 
 	target := yamlTarget{Config: cfg}
-	if err := yaml.Unmarshal([]byte(expanded), &target); err != nil {
-		return nil, fmt.Errorf("failed to parse config.yaml: %w", err)
+	decoder := yaml.NewDecoder(strings.NewReader(expandString(string(data))))
+	// Unknown keys are always detected. Whether they are fatal is decided below,
+	// so the lax mode can still name each one instead of dropping it in silence.
+	decoder.KnownFields(true)
+	// A file holding only comments decodes to nothing; that is an empty overlay,
+	// not a failure.
+	decodeErr := decoder.Decode(&target)
+	if decodeErr != nil && !errors.Is(decodeErr, io.EOF) {
+		if err := reportYAMLDecodeError(path, decodeErr, strict); err != nil {
+			return nil, err
+		}
 	}
+	if err := ensureSingleDocument(path, decoder); err != nil {
+		return nil, err
+	}
+
+	slog.Info("config file loaded", "path", path, "providers", len(target.RawProviders))
 
-	if target.RawProviders != nil {
-		rawProviders = target.RawProviders
+	if target.RawProviders == nil {
+		return map[string]RawProviderConfig{}, nil
 	}
+	return target.RawProviders, nil
+}
+
+// ensureSingleDocument rejects a config file holding more than one YAML document.
+// The decoder reads only the first, so everything after a `---` separator would be
+// applied nowhere — the same silent loss a misindented section causes. Decoding into
+// a yaml.Node accepts any shape, so this detects a second document without
+// re-triggering the unknown-key check. A structural fault, fatal regardless of
+// CONFIG_STRICT.
+func ensureSingleDocument(path string, decoder *yaml.Decoder) error {
+	var extra yaml.Node
+	err := decoder.Decode(&extra)
+	if errors.Is(err, io.EOF) {
+		return nil
+	}
+	if err != nil {
+		return formatYAMLError(path, err)
+	}
+	return fmt.Errorf("failed to parse %s: only one YAML document is supported, found another after a '---' separator", path)
+}
+
+// reportYAMLDecodeError decides the fate of a decode error. Unknown keys are fatal
+// when strict and warnings otherwise; every other problem — a malformed value, a
+// syntax error — is fatal regardless, because CONFIG_STRICT relaxes what the schema
+// accepts, not whether the file makes sense. Returns nil when nothing is fatal.
+func reportYAMLDecodeError(path string, err error, strict bool) error {
+	var typeErr *yaml.TypeError
+	if strict || !errors.As(err, &typeErr) {
+		return formatYAMLError(path, err)
+	}
+
+	var fatal []string
+	for _, message := range typeErr.Errors {
+		line, field, ok := parseUnknownFieldMessage(message)
+		if !ok {
+			fatal = append(fatal, message)
+			continue
+		}
+		slog.Warn("unknown config key ignored; it has no effect",
+			"path", path, "line", line, "field", field)
+	}
+	if len(fatal) > 0 {
+		return formatYAMLError(path, &yaml.TypeError{Errors: fatal})
+	}
+	return nil
+}
+
+// unknownFieldMessage matches yaml.v3's unknown-key message, the only decode error
+// CONFIG_STRICT=false is allowed to downgrade.
+var unknownFieldMessage = regexp.MustCompile(`^line (\d+): field (\S+) not found in type \S+$`)
+
+func parseUnknownFieldMessage(message string) (line int, field string, ok bool) {
+	match := unknownFieldMessage.FindStringSubmatch(message)
+	if match == nil {
+		return 0, "", false
+	}
+	line, err := strconv.Atoi(match[1])
+	if err != nil {
+		return 0, "", false
+	}
+	return line, match[2], true
+}
+
+// readConfigFile returns the first config file that exists and its contents, or an
+// empty path and nil contents when none does. A file that exists but cannot be read
+// — wrong permissions, or a directory mounted where a file was expected — is an
+// error, not a missing file: silently falling back to defaults is how a
+// misconfigured deployment boots with no providers.
+func readConfigFile() (string, []byte, error) {
+	for _, path := range configFilePaths {
+		data, err := os.ReadFile(path)
+		switch {
+		case err == nil:
+			return path, data, nil
+		case errors.Is(err, fs.ErrNotExist):
+			continue
+		default:
+			return "", nil, fmt.Errorf("failed to read %s: %w", path, err)
+		}
+	}
+	return "", nil, nil
+}
+
+// yamlTypeSuffix matches the Go type name yaml.v3 appends to unknown-field errors
+// ("field foo not found in type config.yamlTarget"). It names an internal struct
+// the operator cannot act on, so it is stripped.
+var yamlTypeSuffix = regexp.MustCompile(` in type \S+`)
 
-	return rawProviders, nil
+// formatYAMLError rewrites a yaml.v3 decode error into a single actionable line
+// prefixed with the offending file.
+func formatYAMLError(path string, err error) error {
+	msg := yamlTypeSuffix.ReplaceAllString(err.Error(), "")
+	msg = strings.TrimPrefix(msg, "yaml: unmarshal errors:\n")
+	msg = strings.TrimPrefix(msg, "yaml: ")
+	msg = strings.ReplaceAll(msg, "\n  ", "; ")
+	return fmt.Errorf("failed to parse %s: %s", path, strings.TrimSpace(msg))
 }