ADR-0036: server.apiAuth is required — unsecured is an explicit opt-in
Context and Problem Statement
Server.apiAuth defaulted to AuthConfig.Unsecured. A config that omitted the field — a fresh minimal config, a typo'd key swallowed by the YAML parser's sibling defaults, a copy-paste that dropped the block — silently exposed every API endpoint (including agent execution and, with the console routes, agent file editing) without any authentication. The only signal was a startup WARN banner in app.log that nothing forces an operator to read.
Security scanning ("Unsecured Default API Authentication", risk 7.2) flagged the insecure-by-default posture: the absence of configuration should never select the weakest mode.
Decision Drivers
- Secure by default: forgetting a key must fail loudly, not open the API.
- Unsecured mode is still legitimate (local development, trusted networks) and must remain available — but as a visible, deliberate choice in the config.
- The fix must not change behavior for any config that already sets
apiAuth(all known real deployments do). - Mirror the established fail-fast pattern: startup validators throwing
ConfigurationException(ADR-0016 CORS-for-cookie-auth, HMAC signature scope, session-secret strength).
Considered Options
- Nullable
apiAuth+ startup validator —nullmeans "omitted", startup fails; explicit!<unsecured>still parses toUnsecuredand runs. - Keep the default, WARN harder — no contract change, but the failure mode (silently open API) survives; a louder log is still ignorable.
- Sentinel
AuthConfig.Unspecifieddefault — avoids the nullable type, but adds a fake variant to the public sealed API that config authors could name. - Remove
Unsecuredentirely — breaks local development and theagentdebug-style workflows for no security gain over explicit opt-in.
Decision Outcome
Nullable field + startup validator:
Server.apiAuth: AuthConfig? = null. Deserialization distinguishes an omitted field (null) from an explicitapiAuth: !<unsecured>(AuthConfig.Unsecured).validateExplicitApiAuthfails startup onnull,firstsecond among the validators inconfigureServer(amended 2026-10-09: it runs after ADR-0037'svalidateNoLegacyEndpoints), with a message that shows both remedies (configure a scheme, or write the explicit!<unsecured>opt-in).- Explicit
Unsecuredis unchanged: it runs and keeps the startup WARN banner. - Schema contract:
serverandserver.apiAutharerequiredinhomer-config.schema.json, so editors flag the omission before deploy. flattenAuthSchemes(null)returns no schemes — reachable only in tests, since the validator aborts boot before any scheme is consulted.
Consequences
- Good: a forgotten or mistyped
apiAuthblock is a hard startup error with a copy-pasteable fix, not a silently open API. - Good: existing configs that set
apiAuth(any scheme, including explicitunsecured) are byte-for-byte unaffected. - Bad: breaking for configs that relied on the implicit default — they must add
apiAuth: !<unsecured>(or a real scheme) to boot. This is the point of the change; the migration is one line and named in the error message. - Neutral: minimal configs now always contain a
serverblock, which the schema now requires.