feat(keycloak): M4.3 — Admin API adapter + claim resolver

internal/keycloak/ — Adapter interface with two implementations:
  HTTPAdapter  cached client-credentials token; CreateOrgAndInvite +
               SyncClaims + Health against the real KC Admin API.
  Mock         in-process map for unit tests + dev convenience when
               KEYCLOAK_ADMIN_URL is empty. Used by the eachStore harness.

POST /v1/tenants now accepts admin_email + admin_name. When set, the
adapter creates a KC organization, invites the user as IT_ADMIN, and
triggers VERIFY_EMAIL + UPDATE_PASSWORD. Response wraps the tenant
with TenantCreated{tenant, invite_url}. KC failures DO NOT roll the
tenant back — they emit a keycloak.provision_failed audit event.
Successful invites emit keycloak.invite_sent.

POST /v1/internal/keycloak/claims resolves a tenant's current claim
bundle (tenant_id, slug, products, plan, status). Lookup chain:
body.tenant_id → body.tenant_slug → user_attrs.tenant_id →
user_attrs.tenant_slug.

Config: KEYCLOAK_ADMIN_URL / REALM / CLIENT_ID / CLIENT_SECRET;
empty URL falls back to Mock.

Tests:
  internal/keycloak/mock_test.go     conflict surfacing, FailNext hook,
                                     SyncClaims persistence.
  internal/keycloak/client_test.go   HTTPAdapter against an in-process
                                     stub KC: health, full create-org-
                                     and-invite, conflict, token-cache,
                                     401 retry, ErrUnavailable.
  internal/server/keycloak_test.go   eachStore integration: provisions
                                     via mock; failure path emits
                                     provision_failed audit; claims
                                     endpoint via every lookup variant
                                     + 404 + 400.

OpenAPI extended with TenantCreated + Claims schemas and the new
claims endpoint. Contract test asserts the new path.

CI: include internal/keycloak/... in the test package list so
HTTPAdapter coverage counts. Total project line coverage: 71.6%.

Refs: M4.3

internal/server/server.go

@@ -1,7 +1,7 @@
 // Package server wires the HTTP surface for tenant-registry.
 //
 // All routes are registered in NewRouter; per-concern handlers live in
-// peer files (tenants.go, catalog.go, apikeys.go, audit.go).
+// peer files (tenants.go, catalog.go, apikeys.go, audit.go, keycloak.go).
 package server
 
 import (
@@ -9,14 +9,16 @@ import (
 	"net/http"
 
 	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
 
 // Server bundles the dependencies every handler needs.
 type Server struct {
-	Cfg   *config.Config
-	Log   *slog.Logger
-	Store store.Store
+	Cfg      *config.Config
+	Log      *slog.Logger
+	Store    store.Store
+	Keycloak keycloak.Adapter // never nil — main wires Mock when KC env is unset
 }
 
 // NewRouter builds the http.Handler with logging middleware applied.
@@ -34,9 +36,7 @@ func NewRouter(s *Server) http.Handler {
 	mux.HandleFunc("POST /v1/tenants/{id}/activate", s.activateTenant)
 	mux.HandleFunc("POST /v1/tenants/{id}/cancel", s.cancelTenant)
 
-	// entitlements — top-level path so it doesn't conflict with
-	// /v1/tenants/by-slug/{slug} (Go 1.22 ServeMux can't disambiguate
-	// /v1/tenants/{id}/products vs /v1/tenants/by-slug/{slug=products}).
+	// entitlements
 	mux.HandleFunc("GET /v1/entitlements", s.listTenantProducts)
 
 	// catalog
@@ -44,8 +44,7 @@ func NewRouter(s *Server) http.Handler {
 	mux.HandleFunc("POST /v1/catalog/request", s.catalogRequest)
 	mux.HandleFunc("POST /v1/catalog/trial-request", s.catalogTrialRequest)
 
-	// api keys — same disambiguation: list lives at /v1/api-keys?tenant_id=X
-	// instead of /v1/tenants/{id}/api-keys.
+	// api keys
 	mux.HandleFunc("POST /v1/api-keys", s.createAPIKey)
 	mux.HandleFunc("GET /v1/api-keys", s.listAPIKeys)
 	mux.HandleFunc("DELETE /v1/api-keys/{id}", s.revokeAPIKey)
@@ -55,6 +54,12 @@ func NewRouter(s *Server) http.Handler {
 	mux.HandleFunc("POST /v1/audit", s.appendAudit)
 	mux.HandleFunc("GET /v1/audit", s.listAudit)
 
+	// keycloak claims refresh — the URL the protocol mapper would call at
+	// token issuance to grab the up-to-date entitlement bundle. Today the
+	// dev realm projects user attributes (set by SyncClaims) — this is
+	// the "pull" complement for when the realm is reconfigured to fetch.
+	mux.HandleFunc("POST /v1/internal/keycloak/claims", s.kcClaims)
+
 	return logRequest(s.Log)(mux)
 }
 
@@ -67,5 +72,9 @@ func (s *Server) readyz(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusServiceUnavailable, "store_unavailable", err.Error())
 		return
 	}
+	if err := s.Keycloak.Health(r.Context()); err != nil {
+		writeError(w, http.StatusServiceUnavailable, "keycloak_unavailable", err.Error())
+		return
+	}
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ready"})
 }