ADR-006: auth posture for non-loopback deploy + token rotation impl

ADR-003 locked the auth substrate; ADR-006 ratifies the operator
playbook + adds two implementation pieces needed for Sprint 4
deployment: env-resolved tokens and dual-token rotation.

Six decisions locked in docs/DECISIONS.md:
- 6.1: Non-loopback bind requires auth.token (mechanical gate at
       shared.Run, already implemented; this ratifies it).
- 6.2: Token from env, not TOML. /etc/lakehouse/auth.env (mode 0600)
       loaded by systemd EnvironmentFile=. New TokenEnv field on
       AuthConfig defaults to "AUTH_TOKEN".
- 6.3: AllowedIPs for inter-service same-trust-domain; Token for
       cross-trust-boundary (gateway ↔ external).
- 6.4: /health stays unauthenticated; everything else under
       shared.Run is gated. Already implemented; ratified here.
- 6.5: Token rotation is dual-token. New SecondaryTokens []string
       on AuthConfig — both primary and any secondary pass auth
       during the rotation window. Implemented in this commit.
- 6.6: TLS terminates at the network edge (nginx/Caddy), not
       in-process. Daemons stay HTTP-only; internal traffic stays
       on private subnets per Decision 6.3.

Implementation:
- internal/shared/config.go: AuthConfig gains TokenEnv +
  SecondaryTokens fields. New resolveAuthFromEnv() called by
  LoadConfig fills Token from os.Getenv(TokenEnv) when Token is
  empty. TokenEnv defaults to "AUTH_TOKEN" so the happy path needs
  no TOML config.
- internal/shared/auth.go: RequireAuth pre-encodes Bearer headers
  for primary + every secondary token; per-request constant-time
  compare walks the slice. Fast path is 1 compare (primary).

Tests:
- TestLoadConfig_AuthTokenFromEnv (3 sub-tests): default env name,
  custom token_env, explicit Token wins over env.
- TestRequireAuth_SecondaryTokenAccepted: both primary + secondary
  tokens pass during rotation window.
- TestRequireAuth_SecondaryTokensOnly: only-secondary path works
  for the case where primary was just promoted-to-empty mid-rotation.

go test ./internal/shared all green; existing auth_test.go
unchanged (constant-time compare path preserved).

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

docs/DECISIONS.md

@@ -500,3 +500,159 @@ invariants before the next consumer (scrum runner, distillation rebuild,
 or a real production workflow) takes a hard behavioral dependency.
 
 ---
+
+## ADR-006: Auth posture for non-loopback deploy
+
+**Date:** 2026-04-30
+**Status:** RATIFIED
+**Scope:** `internal/shared/auth.go` + `internal/shared/bind.go` + every `cmd/<bin>/main.go`'s `shared.Run` call site
+
+ADR-003 locked the substrate (Bearer token + IP allowlist, opt-in via
+`cfg.Auth.Token`/`cfg.Auth.AllowedIPs`, `/health` exempt). ADR-006
+ratifies the **operator playbook + deploy-time invariants** — what
+gets enforced when, what operators set where, what happens when keys
+rotate. Required because Sprint 4 deployment work (REPLICATION.md,
+systemd units, Dockerfile) needs a locked auth posture before it
+touches production-shaped configs.
+
+### Decision 6.1 — Non-loopback bind requires `auth.token`; the gate is mechanical
+
+Already implemented in `requireAuthOnNonLoopback` (`internal/shared/bind.go:58-67`).
+Locked:
+
+- Any binary that binds anything other than `127.0.0.0/8` / `::1` /
+  `localhost` MUST have `cfg.Auth.Token != ""`. Empty-token +
+  non-loopback-bind = startup error, not silent insecure mode.
+- The check fires in `shared.Run` BEFORE `http.Server.Serve`, so a
+  misconfigured binary fails fast at startup rather than serving
+  one request.
+- Pairs with `requireLoopbackOrOverride`: that gate refuses any
+  non-loopback bind without `LH_<NAME>_ALLOW_NONLOOPBACK=1`. Together
+  they make the audit's R-001+R-007 worst case (queryd `/sql` =
+  RCE-equivalent off-loopback with no auth) mechanically impossible.
+
+**Why mechanical, not policy:** policy gates rely on operator
+discipline. The substrate gates work even when an operator copies a
+dev `lakehouse.toml` into prod and forgets to set the token —
+binary refuses to start, error message names the env override.
+
+### Decision 6.2 — Token comes from `cfg.Auth.Token` populated by env or secrets file
+
+Locked:
+
+- Operators do NOT put the production token in `lakehouse.toml`
+  directly. The TOML field is empty in the committed file; the
+  daemon's systemd unit sets `AUTH_TOKEN` (or whatever
+  `cfg.Auth.TokenEnv` names) via `EnvironmentFile=` pointing at
+  `/etc/lakehouse/auth.env` (mode 0600, root-owned).
+- Same pattern as `chatd`'s provider keys (`OPENROUTER_API_KEY` etc.):
+  TOML names the env var, systemd loads the env file.
+- Justification: keeps secrets out of git + out of the running
+  process's command line + audit-able via filesystem ACLs.
+
+### Decision 6.3 — `AllowedIPs` is the inter-service gate; `Token` is the cross-trust-boundary gate
+
+Locked:
+
+- Same-box deploys (10 daemons all on one host, all on `127.0.0.0/8`
+  or a private subnet) use **`AllowedIPs` only**. Each daemon's
+  `cfg.Auth.AllowedIPs` lists the gateway's address (and any other
+  daemon that legitimately calls it). No token shared between
+  internal services.
+- Gateway-to-external traffic (a coordinator UI in another VPC,
+  a user's browser, an external integrator) goes through
+  **Bearer token**. The token is per-tenant; rotation is per-tenant.
+- Mixed: a service can require BOTH (allowlist AND token) — the
+  middleware logic is `allowed = ip_allowed && token_valid` when
+  both are set. Use this for the gateway when binding non-loopback.
+
+**Why split:** token rotation is operationally expensive (every
+caller updates a secret). IP allowlist rotation is free if the
+network topology is stable. Splitting them by trust boundary lets
+internal services treat allowlist drift as a network change while
+external callers handle token rotation as a credential change.
+
+### Decision 6.4 — `/health` is unauthenticated; everything else under `shared.Run` is gated
+
+Already implemented (`internal/shared/server.go:84-92`). Locked:
+
+- Load balancers + monitor probes hit `/health` without a token.
+  The route returns `{"status":"ok","service":"<name>"}` and nothing
+  about service state — no version, no commit, no internal counts.
+- Every other route registered via `shared.Run`'s `register`
+  callback lives inside the auth-gated chi.Group. New routes
+  inherit auth automatically; new daemons inherit it via `shared.Run`.
+- A daemon that needs a public route MUST add it to the outer router
+  before the `register` group, with a code comment explaining the
+  exemption. There are no others today.
+
+### Decision 6.5 — Token rotation is operator-staged; old + new accepted during the window
+
+Not yet implemented; locked as a Sprint 4 follow-up:
+
+- Operators stage a rotation by adding a second token to
+  `cfg.Auth.SecondaryTokens []string`. Both primary and secondary
+  pass auth during the window.
+- After every caller is updated to the new token, operators
+  promote secondary → primary and clear secondary. A second
+  rotation can begin.
+- Rolling restart not required; daemons reload `cfg.Auth` on
+  SIGHUP (also a Sprint 4 follow-up — currently they re-read on
+  restart only).
+
+**Why dual-token instead of just single-rotation:** caller pool can be
+large (gateway + observerd + scrum runner + UI + external integrators).
+A single-token rotation forces a flag-day. Dual-token windows let
+operators rotate gradually and abort on failure.
+
+### Decision 6.6 — TLS is the network operator's job, not ours
+
+Locked:
+
+- Daemons speak HTTP, not HTTPS. TLS termination happens at the
+  network edge (nginx / Caddy / cloud LB), not in the Go process.
+- Internal daemon-to-daemon traffic stays on plaintext HTTP because
+  it's all on `127.0.0.0/8` or a private subnet (per Decision 6.3).
+- Justification: TLS in-process means cert management, rotation,
+  reload — all undifferentiated lift that nginx already solves
+  better. The Bearer token + allowlist gates are sufficient when
+  combined with a TLS-terminating reverse proxy.
+
+### Alternatives considered
+
+- **mTLS for inter-service auth** — every daemon issues + verifies
+  certs. Solves token-rotation pain but adds cert lifecycle as a
+  problem. Allowlist + plaintext on the private network is cheaper
+  and gets the same threat-model coverage.
+- **JWT-only** — JWTs let callers carry richer claims (tenant id,
+  expiry, scopes). Overkill for the current threat model; the
+  Bearer token + allowlist split is honest about what each layer
+  actually defends against. Revisit when multi-tenant gateway
+  features land.
+- **No auth, network is the boundary** — works for G0 dev and the
+  current single-box deployment. ADR-006 explicitly does NOT
+  recommend this for non-loopback prod (the mechanical gate
+  refuses it).
+
+### What this ADR does NOT do
+
+- **Does not specify how the gateway authenticates external callers.**
+  Token-vs-mTLS-vs-OAuth at the public edge is a separate decision
+  driven by who-calls-us. ADR-006 is about the inter-service +
+  same-trust-domain posture.
+- **Does not implement token rotation hot-reload.** Decision 6.5
+  documents the design; the implementation is Sprint 4 work.
+- **Does not lock TLS termination details.** Where + how nginx/Caddy
+  goes is ops infrastructure, not ADR territory.
+
+### How this closes the OPEN list
+
+STATE_OF_PLAY listed ADR-006 as the gate before any Go binary binds
+non-loopback in prod. The substrate gates were already present (R-001
++ R-007 enforced via `requireLoopbackOrOverride` +
+`requireAuthOnNonLoopback`); this ADR locks the operator playbook
+that turns those gates into a deployable posture. Sprint 4 can now
+write systemd units that set `AUTH_TOKEN` from `EnvironmentFile=`
+without re-litigating the design.
+
+---