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

internal/keycloak Adapter (HTTPAdapter + Mock). POST /v1/tenants now provisions a KC organization + IT_ADMIN invite when admin_email is set; KC failures emit keycloak.provision_failed but don't roll back. POST /v1/internal/keycloak/claims resolves the current claim bundle for any (tenant_id|tenant_slug|user_attrs.*) lookup. Mock used in tests + when KEYCLOAK_ADMIN_URL is empty. HTTPAdapter tested against an in-process stub KC (httptest.Server).

Refs: M4.3

openapi.yaml

@@ -48,15 +48,22 @@ paths:
   /v1/tenants:
     post:
       summary: Create a tenant.
+      description: |
+        Creates the tenant row, and if `admin_email` is provided, also
+        creates a Keycloak organization + invites the user as IT_ADMIN.
+        Keycloak failures DO NOT roll the tenant back — they emit a
+        `keycloak.provision_failed` audit event so the operator can resend
+        the invite from the KC admin UI.
       requestBody:
         required: true
         content:
           application/json: { schema: { $ref: "#/components/schemas/TenantCreate" } }
       responses:
         "201":
-          description: Created.
+          description: Created. `invite_url` is non-empty when an
+            `admin_email` was passed and Keycloak provisioning succeeded.
           content:
-            application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
+            application/json: { schema: { $ref: "#/components/schemas/TenantCreated" } }
         "400": { $ref: "#/components/responses/BadRequest" }
         "409": { $ref: "#/components/responses/Conflict" }
 
@@ -243,6 +250,35 @@ paths:
           description: Revoked.
         "404": { $ref: "#/components/responses/NotFound" }
 
+  /v1/internal/keycloak/claims:
+    post:
+      summary: Resolve the up-to-date claim bundle for a user/tenant.
+      description: |
+        Called by Keycloak's protocol mapper at token issuance (or by
+        any operator on demand) to fetch the current tenant_id /
+        tenant_slug / org_roles / products / plan / tenant_status
+        claims. Lookup tries tenant_id, then tenant_slug, then
+        user_attrs.tenant_id, then user_attrs.tenant_slug.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                tenant_id:   { type: string, format: uuid }
+                tenant_slug: { type: string }
+                user_attrs:
+                  type: object
+                  additionalProperties: { type: string }
+      responses:
+        "200":
+          description: Resolved claim bundle.
+          content:
+            application/json: { schema: { $ref: "#/components/schemas/Claims" } }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "404": { $ref: "#/components/responses/NotFound" }
+
   /v1/internal/api-keys/verify:
     post:
       summary: Verify an API key. Used by headless products. Returns
@@ -335,6 +371,17 @@ components:
         application/json: { schema: { $ref: "#/components/schemas/Error" } }
 
   schemas:
+    Claims:
+      type: object
+      required: [tenant_id, tenant_slug, plan, tenant_status]
+      properties:
+        tenant_id:     { type: string, format: uuid }
+        tenant_slug:   { type: string }
+        org_roles:     { type: array, items: { type: string } }
+        products:      { type: array, items: { type: string } }
+        plan:          { type: string }
+        tenant_status: { type: string, enum: [demo, trial, active, frozen, archived] }
+
     Error:
       type: object
       required: [error]
@@ -370,6 +417,15 @@ components:
         plan:        { type: string, default: starter }
         kind:        { type: string, enum: [customer, demo], default: customer }
         sales_owner: { type: string }
+        admin_email: { type: string, format: email, description: "IT_ADMIN to invite via Keycloak" }
+        admin_name:  { type: string }
+
+    TenantCreated:
+      type: object
+      required: [tenant]
+      properties:
+        tenant:     { $ref: "#/components/schemas/Tenant" }
+        invite_url: { type: string, description: "KC action-token URL — present only when admin_email was set and KC provisioning succeeded" }
 
     TenantActivate:
       type: object