feat: pluggable authentication — static keys + OIDC + sidecar broker (closes SKA-275)

[mfacenet]

Summary

Closes the auth gap that left the API server accepting unauthenticated requests after K8sLeaseStore made it deployable. Lands all three pieces of the auth story together so the operational picture is reviewable end-to-end.

Commit	Ticket	What it does
44463fd	SKA-278	Hash-backed static API keys + AuthMiddleware + SIGHUP reload. Foundational; defines the Authenticator interface used by everything below.
0e1f3df	SKA-279	Server-side OIDC authenticator for any third-party IdP (Okta, PingFederate, Entra/Azure AD, Auth0, Dex, Keycloak, AWS Cognito, GitHub OIDC, etc.).
6cf4dd9	SKA-283	Operator-side: --berth-api-key-file with reload + cmd/berth-oidc-broker reference token broker for the sidecar pattern.

Together these close SKA-275 (the parent — pluggable authentication for the Berth API server). SKA-280 (SPIFFE/SPIRE) remains explicitly long-term-deferred.

End-to-end flow this enables

Okta / PingFederate / Entra / Auth0
            │ client_credentials
            ▼
┌────────────────────┐    writes JWT     ┌────────────────────┐
│ berth-oidc-broker  │ ─── (atomic) ───▶ │ /var/run/berth/    │
│ (sidecar)          │   to shared vol   │  token             │
└────────────────────┘                   └────────────────────┘
                                                   │
                                                   │ --berth-api-key-file
                                                   ▼
                                         ┌────────────────────┐
                                         │ berth-operator     │
                                         │ (1s cache TTL,     │
                                         │  picks up rotation)│
                                         └────────────────────┘
                                                   │ Bearer JWT
                                                   ▼
                                         ┌────────────────────┐
                                         │ berth-apiserver    │
                                         │ --auth-mode=oidc   │
                                         │ validates iss/aud/ │
                                         │ exp/sig/claims     │
                                         └────────────────────┘

Result: cross-cluster operator auth with no long-lived secret on the operator side beyond the IdP's client-credentials Secret. Token rotation is non-disruptive (the operator's FileTokenSource re-reads on a 1-second cache TTL; the broker's atomic write means readers never see partial files).

Auth modes available

--auth-mode= selects between three implementations of the Authenticator interface in internal/auth:

• none — accepts every request. Logs a loud WARN at startup. Default only when --coordination-namespace is empty (i.e., dev mode using the in-memory store).
• static-keys — file of <key-id>:<sha256-hex> entries, hashed at rest. SIGHUP reloads in place; preserve-on-error means a botched edit can't lock you out.
• oidc — JWT validation against an OIDC provider's JWKS. Supports --oidc-required-claim=key=value for coarse authorization, custom username/tenant claim mapping, and JWKS URL override.

Switching backends is config-only — no code change required.

Operator changes

• New --berth-api-key-file <path> flag, mutually exclusive with --berth-api-key. Existing static-key callers see no behavior change.
• New internal/operator.FileTokenSource reads the file with a small (1s) cache and returns the previously-cached value on transient read errors so a sidecar restart doesn't take down the reconcile loop.

Reference broker

cmd/berth-oidc-broker (~250 LOC) is a small purpose-built sidecar:

• Discovers the IdP's token endpoint via OIDC.
• OAuth2 client-credentials grant (with audience form parameter for Auth0/some Okta setups, scopes for everything else).
• Atomic writes to the shared volume (temp file + rename, mode 0600 — readers never see a partial file).
• Refreshes well before expiry; retries on a min-refresh cadence on failure so a transient IdP outage doesn't tear down the broker.

For exotic flows (token exchange, mTLS-bound tokens) users can substitute their own broker — the operator only cares that the file at --berth-api-key-file contains a valid bearer token.

Test plan

• go test ./... -race -count=1 — all packages green
• make lint — golangci-lint + go vet clean
• make build — all four binaries (apiserver, operator, berth, berth-oidc-broker) build
• Each commit on the branch builds and tests in isolation
• OIDC tests verify: happy path, expired tokens, wrong audience/issuer, bad signature (token signed with a key not in the JWKS), required-claim enforcement (string + array forms), custom claim mapping, generic-error oracle resistance, unreachable-issuer fast-fail
• Static keys tests verify: hashing on construction, file format parsing (with rejection for malformed lines, duplicate hashes, etc.), SIGHUP-equivalent reload preserves old state on parse error, generic error message
• Broker tests verify: arg validation, secret loading from literal vs file, token-URL discovery vs override, refresh-interval math, atomic writes (no leftover temp files), end-to-end run-loop against a fake token endpoint
• Operator file token source tests verify: missing file fast-fail, empty-file rejection, whitespace trim, rotation pickup after TTL, read-error fallback to cached value
• Manual integration against a real Okta/PingFederate tenant — deferred to SKA-276 (e2e tests)

Out of scope

• SPIFFE/SPIRE — SKA-280, explicitly long-term-deferred. mTLS via the SPIFFE Workload API would remove the IdP client-credentials secret entirely but adds significant infra (SPIRE server + agents on every cluster). Revisit when one of the trigger conditions in SKA-280 fires.
• Helm chart wiring for the new flags — SKA-281 / SKA-282.
• OAuth2 chained authenticators (try OIDC, fall back to static-keys) — possible follow-up; v1 makes them mutually exclusive.

Files of note

• internal/auth/static.go — hash-backed static key authenticator
• internal/auth/oidc.go — go-oidc-backed JWT validator
• internal/auth/noauth.go — NoOpAuthenticator for tests/composition
• internal/api/middleware.go — AuthMiddleware, IdentityFromContext
• internal/operator/tokensource.go — FileTokenSource for the operator
• pkg/client/options.go — WithAPIKey (back-compat) + new WithAPIKeyFunc
• cmd/berth-oidc-broker/main.go — reference sidecar broker
• cmd/apiserver/main.go — --auth-mode + --api-keys-file + all --oidc-* flags
• cmd/operator/main.go — --berth-api-key-file + mutual-exclusion check
• README.md — Authentication section with Okta/PingFederate/Entra walkthroughs and the sidecar pod sketch