Address tgrunnagle feedback on CIMD wiring

C1 - Fix CacheFallbackTTL to string in CIMDRunConfig so YAML/JSON
     operators can write "5m" instead of nanoseconds. resolveCIMDConfig
     parses it with time.ParseDuration at runtime.
C6 - Add slog.Debug when applyDefaults substitutes CIMD defaults,
     matching the pattern used by the sibling token-lifespan defaults.
C7 - Add CIMDRunConfig.Validate() and call it from RunConfig.Validate()
     so CIMD misconfiguration fails at the wire-format boundary before
     the runner resolves secrets.
C10 - Add test cases to TestConfigValidate and TestRunConfigValidate
      covering all new CIMD validation paths.
C11 - Add TestNewServer_CIMDEnabled_WrapsStorage: verifies the CIMD
      decorator is actually installed in the storage chain when
      CIMDEnabled=true.
C12 - Add comment in discovery.go explaining why
      client_id_metadata_document_supported is in OIDC discovery.
C13 - Add doc comment on server.storage noting it may be decorated.
C14 - Add note to IsClientIDMetadataDocumentURL about pkg/auth/remote
      callers and why the loopback widening is safe there.

Regenerate swagger docs: CacheFallbackTTL now serialises as string.

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

Author: amirejaz

docs/server/docs.go

@@ -102,6 +102,11 @@ type RunConfig struct {
 // catches operator-supplied misconfiguration early so server startup fails
 // loudly instead of degrading silently at runtime.
 func (c *RunConfig) Validate() error {
+	if c.CIMD != nil {
+		if err := c.CIMD.Validate(); err != nil {
+			return fmt.Errorf("cimd: %w", err)
+		}
+	}
 	return c.validateBaselineClientScopes()
 }
 
@@ -138,9 +143,29 @@ type CIMDRunConfig struct {
 
 	// CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
 	// Cache-Control header parsing is not yet implemented; all entries use this value.
-	// Defaults to 5 minutes when Enabled is true and this field is zero.
-	//nolint:lll // field tags require full JSON+YAML names
-	CacheFallbackTTL time.Duration `json:"cache_fallback_ttl,omitempty" yaml:"cache_fallback_ttl,omitempty" swaggertype:"string" example:"5m"`
+	// Format: Go duration string (e.g. "5m", "10m", "1h").
+	// Defaults to 5 minutes when Enabled is true and this field is omitted.
+	CacheFallbackTTL string `json:"cache_fallback_ttl,omitempty" yaml:"cache_fallback_ttl,omitempty" example:"5m"`
+}
+
+// Validate checks that the CIMDRunConfig fields are internally consistent.
+func (c *CIMDRunConfig) Validate() error {
+	if !c.Enabled {
+		return nil
+	}
+	if c.CacheMaxSize < 0 {
+		return fmt.Errorf("cache_max_size must be non-negative when CIMD is enabled, got %d", c.CacheMaxSize)
+	}
+	if c.CacheFallbackTTL != "" {
+		d, err := time.ParseDuration(c.CacheFallbackTTL)
+		if err != nil {
+			return fmt.Errorf("cache_fallback_ttl: %w", err)
+		}
+		if d < 0 {
+			return fmt.Errorf("cache_fallback_ttl must be non-negative when CIMD is enabled, got %s", c.CacheFallbackTTL)
+		}
+	}
+	return nil
 }
 
 // SigningKeyRunConfig configures where to load signing keys from.
@@ -867,9 +892,11 @@ func (c *Config) applyDefaults() error {
 	}
 	if c.CIMDEnabled && c.CIMDCacheMaxSize == 0 {
 		c.CIMDCacheMaxSize = 256
+		slog.Debug("applied default cimd cache_max_size", "size", c.CIMDCacheMaxSize)
 	}
 	if c.CIMDEnabled && c.CIMDCacheFallbackTTL == 0 {
 		c.CIMDCacheFallbackTTL = 5 * time.Minute
+		slog.Debug("applied default cimd cache_fallback_ttl", "ttl", c.CIMDCacheFallbackTTL)
 	}
 	return nil
 }

docs/server/swagger.json

@@ -114,6 +114,13 @@ func TestConfigValidate(t *testing.T) {
 		{name: "baseline scope not in scopes_supported", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, ScopesSupported: []string{"openid"}, BaselineClientScopes: []string{"offline_access"}}, wantErr: true, errMsg: `baseline_client_scopes contains "offline_access"`},
 		{name: "nil supported with baseline in DefaultScopes passes", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, ScopesSupported: nil, BaselineClientScopes: []string{"offline_access"}}},
 
+		// CIMD validation
+		{name: "CIMD enabled zero cache_max_size rejected", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, CIMDEnabled: true, CIMDCacheMaxSize: 0}, wantErr: true, errMsg: "cache_max_size must be >= 1"},
+		{name: "CIMD enabled negative cache_max_size rejected", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, CIMDEnabled: true, CIMDCacheMaxSize: -1}, wantErr: true, errMsg: "cache_max_size must be >= 1"},
+		{name: "CIMD enabled negative cache_fallback_ttl rejected", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, CIMDEnabled: true, CIMDCacheMaxSize: 256, CIMDCacheFallbackTTL: -time.Second}, wantErr: true, errMsg: "cache_fallback_ttl must be non-negative"},
+		{name: "CIMD disabled ignores invalid cache fields", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, CIMDEnabled: false, CIMDCacheMaxSize: -1, CIMDCacheFallbackTTL: -time.Second}},
+		{name: "CIMD enabled with valid bounds passes", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}, CIMDEnabled: true, CIMDCacheMaxSize: 256, CIMDCacheFallbackTTL: 5 * time.Minute}},
+
 		// Valid configs
 		{name: "valid minimal", config: Config{Issuer: "https://example.com", KeyProvider: validKeyProvider, HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}}},
 		{name: "valid nil key provider", config: Config{Issuer: "https://example.com", HMACSecrets: validHMAC, Upstreams: validUpstreams, AllowedAudiences: []string{"https://mcp.example.com"}}},
@@ -431,6 +438,14 @@ func TestRunConfigValidate(t *testing.T) {
 			wantErr: true,
 			errMsg:  "foo",
 		},
+		// CIMD RunConfig validation
+		{name: "CIMD nil passes", config: RunConfig{CIMD: nil}},
+		{name: "CIMD disabled passes even with invalid fields", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: false, CacheMaxSize: -1, CacheFallbackTTL: "-1s"}}},
+		{name: "CIMD enabled negative cache_max_size rejected", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: true, CacheMaxSize: -1}}, wantErr: true, errMsg: "cache_max_size"},
+		{name: "CIMD enabled invalid TTL string rejected", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: true, CacheFallbackTTL: "not-a-duration"}}, wantErr: true, errMsg: "cache_fallback_ttl"},
+		{name: "CIMD enabled negative TTL rejected", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: true, CacheFallbackTTL: "-5m"}}, wantErr: true, errMsg: "cache_fallback_ttl"},
+		{name: "CIMD enabled valid passes", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: true, CacheMaxSize: 64, CacheFallbackTTL: "5m"}}},
+		{name: "CIMD enabled omitted optional fields pass", config: RunConfig{CIMD: &CIMDRunConfig{Enabled: true}}},
 	}
 
 	for _, tt := range tests {

docs/server/swagger.yaml

@@ -789,11 +789,23 @@ func convertRedisTLSRunConfig(rc *storage.RedisTLSRunConfig) (*tcredis.TLSConfig
 
 // resolveCIMDConfig extracts CIMD settings from a CIMDRunConfig.
 // Returns zero values when cfg is nil (CIMD disabled).
+// The CacheFallbackTTL string is parsed to time.Duration; callers must ensure
+// CIMDRunConfig.Validate() has already been called so the string is well-formed.
 func resolveCIMDConfig(cfg *authserver.CIMDRunConfig) (enabled bool, cacheMaxSize int, cacheFallbackTTL time.Duration) {
 	if cfg == nil {
 		return false, 0, 0
 	}
-	return cfg.Enabled, cfg.CacheMaxSize, cfg.CacheFallbackTTL
+	var ttl time.Duration
+	if cfg.CacheFallbackTTL != "" {
+		var err error
+		ttl, err = time.ParseDuration(cfg.CacheFallbackTTL)
+		if err != nil {
+			// Should not happen when called after CIMDRunConfig.Validate().
+			slog.Warn("invalid cimd cache_fallback_ttl, zero will be replaced by default",
+				"value", cfg.CacheFallbackTTL, "err", err)
+		}
+	}
+	return cfg.Enabled, cfg.CacheMaxSize, ttl
 }
 
 // resolveEnvVar reads a value from the named environment variable.

pkg/authserver/config.go

@@ -2052,7 +2052,7 @@ func TestResolveCIMDConfig(t *testing.T) {
 		cfg := &authserver.CIMDRunConfig{
 			Enabled:          true,
 			CacheMaxSize:     128,
-			CacheFallbackTTL: 10 * time.Minute,
+			CacheFallbackTTL: "10m",
 		}
 		enabled, size, ttl := resolveCIMDConfig(cfg)
 		assert.True(t, enabled)

pkg/authserver/config_test.go

@@ -115,6 +115,11 @@ func (h *Handler) buildOAuthMetadata() sharedobauth.AuthorizationServerMetadata
 		CodeChallengeMethodsSupported:     []string{crypto.PKCEChallengeMethodS256},
 		TokenEndpointAuthMethodsSupported: []string{sharedobauth.TokenEndpointAuthMethodNone},
 
+		// ClientIDMetadataDocumentSupported is defined in the CIMD draft as an
+		// OAuth AS metadata field (RFC 8414), not in OIDC Discovery 1.0. It is
+		// included here because MCP clients (e.g. VS Code) discover the AS via
+		// /.well-known/openid-configuration and need this flag there to activate
+		// CIMD. Spec-compliant OIDC consumers silently ignore unknown fields.
 		ClientIDMetadataDocumentSupported: h.config.CIMDEnabled,
 	}
 }

pkg/authserver/runner/embeddedauthserver.go

@@ -23,6 +23,9 @@ import (
 // server is the internal implementation of the Server interface.
 type server struct {
 	handler http.Handler
+	// storage is the active storage backend, potentially wrapped by decorators
+	// such as CIMDStorageDecorator. Code that needs the concrete type must walk
+	// the Unwrap() chain rather than asserting directly.
 	storage storage.Storage
 	// dcrStore is the same storage.Storage value asserted to
 	// storage.DCRCredentialStore. The assertion runs once at construction

pkg/authserver/runner/embeddedauthserver_test.go

@@ -8,6 +8,7 @@ import (
 	"crypto/rand"
 	"strings"
 	"testing"
+	"time"
 
 	"go.uber.org/mock/gomock"
 
@@ -188,3 +189,37 @@ func TestNewServer_Success(t *testing.T) {
 		t.Error("server.IDPTokenStorage() did not return expected storage")
 	}
 }
+
+func TestNewServer_CIMDEnabled_WrapsStorage(t *testing.T) {
+	t.Parallel()
+
+	mockUpstream := upstreammocks.NewMockOAuth2Provider(gomock.NewController(t))
+
+	stor := storage.NewMemoryStorage()
+	t.Cleanup(func() { _ = stor.Close() })
+
+	cfg := Config{
+		Issuer:               "https://example.com",
+		KeyProvider:          keys.NewGeneratingProvider(keys.DefaultAlgorithm),
+		HMACSecrets:          &servercrypto.HMACSecrets{Current: validHMACSecret()},
+		Upstreams:            []UpstreamConfig{{Name: "default", Type: UpstreamProviderTypeOAuth2, OAuth2Config: validUpstreamConfig()}},
+		AllowedAudiences:     []string{"https://mcp.example.com"},
+		CIMDEnabled:          true,
+		CIMDCacheMaxSize:     16,
+		CIMDCacheFallbackTTL: 5 * time.Minute,
+	}
+
+	mockFactory := func(_ context.Context, _ *UpstreamConfig) (upstream.OAuth2Provider, error) {
+		return mockUpstream, nil
+	}
+
+	srv, err := newServer(context.Background(), cfg, stor, withUpstreamFactory(mockFactory))
+	if err != nil {
+		t.Fatalf("newServer() unexpected error: %v", err)
+	}
+
+	_, ok := srv.storage.(*storage.CIMDStorageDecorator)
+	if !ok {
+		t.Errorf("expected storage to be *storage.CIMDStorageDecorator when CIMDEnabled=true, got %T", srv.storage)
+	}
+}