From 0e5beb4b3a26bf283f3783501196bd9097355451 Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Fri, 12 Jun 2026 13:31:10 +0200
Subject: [PATCH 1/6] Scrub inherited GIT_* env in cli_deps test git helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Running the suite from a git hook (e.g. pre-commit in a worktree) leaks
GIT_DIR into the tests' subprocesses, pointing their git init at the
developer's repo — locked mid-commit — instead of the temp dir.
---
 tests/cli_deps.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tests/cli_deps.rs b/tests/cli_deps.rs
index 7723e8c..bffb1fe 100644
--- a/tests/cli_deps.rs
+++ b/tests/cli_deps.rs
@@ -898,8 +898,15 @@ fn commit_all(repo: &std::path::Path, message: &str) {
 }
 
 fn run_git(repo: &std::path::Path, args: &[&str]) {
+    // Scrub the GIT_* env a parent git process injects (e.g. when these
+    // tests run from a pre-commit hook): an inherited GIT_DIR would point
+    // `git init` at the developer's repo instead of `repo`.
     let output = Command::new("git")
         .current_dir(repo)
+        .env_remove("GIT_DIR")
+        .env_remove("GIT_WORK_TREE")
+        .env_remove("GIT_COMMON_DIR")
+        .env_remove("GIT_INDEX_FILE")
         .args(args)
         .output()
         .expect("run git");

From 72216d44ce1ab3534df861860829f6e524cab386 Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Fri, 12 Jun 2026 13:31:21 +0200
Subject: [PATCH 2/6] Phase 0: vuln-api contract client, in-process stub, test
 scaffold

The vuln-api client and its versioned contract (clean / vulnerable /
malware / unknown verdicts, remediation data), harvested from the
install-vuln-gate spike (dfac68e) and trimmed to phase scope: public
unauthenticated lookups only, no retries, no user-facing command.

- src/vuln_api: blocking client for /v1/packages/.../check with status
  mapping, identity guard, and PEP 503 request-time normalization
- src/vuln_api_stub: in-process TCP stub, gated out of release builds
  via the test-stub feature + self dev-dependency
- tests/common: shared GateHarness scaffold for later phases
- tests/vuln_api_contract.rs: contract tests against the stub (hermetic)
  and the staging worker (#[ignore], deterministic targets documented in
  tests/fixtures/vuln_api/README.md)
---
 Cargo.lock                                    |   1 +
 Cargo.toml                                    |  12 +
 src/deps/ecosystems/pypi.rs                   |   5 +-
 src/lib.rs                                    |  10 +
 src/vuln_api/mod.rs                           | 559 ++++++++++++++++++
 src/vuln_api_stub/mod.rs                      | 271 +++++++++
 tests/common/mod.rs                           | 274 +++++++++
 tests/fixtures/vuln_api/README.md             |  32 +
 tests/fixtures/vuln_api/check_clean.json      |   1 +
 tests/fixtures/vuln_api/check_malware.json    |  15 +
 tests/fixtures/vuln_api/check_unknown.json    |   1 +
 tests/fixtures/vuln_api/check_vulnerable.json |  15 +
 tests/vuln_api_contract.rs                    | 172 ++++++
 13 files changed, 1367 insertions(+), 1 deletion(-)
 create mode 100644 src/vuln_api/mod.rs
 create mode 100644 src/vuln_api_stub/mod.rs
 create mode 100644 tests/common/mod.rs
 create mode 100644 tests/fixtures/vuln_api/README.md
 create mode 100644 tests/fixtures/vuln_api/check_clean.json
 create mode 100644 tests/fixtures/vuln_api/check_malware.json
 create mode 100644 tests/fixtures/vuln_api/check_unknown.json
 create mode 100644 tests/fixtures/vuln_api/check_vulnerable.json
 create mode 100644 tests/vuln_api_contract.rs

diff --git a/Cargo.lock b/Cargo.lock
index 2b9c8e7..58bd8d2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -344,6 +344,7 @@ version = "1.8.8"
 dependencies = [
  "chrono",
  "clap",
+ "corgea",
  "dirs",
  "env_logger",
  "git2",
diff --git a/Cargo.toml b/Cargo.toml
index d60edad..5228045 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,6 +5,18 @@ edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[[bin]]
+name = "corgea"
+path = "src/main.rs"
+
+[features]
+# Compiles the in-crate vuln-api test stub (`vuln_api_stub`). Enabled for all
+# test builds via the self dev-dependency below; never part of release builds.
+test-stub = []
+
+[dev-dependencies]
+corgea = { path = ".", features = ["test-stub"] }
+
 [dependencies]
 clap = { version = "4.4.13", features = ["derive"] }
 dirs = "5.0.1"
diff --git a/src/deps/ecosystems/pypi.rs b/src/deps/ecosystems/pypi.rs
index 062f13c..3a77faa 100644
--- a/src/deps/ecosystems/pypi.rs
+++ b/src/deps/ecosystems/pypi.rs
@@ -367,7 +367,10 @@ fn exact_version_from_declared(name: &str, declared: &str) -> Option<String> {
     Some(declared.trim_start_matches('=').trim().to_string())
 }
 
-fn normalize_pypi_name(name: &str) -> String {
+/// PEP 503 name normalization: lowercase, runs of `-`/`_`/`.` collapse to `-`.
+/// Also used by the vuln-api client (`vuln_api`) so both features share one
+/// canonical pypi name form.
+pub(crate) fn normalize_pypi_name(name: &str) -> String {
     let mut out = String::new();
     let mut last_was_separator = false;
     for c in name.trim().chars() {
diff --git a/src/lib.rs b/src/lib.rs
index 49bc6d0..2f8423e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1 +1,11 @@
 pub mod deps;
+// Also declared in the binary crate (src/main.rs); re-declared here so library modules
+// (e.g. vuln_api) can use `crate::log::debug`. src/log.rs is a thin `::log` facade that
+// compiles cleanly in both crates.
+mod log;
+pub mod vuln_api;
+// Test-only HTTP stub for the vuln-api. Gated out of release builds; the
+// `test-stub` feature is enabled for every test build by the self
+// dev-dependency in Cargo.toml, so integration tests can use it too.
+#[cfg(any(test, feature = "test-stub"))]
+pub mod vuln_api_stub;
diff --git a/src/vuln_api/mod.rs b/src/vuln_api/mod.rs
new file mode 100644
index 0000000..222567c
--- /dev/null
+++ b/src/vuln_api/mod.rs
@@ -0,0 +1,559 @@
+//! Corgea vuln-api client.
+//!
+//! Deliberately independent of `utils::api::SHARED_CLIENT` because:
+//!   * the vuln-api host is user-configurable via `CORGEA_VULN_API_URL`,
+//!     so we must never silently replay Corgea cookies or auth headers
+//!     via redirect following or the shared cookie jar.
+//!   * the shared client's `check_for_warnings` exits the process on
+//!     HTTP 410, which is wrong for per-dep CVE lookups.
+//!
+//! Lookups are public and unauthenticated: no Corgea credential is ever
+//! attached, so a user-configured host can never see one.
+
+use serde::Deserialize;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use crate::log::debug;
+
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Cap on how much of an error response body we splice into the
+/// user-facing error message. Fits a CLI line, captures
+/// `{"error":"…"}`-class messages comfortably, and truncates
+/// Cloudflare HTML before it gets ugly.
+const ERROR_BODY_SNIPPET_LEN: usize = 300;
+
+/// Registry ecosystem a package check targets. Typed so the URL path
+/// segment and the per-ecosystem name encoding can't drift apart on a
+/// string spelling.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Ecosystem {
+    Npm,
+    Pypi,
+}
+
+impl Ecosystem {
+    pub fn path_segment(self) -> &'static str {
+        match self {
+            Ecosystem::Npm => "npm",
+            Ecosystem::Pypi => "pypi",
+        }
+    }
+
+    /// Canonical package name for requests and comparisons: PEP 503 for
+    /// pypi (shared with `deps`), verbatim for npm (names are
+    /// case-sensitive). The one definition of the per-ecosystem rule.
+    pub fn normalize_name(self, name: &str) -> String {
+        match self {
+            Ecosystem::Npm => name.to_string(),
+            Ecosystem::Pypi => crate::deps::ecosystems::pypi::normalize_pypi_name(name),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct VulnCheckResponse {
+    pub ecosystem: String,
+    pub package_name: String,
+    pub version: String,
+    pub is_vulnerable: bool,
+    pub matches: Vec<VulnMatch>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct VulnMatch {
+    pub advisory_id: String,
+    pub severity_level: String,
+    pub tier: u8,
+    pub vulnerable_version_range: Option<String>,
+    pub fixed_version: Option<String>,
+}
+
+/// `corgea-cli/<version> (<label>)` user-agent string.
+pub(crate) fn user_agent(label: &str) -> String {
+    format!("corgea-cli/{} ({label})", env!("CARGO_PKG_VERSION"))
+}
+
+/// Build (once) and clone the shared vuln-api client. A blocking reqwest
+/// client owns a runtime thread, and a gate run checks many packages —
+/// cache it. `Client` clones share the same pool, so the clone is cheap.
+pub fn http_client() -> Result<reqwest::blocking::Client, String> {
+    static CLIENT: OnceLock<Result<reqwest::blocking::Client, String>> = OnceLock::new();
+    CLIENT
+        .get_or_init(|| {
+            reqwest::blocking::Client::builder()
+                .timeout(REQUEST_TIMEOUT)
+                .user_agent(user_agent("vuln-api"))
+                .redirect(reqwest::redirect::Policy::none())
+                .build()
+                .map_err(|e| format!("failed to build vuln-api http client: {}", e))
+        })
+        .clone()
+}
+
+/// URL-encode an npm package name for a URL path segment. Scoped names
+/// contain `@` and `/`; the latter must be encoded as `%2f`.
+pub(crate) fn encode_npm_name(name: &str) -> String {
+    if let Some(stripped) = name.strip_prefix('@') {
+        if let Some((scope, pkg)) = stripped.split_once('/') {
+            return format!("@{}%2f{}", scope, pkg);
+        }
+    }
+    name.to_string()
+}
+
+/// Encode package name for the vuln-api path segment.
+/// npm scoped names: `@scope/pkg` → `@scope%2fpkg`.
+fn encode_package_name(ecosystem: Ecosystem, name: &str) -> String {
+    match ecosystem {
+        Ecosystem::Npm => encode_npm_name(name),
+        Ecosystem::Pypi => urlencoding::encode(name).into_owned(),
+    }
+}
+
+/// Value for the `CORGEA-SOURCE` header: the `CORGEA_SOURCE` env override,
+/// otherwise `cli`. Read once and cached — it's attached per request from
+/// concurrent pool workers, and `std::env::var` takes the process-global
+/// env lock.
+pub fn source() -> String {
+    static SOURCE: OnceLock<String> = OnceLock::new();
+    SOURCE
+        .get_or_init(|| std::env::var("CORGEA_SOURCE").unwrap_or_else(|_| "cli".to_string()))
+        .clone()
+}
+
+/// Build a JSON GET with the standard `Accept` / `CORGEA-SOURCE` headers.
+/// No auth header: lookups are public, and the host may be user-configured.
+fn build_json_get(
+    client: &reqwest::blocking::Client,
+    url: &str,
+) -> reqwest::blocking::RequestBuilder {
+    client
+        .get(url)
+        .header("Accept", "application/json")
+        .header("CORGEA-SOURCE", source())
+}
+
+/// Validate the per-call preconditions shared by every vuln-api request:
+/// a non-empty (trailing-slash-normalized) base URL. Returns the normalized
+/// base so callers don't re-derive it.
+fn validated_base(base_url: &str) -> Result<String, Box<dyn std::error::Error>> {
+    let base = base_url.trim_end_matches('/').to_string();
+    if base.is_empty() {
+        return Err("vuln-api base URL is empty".into());
+    }
+    Ok(base)
+}
+
+/// Format a server error body into a `": <snippet>"` suffix for a single-line
+/// CLI error, or an empty string when the body is empty. Consumes the response.
+fn error_body_suffix(response: reqwest::blocking::Response) -> String {
+    let body = response.text().unwrap_or_default();
+    let snippet = body_snippet(&body, ERROR_BODY_SNIPPET_LEN);
+    if snippet.is_empty() {
+        String::new()
+    } else {
+        format!(": {}", snippet)
+    }
+}
+
+/// Collapse whitespace and truncate at `max_chars` so a server error
+/// body can be spliced into a single-line CLI error message without
+/// dragging in HTML newlines or runaway length. Returns empty string
+/// when the body is empty so the caller can format conditionally.
+/// Char-boundary safe — operates on `chars()`, never byte slices.
+fn body_snippet(body: &str, max_chars: usize) -> String {
+    let collapsed: String = body.split_whitespace().collect::<Vec<_>>().join(" ");
+    if collapsed.is_empty() {
+        return String::new();
+    }
+    let truncated: String = collapsed.chars().take(max_chars).collect();
+    if collapsed.chars().count() > max_chars {
+        format!("{}…", truncated)
+    } else {
+        truncated
+    }
+}
+
+/// One HTTP request per `(name, version)`. A 1000-package lockfile makes
+/// 1000 requests (through the verdict pool's bounded concurrency); the
+/// future optimization is a server-side batch endpoint, not client tricks.
+pub fn check_package_version(
+    client: &reqwest::blocking::Client,
+    base_url: &str,
+    ecosystem: Ecosystem,
+    name: &str,
+    version: &str,
+) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
+    let base = validated_base(base_url)?;
+    // vuln-api advisories are keyed by canonical names; an alternate
+    // spelling (PEP 503: `Flask_Cors` ≡ `flask-cors`) would miss and read
+    // as clean. The client owns request-time normalization so no caller
+    // can forget it.
+    let name = &ecosystem.normalize_name(name);
+    let encoded_name = encode_package_name(ecosystem, name);
+    let encoded_version = urlencoding::encode(version);
+    let url = format!(
+        "{}/v1/packages/{}/{}/versions/{}/check",
+        base,
+        ecosystem.path_segment(),
+        encoded_name,
+        encoded_version
+    );
+
+    debug(&format!("Sending vuln-api request to URL: {}", url));
+
+    let response = build_json_get(client, &url)
+        .send()
+        .map_err(|e| format!("Failed to send vuln-api request: {}", e))?;
+
+    let status = response.status();
+    // Fixed messages for recognized statuses — tests assert these strings,
+    // keep them stable. The /check route answers 200 (empty matches) for
+    // unknown packages; a 404 can only mean a wrong base URL or route, and
+    // treating it as "clean" would silently disable the gate on a
+    // misconfigured endpoint.
+    match status.as_u16() {
+        401 => return Err("vuln-api requires authentication".into()),
+        403 => return Err("vuln-api access denied (check your Corgea plan/permissions)".into()),
+        429 => return Err("vuln-api rate-limited this request (retry later)".into()),
+        code @ 500..=599 => return Err(format!("vuln-api unavailable (HTTP {})", code).into()),
+        404 => {
+            return Err("vuln-api route not found (HTTP 404) — check CORGEA_VULN_API_URL".into());
+        }
+        code if !status.is_success() => {
+            let suffix = error_body_suffix(response);
+            return Err(format!("vuln-api returned unexpected HTTP {}{}", code, suffix).into());
+        }
+        _ => {}
+    }
+
+    let response_text = response.text()?;
+    let parsed: VulnCheckResponse = serde_json::from_str(&response_text).map_err(|e| {
+        debug(&format!(
+            "Failed to parse vuln-api response: {}. Body: {}",
+            e,
+            body_snippet(&response_text, ERROR_BODY_SNIPPET_LEN)
+        ));
+        format!("Failed to parse vuln-api response: {}", e)
+    })?;
+
+    // Confused-deputy guard: refuse to attribute advisories to a different
+    // (name, version, ecosystem) than what we asked about. The server is
+    // allowed to be silent on identity, but if it answers, it must match.
+    // Comparisons are case-insensitive: staging spells pypi "PyPI".
+    if !parsed.ecosystem.is_empty()
+        && !parsed
+            .ecosystem
+            .eq_ignore_ascii_case(ecosystem.path_segment())
+    {
+        return Err(format!(
+            "vuln-api response ecosystem '{}' does not match request '{}'",
+            parsed.ecosystem,
+            ecosystem.path_segment()
+        )
+        .into());
+    }
+    if !parsed.package_name.is_empty() && !parsed.package_name.eq_ignore_ascii_case(name) {
+        return Err(format!(
+            "vuln-api response package '{}' does not match request '{}'",
+            parsed.package_name, name
+        )
+        .into());
+    }
+    if !parsed.version.is_empty() && parsed.version != version {
+        return Err(format!(
+            "vuln-api response version '{}' does not match request '{}'",
+            parsed.version, version
+        )
+        .into());
+    }
+
+    // is_vulnerable=true with no matches is contradictory — treat as an
+    // error so the caller can surface it rather than silently demoting
+    // the dep to "clean".
+    if parsed.is_vulnerable && parsed.matches.is_empty() {
+        return Err(
+            "vuln-api reported is_vulnerable=true with no matches; refusing to interpret".into(),
+        );
+    }
+
+    Ok(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::vuln_api_stub::{self, header_value, spawn_capturing_vuln_api_stub, PackageKey};
+    use std::collections::HashMap;
+
+    fn lodash_key() -> PackageKey {
+        vuln_api_stub::key("npm", "lodash", "4.17.20")
+    }
+
+    fn check_lodash(
+        stub: &vuln_api_stub::VulnApiStub,
+    ) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
+        let client = http_client().expect("test client");
+        check_package_version(&client, &stub.base_url, Ecosystem::Npm, "lodash", "4.17.20")
+    }
+
+    fn check_with_stub_status(
+        status_code: u16,
+        body: &str,
+    ) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
+        let stub = vuln_api_stub::spawn_with_statuses(
+            HashMap::from([(lodash_key(), body.to_string())]),
+            HashMap::from([(lodash_key(), status_code)]),
+        );
+        check_lodash(&stub)
+    }
+
+    fn check_with_stub_body(body: &str) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
+        let stub = vuln_api_stub::spawn_with_statuses(
+            HashMap::from([(lodash_key(), body.to_string())]),
+            HashMap::new(),
+        );
+        check_lodash(&stub)
+    }
+
+    #[test]
+    fn check_sends_no_auth_headers() {
+        // The host is user-configurable; the client must never attach a
+        // Corgea credential, cookie, or token header.
+        let (base_url, requests) = spawn_capturing_vuln_api_stub();
+        let client = http_client().expect("test client");
+        check_package_version(&client, &base_url, Ecosystem::Npm, "lodash", "4.17.20")
+            .expect("captured request should succeed");
+        let requests = requests.lock().unwrap();
+        let request = &requests[0];
+        assert!(header_value(request, "Authorization").is_none());
+        assert!(header_value(request, "CORGEA-TOKEN").is_none());
+        assert!(header_value(request, "Cookie").is_none());
+        assert_eq!(
+            header_value(request, "CORGEA-SOURCE").as_deref(),
+            Some("cli")
+        );
+    }
+
+    #[test]
+    fn check_package_version_401_returns_actionable_error() {
+        let err = check_with_stub_status(401, r#"{"error":"unauthorized"}"#)
+            .expect_err("401 should fail");
+        assert!(err.to_string().contains("requires authentication"));
+    }
+
+    #[test]
+    fn check_package_version_403_returns_actionable_error() {
+        let err =
+            check_with_stub_status(403, r#"{"error":"forbidden"}"#).expect_err("403 should fail");
+        assert!(err.to_string().contains("access denied"));
+    }
+
+    #[test]
+    fn check_package_version_404_is_an_error_not_clean() {
+        // The real /check route 200s for unknown packages; 404 means the
+        // base URL/route is wrong. Synthesizing "clean" here would turn a
+        // misconfigured CORGEA_VULN_API_URL into a silent all-clear.
+        let err = check_with_stub_status(404, r#"{"error":"not found"}"#)
+            .expect_err("404 should be an error");
+        assert!(err.to_string().contains("CORGEA_VULN_API_URL"));
+    }
+
+    #[test]
+    fn check_package_version_429_returns_actionable_error() {
+        let err = check_with_stub_status(429, r#"{"error":"rate limited"}"#)
+            .expect_err("429 should fail");
+        assert!(err.to_string().contains("rate-limited"));
+    }
+
+    #[test]
+    fn check_package_version_500_returns_unavailable() {
+        let err =
+            check_with_stub_status(500, r#"{"error":"internal"}"#).expect_err("500 should fail");
+        assert!(err.to_string().contains("unavailable (HTTP 500)"));
+    }
+
+    #[test]
+    fn check_package_version_unexpected_status_includes_body_snippet() {
+        let err =
+            check_with_stub_status(418, r#"{"error":"teapot"}"#).expect_err("418 should fail");
+        let msg = err.to_string();
+        assert!(msg.contains("unexpected HTTP 418"), "got: {}", msg);
+        assert!(
+            msg.contains("teapot"),
+            "expected body in error; got: {}",
+            msg
+        );
+    }
+
+    #[test]
+    fn check_package_version_unexpected_status_omits_body_when_empty() {
+        let err = check_with_stub_status(418, "").expect_err("418 should fail");
+        let msg = err.to_string();
+        assert!(msg.contains("unexpected HTTP 418"), "got: {}", msg);
+        // Body is empty → message must end at the status, no dangling ":" or whitespace.
+        assert!(
+            msg.trim_end().ends_with("418"),
+            "expected message to end at status code; got: {:?}",
+            msg
+        );
+    }
+
+    #[test]
+    fn mismatched_package_name_is_an_error() {
+        let body = r#"{"ecosystem":"npm","package_name":"left-pad","version":"4.17.20","is_vulnerable":false,"matches":[]}"#;
+        let err = check_with_stub_body(body).expect_err("identity mismatch should fail");
+        assert!(err.to_string().contains("does not match request"));
+    }
+
+    #[test]
+    fn mismatched_version_is_an_error() {
+        let body = r#"{"ecosystem":"npm","package_name":"lodash","version":"9.9.9","is_vulnerable":false,"matches":[]}"#;
+        let err = check_with_stub_body(body).expect_err("identity mismatch should fail");
+        assert!(err.to_string().contains("does not match request"));
+    }
+
+    #[test]
+    fn ecosystem_comparison_is_case_insensitive() {
+        // Staging spells pypi "PyPI"; that must not trip the identity guard.
+        let body = r#"{"ecosystem":"NPM","package_name":"lodash","version":"4.17.20","is_vulnerable":false,"matches":[]}"#;
+        let parsed = check_with_stub_body(body).expect("case difference is not a mismatch");
+        assert!(!parsed.is_vulnerable);
+    }
+
+    #[test]
+    fn vulnerable_without_matches_is_an_error() {
+        let body = r#"{"ecosystem":"npm","package_name":"lodash","version":"4.17.20","is_vulnerable":true,"matches":[]}"#;
+        let err = check_with_stub_body(body).expect_err("contradictory verdict should fail");
+        assert!(err.to_string().contains("refusing to interpret"));
+    }
+
+    #[test]
+    fn body_snippet_truncates_at_char_boundary() {
+        // Multi-byte char ("é" is 2 bytes UTF-8). Naïve byte-slicing would
+        // panic; we must operate on chars().
+        let input = "é".repeat(500);
+        let out = body_snippet(&input, ERROR_BODY_SNIPPET_LEN);
+        assert!(out.ends_with('…'), "expected ellipsis; got: {:?}", out);
+        // 300 "é" chars + the ellipsis.
+        assert_eq!(out.chars().count(), ERROR_BODY_SNIPPET_LEN + 1);
+    }
+
+    #[test]
+    fn body_snippet_collapses_whitespace() {
+        assert_eq!(body_snippet("foo\n  bar\t\tbaz", 100), "foo bar baz");
+    }
+
+    #[test]
+    fn body_snippet_empty_returns_empty() {
+        assert_eq!(body_snippet("", 100), "");
+        assert_eq!(body_snippet("   \n\t  ", 100), "");
+    }
+
+    #[test]
+    fn encode_package_name_scoped_npm() {
+        assert_eq!(
+            encode_package_name(Ecosystem::Npm, "@types/node"),
+            "@types%2fnode"
+        );
+        assert_eq!(encode_package_name(Ecosystem::Npm, "lodash"), "lodash");
+    }
+
+    #[test]
+    fn encode_package_name_pypi() {
+        assert_eq!(encode_package_name(Ecosystem::Pypi, "requests"), "requests");
+    }
+
+    #[test]
+    fn deserialize_vuln_check_response() {
+        let body = r#"{
+            "ecosystem": "npm",
+            "package_name": "lodash",
+            "version": "4.17.20",
+            "is_vulnerable": true,
+            "matches": [{
+                "advisory_id": "GHSA-xxxx-yyyy-zzzz",
+                "severity_level": "high",
+                "tier": 1,
+                "vulnerable_version_range": "<4.17.21",
+                "fixed_version": "4.17.21"
+            }]
+        }"#;
+        let parsed: VulnCheckResponse = serde_json::from_str(body).unwrap();
+        assert!(parsed.is_vulnerable);
+        assert_eq!(parsed.matches.len(), 1);
+        assert_eq!(parsed.matches[0].advisory_id, "GHSA-xxxx-yyyy-zzzz");
+        assert_eq!(parsed.matches[0].tier, 1);
+    }
+
+    #[test]
+    fn validated_base_strips_trailing_slash() {
+        assert_eq!(
+            validated_base("http://localhost:8080/").unwrap(),
+            "http://localhost:8080"
+        );
+        assert!(validated_base("").is_err());
+    }
+
+    // Fixture-based deserialization tests — committed JSON under tests/fixtures/vuln_api/,
+    // built to the authoritative server serialization (vuln-api/cve_worker/src/worker.js).
+    macro_rules! fixture {
+        ($name:literal) => {
+            include_str!(concat!(
+                env!("CARGO_MANIFEST_DIR"),
+                "/tests/fixtures/vuln_api/",
+                $name
+            ))
+        };
+    }
+
+    #[test]
+    fn fixture_check_clean_deserializes() {
+        let parsed: VulnCheckResponse = serde_json::from_str(fixture!("check_clean.json")).unwrap();
+        assert!(!parsed.is_vulnerable);
+        assert!(parsed.matches.is_empty());
+        assert_eq!(parsed.ecosystem, "pypi");
+        assert_eq!(parsed.package_name, "requests");
+        assert_eq!(parsed.version, "2.31.0");
+    }
+
+    #[test]
+    fn fixture_check_unknown_deserializes_as_clean() {
+        // /check returns 200 is_vulnerable:false matches:[] for an unknown package;
+        // the 404 {"error":"Package not found"} body is the profile route, not /check.
+        let parsed: VulnCheckResponse =
+            serde_json::from_str(fixture!("check_unknown.json")).unwrap();
+        assert!(!parsed.is_vulnerable);
+        assert!(parsed.matches.is_empty());
+    }
+
+    #[test]
+    fn fixture_check_vulnerable_deserializes() {
+        let parsed: VulnCheckResponse =
+            serde_json::from_str(fixture!("check_vulnerable.json")).unwrap();
+        assert!(parsed.is_vulnerable);
+        assert_eq!(parsed.matches.len(), 1);
+        let m = &parsed.matches[0];
+        assert_eq!(m.advisory_id, "GHSA-xxxx-yyyy-zzzz");
+        assert_eq!(m.severity_level, "high");
+        assert_eq!(m.tier, 1);
+        assert_eq!(m.vulnerable_version_range.as_deref(), Some(">=3.2,<3.2.5"));
+        assert_eq!(m.fixed_version.as_deref(), Some("3.2.5"));
+    }
+
+    #[test]
+    fn fixture_check_malware_deserializes() {
+        // Malware surfaces through /check as an ordinary is_vulnerable:true match
+        // (MAL-* id); /malware items carry no version, so /check is the per-version signal.
+        let parsed: VulnCheckResponse =
+            serde_json::from_str(fixture!("check_malware.json")).unwrap();
+        assert!(parsed.is_vulnerable);
+        assert_eq!(parsed.matches.len(), 1);
+        let m = &parsed.matches[0];
+        assert!(m.advisory_id.starts_with("MAL-"));
+        assert!(m.vulnerable_version_range.is_none());
+        assert!(m.fixed_version.is_none());
+    }
+}
diff --git a/src/vuln_api_stub/mod.rs b/src/vuln_api_stub/mod.rs
new file mode 100644
index 0000000..6f07a3d
--- /dev/null
+++ b/src/vuln_api_stub/mod.rs
@@ -0,0 +1,271 @@
+use std::collections::HashMap;
+use std::io::{Read, Write};
+use std::net::TcpListener;
+use std::thread;
+
+pub type PackageKey = (String, String, String);
+
+/// `(ecosystem, name, version)` key for the stub's route tables. Applies the
+/// client's canonical-name rule (`Ecosystem::normalize_name`) on both the
+/// fixture and lookup sides, so a fixture keyed under an alternate pypi
+/// spelling can't silently miss and read as clean.
+pub fn key(eco: &str, name: &str, ver: &str) -> PackageKey {
+    let name = match eco {
+        "pypi" => crate::vuln_api::Ecosystem::Pypi.normalize_name(name),
+        _ => name.to_string(),
+    };
+    (eco.to_string(), name, ver.to_string())
+}
+
+/// Single-match vulnerable verdict body; `fixed: None` renders
+/// `"fixed_version":null`. Shared by the in-crate unit tests and the
+/// integration tests (via `tests/common`).
+pub fn vulnerable_body(
+    ecosystem: &str,
+    name: &str,
+    version: &str,
+    advisory: &str,
+    fixed: Option<&str>,
+) -> String {
+    let fixed = fixed.map_or("null".to_string(), |f| format!(r#""{f}""#));
+    format!(
+        r#"{{"ecosystem":"{ecosystem}","package_name":"{name}","version":"{version}","is_vulnerable":true,
+        "matches":[{{"advisory_id":"{advisory}","severity_level":"critical","tier":1,
+                    "vulnerable_version_range":null,"fixed_version":{fixed}}}]}}"#
+    )
+}
+
+const NOT_FOUND_BODY: &str = r#"{"error":"not found"}"#;
+
+pub struct VulnApiStub {
+    pub base_url: String,
+    _handle: thread::JoinHandle<()>,
+}
+
+/// Minimal TCP vuln-api stub for CLI integration tests. Binds an ephemeral
+/// 127.0.0.1 port; unknown packages get a synthesized clean 200.
+pub fn spawn_with_statuses(
+    package_checks: HashMap<PackageKey, String>,
+    status_overrides: HashMap<PackageKey, u16>,
+) -> VulnApiStub {
+    spawn(package_checks, status_overrides, None)
+}
+
+/// Vuln-api stub that records raw requests and answers every package check
+/// with a clean verdict (echoing the eco/name/version from the path). Used
+/// to assert the client's header behavior, both in-crate and from the CLI.
+pub fn spawn_capturing_vuln_api_stub() -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {
+    let requests = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    let stub = spawn(
+        HashMap::new(),
+        HashMap::new(),
+        Some(std::sync::Arc::clone(&requests)),
+    );
+    // Dropping the stub's join handle detaches the listener thread; the
+    // base URL keeps working for the caller's lifetime.
+    (stub.base_url, requests)
+}
+
+fn spawn(
+    package_checks: HashMap<PackageKey, String>,
+    status_overrides: HashMap<PackageKey, u16>,
+    capture: Option<std::sync::Arc<std::sync::Mutex<Vec<String>>>>,
+) -> VulnApiStub {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub");
+    let bound_port = listener.local_addr().expect("stub local_addr").port();
+    let base_url = format!("http://127.0.0.1:{bound_port}");
+
+    let handle = thread::spawn(move || {
+        for stream in listener.incoming() {
+            let Ok(mut stream) = stream else {
+                continue;
+            };
+            handle_connection(
+                &mut stream,
+                &package_checks,
+                &status_overrides,
+                capture.as_deref(),
+            );
+        }
+    });
+
+    VulnApiStub {
+        base_url,
+        _handle: handle,
+    }
+}
+
+/// One-shot JSON HTTP response. `Connection: close` is load-bearing: the
+/// stubs serve one response per connection, so without it reqwest pools the
+/// socket and a second request (a gate run makes several) races the close
+/// and fails. `extra_headers` must be empty or end in `\r\n`.
+pub fn http_response(status_line: &str, extra_headers: &str, body: &str) -> String {
+    format!(
+        "HTTP/1.1 {}\r\nContent-Type: application/json\r\n{}Content-Length: {}\r\nConnection: close\r\n\r\n{}",
+        status_line,
+        extra_headers,
+        body.len(),
+        body
+    )
+}
+
+/// The value of header `name` in a raw captured HTTP request, if present.
+pub fn header_value(request: &str, name: &str) -> Option<String> {
+    request
+        .lines()
+        .skip(1)
+        .take_while(|line| !line.trim().is_empty())
+        .filter_map(|line| line.split_once(':'))
+        .find(|(key, _)| key.eq_ignore_ascii_case(name))
+        .map(|(_, value)| value.trim().to_string())
+}
+
+/// Read one HTTP request's bytes (through the header terminator) off `stream`.
+pub fn read_http_request(stream: &mut std::net::TcpStream) -> Vec<u8> {
+    let mut buf = Vec::with_capacity(4096);
+    let mut chunk = [0u8; 1024];
+    while let Ok(n) = stream.read(&mut chunk) {
+        if n == 0 {
+            break;
+        }
+        buf.extend_from_slice(&chunk[..n]);
+        if buf.windows(4).any(|w| w == b"\r\n\r\n") {
+            break;
+        }
+    }
+    buf
+}
+
+fn handle_connection(
+    stream: &mut std::net::TcpStream,
+    package_checks: &HashMap<PackageKey, String>,
+    status_overrides: &HashMap<PackageKey, u16>,
+    capture: Option<&std::sync::Mutex<Vec<String>>>,
+) {
+    let buf = read_http_request(stream);
+    let req = String::from_utf8_lossy(&buf);
+    if let Some(capture) = capture {
+        capture.lock().unwrap().push(req.clone().into_owned());
+    }
+
+    let path = req.lines().next().and_then(|l| l.split_whitespace().nth(1));
+
+    let (status_code, response_body) = match path {
+        Some(path) => {
+            let parts: Vec<&str> = path.trim_start_matches('/').split('/').collect();
+            if parts.len() >= 7
+                && parts[0] == "v1"
+                && parts[1] == "packages"
+                && parts[4] == "versions"
+                && parts[6] == "check"
+            {
+                let key = key(
+                    parts[2],
+                    &urlencoding::decode(parts[3]).unwrap_or_default(),
+                    &urlencoding::decode(parts[5]).unwrap_or_default(),
+                );
+                let body = package_checks
+                    .get(&key)
+                    .cloned()
+                    .unwrap_or_else(|| default_clean_response(&key.0, &key.1, &key.2));
+                let status = status_overrides.get(&key).copied().unwrap_or(200);
+                (status, body)
+            } else {
+                (404, NOT_FOUND_BODY.to_string())
+            }
+        }
+        None => (400, r#"{"error":"bad request"}"#.to_string()),
+    };
+
+    let response = http_response(
+        &format!("{} {}", status_code, status_text(status_code)),
+        "",
+        &response_body,
+    );
+    let _ = stream.write_all(response.as_bytes());
+}
+
+/// Reason phrase for a stub status line.
+fn status_text(status_code: u16) -> &'static str {
+    match status_code {
+        404 => "Not Found",
+        401 => "Unauthorized",
+        403 => "Forbidden",
+        429 => "Too Many Requests",
+        500..=599 => "Internal Server Error",
+        _ if status_code >= 400 => "Error",
+        _ => "OK",
+    }
+}
+
+fn default_clean_response(eco: &str, name: &str, ver: &str) -> String {
+    format!(
+        r#"{{"ecosystem":"{eco}","package_name":"{name}","version":"{ver}","is_vulnerable":false,"matches":[]}}"#
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Read, Write};
+    use std::net::TcpStream;
+
+    fn get(base_url: &str, path: &str) -> String {
+        let addr = base_url.trim_start_matches("http://");
+        let mut stream = TcpStream::connect(addr).expect("connect stub");
+        let req = format!("GET {path} HTTP/1.1\r\nHost: localhost\r\n\r\n");
+        stream.write_all(req.as_bytes()).unwrap();
+        let mut resp = String::new();
+        stream.read_to_string(&mut resp).unwrap();
+        resp
+    }
+
+    #[test]
+    fn scripted_package_check_and_status_override() {
+        let mut checks = HashMap::new();
+        checks.insert(
+            key("pypi", "evil", "1.0.0"),
+            r#"{"ecosystem":"pypi","package_name":"evil","version":"1.0.0","is_vulnerable":true,"matches":[]}"#.to_string(),
+        );
+        checks.insert(key("pypi", "flaky", "1.0.0"), "{}".to_string());
+        let mut statuses = HashMap::new();
+        statuses.insert(key("pypi", "flaky", "1.0.0"), 503u16);
+        let stub = spawn_with_statuses(checks, statuses);
+
+        let resp = get(
+            &stub.base_url,
+            "/v1/packages/pypi/evil/versions/1.0.0/check",
+        );
+        assert!(resp.starts_with("HTTP/1.1 200"), "resp: {resp}");
+        assert!(resp.contains(r#""is_vulnerable":true"#), "resp: {resp}");
+
+        let resp = get(
+            &stub.base_url,
+            "/v1/packages/pypi/flaky/versions/1.0.0/check",
+        );
+        assert!(resp.starts_with("HTTP/1.1 503"), "resp: {resp}");
+
+        // Unknown package → synthesized clean 200.
+        let resp = get(
+            &stub.base_url,
+            "/v1/packages/pypi/unknown/versions/2.0.0/check",
+        );
+        assert!(resp.starts_with("HTTP/1.1 200"), "resp: {resp}");
+        assert!(resp.contains(r#""is_vulnerable":false"#), "resp: {resp}");
+    }
+
+    #[test]
+    fn pypi_keys_normalize_alternate_spellings() {
+        // A fixture keyed `Flask_Cors` must serve a request for `flask-cors`.
+        let checks = HashMap::from([(
+            key("pypi", "Flask_Cors", "4.0.0"),
+            vulnerable_body("pypi", "flask-cors", "4.0.0", "GHSA-test", None),
+        )]);
+        let stub = spawn_with_statuses(checks, HashMap::new());
+        let resp = get(
+            &stub.base_url,
+            "/v1/packages/pypi/flask-cors/versions/4.0.0/check",
+        );
+        assert!(resp.contains(r#""is_vulnerable":true"#), "resp: {resp}");
+    }
+}
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
new file mode 100644
index 0000000..de0b8c1
--- /dev/null
+++ b/tests/common/mod.rs
@@ -0,0 +1,274 @@
+//! Shared helpers for the e2e CLI tests (standard Cargo `tests/common/mod.rs`
+//! pattern — included via `mod common;` from each integration-test crate, so
+//! items unused by one consumer are `#[allow(dead_code)]`).
+
+#[cfg(unix)]
+use corgea::vuln_api_stub::PackageKey;
+/// `(ecosystem, name, version)` stub key and the single-match vulnerable
+/// verdict body, shared with the in-crate unit tests.
+#[allow(unused_imports)]
+pub use corgea::vuln_api_stub::{key, vulnerable_body};
+#[cfg(unix)]
+use std::collections::HashMap;
+#[cfg(unix)]
+use std::path::PathBuf;
+use std::process::Command;
+use tempfile::TempDir;
+
+/// A `corgea` invocation isolated from the host environment: temp
+/// HOME/USERPROFILE, no Corgea config/registry env vars, and no
+/// agent-detection env vars leaking in.
+#[allow(dead_code)]
+pub fn corgea_isolated() -> (Command, TempDir) {
+    let home = TempDir::new().expect("temp HOME");
+    let mut cmd = Command::new(env!("CARGO_BIN_EXE_corgea"));
+    cmd.env("HOME", home.path())
+        .env("USERPROFILE", home.path())
+        .env_remove("CORGEA_TOKEN")
+        .env_remove("CORGEA_URL")
+        .env_remove("CORGEA_NPM_REGISTRY")
+        .env_remove("CORGEA_PYPI_REGISTRY")
+        .env_remove("CORGEA_VULN_API_URL")
+        .env_remove("AI_AGENT")
+        .env_remove("CODEX_SANDBOX")
+        .env_remove("CLAUDECODE")
+        .env_remove("CLAUDE_CODE")
+        .env_remove("CURSOR_AGENT")
+        .env_remove("CURSOR_TRACE_ID")
+        .env_remove("GEMINI_CLI")
+        .env_remove("PI_AGENT");
+    (cmd, home)
+}
+
+#[allow(dead_code)]
+pub fn fixture(name: &str) -> String {
+    format!("{}/tests/fixtures/{}", env!("CARGO_MANIFEST_DIR"), name)
+}
+
+/// Canned 404 body for stub route tables.
+#[allow(dead_code)]
+pub const NOT_FOUND_JSON: &str = r#"{"message":"not found"}"#;
+
+/// Publish timestamp far in the past → never recent.
+#[allow(dead_code)]
+pub const OLD_TS: &str = "2020-01-01T00:00:00Z";
+
+/// PyPI release JSON: one release of `version`, published at `ts`.
+#[allow(dead_code)]
+pub fn pypi_release_json(name: &str, version: &str, ts: &str) -> String {
+    format!(
+        r#"{{"info":{{"name":"{name}"}},"releases":{{"{version}":[{{"upload_time_iso_8601":"{ts}"}}]}}}}"#
+    )
+}
+
+/// npm packument: a single `version` as latest, published at `ts`.
+#[allow(dead_code)]
+pub fn npm_packument(version: &str, ts: &str) -> String {
+    format!(
+        r#"{{"dist-tags":{{"latest":"{version}"}},"versions":{{"{version}":{{}}}},"time":{{"{version}":"{ts}"}}}}"#
+    )
+}
+
+/// Spawn a one-response-per-connection HTTP stub on an ephemeral 127.0.0.1
+/// port; `route` maps a request path to `(status line, body)`. Returns the
+/// base URL.
+#[allow(dead_code)]
+pub fn spawn_http_stub<F>(route: F) -> String
+where
+    F: Fn(&str) -> (&'static str, String) + Send + 'static,
+{
+    use std::io::Write;
+    use std::net::TcpListener;
+
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub");
+    let base_url = format!("http://127.0.0.1:{}", listener.local_addr().unwrap().port());
+    std::thread::spawn(move || {
+        for stream in listener.incoming() {
+            let Ok(mut stream) = stream else { continue };
+            let buf = corgea::vuln_api_stub::read_http_request(&mut stream);
+            let req = String::from_utf8_lossy(&buf);
+            let path = req
+                .lines()
+                .next()
+                .and_then(|l| l.split_whitespace().nth(1))
+                .unwrap_or("");
+            let (status, body) = route(path);
+            let response = corgea::vuln_api_stub::http_response(status, "", &body);
+            let _ = stream.write_all(response.as_bytes());
+        }
+    });
+    base_url
+}
+
+/// Registry stub serving `/pypi/oldpkg/json` (pypi) and `/oldpkg` (npm
+/// packument), both published 2020 → never recent. Everything else 404s.
+#[allow(dead_code)]
+pub fn spawn_oldpkg_registry_stub() -> String {
+    spawn_http_stub(|path| match path {
+        "/pypi/oldpkg/json" => ("200 OK", pypi_release_json("oldpkg", "1.0.0", OLD_TS)),
+        "/oldpkg" => ("200 OK", npm_packument("1.0.0", OLD_TS)),
+        _ => ("404 Not Found", NOT_FOUND_JSON.to_string()),
+    })
+}
+
+/// Registry stub serving `/pypi/<name>/json` for any single-segment name,
+/// always version 1.0.0 published 2020 → never recent. Everything else 404s.
+#[allow(dead_code)]
+pub fn spawn_wildcard_pypi_stub() -> String {
+    spawn_http_stub(|path| {
+        let name = path
+            .strip_prefix("/pypi/")
+            .and_then(|p| p.strip_suffix("/json"))
+            .filter(|n| !n.is_empty() && !n.contains('/'));
+        match name {
+            Some(name) => ("200 OK", pypi_release_json(name, "1.0.0", OLD_TS)),
+            None => ("404 Not Found", NOT_FOUND_JSON.to_string()),
+        }
+    })
+}
+
+/// Write `script` as the executable `dir/binary`.
+#[cfg(unix)]
+#[allow(dead_code)]
+pub fn write_script(dir: &std::path::Path, binary: &str, script: &str) {
+    use std::os::unix::fs::PermissionsExt;
+    let path = dir.join(binary);
+    std::fs::write(&path, script).expect("write fake script");
+    std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+        .expect("chmod fake script");
+}
+
+/// Write an executable fake package manager named `binary` into `dir`. It
+/// records its argv to `marker` and exits `exit_code` — proving both "the
+/// install ran (with these args)" and exit-code forwarding.
+#[cfg(unix)]
+#[allow(dead_code)]
+pub fn write_fake_recorder(
+    dir: &std::path::Path,
+    binary: &str,
+    marker: &std::path::Path,
+    exit_code: i32,
+) {
+    let script = format!(
+        "#!/bin/sh\nprintf '%s' \"$*\" > '{}'\nexit {}\n",
+        marker.display(),
+        exit_code
+    );
+    write_script(dir, binary, &script);
+}
+
+/// One configurable harness behind every gate test: isolated `corgea`, a
+/// private PATH of fake package managers, optional registry stubs, the
+/// vuln-api stub, and an optional throwaway project cwd.
+#[cfg(unix)]
+#[allow(dead_code)]
+pub struct GateHarness {
+    pub cmd: Command,
+    marker: PathBuf,
+    project: Option<TempDir>,
+    checks: HashMap<PackageKey, String>,
+    statuses: HashMap<PackageKey, u16>,
+    _home: TempDir,
+    _bin: TempDir,
+    _vuln_stub: Option<corgea::vuln_api_stub::VulnApiStub>,
+}
+
+#[cfg(unix)]
+#[allow(dead_code)]
+impl GateHarness {
+    pub fn new() -> Self {
+        let (mut cmd, home) = corgea_isolated();
+        let bin = TempDir::new().expect("temp bin dir");
+        let marker = bin.path().join("pm-argv.txt");
+        cmd.env("PATH", bin.path());
+        Self {
+            cmd,
+            marker,
+            project: None,
+            checks: HashMap::new(),
+            statuses: HashMap::new(),
+            _home: home,
+            _bin: bin,
+            _vuln_stub: None,
+        }
+    }
+
+    /// Plain argv recorder. Call repeatedly for multiple binaries; call
+    /// never for an empty PATH.
+    pub fn fake_recorder(self, binary: &str, exit_code: i32) -> Self {
+        write_fake_recorder(self._bin.path(), binary, &self.marker, exit_code);
+        self
+    }
+
+    /// Raw script escape hatch for scripts that need the temp bin dir or
+    /// marker path.
+    pub fn script_with_paths<F>(self, binary: &str, make_script: F) -> Self
+    where
+        F: FnOnce(&std::path::Path, &std::path::Path) -> String,
+    {
+        let script = make_script(self._bin.path(), &self.marker);
+        write_script(self._bin.path(), binary, &script);
+        self
+    }
+
+    /// oldpkg stub on both registry env vars; only the exercised ecosystem
+    /// dials it.
+    pub fn oldpkg_registry(mut self) -> Self {
+        let url = spawn_oldpkg_registry_stub();
+        self.cmd
+            .env("CORGEA_PYPI_REGISTRY", &url)
+            .env("CORGEA_NPM_REGISTRY", &url);
+        self
+    }
+
+    pub fn wildcard_pypi_registry(mut self) -> Self {
+        let url = spawn_wildcard_pypi_stub();
+        self.cmd.env("CORGEA_PYPI_REGISTRY", &url);
+        self
+    }
+
+    pub fn registry_env(mut self, var: &str, url: &str) -> Self {
+        self.cmd.env(var, url);
+        self
+    }
+
+    pub fn vuln_checks(mut self, checks: HashMap<PackageKey, String>) -> Self {
+        self.checks = checks;
+        self
+    }
+
+    pub fn vuln_statuses(mut self, statuses: HashMap<PackageKey, u16>) -> Self {
+        self.statuses = statuses;
+        self
+    }
+
+    pub fn in_project_dir(mut self) -> Self {
+        let project = TempDir::new().expect("project dir");
+        self.cmd.current_dir(project.path());
+        self.project = Some(project);
+        self
+    }
+
+    pub fn with_project_file(mut self, name: &str, body: &str) -> Self {
+        if self.project.is_none() {
+            self = self.in_project_dir();
+        }
+        let dir = self.project.as_ref().unwrap().path();
+        std::fs::write(dir.join(name), body).expect("write project file");
+        self
+    }
+
+    pub fn build(mut self) -> Self {
+        let stub = corgea::vuln_api_stub::spawn_with_statuses(
+            std::mem::take(&mut self.checks),
+            std::mem::take(&mut self.statuses),
+        );
+        self.cmd.env("CORGEA_VULN_API_URL", &stub.base_url);
+        self._vuln_stub = Some(stub);
+        self
+    }
+
+    pub fn recorded_argv(&self) -> Option<String> {
+        std::fs::read_to_string(&self.marker).ok()
+    }
+}
diff --git a/tests/fixtures/vuln_api/README.md b/tests/fixtures/vuln_api/README.md
new file mode 100644
index 0000000..28e2e14
--- /dev/null
+++ b/tests/fixtures/vuln_api/README.md
@@ -0,0 +1,32 @@
+# vuln-api fixtures
+
+Committed JSON bodies matching the authoritative server serialization
+(vuln-api repo: `cve_worker/src/worker.js`). Deserialization tests live in
+`src/vuln_api/mod.rs`; full-HTTP-path contract tests in
+`tests/vuln_api_contract.rs`.
+
+| Fixture | Verdict |
+|---|---|
+| `check_clean.json` | known package, no advisories |
+| `check_vulnerable.json` | one advisory with `fixed_version` remediation |
+| `check_malware.json` | `MAL-*` advisory, no version range, no fix |
+| `check_unknown.json` | unknown package — `/check` answers 200 clean, not 404 |
+
+## Deterministic staging targets
+
+The staging worker (`https://cve-worker-staging.corgea.workers.dev`) serves
+stable verdicts for these targets; the `#[ignore]`d tests in
+`tests/vuln_api_contract.rs` assert them:
+
+| Target | Ecosystem | Verdict |
+|---|---|---|
+| `axios@0.21.0` | npm | vulnerable (CVE-2021-3749, fixed in 0.21.2) |
+| `minimist@0.0.8` | npm | vulnerable |
+| `node-fetch@2.6.0` | npm | vulnerable |
+| `mezzanine==6.0.0` | pypi | vulnerable (CVE-2025-29573) |
+
+Run the staging contract tests with:
+
+```sh
+cargo test --test vuln_api_contract -- --ignored
+```
diff --git a/tests/fixtures/vuln_api/check_clean.json b/tests/fixtures/vuln_api/check_clean.json
new file mode 100644
index 0000000..7a1d137
--- /dev/null
+++ b/tests/fixtures/vuln_api/check_clean.json
@@ -0,0 +1 @@
+{"ecosystem":"pypi","package_name":"requests","version":"2.31.0","is_vulnerable":false,"matches":[]}
diff --git a/tests/fixtures/vuln_api/check_malware.json b/tests/fixtures/vuln_api/check_malware.json
new file mode 100644
index 0000000..f353d36
--- /dev/null
+++ b/tests/fixtures/vuln_api/check_malware.json
@@ -0,0 +1,15 @@
+{
+  "ecosystem": "npm",
+  "package_name": "wozhendeshitule",
+  "version": "1.0.0",
+  "is_vulnerable": true,
+  "matches": [
+    {
+      "advisory_id": "MAL-2022-7232",
+      "severity_level": "critical",
+      "tier": 1,
+      "vulnerable_version_range": null,
+      "fixed_version": null
+    }
+  ]
+}
diff --git a/tests/fixtures/vuln_api/check_unknown.json b/tests/fixtures/vuln_api/check_unknown.json
new file mode 100644
index 0000000..9886df0
--- /dev/null
+++ b/tests/fixtures/vuln_api/check_unknown.json
@@ -0,0 +1 @@
+{"ecosystem":"pypi","package_name":"this-package-does-not-exist","version":"9.9.9","is_vulnerable":false,"matches":[]}
diff --git a/tests/fixtures/vuln_api/check_vulnerable.json b/tests/fixtures/vuln_api/check_vulnerable.json
new file mode 100644
index 0000000..e50112b
--- /dev/null
+++ b/tests/fixtures/vuln_api/check_vulnerable.json
@@ -0,0 +1,15 @@
+{
+  "ecosystem": "pypi",
+  "package_name": "django",
+  "version": "3.2.0",
+  "is_vulnerable": true,
+  "matches": [
+    {
+      "advisory_id": "GHSA-xxxx-yyyy-zzzz",
+      "severity_level": "high",
+      "tier": 1,
+      "vulnerable_version_range": ">=3.2,<3.2.5",
+      "fixed_version": "3.2.5"
+    }
+  ]
+}
diff --git a/tests/vuln_api_contract.rs b/tests/vuln_api_contract.rs
new file mode 100644
index 0000000..efa0a97
--- /dev/null
+++ b/tests/vuln_api_contract.rs
@@ -0,0 +1,172 @@
+//! Contract tests for the vuln-api client over the full HTTP path.
+//!
+//! Two backends, one contract:
+//!   * the in-process stub (hermetic, always on), serving the committed
+//!     fixture bodies so the stub can't drift from the real serialization;
+//!   * the staging worker (`#[ignore]`d — network), asserting the
+//!     deterministic targets documented in `tests/fixtures/vuln_api/README.md`.
+//!
+//! Run the staging half with:
+//!   cargo test --test vuln_api_contract -- --ignored
+
+mod common;
+
+use corgea::vuln_api::{check_package_version, http_client, Ecosystem, VulnCheckResponse};
+use corgea::vuln_api_stub::{key, spawn_with_statuses, vulnerable_body};
+use std::collections::HashMap;
+
+const STAGING_URL: &str = "https://cve-worker-staging.corgea.workers.dev";
+
+fn check(
+    base_url: &str,
+    ecosystem: Ecosystem,
+    name: &str,
+    version: &str,
+) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
+    let client = http_client().expect("client");
+    check_package_version(&client, base_url, ecosystem, name, version)
+}
+
+fn fixture_body(name: &str) -> String {
+    std::fs::read_to_string(common::fixture(&format!("vuln_api/{name}"))).expect("read fixture")
+}
+
+// ---- stub-backed (hermetic) ----
+
+#[test]
+fn stub_vulnerable_verdict_roundtrip() {
+    let stub = spawn_with_statuses(
+        HashMap::from([(
+            key("npm", "axios", "0.21.0"),
+            vulnerable_body("npm", "axios", "0.21.0", "CVE-2021-3749", Some("0.21.2")),
+        )]),
+        HashMap::new(),
+    );
+    let verdict = check(&stub.base_url, Ecosystem::Npm, "axios", "0.21.0").unwrap();
+    assert!(verdict.is_vulnerable);
+    assert_eq!(verdict.matches[0].advisory_id, "CVE-2021-3749");
+    assert_eq!(verdict.matches[0].fixed_version.as_deref(), Some("0.21.2"));
+}
+
+#[test]
+fn stub_unknown_package_is_clean() {
+    let stub = spawn_with_statuses(HashMap::new(), HashMap::new());
+    let verdict = check(&stub.base_url, Ecosystem::Npm, "no-such-package", "1.0.0").unwrap();
+    assert!(!verdict.is_vulnerable);
+    assert!(verdict.matches.is_empty());
+}
+
+#[test]
+fn stub_serves_committed_fixture_bodies() {
+    // The four committed fixtures, end to end through the client: the
+    // contract's serialization examples must survive the full HTTP path,
+    // identity guard included.
+    let stub = spawn_with_statuses(
+        HashMap::from([
+            (
+                key("pypi", "requests", "2.31.0"),
+                fixture_body("check_clean.json"),
+            ),
+            (
+                key("pypi", "django", "3.2.0"),
+                fixture_body("check_vulnerable.json"),
+            ),
+            (
+                key("npm", "wozhendeshitule", "1.0.0"),
+                fixture_body("check_malware.json"),
+            ),
+            (
+                key("pypi", "this-package-does-not-exist", "9.9.9"),
+                fixture_body("check_unknown.json"),
+            ),
+        ]),
+        HashMap::new(),
+    );
+
+    let clean = check(&stub.base_url, Ecosystem::Pypi, "requests", "2.31.0").unwrap();
+    assert!(!clean.is_vulnerable);
+
+    let vulnerable = check(&stub.base_url, Ecosystem::Pypi, "django", "3.2.0").unwrap();
+    assert!(vulnerable.is_vulnerable);
+    assert_eq!(
+        vulnerable.matches[0].fixed_version.as_deref(),
+        Some("3.2.5")
+    );
+
+    let malware = check(&stub.base_url, Ecosystem::Npm, "wozhendeshitule", "1.0.0").unwrap();
+    assert!(malware.is_vulnerable);
+    assert!(malware.matches[0].advisory_id.starts_with("MAL-"));
+    assert!(malware.matches[0].fixed_version.is_none());
+
+    let unknown = check(
+        &stub.base_url,
+        Ecosystem::Pypi,
+        "this-package-does-not-exist",
+        "9.9.9",
+    )
+    .unwrap();
+    assert!(!unknown.is_vulnerable);
+}
+
+#[test]
+fn stub_server_error_surfaces_as_unavailable() {
+    let stub = spawn_with_statuses(
+        HashMap::from([(key("npm", "flaky", "1.0.0"), "{}".to_string())]),
+        HashMap::from([(key("npm", "flaky", "1.0.0"), 503u16)]),
+    );
+    let err = check(&stub.base_url, Ecosystem::Npm, "flaky", "1.0.0").unwrap_err();
+    assert!(err.to_string().contains("unavailable (HTTP 503)"));
+}
+
+// ---- staging (network, deterministic targets) ----
+
+fn assert_staging_vulnerable(ecosystem: Ecosystem, name: &str, version: &str) {
+    let verdict = check(STAGING_URL, ecosystem, name, version)
+        .unwrap_or_else(|e| panic!("staging check {name}@{version} failed: {e}"));
+    assert!(
+        verdict.is_vulnerable,
+        "{name}@{version} should be vulnerable"
+    );
+    assert!(!verdict.matches.is_empty());
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_axios_0_21_0_is_vulnerable_with_remediation() {
+    let verdict = check(STAGING_URL, Ecosystem::Npm, "axios", "0.21.0").unwrap();
+    assert!(verdict.is_vulnerable);
+    // Remediation data: at least one advisory carries a fixed version.
+    assert!(verdict.matches.iter().any(|m| m.fixed_version.is_some()));
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_minimist_0_0_8_is_vulnerable() {
+    assert_staging_vulnerable(Ecosystem::Npm, "minimist", "0.0.8");
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_node_fetch_2_6_0_is_vulnerable() {
+    assert_staging_vulnerable(Ecosystem::Npm, "node-fetch", "2.6.0");
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_mezzanine_6_0_0_is_vulnerable() {
+    assert_staging_vulnerable(Ecosystem::Pypi, "mezzanine", "6.0.0");
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_unknown_package_is_clean() {
+    let verdict = check(
+        STAGING_URL,
+        Ecosystem::Npm,
+        "corgea-contract-test-nonexistent",
+        "1.0.0",
+    )
+    .unwrap();
+    assert!(!verdict.is_vulnerable);
+    assert!(verdict.matches.is_empty());
+}

From 0ae48f04d0638b29790256d6041b38bdb6b26a96 Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Fri, 12 Jun 2026 15:58:20 +0200
Subject: [PATCH 3/6] Phase 0 review fixes: pypi identity normalization,
 harness smoke test, staging CI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses Cursor review on #110.

- vuln_api identity guard now applies the ecosystem's canonical-name rule
  to the response package_name before comparing, not just
  eq_ignore_ascii_case. A response echoing the stored spelling
  (`flask_cors` for a `flask-cors` request — PEP 503-equivalent) no longer
  trips the guard and fails the gate closed for valid pypi packages with
  `_`/`.` in their names. New unit test covers it.
- tests/harness_smoke.rs exercises the GateHarness scaffold directly (fake
  package manager on PATH, registry stub, vuln-api stub) so the wiring
  can't silently regress before a later phase drives it end-to-end.
- .github/workflows/staging-contract.yml runs the #[ignore]d staging
  contract tests on a daily schedule (non-blocking) so endpoint/schema/seed
  drift is caught out-of-band instead of shipping undetected.
---
 .github/workflows/staging-contract.yml | 34 ++++++++++
 src/vuln_api/mod.rs                    | 35 ++++++++++-
 tests/harness_smoke.rs                 | 87 ++++++++++++++++++++++++++
 tests/vuln_api_contract.rs             |  5 ++
 4 files changed, 160 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/staging-contract.yml
 create mode 100644 tests/harness_smoke.rs

diff --git a/.github/workflows/staging-contract.yml b/.github/workflows/staging-contract.yml
new file mode 100644
index 0000000..7397075
--- /dev/null
+++ b/.github/workflows/staging-contract.yml
@@ -0,0 +1,34 @@
+name: Staging vuln-api contract
+
+# The deterministic staging-target contract tests are #[ignore]d so the
+# default `./harness ci` gate stays hermetic (no network). This scheduled,
+# non-blocking job runs them against the live staging worker so endpoint /
+# schema / seed drift is caught out-of-band instead of shipping undetected.
+# It does not gate PRs — failures here signal "the staging contract moved",
+# not "this PR is broken".
+
+on:
+  schedule:
+    # Daily at 07:00 UTC.
+    - cron: "0 7 * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  staging-contract:
+    name: vuln-api staging contract (non-blocking)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Run ignored staging contract tests
+        run: cargo test --test vuln_api_contract -- --ignored
diff --git a/src/vuln_api/mod.rs b/src/vuln_api/mod.rs
index 222567c..e8855b0 100644
--- a/src/vuln_api/mod.rs
+++ b/src/vuln_api/mod.rs
@@ -255,7 +255,16 @@ pub fn check_package_version(
         )
         .into());
     }
-    if !parsed.package_name.is_empty() && !parsed.package_name.eq_ignore_ascii_case(name) {
+    // Apply the ecosystem's canonical-name rule to BOTH sides before
+    // comparing: `name` is already normalized, and a response that echoes
+    // the registry/stored spelling (`flask_cors` for a `flask-cors` request,
+    // PEP 503-equivalent) must not be a hard failure — that would fail the
+    // gate closed for valid pypi packages with `_`/`.` in their names.
+    if !parsed.package_name.is_empty()
+        && !ecosystem
+            .normalize_name(&parsed.package_name)
+            .eq_ignore_ascii_case(name)
+    {
         return Err(format!(
             "vuln-api response package '{}' does not match request '{}'",
             parsed.package_name, name
@@ -318,6 +327,30 @@ mod tests {
         check_lodash(&stub)
     }
 
+    #[test]
+    fn pypi_response_alternate_spelling_passes_identity_guard() {
+        // The request normalizes `Flask_Cors` → `flask-cors`; a response that
+        // echoes the stored spelling `flask_cors` is PEP 503-equivalent and
+        // must NOT trip the identity guard (which would fail the gate closed
+        // for a valid package).
+        let key = vuln_api_stub::key("pypi", "flask-cors", "1.0.0");
+        let body = r#"{"ecosystem":"PyPI","package_name":"flask_cors","version":"1.0.0","is_vulnerable":false,"matches":[]}"#;
+        let stub = vuln_api_stub::spawn_with_statuses(
+            HashMap::from([(key, body.to_string())]),
+            HashMap::new(),
+        );
+        let client = http_client().expect("test client");
+        let resp = check_package_version(
+            &client,
+            &stub.base_url,
+            Ecosystem::Pypi,
+            "Flask_Cors",
+            "1.0.0",
+        )
+        .expect("alternate pypi spelling must pass the identity guard");
+        assert!(!resp.is_vulnerable);
+    }
+
     #[test]
     fn check_sends_no_auth_headers() {
         // The host is user-configurable; the client must never attach a
diff --git a/tests/harness_smoke.rs b/tests/harness_smoke.rs
new file mode 100644
index 0000000..d2a47c2
--- /dev/null
+++ b/tests/harness_smoke.rs
@@ -0,0 +1,87 @@
+//! Phase 0 smoke test for the `GateHarness` scaffold.
+//!
+//! The harness is a Phase 0 exit criterion ("another phase can write an
+//! integration test in under 20 lines"), but Phase 0 ships no install
+//! command to drive it through. This test exercises the three wiring points
+//! directly — the fake package manager on a private PATH, the registry stub,
+//! and the vuln-api stub — so the scaffold can't silently regress and leave
+//! the next phase failing for harness reasons rather than gate logic.
+
+#![cfg(unix)]
+
+mod common;
+
+use common::GateHarness;
+use std::collections::HashMap;
+use std::ffi::OsStr;
+use std::io::{Read, Write};
+
+fn env_of(cmd: &std::process::Command, key: &str) -> Option<String> {
+    cmd.get_envs()
+        .find(|(k, _)| *k == OsStr::new(key))
+        .and_then(|(_, v)| v)
+        .map(|v| v.to_string_lossy().into_owned())
+}
+
+/// Raw one-shot HTTP GET against a `127.0.0.1` stub (responses carry
+/// `Connection: close`, so `read_to_string` terminates).
+fn http_get(base: &str, path: &str) -> String {
+    let addr = base.trim_start_matches("http://");
+    let mut s = std::net::TcpStream::connect(addr).expect("connect stub");
+    write!(
+        s,
+        "GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n"
+    )
+    .unwrap();
+    let mut buf = String::new();
+    s.read_to_string(&mut buf).unwrap();
+    buf
+}
+
+#[test]
+fn gate_harness_wires_stubs_and_fake_manager() {
+    let checks = HashMap::from([(
+        common::key("pypi", "evil", "1.0.0"),
+        common::vulnerable_body("pypi", "evil", "1.0.0", "MAL-SMOKE-0001", None),
+    )]);
+    let h = GateHarness::new()
+        .fake_recorder("pip", 0)
+        .wildcard_pypi_registry()
+        .vuln_checks(checks)
+        .build();
+
+    // 1. vuln-api stub: the scripted vulnerable verdict is served at the URL
+    //    the harness exported to the corgea invocation.
+    let vuln_url = env_of(&h.cmd, "CORGEA_VULN_API_URL").expect("CORGEA_VULN_API_URL wired");
+    let client = corgea::vuln_api::http_client().expect("vuln-api client");
+    let verdict = corgea::vuln_api::check_package_version(
+        &client,
+        &vuln_url,
+        corgea::vuln_api::Ecosystem::Pypi,
+        "evil",
+        "1.0.0",
+    )
+    .expect("vuln-api stub must be reachable");
+    assert!(
+        verdict.is_vulnerable && verdict.matches[0].advisory_id == "MAL-SMOKE-0001",
+        "the scripted vulnerable verdict must come back through the wired stub"
+    );
+
+    // 2. registry stub: the wildcard pypi stub answers for any package name.
+    let registry = env_of(&h.cmd, "CORGEA_PYPI_REGISTRY").expect("CORGEA_PYPI_REGISTRY wired");
+    let body = http_get(&registry, "/pypi/anything/json");
+    assert!(
+        body.starts_with("HTTP/1.1 200") && body.contains("\"info\""),
+        "registry stub must serve pypi release json: {body}"
+    );
+
+    // 3. fake package manager: an executable recorder is on the private PATH
+    //    the harness exported (so a later phase's install actually finds it).
+    let path = env_of(&h.cmd, "PATH").expect("PATH wired");
+    let pip = std::path::Path::new(&path).join("pip");
+    assert!(
+        pip.is_file(),
+        "the fake pip recorder must exist on the harness PATH: {}",
+        pip.display()
+    );
+}
diff --git a/tests/vuln_api_contract.rs b/tests/vuln_api_contract.rs
index efa0a97..fca3623 100644
--- a/tests/vuln_api_contract.rs
+++ b/tests/vuln_api_contract.rs
@@ -8,6 +8,11 @@
 //!
 //! Run the staging half with:
 //!   cargo test --test vuln_api_contract -- --ignored
+//!
+//! The hermetic stub backend runs in the default `./harness ci` gate. The
+//! `#[ignore]`d staging backend runs out-of-band on a schedule (non-blocking)
+//! via `.github/workflows/staging-contract.yml`, so endpoint/schema/seed
+//! drift in the live worker is caught instead of shipping undetected.
 
 mod common;
 

From 86fb8d2ea7f002b59fa8ea3f7553006b9363d3f3 Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Fri, 12 Jun 2026 18:40:22 +0200
Subject: [PATCH 4/6] Fix flaky port_is_available test: serialize
 ephemeral-port tests

cargo test runs the module's tests on parallel threads. Five of them bind
ephemeral ports, and between port_is_available_reflects_current_port_usage's
drop(listener) and its re-check, a concurrent :0 bind could be handed the
just-freed port, flipping the second assert to false.

Add a module-level PORT_TEST_LOCK that all five port-binding tests acquire.
The async test scopes the guard to the synchronous reserve so no lock is held
across .await (keeps clippy::await_holding_lock clean).
---
 src/authorize.rs | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/authorize.rs b/src/authorize.rs
index 7271cf9..6535847 100644
--- a/src/authorize.rs
+++ b/src/authorize.rs
@@ -539,6 +539,18 @@ mod tests {
     use tokio::runtime::Runtime;
     use tokio::time::{timeout, Duration};
 
+    // Serializes tests that bind ephemeral ports. `cargo test` runs the module's
+    // tests on parallel threads; without this lock one test's just-freed port can
+    // be handed to another between a `drop` and a re-check, which made
+    // `port_is_available_reflects_current_port_usage` flake.
+    static PORT_TEST_LOCK: Mutex<()> = Mutex::new(());
+
+    fn lock_ports() -> std::sync::MutexGuard<'static, ()> {
+        PORT_TEST_LOCK
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
     fn reserve_ephemeral_port() -> u16 {
         let listener = StdTcpListener::bind("127.0.0.1:0").expect("failed to bind ephemeral port");
         listener
@@ -624,6 +636,7 @@ mod tests {
 
     #[test]
     fn port_is_available_reflects_current_port_usage() {
+        let _guard = lock_ports();
         let listener = StdTcpListener::bind("127.0.0.1:0").expect("failed to bind ephemeral port");
         let port = listener
             .local_addr()
@@ -637,6 +650,7 @@ mod tests {
 
     #[test]
     fn find_available_port_skips_ports_that_are_in_use() {
+        let _guard = lock_ports();
         let listener = StdTcpListener::bind("127.0.0.1:0").expect("failed to bind ephemeral port");
         let occupied_port = listener
             .local_addr()
@@ -650,7 +664,12 @@ mod tests {
 
     #[tokio::test]
     async fn start_callback_server_returns_without_waiting_for_second_connection() {
-        let port = reserve_ephemeral_port();
+        // Reserve under the lock so the :0 probe can't race the sync port tests;
+        // the guard drops before the await, so no lock is held across `.await`.
+        let port = {
+            let _guard = lock_ports();
+            reserve_ephemeral_port()
+        };
         let auth_code = Arc::new(Mutex::new(Some("test-code".to_string())));
 
         let returned_code = timeout(
@@ -666,6 +685,7 @@ mod tests {
 
     #[test]
     fn start_callback_server_returns_bind_error_if_port_is_occupied() {
+        let _guard = lock_ports();
         let listener = StdTcpListener::bind("127.0.0.1:0").expect("failed to bind ephemeral port");
         let occupied_port = listener
             .local_addr()
@@ -684,6 +704,7 @@ mod tests {
 
     #[test]
     fn callback_server_serves_waiting_error_and_success_pages_then_returns_code() {
+        let _guard = lock_ports();
         let port = reserve_ephemeral_port();
         let auth_code = Arc::new(Mutex::new(None::<String>));
         let result_rx = spawn_callback_server(port, auth_code);

From caac2d80471ba569cb1d546c7aba992a8e89805f Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Fri, 12 Jun 2026 19:51:02 +0200
Subject: [PATCH 5/6] Phase 0 second-round review fixes: wire-name
 normalization, auth-invariant docs, harness opt-out

- pypi wire names now use the server's rule (lowercase + trim,
  worker.js normalizePackageName), NOT PEP 503: collapsing
  zope.interface to zope-interface missed the stored advisory row and
  read vulnerable dotted/underscored packages as clean. PEP 503 remains
  the identity-comparison rule (Ecosystem::request_name vs
  normalize_name), and the stub's key() now mirrors the server so the
  divergence can't be masked in tests again.
- Module/auth docs no longer claim lookups are permanently
  unauthenticated: production /check requires a Corgea token (staging
  runs VULN_API_REQUIRE_AUTH=false); token wiring lands with
  authenticated mode. Test renamed public_check_sends_no_auth_headers.
- GateHarness::without_vuln_api() opt-out for no-endpoint tests.
- utils/api.rs get_source() delegates to the cached vuln_api::source().
---
 src/utils/api.rs         |   3 +-
 src/vuln_api/mod.rs      | 101 +++++++++++++++++++++++++++++----------
 src/vuln_api_stub/mod.rs |  40 +++++++++++-----
 tests/common/mod.rs      |  12 +++++
 4 files changed, 117 insertions(+), 39 deletions(-)

diff --git a/src/utils/api.rs b/src/utils/api.rs
index 9b9a445..cd401e1 100644
--- a/src/utils/api.rs
+++ b/src/utils/api.rs
@@ -19,7 +19,8 @@ const CHUNK_SIZE: usize = 50 * 1024 * 1024; // 50 MB
 const API_BASE: &str = "/api/v1";
 
 fn get_source() -> String {
-    std::env::var("CORGEA_SOURCE").unwrap_or_else(|_| "cli".to_string())
+    // One definition of the CORGEA-SOURCE value (cached there).
+    corgea::vuln_api::source()
 }
 
 fn is_jwt(token: &str) -> bool {
diff --git a/src/vuln_api/mod.rs b/src/vuln_api/mod.rs
index e8855b0..fd24c6f 100644
--- a/src/vuln_api/mod.rs
+++ b/src/vuln_api/mod.rs
@@ -7,8 +7,11 @@
 //!   * the shared client's `check_for_warnings` exits the process on
 //!     HTTP 410, which is wrong for per-dep CVE lookups.
 //!
-//! Lookups are public and unauthenticated: no Corgea credential is ever
-//! attached, so a user-configured host can never see one.
+//! This phase attaches no Corgea credential: the staging deployment
+//! (`VULN_API_REQUIRE_AUTH=false`) accepts anonymous checks. The
+//! production /check route requires a Corgea token — wired in with
+//! authenticated mode, and never sent to a user-configured host
+//! without explicit opt-in.
 
 use serde::Deserialize;
 use std::sync::OnceLock;
@@ -41,15 +44,27 @@ impl Ecosystem {
         }
     }
 
-    /// Canonical package name for requests and comparisons: PEP 503 for
-    /// pypi (shared with `deps`), verbatim for npm (names are
-    /// case-sensitive). The one definition of the per-ecosystem rule.
+    /// Canonical package name for IDENTITY COMPARISONS: PEP 503 for pypi
+    /// (shared with `deps`), verbatim for npm (names are case-sensitive).
+    /// Not the wire spelling — see `request_name`.
     pub fn normalize_name(self, name: &str) -> String {
         match self {
             Ecosystem::Npm => name.to_string(),
             Ecosystem::Pypi => crate::deps::ecosystems::pypi::normalize_pypi_name(name),
         }
     }
+
+    /// Wire spelling for the request path. The server normalizes lookups
+    /// with lowercase + trim only (worker.js `normalizePackageName`), NOT
+    /// PEP 503 — collapsing `zope.interface` to `zope-interface` here
+    /// would miss the stored advisory row and read a vulnerable package
+    /// as clean. Match the server's rule exactly.
+    pub fn request_name(self, name: &str) -> String {
+        match self {
+            Ecosystem::Npm => name.to_string(),
+            Ecosystem::Pypi => name.trim().to_lowercase(),
+        }
+    }
 }
 
 #[derive(Debug, Clone, Deserialize)]
@@ -124,7 +139,9 @@ pub fn source() -> String {
 }
 
 /// Build a JSON GET with the standard `Accept` / `CORGEA-SOURCE` headers.
-/// No auth header: lookups are public, and the host may be user-configured.
+/// No auth header in this phase (staging accepts anonymous checks); the
+/// token attach lands with authenticated mode, and the host may be
+/// user-configured — so nothing credential-shaped goes here by default.
 fn build_json_get(
     client: &reqwest::blocking::Client,
     url: &str,
@@ -187,11 +204,14 @@ pub fn check_package_version(
     version: &str,
 ) -> Result<VulnCheckResponse, Box<dyn std::error::Error>> {
     let base = validated_base(base_url)?;
-    // vuln-api advisories are keyed by canonical names; an alternate
-    // spelling (PEP 503: `Flask_Cors` ≡ `flask-cors`) would miss and read
-    // as clean. The client owns request-time normalization so no caller
-    // can forget it.
-    let name = &ecosystem.normalize_name(name);
+    // The server keys advisories by lowercase+trim of the canonical
+    // registry spelling and normalizes lookups the same way — it does
+    // NOT apply PEP 503 (worker.js `normalizePackageName`). Sending a
+    // PEP 503-collapsed name would miss dotted/underscored canonical
+    // names (`zope.interface`) and read them as clean. The client owns
+    // request-time normalization so no caller can forget it; PEP 503 is
+    // reserved for the identity comparison below.
+    let name = &ecosystem.request_name(name);
     let encoded_name = encode_package_name(ecosystem, name);
     let encoded_version = urlencoding::encode(version);
     let url = format!(
@@ -255,15 +275,16 @@ pub fn check_package_version(
         )
         .into());
     }
-    // Apply the ecosystem's canonical-name rule to BOTH sides before
-    // comparing: `name` is already normalized, and a response that echoes
-    // the registry/stored spelling (`flask_cors` for a `flask-cors` request,
-    // PEP 503-equivalent) must not be a hard failure — that would fail the
-    // gate closed for valid pypi packages with `_`/`.` in their names.
+    // Apply the ecosystem's canonical-name rule (PEP 503) to BOTH sides
+    // before comparing: `name` carries the wire spelling (dots/underscores
+    // preserved), and a response that echoes the registry/stored spelling
+    // (`flask_cors` for a `flask-cors` request, PEP 503-equivalent) must
+    // not be a hard failure — that would fail the gate closed for valid
+    // pypi packages with `_`/`.` in their names.
     if !parsed.package_name.is_empty()
         && !ecosystem
             .normalize_name(&parsed.package_name)
-            .eq_ignore_ascii_case(name)
+            .eq_ignore_ascii_case(&ecosystem.normalize_name(name))
     {
         return Err(format!(
             "vuln-api response package '{}' does not match request '{}'",
@@ -329,12 +350,12 @@ mod tests {
 
     #[test]
     fn pypi_response_alternate_spelling_passes_identity_guard() {
-        // The request normalizes `Flask_Cors` → `flask-cors`; a response that
-        // echoes the stored spelling `flask_cors` is PEP 503-equivalent and
-        // must NOT trip the identity guard (which would fail the gate closed
-        // for a valid package).
-        let key = vuln_api_stub::key("pypi", "flask-cors", "1.0.0");
-        let body = r#"{"ecosystem":"PyPI","package_name":"flask_cors","version":"1.0.0","is_vulnerable":false,"matches":[]}"#;
+        // The wire name for `Flask_Cors` is `flask_cors` (lowercase + trim,
+        // the server's rule); a response that echoes a PEP 503-equivalent
+        // spelling (`Flask-Cors`) must NOT trip the identity guard (which
+        // would fail the gate closed for a valid package).
+        let key = vuln_api_stub::key("pypi", "flask_cors", "1.0.0");
+        let body = r#"{"ecosystem":"PyPI","package_name":"Flask-Cors","version":"1.0.0","is_vulnerable":false,"matches":[]}"#;
         let stub = vuln_api_stub::spawn_with_statuses(
             HashMap::from([(key, body.to_string())]),
             HashMap::new(),
@@ -352,9 +373,37 @@ mod tests {
     }
 
     #[test]
-    fn check_sends_no_auth_headers() {
-        // The host is user-configurable; the client must never attach a
-        // Corgea credential, cookie, or token header.
+    fn pypi_wire_name_is_lowercased_not_pep503_collapsed() {
+        // The server keys advisories lowercase+trim, NOT PEP 503: collapsing
+        // `Zope.Interface` to `zope-interface` on the wire would miss the
+        // stored `zope.interface` row and read a vulnerable package as
+        // clean. The request path must carry the dot.
+        let (base_url, requests) = spawn_capturing_vuln_api_stub();
+        let client = http_client().expect("test client");
+        check_package_version(
+            &client,
+            &base_url,
+            Ecosystem::Pypi,
+            "Zope.Interface",
+            "5.0.0",
+        )
+        .expect("captured request should succeed");
+        let requests = requests.lock().unwrap();
+        let path = requests[0].lines().next().unwrap_or_default().to_string();
+        assert!(
+            path.contains("/pypi/zope.interface/"),
+            "wire name must be lowercased with separators preserved; got: {path}"
+        );
+        assert!(
+            !path.contains("zope-interface"),
+            "wire name must not be PEP 503-collapsed; got: {path}"
+        );
+    }
+
+    #[test]
+    fn public_check_sends_no_auth_headers() {
+        // The host is user-configurable; without a caller-owned token the
+        // client must never attach a Corgea credential or cookie.
         let (base_url, requests) = spawn_capturing_vuln_api_stub();
         let client = http_client().expect("test client");
         check_package_version(&client, &base_url, Ecosystem::Npm, "lodash", "4.17.20")
diff --git a/src/vuln_api_stub/mod.rs b/src/vuln_api_stub/mod.rs
index 6f07a3d..112f2fe 100644
--- a/src/vuln_api_stub/mod.rs
+++ b/src/vuln_api_stub/mod.rs
@@ -6,15 +6,12 @@ use std::thread;
 pub type PackageKey = (String, String, String);
 
 /// `(ecosystem, name, version)` key for the stub's route tables. Applies the
-/// client's canonical-name rule (`Ecosystem::normalize_name`) on both the
-/// fixture and lookup sides, so a fixture keyed under an alternate pypi
-/// spelling can't silently miss and read as clean.
+/// REAL server's normalization (worker.js `normalizePackageName`: lowercase
+/// + trim, NOT PEP 503) on both the fixture and lookup sides. The stub must
+/// miss exactly when production would miss — a looser rule here would mask
+/// client/server normalization divergence in tests.
 pub fn key(eco: &str, name: &str, ver: &str) -> PackageKey {
-    let name = match eco {
-        "pypi" => crate::vuln_api::Ecosystem::Pypi.normalize_name(name),
-        _ => name.to_string(),
-    };
-    (eco.to_string(), name, ver.to_string())
+    (eco.to_string(), name.trim().to_lowercase(), ver.to_string())
 }
 
 /// Single-match vulnerable verdict body; `fixed: None` renders
@@ -255,17 +252,36 @@ mod tests {
     }
 
     #[test]
-    fn pypi_keys_normalize_alternate_spellings() {
-        // A fixture keyed `Flask_Cors` must serve a request for `flask-cors`.
+    fn pypi_keys_lowercase_like_the_server() {
+        // A fixture keyed `Flask_Cors` must serve a request for `flask_cors`:
+        // the server's rule is lowercase + trim (worker.js).
         let checks = HashMap::from([(
             key("pypi", "Flask_Cors", "4.0.0"),
-            vulnerable_body("pypi", "flask-cors", "4.0.0", "GHSA-test", None),
+            vulnerable_body("pypi", "flask_cors", "4.0.0", "GHSA-test", None),
         )]);
         let stub = spawn_with_statuses(checks, HashMap::new());
         let resp = get(
             &stub.base_url,
-            "/v1/packages/pypi/flask-cors/versions/4.0.0/check",
+            "/v1/packages/pypi/flask_cors/versions/4.0.0/check",
         );
         assert!(resp.contains(r#""is_vulnerable":true"#), "resp: {resp}");
     }
+
+    #[test]
+    fn pypi_keys_do_not_collapse_separators_like_the_server() {
+        // The real server does NOT apply PEP 503: a row stored under
+        // `flask_cors` does not answer a lookup for `flask-cors`. The stub
+        // must reproduce that miss (synthesized clean), or tests would hide
+        // exactly the client/server divergence they exist to catch.
+        let checks = HashMap::from([(
+            key("pypi", "flask_cors", "4.0.0"),
+            vulnerable_body("pypi", "flask_cors", "4.0.0", "GHSA-test", None),
+        )]);
+        let stub = spawn_with_statuses(checks, HashMap::new());
+        let resp = get(
+            &stub.base_url,
+            "/v1/packages/pypi/flask-cors/versions/4.0.0/check",
+        );
+        assert!(resp.contains(r#""is_vulnerable":false"#), "resp: {resp}");
+    }
 }
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
index de0b8c1..f2a1a8e 100644
--- a/tests/common/mod.rs
+++ b/tests/common/mod.rs
@@ -168,6 +168,7 @@ pub struct GateHarness {
     project: Option<TempDir>,
     checks: HashMap<PackageKey, String>,
     statuses: HashMap<PackageKey, u16>,
+    vuln_api: bool,
     _home: TempDir,
     _bin: TempDir,
     _vuln_stub: Option<corgea::vuln_api_stub::VulnApiStub>,
@@ -187,6 +188,7 @@ impl GateHarness {
             project: None,
             checks: HashMap::new(),
             statuses: HashMap::new(),
+            vuln_api: true,
             _home: home,
             _bin: bin,
             _vuln_stub: None,
@@ -258,7 +260,17 @@ impl GateHarness {
         self
     }
 
+    /// Skip the vuln-api stub: `CORGEA_VULN_API_URL` stays unset so tests
+    /// can exercise the no-endpoint / unreachable-endpoint behavior.
+    pub fn without_vuln_api(mut self) -> Self {
+        self.vuln_api = false;
+        self
+    }
+
     pub fn build(mut self) -> Self {
+        if !self.vuln_api {
+            return self;
+        }
         let stub = corgea::vuln_api_stub::spawn_with_statuses(
             std::mem::take(&mut self.checks),
             std::mem::take(&mut self.statuses),

From 4bf25dd954a8d656c05944c2d05bfcd4b76030a8 Mon Sep 17 00:00:00 2001
From: juangaitanv <juan@corgea.com>
Date: Mon, 15 Jun 2026 10:48:12 +0200
Subject: [PATCH 6/6] Phase 0 review fixes: symmetric verdict guard, tier
 tolerance, npm encoding, clippy --all-targets

- Reject contradictory verdicts in both directions (is_vulnerable must agree
  with matches presence); false+non-empty was the dangerous false-negative.
- VulnMatch.tier: u8 -> Option<u8> so a null/missing tier no longer fails the
  whole response (server emits row.tier unclamped on /check).
- encode_npm_name percent-encodes every component (scoped + unscoped); output
  is identical for valid names, robust against reserved chars (matches pypi).
- Correct two factually-wrong comments (npm casing; 'staging spells PyPI')
  against the real server (worker.js echoes ecosystem/name/version verbatim).
- source() -> &'static str and validated_base() -> &str: drop per-request
  clone / per-call alloc on the per-package hot path.
- Harness strict clippy now --all-targets (lints tests + the test-stub module);
  cleared the two doc_lazy_continuation warnings it surfaced.
---
 harness                  |  6 ++--
 src/utils/api.rs         |  2 +-
 src/vuln_api/mod.rs      | 65 ++++++++++++++++++++++++----------------
 src/vuln_api_stub/mod.rs |  6 ++--
 4 files changed, 47 insertions(+), 32 deletions(-)

diff --git a/harness b/harness
index 84b5076..ce9e7c1 100755
--- a/harness
+++ b/harness
@@ -268,7 +268,7 @@ cmd_pre_commit() {
     printf "\n%s[pre-commit]%s\n\n" "$BLUE" "$RESET"
     # Check-only: never rewrite the working tree behind the commit.
     # Mirrors the CI gate so anything that passes here passes there.
-    run "Clippy (strict)" 0 -- cargo clippy -- -D warnings
+    run "Clippy (strict)" 0 -- cargo clippy --all-targets -- -D warnings
     run "Format check" 0 -- cargo fmt --check
     cmd_test
 }
@@ -282,7 +282,7 @@ cmd_check() {
     [ $? -eq 0 ] && passed=$(( passed + 1 )) || failed=$(( failed + 1 ))
     run "Format" 1 -- cargo fmt
     [ $? -eq 0 ] && passed=$(( passed + 1 )) || failed=$(( failed + 1 ))
-    run "Clippy (strict)" 1 -- cargo clippy -- -D warnings
+    run "Clippy (strict)" 1 -- cargo clippy --all-targets -- -D warnings
     [ $? -eq 0 ] && passed=$(( passed + 1 )) || failed=$(( failed + 1 ))
     run_with_summary "Tests" 1 -- cargo test
     [ $? -eq 0 ] && passed=$(( passed + 1 )) || failed=$(( failed + 1 ))
@@ -304,7 +304,7 @@ cmd_check() {
 
 cmd_ci() {
     printf "\n%s[ci]%s\n\n" "$BLUE" "$RESET"
-    run "Clippy (strict)" 0 -- cargo clippy -- -D warnings
+    run "Clippy (strict)" 0 -- cargo clippy --all-targets -- -D warnings
     run "Format check" 0 -- cargo fmt --check
     _cmd_audit_inner 1
     if ! cargo llvm-cov --version >/dev/null 2>&1; then
diff --git a/src/utils/api.rs b/src/utils/api.rs
index cd401e1..23e53ae 100644
--- a/src/utils/api.rs
+++ b/src/utils/api.rs
@@ -18,7 +18,7 @@ use std::path::Path;
 const CHUNK_SIZE: usize = 50 * 1024 * 1024; // 50 MB
 const API_BASE: &str = "/api/v1";
 
-fn get_source() -> String {
+fn get_source() -> &'static str {
     // One definition of the CORGEA-SOURCE value (cached there).
     corgea::vuln_api::source()
 }
diff --git a/src/vuln_api/mod.rs b/src/vuln_api/mod.rs
index fd24c6f..c92f7df 100644
--- a/src/vuln_api/mod.rs
+++ b/src/vuln_api/mod.rs
@@ -45,8 +45,10 @@ impl Ecosystem {
     }
 
     /// Canonical package name for IDENTITY COMPARISONS: PEP 503 for pypi
-    /// (shared with `deps`), verbatim for npm (names are case-sensitive).
-    /// Not the wire spelling — see `request_name`.
+    /// (shared with `deps`), verbatim for npm. The server lowercases every
+    /// ecosystem for lookup (worker.js `normalizePackageName`) and the
+    /// identity check below compares case-insensitively, so npm casing is
+    /// not load-bearing. Not the wire spelling — see `request_name`.
     pub fn normalize_name(self, name: &str) -> String {
         match self {
             Ecosystem::Npm => name.to_string(),
@@ -80,7 +82,7 @@ pub struct VulnCheckResponse {
 pub struct VulnMatch {
     pub advisory_id: String,
     pub severity_level: String,
-    pub tier: u8,
+    pub tier: Option<u8>,
     pub vulnerable_version_range: Option<String>,
     pub fixed_version: Option<String>,
 }
@@ -108,14 +110,20 @@ pub fn http_client() -> Result<reqwest::blocking::Client, String> {
 }
 
 /// URL-encode an npm package name for a URL path segment. Scoped names
-/// contain `@` and `/`; the latter must be encoded as `%2f`.
+/// (`@scope/pkg`) keep the readable `@…%2f…` shape, but every component is
+/// percent-encoded so a name carrying other reserved characters can't break
+/// out of its path segment (pypi already encodes the whole segment).
 pub(crate) fn encode_npm_name(name: &str) -> String {
     if let Some(stripped) = name.strip_prefix('@') {
         if let Some((scope, pkg)) = stripped.split_once('/') {
-            return format!("@{}%2f{}", scope, pkg);
+            return format!(
+                "@{}%2f{}",
+                urlencoding::encode(scope),
+                urlencoding::encode(pkg)
+            );
         }
     }
-    name.to_string()
+    urlencoding::encode(name).into_owned()
 }
 
 /// Encode package name for the vuln-api path segment.
@@ -128,14 +136,14 @@ fn encode_package_name(ecosystem: Ecosystem, name: &str) -> String {
 }
 
 /// Value for the `CORGEA-SOURCE` header: the `CORGEA_SOURCE` env override,
-/// otherwise `cli`. Read once and cached — it's attached per request from
-/// concurrent pool workers, and `std::env::var` takes the process-global
-/// env lock.
-pub fn source() -> String {
+/// otherwise `cli`. Read once and cached, then borrowed (no per-request
+/// clone) — it's attached per request from concurrent pool workers, and
+/// `std::env::var` takes the process-global env lock.
+pub fn source() -> &'static str {
     static SOURCE: OnceLock<String> = OnceLock::new();
     SOURCE
         .get_or_init(|| std::env::var("CORGEA_SOURCE").unwrap_or_else(|_| "cli".to_string()))
-        .clone()
+        .as_str()
 }
 
 /// Build a JSON GET with the standard `Accept` / `CORGEA-SOURCE` headers.
@@ -155,8 +163,8 @@ fn build_json_get(
 /// Validate the per-call preconditions shared by every vuln-api request:
 /// a non-empty (trailing-slash-normalized) base URL. Returns the normalized
 /// base so callers don't re-derive it.
-fn validated_base(base_url: &str) -> Result<String, Box<dyn std::error::Error>> {
-    let base = base_url.trim_end_matches('/').to_string();
+fn validated_base(base_url: &str) -> Result<&str, Box<dyn std::error::Error>> {
+    let base = base_url.trim_end_matches('/');
     if base.is_empty() {
         return Err("vuln-api base URL is empty".into());
     }
@@ -260,9 +268,12 @@ pub fn check_package_version(
     })?;
 
     // Confused-deputy guard: refuse to attribute advisories to a different
-    // (name, version, ecosystem) than what we asked about. The server is
-    // allowed to be silent on identity, but if it answers, it must match.
-    // Comparisons are case-insensitive: staging spells pypi "PyPI".
+    // (name, version, ecosystem) than what we asked about. The current
+    // server echoes ecosystem/name/version verbatim from the request path
+    // (worker.js `packageVersionCheckCliHandler`), so this can only fire on
+    // a tampering or misbehaving intermediary — defense in depth, not a live
+    // server contract. Comparisons stay case-insensitive to tolerate a
+    // future server that echoes a stored spelling/casing instead.
     if !parsed.ecosystem.is_empty()
         && !parsed
             .ecosystem
@@ -300,13 +311,17 @@ pub fn check_package_version(
         .into());
     }
 
-    // is_vulnerable=true with no matches is contradictory — treat as an
-    // error so the caller can surface it rather than silently demoting
-    // the dep to "clean".
-    if parsed.is_vulnerable && parsed.matches.is_empty() {
-        return Err(
-            "vuln-api reported is_vulnerable=true with no matches; refusing to interpret".into(),
-        );
+    // `is_vulnerable` must agree with the presence of matches in BOTH
+    // directions. true+empty is a contradictory verdict; false+non-empty is
+    // the dangerous one — a caller keying "clean" off `is_vulnerable` would
+    // silently drop real advisories. Refuse either rather than guess.
+    if parsed.is_vulnerable == parsed.matches.is_empty() {
+        return Err(format!(
+            "vuln-api verdict is contradictory (is_vulnerable={}, matches={}); refusing to interpret",
+            parsed.is_vulnerable,
+            parsed.matches.len()
+        )
+        .into());
     }
 
     Ok(parsed)
@@ -567,7 +582,7 @@ mod tests {
         assert!(parsed.is_vulnerable);
         assert_eq!(parsed.matches.len(), 1);
         assert_eq!(parsed.matches[0].advisory_id, "GHSA-xxxx-yyyy-zzzz");
-        assert_eq!(parsed.matches[0].tier, 1);
+        assert_eq!(parsed.matches[0].tier, Some(1));
     }
 
     #[test]
@@ -620,7 +635,7 @@ mod tests {
         let m = &parsed.matches[0];
         assert_eq!(m.advisory_id, "GHSA-xxxx-yyyy-zzzz");
         assert_eq!(m.severity_level, "high");
-        assert_eq!(m.tier, 1);
+        assert_eq!(m.tier, Some(1));
         assert_eq!(m.vulnerable_version_range.as_deref(), Some(">=3.2,<3.2.5"));
         assert_eq!(m.fixed_version.as_deref(), Some("3.2.5"));
     }
diff --git a/src/vuln_api_stub/mod.rs b/src/vuln_api_stub/mod.rs
index 112f2fe..5e51880 100644
--- a/src/vuln_api_stub/mod.rs
+++ b/src/vuln_api_stub/mod.rs
@@ -7,9 +7,9 @@ pub type PackageKey = (String, String, String);
 
 /// `(ecosystem, name, version)` key for the stub's route tables. Applies the
 /// REAL server's normalization (worker.js `normalizePackageName`: lowercase
-/// + trim, NOT PEP 503) on both the fixture and lookup sides. The stub must
-/// miss exactly when production would miss — a looser rule here would mask
-/// client/server normalization divergence in tests.
+/// and trim, NOT PEP 503) on both the fixture and lookup sides. The stub
+/// must miss exactly when production would miss — a looser rule here would
+/// mask client/server normalization divergence in tests.
 pub fn key(eco: &str, name: &str, ver: &str) -> PackageKey {
     (eco.to_string(), name.trim().to_lowercase(), ver.to_string())
 }