cleanlib_client/

customer_state.rs

//! CLEANLIB-178 — canonical customer-facing state taxonomy (Rust surfaces).
//!
//! Single source of truth for the **8 customer states** that the malicious-vs-
//! vulnerable cluster (CLEANLIB-176 wire-shape + 177 policy overlay + 178
//! aesthetic) surfaces. The design contract lives at
//! `decisions/2026-06-12-cleanlib-178-state-aesthetic-mapping.md`; this module
//! is its executable form for the Rust render surfaces — `cleanlib-cli`,
//! `cleanlib-lsp` (CLEANLIB-209), and any consumer of `cleanlib-client`. The
//! TS extension / Python MCP / JS+Go+Py SDKs mirror this table in their own
//! languages, each with a contract test asserting the same wire→state map
//! (anti-drift, sister of the silent-schema-drift discipline).
//!
//! ## Why this lives in `cleanlib-client`, not `cleanlib-core`
//!
//! `cleanlib-core` is `publish = false`; the customer-state taxonomy is a
//! *presentation* concern consumed only by published render surfaces (the App
//! emits the wire `source`; it never renders a customer state). Keying on the
//! wire string (`Verdict.source: String`) — rather than `cleanlib-core`'s
//! `VerdictSource` enum — keeps this crate publishable to crates.io and avoids
//! a render-side dependency on the service-internal core crate.
//!
//! ## Design rules baked in (§0 of the spec — non-negotiable)
//!
//! 1. **Customer-language only** — wire/engine codenames never appear in
//!    `label()` / `copy()`.
//! 2. **Soft severity tokens** (dark-theme-safe); brand cyan `#50C0E0` is
//!    reserved for CLEAN.
//! 3. **Three derive tiers** (block / warn / clean) → exit codes (1 / 2 / 0).
//!
//! ## Derive-once + fail-closed
//!
//! Derive the state ONCE from the wire `source` ([`CustomerState::from_wire`]).
//! The App applies severity precedence server-side when it picks the single
//! `source`, so this map is 1:1 — no precedence is re-implemented here. An
//! unrecognized / future `source` fails CLOSED to `NotYetAssessed` (warn,
//! needs-review) — never silently Clean.

/// The three derive tiers — drive exit codes (block=1, warn=2, clean=0) and
/// the colour family, and map onto the universal ALLOW/WARN/DENY render bucket.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Tier {
    /// exit 1 — DENY. Customer must not install / must remove.
    Block,
    /// exit 2 — WARN. Review / upgrade (fail-closed for unknown).
    Warn,
    /// exit 0 — ALLOW. No known issues.
    Clean,
}

impl Tier {
    /// Process exit code for the CLI gate (block=1, warn=2, clean=0).
    pub fn exit_code(self) -> i32 {
        match self {
            Tier::Block => 1,
            Tier::Warn => 2,
            Tier::Clean => 0,
        }
    }
}

/// The 9 canonical customer-facing states, severity order (highest first) per
/// the BD-ratified ordering in §1: Blocked-by-policy, Compromised, Malicious,
/// Ransomware-linked, Actively-exploited, Vulnerable, Range-not-resolved,
/// Not-yet-assessed, Clean. CLEANLIB-518(§3) added Range-not-resolved (8→9).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum CustomerState {
    /// Customer's OWN policy rule blocked this package (operative gate).
    BlockedByPolicy,
    /// Tampered-with in a supply-chain attack (curated compromise list).
    Compromised,
    /// Known-malicious package (malware / typosquat).
    Malicious,
    /// Vulnerability tied to active ransomware campaigns.
    RansomwareLinked,
    /// Vulnerability being exploited in the wild (CISA KEV).
    ActivelyExploited,
    /// Has known CVEs (review + upgrade).
    Vulnerable,
    /// CLEANLIB-518 (§3): the requested semver range could not be resolved to a
    /// concrete version (`source_state = RANGE_NOT_RESOLVED`). Distinct from
    /// `NotYetAssessed` — the package is not un-assessed, the *range* is; the
    /// customer must pin an exact version. Fail-closed needs-input (Warn).
    RangeNotResolved,
    /// No verdict on file yet — fail-closed needs-review.
    NotYetAssessed,
    /// No known issues found.
    Clean,
}

impl CustomerState {
    /// Derive the customer state from the wire `source` string (the values in
    /// `crate::envelope::ALL_VERDICT_SOURCES`). Unknown / future variants fail
    /// CLOSED to `NotYetAssessed` (warn) — never silently Clean.
    ///
    /// Two variants carry a note:
    /// - `DM_THRESHOLD_BLOCK` → `BlockedByPolicy` (the customer's own rule).
    ///   The spec also routes a `DM_THRESHOLD_BLOCK` from the *curated*
    ///   supply-chain-compromise list (CLEANLIB-177) to `Compromised`, but that
    ///   distinction is carried by which rule fired, not by `source` alone, and
    ///   177 is not yet shipped. Until 177 lands + the App tags curated-list
    ///   blocks, every `DM_THRESHOLD_BLOCK` is the customer's policy. See
    ///   [`from_block_origin`](CustomerState::from_block_origin).
    /// - `VECTOR_VERDICT` is the legacy pre-176 full-eval source, preserved for
    ///   backward-compat. Post-176 the App projects findings into the specific
    ///   `CVE_FINDING*` variants, so a bare `VECTOR_VERDICT` reaching a render
    ///   surface is a legacy non-clean signal → `Vulnerable` (fail-safe).
    pub fn from_wire(source: &str) -> CustomerState {
        match source {
            "ALLOWED_NO_FINDINGS" => CustomerState::Clean,
            "CVE_FINDING" => CustomerState::Vulnerable,
            "CVE_FINDING_ON_KEV" => CustomerState::ActivelyExploited,
            "CVE_FINDING_ON_RANSOMWARE" => CustomerState::RansomwareLinked,
            "MALICIOUS_TRIAGE" => CustomerState::Malicious,
            "DM_THRESHOLD_BLOCK" => CustomerState::BlockedByPolicy,
            "INSUFFICIENT_DATA" => CustomerState::NotYetAssessed,
            // Legacy backward-compat — fail-safe to Vulnerable, never Clean.
            "VECTOR_VERDICT" => CustomerState::Vulnerable,
            // Unknown / future variant — fail CLOSED to needs-review.
            _ => CustomerState::NotYetAssessed,
        }
    }

    /// Same as [`from_wire`](CustomerState::from_wire) but lets the caller
    /// resolve the `DM_THRESHOLD_BLOCK` ambiguity when it knows the block
    /// origin. Use once CLEANLIB-177 ships and the App tags curated-list
    /// blocks: `curated_compromise = true` routes `DM_THRESHOLD_BLOCK` to
    /// `Compromised` instead of `BlockedByPolicy`.
    pub fn from_block_origin(source: &str, curated_compromise: bool) -> CustomerState {
        match (source, curated_compromise) {
            ("DM_THRESHOLD_BLOCK", true) => CustomerState::Compromised,
            _ => CustomerState::from_wire(source),
        }
    }

    /// CLEANLIB-518 (§3): resolve the customer state taking the wire
    /// `source_state` into account. A `RANGE_NOT_RESOLVED` source_state
    /// (CLEANLIB-513 — App could not resolve the requested semver range) maps to
    /// `RangeNotResolved` so the render banner reads "Range not resolved" and
    /// agrees with the reasoning body, instead of collapsing to the generic
    /// `NotYetAssessed` banner. All other source_states defer to
    /// [`from_wire`](CustomerState::from_wire) on `source`.
    pub fn from_wire_with_source_state(source: &str, source_state: Option<&str>) -> CustomerState {
        match source_state {
            // `RANGE_NOT_RESOLVED` (CLEANLIB-513/§3) is a source_state-only value
            // — not a VerdictSource `from_wire` knows — so it keeps its explicit
            // arm.
            Some(s) if s.eq_ignore_ascii_case("RANGE_NOT_RESOLVED") => {
                CustomerState::RangeNotResolved
            }
            // CLEANLIB-543: `source_state` is the envelope-v2 canonical status key
            // (the v2 rename of `source`, carrying the refined origin —
            // CVE_FINDING_ON_KEV / CVE_FINDING_ON_RANSOMWARE / MALICIOUS_TRIAGE /
            // …). When present, derive from IT, not the coarse `source` (which the
            // App may emit as a flat VECTOR_VERDICT on the v2 shape). This is what
            // keeps `actively_exploited` / `ransomware_linked` from flattening to
            // `vulnerable` when the origin rides in source_state. `from_wire`
            // already maps the full VerdictSource corpus and fail-closes an
            // unknown value to `not_yet_assessed`, so this stays fail-safe. Note
            // the App emits `customer_state == from_wire(source_state)` server-side
            // (§3), so preferring source_state is equivalent to trusting the
            // pre-resolved customer_state.
            Some(s) if !s.is_empty() => CustomerState::from_wire(s),
            // v1 back-compat: no source_state → the origin rides in `source`.
            _ => CustomerState::from_wire(source),
        }
    }

    /// Stable machine string for `--output json` `state` field + structured
    /// MCP/SDK fields. snake_case, customer-vocabulary, NOT the wire variant.
    pub fn as_str(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => "blocked_by_policy",
            CustomerState::Compromised => "compromised",
            CustomerState::Malicious => "malicious",
            CustomerState::RansomwareLinked => "ransomware_linked",
            CustomerState::ActivelyExploited => "actively_exploited",
            CustomerState::Vulnerable => "vulnerable",
            CustomerState::RangeNotResolved => "range_not_resolved",
            CustomerState::NotYetAssessed => "not_yet_assessed",
            CustomerState::Clean => "clean",
        }
    }

    /// Customer-facing display label (Title-case, no codenames). §2 of spec.
    pub fn label(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => "Blocked by policy",
            CustomerState::Compromised => "Compromised",
            CustomerState::Malicious => "Malicious",
            CustomerState::RansomwareLinked => "Ransomware-linked",
            CustomerState::ActivelyExploited => "Actively exploited",
            CustomerState::Vulnerable => "Vulnerable",
            CustomerState::RangeNotResolved => "Range not resolved",
            CustomerState::NotYetAssessed => "Not yet assessed",
            CustomerState::Clean => "Clean",
        }
    }

    /// One-line, action-first customer copy (no codenames, no raw tier words).
    /// §2 of spec — verbatim.
    pub fn copy(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => {
                "Blocked by your organization's policy. Contact your security \
                 owner or request an exception."
            }
            CustomerState::Compromised => {
                "This version was tampered with in a supply-chain attack. Do \
                 not install — use a known-good version."
            }
            CustomerState::Malicious => {
                "Known-malicious package (malware / typosquat). Do not install."
            }
            CustomerState::RansomwareLinked => {
                "Carries a vulnerability tied to active ransomware campaigns. \
                 Upgrade before shipping."
            }
            CustomerState::ActivelyExploited => {
                "Has a vulnerability that's being exploited in the wild (on the \
                 U.S. CISA exploited list). Upgrade urgently."
            }
            CustomerState::Vulnerable => {
                "Has known vulnerabilities (CVEs). Review and upgrade to a \
                 fixed version."
            }
            CustomerState::RangeNotResolved => {
                "The requested version range couldn't be resolved to a concrete \
                 version. Pin an exact version and re-check."
            }
            CustomerState::NotYetAssessed => {
                "No verdict on file yet — treat as needs-review until assessed."
            }
            CustomerState::Clean => "No known issues found.",
        }
    }

    /// Derive tier (block / warn / clean). `NotYetAssessed` is fail-closed →
    /// Warn. Per §1 "Tier" column.
    pub fn tier(self) -> Tier {
        match self {
            CustomerState::BlockedByPolicy
            | CustomerState::Compromised
            | CustomerState::Malicious
            | CustomerState::RansomwareLinked
            | CustomerState::ActivelyExploited => Tier::Block,
            CustomerState::Vulnerable
            | CustomerState::RangeNotResolved
            | CustomerState::NotYetAssessed => Tier::Warn,
            CustomerState::Clean => Tier::Clean,
        }
    }

    /// Process exit code for the CLI gate.
    pub fn exit_code(self) -> i32 {
        self.tier().exit_code()
    }

    /// CSS custom-property name for the soft severity token (extension + SDKs
    /// consume these for theming). §1 "Soft colour token" column.
    pub fn color_token(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => "--cl-policy",
            CustomerState::Compromised => "--cl-compromised",
            CustomerState::Malicious => "--cl-malicious",
            CustomerState::RansomwareLinked => "--cl-ransomware",
            CustomerState::ActivelyExploited => "--cl-exploited",
            CustomerState::Vulnerable => "--cl-vulnerable",
            // §5 reuse: range-not-resolved shares the needs-input token family;
            // states differentiate by label, not a bespoke colour.
            CustomerState::RangeNotResolved => "--cl-unknown",
            CustomerState::NotYetAssessed => "--cl-unknown",
            CustomerState::Clean => "--cl-clean",
        }
    }

    /// Soft severity hex (draft-ratified working palette, §5). Brand cyan for
    /// Clean; distinct mauve for policy so "your rule" reads apart from "our
    /// finding" reds.
    pub fn color_hex(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => "#C77DBB",
            CustomerState::Compromised => "#D16D6A",
            CustomerState::Malicious => "#D9534F",
            CustomerState::RansomwareLinked => "#DB7B57",
            CustomerState::ActivelyExploited => "#E0934A",
            CustomerState::Vulnerable => "#D9A441",
            CustomerState::RangeNotResolved => "#7C8696",
            CustomerState::NotYetAssessed => "#7C8696",
            CustomerState::Clean => "#50C0E0",
        }
    }

    /// Text-surface emoji for MCP `human_message` + CLI text output. §1
    /// "MCP/CLI emoji" column. One concept per tier; states differentiate by
    /// label + colour, not a bespoke glyph family (§5 — reuse, don't cut).
    pub fn emoji(self) -> &'static str {
        match self {
            CustomerState::BlockedByPolicy => "🛑",
            CustomerState::Compromised => "⛔",
            CustomerState::Malicious => "⛔",
            CustomerState::RansomwareLinked => "🔴",
            CustomerState::ActivelyExploited => "🔴",
            CustomerState::Vulnerable => "⚠️",
            CustomerState::RangeNotResolved => "❔",
            CustomerState::NotYetAssessed => "❔",
            CustomerState::Clean => "✅",
        }
    }

    /// All 9 states, severity order (highest first). For exhaustive contract
    /// tests + doc generation. CLEANLIB-518(§3) added RangeNotResolved (8→9).
    pub fn all() -> [CustomerState; 9] {
        [
            CustomerState::BlockedByPolicy,
            CustomerState::Compromised,
            CustomerState::Malicious,
            CustomerState::RansomwareLinked,
            CustomerState::ActivelyExploited,
            CustomerState::Vulnerable,
            CustomerState::RangeNotResolved,
            CustomerState::NotYetAssessed,
            CustomerState::Clean,
        ]
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::envelope::ALL_VERDICT_SOURCES;

    // ── The wire→state mappings (the cross-surface contract) ────────────────
    #[test]
    fn wire_to_state_mapping_is_canonical() {
        use CustomerState::*;
        assert_eq!(CustomerState::from_wire("ALLOWED_NO_FINDINGS"), Clean);
        assert_eq!(CustomerState::from_wire("CVE_FINDING"), Vulnerable);
        assert_eq!(CustomerState::from_wire("CVE_FINDING_ON_KEV"), ActivelyExploited);
        assert_eq!(CustomerState::from_wire("CVE_FINDING_ON_RANSOMWARE"), RansomwareLinked);
        assert_eq!(CustomerState::from_wire("MALICIOUS_TRIAGE"), Malicious);
        assert_eq!(CustomerState::from_wire("DM_THRESHOLD_BLOCK"), BlockedByPolicy);
        assert_eq!(CustomerState::from_wire("INSUFFICIENT_DATA"), NotYetAssessed);
        assert_eq!(CustomerState::from_wire("VECTOR_VERDICT"), Vulnerable);
    }

    #[test]
    fn every_known_wire_source_maps_without_falling_through() {
        // Anti-drift: every value the envelope declares must have an explicit
        // mapping (not silently hit the fail-closed `_` arm). If 176/177 adds
        // a wire source, this fails until the map is extended.
        for &src in ALL_VERDICT_SOURCES {
            let state = CustomerState::from_wire(src);
            // ALLOWED_NO_FINDINGS is the only known source that may be Clean.
            if src != "ALLOWED_NO_FINDINGS" {
                assert_ne!(
                    state,
                    CustomerState::Clean,
                    "known non-clean source {src} mapped to Clean"
                );
            }
        }
    }

    #[test]
    fn cleanlib_518_range_not_resolved_source_state_maps_distinctly() {
        // §3: a RANGE_NOT_RESOLVED source_state yields the distinct
        // RangeNotResolved state (not the generic NotYetAssessed), so the CLI
        // banner label agrees with the reasoning body. Case-insensitive.
        assert_eq!(
            CustomerState::from_wire_with_source_state("INSUFFICIENT_DATA", Some("RANGE_NOT_RESOLVED")),
            CustomerState::RangeNotResolved
        );
        assert_eq!(
            CustomerState::from_wire_with_source_state("INSUFFICIENT_DATA", Some("range_not_resolved")),
            CustomerState::RangeNotResolved
        );
        // Banner↔body coherence: the label is no longer "Not yet assessed".
        assert_eq!(CustomerState::RangeNotResolved.label(), "Range not resolved");
        assert_ne!(
            CustomerState::RangeNotResolved.label(),
            CustomerState::NotYetAssessed.label()
        );
        // Fail-closed: an unresolved range is a WARN, never an ALLOW.
        assert_eq!(CustomerState::RangeNotResolved.exit_code(), 2);
        // No source_state (or a different one) still defers to `source`.
        assert_eq!(
            CustomerState::from_wire_with_source_state("CVE_FINDING", None),
            CustomerState::Vulnerable
        );
        assert_eq!(
            CustomerState::from_wire_with_source_state("CVE_FINDING", Some("CVE_FINDING")),
            CustomerState::Vulnerable
        );
    }

    #[test]
    fn unknown_source_fails_closed_to_needs_review() {
        assert_eq!(CustomerState::from_wire("SOME_FUTURE_VARIANT"), CustomerState::NotYetAssessed);
        assert_eq!(CustomerState::from_wire(""), CustomerState::NotYetAssessed);
        assert_ne!(CustomerState::from_wire("SOME_FUTURE_VARIANT"), CustomerState::Clean);
    }

    #[test]
    fn curated_compromise_routes_dm_block_to_compromised() {
        assert_eq!(
            CustomerState::from_block_origin("DM_THRESHOLD_BLOCK", true),
            CustomerState::Compromised
        );
        assert_eq!(
            CustomerState::from_block_origin("DM_THRESHOLD_BLOCK", false),
            CustomerState::BlockedByPolicy
        );
        assert_eq!(
            CustomerState::from_block_origin("CVE_FINDING", true),
            CustomerState::Vulnerable
        );
    }

    #[test]
    fn tier_and_exit_codes() {
        assert_eq!(CustomerState::Clean.exit_code(), 0);
        assert_eq!(CustomerState::Vulnerable.exit_code(), 2);
        assert_eq!(CustomerState::NotYetAssessed.exit_code(), 2); // fail-closed
        for s in [
            CustomerState::ActivelyExploited,
            CustomerState::RansomwareLinked,
            CustomerState::Malicious,
            CustomerState::Compromised,
            CustomerState::BlockedByPolicy,
        ] {
            assert_eq!(s.exit_code(), 1, "{s:?} must be block-tier");
        }
    }

    #[test]
    fn no_internal_codenames_in_customer_strings() {
        let banned = [
            "Vector", "VECTOR", "Tricorder", "DmThreshold", "DM_THRESHOLD",
            "CveFinding", "CVE_FINDING", "MaliciousTriage", "MALICIOUS_TRIAGE",
            "InsufficientData", "INSUFFICIENT_DATA", "vuln_xref", "mock", "fixture",
        ];
        for s in CustomerState::all() {
            for text in [s.label(), s.copy()] {
                for b in banned {
                    assert!(
                        !text.contains(b),
                        "codename {b:?} leaked into customer string {text:?} for {s:?}"
                    );
                }
            }
        }
    }

    #[test]
    fn no_raw_tier_words_in_customer_copy() {
        for s in CustomerState::all() {
            for b in ["DENY", "WARN", "ALLOW"] {
                assert!(!s.copy().contains(b), "raw tier word {b} in copy for {s:?}");
                assert!(!s.label().contains(b), "raw tier word {b} in label for {s:?}");
            }
        }
    }

    #[test]
    fn every_state_has_complete_token_set() {
        for s in CustomerState::all() {
            assert!(!s.as_str().is_empty());
            assert!(!s.label().is_empty());
            assert!(!s.copy().is_empty());
            assert!(s.color_token().starts_with("--cl-"));
            assert!(s.color_hex().starts_with('#') && s.color_hex().len() == 7);
            assert!(!s.emoji().is_empty());
        }
    }

    #[test]
    fn clean_uses_brand_cyan_others_do_not() {
        assert_eq!(CustomerState::Clean.color_hex(), "#50C0E0");
        for s in CustomerState::all() {
            if s != CustomerState::Clean {
                assert_ne!(s.color_hex(), "#50C0E0", "{s:?} must not reuse brand cyan");
            }
        }
    }

    #[test]
    fn machine_strings_are_unique() {
        let mut seen = std::collections::HashSet::new();
        for s in CustomerState::all() {
            assert!(seen.insert(s.as_str()), "duplicate state string {}", s.as_str());
        }
    }
}