feat(tenants): provision the product tenant with the registry UUID on create

Closes the tenant-anchor divergence that blocked the Auth-5 sdk/backend flips.

The registry is the authority for tenant identity (model B2), but nothing ever
told the product about a new tenant. The anchors drifted: the registry held
acme/matrix-acme while the product database held only the legacy seed tenant
9282a473. With the SDK gate enabled its TenantResolver does GetTenantBySlug and
would 403 EVERY authenticated request, because no real user's org slug existed
locally.

New internal/product port, mirroring keycloak.Adapter: handlers depend on the
interface, main wires HTTPProvisioner when PRODUCT_API_URL is set and
NoopProvisioner otherwise, so an unconfigured deployment still creates tenants.
Tenant creation now also provisions the product tenant with OUR uuid, using the
same best-effort contract as Keycloak provisioning: a failure does not roll the
tenant back, it emits a product.provision_failed audit event so the divergence
is traceable. Success emits product.tenant_provisioned.

A 409 from the product counts as success — onboarding may retry and the
product's insert is idempotent on the primary key (compliance#217).

Server.productProvisioner() guarantees the documented never-nil invariant;
tests construct Server directly and would otherwise panic mid-tenant-creation.

5 tests incl. the point of the whole port (the registry UUID is what gets sent).
Full suite green with -race, coverage 71.4% (gate 70).

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

.env.example

@@ -9,3 +9,11 @@ KEYCLOAK_ISSUER=http://localhost:8080/realms/breakpilot-dev
 # only; data lost on restart). Set to use the dev-stack Postgres + run
 # `make migrate-up` first.
 # DATABASE_URL=postgres://platform:platform-dev-pass@localhost:5432/platform?sslmode=disable
+
+# Keycloak Admin API — when these are set, tenant-registry calls the real KC
+# Admin API to provision orgs + invite IT_ADMINs on POST /v1/tenants. Leave
+# empty to use the in-process Mock adapter (no real KC writes).
+# KEYCLOAK_ADMIN_URL=http://localhost:8080
+# KEYCLOAK_REALM=breakpilot-dev
+# KEYCLOAK_CLIENT_ID=tenant-registry-admin
+# KEYCLOAK_CLIENT_SECRET=...from infisical...

.gitea/workflows/ci.yaml

@@ -83,7 +83,7 @@ jobs:
         # own test binary — and including it triggers a covdata-tool error
         # on packages with no _test.go files. -coverpkg makes the server's
         # exercise of store/* count toward coverage.
-        run: go test -race -coverpkg=./internal/... -coverprofile=cover.out ./internal/server/... ./internal/config/...
+        run: go test -race -coverpkg=./internal/... -coverprofile=cover.out ./internal/server/... ./internal/config/... ./internal/keycloak/...
 
       - name: coverage gate
         run: |
@@ -94,29 +94,53 @@ jobs:
 
   image:
     needs: [shared, test]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && hashFiles('Dockerfile') != ''
+    # NOTE: no hashFiles() here — at job level it evaluates BEFORE checkout
+    # against an empty workspace, so the old condition was always false and
+    # this job silently never ran (deployment sat on an Aug-06 image).
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: docker
+    # The runner's default job container has no docker CLI, so
+    # docker/login-action + docker/build-push-action die with "Unable to
+    # locate executable file: docker". Same pattern as the proven
+    # breakpilot-compliance build-push-deploy.yml: run in docker:27-cli
+    # (talks to the runner's daemon) and use plain docker commands.
+    container: docker:27-cli
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        run: |
+          apk add --no-cache git curl openssl
+          git clone --depth 1 --branch ${GITHUB_REF_NAME} $(echo ${GITHUB_SERVER_URL} | sed -E "s#^(https?://)#\1ci:${{ secrets.GITHUB_TOKEN }}@#")/${GITHUB_REPOSITORY}.git .
 
-      - uses: docker/login-action@v3
-        with:
-          registry: registry.breakpilot.com
-          username: ${{ secrets.REGISTRY_USER }}
-          password: ${{ secrets.REGISTRY_PASS }}
-
-      - uses: docker/build-push-action@v6
-        with:
-          push: true
-          tags: |
-            registry.breakpilot.com/${{ github.event.repository.name }}:sha-${{ github.sha }}
-            registry.breakpilot.com/${{ github.event.repository.name }}:env-stage
-
-      - uses: anchore/sbom-action@v0
-        with:
-          image: registry.breakpilot.com/${{ github.event.repository.name }}:sha-${{ github.sha }}
-
-      - name: orca deploy stage
-        run: orca apply --env=stage --image-tag=sha-${{ github.sha }}
+      - name: Login
         env:
-          ORCA_TOKEN: ${{ secrets.ORCA_STAGE_TOKEN }}
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_PASS: ${{ secrets.REGISTRY_PASS }}
+        run: echo "$REGISTRY_PASS" | docker login repo.breakpilot.com -u "$REGISTRY_USER" --password-stdin
+
+      - name: Build + push
+        run: |
+          set -eu
+          docker build \
+            -t repo.breakpilot.com/breakpilot/tenant-registry:latest \
+            -t repo.breakpilot.com/breakpilot/tenant-registry:sha-${GITHUB_SHA} \
+            .
+          docker push repo.breakpilot.com/breakpilot/tenant-registry:latest
+          docker push repo.breakpilot.com/breakpilot/tenant-registry:sha-${GITHUB_SHA}
+
+      # Notify orca to pull :latest and recreate the service (same pattern as
+      # breakpilot-core/build-pitch-deck.yml). The stage-env deploy this used to
+      # attempt does not exist in this cluster.
+      - name: orca deploy webhook
+        env:
+          ORCA_WEBHOOK_SECRET: ${{ secrets.ORCA_WEBHOOK_SECRET }}
+          ORCA_WEBHOOK_URL: http://46.225.100.82:6880/api/v1/webhooks/github
+        run: |
+          set -eu
+          PAYLOAD="{\"ref\":\"refs/heads/main\",\"repository\":{\"full_name\":\"${GITHUB_REPOSITORY}\"},\"head_commit\":{\"id\":\"${GITHUB_SHA}\",\"message\":\"ci: tenant-registry image build\"}}"
+          SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$ORCA_WEBHOOK_SECRET" -r | awk '{print $1}')
+          curl -sSf -k \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Event: push" \
+            -H "X-Hub-Signature-256: sha256=$SIG" \
+            -d "$PAYLOAD" \
+            "$ORCA_WEBHOOK_URL"

.gitea/workflows/release.yaml

@@ -22,7 +22,7 @@ jobs:
 
       - name: verify stage soak (>= 24h on this image)
         run: |
-          IMG=registry.breakpilot.com/${{ github.event.repository.name }}:env-stage
+          IMG=repo.breakpilot.com/breakpilot/${{ github.event.repository.name }}:env-stage
           SOAK_SECONDS=$(orca image-age --env=stage --image $IMG)
           if [ "$SOAK_SECONDS" -lt 86400 ]; then
             echo "Stage soak only $SOAK_SECONDS s, < 24h. Aborting."
@@ -34,12 +34,12 @@ jobs:
       - name: re-tag image as semver + env-prod
         uses: docker/login-action@v3
         with:
-          registry: registry.breakpilot.com
+          registry: repo.breakpilot.com
           username: ${{ secrets.REGISTRY_USER }}
           password: ${{ secrets.REGISTRY_PASS }}
 
       - run: |
-          IMG=registry.breakpilot.com/${{ github.event.repository.name }}
+          IMG=repo.breakpilot.com/breakpilot/${{ github.event.repository.name }}
           docker pull $IMG:env-stage
           docker tag  $IMG:env-stage $IMG:v${{ steps.v.outputs.version }}
           docker tag  $IMG:env-stage $IMG:env-prod
@@ -67,7 +67,7 @@ jobs:
           curl -X POST -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
             -H "Content-Type: application/json" \
             -d "$(jq -Rs '{tag_name:"v${{ steps.v.outputs.version }}", name:"v${{ steps.v.outputs.version }}", body:.}' < RELEASE_NOTES.md)" \
-            https://gitea.meghsakha.com/api/v1/repos/${{ github.repository }}/releases
+            https://git.breakpilot.com/api/v1/repos/${{ github.repository }}/releases
 
   rollback-on-failure:
     needs: promote

CHANGELOG.md

@@ -6,6 +6,8 @@ Generated section is appended on release tag via `git-cliff` (see `.gitea/workfl
 ## [Unreleased]
 
 ### Added
+- feat(store): CreateTenant defaults trial_ends_at to NOW()+14d for customer kind; demo kind gets status='demo' and no trial end
+- feat(keycloak): M4.3 — internal/keycloak adapter (Admin API: org create + IT_ADMIN invite + execute-actions-email + attribute sync). admin_email on POST /v1/tenants triggers KC provisioning; failures emit keycloak.provision_failed audit but don't roll back. POST /v1/internal/keycloak/claims resolves the current claim bundle for a tenant.
 - feat(api): M4.2 — full REST surface (tenants CRUD + lifecycle, catalog, entitlements, API keys w/ argon2 hashing, audit query). pgx-backed Postgres store; in-memory fallback when DATABASE_URL is empty. OpenAPI 3.1 spec at openapi.yaml with kin-openapi contract test.
 - feat(schema): M4.1 — golang-migrate migrations for tenants + tenant_projects + tenant_products + tenant_idp_config + api_keys + audit_log; cmd/migrate binary; testcontainers round-trip + seed + slug-constraint tests
 - feat(server): minimal Go service — /healthz + GET /v1/tenants/by-slug/:slug + GET /v1/tenants/:id with in-memory store seeded with the acme tenant

Dockerfile

@@ -3,7 +3,7 @@
 #   /tenant-registry  — long-running API server
 #   /migrate          — one-shot schema migrator (Orca init container in prod)
 
-FROM golang:1.24-alpine AS build
+FROM golang:1.25-alpine AS build
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download

README.md

@@ -38,8 +38,12 @@ Env vars (override at the shell):
 |---|---|---|
 | `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 |
+| `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).
+

cmd/server/main.go

@@ -10,7 +10,10 @@ import (
 	"syscall"
 	"time"
 
+	"gitea.meghsakha.com/platform/tenant-registry/internal/authn"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/product"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/server"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
@@ -42,7 +45,49 @@ func main() {
 	}
 	defer s.Close()
 
-	handler := server.NewRouter(&server.Server{Cfg: cfg, Log: logger, Store: s})
+	var kc keycloak.Adapter
+	if cfg.KeycloakAdminURL != "" && cfg.KeycloakClientID != "" {
+		kc = keycloak.NewHTTPAdapter(keycloak.HTTPConfig{
+			BaseURL:      cfg.KeycloakAdminURL,
+			Realm:        cfg.KeycloakRealm,
+			ClientID:     cfg.KeycloakClientID,
+			ClientSecret: cfg.KeycloakClientSecret,
+			Timeout:      cfg.KeycloakTimeout,
+		})
+		slog.Info("keycloak adapter configured",
+			"url", cfg.KeycloakAdminURL, "realm", cfg.KeycloakRealm, "client_id", cfg.KeycloakClientID)
+	} else {
+		slog.Warn("KEYCLOAK_ADMIN_URL not set — using mock adapter (dev only; no real KC writes)")
+		kc = keycloak.NewMock()
+	}
+
+	var av *authn.Verifier
+	if cfg.AuthEnabled {
+		av, err = authn.New(bootCtx, cfg.KeycloakIssuer, cfg.AuthAudience)
+		if err != nil {
+			// Fail closed: never start an "authenticated" server that
+			// cannot actually verify tokens.
+			slog.Error("AUTH_CONFIG_INCOMPLETE — AUTH_ENABLED=true but verifier init failed", "err", err)
+			os.Exit(1)
+		}
+		slog.Info("api auth enabled", "issuer", cfg.KeycloakIssuer, "audience", cfg.AuthAudience)
+	} else {
+		slog.Warn("AUTH_ENABLED=false — API is unauthenticated (dev only)")
+	}
+
+	// Downstream product provisioning. Wired only when PRODUCT_API_URL is set;
+	// otherwise a no-op so an unconfigured deployment still creates tenants.
+	// The product's gate is not yet enforcing, so no token is attached today —
+	// AuthHeaderFunc is the seam for when it is.
+	var pv product.Provisioner = product.NoopProvisioner{}
+	if cfg.ProductAPIURL != "" {
+		pv = product.NewHTTPProvisioner(cfg.ProductAPIURL, cfg.ProductAPIPath, nil, cfg.ProductTimeout)
+		slog.Info("product provisioner configured", "url", cfg.ProductAPIURL, "path", cfg.ProductAPIPath)
+	} else {
+		slog.Warn("PRODUCT_API_URL not set — product tenant provisioning disabled (anchors may diverge)")
+	}
+
+	handler := server.NewRouter(&server.Server{Cfg: cfg, Log: logger, Store: s, Keycloak: kc, Auth: av, Product: pv})
 	srv := &http.Server{
 		Addr:         cfg.Addr,
 		Handler:      handler,

go.mod

@@ -3,13 +3,15 @@ module gitea.meghsakha.com/platform/tenant-registry
 go 1.25.0
 
 require (
-	github.com/getkin/kin-openapi v0.138.0
+	github.com/coreos/go-oidc/v3 v3.20.0
+	github.com/getkin/kin-openapi v0.144.0
+	github.com/go-jose/go-jose/v4 v4.1.4
 	github.com/golang-migrate/migrate/v4 v4.19.1
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6
 	github.com/jackc/pgx/v5 v5.9.2
 	github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0
-	golang.org/x/crypto v0.51.0
+	golang.org/x/crypto v0.55.0
 )
 
 require (
@@ -32,33 +34,29 @@ require (
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect
-	github.com/go-openapi/jsonpointer v0.21.0 // indirect
-	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/go-openapi/jsonpointer v0.22.5 // indirect
+	github.com/go-openapi/swag/jsonname v0.25.5 // indirect
 	github.com/gorilla/mux v1.8.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	github.com/josharian/intern v1.0.0 // indirect
-	github.com/klauspost/compress v1.18.5 // indirect
+	github.com/klauspost/compress v1.18.7 // indirect
 	github.com/lib/pq v1.10.9 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
-	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
-	github.com/moby/go-archive v0.2.0 // indirect
+	github.com/moby/go-archive v0.3.0 // indirect
 	github.com/moby/moby/api v1.54.1 // indirect
 	github.com/moby/moby/client v0.4.0 // indirect
 	github.com/moby/patternmatcher v0.6.1 // indirect
-	github.com/moby/sys/sequential v0.6.0 // indirect
-	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/sequential v0.7.0 // indirect
+	github.com/moby/sys/user v0.4.1 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
-	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
-	github.com/oasdiff/yaml v0.0.9 // indirect
-	github.com/oasdiff/yaml3 v0.0.12 // indirect
+	github.com/oasdiff/yaml v0.1.1 // indirect
+	github.com/oasdiff/yaml3 v0.0.14 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
-	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
@@ -68,15 +66,15 @@ require (
 	github.com/testcontainers/testcontainers-go v0.42.0 // indirect
 	github.com/tklauser/go-sysconf v0.3.16 // indirect
 	github.com/tklauser/numcpus v0.11.0 // indirect
-	github.com/woodsbury/decimal128 v1.3.0 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
 	go.opentelemetry.io/otel v1.41.0 // indirect
 	go.opentelemetry.io/otel/metric v1.41.0 // indirect
 	go.opentelemetry.io/otel/trace v1.41.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.44.0 // indirect
-	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/oauth2 v0.36.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -18,6 +18,8 @@ github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
 github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/coreos/go-oidc/v3 v3.20.0 h1:EtE0WIBHk03N+DqGkY4+UONzzZHk7amKt6IyNd7OsZE=
+github.com/coreos/go-oidc/v3 v3.20.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
 github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
@@ -41,8 +43,10 @@ github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/
 github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
-github.com/getkin/kin-openapi v0.138.0 h1:ebfE0JAmF6AqHrNBy1KO3Fs68K9tPs48HalvLPo7Rv4=
-github.com/getkin/kin-openapi v0.138.0/go.mod h1:vUYWaKyMqj7PfTybelXtLuLN9tReS12vxnzMRK+z2GY=
+github.com/getkin/kin-openapi v0.144.0 h1:hIRcTH+KjLfkLpYU6bSSfdFpi0fZi1fp+hSPi4aQu9Y=
+github.com/getkin/kin-openapi v0.144.0/go.mod h1:3BH9M9XDe/y9M5DSvEocVYAYq1w0qrhJHjC/vZi0AaY=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -50,12 +54,12 @@ github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
-github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ=
-github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY=
-github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE=
-github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ=
-github.com/go-test/deep v1.0.8 h1:TDsG77qcSprGbC6vTN8OuXp5g+J+b5Pcguhf7Zt61VM=
-github.com/go-test/deep v1.0.8/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
+github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA=
+github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0=
+github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo=
+github.com/go-openapi/swag/jsonname v0.25.5/go.mod h1:jNqqikyiAK56uS7n8sLkdaNY/uq6+D2m2LANat09pKU=
+github.com/go-openapi/testify/v2 v2.4.0 h1:8nsPrHVCWkQ4p8h1EsRVymA2XABB4OT40gcvAu+voFM=
+github.com/go-openapi/testify/v2 v2.4.0/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang-migrate/migrate/v4 v4.19.1 h1:OCyb44lFuQfYXYLx1SCxPZQGU7mcaZ7gH9yH4jSFbBA=
@@ -77,10 +81,8 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
 github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
-github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
-github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
-github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.18.7 h1:aUyZsS4kH3QTKurYhAOwAHxllVPnOthb3vPfnF1Ehjw=
+github.com/klauspost/compress v1.18.7/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -91,42 +93,36 @@ github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ
 github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
 github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
-github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
-github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
 github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
-github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
-github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
+github.com/moby/go-archive v0.3.0 h1:nos4BtzzUIqB406BgQnWGMI4qib9BZ8XUHU+ucv/n1c=
+github.com/moby/go-archive v0.3.0/go.mod h1:Npdv43fFqlhZW7Xo8fbm3ZMYFvAGNviUPqX21VERbcE=
 github.com/moby/moby/api v1.54.1 h1:TqVzuJkOLsgLDDwNLmYqACUuTehOHRGKiPhvH8V3Nn4=
 github.com/moby/moby/api v1.54.1/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
 github.com/moby/moby/client v0.4.0 h1:S+2XegzHQrrvTCvF6s5HFzcrywWQmuVnhOXe2kiWjIw=
 github.com/moby/moby/client v0.4.0/go.mod h1:QWPbvWchQbxBNdaLSpoKpCdf5E+WxFAgNHogCWDoa7g=
 github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U=
 github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
-github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
-github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
-github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
-github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8=
+github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o=
+github.com/moby/sys/user v0.4.1 h1:RgjRlaDKi/Xmyrz4t8lyzXT6v2ooFeO/7xtchmhVWE0=
+github.com/moby/sys/user v0.4.1/go.mod h1:E9QsW5WRe1kUAf7kW8hXKwu1uhsZEAdPLYHYSDudF4Y=
 github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
 github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
 github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
 github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
-github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw=
-github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8=
 github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
 github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
-github.com/oasdiff/yaml v0.0.9 h1:zQOvd2UKoozsSsAknnWoDJlSK4lC0mpmjfDsfqNwX48=
-github.com/oasdiff/yaml v0.0.9/go.mod h1:8lvhgJG4xiKPj3HN5lDow4jZHPlx1i7dIwzkdAo6oAM=
-github.com/oasdiff/yaml3 v0.0.12 h1:75urAtPeDg2/iDEWwzNrLOWxI9N/dCh81nTTJtokt2M=
-github.com/oasdiff/yaml3 v0.0.12/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o=
+github.com/oasdiff/yaml v0.1.1 h1:6nHx+pn9gBRM6YpBlFZFQGCCd1nuvqOBtTD3KKTgGxY=
+github.com/oasdiff/yaml v0.1.1/go.mod h1:EYJNoyktvWMJ0Hmhx+6qTaqMOsalUaRGT8Sj1hNcegU=
+github.com/oasdiff/yaml3 v0.0.14 h1:aLJee3hxBK2H5wdXd9iPcIXb93Nty1Ge0pT171eHtkw=
+github.com/oasdiff/yaml3 v0.0.14/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg=
 github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
 github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
-github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s=
-github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
@@ -157,10 +153,6 @@ github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYI
 github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
 github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
 github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
-github.com/ugorji/go/codec v1.2.7 h1:YPXUKf7fYbp/y8xloBqZOw2qaVggbfwMlI8WM3wZUJ0=
-github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95kRgeqEY=
-github.com/woodsbury/decimal128 v1.3.0 h1:8pffMNWIlC0O5vbyHWFZAt5yWvWcrHA+3ovIIjVWss0=
-github.com/woodsbury/decimal128 v1.3.0/go.mod h1:C5UTmyTjW3JftjUFzOVhC20BEQa2a4ZKOB5I6Zjb+ds=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
@@ -177,19 +169,21 @@ go.opentelemetry.io/otel/sdk/metric v1.36.0 h1:r0ntwwGosWGaa0CrSt8cuNuTcccMXERFw
 go.opentelemetry.io/otel/sdk/metric v1.36.0/go.mod h1:qTNOhFDfKRwX0yXOqJYegL5WRaW376QbB7P4Pb0qva4=
 go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
 go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
-golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
-golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
+golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
-golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=

internal/authn/authn.go

@@ -0,0 +1,88 @@
+// Package authn validates Keycloak-issued bearer tokens for the
+// tenant-registry API (RBAC rollout Phase 1; fail-closed per the ratified
+// compliance auth design, model B2).
+//
+// The package only verifies — issuer, signature via JWKS, expiry, and
+// audience. It deliberately does not authorize: tenant-registry IS the
+// membership authority, so its callers are services (INTERNAL_SERVICE_ONLY
+// posture) holding client_credentials tokens whose audience includes
+// AUTH_EXPECTED_AUDIENCE.
+package authn
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+)
+
+// ErrNoToken means the Authorization header was absent or not a Bearer
+// scheme. Handlers map it to 401 TOKEN_MISSING.
+var ErrNoToken = errors.New("authorization header missing or not Bearer")
+
+// Principal is the verified caller identity, placed in the request context
+// so handlers (and, later, audit writes) can attribute actions.
+type Principal struct {
+	Subject  string // JWT sub — the Keycloak user or service-account id
+	ClientID string // JWT azp — which OAuth client obtained the token
+	Issuer   string
+}
+
+type ctxKey struct{}
+
+// WithPrincipal returns ctx carrying p.
+func WithPrincipal(ctx context.Context, p *Principal) context.Context {
+	return context.WithValue(ctx, ctxKey{}, p)
+}
+
+// PrincipalFrom extracts the verified principal, if any.
+func PrincipalFrom(ctx context.Context) (*Principal, bool) {
+	p, ok := ctx.Value(ctxKey{}).(*Principal)
+	return p, ok
+}
+
+// Verifier checks bearer tokens against one issuer + audience. A nil
+// *Verifier means auth is disabled (AUTH_ENABLED=false) and the server
+// passes requests through unauthenticated.
+type Verifier struct {
+	issuer   string
+	verifier *oidc.IDTokenVerifier
+}
+
+// New performs OIDC discovery against issuer and prepares JWKS-backed
+// verification. Callers must treat an error as fatal when AUTH_ENABLED=true
+// (AUTH_CONFIG_INCOMPLETE — refuse to start, never fall open).
+func New(ctx context.Context, issuer, audience string) (*Verifier, error) {
+	if issuer == "" || audience == "" {
+		return nil, errors.New("issuer and audience are required")
+	}
+	provider, err := oidc.NewProvider(ctx, issuer)
+	if err != nil {
+		return nil, fmt.Errorf("oidc discovery for %s: %w", issuer, err)
+	}
+	return &Verifier{
+		issuer:   issuer,
+		verifier: provider.Verifier(&oidc.Config{ClientID: audience}),
+	}, nil
+}
+
+// Verify checks the raw Authorization header value and returns the caller
+// principal. Signature, issuer, expiry, and audience are all enforced by
+// the underlying oidc verifier.
+func (v *Verifier) Verify(ctx context.Context, authorization string) (*Principal, error) {
+	raw, ok := strings.CutPrefix(authorization, "Bearer ")
+	if !ok || strings.TrimSpace(raw) == "" {
+		return nil, ErrNoToken
+	}
+	tok, err := v.verifier.Verify(ctx, strings.TrimSpace(raw))
+	if err != nil {
+		return nil, err
+	}
+	var claims struct {
+		Azp string `json:"azp"`
+	}
+	_ = tok.Claims(&claims) // azp is informational; absence is not an error
+	return &Principal{Subject: tok.Subject, ClientID: claims.Azp, Issuer: tok.Issuer}, nil
+}

internal/authn/authn_test.go

@@ -0,0 +1,189 @@
+package authn_test
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	jose "github.com/go-jose/go-jose/v4"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/authn"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/server"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
+)
+
+// stubIssuer is a minimal OIDC issuer: discovery + JWKS + an RS256 signer.
+type stubIssuer struct {
+	URL  string
+	key  *rsa.PrivateKey
+	sign func(t *testing.T, claims map[string]any) string
+}
+
+func newStubIssuer(t *testing.T) *stubIssuer {
+	t.Helper()
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := &stubIssuer{key: key}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"issuer":   s.URL,
+			"jwks_uri": s.URL + "/jwks",
+		})
+	})
+	mux.HandleFunc("/jwks", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(jose.JSONWebKeySet{Keys: []jose.JSONWebKey{
+			{Key: key.Public(), KeyID: "test-kid", Algorithm: "RS256", Use: "sig"},
+		}})
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	s.URL = srv.URL
+
+	signer, err := jose.NewSigner(
+		jose.SigningKey{Algorithm: jose.RS256, Key: key},
+		(&jose.SignerOptions{}).WithHeader("kid", "test-kid"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s.sign = func(t *testing.T, claims map[string]any) string {
+		t.Helper()
+		payload, _ := json.Marshal(claims)
+		jws, err := signer.Sign(payload)
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, err := jws.CompactSerialize()
+		if err != nil {
+			t.Fatal(err)
+		}
+		return raw
+	}
+	return s
+}
+
+func (s *stubIssuer) claims(overrides map[string]any) map[string]any {
+	c := map[string]any{
+		"iss": s.URL,
+		"aud": "tenant-registry",
+		"sub": "svc-account-1",
+		"azp": "compliance-svc",
+		"exp": time.Now().Add(5 * time.Minute).Unix(),
+		"iat": time.Now().Unix(),
+	}
+	for k, v := range overrides {
+		c[k] = v
+	}
+	return c
+}
+
+func TestVerifier(t *testing.T) {
+	iss := newStubIssuer(t)
+	v, err := authn.New(context.Background(), iss.URL, "tenant-registry")
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	ctx := context.Background()
+
+	t.Run("valid token yields principal", func(t *testing.T) {
+		p, err := v.Verify(ctx, "Bearer "+iss.sign(t, iss.claims(nil)))
+		if err != nil {
+			t.Fatalf("verify: %v", err)
+		}
+		if p.Subject != "svc-account-1" || p.ClientID != "compliance-svc" || p.Issuer != iss.URL {
+			t.Errorf("principal wrong: %+v", p)
+		}
+	})
+
+	fail := func(name, header string) {
+		t.Run(name, func(t *testing.T) {
+			if _, err := v.Verify(ctx, header); err == nil {
+				t.Fatal("expected verification failure")
+			}
+		})
+	}
+	fail("missing header", "")
+	fail("not bearer", "Basic abc")
+	fail("garbage token", "Bearer not.a.jwt")
+	fail("expired", "Bearer "+iss.sign(t, iss.claims(map[string]any{"exp": time.Now().Add(-time.Minute).Unix()})))
+	fail("wrong audience", "Bearer "+iss.sign(t, iss.claims(map[string]any{"aud": "someone-else"})))
+	fail("wrong issuer", "Bearer "+iss.sign(t, iss.claims(map[string]any{"iss": "https://evil.example"})))
+
+	t.Run("missing header is ErrNoToken", func(t *testing.T) {
+		if _, err := v.Verify(ctx, ""); err != authn.ErrNoToken {
+			t.Fatalf("want ErrNoToken, got %v", err)
+		}
+	})
+}
+
+func TestNew_failsClosed(t *testing.T) {
+	if _, err := authn.New(context.Background(), "", "aud"); err == nil {
+		t.Fatal("empty issuer must error")
+	}
+	if _, err := authn.New(context.Background(), "http://127.0.0.1:1/realms/none", "aud"); err == nil {
+		t.Fatal("unreachable issuer must error")
+	}
+}
+
+// TestRouterGating proves the wiring: health stays PUBLIC_EXPLICIT, every
+// API route fails closed without a token, and a valid service token passes.
+func TestRouterGating(t *testing.T) {
+	iss := newStubIssuer(t)
+	v, err := authn.New(context.Background(), iss.URL, "tenant-registry")
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	handler := server.NewRouter(&server.Server{
+		Cfg:      &config.Config{Env: "dev"},
+		Log:      slog.New(slog.NewTextHandler(io.Discard, nil)),
+		Store:    store.NewMemory(),
+		Keycloak: keycloak.NewMock(),
+		Auth:     v,
+	})
+	srv := httptest.NewServer(handler)
+	defer srv.Close()
+
+	get := func(t *testing.T, path, authz string) (int, string) {
+		t.Helper()
+		req, _ := http.NewRequest(http.MethodGet, srv.URL+path, nil)
+		if authz != "" {
+			req.Header.Set("Authorization", authz)
+		}
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer func() { _ = resp.Body.Close() }()
+		raw, _ := io.ReadAll(resp.Body)
+		return resp.StatusCode, string(raw)
+	}
+
+	if code, _ := get(t, "/healthz", ""); code != http.StatusOK {
+		t.Errorf("healthz must stay public, got %d", code)
+	}
+	if code, body := get(t, "/v1/catalog", ""); code != http.StatusUnauthorized || !strings.Contains(body, "TOKEN_MISSING") {
+		t.Errorf("no token: want 401 TOKEN_MISSING, got %d %s", code, body)
+	}
+	if code, body := get(t, "/v1/catalog", "Bearer junk"); code != http.StatusUnauthorized || !strings.Contains(body, "TOKEN_INVALID") {
+		t.Errorf("bad token: want 401 TOKEN_INVALID, got %d %s", code, body)
+	}
+	if code, _ := get(t, "/v1/catalog", "Bearer "+iss.sign(t, iss.claims(nil))); code != http.StatusOK {
+		t.Errorf("valid token: want 200, got %d", code)
+	}
+}

internal/config/config.go

@@ -3,6 +3,7 @@ package config
 import (
 	"fmt"
 	"os"
+	"time"
 )
 
 type Config struct {
@@ -10,6 +11,29 @@ type Config struct {
 	Addr           string // listen address, e.g. ":8090"
 	KeycloakIssuer string // e.g. http://localhost:8080/realms/breakpilot-dev
 	DatabaseURL    string // postgres DSN (unused in skeleton; in-memory store)
+
+	// Keycloak Admin API — only used if KeycloakAdminURL is set. Empty
+	// values disable the adapter and tenant-registry falls back to the
+	// Mock (dev convenience).
+	KeycloakAdminURL     string
+	KeycloakRealm        string
+	KeycloakClientID     string
+	KeycloakClientSecret string
+	KeycloakTimeout      time.Duration
+
+	// Inbound API auth (RBAC Phase 1). With AuthEnabled the server refuses
+	// to start unless OIDC discovery against KeycloakIssuer succeeds, and
+	// every non-health route requires a bearer token whose audience
+	// contains AuthAudience.
+	AuthEnabled  bool
+	AuthAudience string
+
+	// Downstream product provisioning. When ProductAPIURL is set, tenant
+	// creation also provisions the tenant in the product's own database with
+	// the SAME registry UUID, so both anchors agree. Empty ⇒ no-op adapter.
+	ProductAPIURL  string
+	ProductAPIPath string
+	ProductTimeout time.Duration
 }
 
 func Load() (*Config, error) {
@@ -23,6 +47,19 @@ func Load() (*Config, error) {
 		Addr:           getenv("ADDR", ":8090"),
 		KeycloakIssuer: getenv("KEYCLOAK_ISSUER", "http://localhost:8080/realms/breakpilot-dev"),
 		DatabaseURL:    os.Getenv("DATABASE_URL"),
+
+		KeycloakAdminURL:     os.Getenv("KEYCLOAK_ADMIN_URL"),
+		KeycloakRealm:        getenv("KEYCLOAK_REALM", "breakpilot-dev"),
+		KeycloakClientID:     os.Getenv("KEYCLOAK_CLIENT_ID"),
+		KeycloakClientSecret: os.Getenv("KEYCLOAK_CLIENT_SECRET"),
+		KeycloakTimeout:      10 * time.Second,
+
+		AuthEnabled:  getenv("AUTH_ENABLED", "false") == "true",
+		AuthAudience: getenv("AUTH_EXPECTED_AUDIENCE", "tenant-registry"),
+
+		ProductAPIURL:  os.Getenv("PRODUCT_API_URL"),
+		ProductAPIPath: getenv("PRODUCT_API_TENANTS_PATH", "/sdk/v1/tenants"),
+		ProductTimeout: 10 * time.Second,
 	}, nil
 }
 

internal/keycloak/adapter.go

@@ -0,0 +1,89 @@
+// Package keycloak adapts the Keycloak Admin API to the tenant-registry's
+// language of "tenants" and "IT_ADMIN invites".
+//
+// The Adapter interface is the seam: tenant-registry handlers depend on
+// it, never on the concrete HTTP client. Tests use Mock; production uses
+// HTTPAdapter against the real KC at the configured base URL.
+//
+// Required Keycloak features (verified against KC 26):
+//   - Organizations feature enabled in the realm (organizationsEnabled: true)
+//   - Realm roles: BREAKPILOT_ADMIN, SUPPORT_ENGINEER, SALES_REP
+//   - Group `/IT_ADMIN` (used as the org_role marker for invited users)
+//
+// All errors are wrapped with %w so callers can errors.Is them against
+// ErrUnauthorized / ErrOrgConflict / ErrUserConflict.
+package keycloak
+
+import (
+	"context"
+	"errors"
+)
+
+// Sentinel errors.
+var (
+	ErrUnauthorized = errors.New("keycloak: admin auth failed")
+	ErrOrgConflict  = errors.New("keycloak: organization already exists")
+	ErrUserConflict = errors.New("keycloak: user already exists")
+	ErrUnavailable  = errors.New("keycloak: unreachable")
+	ErrUserNotFound = errors.New("keycloak: user does not exist")
+)
+
+// InviteInput captures the per-tenant onboarding event from POST /v1/tenants.
+// The adapter creates a Keycloak organization, invites the IT_ADMIN, and
+// stores the (TenantID, OrganizationID) link back in the caller's Tenant.
+type InviteInput struct {
+	TenantID   string // the tenant_registry id; stored as KC org attribute "tenant_id"
+	Slug       string // becomes the KC org alias
+	Name       string // human-readable org name
+	AdminEmail string // IT_ADMIN to invite (required)
+	AdminName  string // optional display name
+}
+
+// InviteResult is what the adapter produces. OrganizationID is what the
+// tenant-registry stores so it can later assert tenants.id ↔ kc.org_id 1:1.
+type InviteResult struct {
+	OrganizationID string
+	UserID         string
+	// InviteURL is what the user clicks to set their password. In dev (no
+	// Stalwart yet) we surface it in the response so testers can use it
+	// directly. In prod it's emailed by Keycloak and we discard it.
+	InviteURL string
+}
+
+// Claims is the tenant-scoped claim bundle the protocol-mapper would push
+// into a JWT at token issuance. Returned by Adapter.ClaimsFor so the user-
+// attributes can be refreshed on subscription change.
+type Claims struct {
+	TenantID     string   `json:"tenant_id"`
+	TenantSlug   string   `json:"tenant_slug"`
+	OrgRoles     []string `json:"org_roles"`
+	Products     []string `json:"products"`
+	Plan         string   `json:"plan"`
+	TenantStatus string   `json:"tenant_status"`
+}
+
+// Adapter is the shape tenant-registry handlers code against. HTTPAdapter
+// is the real one; Mock satisfies the same surface for tests.
+type Adapter interface {
+	// CreateOrgAndInvite is the M4.3 happy path. Atomic from the caller's
+	// PoV: either both org+user land or neither does.
+	CreateOrgAndInvite(ctx context.Context, in InviteInput) (*InviteResult, error)
+
+	// SyncClaims pushes the current Claims into the user's Keycloak
+	// attributes. Called whenever entitlements change (M4.2 catalog/trial
+	// flows, M14.x cancel, M12.x trial transitions).
+	SyncClaims(ctx context.Context, userID string, c Claims) error
+
+	// Memberships resolves the tenants user userID (the Keycloak user id,
+	// i.e. the JWT `sub`) belongs to, as Keycloak records them. Since the
+	// realm enabled Organizations (2026-09-01) this is an org-membership
+	// query: one membership per enabled org the user belongs to (alias =
+	// tenant slug, org attribute tenant_id = registry UUID). The legacy
+	// user-attribute projection no longer grants membership on its own.
+	// Returns ErrUserNotFound for an unknown user id.
+	Memberships(ctx context.Context, userID string) ([]Claims, error)
+
+	// Health pings the admin endpoint. Used by readyz and the cluster cold-
+	// start sequence (INFRASTRUCTURE.md §10 scenario F).
+	Health(ctx context.Context) error
+}

internal/keycloak/client.go

@@ -0,0 +1,165 @@
+package keycloak
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+)
+
+// HTTPAdapter implements Adapter against the real Keycloak Admin REST API.
+// Uses client-credentials grant; an admin-role'd service account on the
+// realm should be configured. Token is cached and refreshed before expiry.
+type HTTPAdapter struct {
+	cfg HTTPConfig
+	hc  *http.Client
+
+	// token cache
+	mu       sync.Mutex
+	tokenStr string
+	tokenExp time.Time
+}
+
+// HTTPConfig — every value read from env via internal/config.
+type HTTPConfig struct {
+	BaseURL      string // e.g. http://localhost:8080
+	Realm        string // breakpilot-dev | breakpilot-prod
+	ClientID     string // service account client id
+	ClientSecret string // service account client secret
+	AdminEmail   string // platform admin email — used to gate the BREAKPILOT_ADMIN realm role check
+	Timeout      time.Duration
+}
+
+func NewHTTPAdapter(cfg HTTPConfig) *HTTPAdapter {
+	if cfg.Timeout == 0 {
+		cfg.Timeout = 10 * time.Second
+	}
+	return &HTTPAdapter{cfg: cfg, hc: &http.Client{Timeout: cfg.Timeout}}
+}
+
+// ─── auth ────────────────────────────────────────────────────────────────
+
+func (a *HTTPAdapter) token(ctx context.Context) (string, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.tokenStr != "" && time.Now().Before(a.tokenExp.Add(-30*time.Second)) {
+		return a.tokenStr, nil
+	}
+
+	form := url.Values{
+		"grant_type":    {"client_credentials"},
+		"client_id":     {a.cfg.ClientID},
+		"client_secret": {a.cfg.ClientSecret},
+	}
+	tokenURL := fmt.Sprintf("%s/realms/%s/protocol/openid-connect/token", a.cfg.BaseURL, a.cfg.Realm)
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, tokenURL, strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	resp, err := a.hc.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("%w: %v", ErrUnavailable, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode == http.StatusUnauthorized {
+		return "", ErrUnauthorized
+	}
+	if resp.StatusCode/100 != 2 {
+		body, _ := io.ReadAll(resp.Body)
+		return "", fmt.Errorf("keycloak token: %d %s", resp.StatusCode, body)
+	}
+	var tr struct {
+		AccessToken string `json:"access_token"`
+		ExpiresIn   int    `json:"expires_in"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&tr); err != nil {
+		return "", fmt.Errorf("keycloak token decode: %w", err)
+	}
+	a.tokenStr = tr.AccessToken
+	a.tokenExp = time.Now().Add(time.Duration(tr.ExpiresIn) * time.Second)
+	return a.tokenStr, nil
+}
+
+// adminCall is the common request shape against /admin/realms/{realm}/...
+// On 401/403 it clears the token and tries once more.
+func (a *HTTPAdapter) adminCall(ctx context.Context, method, path string, body any, into any) (resp *http.Response, err error) {
+	tok, err := a.token(ctx)
+	if err != nil {
+		return nil, err
+	}
+	resp, err = a.doAdmin(ctx, method, path, body, tok)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode == http.StatusUnauthorized {
+		_ = resp.Body.Close()
+		a.mu.Lock()
+		a.tokenStr = "" // force refresh
+		a.mu.Unlock()
+		if tok, err = a.token(ctx); err != nil {
+			return nil, err
+		}
+		resp, err = a.doAdmin(ctx, method, path, body, tok)
+		if err != nil {
+			return nil, err
+		}
+	}
+	if into != nil && resp.StatusCode/100 == 2 && resp.ContentLength != 0 {
+		defer func() { _ = resp.Body.Close() }()
+		if err := json.NewDecoder(resp.Body).Decode(into); err != nil && !errors.Is(err, io.EOF) {
+			return nil, fmt.Errorf("decode response: %w", err)
+		}
+	}
+	return resp, nil
+}
+
+func (a *HTTPAdapter) doAdmin(ctx context.Context, method, path string, body any, tok string) (*http.Response, error) {
+	u := fmt.Sprintf("%s/admin/realms/%s%s", a.cfg.BaseURL, a.cfg.Realm, path)
+	var bodyR io.Reader
+	if body != nil {
+		buf, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		bodyR = bytes.NewReader(buf)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u, bodyR)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+tok)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	req.Header.Set("Accept", "application/json")
+	resp, err := a.hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrUnavailable, err)
+	}
+	return resp, nil
+}
+
+// Health pings /admin/serverinfo (cheap, returns 200 on a working install).
+func (a *HTTPAdapter) Health(ctx context.Context) error {
+	tok, err := a.token(ctx)
+	if err != nil {
+		return err
+	}
+	u := fmt.Sprintf("%s/admin/serverinfo", a.cfg.BaseURL)
+	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	req.Header.Set("Authorization", "Bearer "+tok)
+	resp, err := a.hc.Do(req)
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrUnavailable, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode/100 != 2 {
+		return fmt.Errorf("keycloak health: %d", resp.StatusCode)
+	}
+	return nil
+}

internal/keycloak/client_test.go

@@ -0,0 +1,253 @@
+package keycloak
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// stubKC builds a minimal KC look-alike: token endpoint + the Admin API
+// paths the HTTPAdapter actually calls. Each path is a single handler that
+// asserts the request shape and returns the bare-minimum valid response.
+type stubKC struct {
+	srv         *httptest.Server
+	tokenCalls  atomic.Int32
+	orgCalls    atomic.Int32
+	userCalls   atomic.Int32
+	memberCalls atomic.Int32
+	emailCalls  atomic.Int32
+	healthCalls atomic.Int32
+	syncCalls   atomic.Int32
+	lastOrgBody string
+
+	tokenFails atomic.Bool // when true, /token returns 401 once
+}
+
+func newStubKC(t *testing.T) *stubKC {
+	t.Helper()
+	s := &stubKC{}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/realms/test-realm/protocol/openid-connect/token", func(w http.ResponseWriter, r *http.Request) {
+		s.tokenCalls.Add(1)
+		if s.tokenFails.Swap(false) {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": "test-token", "expires_in": 60,
+		})
+	})
+
+	mux.HandleFunc("/admin/serverinfo", func(w http.ResponseWriter, r *http.Request) {
+		s.healthCalls.Add(1)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"systemInfo":{"version":"26.0.0"}}`))
+	})
+
+	mux.HandleFunc("/admin/realms/test-realm/organizations", func(w http.ResponseWriter, r *http.Request) {
+		s.orgCalls.Add(1)
+		if r.Method == http.MethodPost {
+			body, _ := io.ReadAll(r.Body)
+			s.lastOrgBody = string(body)
+			w.Header().Set("Location", s.srv.URL+"/admin/realms/test-realm/organizations/org-xyz")
+			w.WriteHeader(http.StatusCreated)
+			return
+		}
+		http.Error(w, "method", http.StatusMethodNotAllowed)
+	})
+
+	mux.HandleFunc("/admin/realms/test-realm/organizations/org-xyz/members", func(w http.ResponseWriter, r *http.Request) {
+		s.memberCalls.Add(1)
+		w.WriteHeader(http.StatusCreated)
+	})
+
+	mux.HandleFunc("/admin/realms/test-realm/users", func(w http.ResponseWriter, r *http.Request) {
+		s.userCalls.Add(1)
+		if r.Method == http.MethodPost {
+			w.Header().Set("Location", s.srv.URL+"/admin/realms/test-realm/users/user-abc")
+			w.WriteHeader(http.StatusCreated)
+			return
+		}
+	})
+
+	mux.HandleFunc("/admin/realms/test-realm/users/user-abc/execute-actions-email", func(w http.ResponseWriter, r *http.Request) {
+		s.emailCalls.Add(1)
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	mux.HandleFunc("/admin/realms/test-realm/users/user-abc", func(w http.ResponseWriter, r *http.Request) {
+		s.syncCalls.Add(1)
+		if r.Method == http.MethodPut {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+	})
+
+	s.srv = httptest.NewServer(mux)
+	return s
+}
+
+func (s *stubKC) close() { s.srv.Close() }
+
+func newTestAdapter(srv *httptest.Server) *HTTPAdapter {
+	return NewHTTPAdapter(HTTPConfig{
+		BaseURL:      srv.URL,
+		Realm:        "test-realm",
+		ClientID:     "test-client",
+		ClientSecret: "test-secret",
+		Timeout:      5 * time.Second,
+	})
+}
+
+func TestHTTPAdapter_health(t *testing.T) {
+	s := newStubKC(t)
+	defer s.close()
+	a := newTestAdapter(s.srv)
+	if err := a.Health(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if s.healthCalls.Load() != 1 {
+		t.Errorf("health calls = %d", s.healthCalls.Load())
+	}
+}
+
+func TestHTTPAdapter_createOrgAndInvite(t *testing.T) {
+	s := newStubKC(t)
+	defer s.close()
+	a := newTestAdapter(s.srv)
+
+	res, err := a.CreateOrgAndInvite(context.Background(), InviteInput{
+		TenantID: "t1", Slug: "acme", Name: "Acme Inc.",
+		AdminEmail: "owner@acme.test", AdminName: "Alice Owner",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.OrganizationID != "org-xyz" || res.UserID != "user-abc" {
+		t.Errorf("unexpected ids: %+v", res)
+	}
+	if s.orgCalls.Load() != 1 || s.userCalls.Load() != 1 ||
+		s.memberCalls.Load() != 1 || s.emailCalls.Load() != 1 {
+		t.Errorf("call counts: org=%d user=%d member=%d email=%d",
+			s.orgCalls.Load(), s.userCalls.Load(), s.memberCalls.Load(), s.emailCalls.Load())
+	}
+	// KC 26 rejects a domainless org; the adapter must send a synthetic
+	// per-slug domain so onboarding actually provisions.
+	if !strings.Contains(s.lastOrgBody, `"domains"`) ||
+		!strings.Contains(s.lastOrgBody, "acme.tenant.breakpilot.com") {
+		t.Errorf("org create body missing synthetic domain: %s", s.lastOrgBody)
+	}
+}
+
+func TestHTTPAdapter_emailMissingAdminEmailRejected(t *testing.T) {
+	s := newStubKC(t)
+	defer s.close()
+	a := newTestAdapter(s.srv)
+
+	_, err := a.CreateOrgAndInvite(context.Background(), InviteInput{
+		TenantID: "t1", Slug: "x", Name: "X",
+	})
+	if err == nil {
+		t.Fatal("expected error for empty admin email")
+	}
+}
+
+func TestHTTPAdapter_orgConflict(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/realms/test-realm/protocol/openid-connect/token", tokenOK)
+	mux.HandleFunc("/admin/realms/test-realm/organizations", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+	a := newTestAdapter(srv)
+
+	_, err := a.CreateOrgAndInvite(context.Background(), InviteInput{
+		TenantID: "t1", Slug: "x", Name: "X", AdminEmail: "a@b.test",
+	})
+	if !errors.Is(err, ErrOrgConflict) {
+		t.Errorf("err = %v, want ErrOrgConflict", err)
+	}
+}
+
+func TestHTTPAdapter_tokenUnavailable(t *testing.T) {
+	// No KC server at all — adapter should surface ErrUnavailable.
+	a := NewHTTPAdapter(HTTPConfig{
+		BaseURL: "http://127.0.0.1:1", Realm: "test", ClientID: "x", ClientSecret: "y", Timeout: 1 * time.Second,
+	})
+	err := a.Health(context.Background())
+	if !errors.Is(err, ErrUnavailable) {
+		t.Errorf("err = %v, want ErrUnavailable", err)
+	}
+}
+
+func TestHTTPAdapter_tokenUnauthorized(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/realms/test-realm/protocol/openid-connect/token", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+	a := newTestAdapter(srv)
+	err := a.Health(context.Background())
+	if !errors.Is(err, ErrUnauthorized) {
+		t.Errorf("err = %v, want ErrUnauthorized", err)
+	}
+}
+
+func TestHTTPAdapter_syncClaims(t *testing.T) {
+	s := newStubKC(t)
+	defer s.close()
+	a := newTestAdapter(s.srv)
+
+	err := a.SyncClaims(context.Background(), "user-abc", Claims{
+		TenantID: "t1", TenantSlug: "acme", Plan: "professional",
+		Products: []string{"certifai"}, TenantStatus: "active",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.syncCalls.Load() != 1 {
+		t.Errorf("sync calls = %d", s.syncCalls.Load())
+	}
+}
+
+func TestHTTPAdapter_tokenIsCached(t *testing.T) {
+	s := newStubKC(t)
+	defer s.close()
+	a := newTestAdapter(s.srv)
+
+	// Three Health calls should produce ONE token fetch (cached).
+	for i := 0; i < 3; i++ {
+		if err := a.Health(context.Background()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if s.tokenCalls.Load() != 1 {
+		t.Errorf("token fetches = %d, want 1 (cache miss)", s.tokenCalls.Load())
+	}
+}
+
+// tokenOK is a reusable handler that always returns a working token.
+func tokenOK(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method", http.StatusMethodNotAllowed)
+		return
+	}
+	b := make([]byte, r.ContentLength)
+	_, _ = r.Body.Read(b)
+	if !strings.Contains(string(b), "client_credentials") {
+		http.Error(w, "grant_type", http.StatusBadRequest)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_, _ = w.Write([]byte(`{"access_token":"t","expires_in":60}`))
+}

internal/keycloak/mock.go

@@ -0,0 +1,86 @@
+package keycloak
+
+import (
+	"context"
+	"errors"
+	"sync"
+)
+
+// Mock is the test-friendly Adapter. Records every call; predictable IDs.
+// Use in unit tests + as the default adapter when KEYCLOAK_BASE_URL is empty
+// (dev convenience).
+type Mock struct {
+	mu       sync.Mutex
+	Orgs     map[string]string // tenantID → orgID
+	Users    map[string]string // email → userID
+	Claims   map[string]Claims // userID → last synced
+	FailNext error             // set to force the next call to fail
+}
+
+func NewMock() *Mock {
+	return &Mock{
+		Orgs:   map[string]string{},
+		Users:  map[string]string{},
+		Claims: map[string]Claims{},
+	}
+}
+
+func (m *Mock) Health(_ context.Context) error { return nil }
+
+func (m *Mock) CreateOrgAndInvite(_ context.Context, in InviteInput) (*InviteResult, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.FailNext != nil {
+		err := m.FailNext
+		m.FailNext = nil
+		return nil, err
+	}
+	if _, taken := m.Orgs[in.TenantID]; taken {
+		return nil, ErrOrgConflict
+	}
+	if _, taken := m.Users[in.AdminEmail]; taken {
+		return nil, ErrUserConflict
+	}
+	orgID := "mock-org-" + in.Slug
+	userID := "mock-user-" + in.AdminEmail
+	m.Orgs[in.TenantID] = orgID
+	m.Users[in.AdminEmail] = userID
+	return &InviteResult{
+		OrganizationID: orgID,
+		UserID:         userID,
+		InviteURL:      "http://mock-keycloak/invite/" + userID,
+	}, nil
+}
+
+// Memberships returns the last-synced Claims for userID as its single
+// membership, mirroring the attribute-projection behavior of the real
+// adapter. Unknown users yield ErrUserNotFound.
+func (m *Mock) Memberships(_ context.Context, userID string) ([]Claims, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.FailNext != nil {
+		err := m.FailNext
+		m.FailNext = nil
+		return nil, err
+	}
+	c, ok := m.Claims[userID]
+	if !ok {
+		return nil, ErrUserNotFound
+	}
+	return []Claims{c}, nil
+}
+
+func (m *Mock) SyncClaims(_ context.Context, userID string, c Claims) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.FailNext != nil {
+		err := m.FailNext
+		m.FailNext = nil
+		return err
+	}
+	if userID == "" {
+		return errors.New("mock: user_id required")
+	}
+	m.Claims[userID] = c
+	return nil
+}

internal/keycloak/mock_test.go

@@ -0,0 +1,84 @@
+package keycloak
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestMock_createOrgAndInvite(t *testing.T) {
+	m := NewMock()
+	ctx := context.Background()
+
+	res, err := m.CreateOrgAndInvite(ctx, InviteInput{
+		TenantID: "t1", Slug: "acme", Name: "Acme",
+		AdminEmail: "a@acme.test", AdminName: "Alice",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.OrganizationID == "" || res.UserID == "" {
+		t.Errorf("ids missing: %+v", res)
+	}
+	if m.Orgs["t1"] != res.OrganizationID {
+		t.Errorf("Orgs map not updated")
+	}
+	if m.Users["a@acme.test"] != res.UserID {
+		t.Errorf("Users map not updated")
+	}
+}
+
+func TestMock_orgConflict(t *testing.T) {
+	m := NewMock()
+	ctx := context.Background()
+	_, _ = m.CreateOrgAndInvite(ctx, InviteInput{TenantID: "t1", Slug: "x", AdminEmail: "a@y.test"})
+	_, err := m.CreateOrgAndInvite(ctx, InviteInput{TenantID: "t1", Slug: "x", AdminEmail: "b@y.test"})
+	if !errors.Is(err, ErrOrgConflict) {
+		t.Errorf("err = %v, want ErrOrgConflict", err)
+	}
+}
+
+func TestMock_userConflict(t *testing.T) {
+	m := NewMock()
+	ctx := context.Background()
+	_, _ = m.CreateOrgAndInvite(ctx, InviteInput{TenantID: "t1", Slug: "x", AdminEmail: "a@y.test"})
+	_, err := m.CreateOrgAndInvite(ctx, InviteInput{TenantID: "t2", Slug: "z", AdminEmail: "a@y.test"})
+	if !errors.Is(err, ErrUserConflict) {
+		t.Errorf("err = %v, want ErrUserConflict", err)
+	}
+}
+
+func TestMock_failNextHook(t *testing.T) {
+	m := NewMock()
+	m.FailNext = ErrUnavailable
+	_, err := m.CreateOrgAndInvite(context.Background(), InviteInput{TenantID: "t1", Slug: "x", AdminEmail: "a@y.test"})
+	if !errors.Is(err, ErrUnavailable) {
+		t.Errorf("err = %v, want ErrUnavailable", err)
+	}
+	// Subsequent call recovers
+	_, err = m.CreateOrgAndInvite(context.Background(), InviteInput{TenantID: "t1", Slug: "x", AdminEmail: "a@y.test"})
+	if err != nil {
+		t.Errorf("FailNext should clear after one use; err=%v", err)
+	}
+}
+
+func TestMock_syncClaims(t *testing.T) {
+	m := NewMock()
+	err := m.SyncClaims(context.Background(), "user-1", Claims{
+		TenantID: "t1", Plan: "professional", Products: []string{"certifai"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m.Claims["user-1"].Plan != "professional" {
+		t.Errorf("claims not stored")
+	}
+}
+
+func TestMock_syncClaimsRequiresUserID(t *testing.T) {
+	m := NewMock()
+	err := m.SyncClaims(context.Background(), "", Claims{})
+	if err == nil {
+		t.Error("expected error for empty user id")
+	}
+}

internal/keycloak/orgs.go

@@ -0,0 +1,273 @@
+package keycloak
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"path"
+	"strings"
+)
+
+// ─── organizations API ───────────────────────────────────────────────────
+
+// orgDomainSuffix namespaces the synthetic org domain. The slug is unique in
+// the registry, so "<slug>.tenant.breakpilot.com" is unique per organization
+// and never a real deliverable mail domain we might clash with.
+const orgDomainSuffix = ".tenant.breakpilot.com"
+
+type orgCreate struct {
+	Name        string              `json:"name"`
+	Alias       string              `json:"alias"`
+	Description string              `json:"description,omitempty"`
+	Domains     []map[string]any    `json:"domains,omitempty"`
+	Attributes  map[string][]string `json:"attributes,omitempty"`
+}
+
+type userCreate struct {
+	Username      string              `json:"username"`
+	Email         string              `json:"email"`
+	FirstName     string              `json:"firstName,omitempty"`
+	LastName      string              `json:"lastName,omitempty"`
+	Enabled       bool                `json:"enabled"`
+	EmailVerified bool                `json:"emailVerified"`
+	Attributes    map[string][]string `json:"attributes,omitempty"`
+}
+
+// CreateOrgAndInvite creates the organization, creates the IT_ADMIN user,
+// adds them as org member, and triggers the verify-email-and-set-password
+// flow (Keycloak's native "invite via email" path).
+//
+// Best-effort atomicity: on partial failure we leave KC in whatever state
+// it's in and surface the error. A follow-up reconciler (M4.x or M14.x)
+// can heal divergence. For local dev where everything either succeeds or
+// the test surfaces the exact failure, this is fine.
+func (a *HTTPAdapter) CreateOrgAndInvite(ctx context.Context, in InviteInput) (*InviteResult, error) {
+	if in.AdminEmail == "" {
+		return nil, fmt.Errorf("keycloak: admin email required")
+	}
+
+	// 1. Create org with tenant_id baked in as an attribute so we can
+	//    correlate the two systems with a single Admin API call later.
+	orgPayload := orgCreate{
+		Name:        in.Name,
+		Alias:       in.Slug,
+		Description: fmt.Sprintf("Auto-provisioned from tenant-registry %s", in.TenantID),
+		// Keycloak 26 rejects an organization with no domain ("You must
+		// provide at least one domain"). Membership is registry-authoritative
+		// (model B2), so we do NOT use Keycloak's email-domain auto-join; a
+		// synthetic per-tenant domain derived from the unique slug satisfies
+		// the constraint without depending on the customer's real mail domain
+		// (which may be a shared public domain and would collide across
+		// tenants). Unverified is fine — verification only gates auto-join.
+		Domains: []map[string]any{
+			{"name": in.Slug + orgDomainSuffix, "verified": false},
+		},
+		Attributes: map[string][]string{
+			"tenant_id": {in.TenantID},
+		},
+	}
+	resp, err := a.adminCall(ctx, http.MethodPost, "/organizations", orgPayload, nil)
+	if err != nil {
+		return nil, err
+	}
+	switch resp.StatusCode {
+	case http.StatusCreated:
+		// keep going
+	case http.StatusConflict:
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("%w: alias=%s", ErrOrgConflict, in.Slug)
+	default:
+		body, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("create org: %d %s", resp.StatusCode, body)
+	}
+	// Keycloak returns the id in the Location header.
+	orgID := lastSegment(resp.Header.Get("Location"))
+	_ = resp.Body.Close()
+	if orgID == "" {
+		// Fallback: query by alias.
+		orgID, err = a.findOrgByAlias(ctx, in.Slug)
+		if err != nil {
+			return nil, fmt.Errorf("create org: missing Location and lookup failed: %w", err)
+		}
+	}
+
+	// 2. Create the user (disabled until they set a password).
+	first, last := splitName(in.AdminName)
+	userPayload := userCreate{
+		Username:      in.AdminEmail,
+		Email:         in.AdminEmail,
+		FirstName:     first,
+		LastName:      last,
+		Enabled:       true,
+		EmailVerified: false,
+		Attributes: map[string][]string{
+			"tenant_id":     {in.TenantID},
+			"tenant_slug":   {in.Slug},
+			"org_roles":     {"IT_ADMIN"},
+			"tenant_status": {"trial"},
+		},
+	}
+	resp, err = a.adminCall(ctx, http.MethodPost, "/users", userPayload, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create user: %w", err)
+	}
+	switch resp.StatusCode {
+	case http.StatusCreated:
+		// keep going
+	case http.StatusConflict:
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("%w: email=%s", ErrUserConflict, in.AdminEmail)
+	default:
+		body, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("create user: %d %s", resp.StatusCode, body)
+	}
+	userID := lastSegment(resp.Header.Get("Location"))
+	_ = resp.Body.Close()
+	if userID == "" {
+		userID, err = a.findUserByEmail(ctx, in.AdminEmail)
+		if err != nil {
+			return nil, fmt.Errorf("create user: missing Location and lookup failed: %w", err)
+		}
+	}
+
+	// 3. Add user to organization (member).
+	addBody := map[string]string{"id": userID}
+	resp, err = a.adminCall(ctx, http.MethodPost,
+		fmt.Sprintf("/organizations/%s/members", orgID), addBody, nil)
+	if err != nil {
+		return nil, fmt.Errorf("add member: %w", err)
+	}
+	if resp.StatusCode/100 != 2 && resp.StatusCode != http.StatusConflict {
+		body, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("add member: %d %s", resp.StatusCode, body)
+	}
+	_ = resp.Body.Close()
+
+	// 4. Trigger the verify-email + set-password execute-actions email.
+	//    In dev (no Stalwart) we also surface the action-token URL to
+	//    the caller so they can hit it directly.
+	inviteURL, err := a.executeActionsEmail(ctx, userID,
+		[]string{"VERIFY_EMAIL", "UPDATE_PASSWORD"},
+		"https://breakpilot.com/onboard")
+	if err != nil {
+		// Non-fatal — admin can resend from the KC UI.
+		return &InviteResult{OrganizationID: orgID, UserID: userID, InviteURL: ""}, nil
+	}
+
+	return &InviteResult{OrganizationID: orgID, UserID: userID, InviteURL: inviteURL}, nil
+}
+
+// SyncClaims pushes the up-to-date claim bundle into the user's KC
+// attributes. Called by tenant-registry whenever entitlements change.
+func (a *HTTPAdapter) SyncClaims(ctx context.Context, userID string, c Claims) error {
+	attrs := map[string][]string{
+		"tenant_id":     {c.TenantID},
+		"tenant_slug":   {c.TenantSlug},
+		"org_roles":     c.OrgRoles,
+		"products":      c.Products,
+		"plan":          {c.Plan},
+		"tenant_status": {c.TenantStatus},
+	}
+	resp, err := a.adminCall(ctx, http.MethodPut, "/users/"+userID,
+		map[string]any{"attributes": attrs}, nil)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode/100 != 2 {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("sync claims: %d %s", resp.StatusCode, body)
+	}
+	return nil
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────
+
+func (a *HTTPAdapter) findOrgByAlias(ctx context.Context, alias string) (string, error) {
+	resp, err := a.adminCall(ctx, http.MethodGet,
+		fmt.Sprintf("/organizations?search=%s&exact=true", alias), nil, nil)
+	if err != nil {
+		return "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode/100 != 2 {
+		return "", fmt.Errorf("find org: %d", resp.StatusCode)
+	}
+	var orgs []struct {
+		ID    string `json:"id"`
+		Alias string `json:"alias"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&orgs); err != nil {
+		return "", err
+	}
+	for _, o := range orgs {
+		if o.Alias == alias {
+			return o.ID, nil
+		}
+	}
+	return "", errors.New("org not found")
+}
+
+func (a *HTTPAdapter) findUserByEmail(ctx context.Context, email string) (string, error) {
+	resp, err := a.adminCall(ctx, http.MethodGet,
+		fmt.Sprintf("/users?email=%s&exact=true", email), nil, nil)
+	if err != nil {
+		return "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	var users []struct {
+		ID    string `json:"id"`
+		Email string `json:"email"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&users); err != nil {
+		return "", err
+	}
+	for _, u := range users {
+		if strings.EqualFold(u.Email, email) {
+			return u.ID, nil
+		}
+	}
+	return "", errors.New("user not found")
+}
+
+func (a *HTTPAdapter) executeActionsEmail(ctx context.Context, userID string, actions []string, redirectURI string) (string, error) {
+	resp, err := a.adminCall(ctx, http.MethodPut,
+		fmt.Sprintf("/users/%s/execute-actions-email?client_id=dev-portal&redirect_uri=%s", userID, redirectURI),
+		actions, nil)
+	if err != nil {
+		return "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode/100 != 2 {
+		return "", fmt.Errorf("execute-actions: %d", resp.StatusCode)
+	}
+	// KC doesn't return the action-token URL via this endpoint — it sends
+	// the email. For dev we surface an admin-portal pointer so the tester
+	// has somewhere to land.
+	return fmt.Sprintf("%s/realms/%s/account", a.cfg.BaseURL, a.cfg.Realm), nil
+}
+
+func lastSegment(loc string) string {
+	if loc == "" {
+		return ""
+	}
+	return path.Base(loc)
+}
+
+func splitName(full string) (first, last string) {
+	full = strings.TrimSpace(full)
+	if full == "" {
+		return "", ""
+	}
+	parts := strings.Fields(full)
+	if len(parts) == 1 {
+		return parts[0], ""
+	}
+	return parts[0], strings.Join(parts[1:], " ")
+}

internal/keycloak/users.go

@@ -0,0 +1,109 @@
+package keycloak
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+)
+
+// userRepresentation is the slice of the Admin API's UserRepresentation we
+// need. Attributes arrive as map[name][]values; the KC admin console writes
+// multivalued attributes either as separate list entries or as one entry
+// joined with "##", so both shapes must be accepted.
+type userRepresentation struct {
+	ID         string              `json:"id"`
+	Username   string              `json:"username"`
+	Enabled    bool                `json:"enabled"`
+	Attributes map[string][]string `json:"attributes"`
+}
+
+// memberOrgRepresentation is the slice of OrganizationRepresentation the
+// membership query needs: the alias IS the tenant slug and the org
+// attribute "tenant_id" carries the registry tenant UUID (both written by
+// CreateOrgAndInvite, or provisioned by the realm admin for pre-existing
+// tenants).
+type memberOrgRepresentation struct {
+	ID         string              `json:"id"`
+	Alias      string              `json:"alias"`
+	Enabled    bool                `json:"enabled"`
+	Attributes map[string][]string `json:"attributes"`
+}
+
+// Memberships implements Adapter with Keycloak Organizations as the
+// authoritative membership source (prod shape, realm orgs enabled
+// 2026-09-01):
+//
+//  1. GET /users/{id} — preserves ErrUserNotFound semantics and supplies
+//     the per-user claim attributes (org_roles / products / plan /
+//     tenant_status) that SyncClaims maintains.
+//  2. GET /organizations/members/{id}/organizations — the memberships.
+//
+// One Claims entry per ENABLED organization: TenantID = org attribute
+// "tenant_id" (registry UUID), TenantSlug = org alias. A disabled org
+// grants no membership. A user in no organization has zero memberships —
+// the legacy user-attribute tenant projection is NO LONGER consulted for
+// membership, so a stale tenant_id/tenant_slug user attribute cannot
+// grant access the org model has revoked.
+func (a *HTTPAdapter) Memberships(ctx context.Context, userID string) ([]Claims, error) {
+	var u userRepresentation
+	resp, err := a.adminCall(ctx, http.MethodGet, "/users/"+userID, nil, &u)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode == http.StatusNotFound {
+		_ = resp.Body.Close()
+		return nil, ErrUserNotFound
+	}
+	if resp.StatusCode/100 != 2 {
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("keycloak get user: %d", resp.StatusCode)
+	}
+
+	var orgs []memberOrgRepresentation
+	resp, err = a.adminCall(
+		ctx, http.MethodGet, "/organizations/members/"+userID+"/organizations", nil, &orgs,
+	)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode/100 != 2 {
+		_ = resp.Body.Close()
+		return nil, fmt.Errorf("keycloak member organizations: %d", resp.StatusCode)
+	}
+
+	claims := []Claims{}
+	for _, org := range orgs {
+		if !org.Enabled {
+			continue
+		}
+		claims = append(claims, Claims{
+			TenantID:     attrValue(org.Attributes, "tenant_id"),
+			TenantSlug:   org.Alias,
+			OrgRoles:     attrValues(u.Attributes, "org_roles"),
+			Products:     attrValues(u.Attributes, "products"),
+			Plan:         attrValue(u.Attributes, "plan"),
+			TenantStatus: attrValue(u.Attributes, "tenant_status"),
+		})
+	}
+	return claims, nil
+}
+
+func attrValue(attrs map[string][]string, key string) string {
+	if vs := attrValues(attrs, key); len(vs) > 0 {
+		return vs[0]
+	}
+	return ""
+}
+
+func attrValues(attrs map[string][]string, key string) []string {
+	out := []string{}
+	for _, entry := range attrs[key] {
+		for _, v := range strings.Split(entry, "##") {
+			if v = strings.TrimSpace(v); v != "" {
+				out = append(out, v)
+			}
+		}
+	}
+	return out
+}

internal/keycloak/users_test.go

@@ -0,0 +1,177 @@
+package keycloak
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// stubUsersKC is a users+organizations KC look-alike; stubKC (client_test.go)
+// covers the org-create/invite paths and doesn't register these reads.
+func stubUsersKC(
+	t *testing.T,
+	users map[string]userRepresentation,
+	memberOrgs map[string][]memberOrgRepresentation,
+) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/realms/test-realm/protocol/openid-connect/token", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "test-token", "expires_in": 60})
+	})
+	mux.HandleFunc("GET /admin/realms/test-realm/users/{id}", func(w http.ResponseWriter, r *http.Request) {
+		u, ok := users[r.PathValue("id")]
+		if !ok {
+			w.WriteHeader(http.StatusNotFound)
+			_, _ = w.Write([]byte(`{"error":"User not found"}`))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(u)
+	})
+	mux.HandleFunc("GET /admin/realms/test-realm/organizations/members/{id}/organizations", func(w http.ResponseWriter, r *http.Request) {
+		orgs, ok := memberOrgs[r.PathValue("id")]
+		if !ok {
+			orgs = []memberOrgRepresentation{}
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(orgs)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func usersAdapter(srv *httptest.Server) *HTTPAdapter {
+	return NewHTTPAdapter(HTTPConfig{
+		BaseURL: srv.URL, Realm: "test-realm", ClientID: "svc", ClientSecret: "secret",
+	})
+}
+
+func TestHTTPAdapter_Memberships(t *testing.T) {
+	users := map[string]userRepresentation{
+		"u-1": {ID: "u-1", Username: "test@breakpilot.com", Enabled: true, Attributes: map[string][]string{
+			// legacy projection attrs — MUST NOT grant membership on their own
+			"tenant_id":     {"stale-legacy-001"},
+			"tenant_slug":   {"stale"},
+			"tenant_status": {"active"},
+			"plan":          {"Scale"},
+			"org_roles":     {"IT_ADMIN", "FINANCE"},
+			// the KC admin console writes multivalued attrs "##"-joined
+			"products": {"compliance##certifai"},
+		}},
+		"u-2": {ID: "u-2", Username: "bare@breakpilot.com", Enabled: true},
+		"u-3": {ID: "u-3", Username: "multi@breakpilot.com", Enabled: true},
+		"u-4": {ID: "u-4", Username: "attrs-only@breakpilot.com", Enabled: true, Attributes: map[string][]string{
+			"tenant_id":   {"acme-001"},
+			"tenant_slug": {"acme"},
+		}},
+	}
+	memberOrgs := map[string][]memberOrgRepresentation{
+		"u-1": {{
+			ID: "org-1", Alias: "acme", Enabled: true,
+			Attributes: map[string][]string{"tenant_id": {"2f875d6a-1d94-433a-b2ec-8529451a2d89"}},
+		}},
+		"u-3": {
+			{ID: "org-1", Alias: "acme", Enabled: true,
+				Attributes: map[string][]string{"tenant_id": {"2f875d6a-1d94-433a-b2ec-8529451a2d89"}}},
+			{ID: "org-2", Alias: "globex", Enabled: true,
+				Attributes: map[string][]string{"tenant_id": {"7c3f2b10-0000-4000-8000-000000000042"}}},
+			{ID: "org-3", Alias: "disabled-co", Enabled: false,
+				Attributes: map[string][]string{"tenant_id": {"9e9e9e9e-0000-4000-8000-000000000099"}}},
+		},
+	}
+	srv := stubUsersKC(t, users, memberOrgs)
+	a := usersAdapter(srv)
+
+	t.Run("org membership becomes the claim, org attrs are authoritative", func(t *testing.T) {
+		got, err := a.Memberships(context.Background(), "u-1")
+		if err != nil {
+			t.Fatalf("memberships: %v", err)
+		}
+		if len(got) != 1 {
+			t.Fatalf("want 1 membership, got %d", len(got))
+		}
+		c := got[0]
+		// tenant identity comes from the ORG (alias + tenant_id attribute),
+		// never from the user's legacy projection attributes
+		if c.TenantID != "2f875d6a-1d94-433a-b2ec-8529451a2d89" || c.TenantSlug != "acme" {
+			t.Errorf("org identity wrong: %+v", c)
+		}
+		// per-user claim attrs still ride along
+		if c.Plan != "Scale" || c.TenantStatus != "active" {
+			t.Errorf("user claim attrs wrong: %+v", c)
+		}
+		if len(c.OrgRoles) != 2 || c.OrgRoles[0] != "IT_ADMIN" || c.OrgRoles[1] != "FINANCE" {
+			t.Errorf("org_roles wrong: %v", c.OrgRoles)
+		}
+		if len(c.Products) != 2 || c.Products[0] != "compliance" || c.Products[1] != "certifai" {
+			t.Errorf("## split failed: %v", c.Products)
+		}
+	})
+
+	t.Run("user in no org has zero memberships", func(t *testing.T) {
+		got, err := a.Memberships(context.Background(), "u-2")
+		if err != nil {
+			t.Fatalf("memberships: %v", err)
+		}
+		if len(got) != 0 {
+			t.Fatalf("want 0 memberships, got %+v", got)
+		}
+	})
+
+	t.Run("legacy tenant attributes alone grant NO membership", func(t *testing.T) {
+		got, err := a.Memberships(context.Background(), "u-4")
+		if err != nil {
+			t.Fatalf("memberships: %v", err)
+		}
+		if len(got) != 0 {
+			t.Fatalf("attribute projection must not grant membership, got %+v", got)
+		}
+	})
+
+	t.Run("multiple orgs give multiple memberships, disabled org skipped", func(t *testing.T) {
+		got, err := a.Memberships(context.Background(), "u-3")
+		if err != nil {
+			t.Fatalf("memberships: %v", err)
+		}
+		if len(got) != 2 {
+			t.Fatalf("want 2 memberships (disabled org skipped), got %d", len(got))
+		}
+		if got[0].TenantSlug != "acme" || got[1].TenantSlug != "globex" {
+			t.Errorf("slugs wrong: %+v", got)
+		}
+	})
+
+	t.Run("unknown user is ErrUserNotFound", func(t *testing.T) {
+		_, err := a.Memberships(context.Background(), "nope")
+		if !errors.Is(err, ErrUserNotFound) {
+			t.Fatalf("want ErrUserNotFound, got %v", err)
+		}
+	})
+}
+
+func TestHTTPAdapter_Memberships_OrgQueryFailure(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/realms/test-realm/protocol/openid-connect/token", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "t", "expires_in": 60})
+	})
+	mux.HandleFunc("GET /admin/realms/test-realm/users/{id}", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(userRepresentation{ID: "u-1", Enabled: true})
+	})
+	mux.HandleFunc("GET /admin/realms/test-realm/organizations/members/{id}/organizations", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+
+	_, err := usersAdapter(srv).Memberships(context.Background(), "u-1")
+	if err == nil {
+		t.Fatal("want error when the org query fails, got nil")
+	}
+}

internal/product/product.go

@@ -0,0 +1,106 @@
+// Package product provisions a tenant into the downstream product database.
+//
+// The registry is the authority for tenant identity (ratified model B2), so a
+// product must anchor its own tenant row to the SAME canonical UUID. Without
+// this the anchors diverge: the registry knows "acme", the product database
+// does not, and the product's gate rejects every request from that tenant
+// because it cannot resolve the org slug.
+//
+// The Provisioner is a port, mirroring keycloak.Adapter: handlers depend on the
+// interface, main wires the HTTP implementation when PRODUCT_API_URL is set and
+// a no-op otherwise (dev convenience, and so an unconfigured deployment does
+// not fail tenant creation).
+package product
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+// ErrUnavailable means the product API could not be reached or refused us.
+var ErrUnavailable = errors.New("product: provisioning API unavailable")
+
+// Tenant is the minimal identity a product needs to create its own row.
+type Tenant struct {
+	ID   string `json:"id"` // the registry UUID — the whole point
+	Name string `json:"name"`
+	Slug string `json:"slug"`
+}
+
+// Provisioner creates the tenant in a product's own datastore.
+type Provisioner interface {
+	ProvisionTenant(ctx context.Context, t Tenant) error
+}
+
+// NoopProvisioner is wired when PRODUCT_API_URL is unset.
+type NoopProvisioner struct{}
+
+func (NoopProvisioner) ProvisionTenant(context.Context, Tenant) error { return nil }
+
+// AuthHeaderFunc supplies an Authorization header per call, so a token is
+// fetched lazily and refreshed rather than captured at construction. Nil means
+// no header, which is the correct behaviour against a product whose gate is
+// not yet enforcing.
+type AuthHeaderFunc func(context.Context) (string, error)
+
+// HTTPProvisioner calls the product's tenant-create endpoint.
+type HTTPProvisioner struct {
+	BaseURL string
+	Path    string // e.g. /sdk/v1/tenants
+	Auth    AuthHeaderFunc
+	Client  *http.Client
+}
+
+func NewHTTPProvisioner(baseURL, path string, auth AuthHeaderFunc, timeout time.Duration) *HTTPProvisioner {
+	if path == "" {
+		path = "/sdk/v1/tenants"
+	}
+	return &HTTPProvisioner{
+		BaseURL: baseURL, Path: path, Auth: auth,
+		Client: &http.Client{Timeout: timeout},
+	}
+}
+
+func (p *HTTPProvisioner) ProvisionTenant(ctx context.Context, t Tenant) error {
+	body, err := json.Marshal(t)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.BaseURL+p.Path, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if p.Auth != nil {
+		h, aerr := p.Auth(ctx)
+		if aerr != nil {
+			return fmt.Errorf("%w: %v", ErrUnavailable, aerr)
+		}
+		if h != "" {
+			req.Header.Set("Authorization", h)
+		}
+	}
+	resp, err := p.Client.Do(req)
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrUnavailable, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	switch {
+	case resp.StatusCode == http.StatusConflict:
+		// Already provisioned. The product's insert is idempotent on the
+		// primary key, so this is success from our point of view.
+		return nil
+	case resp.StatusCode/100 == 2:
+		return nil
+	default:
+		b, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return fmt.Errorf("%w: %d %s", ErrUnavailable, resp.StatusCode, b)
+	}
+}

internal/product/product_test.go

@@ -0,0 +1,88 @@
+package product
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// The whole point of this port: the product must be created with the
+// REGISTRY's uuid, so both systems anchor to the same tenant identity.
+func TestProvisionTenant_sendsTheRegistryUUID(t *testing.T) {
+	var got Tenant
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewDecoder(r.Body).Decode(&got)
+		w.WriteHeader(http.StatusCreated)
+	}))
+	defer srv.Close()
+
+	p := NewHTTPProvisioner(srv.URL, "/sdk/v1/tenants", nil, 5*time.Second)
+	err := p.ProvisionTenant(context.Background(), Tenant{
+		ID: "2f875d6a-1d94-433a-b2ec-8529451a2d89", Name: "Acme", Slug: "acme",
+	})
+	if err != nil {
+		t.Fatalf("provision: %v", err)
+	}
+	if got.ID != "2f875d6a-1d94-433a-b2ec-8529451a2d89" {
+		t.Errorf("registry uuid not sent: %+v", got)
+	}
+	if got.Slug != "acme" || got.Name != "Acme" {
+		t.Errorf("payload wrong: %+v", got)
+	}
+}
+
+// Re-provisioning must be safe: onboarding may retry, and the product's
+// insert is idempotent on the primary key.
+func TestProvisionTenant_conflictIsSuccess(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+	}))
+	defer srv.Close()
+
+	p := NewHTTPProvisioner(srv.URL, "", nil, 5*time.Second)
+	if err := p.ProvisionTenant(context.Background(), Tenant{ID: "x"}); err != nil {
+		t.Fatalf("409 should be treated as already-provisioned, got %v", err)
+	}
+}
+
+func TestProvisionTenant_serverErrorIsUnavailable(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	p := NewHTTPProvisioner(srv.URL, "", nil, 5*time.Second)
+	err := p.ProvisionTenant(context.Background(), Tenant{ID: "x"})
+	if !errors.Is(err, ErrUnavailable) {
+		t.Fatalf("want ErrUnavailable, got %v", err)
+	}
+}
+
+func TestProvisionTenant_attachesAuthHeaderWhenSupplied(t *testing.T) {
+	var seen string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusCreated)
+	}))
+	defer srv.Close()
+
+	p := NewHTTPProvisioner(srv.URL, "", func(context.Context) (string, error) {
+		return "Bearer tok-123", nil
+	}, 5*time.Second)
+	if err := p.ProvisionTenant(context.Background(), Tenant{ID: "x"}); err != nil {
+		t.Fatal(err)
+	}
+	if seen != "Bearer tok-123" {
+		t.Errorf("auth header = %q", seen)
+	}
+}
+
+func TestNoopProvisioner(t *testing.T) {
+	if err := (NoopProvisioner{}).ProvisionTenant(context.Background(), Tenant{}); err != nil {
+		t.Fatal(err)
+	}
+}

internal/server/audit_test.go

@@ -97,7 +97,10 @@ func TestAuditAutoEmittedOnTenantCreate(t *testing.T) {
 		_, body := h.do("POST", "/v1/tenants", map[string]any{
 			"slug": "audit-target", "name": "Audit Target",
 		})
-		fresh := decode[store.Tenant](t, body)
+		freshWrap := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		fresh := freshWrap.Tenant
 
 		resp, body := h.do("GET", "/v1/audit?action=tenant.created&tenant_id="+fresh.ID, nil)
 		if resp.StatusCode != 200 {

internal/server/catalog_test.go

@@ -50,7 +50,10 @@ func TestCatalogTrialRequest(t *testing.T) {
 		_, body := h.do("POST", "/v1/tenants", map[string]any{
 			"slug": "trial-target", "name": "Trial Target",
 		})
-		fresh := decode[store.Tenant](t, body)
+		freshWrap := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		fresh := freshWrap.Tenant
 
 		resp, body := h.do("POST", "/v1/catalog/trial-request", map[string]any{
 			"tenant_id": fresh.ID, "product": "compliance",

internal/server/helpers.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"log/slog"
+	"net"
 	"net/http"
 	"strings"
 	"time"
@@ -87,22 +88,23 @@ func (s *statusRecorder) WriteHeader(c int) {
 func clientIP(r *http.Request) string {
 	if fwd := r.Header.Get("X-Forwarded-For"); fwd != "" {
 		if i := strings.IndexByte(fwd, ','); i > 0 {
-			return strings.TrimSpace(fwd[:i])
+			return stripBrackets(strings.TrimSpace(fwd[:i]))
 		}
-		return strings.TrimSpace(fwd)
+		return stripBrackets(strings.TrimSpace(fwd))
 	}
-	if host, _, ok := splitHostPort(r.RemoteAddr); ok {
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		// net.SplitHostPort returns IPv6 without brackets already.
 		return host
 	}
-	return r.RemoteAddr
+	return stripBrackets(r.RemoteAddr)
 }
 
-// splitHostPort is a port-tolerant version of net.SplitHostPort that doesn't
-// error on missing port.
-func splitHostPort(s string) (string, string, bool) {
-	i := strings.LastIndexByte(s, ':')
-	if i < 0 {
-		return s, "", false
+// stripBrackets removes the `[...]` wrapping IPv6 hosts pick up from
+// net/http's RemoteAddr in some Go versions, since Postgres `inet` rejects
+// `[::1]` but accepts `::1`.
+func stripBrackets(s string) string {
+	if len(s) >= 2 && s[0] == '[' && s[len(s)-1] == ']' {
+		return s[1 : len(s)-1]
 	}
-	return s[:i], s[i+1:], true
+	return s
 }

internal/server/keycloak.go

@@ -0,0 +1,115 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
+)
+
+// provisionKeycloak is called inside createTenant after the DB insert
+// succeeds. Best-effort: a failure does NOT roll the tenant back. The
+// audit_log captures the error so the operator can heal it later
+// (resending the invite is a one-click in the KC admin UI).
+//
+// Returns the InviteURL so the API response can surface it for dev.
+func (s *Server) provisionKeycloak(ctx context.Context, t *store.Tenant, adminEmail, adminName string) (string, error) {
+	if adminEmail == "" {
+		// Skip silently — caller chose not to invite anyone yet (sales-led
+		// flow, demo tenant, test fixture, etc.).
+		return "", nil
+	}
+	res, err := s.Keycloak.CreateOrgAndInvite(ctx, keycloak.InviteInput{
+		TenantID:   t.ID,
+		Slug:       t.Slug,
+		Name:       t.Name,
+		AdminEmail: adminEmail,
+		AdminName:  adminName,
+	})
+	if err != nil {
+		s.Log.Error("keycloak provision failed",
+			"tenant_id", t.ID, "slug", t.Slug, "err", err)
+		return "", err
+	}
+	s.Log.Info("keycloak provisioned",
+		"tenant_id", t.ID, "kc_org_id", res.OrganizationID, "kc_user_id", res.UserID)
+	return res.InviteURL, nil
+}
+
+// kcClaims is POST /v1/internal/keycloak/claims. Called by Keycloak's
+// protocol mapper (or by a dev tester) to fetch the current entitlement
+// bundle for a user. Lookup chain:
+//  1. body.tenant_slug   → tenant
+//  2. body.tenant_id     → tenant
+//  3. body.user_attrs.tenant_id → tenant
+//
+// At least one must be present.
+type kcClaimsReq struct {
+	TenantID   string            `json:"tenant_id,omitempty"`
+	TenantSlug string            `json:"tenant_slug,omitempty"`
+	UserAttrs  map[string]string `json:"user_attrs,omitempty"`
+}
+
+func (s *Server) kcClaims(w http.ResponseWriter, r *http.Request) {
+	var in kcClaimsReq
+	if !decodeJSON(w, r, &in) {
+		return
+	}
+	id := in.TenantID
+	if id == "" {
+		id = in.UserAttrs["tenant_id"]
+	}
+	slug := in.TenantSlug
+	if slug == "" {
+		slug = in.UserAttrs["tenant_slug"]
+	}
+	if id == "" && slug == "" {
+		writeError(w, http.StatusBadRequest, "invalid_input", "tenant_id or tenant_slug required")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+	defer cancel()
+
+	var (
+		t   *store.Tenant
+		err error
+	)
+	if id != "" {
+		t, err = s.Store.GetTenant(ctx, id)
+	} else {
+		t, err = s.Store.GetTenantBySlug(ctx, slug)
+	}
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			writeError(w, http.StatusNotFound, "not_found", "tenant does not exist")
+			return
+		}
+		writeError(w, http.StatusInternalServerError, "internal", err.Error())
+		return
+	}
+
+	products, err := s.Store.ListTenantProducts(ctx, t.ID)
+	if err != nil && !errors.Is(err, store.ErrNotFound) {
+		writeError(w, http.StatusInternalServerError, "internal", err.Error())
+		return
+	}
+	productKeys := make([]string, 0, len(products))
+	for _, p := range products {
+		if p.Enabled {
+			productKeys = append(productKeys, p.Product)
+		}
+	}
+
+	writeJSON(w, http.StatusOK, keycloak.Claims{
+		TenantID:     t.ID,
+		TenantSlug:   t.Slug,
+		OrgRoles:     []string{}, // populated by /v1/users/:id role lookup — out of scope until M5.2
+		Products:     productKeys,
+		Plan:         t.Plan,
+		TenantStatus: t.Status,
+	})
+}

internal/server/keycloak_test.go

@@ -0,0 +1,147 @@
+package server_test
+
+import (
+	"net/http"
+	"testing"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
+)
+
+func TestCreateTenant_provisionsKeycloak(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, body := h.do("POST", "/v1/tenants", map[string]any{
+			"slug":        "kc-co",
+			"name":        "KC Co.",
+			"admin_email": "owner@kc-co.test",
+			"admin_name":  "Pat Owner",
+		})
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("status = %d, body=%s", resp.StatusCode, body)
+		}
+		out := decode[struct {
+			Tenant    *store.Tenant `json:"tenant"`
+			InviteURL string        `json:"invite_url"`
+		}](t, body)
+		if out.Tenant.Slug != "kc-co" {
+			t.Errorf("slug = %q", out.Tenant.Slug)
+		}
+		if out.InviteURL == "" {
+			t.Error("invite_url missing in response")
+		}
+
+		// The mock recorded the call.
+		if _, ok := h.kcMock.Orgs[out.Tenant.ID]; !ok {
+			t.Errorf("kc mock did not record org for tenant %s", out.Tenant.ID)
+		}
+		if _, ok := h.kcMock.Users["owner@kc-co.test"]; !ok {
+			t.Error("kc mock did not record user for owner@kc-co.test")
+		}
+
+		// And we emitted a keycloak.invite_sent audit event.
+		resp, body = h.do("GET",
+			"/v1/audit?action=keycloak.invite_sent&tenant_id="+out.Tenant.ID, nil)
+		if resp.StatusCode != 200 {
+			t.Fatalf("audit list status = %d", resp.StatusCode)
+		}
+		listed := decode[struct {
+			Items []store.AuditEvent `json:"items"`
+		}](t, body)
+		if len(listed.Items) != 1 {
+			t.Errorf("expected 1 invite_sent event, got %d", len(listed.Items))
+		}
+	})
+}
+
+func TestCreateTenant_kcFailure_doesNotRollback(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		// Force the mock to fail the next call.
+		h.kcMock.FailNext = keycloak.ErrUnavailable
+
+		resp, body := h.do("POST", "/v1/tenants", map[string]any{
+			"slug": "kc-fail", "name": "KC Fail", "admin_email": "x@y.test",
+		})
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected tenant still created despite kc fail; status=%d body=%s",
+				resp.StatusCode, body)
+		}
+		out := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		// Tenant landed in the DB.
+		if out.Tenant.ID == "" {
+			t.Error("tenant id missing")
+		}
+		// And there's a provision_failed audit event for it.
+		_, body = h.do("GET",
+			"/v1/audit?action=keycloak.provision_failed&tenant_id="+out.Tenant.ID, nil)
+		listed := decode[struct {
+			Items []store.AuditEvent `json:"items"`
+		}](t, body)
+		if len(listed.Items) != 1 {
+			t.Errorf("expected 1 provision_failed event, got %d", len(listed.Items))
+		}
+	})
+}
+
+func TestKcClaims_returnsCurrentEntitlements(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, body := h.do("POST", "/v1/internal/keycloak/claims", map[string]any{
+			"tenant_slug": h.tenant.Slug,
+		})
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("status = %d, body=%s", resp.StatusCode, body)
+		}
+		got := decode[keycloak.Claims](t, body)
+		if got.TenantID != h.tenant.ID || got.TenantSlug != h.tenant.Slug {
+			t.Errorf("tenant fields off: %+v", got)
+		}
+		if got.Plan != h.tenant.Plan {
+			t.Errorf("plan = %q, want %q", got.Plan, h.tenant.Plan)
+		}
+		if got.TenantStatus != h.tenant.Status {
+			t.Errorf("status = %q, want %q", got.TenantStatus, h.tenant.Status)
+		}
+		// acme is seeded with certifai + compliance entitlements (memory)
+		// or one or zero (postgres, depending on prior subtest ordering).
+		// At minimum the field is present.
+		if got.Products == nil {
+			t.Error("products is nil; should be at least empty slice")
+		}
+	})
+}
+
+func TestKcClaims_lookupByUserAttrs(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, body := h.do("POST", "/v1/internal/keycloak/claims", map[string]any{
+			"user_attrs": map[string]string{"tenant_slug": h.tenant.Slug},
+		})
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("status = %d, body=%s", resp.StatusCode, body)
+		}
+		got := decode[keycloak.Claims](t, body)
+		if got.TenantID != h.tenant.ID {
+			t.Errorf("did not resolve via user_attrs; got %+v", got)
+		}
+	})
+}
+
+func TestKcClaims_missingTenant404(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, _ := h.do("POST", "/v1/internal/keycloak/claims", map[string]any{
+			"tenant_slug": "nope-nope",
+		})
+		if resp.StatusCode != http.StatusNotFound {
+			t.Errorf("status = %d, want 404", resp.StatusCode)
+		}
+	})
+}
+
+func TestKcClaims_requiresInput(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, _ := h.do("POST", "/v1/internal/keycloak/claims", map[string]any{})
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Errorf("status = %d, want 400", resp.StatusCode)
+		}
+	})
+}

internal/server/openapi_test.go

@@ -44,6 +44,7 @@ func TestOpenAPISpec_loadsAndIsConsistent(t *testing.T) {
 		{"GET", "/v1/api-keys?tenant_id=00000000-0000-0000-0000-000000000001"},
 		{"GET", "/v1/catalog"},
 		{"GET", "/v1/audit?limit=10"},
+		{"POST", "/v1/internal/keycloak/claims"},
 	}
 	for _, c := range cases {
 		req := newRequest(t, c.method, c.path)

internal/server/server.go

@@ -1,14 +1,18 @@
 // 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 (
+	"errors"
 	"log/slog"
 	"net/http"
 
+	"gitea.meghsakha.com/platform/tenant-registry/internal/authn"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/product"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
 
@@ -17,15 +21,36 @@ type Server struct {
 	Cfg      *config.Config
 	Log      *slog.Logger
 	Store    store.Store
+	Keycloak keycloak.Adapter    // never nil — main wires Mock when KC env is unset
+	Auth     *authn.Verifier     // nil ⇒ AUTH_ENABLED=false, API is open (dev only)
+	Product  product.Provisioner // never nil — main wires Noop when PRODUCT_API_URL is unset
+}
+
+// productProvisioner guarantees the "never nil" invariant the struct documents.
+// Tests construct Server directly and would otherwise panic; an unset provisioner
+// simply means no downstream provisioning, never a crash mid-tenant-creation.
+func (s *Server) productProvisioner() product.Provisioner {
+	if s.Product == nil {
+		return product.NoopProvisioner{}
+	}
+	return s.Product
 }
 
 // NewRouter builds the http.Handler with logging middleware applied.
+//
+// Route auth classes (ratified auth design): /healthz and /readyz are
+// PUBLIC_EXPLICIT (orca probes, no auth by design); every other route is
+// INTERNAL_SERVICE_ONLY and sits behind requireAuth. New routes land in
+// the protected mux by construction — registering one on the root mux is
+// the exception and needs a PUBLIC_EXPLICIT justification comment.
 func NewRouter(s *Server) http.Handler {
-	mux := http.NewServeMux()
+	root := http.NewServeMux()
 
-	// health + status
-	mux.HandleFunc("GET /healthz", s.healthz)
-	mux.HandleFunc("GET /readyz", s.readyz)
+	// PUBLIC_EXPLICIT: health + status probes.
+	root.HandleFunc("GET /healthz", s.healthz)
+	root.HandleFunc("GET /readyz", s.readyz)
+
+	mux := http.NewServeMux()
 
 	// tenants
 	mux.HandleFunc("POST /v1/tenants", s.createTenant)
@@ -34,9 +59,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 +67,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,7 +77,41 @@ func NewRouter(s *Server) http.Handler {
 	mux.HandleFunc("POST /v1/audit", s.appendAudit)
 	mux.HandleFunc("GET /v1/audit", s.listAudit)
 
-	return logRequest(s.Log)(mux)
+	// 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)
+
+	// memberships — the B2 membership authority: which tenants does a
+	// JWT subject belong to, with which org_roles and entitlements.
+	mux.HandleFunc("GET /v1/users/{id}/memberships", s.getUserMemberships)
+
+	root.Handle("/", s.requireAuth(mux))
+	return logRequest(s.Log)(root)
+}
+
+// requireAuth gates the INTERNAL_SERVICE_ONLY routes. With Auth nil
+// (AUTH_ENABLED=false) it passes through — the startup log carries the
+// warning, and the Auth-5 activation flips the env, not the code.
+func (s *Server) requireAuth(next http.Handler) http.Handler {
+	if s.Auth == nil {
+		return next
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		p, err := s.Auth.Verify(r.Context(), r.Header.Get("Authorization"))
+		if err != nil {
+			if errors.Is(err, authn.ErrNoToken) {
+				writeError(w, http.StatusUnauthorized, "TOKEN_MISSING", "bearer token required")
+				return
+			}
+			// Signature, issuer, expiry, and audience failures all land
+			// here; the message says which without echoing the token.
+			writeError(w, http.StatusUnauthorized, "TOKEN_INVALID", err.Error())
+			return
+		}
+		next.ServeHTTP(w, r.WithContext(authn.WithPrincipal(r.Context(), p)))
+	})
 }
 
 func (s *Server) healthz(w http.ResponseWriter, _ *http.Request) {
@@ -67,5 +123,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"})
 }

internal/server/server_test.go

@@ -21,6 +21,7 @@ import (
 	tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
 
 	"gitea.meghsakha.com/platform/tenant-registry/internal/config"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/server"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 	"gitea.meghsakha.com/platform/tenant-registry/migrations"
@@ -33,6 +34,7 @@ type testHarness struct {
 	srv    *httptest.Server
 	store  store.Store
 	tenant *store.Tenant // pre-created acme tenant
+	kcMock *keycloak.Mock
 }
 
 func (h *testHarness) Close() {
@@ -131,14 +133,19 @@ func newPostgresHarness(t *testing.T) *testHarness {
 func wireHarness(t *testing.T, s store.Store, seed *store.Tenant) *testHarness {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	mock := keycloak.NewMock()
 	handler := server.NewRouter(&server.Server{
-		Cfg: &config.Config{Env: "dev"}, Log: logger, Store: s,
+		Cfg:      &config.Config{Env: "dev"},
+		Log:      logger,
+		Store:    s,
+		Keycloak: mock,
 	})
 	return &testHarness{
 		t:      t,
 		srv:    httptest.NewServer(handler),
 		store:  s,
 		tenant: seed,
+		kcMock: mock,
 	}
 }
 

internal/server/tenants.go

@@ -7,6 +7,7 @@ import (
 	"regexp"
 	"time"
 
+	"gitea.meghsakha.com/platform/tenant-registry/internal/product"
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
 
@@ -20,6 +21,18 @@ type createTenantReq struct {
 	Plan       string `json:"plan,omitempty"`
 	Kind       string `json:"kind,omitempty"`
 	SalesOwner string `json:"sales_owner,omitempty"`
+	// AdminEmail is optional. When set, the Keycloak adapter provisions
+	// an organization + invites this user as IT_ADMIN. Omitted for
+	// sales-led flows that invite the admin later via the portal.
+	AdminEmail string `json:"admin_email,omitempty"`
+	AdminName  string `json:"admin_name,omitempty"`
+}
+
+// createTenantResp wraps the tenant with the optional KC invite URL so
+// dev testers can use it without waiting for the email.
+type createTenantResp struct {
+	Tenant    *store.Tenant `json:"tenant"`
+	InviteURL string        `json:"invite_url,omitempty"`
 }
 
 func (s *Server) createTenant(w http.ResponseWriter, r *http.Request) {
@@ -40,7 +53,7 @@ func (s *Server) createTenant(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
 	defer cancel()
 	t, err := s.Store.CreateTenant(ctx, store.TenantCreate{
 		Slug: in.Slug, Name: in.Name, Plan: in.Plan, Kind: in.Kind, SalesOwner: in.SalesOwner,
@@ -63,7 +76,46 @@ func (s *Server) createTenant(w http.ResponseWriter, r *http.Request) {
 		Metadata:   map[string]interface{}{"plan": t.Plan, "kind": t.Kind},
 	})
 
-	writeJSON(w, http.StatusCreated, t)
+	// Best-effort Keycloak provisioning. A failure here doesn't roll the
+	// tenant back — the operator can resend the invite via the KC admin UI.
+	// We emit an audit event regardless so the failure is traceable.
+	inviteURL, kcErr := s.provisionKeycloak(ctx, t, in.AdminEmail, in.AdminName)
+	if kcErr != nil {
+		s.emitAudit(ctx, r, store.AuditEvent{
+			TenantID: t.ID, Action: "keycloak.provision_failed",
+			TargetID: t.ID, TargetType: "tenant",
+			Metadata: map[string]interface{}{"err": kcErr.Error(), "admin_email": in.AdminEmail},
+		})
+	} else if in.AdminEmail != "" {
+		s.emitAudit(ctx, r, store.AuditEvent{
+			TenantID: t.ID, Action: "keycloak.invite_sent",
+			TargetID: in.AdminEmail, TargetType: "user", TargetName: in.AdminEmail,
+			Metadata: map[string]interface{}{"role": "IT_ADMIN"},
+		})
+	}
+
+	// Best-effort product provisioning, same contract as Keycloak above: the
+	// registry is the authority for tenant identity, so the product gets a row
+	// keyed by OUR uuid. A failure must not roll the tenant back — it is
+	// recorded as an audit event so the divergence is traceable and fixable.
+	// Without this the anchors drift and the product's gate rejects every
+	// request from the tenant because it cannot resolve the org slug.
+	if perr := s.productProvisioner().ProvisionTenant(ctx, product.Tenant{
+		ID: t.ID, Name: t.Name, Slug: t.Slug,
+	}); perr != nil {
+		s.emitAudit(ctx, r, store.AuditEvent{
+			TenantID: t.ID, Action: "product.provision_failed",
+			TargetID: t.ID, TargetType: "tenant",
+			Metadata: map[string]interface{}{"err": perr.Error()},
+		})
+	} else {
+		s.emitAudit(ctx, r, store.AuditEvent{
+			TenantID: t.ID, Action: "product.tenant_provisioned",
+			TargetID: t.ID, TargetType: "tenant",
+		})
+	}
+
+	writeJSON(w, http.StatusCreated, createTenantResp{Tenant: t, InviteURL: inviteURL})
 }
 
 func (s *Server) getTenant(w http.ResponseWriter, r *http.Request) {

internal/server/tenants_test.go

@@ -3,6 +3,7 @@ package server_test
 import (
 	"net/http"
 	"testing"
+	"time"
 
 	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
 )
@@ -24,9 +25,12 @@ func TestCreateTenant(t *testing.T) {
 		if resp.StatusCode != http.StatusCreated {
 			t.Fatalf("status = %d, body=%s", resp.StatusCode, body)
 		}
-		t1 := decode[store.Tenant](t, body)
-		if t1.Slug != "beta-co" || t1.Status != "trial" || t1.Plan != "starter" {
-			t.Errorf("unexpected: %+v", t1)
+		out := decode[struct {
+			Tenant    *store.Tenant `json:"tenant"`
+			InviteURL string        `json:"invite_url"`
+		}](t, body)
+		if out.Tenant.Slug != "beta-co" || out.Tenant.Status != "trial" || out.Tenant.Plan != "starter" {
+			t.Errorf("unexpected: %+v", out.Tenant)
 		}
 	})
 }
@@ -81,7 +85,10 @@ func TestActivateTenant(t *testing.T) {
 		_, body := h.do("POST", "/v1/tenants", map[string]any{
 			"slug": "trial-co", "name": "Trial Co.",
 		})
-		created := decode[store.Tenant](t, body)
+		createdWrap := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		created := createdWrap.Tenant
 		if created.Status != "trial" {
 			t.Fatalf("precondition: %q", created.Status)
 		}
@@ -113,3 +120,42 @@ func TestCancelTenant(t *testing.T) {
 		}
 	})
 }
+
+func TestCreateTenant_setsTrialEndsAt(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		_, body := h.do("POST", "/v1/tenants", map[string]any{
+			"slug": "trial-ends-co", "name": "Trial Ends Co.",
+		})
+		out := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		if out.Tenant.Status != "trial" {
+			t.Fatalf("status = %q, want trial", out.Tenant.Status)
+		}
+		if out.Tenant.TrialEndsAt == nil {
+			t.Fatal("trial_ends_at is nil; should be ~14 days from now")
+		}
+		// Sanity-check: ends_at is in the future, within 13.5-14.5 days.
+		delta := time.Until(*out.Tenant.TrialEndsAt)
+		if delta < 13*24*time.Hour || delta > 15*24*time.Hour {
+			t.Errorf("trial_ends_at offset = %v, want ~14d", delta)
+		}
+	})
+}
+
+func TestCreateTenant_demoKindHasNoTrialEnd(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		_, body := h.do("POST", "/v1/tenants", map[string]any{
+			"slug": "demo-co", "name": "Demo", "kind": "demo",
+		})
+		out := decode[struct {
+			Tenant *store.Tenant `json:"tenant"`
+		}](t, body)
+		if out.Tenant.Status != "demo" {
+			t.Errorf("status = %q, want demo", out.Tenant.Status)
+		}
+		if out.Tenant.TrialEndsAt != nil {
+			t.Errorf("trial_ends_at = %v, want nil for demo kind", out.Tenant.TrialEndsAt)
+		}
+	})
+}

internal/server/users.go

@@ -0,0 +1,104 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+	"gitea.meghsakha.com/platform/tenant-registry/internal/store"
+)
+
+// membershipItem is one tenant a user belongs to. Source records which
+// system produced the authoritative half: "registry" when the tenant exists
+// here (status/plan/products come from our tables), "keycloak" when only
+// the attribute projection knows it (e.g. a tenant seeded directly in the
+// realm that the registry has not onboarded yet).
+type membershipItem struct {
+	keycloak.Claims
+	Source string `json:"source"`
+}
+
+type membershipsResp struct {
+	UserID      string           `json:"user_id"`
+	Memberships []membershipItem `json:"memberships"`
+}
+
+// getUserMemberships is GET /v1/users/{id}/memberships — the membership
+// authority endpoint (ratified auth design, model B2). Product backends
+// call it to answer "which tenants does this JWT subject belong to, with
+// which roles", instead of trusting token claims or client headers.
+//
+// Resolution: Keycloak (via the Adapter) supplies user→tenant links and
+// org_roles; where the tenant is registered here, status, plan, and
+// product entitlements are overridden from the registry tables, which are
+// authoritative for lifecycle and billing state.
+func (s *Server) getUserMemberships(w http.ResponseWriter, r *http.Request) {
+	userID := r.PathValue("id")
+	if userID == "" {
+		writeError(w, http.StatusBadRequest, "invalid_input", "user id required")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+
+	claims, err := s.Keycloak.Memberships(ctx, userID)
+	if err != nil {
+		switch {
+		case errors.Is(err, keycloak.ErrUserNotFound):
+			writeError(w, http.StatusNotFound, "not_found", "user does not exist")
+		case errors.Is(err, keycloak.ErrUnavailable), errors.Is(err, keycloak.ErrUnauthorized):
+			writeError(w, http.StatusServiceUnavailable, "keycloak_unavailable", err.Error())
+		default:
+			writeError(w, http.StatusInternalServerError, "internal", err.Error())
+		}
+		return
+	}
+
+	items := make([]membershipItem, 0, len(claims))
+	for _, c := range claims {
+		items = append(items, s.enrichMembership(ctx, c))
+	}
+	writeJSON(w, http.StatusOK, membershipsResp{UserID: userID, Memberships: items})
+}
+
+// enrichMembership overrides the Keycloak attribute projection with
+// registry truth when the tenant is known here. Lookup prefers the slug —
+// the attribute tenant_id predates the registry for hand-seeded dev users
+// and may not be a registry id.
+func (s *Server) enrichMembership(ctx context.Context, c keycloak.Claims) membershipItem {
+	var (
+		t   *store.Tenant
+		err error
+	)
+	if c.TenantSlug != "" {
+		t, err = s.Store.GetTenantBySlug(ctx, c.TenantSlug)
+	} else {
+		t, err = s.Store.GetTenant(ctx, c.TenantID)
+	}
+	if err != nil || t == nil {
+		return membershipItem{Claims: c, Source: "keycloak"}
+	}
+
+	products := []string{}
+	if tps, perr := s.Store.ListTenantProducts(ctx, t.ID); perr == nil {
+		for _, p := range tps {
+			if p.Enabled {
+				products = append(products, p.Product)
+			}
+		}
+	}
+	return membershipItem{
+		Claims: keycloak.Claims{
+			TenantID:     t.ID,
+			TenantSlug:   t.Slug,
+			OrgRoles:     c.OrgRoles, // roles stay Keycloak-owned
+			Products:     products,
+			Plan:         t.Plan,
+			TenantStatus: t.Status,
+		},
+		Source: "registry",
+	}
+}

internal/server/users_test.go

@@ -0,0 +1,74 @@
+package server_test
+
+import (
+	"net/http"
+	"testing"
+
+	"gitea.meghsakha.com/platform/tenant-registry/internal/keycloak"
+)
+
+type membershipsBody struct {
+	UserID      string `json:"user_id"`
+	Memberships []struct {
+		keycloak.Claims
+		Source string `json:"source"`
+	} `json:"memberships"`
+}
+
+func TestGetUserMemberships(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		// The KC attribute projection carries a stale plan/status and a
+		// legacy tenant_id — the registry row must win (source: registry).
+		h.kcMock.Claims["u-1"] = keycloak.Claims{
+			TenantID: "kc-legacy-id", TenantSlug: "acme",
+			OrgRoles: []string{"IT_ADMIN"}, Plan: "stale-plan", TenantStatus: "stale",
+		}
+		resp, raw := h.do(http.MethodGet, "/v1/users/u-1/memberships", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("status %d: %s", resp.StatusCode, raw)
+		}
+		body := decode[membershipsBody](t, raw)
+		if body.UserID != "u-1" || len(body.Memberships) != 1 {
+			t.Fatalf("unexpected body: %s", raw)
+		}
+		m := body.Memberships[0]
+		if m.Source != "registry" {
+			t.Errorf("want source registry, got %q", m.Source)
+		}
+		if m.TenantID != h.tenant.ID || m.TenantSlug != "acme" {
+			t.Errorf("registry identity not authoritative: %+v", m.Claims)
+		}
+		if m.Plan != h.tenant.Plan || m.TenantStatus != h.tenant.Status {
+			t.Errorf("registry lifecycle not authoritative: plan=%q status=%q", m.Plan, m.TenantStatus)
+		}
+		if len(m.OrgRoles) != 1 || m.OrgRoles[0] != "IT_ADMIN" {
+			t.Errorf("org_roles must stay keycloak-owned: %v", m.OrgRoles)
+		}
+	})
+}
+
+func TestGetUserMemberships_unknownTenantFallsBackToKeycloak(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		h.kcMock.Claims["u-2"] = keycloak.Claims{
+			TenantID: "ghost-001", TenantSlug: "ghost",
+			OrgRoles: []string{"USER"}, Plan: "Scale", TenantStatus: "active",
+		}
+		resp, raw := h.do(http.MethodGet, "/v1/users/u-2/memberships", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("status %d: %s", resp.StatusCode, raw)
+		}
+		m := decode[membershipsBody](t, raw).Memberships[0]
+		if m.Source != "keycloak" || m.TenantSlug != "ghost" || m.Plan != "Scale" {
+			t.Errorf("expected untouched keycloak projection, got %+v (source %q)", m.Claims, m.Source)
+		}
+	})
+}
+
+func TestGetUserMemberships_unknownUser404(t *testing.T) {
+	eachStore(t, func(t *testing.T, h *testHarness) {
+		resp, _ := h.do(http.MethodGet, "/v1/users/nobody/memberships", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("want 404, got %d", resp.StatusCode)
+		}
+	})
+}

internal/store/memory.go

@@ -69,14 +69,24 @@ func (m *Memory) CreateTenant(_ context.Context, in TenantCreate) (*Tenant, erro
 		return nil, ErrConflict
 	}
 	now := time.Now().UTC()
+	kind := firstNonEmpty(in.Kind, "customer")
+	status := "trial"
+	var trialEnds *time.Time
+	if kind == "demo" {
+		status = "demo"
+	} else {
+		end := now.Add(14 * 24 * time.Hour)
+		trialEnds = &end
+	}
 	t := &Tenant{
 		ID:          uuid.NewString(),
 		Slug:        in.Slug,
 		Name:        in.Name,
-		Status:     "trial",
-		Kind:       firstNonEmpty(in.Kind, "customer"),
+		Status:      status,
+		Kind:        kind,
 		Plan:        firstNonEmpty(in.Plan, "starter"),
 		SalesOwner:  in.SalesOwner,
+		TrialEndsAt: trialEnds,
 		CreatedAt:   now,
 		UpdatedAt:   now,
 	}

internal/store/postgres.go

@@ -90,9 +90,20 @@ func scanTenant(row pgx.Row) (*Tenant, error) {
 func (p *Postgres) CreateTenant(ctx context.Context, in TenantCreate) (*Tenant, error) {
 	kind := firstNonEmpty(in.Kind, "customer")
 	plan := firstNonEmpty(in.Plan, "starter")
+	// Default status = 'trial'; set trial_ends_at = NOW() + 14 days so the
+	// portal's trial banner has a real countdown to render. Demo tenants
+	// (kind=demo) get status='demo' and no trial_ends_at — that's set by
+	// the M13.2 demo provisioning path.
 	row := p.pool.QueryRow(ctx,
-		`INSERT INTO tenants (slug, name, kind, plan, sales_owner)
-		 VALUES ($1, $2, $3::tenant_kind, $4, NULLIF($5, ''))
+		`INSERT INTO tenants (slug, name, kind, plan, status, sales_owner, trial_ends_at)
+		 VALUES (
+		   $1, $2, $3::tenant_kind, $4,
+		   CASE WHEN $3::tenant_kind = 'demo' THEN 'demo'::tenant_status
+		        ELSE 'trial'::tenant_status END,
+		   NULLIF($5, ''),
+		   CASE WHEN $3::tenant_kind = 'demo' THEN NULL
+		        ELSE NOW() + INTERVAL '14 days' END
+		 )
 		 RETURNING id::text, slug, name, status::text, kind::text, plan,
 		           COALESCE(erp_customer_id,''), COALESCE(stripe_cust_id,''),
 		           trial_ends_at, contract_start, contract_end, COALESCE(sales_owner,''),

openapi.yaml

@@ -8,7 +8,10 @@ info:
     `PLATFORM_ARCHITECTURE.md §5c` for the schema, and
     `PRODUCT_INTEGRATION_SPEC.md §8.4` for the audit shape.
 
-    This API is not yet authenticated — M4.3 adds Keycloak JWT validation.
+    Auth (RBAC Phase 1): with AUTH_ENABLED=true every route except
+    /healthz and /readyz requires a Keycloak-issued bearer token whose
+    audience contains AUTH_EXPECTED_AUDIENCE (INTERNAL_SERVICE_ONLY
+    posture). With AUTH_ENABLED=false (dev default) the API is open.
   contact:
     email: oncall@breakpilot.com
   license:
@@ -48,15 +51,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 +253,78 @@ paths:
           description: Revoked.
         "404": { $ref: "#/components/responses/NotFound" }
 
+  /v1/users/{id}/memberships:
+    get:
+      summary: Resolve which tenants a user belongs to (membership authority).
+      description: |
+        The B2 membership-authority endpoint (ratified compliance auth
+        design). Product backends call this with the JWT `sub` instead of
+        trusting token claims or client-supplied headers. Keycloak supplies
+        the user→tenant links and org_roles; where the tenant is registered
+        here, tenant_status / plan / products are overridden from registry
+        tables (source: "registry"), otherwise the Keycloak attribute
+        projection is returned as-is (source: "keycloak").
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Keycloak user id (the JWT `sub`).
+          schema: { type: string }
+      responses:
+        "200":
+          description: Memberships (possibly empty) for the user.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [user_id, memberships]
+                properties:
+                  user_id: { type: string }
+                  memberships:
+                    type: array
+                    items:
+                      allOf:
+                        - $ref: "#/components/schemas/Claims"
+                        - type: object
+                          required: [source]
+                          properties:
+                            source: { type: string, enum: [registry, keycloak] }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "503":
+          description: Keycloak unreachable — membership cannot be resolved.
+          content:
+            application/json: { schema: { $ref: "#/components/schemas/Error" } }
+
+  /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
@@ -320,6 +402,15 @@ paths:
         "400": { $ref: "#/components/responses/BadRequest" }
 
 components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        Keycloak-issued token (client_credentials for services). Enforced
+        on all non-health routes when AUTH_ENABLED=true.
+
   responses:
     BadRequest:
       description: Input failed validation.
@@ -335,6 +426,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 +472,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