fixup(m7.2-A): validate db_prefix at connect, bump hash to 16 bytes

Addresses review feedback on the hash-fallback path.

The original `debug_assert!(hashed.len() <= MAX_DB_NAME_LEN)` was a
runtime hack that vanished in release builds. With an 8-byte hash
truncation (~2^32 birthday-collision resistance), two tenant_ids
hashing to the same suffix would silently share a database — no
panic, no rollback, just cross-tenant data leak. Not acceptable for
a regulated-industry product.

Changes:
- Bump hash truncation 8 → 16 bytes (32 hex chars). 2^64 birthday
  resistance — collision-impossible at our scale.
- Add MAX_PREFIX_LEN (= 30) and validate db_prefix.len() at
  `DatabasePool::connect`. The runtime hash-fallback arithmetic is
  now provably within Mongo's 63-byte cap; drop the debug_assert!.
- New test `connect_rejects_overlong_db_prefix` exercises the
  inclusive bound (30 passes, 31 fails).
- Existing hash-fallback test now asserts a 32-char hex suffix +
  basic distinctness for two different inputs.

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/agent.rs

@@ -6,7 +6,7 @@ use tokio::sync::{broadcast, watch, Semaphore};
 use compliance_core::models::pentest::PentestEvent;
 use compliance_core::AgentConfig;
 
-use crate::database::Database;
+use crate::database::{Database, DatabasePool};
 use crate::llm::LlmClient;
 use crate::pipeline::orchestrator::PipelineOrchestrator;
 
@@ -16,7 +16,13 @@ const DEFAULT_MAX_CONCURRENT_SESSIONS: usize = 5;
 #[derive(Clone)]
 pub struct ComplianceAgent {
     pub config: AgentConfig,
+    /// Transitional single-database handle. Used by handlers that have
+    /// not yet been migrated to `db_pool.for_tenant(&ctx)` (M7.2-B/C).
+    /// Will be removed once every call site is tenant-scoped (M7.2-D).
     pub db: Database,
+    /// Per-tenant Mongo broker introduced in M7.2-A. Handlers should
+    /// prefer this and obtain a tenant-scoped [`Database`] from it.
+    pub db_pool: DatabasePool,
     pub llm: Arc<LlmClient>,
     pub http: reqwest::Client,
     /// Per-session broadcast senders for SSE streaming.
@@ -28,7 +34,7 @@ pub struct ComplianceAgent {
 }
 
 impl ComplianceAgent {
-    pub fn new(config: AgentConfig, db: Database) -> Self {
+    pub fn new(config: AgentConfig, db: Database, db_pool: DatabasePool) -> Self {
         let llm = Arc::new(LlmClient::new(
             config.litellm_url.clone(),
             config.litellm_api_key.clone(),
@@ -43,6 +49,7 @@ impl ComplianceAgent {
         Self {
             config,
             db,
+            db_pool,
             llm,
             http,
             session_streams: Arc::new(DashMap::new()),

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
+        // Layers execute outermost-first. Extension(jwks_state) must run
-        // require_jwt_auth so that middleware can read JwksState from
+        // before require_jwt_auth so the middleware can read it; the
-        // request extensions, and the status gate must run after the
+        // status gate runs after JWT so TenantContext is in extensions.
-        // JWT auth so TenantContext is in extensions.
         app = app
             .layer(middleware::from_fn(require_tenant_status))
             .layer(middleware::from_fn(require_jwt_auth))

compliance-agent/src/database.rs

@@ -1,11 +1,151 @@
+use std::sync::Arc;
+
+use dashmap::DashMap;
 use mongodb::bson::doc;
 use mongodb::options::IndexOptions;
 use mongodb::{Client, Collection, IndexModel};
+use sha2::{Digest, Sha256};
 
 use compliance_core::models::*;
+use compliance_core::TenantContext;
 
 use crate::error::AgentError;
 
+/// Mongo enforces a 63-byte cap on database names (older clusters: 64
+/// on Linux, 63 on Windows; we target the conservative limit).
+const MAX_DB_NAME_LEN: usize = 63;
+
+/// Hex length of the SHA-256 truncation used for the hash fallback
+/// tenant DB name (16 bytes → 32 hex chars). 16 bytes gives ~2^64
+/// birthday-collision resistance — at our 10s-100s tenant scale this
+/// is effectively impossible to hit.
+const HASH_HEX_LEN: usize = 32;
+
+/// Largest `db_prefix` that still guarantees the hash-fallback name
+/// fits in the 63-byte cap: `prefix + "_" + 32 hex chars`.
+const MAX_PREFIX_LEN: usize = MAX_DB_NAME_LEN - 1 - HASH_HEX_LEN;
+
+/// Per-tenant Mongo connection broker (M7.2 isolation model).
+///
+/// Holds one [`Client`] and hands out [`Database`] handles physically
+/// scoped to `<db_prefix>_<tenant_id>`. The driver is the isolation
+/// boundary — a handle for tenant A cannot see tenant B's documents
+/// because it is connected to a different database, not because of an
+/// application-level filter.
+///
+/// Index creation runs idempotently the first time each tenant is seen
+/// in the process's lifetime. Mongo's `createIndex` is itself idempotent
+/// by index name; the in-memory `ensured` set just skips the round-trip.
+#[derive(Clone, Debug)]
+pub struct DatabasePool {
+    client: Client,
+    db_prefix: String,
+    ensured: Arc<DashMap<String, ()>>,
+}
+
+impl DatabasePool {
+    /// Connect to the cluster and prepare to hand out tenant databases
+    /// named `<db_prefix>_<tenant_id>`.
+    ///
+    /// Validates `db_prefix.len() <= MAX_PREFIX_LEN` so the
+    /// hash-fallback path is provably within Mongo's 63-byte db-name
+    /// cap. Refuses to construct a pool that could ever produce an
+    /// over-long name.
+    pub async fn connect(uri: &str, db_prefix: &str) -> Result<Self, AgentError> {
+        if db_prefix.len() > MAX_PREFIX_LEN {
+            return Err(AgentError::Other(format!(
+                "db_prefix '{db_prefix}' is {} chars; max is {MAX_PREFIX_LEN} so the \
+                 hash-fallback tenant DB name fits Mongo's {MAX_DB_NAME_LEN}-byte cap",
+                db_prefix.len()
+            )));
+        }
+        let client = Client::with_uri_str(uri).await?;
+        client
+            .database("admin")
+            .run_command(doc! { "ping": 1 })
+            .await?;
+        tracing::info!(
+            "MongoDB cluster reachable; per-tenant pool ready (db prefix '{db_prefix}')"
+        );
+        Ok(Self {
+            client,
+            db_prefix: db_prefix.to_string(),
+            ensured: Arc::new(DashMap::new()),
+        })
+    }
+
+    /// Return a [`Database`] scoped to this tenant. Ensures indexes on
+    /// first call per tenant (per process). Cheap on the hot path —
+    /// subsequent calls skip the round-trip.
+    pub async fn for_tenant(&self, ctx: &TenantContext) -> Result<Database, AgentError> {
+        let db_name = self.tenant_db_name(&ctx.tenant_id);
+        let db = Database::from_database(self.client.database(&db_name));
+        // `DashMap::insert` returns the previous value; `None` means we
+        // were the first writer for this tenant_id and own the
+        // index-ensure work.
+        if self.ensured.insert(ctx.tenant_id.clone(), ()).is_none() {
+            if let Err(e) = db.ensure_indexes().await {
+                // Roll the marker back so the next request retries.
+                self.ensured.remove(&ctx.tenant_id);
+                return Err(e);
+            }
+            tracing::debug!(
+                tenant_id = %ctx.tenant_id,
+                db_name = %db_name,
+                "Indexes ensured for tenant database"
+            );
+        }
+        Ok(db)
+    }
+
+    /// Compute the Mongo database name for a tenant. Public for tests
+    /// and tenant offboarding (`pool.client().database(name).drop()`).
+    ///
+    /// Format: `<prefix>_<sanitized_tenant_id>` if it fits the 63-byte
+    /// cap, else `<prefix>_<sha256-16-byte-hex-of-tenant_id>`. The
+    /// `db_prefix` length invariant established at [`Self::connect`]
+    /// guarantees the hash-fallback name always fits — no runtime
+    /// assertion needed.
+    ///
+    /// Collision resistance: the hash fallback is a 16-byte SHA-256
+    /// truncation, which gives ~2^64 birthday-collision resistance. At
+    /// our 10s–100s tenant scale the probability of two tenant_ids
+    /// colliding is effectively zero. (8-byte truncation would have
+    /// been ~2^32 — too close for comfort on a regulated product.)
+    pub fn tenant_db_name(&self, tenant_id: &str) -> String {
+        let sanitized = sanitize_tenant_id(tenant_id);
+        let natural = format!("{}_{}", self.db_prefix, sanitized);
+        if natural.len() <= MAX_DB_NAME_LEN {
+            natural
+        } else {
+            let mut hasher = Sha256::new();
+            hasher.update(tenant_id.as_bytes());
+            let digest = hasher.finalize();
+            let suffix = hex::encode(&digest[..HASH_HEX_LEN / 2]);
+            format!("{}_{}", self.db_prefix, suffix)
+        }
+    }
+
+    /// Raw client handle. Reserved for cross-tenant admin flows that
+    /// must opt in explicitly (tenant listing, drop-on-offboard).
+    pub fn client(&self) -> &Client {
+        &self.client
+    }
+}
+
+/// Mongo database names disallow `/`, `\`, `.`, `"`, `$`, ` `, and NUL.
+/// breakpilot-dev tenant_ids are UUIDs so this is belt-and-braces, but
+/// it lets the pool tolerate any future tenant_id shape without surprise.
+fn sanitize_tenant_id(tenant_id: &str) -> String {
+    tenant_id
+        .chars()
+        .map(|c| match c {
+            '/' | '\\' | '.' | '"' | '$' | ' ' | '\0' => '_',
+            c => c,
+        })
+        .collect()
+}
+
 #[derive(Clone, Debug)]
 pub struct Database {
     inner: mongodb::Database,
@@ -20,6 +160,12 @@ impl Database {
         Ok(Self { inner: db })
     }
 
+    /// Wrap an already-resolved Mongo database. Used by [`DatabasePool`]
+    /// to hand out tenant-scoped handles without a fresh client per tenant.
+    pub(crate) fn from_database(inner: mongodb::Database) -> Self {
+        Self { inner }
+    }
+
     pub async fn ensure_indexes(&self) -> Result<(), AgentError> {
         // repositories: unique git_url
         self.repositories()

compliance-agent/src/main.rs

@@ -28,7 +28,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let db = database::Database::connect(&config.mongodb_uri, &config.mongodb_database).await?;
     db.ensure_indexes().await?;
 
-    let agent = agent::ComplianceAgent::new(config.clone(), db.clone());
+    // M7.2-A: per-tenant pool. Uses `mongodb_database` as the db-name
+    // prefix so tenant databases land as `<prefix>_<tenant_id>` next to
+    // the legacy single-tenant database.
+    let db_pool =
+        database::DatabasePool::connect(&config.mongodb_uri, &config.mongodb_database).await?;
+
+    let agent = agent::ComplianceAgent::new(config.clone(), db.clone(), db_pool);
 
     tracing::info!("Starting scheduler...");
     let scheduler_agent = agent.clone();

compliance-agent/tests/common/mod.rs

@@ -7,7 +7,7 @@ use std::sync::Arc;
 
 use compliance_agent::agent::ComplianceAgent;
 use compliance_agent::api;
-use compliance_agent::database::Database;
+use compliance_agent::database::{Database, DatabasePool};
 use compliance_core::AgentConfig;
 use secrecy::SecretString;
 
@@ -33,6 +33,10 @@ impl TestServer {
             .expect("Failed to connect to MongoDB — is it running?");
         db.ensure_indexes().await.expect("Failed to create indexes");
 
+        let db_pool = DatabasePool::connect(&mongodb_uri, &db_name)
+            .await
+            .expect("Failed to build DatabasePool");
+
         let config = AgentConfig {
             mongodb_uri: mongodb_uri.clone(),
             mongodb_database: db_name.clone(),
@@ -69,7 +73,7 @@ impl TestServer {
             pentest_imap_password: None,
         };
 
-        let agent = ComplianceAgent::new(config, db);
+        let agent = ComplianceAgent::new(config, db, db_pool);
 
         // Build the router with the agent extension
         let app = api::routes::build_router()

compliance-agent/tests/tenant_isolation.rs

@@ -0,0 +1,234 @@
+//! M7.2-A — `DatabasePool` isolation proof.
+//!
+//! Two `TenantContext`s, two databases, one client. Insert on A, query
+//! on B → empty. Insert on B, query on A → only A's docs. Proves that
+//! the per-tenant database split actually isolates at the driver level
+//! and not at "we hope we filter."
+//!
+//! Requires MongoDB. Set `TEST_MONGODB_URI` to override the default
+//! `mongodb://root:example@localhost:27017/?authSource=admin`.
+
+#![allow(clippy::expect_used, clippy::unwrap_used)]
+
+use compliance_agent::database::DatabasePool;
+use compliance_core::models::TrackedRepository;
+use compliance_core::{OrgRole, TenantContext, TenantStatus};
+use mongodb::bson::doc;
+
+fn ctx(tenant_id: &str, slug: &str) -> TenantContext {
+    TenantContext {
+        tenant_id: tenant_id.to_string(),
+        tenant_slug: slug.to_string(),
+        org_roles: vec![OrgRole::ItAdmin],
+        products: vec!["compliance-scanner".to_string()],
+        plan: "starter".to_string(),
+        status: TenantStatus::Active,
+        user_id: "u-1".to_string(),
+        user_name: None,
+    }
+}
+
+fn fixture_repo(name: &str, git_url: &str) -> TrackedRepository {
+    TrackedRepository {
+        id: None,
+        name: name.to_string(),
+        git_url: git_url.to_string(),
+        default_branch: "main".to_string(),
+        local_path: None,
+        scan_schedule: None,
+        webhook_enabled: false,
+        webhook_secret: None,
+        tracker_type: None,
+        tracker_owner: None,
+        tracker_repo: None,
+        tracker_token: None,
+        auth_token: None,
+        auth_username: None,
+        last_scanned_commit: None,
+        findings_count: 0,
+        created_at: chrono::Utc::now(),
+        updated_at: chrono::Utc::now(),
+    }
+}
+
+#[tokio::test]
+async fn pool_isolates_tenants_at_driver_level() {
+    let uri = std::env::var("TEST_MONGODB_URI")
+        .unwrap_or_else(|_| "mongodb://root:example@localhost:27017/?authSource=admin".into());
+    // Unique per run so parallel test invocations don't collide. Kept
+    // short because Mongo caps db names at 63 bytes (prefix + tenant_id).
+    let prefix = format!("m72a_{}", short_id());
+
+    let pool = DatabasePool::connect(&uri, &prefix)
+        .await
+        .expect("Failed to connect to MongoDB — is it running?");
+
+    let acme = ctx("00000000-0000-0000-0000-00000000acme", "acme");
+    let globex = ctx("00000000-0000-0000-0000-0000globex000", "globex");
+
+    let acme_db = pool.for_tenant(&acme).await.expect("acme db");
+    let globex_db = pool.for_tenant(&globex).await.expect("globex db");
+
+    // Write distinct repos into each tenant's database.
+    acme_db
+        .repositories()
+        .insert_one(fixture_repo("acme-app", "git@example.com:acme/app.git"))
+        .await
+        .expect("insert acme");
+    globex_db
+        .repositories()
+        .insert_one(fixture_repo(
+            "globex-platform",
+            "git@example.com:globex/platform.git",
+        ))
+        .await
+        .expect("insert globex");
+
+    // The point of the whole exercise: acme can ONLY see acme's repo
+    // and globex can ONLY see globex's, with no filter doc anywhere
+    // because the isolation is at the database handle, not in the query.
+    let acme_seen = collect(&acme_db).await;
+    let globex_seen = collect(&globex_db).await;
+
+    assert_eq!(acme_seen.len(), 1, "acme should see exactly its own repo");
+    assert_eq!(acme_seen[0].name, "acme-app");
+    assert_eq!(
+        globex_seen.len(),
+        1,
+        "globex should see exactly its own repo"
+    );
+    assert_eq!(globex_seen[0].name, "globex-platform");
+
+    // Sanity: the two databases really are different by name.
+    let acme_db_name = pool.tenant_db_name(&acme.tenant_id);
+    let globex_db_name = pool.tenant_db_name(&globex.tenant_id);
+    assert_ne!(acme_db_name, globex_db_name);
+    assert!(acme_db_name.starts_with(&prefix));
+
+    // Cleanup — drop both per-tenant databases.
+    pool.client()
+        .database(&acme_db_name)
+        .drop()
+        .await
+        .expect("drop acme");
+    pool.client()
+        .database(&globex_db_name)
+        .drop()
+        .await
+        .expect("drop globex");
+}
+
+#[tokio::test]
+async fn for_tenant_is_idempotent_index_creation() {
+    let uri = std::env::var("TEST_MONGODB_URI")
+        .unwrap_or_else(|_| "mongodb://root:example@localhost:27017/?authSource=admin".into());
+    let prefix = format!("m72a_{}", short_id());
+    let pool = DatabasePool::connect(&uri, &prefix).await.expect("connect");
+
+    let acme = ctx("00000000-0000-0000-0000-00000000acme", "acme");
+
+    // Second call must not fail (ensure_indexes already ran, in-memory
+    // marker is set, Mongo's createIndex is idempotent by name anyway).
+    let _ = pool.for_tenant(&acme).await.expect("first call");
+    let _ = pool.for_tenant(&acme).await.expect("second call");
+    let _ = pool.for_tenant(&acme).await.expect("third call");
+
+    // Cleanup
+    let db_name = pool.tenant_db_name(&acme.tenant_id);
+    pool.client().database(&db_name).drop().await.expect("drop");
+}
+
+#[tokio::test]
+async fn tenant_db_name_sanitizes_unsafe_characters() {
+    let uri = std::env::var("TEST_MONGODB_URI")
+        .unwrap_or_else(|_| "mongodb://root:example@localhost:27017/?authSource=admin".into());
+    let pool = DatabasePool::connect(&uri, "m72a_sanitize")
+        .await
+        .expect("connect");
+
+    // Mongo db names cannot contain `/ \ . " $ <space> NUL`. The pool
+    // must rewrite these without exploding on connect.
+    let funky = "te/n.a\\nt$id\" with spaces";
+    let name = pool.tenant_db_name(funky);
+    for c in ['/', '\\', '.', '"', '$', ' '] {
+        assert!(
+            !name.contains(c),
+            "sanitized db name still contains {c:?}: {name}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn tenant_db_name_falls_back_to_hash_when_too_long() {
+    let uri = std::env::var("TEST_MONGODB_URI")
+        .unwrap_or_else(|_| "mongodb://root:example@localhost:27017/?authSource=admin".into());
+    let pool = DatabasePool::connect(&uri, "m72a_long")
+        .await
+        .expect("connect");
+
+    // 100-byte tenant_id would overflow the 63-byte db-name cap with
+    // any reasonable prefix. The pool must hash it down.
+    let huge = "x".repeat(100);
+    let name = pool.tenant_db_name(&huge);
+    assert!(name.len() <= 63, "hashed name should fit: {name}");
+    assert!(name.starts_with("m72a_long_"));
+    // The hash suffix is 32 hex chars (16-byte SHA-256 truncation).
+    let suffix = name.trim_start_matches("m72a_long_");
+    assert_eq!(
+        suffix.len(),
+        32,
+        "expected 32-hex suffix (16-byte hash), got {suffix:?}"
+    );
+    assert!(suffix.chars().all(|c| c.is_ascii_hexdigit()));
+
+    // Stable: same input → same output.
+    assert_eq!(name, pool.tenant_db_name(&huge));
+
+    // Different inputs → different outputs (collision check on a tiny
+    // sample — full birthday-resistance is a proof not a test).
+    let huge2 = "y".repeat(100);
+    assert_ne!(pool.tenant_db_name(&huge), pool.tenant_db_name(&huge2));
+}
+
+#[tokio::test]
+async fn connect_rejects_overlong_db_prefix() {
+    let uri = std::env::var("TEST_MONGODB_URI")
+        .unwrap_or_else(|_| "mongodb://root:example@localhost:27017/?authSource=admin".into());
+
+    // MAX_PREFIX_LEN is 30 (= 63 - 1 - 32). A 31-char prefix MUST be
+    // rejected at construction so the hash-fallback path can never
+    // produce an over-long db name at runtime.
+    let too_long = "a".repeat(31);
+    let err = DatabasePool::connect(&uri, &too_long).await.unwrap_err();
+    let msg = format!("{err}");
+    assert!(
+        msg.contains("max is 30") || msg.contains(&too_long),
+        "error should explain the cap: {msg}"
+    );
+
+    // Exactly 30 chars is the inclusive bound — must succeed.
+    let just_right = "a".repeat(30);
+    let _ = DatabasePool::connect(&uri, &just_right)
+        .await
+        .expect("30-char prefix should be accepted");
+}
+
+/// Short UUID slug for keeping test prefixes well under Mongo's 63-byte
+/// db-name cap.
+fn short_id() -> String {
+    uuid::Uuid::new_v4().simple().to_string()[..8].to_string()
+}
+
+/// Drain a `repositories` find cursor on the given tenant database.
+async fn collect(db: &compliance_agent::database::Database) -> Vec<TrackedRepository> {
+    let mut cursor = db
+        .repositories()
+        .find(doc! {})
+        .await
+        .expect("find repositories");
+    let mut out = Vec::new();
+    while cursor.advance().await.expect("advance") {
+        out.push(cursor.deserialize_current().expect("deserialize"));
+    }
+    out
+}

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::{auth::require_tenant_status, TenantContext, TenantStatus};
-use compliance_core::{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
+//! attaches a [`TenantContext`] to the request extensions. Downstream
-//! middleware (`require_tenant_status`) and Axum extractors (`TenantCtx`)
+//! middleware ([`require_tenant_status`]) and Axum extractors
-//! read it from there.
+//! ([`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))
+        .find(|k| k.common.key_id.as_deref() == Some(kid))
-        .ok_or_else(|| "no matching key found in JWKS".to_string())?;
+    {
+        Some(j) => j,
+        None => {
+            return Err(ValidationError::Stale(
+                "no matching key found in JWKS".to_string(),
+            ))
+        }
+    };
 
-    let decoding_key =
+    let decoding_key = DecodingKey::from_jwk(jwk)
-        DecodingKey::from_jwk(jwk).map_err(|e| format!("failed to create decoding key: {e}"))?;
+        .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)
+    let data = match decode::<Claims>(token, &decoding_key, &validation) {
-        .map_err(|e| format!("token validation failed: {e}"))?;
+        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
+//! M7.1 single source of truth for "who is this request for". Claims come
-//! for". Claims come from a Keycloak-issued JWT and land here via
+//! from a Keycloak-issued JWT and land here via [`crate::auth::require_jwt_auth`]
-//! `compliance-agent`'s `require_jwt_auth` middleware. Handlers reach into
+//! (enabled with the `axum` feature). Handlers reach into the request
-//! the request extensions with the `TenantCtx` Axum extractor.
+//! 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
+/// Everything we know about the requesting tenant at the moment a request
-/// moment a request lands. Cheap to clone (every field is owned + small).
+/// 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
+//! The middleware ([`crate::auth::require_jwt_auth`]) is responsible for
-//! context into the request extensions. If it's missing on a route that
+//! inserting the context into the request extensions. If it's missing on
-//! uses this extractor, that's a bug in the wiring — we return 401 so the
+//! a route that uses this extractor, that's a bug in the wiring — we
-//! caller sees an auth failure rather than a 500.
+//! 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"