feat(m7.1): wire compliance-agent to compliance-core auth + status gate

Supersedes #82.

Deletes the inline JWT middleware in compliance-agent (now stale —
missing JWKS refresh from #84 and tenant extraction from #83) and
imports require_jwt_auth, require_tenant_status, JwksState from
compliance_core::auth. Wires the status gate into the server's layer
stack: Extension(jwks_state) → require_jwt_auth → require_tenant_status
→ handler.

Adds the integration test from #82, retargeted to
compliance_core::auth::require_tenant_status.

Test plan
- cargo fmt --all clean
- cargo clippy --workspace --exclude compliance-dashboard -- -D warnings
  clean (matches baseline)
- cargo test -p compliance-core --lib — 7 tests pass
- cargo test -p compliance-agent --lib — 228 tests pass
- cargo test -p compliance-agent --test tenant_status_middleware —
  6 tests pass
- scripts/smoke.sh against live certifai KC — 15/15 cells pass
  (anon, bogus, active×2, trial, frozen, archived × {GET/health,
  GET/echo, POST/echo})

Caveats
- M7.1 only — status gate + claim extraction. Per-collection
  tenant_id scoping (M7.2) still pending; agent will still serve any
  Active/Trial tenant's data to any caller until the ~38 query
  call-sites use compliance_core::db::tenant_filter.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Cargo.lock

@@ -701,19 +701,23 @@ dependencies = [
 name = "compliance-core"
 version = "0.1.0"
 dependencies = [
+ "axum",
  "bson",
  "chrono",
  "hex",
+ "jsonwebtoken",
  "mongodb",
  "opentelemetry",
  "opentelemetry-appender-tracing",
  "opentelemetry-otlp",
  "opentelemetry_sdk",
+ "reqwest",
  "secrecy",
  "serde",
  "serde_json",
  "sha2",
  "thiserror 2.0.18",
+ "tokio",
  "tracing",
  "tracing-opentelemetry",
  "tracing-subscriber",
@@ -827,6 +831,20 @@ dependencies = [
  "tracing-subscriber",
 ]
 
+[[package]]
+name = "compliance-smoke"
+version = "0.1.0"
+dependencies = [
+ "axum",
+ "compliance-core",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+]
+
 [[package]]
 name = "console_error_panic_hook"
 version = "0.1.7"

Cargo.toml

@@ -6,6 +6,7 @@ members = [
     "compliance-graph",
     "compliance-dast",
     "compliance-mcp",
+    "compliance-smoke",
 ]
 resolver = "2"
 

compliance-agent/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2021"
 workspace = true
 
 [dependencies]
-compliance-core = { workspace = true, features = ["mongodb", "telemetry"] }
+compliance-core = { workspace = true, features = ["mongodb", "telemetry", "axum"] }
 compliance-graph = { path = "../compliance-graph" }
 compliance-dast = { path = "../compliance-dast" }
 serde = { workspace = true }
@@ -44,7 +44,8 @@ dashmap = { workspace = true }
 tokio-stream = { workspace = true }
 
 [dev-dependencies]
-compliance-core = { workspace = true, features = ["mongodb"] }
+compliance-core = { workspace = true, features = ["mongodb", "axum"] }
+tower = { version = "0.5", features = ["util"] }
 reqwest = { workspace = true }
 serde_json = { workspace = true }
 tokio = { workspace = true }
@@ -52,5 +53,4 @@ mongodb = { workspace = true }
 uuid = { workspace = true }
 secrecy = { workspace = true }
 axum = "0.8"
-tower = { version = "0.5", features = ["util"] }
 tower-http = { version = "0.6", features = ["cors"] }

compliance-agent/src/api/mod.rs

@@ -1,8 +1,5 @@
-pub mod auth_middleware;
 pub mod handlers;
 pub mod routes;
 pub mod server;
-pub mod tenant_ctx;
 
 pub use server::start_api_server;
-pub use tenant_ctx::TenantCtx;

compliance-agent/src/api/server.rs

@@ -7,8 +7,9 @@ use tower_http::cors::CorsLayer;
 use tower_http::set_header::SetResponseHeaderLayer;
 use tower_http::trace::TraceLayer;
 
+use compliance_core::auth::{require_jwt_auth, require_tenant_status, JwksState};
+
 use crate::agent::ComplianceAgent;
-use crate::api::auth_middleware::{require_jwt_auth, require_tenant_status, JwksState};
 use crate::api::routes;
 use crate::error::AgentError;
 
@@ -44,10 +45,9 @@ pub async fn start_api_server(agent: ComplianceAgent, port: u16) -> Result<(), A
             jwks_url,
         };
         tracing::info!("Keycloak JWT auth enabled for realm '{kc_realm}'");
-        // Layers execute outermost-first. The Extension must run before
-        // require_jwt_auth so that middleware can read JwksState from
-        // request extensions, and the status gate must run after the
-        // JWT auth so TenantContext is in extensions.
+        // Layers execute outermost-first. Extension(jwks_state) must run
+        // before require_jwt_auth so the middleware can read it; the
+        // status gate runs after JWT so TenantContext is in extensions.
         app = app
             .layer(middleware::from_fn(require_tenant_status))
             .layer(middleware::from_fn(require_jwt_auth))

compliance-agent/tests/tenant_status_middleware.rs

@@ -1,4 +1,4 @@
-//! M7.1 — integration tests for `require_tenant_status`.
+//! M7.1 — integration tests for `compliance_core::auth::require_tenant_status`.
 //!
 //! Exercises the middleware end-to-end through an Axum router so we
 //! catch wiring bugs (extension propagation, method matching) that pure
@@ -15,8 +15,7 @@ use axum::{
     routing::{get, post},
     Router,
 };
-use compliance_agent::api::auth_middleware::require_tenant_status;
-use compliance_core::{TenantContext, TenantStatus};
+use compliance_core::{auth::require_tenant_status, TenantContext, TenantStatus};
 use tower::ServiceExt;
 
 fn ctx_with(status: TenantStatus) -> TenantContext {

compliance-core/Cargo.toml

@@ -18,6 +18,15 @@ telemetry = [
     "dep:tracing-subscriber",
     "dep:tracing",
 ]
+# Pulls in the M7.1 Axum middleware + extractor. Consumers that don't
+# embed an HTTP server (e.g. the wasm dashboard frontend) leave it off.
+axum = [
+    "dep:axum",
+    "dep:jsonwebtoken",
+    "dep:reqwest",
+    "dep:tokio",
+    "dep:tracing",
+]
 
 [dependencies]
 serde = { workspace = true }
@@ -37,3 +46,7 @@ opentelemetry-appender-tracing = { version = "0.29", optional = true }
 tracing-opentelemetry = { version = "0.30", optional = true }
 tracing-subscriber = { workspace = true, optional = true }
 tracing = { workspace = true, optional = true }
+axum = { version = "0.8", optional = true }
+jsonwebtoken = { version = "9", optional = true }
+reqwest = { workspace = true, optional = true }
+tokio = { workspace = true, optional = true }

compliance-core/src/auth.rs

@@ -1,9 +1,9 @@
 //! M7.1 — JWT validation + tenant context propagation.
 //!
 //! `require_jwt_auth` validates a Bearer JWT against Keycloak's JWKS and
-//! attaches a `TenantContext` to the request extensions. Downstream
-//! middleware (`require_tenant_status`) and Axum extractors (`TenantCtx`)
-//! read it from there.
+//! attaches a [`TenantContext`] to the request extensions. Downstream
+//! middleware ([`require_tenant_status`]) and Axum extractors
+//! ([`crate::tenant_ctx::TenantCtx`]) read it from there.
 //!
 //! Skipped paths:
 //! * `/api/v1/health` — Kubernetes liveness; never authenticated.
@@ -23,12 +23,13 @@ use axum::{
     middleware::Next,
     response::{IntoResponse, Response},
 };
-use compliance_core::{OrgRole, TenantContext, TenantStatus};
 use jsonwebtoken::{decode, decode_header, jwk::JwkSet, DecodingKey, Validation};
 use reqwest::StatusCode;
 use serde::Deserialize;
 use tokio::sync::RwLock;
 
+use crate::{OrgRole, TenantContext, TenantStatus};
+
 /// Cached JWKS from Keycloak for token validation.
 #[derive(Clone)]
 pub struct JwksState {
@@ -147,27 +148,83 @@ async fn validate_token(token: &str, state: &JwksState) -> Result<TenantContext,
 
     let kid = header
         .kid
+        .clone()
         .ok_or_else(|| "JWT missing kid header".to_string())?;
 
-    let jwks = fetch_or_get_jwks(state).await?;
+    // First try against whatever's currently cached. If the kid isn't
+    // there or the signature doesn't verify, the cached JWKS is most
+    // likely stale (KC rotated keys) — refresh once and retry before
+    // giving up. Without this every key rotation produces a silent 401
+    // storm that only goes away when the agent restarts.
+    let jwks = fetch_or_get_jwks(state, false).await?;
+    match try_validate(token, &header, &kid, &jwks) {
+        Ok(ctx) => Ok(ctx),
+        Err(ValidationError::Permanent(e)) => Err(e),
+        Err(ValidationError::Stale(reason)) => {
+            tracing::info!(
+                kid = %kid,
+                reason = %reason,
+                "JWKS appears stale — forcing refresh and retrying"
+            );
+            let jwks = fetch_or_get_jwks(state, true).await?;
+            try_validate(token, &header, &kid, &jwks).map_err(|e| match e {
+                ValidationError::Stale(s) | ValidationError::Permanent(s) => s,
+            })
+        }
+    }
+}
 
-    let jwk = jwks
+#[derive(Debug)]
+enum ValidationError {
+    /// Refresh-eligible: cached JWKS may be stale.
+    Stale(String),
+    /// Refusing the token regardless of JWKS freshness.
+    Permanent(String),
+}
+
+fn try_validate(
+    token: &str,
+    header: &jsonwebtoken::Header,
+    kid: &str,
+    jwks: &JwkSet,
+) -> Result<TenantContext, ValidationError> {
+    let jwk = match jwks
         .keys
         .iter()
-        .find(|k| k.common.key_id.as_deref() == Some(&kid))
-        .ok_or_else(|| "no matching key found in JWKS".to_string())?;
+        .find(|k| k.common.key_id.as_deref() == Some(kid))
+    {
+        Some(j) => j,
+        None => {
+            return Err(ValidationError::Stale(
+                "no matching key found in JWKS".to_string(),
+            ))
+        }
+    };
 
-    let decoding_key =
-        DecodingKey::from_jwk(jwk).map_err(|e| format!("failed to create decoding key: {e}"))?;
+    let decoding_key = DecodingKey::from_jwk(jwk)
+        .map_err(|e| ValidationError::Permanent(format!("failed to create decoding key: {e}")))?;
 
     let mut validation = Validation::new(header.alg);
     validation.validate_exp = true;
     validation.validate_aud = false;
 
-    let data = decode::<Claims>(token, &decoding_key, &validation)
-        .map_err(|e| format!("token validation failed: {e}"))?;
+    let data = match decode::<Claims>(token, &decoding_key, &validation) {
+        Ok(d) => d,
+        Err(e) => {
+            // Signature mismatch is the other refresh-eligible failure:
+            // the matching kid is present but the key bytes don't match.
+            // Everything else (expired, malformed, etc.) is permanent.
+            return Err(
+                if matches!(e.kind(), jsonwebtoken::errors::ErrorKind::InvalidSignature) {
+                    ValidationError::Stale(format!("token validation failed: {e}"))
+                } else {
+                    ValidationError::Permanent(format!("token validation failed: {e}"))
+                },
+            );
+        }
+    };
 
-    claims_to_context(data.claims)
+    claims_to_context(data.claims).map_err(ValidationError::Permanent)
 }
 
 /// Map the decoded JWT payload into the platform-wide `TenantContext`.
@@ -197,14 +254,25 @@ fn claims_to_context(c: Claims) -> Result<TenantContext, String> {
     })
 }
 
-async fn fetch_or_get_jwks(state: &JwksState) -> Result<JwkSet, String> {
-    {
+async fn fetch_or_get_jwks(state: &JwksState, force: bool) -> Result<JwkSet, String> {
+    if !force {
         let cached = state.jwks.read().await;
         if let Some(ref jwks) = *cached {
             return Ok(jwks.clone());
         }
     }
 
+    // Hold the write lock across the fetch so concurrent refreshers
+    // don't all hammer Keycloak when keys rotate. If another writer
+    // already populated a fresh JWKS while we were waiting (and we
+    // weren't asked to force), use theirs.
+    let mut cached = state.jwks.write().await;
+    if !force {
+        if let Some(ref jwks) = *cached {
+            return Ok(jwks.clone());
+        }
+    }
+
     let resp = reqwest::get(&state.jwks_url)
         .await
         .map_err(|e| format!("failed to fetch JWKS: {e}"))?;
@@ -214,7 +282,6 @@ async fn fetch_or_get_jwks(state: &JwksState) -> Result<JwkSet, String> {
         .await
         .map_err(|e| format!("failed to parse JWKS: {e}"))?;
 
-    let mut cached = state.jwks.write().await;
     *cached = Some(jwks.clone());
 
     Ok(jwks)
@@ -292,6 +359,24 @@ mod tests {
         );
     }
 
+    #[test]
+    fn try_validate_returns_stale_when_kid_missing_from_jwks() {
+        // Empty JWKS — the kid we ask for can't possibly match. The error
+        // must classify as Stale so the caller refreshes JWKS and retries.
+        let jwks = JwkSet { keys: vec![] };
+        let header = jsonwebtoken::Header {
+            alg: jsonwebtoken::Algorithm::RS256,
+            kid: Some("kid-rotated-out".to_string()),
+            ..Default::default()
+        };
+        let err = try_validate("ignored.token.value", &header, "kid-rotated-out", &jwks)
+            .expect_err("should fail");
+        match err {
+            ValidationError::Stale(s) => assert!(s.contains("no matching key")),
+            ValidationError::Permanent(s) => panic!("must be Stale, got Permanent: {s}"),
+        }
+    }
+
     #[test]
     fn is_write_detects_methods() {
         assert!(!is_write(&Method::GET));

compliance-core/src/lib.rs

@@ -7,6 +7,11 @@ pub mod telemetry;
 pub mod tenant;
 pub mod traits;
 
+#[cfg(feature = "axum")]
+pub mod auth;
+#[cfg(feature = "axum")]
+pub mod tenant_ctx;
+
 pub use config::{AgentConfig, DashboardConfig};
 pub use error::CoreError;
 pub use tenant::{OrgRole, TenantContext, TenantStatus};

compliance-core/src/tenant.rs

@@ -1,9 +1,9 @@
 //! Tenant context propagated through every authenticated request.
 //!
-//! This module is the M7.1 single source of truth for "who is this request
-//! for". Claims come from a Keycloak-issued JWT and land here via
-//! `compliance-agent`'s `require_jwt_auth` middleware. Handlers reach into
-//! the request extensions with the `TenantCtx` Axum extractor.
+//! M7.1 single source of truth for "who is this request for". Claims come
+//! from a Keycloak-issued JWT and land here via [`crate::auth::require_jwt_auth`]
+//! (enabled with the `axum` feature). Handlers reach into the request
+//! extensions with the [`crate::tenant_ctx::TenantCtx`] extractor.
 //!
 //! The shape mirrors the JWT claim names the breakpilot-platform realm
 //! emits (see `platform/orca-platform/dev/keycloak/realm-export.json`).
@@ -87,8 +87,8 @@ impl OrgRole {
     }
 }
 
-/// Everything `compliance-agent` knows about the requesting tenant at the
-/// moment a request lands. Cheap to clone (every field is owned + small).
+/// Everything we know about the requesting tenant at the moment a request
+/// lands. Cheap to clone (every field is owned + small).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TenantContext {
     /// `tenants.id` from the platform's tenant-registry (UUID).

compliance-core/src/tenant_ctx.rs

@@ -9,17 +9,18 @@
 //! }
 //! ```
 //!
-//! The middleware (`require_jwt_auth`) is responsible for inserting the
-//! context into the request extensions. If it's missing on a route that
-//! uses this extractor, that's a bug in the wiring — we return 401 so the
-//! caller sees an auth failure rather than a 500.
+//! The middleware ([`crate::auth::require_jwt_auth`]) is responsible for
+//! inserting the context into the request extensions. If it's missing on
+//! a route that uses this extractor, that's a bug in the wiring — we
+//! return 401 so the caller sees an auth failure rather than a 500.
 
 use axum::{
     extract::FromRequestParts,
     http::{request::Parts, StatusCode},
     response::{IntoResponse, Response},
 };
-use compliance_core::TenantContext;
+
+use crate::TenantContext;
 
 #[derive(Debug, Clone)]
 pub struct TenantCtx(pub TenantContext);
@@ -57,8 +58,8 @@ where
 #[allow(clippy::expect_used, clippy::unwrap_used)]
 mod tests {
     use super::*;
+    use crate::TenantStatus;
     use axum::http::Request;
-    use compliance_core::TenantStatus;
 
     fn ctx() -> TenantContext {
         TenantContext {

compliance-smoke/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "compliance-smoke"
+version = "0.1.0"
+edition = "2021"
+description = "Tiny Axum service exercising compliance-core M7.1 tenant gating. Run smoke.sh against it before merging anything that touches the auth/tenant path."
+
+[lints]
+workspace = true
+
+[[bin]]
+name = "compliance-smoke"
+path = "src/main.rs"
+
+[dependencies]
+compliance-core = { workspace = true, features = ["axum"] }
+axum = "0.8"
+tokio = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+reqwest = { workspace = true }

compliance-smoke/src/main.rs

@@ -0,0 +1,111 @@
+//! M7.1 smoke service.
+//!
+//! A standalone Axum binary whose only job is to host the
+//! [`compliance_core::auth`] middleware + [`compliance_core::tenant_ctx`]
+//! extractor on three endpoints, so `scripts/smoke.sh` can prove the
+//! tenant-gating contract end-to-end before any auth-path PR merges.
+//!
+//! Endpoints:
+//! * `GET  /api/v1/health` — public, never authenticated.
+//! * `GET  /api/v1/echo`   — protected read; returns the [`TenantContext`].
+//! * `POST /api/v1/echo`   — protected write; exercises the `Frozen → 402`
+//!   gate on the same handler.
+//!
+//! Configuration (env):
+//! * `KEYCLOAK_URL`   — e.g. `http://localhost:8080`. Required.
+//! * `KEYCLOAK_REALM` — e.g. `certifai`. Required.
+//! * `SMOKE_PORT`     — defaults to `3010`.
+
+use std::sync::Arc;
+
+use axum::{middleware, routing::get, Extension, Json, Router};
+use compliance_core::{
+    auth::{require_jwt_auth, require_tenant_status, JwksState},
+    tenant_ctx::TenantCtx,
+};
+use serde::Serialize;
+use tokio::sync::RwLock;
+
+#[derive(Serialize)]
+struct EchoResponse {
+    method: &'static str,
+    tenant_id: String,
+    tenant_slug: String,
+    plan: String,
+    status: String,
+    products: Vec<String>,
+    org_roles: Vec<String>,
+    user_id: String,
+    user_name: Option<String>,
+}
+
+async fn health() -> Json<serde_json::Value> {
+    Json(serde_json::json!({ "ok": true }))
+}
+
+async fn echo_read(TenantCtx(ctx): TenantCtx) -> Json<EchoResponse> {
+    Json(echo(ctx, "GET"))
+}
+
+async fn echo_write(TenantCtx(ctx): TenantCtx) -> Json<EchoResponse> {
+    Json(echo(ctx, "POST"))
+}
+
+fn echo(ctx: compliance_core::TenantContext, method: &'static str) -> EchoResponse {
+    EchoResponse {
+        method,
+        tenant_id: ctx.tenant_id,
+        tenant_slug: ctx.tenant_slug,
+        plan: ctx.plan,
+        status: ctx.status.to_string(),
+        products: ctx.products,
+        org_roles: ctx.org_roles.iter().map(|r| format!("{r:?}")).collect(),
+        user_id: ctx.user_id,
+        user_name: ctx.user_name,
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+        )
+        .init();
+
+    let kc_url = std::env::var("KEYCLOAK_URL")
+        .map_err(|_| "KEYCLOAK_URL is required (e.g. http://localhost:8080)")?;
+    let kc_realm = std::env::var("KEYCLOAK_REALM")
+        .map_err(|_| "KEYCLOAK_REALM is required (e.g. certifai)")?;
+    let port: u16 = std::env::var("SMOKE_PORT")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(3010);
+
+    let jwks_url = format!("{kc_url}/realms/{kc_realm}/protocol/openid-connect/certs");
+    let jwks_state = JwksState {
+        jwks: Arc::new(RwLock::new(None)),
+        jwks_url: jwks_url.clone(),
+    };
+
+    // Layers execute outermost-first. The Extension must be registered
+    // before `require_jwt_auth` so the middleware can read JwksState; the
+    // status gate must run after JWT so `TenantContext` is in extensions.
+    let app = Router::new()
+        .route("/api/v1/health", get(health))
+        .route("/api/v1/echo", get(echo_read).post(echo_write))
+        .layer(middleware::from_fn(require_tenant_status))
+        .layer(middleware::from_fn(require_jwt_auth))
+        .layer(Extension(jwks_state));
+
+    let addr = format!("0.0.0.0:{port}");
+    let listener = tokio::net::TcpListener::bind(&addr).await?;
+    tracing::info!(
+        port,
+        jwks = %jwks_url,
+        "compliance-smoke listening — try `scripts/smoke.sh`"
+    );
+    axum::serve(listener, app).await?;
+    Ok(())
+}

scripts/smoke.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# M7.1 tenant-gating smoke test.
+#
+# Drives compliance-smoke against a live Keycloak realm with five test
+# users (one per tenant_status), asserts the response code on each
+# endpoint, and exits non-zero on any mismatch.
+#
+# Pre-reqs (one-time):
+#   * KC up at $KC_URL with realm $KC_REALM
+#   * Client $KC_CLIENT has direct-access-grants enabled
+#   * Users + tenant_status mappers per certifai/keycloak/realm-export.json
+#   * compliance-smoke binary running and reachable at $SMOKE_URL
+#
+# Usage:
+#   scripts/smoke.sh              # uses defaults below
+#   SMOKE_URL=... scripts/smoke.sh
+
+set -euo pipefail
+
+KC_URL="${KC_URL:-http://localhost:8080}"
+KC_REALM="${KC_REALM:-certifai}"
+KC_CLIENT="${KC_CLIENT:-certifai-dashboard}"
+SMOKE_URL="${SMOKE_URL:-http://localhost:3010}"
+
+readonly TOKEN_ENDPOINT="${KC_URL}/realms/${KC_REALM}/protocol/openid-connect/token"
+
+PASS=0
+FAIL=0
+
+red()    { printf '\033[31m%s\033[0m' "$*"; }
+green()  { printf '\033[32m%s\033[0m' "$*"; }
+yellow() { printf '\033[33m%s\033[0m' "$*"; }
+
+# Fetches an access token via direct access grant. Echoes the raw token.
+get_token() {
+    local user="$1" pass="$2"
+    curl -sS -X POST "$TOKEN_ENDPOINT" \
+        -H 'Content-Type: application/x-www-form-urlencoded' \
+        -d "grant_type=password" \
+        -d "client_id=${KC_CLIENT}" \
+        -d "username=${user}" \
+        -d "password=${pass}" \
+        -d "scope=openid" \
+        | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p'
+}
+
+# Hits SMOKE_URL$path with the given method and (optional) bearer token,
+# asserts the response status code matches $want.
+assert_status() {
+    local label="$1" method="$2" path="$3" want="$4" token="${5:-}"
+    local args=(-sS -o /dev/null -w '%{http_code}' -X "$method" "${SMOKE_URL}${path}")
+    if [[ -n "$token" ]]; then
+        args+=(-H "Authorization: Bearer ${token}")
+    fi
+    local got
+    got=$(curl "${args[@]}")
+    if [[ "$got" == "$want" ]]; then
+        printf '  %s %s %-4s %-15s → %s\n' "$(green PASS)" "$label" "$method" "$path" "$got"
+        PASS=$((PASS + 1))
+    else
+        printf '  %s %s %-4s %-15s → got %s, want %s\n' "$(red FAIL)" "$label" "$method" "$path" "$got" "$want"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+header() {
+    printf '\n%s %s\n' "$(yellow '##')" "$1"
+}
+
+# ---- Pre-flight ----------------------------------------------------------
+header "Pre-flight"
+if ! curl -sS -o /dev/null -w '%{http_code}\n' "${SMOKE_URL}/api/v1/health" | grep -q '^200$'; then
+    printf '  %s smoke service not reachable at %s\n' "$(red ERR)" "$SMOKE_URL"
+    exit 2
+fi
+if ! curl -sS -o /dev/null -w '%{http_code}\n' "${KC_URL}/realms/${KC_REALM}/.well-known/openid-configuration" | grep -q '^200$'; then
+    printf '  %s Keycloak realm %s not reachable at %s\n' "$(red ERR)" "$KC_REALM" "$KC_URL"
+    exit 2
+fi
+printf '  %s smoke service + Keycloak both up\n' "$(green OK)"
+
+# ---- Public endpoint --------------------------------------------------
+header "Public endpoint (no auth required)"
+assert_status anon GET  /api/v1/health 200
+
+# ---- Anonymous access to protected endpoints ----------------------------
+header "Anonymous → 401 on protected endpoints"
+assert_status anon GET  /api/v1/echo   401
+assert_status anon POST /api/v1/echo   401
+
+# ---- Bad token ----------------------------------------------------------
+header "Bad token → 401"
+assert_status bogus GET  /api/v1/echo  401 "not-a-real-jwt"
+assert_status bogus POST /api/v1/echo  401 "not-a-real-jwt"
+
+# ---- Active tenant (admin user) -----------------------------------------
+header "admin@certifai.local (active) → full access"
+TOKEN=$(get_token admin@certifai.local admin)
+if [[ -z "$TOKEN" ]]; then
+    printf '  %s failed to fetch token for admin\n' "$(red ERR)"
+    exit 2
+fi
+assert_status active GET  /api/v1/echo 200 "$TOKEN"
+assert_status active POST /api/v1/echo 200 "$TOKEN"
+
+# ---- Active tenant (USER role) ------------------------------------------
+header "user@certifai.local (active) → full access"
+TOKEN=$(get_token user@certifai.local user)
+assert_status active GET  /api/v1/echo 200 "$TOKEN"
+assert_status active POST /api/v1/echo 200 "$TOKEN"
+
+# ---- Trial tenant -------------------------------------------------------
+header "trial@acme.local (trial) → full access"
+TOKEN=$(get_token trial@acme.local trial)
+assert_status trial  GET  /api/v1/echo 200 "$TOKEN"
+assert_status trial  POST /api/v1/echo 200 "$TOKEN"
+
+# ---- Frozen tenant ------------------------------------------------------
+header "frozen@acme.local (frozen) → read-only, writes 402"
+TOKEN=$(get_token frozen@acme.local frozen)
+assert_status frozen GET  /api/v1/echo 200 "$TOKEN"
+assert_status frozen POST /api/v1/echo 402 "$TOKEN"
+
+# ---- Archived tenant ----------------------------------------------------
+header "archived@acme.local (archived) → 410 everywhere"
+TOKEN=$(get_token archived@acme.local archived)
+assert_status archived GET  /api/v1/echo 410 "$TOKEN"
+assert_status archived POST /api/v1/echo 410 "$TOKEN"
+
+# ---- Summary ------------------------------------------------------------
+printf '\n'
+if [[ "$FAIL" -gt 0 ]]; then
+    printf '%s %d passed, %d failed\n' "$(red FAIL)" "$PASS" "$FAIL"
+    exit 1
+fi
+printf '%s %d/%d assertions passed\n' "$(green PASS)" "$PASS" "$PASS"