Install gate, Phase 0: vuln-api contract + test harness

.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

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"

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);

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() {

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;

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 {