Wire tenant_roles as explicit opt-in configuration

Closes gap G07. The tenant-engine client and TokenHandler.TenantEngine were
implemented and tested, but main.go supplied no client and exposed no
configuration, so the stock executable left the field nil and the capability
existed at library level only.

A tenantEngine block with baseURL and an optional timeout now wires it. An empty
baseURL leaves the stock server's behaviour exactly as it was, so enabling the
claim is a deliberate act. Validation treats a configured source as one that must
work: http/https with a host, and a timeout in (0, 10s] since it sits on the
synchronous token-issuance path. A timeout set without a baseURL is rejected
rather than ignored -- it means someone expected the claim to be on.

Verified in the built executable, which is what G07 asks for, rather than at the
wiring: against a stub source a real token carries tenant_roles; with no block
the claim is absent; with the source configured but down, issuance succeeds
without it, confirming the documented fail-open path end to end.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NV9oijZukGyGbRQGGKnK4P

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 713576@bnt-lap001
Assistant-Session: 384c511d-9bce-4cb8-a676-2aef6c0c8df6

src/cmd/keycape/main.go

@@ -21,6 +21,7 @@ import (
 	"keycape/internal/adapters/authelia"
 	"keycape/internal/adapters/lldap"
 	"keycape/internal/adapters/privacyidea"
+	"keycape/internal/adapters/tenantengine"
 	"keycape/internal/authclient"
 	"keycape/internal/config"
 	"keycape/internal/domain"
@@ -178,6 +179,11 @@ func main() {
 		Issuer:        issuer,
 		TokenLifetime: tokenLifetime,
 		Emitter:       emitter,
+		// Opt-in: nil unless tenantEngine.baseURL is configured, which is what
+		// leaves tenant_roles off the stock server (KEY-WP-0024). The adapter
+		// fails open, so a configured-but-unreachable cache omits the claim
+		// rather than failing issuance.
+		TenantEngine: buildTenantEngine(cfg.TenantEngine),
 	}
 	mux.Handle("/token", enforcement.Middleware(tokenHandler))
 
@@ -320,3 +326,18 @@ func withEmitter(next http.Handler, e telemetry.Emitter) http.Handler {
 		next.ServeHTTP(w, r.WithContext(ctx))
 	})
 }
+
+// buildTenantEngine returns the tenant_roles cache client, or nil when the
+// claim is not configured. Validation has already accepted the URL and timeout.
+func buildTenantEngine(cfg config.TenantEngineConfig) *tenantengine.Client {
+	if cfg.BaseURL == "" {
+		return nil
+	}
+	var httpClient *http.Client
+	if cfg.Timeout != "" {
+		if timeout, err := time.ParseDuration(cfg.Timeout); err == nil {
+			httpClient = &http.Client{Timeout: timeout}
+		}
+	}
+	return tenantengine.New(cfg.BaseURL, httpClient)
+}

src/internal/config/config.go

@@ -27,6 +27,22 @@ type Config struct {
 	PrivacyIDEA   privacyidea.Config `yaml:"privacyidea"`
 	Clients       []ClientConfig     `yaml:"clients"`
 	Environment   string             `yaml:"environment"`
+	TenantEngine  TenantEngineConfig `yaml:"tenantEngine,omitempty"`
+}
+
+// TenantEngineConfig configures the optional tenant_roles cache claim.
+//
+// Opt-in by design: an empty baseURL leaves the claim off entirely, which is
+// what the stock server does. tenant_roles is a cache callers must not trust for
+// privileged decisions, and the adapter fails open, so enabling it is a
+// performance choice rather than a security one (KEY-WP-0024).
+type TenantEngineConfig struct {
+	// BaseURL is tenant-engine's cache-read endpoint. Empty disables the claim.
+	BaseURL string `yaml:"baseURL,omitempty"`
+
+	// Timeout bounds the lookup, which sits on the synchronous token-issuance
+	// path. Empty uses the adapter's own short default.
+	Timeout string `yaml:"timeout,omitempty"`
 }
 
 // ClientConfig is a static OIDC client registration.

src/internal/config/config_test.go

@@ -496,3 +496,36 @@ func TestValidateConfigAudience(t *testing.T) {
 		}
 	}
 }
+
+// tenant_roles is opt-in, but a configured cache source must be usable: it sits
+// on the synchronous token-issuance path (KEY-WP-0024).
+func TestValidate_TenantEngine(t *testing.T) {
+	cases := map[string]struct {
+		engine config.TenantEngineConfig
+		valid  bool
+	}{
+		"absent is valid":       {config.TenantEngineConfig{}, true},
+		"http url":              {config.TenantEngineConfig{BaseURL: "http://tenant-engine:8080"}, true},
+		"https url and timeout": {config.TenantEngineConfig{BaseURL: "https://tenant-engine", Timeout: "2s"}, true},
+		"not a url":             {config.TenantEngineConfig{BaseURL: "tenant-engine"}, false},
+		"wrong scheme":          {config.TenantEngineConfig{BaseURL: "ldap://tenant-engine"}, false},
+		"unparseable timeout":   {config.TenantEngineConfig{BaseURL: "http://t", Timeout: "soon"}, false},
+		"zero timeout":          {config.TenantEngineConfig{BaseURL: "http://t", Timeout: "0s"}, false},
+		"timeout far too long":  {config.TenantEngineConfig{BaseURL: "http://t", Timeout: "5m"}, false},
+		// A timeout with no base URL means someone expected the claim to be on.
+		"timeout without url": {config.TenantEngineConfig{Timeout: "2s"}, false},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			cfg := validConfig(writeTempFile(t, "key"))
+			cfg.TenantEngine = tc.engine
+			errs := config.ValidateConfig(cfg)
+			if tc.valid && len(errs) != 0 {
+				t.Fatalf("expected valid, got %v", errs)
+			}
+			if !tc.valid && len(errs) == 0 {
+				t.Fatal("expected a validation error")
+			}
+		})
+	}
+}

src/internal/config/validate.go

@@ -30,6 +30,27 @@ func ValidateConfig(cfg *Config) []string {
 		errs = append(errs, fmt.Sprintf("port: must be between 1 and 65535, got %d", cfg.Port))
 	}
 
+	// tenant_roles is opt-in: an empty baseURL disables it. A configured one
+	// must be usable, since a misconfigured cache source on the token path is
+	// worse than no cache source (KEY-WP-0024).
+	if cfg.TenantEngine.BaseURL != "" {
+		u, err := url.Parse(cfg.TenantEngine.BaseURL)
+		if err != nil || u.Scheme == "" || u.Host == "" {
+			errs = append(errs, fmt.Sprintf("tenantEngine.baseURL: %q is not a valid URL (must include scheme and host)", cfg.TenantEngine.BaseURL))
+		} else if u.Scheme != "http" && u.Scheme != "https" {
+			errs = append(errs, fmt.Sprintf("tenantEngine.baseURL: scheme must be http or https, got %q", u.Scheme))
+		}
+	}
+	if cfg.TenantEngine.Timeout != "" {
+		if cfg.TenantEngine.BaseURL == "" {
+			errs = append(errs, "tenantEngine.timeout: set without a baseURL, so tenant_roles stays disabled")
+		} else if timeout, err := time.ParseDuration(cfg.TenantEngine.Timeout); err != nil {
+			errs = append(errs, "tenantEngine.timeout: must be a valid duration")
+		} else if timeout <= 0 || timeout > 10*time.Second {
+			errs = append(errs, "tenantEngine.timeout: must be greater than 0 and at most 10s; it sits on the token-issuance path")
+		}
+	}
+
 	// At least one client must be registered.
 	if len(cfg.Clients) == 0 {
 		errs = append(errs, "clients: at least one client must be defined")