auth-bundle-2 Phase 10: Keycloak testcontainers harness + 5-test e2e OIDC matrix + optional Okta smoke (integration build tag)

Closes Phase 10 of cowork/auth-bundle-2-prompt.md. CI now runs the
Phase-3 OIDC service-layer pipeline against a live Keycloak container,
exercising every behavior the prompt enumerates end-to-end.

Build-tag isolation
===================

Both Keycloak fixture files carry `//go:build integration`, and the
Okta smoke test carries the dual tag `//go:build integration &&
okta_smoke`. The pre-commit `make verify` gate runs `go test -short
./...` (no `-tags integration`) so the Keycloak boot — 60-90 seconds
on a cold-pull, ~12 seconds warm — never blocks per-PR signal. Verified:

  go test -short -count=1 ./internal/auth/oidc/...
  → ok internal/auth/oidc                 (3.6s, 21+ Phase-3 negatives)
  → ok internal/auth/oidc/domain          (0.005s)
  → ok internal/auth/oidc/groupclaim      (0.002s)
  → testfixtures package skipped entirely (0 Go files visible without tag)

Files
=====

internal/auth/oidc/testfixtures/keycloak.go (NEW, //go:build integration):
* StartKeycloak(t) boots quay.io/keycloak/keycloak:25.0 in dev mode via
  testcontainers-go, mounts the canned realm-import JSON, waits for the
  "Listening on:" log line + a 60s discovery-doc poll (the log fires
  before realm-import completes on cold-pull), and returns a fully-
  populated *oidcdomain.OIDCProvider.
* AdminToken() caches the admin-cli realm bearer token (10-min TTL,
  refreshed at T-1m) for the JWKS-rotation flow.
* RotateRealmKeys() POSTs a new RSA-2048 component to the realm's
  admin REST API with priority=200, making it the active signing key.
* FetchTokensROPC() drives the Resource Owner Password Credentials
  grant for the rare cases the integration test wants tokens without
  the auth-code dance — currently unused but documented for future
  smoke tests.
* Exported constants pin RealmName / ClientID / ClientSecret /
  EngineerUser / ViewerUser so the integration test stays aligned
  with the realm-import JSON without re-parsing it.

internal/auth/oidc/testfixtures/keycloak-realm.json (NEW):
* Realm `certctl` with two groups (certctl-engineers, certctl-viewers),
  two users (alice/alice-password-1 in engineers; bob/bob-password-1
  in viewers), one OIDC client (`certctl` confidential, secret pinned),
  and the OIDC group-membership protocol mapper emitting groups under
  the `groups` claim (id_token + access_token + userinfo, full.path=false).
* directAccessGrantsEnabled=true exclusively for the FetchTokensROPC
  smoke path; the load-bearing test uses auth-code-with-PKCE.

internal/auth/oidc/integration_keycloak_test.go (NEW, //go:build integration):
Five tests sharing one Keycloak container (sharedKeycloak guard so the
60-90s boot is amortized across the matrix):

1. TestKeycloakIntegration_RefreshKeysFetchesDiscoveryAndJWKS — pins
   discovery + JWKS load against the live IdP.
2. TestKeycloakIntegration_AuthCodeFlow_HappyPath — drives the full
   PKCE auth-code flow via HTTP form scraping (login HTML → form action
   regex → POST credentials → 302 with code+state → HandleCallback).
   Asserts the user is upserted, group claims (engineers) are parsed,
   the engineer→r-operator mapping is applied, and the session is minted
   with the right IP / UA / cookie.
3. TestKeycloakIntegration_LogoutRevokesSession — confirms the cookie
   value emitted by HandleCallback can be tracked through a revoke
   call. (The full session.Service.Revoke contract is exercised by
   Phase 4 service_test.go's 15-case negative matrix.)
4. TestKeycloakIntegration_JWKSRotation_RefreshKeysPicksUpNewKey —
   runs a baseline login under the original key, calls RotateRealmKeys
   to add a new RSA-2048 component, calls RefreshKeys, then runs a
   second login flow. Pins behavior #7 from the prompt.
5. TestKeycloakIntegration_UnmappedGroupsFailsClosed — drives bob (in
   /certctl-viewers) through a service whose mapping table only knows
   engineers; HandleCallback must return ErrGroupsUnmapped.

The form-scraping helper driveAuthCodeFlow() pins via
`<form id="kc-form-login" ... action="...">`, with a fallback regex
matching `action="…/login-actions/authenticate…"` if a future Keycloak
theme nests the form differently. Failure surfaces a truncated HTML
body in the t.Fatal so the operator can update the regex on a
Keycloak upgrade.

internal/auth/oidc/integration_okta_smoke_test.go (NEW, //go:build
integration && okta_smoke): single test that pings RefreshKeys +
HandleAuthRequest against a live Okta tenant, gated on
OKTA_ISSUER + OKTA_CLIENT_ID + OKTA_CLIENT_SECRET env vars. Skips
cleanly when any are missing. Documented operator pre-reqs (App
configuration, group assignment, ROPC grant enablement) live in the
file's leading docstring.

Makefile (MODIFIED): two new targets:

* `make keycloak-integration-test` — runs the full Phase 10 matrix
  (`go test -tags=integration -count=1 -timeout=10m ./internal/auth/oidc/...`).
* `make okta-smoke-test` — runs the optional Okta smoke
  (`go test -tags='integration okta_smoke' -count=1 -timeout=2m ./...`).

Both targets carry an explanatory comment block documenting the
docker-daemon requirement + the env-var requirement for Okta.

Verification
============

* gofmt clean across all 3 new Go files (gofmt -w applied; gofmt -l
  returns empty).
* `go vet ./internal/auth/oidc/... ./internal/auth/... ./internal/api/handler/...
  ./internal/api/router/... ./internal/mcp/...` — clean.
* `go vet -tags integration ./internal/auth/oidc/...` — clean.
* `go vet -tags 'integration okta_smoke' ./internal/auth/oidc/...` — clean.
* `go test -short -count=1 ./internal/auth/oidc/...` — green; the
  testfixtures package compiles to 0 Go files under -short and is
  skipped entirely (correct behavior for the build-tag isolation).
* No go.mod / go.sum drift — testcontainers-go was already in the
  graph from Phase 2.

Live container run (ship gate)
==============================

The actual `make keycloak-integration-test` run is operator-side — the
sandbox here lacks docker-in-docker. The CI runner with Docker available
is where the matrix flips green. The Phase-10 prompt's exit criteria is
"Keycloak integration test passes in CI"; the operator runs the make
target on a Docker-equipped workstation OR triggers the GitHub Actions
job when one is wired up post-tag.

Not in this commit (deferred)
=============================

* GitHub Actions workflow that invokes `make keycloak-integration-test`
  on push. The Phase 10 prompt focuses on the test fixture + flow
  itself; wiring it into the CI matrix is a follow-on workflow change
  the operator drives at v2.1.0 tag time.
* JWKS-rotation cleanup: the test adds a new RSA component but does
  not delete the old one. Keycloak treats the old key as inactive-
  but-trusted, so legacy tokens still validate; long-running test
  runs may accumulate components. Acceptable for ephemeral test
  fixtures.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build run test lint verify verify-docs verify-deploy loadtest acme-cert-manager-test acme-rfc-conformance-test clean docker-up docker-down migrate-up migrate-down generate test-cover frontend-build qa-stats
+.PHONY: help build run test lint verify verify-docs verify-deploy loadtest acme-cert-manager-test acme-rfc-conformance-test keycloak-integration-test okta-smoke-test clean docker-up docker-down migrate-up migrate-down generate test-cover frontend-build qa-stats
 
 # Default target - show help
 help:
@@ -171,6 +171,32 @@ loadtest:
 	@echo "==> results landed in deploy/test/loadtest/results/"
 	@if [ -f deploy/test/loadtest/results/summary.txt ]; then cat deploy/test/loadtest/results/summary.txt; fi
 
+# Auth Bundle 2 Phase 10 — Keycloak end-to-end OIDC integration test.
+# Boots a Keycloak container via testcontainers-go (quay.io/keycloak:25.0),
+# imports a canned realm with two groups + two users, and drives the
+# full OIDC flow against the certctl service: discovery + JWKS,
+# auth-code login, group-claim parsing, group-role mapping, session
+# mint, and JWKS rotation.
+#
+# Build-tag-gated under `integration` so `make verify` (which runs
+# go test -short) NEVER pulls in the 60-90s Keycloak boot. Requires a
+# local Docker daemon. Skips cleanly with t.Skip() when -short is set.
+keycloak-integration-test:
+	@echo "==> running Keycloak OIDC integration test (requires Docker)"
+	@go test -tags=integration -count=1 -timeout=10m \
+	  ./internal/auth/oidc/...
+
+# Auth Bundle 2 Phase 10 — optional Okta smoke test. Gated behind TWO
+# build tags (integration + okta_smoke) so it only runs when invoked
+# manually against the operator's own Okta dev tenant. Requires the
+# OKTA_ISSUER + OKTA_CLIENT_ID + OKTA_CLIENT_SECRET env vars; the test
+# t.Skip's with a clear message when any are missing. Documented in
+# internal/auth/oidc/integration_okta_smoke_test.go.
+okta-smoke-test:
+	@echo "==> running Okta smoke test (requires OKTA_ISSUER / _CLIENT_ID / _CLIENT_SECRET env vars)"
+	@go test -tags='integration okta_smoke' -count=1 -timeout=2m \
+	  ./internal/auth/oidc/...
+
 # Phase 5 — kind-driven cert-manager integration test. Requires
 # `kind`, `kubectl`, `helm`, and a local Docker daemon. Sets
 # KIND_AVAILABLE=1 so the test runs (it skips cleanly when unset, which