fix(auth): a validator whose issuer is down at boot is built anyway

Closes #4. Closes gitea-mcp#57.

Filed 2026-07-17, filed again 2026-09-07, recurred 2026-09-14. Each occurrence
ended with a human running `kubectl rollout restart`; the last one ran for six
days and was found by chance while gathering context for unrelated work.

THE BUG

NewMultiJWTValidator resolved OIDC discovery eagerly and returned (nil, err) if
the issuer was not answering. BearerMiddleware reads a nil validator as "this
server does not do JWT auth", so it fell through to the static-token comparison
and rejected every Authentik JWT:

    WARN mcp auth rejected reason=static_token_mismatch token_type=jwt status=401

Two states collapsed into one nil:

    static-token-only by design      -> nil   correct
    JWT required, IdP down at boot   -> nil   wrong, and permanent

Permanent because discovery was attempted exactly once, at construction.

WHY THE FIX IS SMALL

Everything downstream was already right. Validate distinguishes ErrUnavailable
(issuer unreachable -> 503, client retries) from a definitive rejection (-> 401),
and BearerMiddleware already honours that — gitea-mcp#6 got it right. That path
was simply unreachable when the validator was never built.

So: build it anyway. jwks_uri now resolves lazily on first use and re-resolves on
failure, no sooner than WithRetryInterval apart (default 30s) so a down issuer
costs one discovery request per interval, not one per request. Until it resolves,
Validate returns ErrUnavailable and the existing machinery does the rest. The
constructor still warms discovery eagerly on a healthy start; it just no longer
fails on it.

Ready(ctx) reports whether every issuer resolved, and attempts resolution for any
that have not. That makes a readiness probe the retry loop — no background
goroutine, no context to leak, and the platform's own cadence drives recovery.
A nil validator is Ready: "JWT auth disabled" is a configuration, not a fault.

WHAT DID NOT CHANGE

No issuer configured still returns (nil, nil). That is the one case where nil is
not a lie, and collapsing it would turn every static-only server into a JWT
server. Pinned by TestNewMultiJWTValidator_NoIssuer_StillReturnsNilNil.

ONE EXISTING TEST CHANGED ITS MECHANISM, NOT ITS CLAIM

TestNewMultiJWTValidator_UsesPerIssuerHTTPClientForAuthedFetch asserted that the
constructor ERRORS when discovery 401s without the fetch credential. It cannot,
now, by design. Rewritten to assert the property that actually mattered, and
more directly than before: without the credential the validator is not Ready AND
a correctly-minted token from that very issuer is refused as ErrUnavailable. The
old test only checked that a constructor returned an error.

Written test-first: jwt_bootrace_test.go red (API absent), then green. Also red
in the behavioural sense — the constructor-errors assertion above had to be
rewritten precisely because the semantics genuinely changed.

Verified: golangci-lint 0 issues; go vet clean; go test -race -count=1 ./... ok.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

auth/jwt_test.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"sync"
 	"testing"
 	"time"
 
@@ -24,12 +25,37 @@ type testIssuer struct {
 	url           string
 	priv          jwk.Key
 	requireBearer string // if set, discovery+JWKS return 401 without this bearer
+
+	// mu guards the boot-race fields below, which a test mutates while the
+	// httptest server is serving.
+	mu sync.Mutex
+	// discoveryFailures is how many initial discovery requests answer 503 —
+	// the IdP-not-yet-serving case that disabled OAuth for six days
+	// (mcp-chassis#4, gitea-mcp#57).
+	discoveryFailures int
+	discoveryHits     int
 }
 
 func (ti *testIssuer) authed(r *http.Request) bool {
 	return ti.requireBearer == "" || r.Header.Get("Authorization") == "Bearer "+ti.requireBearer
 }
 
+// discoveryDown reports whether this discovery request should answer 503, and
+// counts the attempt. Attempts are counted even while down, so a test can assert
+// that resolution was RETRIED rather than cached as a permanent failure.
+func (ti *testIssuer) discoveryDown() bool {
+	ti.mu.Lock()
+	defer ti.mu.Unlock()
+	ti.discoveryHits++
+	return ti.discoveryHits <= ti.discoveryFailures
+}
+
+func (ti *testIssuer) discoveryAttempts() int {
+	ti.mu.Lock()
+	defer ti.mu.Unlock()
+	return ti.discoveryHits
+}
+
 // bearerRT adds a static Authorization header to every request — a minimal stand-in
 // for the in-cluster case where the JWKS fetch carries the pod's SA token.
 type bearerRT struct{ token string }
@@ -62,6 +88,10 @@ func newTestIssuer(t *testing.T) *testIssuer {
 		_ = json.NewEncoder(w).Encode(set)
 	})
 	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, r *http.Request) {
+		if ti.discoveryDown() {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
 		if !ti.authed(r) {
 			w.WriteHeader(http.StatusUnauthorized)
 			return
@@ -172,9 +202,29 @@ func TestNewMultiJWTValidator_UsesPerIssuerHTTPClientForAuthedFetch(t *testing.T
 	iss := newTestIssuer(t)
 	iss.requireBearer = "fetch-secret" // discovery + JWKS now demand this bearer
 
-	// nil client (http.DefaultClient, no credential) → discovery 401 → build fails.
-	_, err := NewMultiJWTValidator(ctx, []IssuerConfig{{IssuerURL: iss.url, Audience: "sa-poc"}})
-	require.Error(t, err, "unauthenticated fetch must fail against an auth-gated issuer")
+	// nil client (http.DefaultClient, no credential) → discovery 401 → the issuer
+	// never resolves.
+	//
+	// This used to assert that the CONSTRUCTOR errored. It no longer does: since
+	// mcp-chassis#4, construction cannot fail on an unreachable issuer, because
+	// "could not resolve" and "JWT auth not wanted" must stop collapsing into the
+	// same nil. The property that actually matters is unchanged and asserted more
+	// directly here — without the credential, a correctly-minted token from this
+	// very issuer still gets nowhere, and the validator says it is not ready.
+	unauth, err := NewMultiJWTValidator(ctx,
+		[]IssuerConfig{{IssuerURL: iss.url, Audience: "sa-poc"}},
+		WithRetryInterval(0),
+	)
+	require.NoError(t, err)
+	require.NotNil(t, unauth)
+
+	ready, why := unauth.Ready(ctx)
+	require.False(t, ready, "an issuer whose discovery 401s is not ready")
+	require.Error(t, why)
+
+	_, err = unauth.Validate(ctx, iss.mint(t, "sa-poc", "poc-pod"))
+	require.Error(t, err, "unauthenticated fetch must authenticate nobody, even with a genuine token")
+	require.ErrorIs(t, err, ErrUnavailable)
 
 	// A client that presents the fetch credential → build succeeds, token validates.
 	client := &http.Client{Transport: bearerRT{token: "fetch-secret"}}