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

README.md

@@ -34,12 +34,16 @@ make build        # compile to ./bin/tenant-registry
 
 Env vars (override at the shell):
 
-| Var                | Default                                                      | Purpose                                |
+| Var                       | Default                                          | Purpose                                |
 |---|---|---|
-| `APP_ENV`          | `dev`                                                        | one of `dev`, `stage`, `prod`          |
-| `ADDR`             | `:8090`                                                      | listen address (avoids Keycloak's :8080) |
-| `KEYCLOAK_ISSUER`  | `http://localhost:8080/realms/breakpilot-dev`                | OIDC issuer URL                        |
-| `DATABASE_URL`     | empty (in-memory store in skeleton)                          | Postgres DSN, wired up in the M4.1 schema PR |
+| `APP_ENV`                 | `dev`                                            | one of `dev`, `stage`, `prod`          |
+| `ADDR`                    | `:8090`                                          | listen address (avoids Keycloak's :8080) |
+| `KEYCLOAK_ISSUER`         | `http://localhost:8080/realms/breakpilot-dev`    | OIDC issuer URL (the JWT signer)       |
+| `DATABASE_URL`            | empty (in-memory store fallback)                 | Postgres DSN; service uses Memory when empty |
+| `KEYCLOAK_ADMIN_URL`      | empty (Mock adapter used in dev)                 | KC base URL for the Admin API          |
+| `KEYCLOAK_REALM`          | `breakpilot-dev`                                 | Realm name for Admin API calls         |
+| `KEYCLOAK_CLIENT_ID`      | empty                                            | Service-account client id (Admin)      |
+| `KEYCLOAK_CLIENT_SECRET`  | empty                                            | Service-account client secret          |
 
 ## Endpoints
 
@@ -76,6 +80,37 @@ The service picks its store based on `DATABASE_URL`:
 
 Both implementations pass the same test harness (`internal/server/server_test.go` → `eachStore`).
 
+
+
+## Keycloak adapter (M4.3)
+
+`internal/keycloak` is the seam between tenant-registry and Keycloak. The
+`Adapter` interface has two implementations:
+
+| Implementation | When used                                                          |
+|---|---|
+| `Mock`         | Default in dev when `KEYCLOAK_ADMIN_URL` is empty                  |
+| `HTTPAdapter`  | Real KC Admin API client; activated when KC env vars are populated |
+
+`POST /v1/tenants` now accepts `admin_email` and `admin_name`. When set, the
+adapter creates a Keycloak organization (alias = the tenant slug), invites
+the user as the IT_ADMIN, and triggers the verify-email + set-password
+flow. The response body includes `invite_url` so dev testers can use it
+without waiting for the email — production discards it.
+
+**KC failures are non-fatal.** The tenant row still lands; a
+`keycloak.provision_failed` audit event captures the error so the operator
+can resend the invite from the KC UI.
+
+`POST /v1/internal/keycloak/claims` resolves a tenant's current entitlement
+bundle (tenant_id, slug, products, plan, status). The realm's protocol
+mapper calls this at token-issuance time (or whenever user attributes
+need a refresh).
+
+For production, provision a service-account client in the realm with the
+`realm-management:manage-users` + `manage-organizations` roles. Drop its
+credentials in Infisical at `/{env}/tenant-registry/KEYCLOAK_CLIENT_*`.
+
 ## Schema migrations (M4.1)
 
 ```bash
@@ -131,3 +166,4 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md). TL;DR: branch from main, open a PR,
 ## License
 
 Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See [`LICENSE`](./LICENSE).
+