From dccbc41f89effc0185503addd921f0df90bc002b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:04:51 +0000 Subject: [PATCH 1/7] test(plasma): capture reproducible forensic regression failures Pin strict SPDX admission, reserved-action assurance, and forensic observation limitations against the inspected d9998ab baseline. The three active negative tests are intentionally red; four expanded-scope tests remain ignored pending a versioned forensic API. Real WSL cargo receipts included; no production changes. --- docs/FORENSIC-REGRESSION-HANDOVER.adoc | 57 ++++++ tests/forensic_regression_contracts.rs | 229 +++++++++++++++++++++++++ 2 files changed, 286 insertions(+) create mode 100644 docs/FORENSIC-REGRESSION-HANDOVER.adoc create mode 100644 tests/forensic_regression_contracts.rs diff --git a/docs/FORENSIC-REGRESSION-HANDOVER.adoc b/docs/FORENSIC-REGRESSION-HANDOVER.adoc new file mode 100644 index 0000000..c7c100e --- /dev/null +++ b/docs/FORENSIC-REGRESSION-HANDOVER.adoc @@ -0,0 +1,57 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Plasma forensic regression test handover +// Copyright (c) 2026 Jonathan D.A. Jewell +:toc: + +== Purpose and authority + +* Baseline inspected: `hyperpolymath/plasma-parser-writer`, commit `d9998ab0d9b612c82ef782b75e0ea62703da1344` (2026-11-11). +* Canonical governance is maintained by `metadatastician/standards`: DEED v2.0 ABNF (`1-formats/deed/spec/abnf/deed.abnf`), K9 component Nickel contract (`1-formats/k9/spec/contract/k9_contract.ncl`), K9 coordination v1.2 ABNF (`2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.2.abnf`). No competing parser is introduced here. +* No production-source changes; no remote branch or PR created; no `.deed` or `.k9` files rewritten. + +== File added + +`tests/forensic_regression_contracts.rs` -- six default tests (three current correctness regressions expected red, three baseline positive controls expected green) and four explicitly ignored forensic-mode requirements. + +== Running on an isolated branch or worktree + +[source,shell] +---- +git switch -c test/plasma-forensic-contracts +# apply plasma-regressions.patch using git apply --check && git apply +cargo test --test forensic_regression_contracts -- --nocapture +cargo test --test forensic_regression_contracts -- --ignored --nocapture +cargo test --workspace +---- + +The first test command should expose current strictness failures (red): unexpected punctuation, integer overflow, and unvalidated reserved-action positive assurance. The `--ignored` command exercises the four design-changing forensic assertions; failures on v0 are expected and do NOT establish that the existing narrower policy-mode collector violates its documented contract. + +== Source findings underlying the negative controls + +* Lexer: `plasma-parser/src/spdx/lexer.rs`, lines 118-122 silently skip unknown characters; line 149 maps parse failure to 0. +* Policy evaluator: `plasma-engine/src/eval.rs`, lines 344-349 maps `ConsistentWith` to a non-violation; `evaluate` accepts a raw Policy and schema validation is performed only through the loader. +* Facts: `plasma-engine/src/facts.rs`, lines 72-79 skip dot-prefixed directories, and lines 91-98 discard some walking errors; collection has no content hashes. +* Diff: `plasma-engine/src/diff.rs` compares file names, headers, metadata, and GitFacts but not content. +* Conditions: `plasma-engine/src/eval.rs` lines 170-181 treat absent content as false; negating that boolean can create a true condition. +* GitFacts: `plasma-engine/src/facts.rs` lines 169-185 preserve the symbolic HEAD ref but do not resolve its content hash. + +== Decisions still pending (do not invent semantics) + +* `Overlay.applies_to`: accepted by the schema, but unused by `effective_rules`. Its concrete selection semantics require an architecture decision before encoding a regression assertion. +* Filesystem error handling: a portable deterministic unreadable-directory fixture needs a testable traversal abstraction, because root users can bypass ordinary permission checks. +* Evidence-completeness / Unknown semantics: introduce a versioned forensic API rather than silently changing existing policy-mode truth tables. +* Creusot+Pearlite: these tests are not proofs. After correcting contracts and production behaviour, prove deontic evaluation, admission and aggregation; validate the CI prover with a deliberately false control. + +== Sign-off rule + +Nothing is signed off as executed unless a real Cargo transcript, exit status and tool versions are recorded. The execution results for 2026-11-16 are recorded below. Keep each expected red case until a reviewed fix changes it to green, then run the complete workspace suite. + +== Execution receipts — 2026-11-16 (isolated WSL checkout) + +* Host: The-Titanic (WSL2 Linux); rustc 1.99.1, cargo 1.99.1, rustfmt 1.10.0. +* Baseline: `d9998ab0d9b612c82ef782b75e0ea62703da1344`; local branch `test/plasma-forensic-contracts-20261116`. +* Run 1: `cargo test --test forensic_regression_contracts -- --nocapture` → exit 101: three passing positive controls, three failing strictness regressions, four ignored. +* Run 2: `cargo test --test forensic_regression_contracts -- --ignored --nocapture` → exit 101: four intentionally ignored forensic-mode targets each reproduced the current limitation. +* Run 3: `cargo test --workspace -- --skip rejects_unrecognised_spdx_punctuation_instead_of_dropping_it --skip rejects_overflowing_spdx_number_instead_of_substituting_zero --skip reserved_action_does_not_silently_produce_a_pass` → exit 0; all other executed tests passed, with four forensic-mode targets ignored. +* Logs stored on the same WSL host at `/tmp/plasma-regression-test-run-20261116.log`, `/tmp/plasma-regression-ignored-20261116.log`, and `/tmp/plasma-regression-workspace-20261116.log`. +* The test-only source was formatted with `rustfmt --edition 2021`; neither production code nor `main` was edited. This is expected-red evidence, not a successful compliance gate. diff --git a/tests/forensic_regression_contracts.rs b/tests/forensic_regression_contracts.rs new file mode 100644 index 0000000..89c3ab8 --- /dev/null +++ b/tests/forensic_regression_contracts.rs @@ -0,0 +1,229 @@ +// SPDX-License-Identifier: MPL-2.0 +// Regression contract candidates for plasma's forensic assurance boundary. +// Copyright (c) 2026 Jonathan D.A. Jewell +// +// These tests intentionally separate confirmed strictness defects (active, +// expected RED on the inspected baseline) from new forensic-mode contracts +// (ignored pending a distinct API/versioned contract). Do not weaken the +// production policy-mode semantics merely to make these tests pass. + +use plasma_engine::ast::{ + ActionKind, Condition, Modality, Policy, PolicyVersion, Resource, Rule, Subject, +}; +use plasma_engine::facts::{collect, FactSet}; +use plasma_engine::finding::{FindingStatus, Severity}; +use plasma_engine::{diff, evaluate}; +use plasma_parser::spdx::lexer::{Lexer, Token}; +use plasma_parser::spdx::parse_spdx_expr; +use std::collections::{BTreeMap, BTreeSet}; +use std::fs; + +fn facts(paths: &[&str]) -> FactSet { + FactSet { + root: "fixture".to_owned(), + files: paths + .iter() + .map(|s| (*s).to_owned()) + .collect::>(), + spdx_headers: BTreeMap::new(), + metadata: BTreeMap::new(), + git: Default::default(), + file_contents: BTreeMap::new(), + } +} + +fn policy_for( + subject: Subject, + condition: Condition, + resource: Resource, + action: ActionKind, +) -> Policy { + Policy { + schema_version: PolicyVersion { major: 0, minor: 1 }, + id: "forensic-regression".to_owned(), + version: PolicyVersion { major: 0, minor: 1 }, + rules: vec![Rule { + id: "r1".to_owned(), + modality: Modality::Obligation, + severity: Severity::Error, + subject, + resource, + condition, + action, + rationale: None, + source: None, + }], + overlays: Vec::new(), + } +} + +// NEGATIVE CONTROLS: active tests. They should FAIL on the inspected baseline. +// Passing these without modifying the lexer/parser warrants investigation. + +#[test] +fn rejects_unrecognised_spdx_punctuation_instead_of_dropping_it() { + let actual = parse_spdx_expr("MIT@"); + assert!( + actual.is_err(), + "invalid trailing '@' must not vanish: parser returned {actual:?}" + ); +} + +#[test] +fn rejects_overflowing_spdx_number_instead_of_substituting_zero() { + let tokens = Lexer::new("Apache-4294967296.0").tokenize(); + assert!( + !tokens.iter().any(|token| matches!(token, Token::Number(0))), + "overflow silently became Number(0): {tokens:?}" + ); + assert!( + parse_spdx_expr("Apache-4294967296.0").is_err(), + "overflowing numeric component must reject rather than admit a different identifier" + ); +} + +#[test] +fn reserved_action_does_not_silently_produce_a_pass() { + // Direct evaluate() currently accepts a Policy struct, bypassing the + // validation that load_policy_str() applies. An eventual ValidatedPolicy + // boundary should make this call unrepresentable instead of merely + // changing the verdict to Violation. This test pins the immediate hazard. + let p = policy_for( + Subject::Repo, + Condition::True, + Resource::File { + path: "LICENSE".to_owned(), + }, + ActionKind::ConsistentWith { + id: "external-decision".to_owned(), + }, + ); + let result = evaluate(&p, &facts(&["LICENSE"])); + assert!( + result + .findings + .iter() + .all(|f| f.status != FindingStatus::Pass), + "reserved/unvalidated action must not emit positive assurance: {result:?}" + ); +} + +// POSITIVE CONTROLS: active tests. These should PASS on the baseline. + +#[test] +fn accepts_an_ordinary_compound_spdx_expression() { + assert!(parse_spdx_expr("MIT OR Apache-2.0").is_ok()); +} + +#[test] +fn findings_summary_matches_actual_pass_and_violation_counts() { + let mut p = policy_for( + Subject::Repo, + Condition::True, + Resource::File { + path: "README.md".to_owned(), + }, + ActionKind::Present, + ); + let mut second = p.rules[0].clone(); + second.id = "r2".to_owned(); + second.resource = Resource::File { + path: "LICENSE".to_owned(), + }; + p.rules.push(second); + let e = evaluate(&p, &facts(&["README.md"])); + assert_eq!(e.findings.len(), 2); + assert_eq!(e.summary.errors, 1); + assert_eq!(e.summary.warnings, 0); + assert_eq!(e.summary.info, 0); + assert_eq!(e.summary.passes, 1); + assert_eq!(e.findings[0].rule_id, "r1"); + assert_eq!(e.findings[1].rule_id, "r2"); + assert_eq!(e, evaluate(&p, &facts(&["README.md"]))); +} + +#[test] +fn existing_policy_collector_discovers_regular_visible_files() { + let d = tempfile::tempdir().expect("temp fixture"); + fs::write(d.path().join("visible.rs"), "fn example() {}\n").expect("fixture file"); + let snap = collect(d.path()).expect("collect baseline facts"); + assert!(snap.files.contains("visible.rs")); +} + +// FORENSIC-MODE TARGETS: intentionally IGNORED in the default suite. +// Current v0 contracts deliberately exclude these facts or define unknown +// input as false. Re-enable these ONLY for a new, explicitly versioned +// forensic observation/evaluation API, or run with `--ignored` to confirm +// the existing limitations before designing that API. + +#[test] +#[ignore = "new forensic collector required; existing policy collector skips dot-directories by specification"] +fn forensic_view_includes_governance_directories() { + let d = tempfile::tempdir().expect("temp fixture"); + let workflows = d.path().join(".github").join("workflows"); + fs::create_dir_all(&workflows).expect("fixture dir"); + fs::write(workflows.join("gate.yml"), "name: Gate\n").expect("fixture file"); + let snap = collect(d.path()).expect("collect baseline facts"); + assert!( + snap.files.contains(".github/workflows/gate.yml"), + "forensic view may not omit governance paths" + ); +} + +#[test] +#[ignore = "new forensic snapshot-diff contract required; current diff intentionally compares selected facts, not source bytes"] +fn forensic_diff_detects_content_only_mutations() { + let mut before = facts(&["src/main.rs"]); + before + .file_contents + .insert("src/main.rs".to_owned(), "fn a() {}\n".to_owned()); + let mut after = before.clone(); + after + .file_contents + .insert("src/main.rs".to_owned(), "fn b() {}\n".to_owned()); + let observed = diff(&before, &after); + assert!( + !observed.is_empty(), + "source bytes changed but diff claimed identical: {observed:?}" + ); +} + +#[test] +#[ignore = "forensic evidence needs explicit Unknown; v0 boolean predicates intentionally use false for uncollected content"] +fn negated_unavailable_evidence_cannot_emit_a_clean_pass() { + let p = policy_for( + Subject::Repo, + Condition::Not { + of: Box::new(Condition::FileMatchesPattern { + path: "src/main.rs".to_owned(), + pattern: "secret".to_owned(), + }), + }, + Resource::File { + path: "LICENSE".to_owned(), + }, + ActionKind::Present, + ); + let e = evaluate(&p, &facts(&["src/main.rs", "LICENSE"])); + assert!( + e.findings.iter().all(|f| f.status != FindingStatus::Pass), + "uncollected content cannot justify positive forensic assurance: {e:?}" + ); +} + +#[test] +#[ignore = "new Git snapshot fidelity contract required; v0 stores symbolic HEAD reference only"] +fn forensic_git_facts_distinguish_two_commits_on_the_same_branch() { + let d = tempfile::tempdir().expect("temp fixture"); + let ref_dir = d.path().join(".git").join("refs").join("heads"); + fs::create_dir_all(&ref_dir).expect("fixture git refs"); + fs::write(d.path().join(".git").join("HEAD"), "ref: refs/heads/main\n").expect("HEAD"); + fs::write(ref_dir.join("main"), format!("{}\n", "a".repeat(40))).expect("ref"); + let before = collect(d.path()).expect("before"); + fs::write(ref_dir.join("main"), format!("{}\n", "b".repeat(40))).expect("updated ref"); + let after = collect(d.path()).expect("after"); + assert_ne!( + before.git, after.git, + "HEAD commit changed but GitFacts did not" + ); +} From 531077bbf6328453e1d14391c90072e9b6c5ee88 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:07:03 +0000 Subject: [PATCH 2/7] test(plasma): avoid benign zero in overflow regression fixture Use Apache-4294967296.9, so Number(0) unambiguously represents the overflow coercion rather than a legitimate minor version token. Rerun reproduced the original three failures. --- tests/forensic_regression_contracts.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/forensic_regression_contracts.rs b/tests/forensic_regression_contracts.rs index 89c3ab8..cad1d0e 100644 --- a/tests/forensic_regression_contracts.rs +++ b/tests/forensic_regression_contracts.rs @@ -71,13 +71,13 @@ fn rejects_unrecognised_spdx_punctuation_instead_of_dropping_it() { #[test] fn rejects_overflowing_spdx_number_instead_of_substituting_zero() { - let tokens = Lexer::new("Apache-4294967296.0").tokenize(); + let tokens = Lexer::new("Apache-4294967296.9").tokenize(); assert!( !tokens.iter().any(|token| matches!(token, Token::Number(0))), "overflow silently became Number(0): {tokens:?}" ); assert!( - parse_spdx_expr("Apache-4294967296.0").is_err(), + parse_spdx_expr("Apache-4294967296.9").is_err(), "overflowing numeric component must reject rather than admit a different identifier" ); } From 02e55d86405cd6e03a6a5cb89a6b56180834753a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:08:27 +0000 Subject: [PATCH 3/7] fix(spdx): reject invalid characters and overflowing numeric tokens Represent malformed lexical material explicitly so the recursive descent parser cannot silently accept a different licence expression. Keep the existing tokenize API shape and reject overflows without coercion. Regression suite now passes both parser strictness cases; other workspace tests pass except the separately tracked reserved-action negative. --- plasma-parser/src/spdx/lexer.rs | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/plasma-parser/src/spdx/lexer.rs b/plasma-parser/src/spdx/lexer.rs index 3fbf72a..76f798d 100644 --- a/plasma-parser/src/spdx/lexer.rs +++ b/plasma-parser/src/spdx/lexer.rs @@ -29,6 +29,10 @@ pub enum Token { LParen, /// Right parenthesis ')'. RParen, + /// Invalid lexical input (unrecognised character or overflowing number). + /// Retained as a token so the parser can reject it rather than silently + /// changing the meaning of the input. + Invalid(String), } /// Lexer for SPDX expression strings. @@ -98,10 +102,7 @@ impl<'a> Lexer<'a> { Some(Token::Dash) } } - '0'..='9' => { - let num = self.read_number(); - Some(Token::Number(num)) - } + '0'..='9' => Some(self.read_number()), '+' => { self.chars.next(); Some(Token::OrLater) @@ -116,9 +117,13 @@ impl<'a> Lexer<'a> { } } _ => { - // Skip unrecognised characters. + // Preserve malformed input as an explicit token. Dropping it + // would allow malformed expressions such as `MIT@` to parse + // successfully as a different (valid) licence expression. self.chars.next(); - self.next_token() + Some(Token::Invalid(format!( + "unrecognised character {ch:?} at byte offset {start}" + ))) } } } @@ -135,8 +140,9 @@ impl<'a> Lexer<'a> { } } - /// Read a contiguous run of digit characters and return the parsed number. - fn read_number(&mut self) -> u32 { + /// Read a contiguous run of digits, preserving overflow as invalid input. + /// Substituting zero would make a malformed expression look legitimate. + fn read_number(&mut self) -> Token { let mut s = String::new(); while let Some(&(_, ch)) = self.chars.peek() { if ch.is_ascii_digit() { @@ -146,7 +152,10 @@ impl<'a> Lexer<'a> { break; } } - s.parse().unwrap_or(0) + match s.parse::() { + Ok(n) => Token::Number(n), + Err(_) => Token::Invalid(format!("numeric component out of range: {s}")), + } } /// Read a contiguous word of alphanumeric characters, hyphens within From 76f1c3667f1dffd028f6e937fd4698be2709770a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:11:21 +0000 Subject: [PATCH 4/7] fix(plasma): fail closed on unvalidated policy evaluation Validate raw Policy values at the public evaluator boundary, producing one explicit error finding instead of any misleading pass or empty clean evaluation. Retain a defensive reserved-action violation arm. Add direct evaluation regressions for a false-guarded reserved action and unsupported release subject. cargo test --workspace, cargo fmt --check, cargo clippy --all-targets -D warnings pass. --- plasma-engine/src/eval.rs | 44 ++++++++++++++++++++---- plasma-engine/src/schema.rs | 4 ++- tests/forensic_regression_contracts.rs | 47 ++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 7 deletions(-) diff --git a/plasma-engine/src/eval.rs b/plasma-engine/src/eval.rs index 5fc8bbc..cdfa4a0 100644 --- a/plasma-engine/src/eval.rs +++ b/plasma-engine/src/eval.rs @@ -33,7 +33,36 @@ impl Instance { } /// Evaluate a policy against a fact set. +/// +/// The loader validates policies, but callers can also construct `Policy` +/// values directly. Do not issue successful findings for such unvalidated +/// inputs: reject them explicitly before executing any rule. pub fn evaluate(policy: &Policy, facts: &FactSet) -> Evaluation { + if let Err(error) = crate::schema::validate(policy) { + return Evaluation { + root: facts.root.clone(), + policy_id: policy.id.clone(), + policy_version: policy.version, + schema_version: policy.schema_version, + findings: vec![Finding { + rule_id: "__policy_admission__".to_owned(), + modality: Modality::Obligation, + severity: Severity::Error, + subject: "repo".to_owned(), + message: format!("policy rejected before evaluation: {error}"), + rationale: Some( + "Only schema-validated policies can produce compliance findings".to_owned(), + ), + source: Some("plasma:schema".to_owned()), + status: FindingStatus::Violation, + }], + summary: Summary { + errors: 1, + ..Summary::default() + }, + }; + } + let mut findings = Vec::new(); for (rule, origin) in effective_rules(policy) { @@ -271,6 +300,15 @@ fn check_rule(rule: &Rule, origin: Option<&str>, instance: &Instance, facts: &Fa let resource_desc = describe_resource(&rule.resource); let (violated, message) = match (&rule.modality, &rule.action) { + // Defense in depth: even an illicit call that bypasses admission must + // never report a reserved action as satisfied (including permission). + (_, ActionKind::ConsistentWith { .. }) => ( + true, + format!( + "consistency action is reserved and cannot be evaluated for {}", + instance.label() + ), + ), (Modality::Permission, _) => ( false, format!("{resource_desc} is permitted for {}", instance.label()), @@ -341,12 +379,6 @@ fn check_rule(rule: &Rule, origin: Option<&str>, instance: &Instance, facts: &Fa }, ) } - // ConsistentWith is rejected at load; treated as a pass to keep - // evaluation total. - (_, ActionKind::ConsistentWith { .. }) => ( - false, - format!("consistency check skipped for {}", instance.label()), - ), }; let source = rule diff --git a/plasma-engine/src/schema.rs b/plasma-engine/src/schema.rs index 586ba8d..edfaf73 100644 --- a/plasma-engine/src/schema.rs +++ b/plasma-engine/src/schema.rs @@ -93,7 +93,9 @@ pub fn builtin_repo_hygiene() -> Policy { } /// Validate a parsed policy against v0 evaluability rules. -fn validate(policy: &Policy) -> Result<(), SchemaError> { +/// Kept within the crate so the public evaluator can reject raw policies +/// constructed without passing through `load_policy_str`. +pub(crate) fn validate(policy: &Policy) -> Result<(), SchemaError> { if policy.schema_version != SCHEMA_VERSION { return Err(SchemaError::UnsupportedSchemaVersion { found: policy.schema_version, diff --git a/tests/forensic_regression_contracts.rs b/tests/forensic_regression_contracts.rs index cad1d0e..a95b860 100644 --- a/tests/forensic_regression_contracts.rs +++ b/tests/forensic_regression_contracts.rs @@ -108,6 +108,53 @@ fn reserved_action_does_not_silently_produce_a_pass() { ); } +#[test] +fn rejects_reserved_action_even_if_its_condition_would_be_false() { + let p = policy_for( + Subject::Repo, + Condition::Not { + of: Box::new(Condition::True), + }, + Resource::File { + path: "LICENSE".to_owned(), + }, + ActionKind::ConsistentWith { + id: "external-decision".to_owned(), + }, + ); + let e = evaluate(&p, &facts(&["LICENSE"])); + assert_eq!( + e.findings.len(), + 1, + "invalid policy must be rejected at admission" + ); + assert_eq!(e.summary.errors, 1); + assert_eq!(e.findings[0].rule_id, "__policy_admission__"); + assert_eq!(e.findings[0].status, FindingStatus::Violation); +} + +#[test] +fn rejects_reserved_release_subject_in_direct_evaluation() { + let p = policy_for( + Subject::Release { + tag: "v1.0.0".to_owned(), + }, + Condition::True, + Resource::File { + path: "LICENSE".to_owned(), + }, + ActionKind::Present, + ); + let e = evaluate(&p, &facts(&["LICENSE"])); + assert_eq!( + e.findings.len(), + 1, + "invalid subject must not vanish silently" + ); + assert_eq!(e.summary.errors, 1); + assert_eq!(e.findings[0].status, FindingStatus::Violation); +} + // POSITIVE CONTROLS: active tests. These should PASS on the baseline. #[test] From 879c813d3e3673a8183a0dfad4c767c651655863 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:12:22 +0000 Subject: [PATCH 5/7] docs(plasma): record verified repair and test receipts Document baseline and signed repair commits, executed Cargo/fmt/Clippy checks, the four still-ignored forensic-mode targets, formal-proof gaps, and the explicit no-push/no-merge boundary. --- docs/FORENSIC-REGRESSION-HANDOVER.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/FORENSIC-REGRESSION-HANDOVER.adoc b/docs/FORENSIC-REGRESSION-HANDOVER.adoc index c7c100e..b1bd1dc 100644 --- a/docs/FORENSIC-REGRESSION-HANDOVER.adoc +++ b/docs/FORENSIC-REGRESSION-HANDOVER.adoc @@ -55,3 +55,22 @@ Nothing is signed off as executed unless a real Cargo transcript, exit status an * Run 3: `cargo test --workspace -- --skip rejects_unrecognised_spdx_punctuation_instead_of_dropping_it --skip rejects_overflowing_spdx_number_instead_of_substituting_zero --skip reserved_action_does_not_silently_produce_a_pass` → exit 0; all other executed tests passed, with four forensic-mode targets ignored. * Logs stored on the same WSL host at `/tmp/plasma-regression-test-run-20261116.log`, `/tmp/plasma-regression-ignored-20261116.log`, and `/tmp/plasma-regression-workspace-20261116.log`. * The test-only source was formatted with `rustfmt --edition 2021`; neither production code nor `main` was edited. This is expected-red evidence, not a successful compliance gate. + +== Repair receipts — 2026-11-16 (persistent local branch) + +* The baseline was preserved from the temporary checkout into `/home/hyperpolymath/repos/plasma-parser-writer`, branch `test/plasma-forensic-contracts-20261116`. GitHub main was not modified. +* `dccbc41` — regression tests and original observed-failure handover. +* `531077b` — correct overflow negative control to use `Apache-4294967296.9`, avoiding an innocent minor-version zero. +* `02e55d8` — reject unrecognised SPDX characters and numeric token overflow without silently changing the parsed expression. +* `76f1c36` — fail closed at direct `evaluate` admission for unvalidated raw policies, including reserved actions and unsupported release subjects. Two additional negative tests cover a false condition and an unsupported subject. +* Post-fix `cargo test --test forensic_regression_contracts -- --nocapture`: **8 passed, 0 failed, 4 ignored**. +* Post-fix `cargo test --workspace`: **exit 0**, all enabled workspace unit, integration and doc tests pass. +* `cargo fmt --all -- --check`: **exit 0**. +* `cargo clippy --workspace --all-targets -- -D warnings`: **exit 0**. +* The four ignored forensic-mode targets remain open and were previously executed with `--ignored`, reproducing the initial limitations. They require an explicitly versioned forensic contract and must not be marked green. +* Creusot/Pearlite proofs were **not run or added**; this phase supplies executable regression evidence, not formal verification. +* All local commits use SSH signatures from the loaded agent key. The local verifier reports a mathematically good signature but `No principal matched` in the user's current allowed-signers file; external GitHub signature-verification status is not established until publication. The configured signing requirement was not disabled. +* No `.deed` or `.k9` file was rewritten. Follow-up migration must use the canonical DEED grammar and K9/coordination validators in `metadatastician/standards`. +* No push, pull request, merge, licensing change or changes to remote branch rulesets were performed. + +Next steps: decide and implement the independent forensic evidence schema for content hashes, Git commit resolution, coverage and Unknown status. Clarify `Overlay.applies_to` semantics before formally proving overlay applicability; then add Creusot+Pearlite proof obligations with independent negative-proof controls. \ No newline at end of file From a8c40a3e2cb82725768cb31a43ed876d4e553395 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:43:36 +0000 Subject: [PATCH 6/7] feat(plasma): introduce opt-in forensic evidence snapshot v0.1 Add a separate, versioned, read-only evidence model with SHA-256 source digests, explicit scope/exclusions and observation errors, Git HEAD commit identity, three-valued evidence and deterministic pure diffing. Preserve legacy policy-mode facts and CLI; avoid following file or Git administrative symlinks. Add 14 negative/positive integration fixtures and a scoped contract. cargo test --workspace --locked --offline, cargo fmt --all -- --check, and cargo clippy --workspace --all-targets --offline -- -D warnings pass. --- Cargo.lock | 72 ++++ docs/forensic-evidence-v0.1.adoc | 112 +++++ plasma-engine/Cargo.toml | 1 + plasma-engine/src/forensic.rs | 494 +++++++++++++++++++++++ plasma-engine/src/lib.rs | 1 + plasma-engine/tests/forensic_evidence.rs | 287 +++++++++++++ 6 files changed, 967 insertions(+) create mode 100644 docs/forensic-evidence-v0.1.adoc create mode 100644 plasma-engine/src/forensic.rs create mode 100644 plasma-engine/tests/forensic_evidence.rs diff --git a/Cargo.lock b/Cargo.lock index 9cc6c7e..588d552 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -73,6 +73,15 @@ version = "2.11.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af" +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + [[package]] name = "cfg-if" version = "1.0.4" @@ -125,6 +134,35 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + [[package]] name = "equivalent" version = "1.0.2" @@ -153,6 +191,16 @@ version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + [[package]] name = "getrandom" version = "0.4.2" @@ -289,6 +337,7 @@ dependencies = [ "regex", "serde", "serde_json", + "sha2", "tempfile", "thiserror", "toml", @@ -451,6 +500,17 @@ dependencies = [ "serde", ] +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + [[package]] name = "strsim" version = "0.11.1" @@ -542,6 +602,12 @@ version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801" +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + [[package]] name = "unicode-ident" version = "1.0.24" @@ -560,6 +626,12 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + [[package]] name = "walkdir" version = "2.5.0" diff --git a/docs/forensic-evidence-v0.1.adoc b/docs/forensic-evidence-v0.1.adoc new file mode 100644 index 0000000..15a6735 --- /dev/null +++ b/docs/forensic-evidence-v0.1.adoc @@ -0,0 +1,112 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Plasma forensic evidence contract v0.1 (experimental) +:toc: + +== Purpose + +This opt-in evidence model is separate from v0 policy `FactSet`, +`plasma facts`, `plasma diff`, and the existing boolean policy evaluator. +Those contracts retain their current semantics and wire formats. + +The model answers a narrower question: "what repository bytes and Git HEAD +identity were actually observed, and was the bounded observation complete?" +It does not claim that observing a tree means every governance rule passes. + +== Seams and authorities + +[cols="1,3,3",options="header"] +|=== +| Seam | Authority | Evidence and guarantee +| S-01 Scope | Forensic scanner options | Dot-prefixed governance paths are included. `.git`, `target`, `node_modules`, `vendor`, `_build`, and `deps` are excluded *explicitly* as directory entries. Exclusions are reported, not silently erased. +| S-02 Content | SHA-256 over bytes of every in-scope regular file | Streaming hash and byte count. A same-path edit with unchanged SPDX header must change the observed digest, subject to SHA-256 collision assumptions and stable input during read. +| S-03 Git | `.git/HEAD` plus loose or packed ref resolution | Symbolic ref and resolved commit object ID recorded separately. Git object IDs are *identity*, not a substitute for SHA-256 content integrity. Unresolvable Git state remains unknown. +| S-04 Completeness | Typed observation status and issues | An unreadable path, traversal failure, invalid UTF-8 path, unsupported file type or detected concurrent write blocks a claim of complete in-scope observation. Intentional exclusions do not vanish; complete means only "for the declared scope." +| S-05 Epistemic status | Explicit three-valued evidence truth | True, False and Unknown; negating Unknown remains Unknown. This is NOT inserted into the legacy policy evaluator without an explicit version migration. +|=== + +== Boundary discipline + +* `collect_forensic(root)` is read-only: no file writes, git commands, + process execution, network, signature checks or remediation. +* No timestamps or ambient randomness are serialized. BTree ordering is + canonical. `root` is informational and may differ between checkouts. +* Symlinks are recorded by their link target and never followed outside + the root. Unknown or non-UTF-8 targets are explicit issues. +* A path not safely representable as UTF-8 is not silently accepted under a + lossy identifier: observation is marked incomplete. +* SHA-256 records observations, not a transactional filesystem snapshot. + Concurrent writes cannot be completely ruled out without filesystem or + Git-object snapshot isolation. A detected metadata change during read + invalidates that file's observation. +* The format identifies a schema version. Consumers must reject unsupported + versions and must not interpret missing/unknown evidence as a clean pass. +* The existing `FactSet` and `FactsDiff` retain their legacy semantics: + this version does NOT change their JSON, CLI, or policy-mode behaviour. +* DEED and K9 syntax must be validated against the existing standards + conformance tools; this module must not implement competing grammars. + +== Invariants and tests + +. Full in-scope file-body mutations are visible even when paths, lengths, SPDX + headers and symbolic Git ref remain the same. +. `.github`, `.machine_readable` and other dot-prefixed governance paths + remain observable; `.git` internals remain explicitly out of scope. +. Missing or unreadable evidence cannot yield a complete in-scope verdict. +. Changes to a resolved Git HEAD object ID are visible even if the branch + name does not change; detached HEAD and packed refs have defined behaviour. +. Repeated scans over stable inputs produce byte-identical JSON; diffs are + ordered and root-location-independent. +. Symlinks are not dereferenced; changes to a link target path are visible. +. The three-valued algebra preserves Unknown under negation and propagates it + according to strong Kleene conjunction/disjunction. + +== Non-goals and outstanding decisions + +* No rewriting of the legacy `plasma diff` command. +* No global proof of all repository files if generated directories are + intentionally excluded; coverage must always be interpreted with scope. +* No guarantee against concurrently mutated files beyond observed metadata + stability; stronger consistency requires Git tree or filesystem snapshot + capture with a separate contract. +* No `Overlay.applies_to` semantics here; establish an ADR separately before + formalising an overlay theorem. +* No formal Creusot/Pearlite assurance yet; these are testable contracts + and proof candidates, not completed deductive proofs. + +== Integration and release gate + +This module is library-only in v0.1, with ordinary Rust unit tests. Before +exposing it to bots as a normative auditor, require: +* A versioned JSON schema / compatibility and negative fixture suite. +* A CLI with explicit `--forensic` mode and nonzero/Unknown exit semantics. +* A bounded scan of representative real repositories, including worktrees, + large files, governance files, symlinks and concurrency experiments. +* Independent review of error, exclusion, Git and SHA-256 handling. +* Creusot+Pearlite obligations on pure evidence comparisons and admission. +* No automatic repair and no change to production policy mode. + +== Local implementation receipt — 2026-11-16 + +* Baseline: `879c813d3e3673a8183a0dfad4c767c651655863` on branch + `test/plasma-forensic-contracts-20261116`. +* Implementation: `plasma-engine/src/forensic.rs`; integration fixtures: + `plasma-engine/tests/forensic_evidence.rs`. +* New dependency: RustCrypto `sha2` 0.10.9, locked in `Cargo.lock`; + SHA-256 is used for byte observations. Git OIDs remain identity only. +* New APIs are library-only, separately versioned `0.1.0`. Legacy + `FactSet`, `FactsDiff`, `evaluate` and CLI semantics were not changed. +* `cargo test -p plasma-engine --test forensic_evidence --offline`: + 14 passed, 0 failed; hidden governance paths, binary bytes, same-length + source mutations, normal/detached/packed Git HEAD, external Gitdir refusal, + symlink refusal, unknown paths/types and three-valued evidence. +* `cargo test --workspace --offline`: exit 0. Existing forensic-mode + legacy assertions remain 4 ignored, pending a versioned CLI integration. +* `cargo fmt --all -- --check`: exit 0. +* `cargo clippy --workspace --all-targets --offline -- -D warnings`: + exit 0. +* Explicit limitations: Git worktree external pointer files result in + `Unknown` rather than dereferencing external paths; filesystem reads + are not atomic; excluded paths appear in `excluded_paths`; an + in-scope complete scan does not imply that the Git identity was resolved. +* No remote push, PR, production deployment, trust-policy bypass, DEED/K9 + migration, or formal deductive-proof execution was performed. diff --git a/plasma-engine/Cargo.toml b/plasma-engine/Cargo.toml index 33dbd7a..f656506 100644 --- a/plasma-engine/Cargo.toml +++ b/plasma-engine/Cargo.toml @@ -18,6 +18,7 @@ toml = "0.8" walkdir = "2" glob = "0.3" regex = "1" +sha2 = "0.10" thiserror = "2" [dev-dependencies] diff --git a/plasma-engine/src/forensic.rs b/plasma-engine/src/forensic.rs new file mode 100644 index 0000000..2862238 --- /dev/null +++ b/plasma-engine/src/forensic.rs @@ -0,0 +1,494 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell +//! +//! Experimental forensic evidence v0.1. Independent of the legacy FactSet: +//! observe in-scope repository bytes without interpreting a policy verdict. +//! See docs/forensic-evidence-v0.1.adoc for scope, limits and seam contracts. + +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; +use std::collections::{BTreeMap, BTreeSet}; +use std::fs::{self, File}; +use std::io::{self, Read}; +use std::path::Path; +use thiserror::Error; + +pub const SCHEMA_VERSION: &str = "0.1.0"; + +/// Deliberate exclusions in this schema version (never hide governance trees). +const EXCLUDED_DIRS: &[&str] = &[".git", "target", "node_modules", "vendor", "_build", "deps"]; + +/// Epistemic truth for future forensic consumers; not wired into policy v0. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EvidenceTruth { + True, + False, + Unknown, +} + +impl EvidenceTruth { + pub fn negate(self) -> Self { + match self { + Self::True => Self::False, + Self::False => Self::True, + Self::Unknown => Self::Unknown, + } + } + + /// Strong Kleene conjunction: False dominates Unknown. + pub fn all(values: impl IntoIterator) -> Self { + let mut unknown = false; + for value in values { + match value { + Self::False => return Self::False, + Self::Unknown => unknown = true, + Self::True => {} + } + } + if unknown { + Self::Unknown + } else { + Self::True + } + } + + /// Strong Kleene disjunction: True dominates Unknown. + pub fn any(values: impl IntoIterator) -> Self { + let mut unknown = false; + for value in values { + match value { + Self::True => return Self::True, + Self::Unknown => unknown = true, + Self::False => {} + } + } + if unknown { + Self::Unknown + } else { + Self::False + } + } +} + +/// Every in-scope path is accounted for, including paths that could not be read. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum PathEvidence { + Regular { size: u64, sha256: String }, + Symlink { target: String }, + Unknown { reason: IssueKind }, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum IssueKind { + TraversalFailed, + InvalidUtf8Path, + ReadFailed, + ChangedDuringRead, + InvalidUtf8SymlinkTarget, + UnsupportedFileType, +} + +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] +pub struct ObservationIssue { + pub path: String, + pub kind: IssueKind, +} + +/// Git identity is independent of file-content observations. Never treat a +/// symbolic HEAD branch name as the underlying commit identity. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "status", rename_all = "snake_case")] +pub enum GitHead { + NotRepository, + Resolved { + reference: Option, + commit: String, + }, + Unknown { + reference: Option, + reason: GitProblem, + }, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum GitProblem { + ExternalGitDirectory, + UnreadableHead, + InvalidHead, + MissingReference, + InvalidObjectId, +} + +/// Scope completeness does NOT mean whole-repository completeness: +/// excluded directories are separately enumerated. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ForensicSnapshot { + pub schema_version: String, + pub root: String, + pub exclusion_policy: String, + pub paths: BTreeMap, + pub excluded_paths: BTreeSet, + pub issues: Vec, + pub scope_complete: bool, + pub git: GitHead, +} + +#[derive(Debug, Error)] +pub enum ForensicError { + #[error("forensic root does not exist: {0}")] + MissingRoot(String), + #[error("forensic root must be a real directory, not a symlink or file: {0}")] + InvalidRoot(String), + #[error("cannot inspect forensic root: {0}")] + Io(#[from] io::Error), +} + +/// A pure comparison of two forensic observations. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PathChange { + pub before: Option, + pub after: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ForensicDiff { + pub schema_version: String, + pub paths_changed: BTreeMap, + pub exclusions_changed: bool, + pub issues_changed: bool, + pub scope_completeness_changed: bool, + pub git_changed: bool, +} + +impl ForensicDiff { + pub fn is_empty(&self) -> bool { + self.paths_changed.is_empty() + && !self.exclusions_changed + && !self.issues_changed + && !self.scope_completeness_changed + && !self.git_changed + } +} + +/// Compare observations, rejecting incompatible version identifiers. +pub fn diff_forensic( + before: &ForensicSnapshot, + after: &ForensicSnapshot, +) -> Result { + if before.schema_version != SCHEMA_VERSION || after.schema_version != SCHEMA_VERSION { + return Err("unsupported forensic schema version"); + } + if before.exclusion_policy != after.exclusion_policy { + return Err("forensic exclusion policies differ"); + } + + let mut paths_changed = BTreeMap::new(); + let keys: BTreeSet<_> = before.paths.keys().chain(after.paths.keys()).collect(); + for path in keys { + let b = before.paths.get(path); + let a = after.paths.get(path); + if b != a { + paths_changed.insert( + path.clone(), + PathChange { + before: b.cloned(), + after: a.cloned(), + }, + ); + } + } + Ok(ForensicDiff { + schema_version: SCHEMA_VERSION.to_owned(), + paths_changed, + exclusions_changed: before.excluded_paths != after.excluded_paths, + issues_changed: before.issues != after.issues, + scope_completeness_changed: before.scope_complete != after.scope_complete, + git_changed: before.git != after.git, + }) +} + +fn normalized_relative(root: &Path, path: &Path) -> Option { + let relative = path.strip_prefix(root).ok()?; + let mut segments = Vec::new(); + for segment in relative.components() { + segments.push(segment.as_os_str().to_str()?); + } + Some(segments.join("/")) +} + +/// SHA-256 digest of exact bytes with bounded memory, not a text decoding. +fn hash_regular_file(path: &Path) -> Result<(u64, String), IssueKind> { + let before = fs::symlink_metadata(path).map_err(|_| IssueKind::ReadFailed)?; + let mut file = File::open(path).map_err(|_| IssueKind::ReadFailed)?; + let mut hasher = Sha256::new(); + let mut buffer = [0_u8; 64 * 1024]; + let mut size = 0_u64; + loop { + let n = file.read(&mut buffer).map_err(|_| IssueKind::ReadFailed)?; + if n == 0 { + break; + } + size = size.checked_add(n as u64).ok_or(IssueKind::ReadFailed)?; + hasher.update(&buffer[..n]); + } + let after = fs::symlink_metadata(path).map_err(|_| IssueKind::ReadFailed)?; + if !after.is_file() + || size != before.len() + || size != after.len() + || before.modified().ok() != after.modified().ok() + { + return Err(IssueKind::ChangedDuringRead); + } + Ok((size, format!("{:x}", hasher.finalize()))) +} + +/// Read-only observation of the declared scope. Never dereferences symlinks. +pub fn collect_forensic(root: &Path) -> Result { + let meta = match fs::symlink_metadata(root) { + Ok(m) => m, + Err(e) if e.kind() == io::ErrorKind::NotFound => { + return Err(ForensicError::MissingRoot(root.display().to_string())) + } + Err(e) => return Err(ForensicError::Io(e)), + }; + if !meta.is_dir() { + return Err(ForensicError::InvalidRoot(root.display().to_string())); + } + + let mut paths = BTreeMap::new(); + let mut excluded_paths = BTreeSet::new(); + let mut issues = Vec::new(); + // The walker filter borrows this independently from per-entry issues. + let mut exclusion_issues = Vec::new(); + let walker = walkdir::WalkDir::new(root) + .follow_links(false) + .sort_by_file_name() + .into_iter() + .filter_entry(|entry| { + if entry.depth() == 0 { + return true; + } + // A Git worktree's .git is a *file*, not a directory. It is + // still administrative state, not source data to hash. + let excluded = entry.file_name().to_str().is_some_and(|name| { + name == ".git" || (entry.file_type().is_dir() && EXCLUDED_DIRS.contains(&name)) + }); + if excluded { + if let Some(path) = normalized_relative(root, entry.path()) { + excluded_paths.insert(path); + } else { + exclusion_issues.push(ObservationIssue { + path: entry.path().to_string_lossy().into_owned(), + kind: IssueKind::InvalidUtf8Path, + }); + } + } + !excluded + }); + + for next in walker { + let entry = match next { + Ok(entry) => entry, + Err(error) => { + let path = error.path().map_or_else( + || "".to_owned(), + |path| { + path.strip_prefix(root) + .unwrap_or(path) + .to_string_lossy() + .into_owned() + }, + ); + issues.push(ObservationIssue { + path, + kind: IssueKind::TraversalFailed, + }); + continue; + } + }; + if entry.depth() == 0 || entry.file_type().is_dir() { + continue; + } + let Some(path) = normalized_relative(root, entry.path()) else { + issues.push(ObservationIssue { + path: entry.path().to_string_lossy().into_owned(), + kind: IssueKind::InvalidUtf8Path, + }); + continue; + }; + let evidence = if entry.file_type().is_file() { + match hash_regular_file(entry.path()) { + Ok((size, sha256)) => PathEvidence::Regular { size, sha256 }, + Err(reason) => { + issues.push(ObservationIssue { + path: path.clone(), + kind: reason, + }); + PathEvidence::Unknown { reason } + } + } + } else if entry.file_type().is_symlink() { + match fs::read_link(entry.path()) { + Ok(target) => match target.to_str() { + Some(target) => PathEvidence::Symlink { + target: target.to_owned(), + }, + None => { + issues.push(ObservationIssue { + path: path.clone(), + kind: IssueKind::InvalidUtf8SymlinkTarget, + }); + PathEvidence::Unknown { + reason: IssueKind::InvalidUtf8SymlinkTarget, + } + } + }, + Err(_) => { + issues.push(ObservationIssue { + path: path.clone(), + kind: IssueKind::ReadFailed, + }); + PathEvidence::Unknown { + reason: IssueKind::ReadFailed, + } + } + } + } else { + issues.push(ObservationIssue { + path: path.clone(), + kind: IssueKind::UnsupportedFileType, + }); + PathEvidence::Unknown { + reason: IssueKind::UnsupportedFileType, + } + }; + paths.insert(path, evidence); + } + + issues.extend(exclusion_issues); + issues.sort(); + let scope_complete = issues.is_empty(); + Ok(ForensicSnapshot { + schema_version: SCHEMA_VERSION.to_owned(), + root: root.display().to_string(), + exclusion_policy: "v0.1-default".to_owned(), + paths, + excluded_paths, + issues, + scope_complete, + git: read_git_head(root), + }) +} + +fn valid_oid(value: &str) -> bool { + (value.len() == 40 || value.len() == 64) + && value.as_bytes().iter().all(|byte| byte.is_ascii_hexdigit()) +} + +/// Read only a regular administrative file without following any symbolic +/// link in its path. A repository must not redirect the auditor outside its +/// declared Git directory using malicious ref or HEAD symlinks. +fn read_git_text(dir: &Path, relative: &str) -> Option { + let mut path = dir.to_path_buf(); + for part in Path::new(relative).components() { + let std::path::Component::Normal(name) = part else { + return None; + }; + path.push(name); + let metadata = fs::symlink_metadata(&path).ok()?; + if metadata.file_type().is_symlink() { + return None; + } + } + if !fs::symlink_metadata(&path).ok()?.is_file() { + return None; + } + fs::read_to_string(path).ok() +} + +fn read_reference(dir: &Path, reference: &str) -> Option { + // Ref names are untrusted repository content; disallow absolute paths, + // traversal, empty segments and special components. + if !reference.starts_with("refs/") + || !reference + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || b"._-/".contains(&byte)) + || reference + .split('/') + .any(|s| s.is_empty() || s == "." || s == ".." || s.starts_with('.')) + { + return None; + } + if let Some(oid) = read_git_text(dir, reference) { + let oid = oid.trim(); + if valid_oid(oid) { + return Some(oid.to_owned()); + } + } + let packed = read_git_text(dir, "packed-refs")?; + packed + .lines() + .filter(|line| !line.starts_with('#') && !line.starts_with('^')) + .filter_map(|line| line.split_once(' ')) + .find_map(|(oid, name)| (name == reference && valid_oid(oid)).then(|| oid.to_owned())) +} + +fn read_git_head(root: &Path) -> GitHead { + let dotgit = root.join(".git"); + let meta = match fs::symlink_metadata(&dotgit) { + Ok(meta) => meta, + Err(e) if e.kind() == io::ErrorKind::NotFound => return GitHead::NotRepository, + Err(_) => { + return GitHead::Unknown { + reference: None, + reason: GitProblem::UnreadableHead, + }; + } + }; + // Worktrees often use .git pointer files to an external administrative + // tree. Do not follow arbitrary pointers supplied by untrusted repos. + if !meta.is_dir() { + return GitHead::Unknown { + reference: None, + reason: GitProblem::ExternalGitDirectory, + }; + } + let head = match read_git_text(&dotgit, "HEAD") { + Some(head) => head, + None => { + return GitHead::Unknown { + reference: None, + reason: GitProblem::UnreadableHead, + } + } + }; + let head = head.trim(); + if let Some(reference) = head.strip_prefix("ref: ") { + let reference = reference.to_owned(); + return match read_reference(&dotgit, &reference) { + Some(commit) => GitHead::Resolved { + reference: Some(reference), + commit, + }, + None => GitHead::Unknown { + reference: Some(reference), + reason: GitProblem::MissingReference, + }, + }; + } + if valid_oid(head) { + GitHead::Resolved { + reference: None, + commit: head.to_owned(), + } + } else { + GitHead::Unknown { + reference: None, + reason: GitProblem::InvalidHead, + } + } +} diff --git a/plasma-engine/src/lib.rs b/plasma-engine/src/lib.rs index 1f4d457..fd76102 100644 --- a/plasma-engine/src/lib.rs +++ b/plasma-engine/src/lib.rs @@ -23,6 +23,7 @@ pub mod diff; pub mod eval; pub mod facts; pub mod finding; +pub mod forensic; pub mod report; pub mod schema; diff --git a/plasma-engine/tests/forensic_evidence.rs b/plasma-engine/tests/forensic_evidence.rs new file mode 100644 index 0000000..fe2bfa6 --- /dev/null +++ b/plasma-engine/tests/forensic_evidence.rs @@ -0,0 +1,287 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell +// Regression tests for the separate, opt-in forensic evidence contract. + +use plasma_engine::forensic::{ + collect_forensic, diff_forensic, EvidenceTruth, ForensicSnapshot, GitHead, GitProblem, + PathEvidence, +}; +use std::fs; +use std::path::Path; +use tempfile::tempdir; + +fn write(path: &Path, content: impl AsRef<[u8]>) { + if let Some(parent) = path.parent() { + fs::create_dir_all(parent).unwrap(); + } + fs::write(path, content).unwrap(); +} + +fn sha256_of<'a>(snapshot: &'a ForensicSnapshot, path: &str) -> &'a str { + match snapshot.paths.get(path).expect("observed path") { + PathEvidence::Regular { sha256, .. } => sha256, + other => panic!("expected exact observed bytes, got {other:?}"), + } +} + +#[test] +fn includes_hidden_governance_paths_and_reports_exclusions() { + let temp = tempdir().unwrap(); + write( + &temp.path().join(".github/workflows/gate.yml"), + b"name: Gate\n", + ); + write( + &temp.path().join(".machine_readable/contract.deed"), + b"(repo-deed)\n", + ); + write(&temp.path().join(".claude/CLAUDE.md"), b"agents\n"); + write(&temp.path().join("src/main.rs"), b"fn main() {}\n"); + write(&temp.path().join("target/generated.rs"), b"generated\n"); + write(&temp.path().join(".git/objects/ignore"), b"git internals\n"); + let s = collect_forensic(temp.path()).unwrap(); + for expected in [ + ".github/workflows/gate.yml", + ".machine_readable/contract.deed", + ".claude/CLAUDE.md", + "src/main.rs", + ] { + assert!(s.paths.contains_key(expected), "missing {expected}"); + } + assert!(!s.paths.contains_key("target/generated.rs")); + assert!(!s.paths.contains_key(".git/objects/ignore")); + assert!(s.excluded_paths.contains("target")); + assert!(s.excluded_paths.contains(".git")); + assert!(s.scope_complete); + assert!(s.issues.is_empty()); +} + +#[test] +fn detects_same_length_content_only_edits_without_header_changes() { + let temp = tempdir().unwrap(); + let path = temp.path().join("src/example.rs"); + write( + &path, + b"// SPDX-License-Identifier: MPL-2.0\nfn alpha() {}\n", + ); + let before = collect_forensic(temp.path()).unwrap(); + write( + &path, + b"// SPDX-License-Identifier: MPL-2.0\nfn omega() {}\n", + ); + let after = collect_forensic(temp.path()).unwrap(); + assert_ne!( + sha256_of(&before, "src/example.rs"), + sha256_of(&after, "src/example.rs") + ); + let diff = diff_forensic(&before, &after).unwrap(); + assert_eq!(diff.paths_changed.len(), 1); + assert!(diff.paths_changed.contains_key("src/example.rs")); + assert!(!diff.is_empty()); +} + +#[test] +fn hashes_binary_bytes_and_produces_stable_json_on_stable_input() { + let temp = tempdir().unwrap(); + write(&temp.path().join("assets/binary.bin"), [0u8, 0xff, 0, 0x80]); + let before = collect_forensic(temp.path()).unwrap(); + let after = collect_forensic(temp.path()).unwrap(); + assert_eq!(sha256_of(&before, "assets/binary.bin").len(), 64); + assert_eq!(before, after); + assert_eq!( + serde_json::to_string(&before).unwrap(), + serde_json::to_string(&after).unwrap() + ); + assert!(diff_forensic(&before, &after).unwrap().is_empty()); +} + +#[test] +fn reports_git_head_commit_change_with_unchanged_symbolic_ref() { + let temp = tempdir().unwrap(); + write(&temp.path().join(".git/HEAD"), b"ref: refs/heads/main\n"); + write( + &temp.path().join(".git/refs/heads/main"), + format!("{}\n", "a".repeat(40)), + ); + let before = collect_forensic(temp.path()).unwrap(); + assert_eq!( + before.git, + GitHead::Resolved { + reference: Some("refs/heads/main".into()), + commit: "a".repeat(40) + } + ); + write( + &temp.path().join(".git/refs/heads/main"), + format!("{}\n", "b".repeat(40)), + ); + let after = collect_forensic(temp.path()).unwrap(); + assert_eq!( + after.git, + GitHead::Resolved { + reference: Some("refs/heads/main".into()), + commit: "b".repeat(40) + } + ); + let diff = diff_forensic(&before, &after).unwrap(); + assert!(diff.git_changed); + assert!(diff.paths_changed.is_empty()); + assert!(before.scope_complete && after.scope_complete); +} + +#[test] +fn resolves_detached_and_packed_heads_without_process_execution() { + let detached = tempdir().unwrap(); + write( + &detached.path().join(".git/HEAD"), + format!("{}\n", "c".repeat(40)), + ); + let s = collect_forensic(detached.path()).unwrap(); + assert_eq!( + s.git, + GitHead::Resolved { + reference: None, + commit: "c".repeat(40) + } + ); + let packed = tempdir().unwrap(); + write(&packed.path().join(".git/HEAD"), b"ref: refs/heads/main\n"); + write( + &packed.path().join(".git/packed-refs"), + format!("# pack-refs\n{} refs/heads/main\n", "d".repeat(40)), + ); + let p = collect_forensic(packed.path()).unwrap(); + assert_eq!( + p.git, + GitHead::Resolved { + reference: Some("refs/heads/main".into()), + commit: "d".repeat(40) + } + ); +} + +#[test] +fn reports_external_gitdir_as_unresolved_not_trusted() { + let temp = tempdir().unwrap(); + write( + &temp.path().join(".git"), + b"gitdir: /some/external/location\n", + ); + let snapshot = collect_forensic(temp.path()).unwrap(); + assert!(!snapshot.paths.contains_key(".git")); + assert!(snapshot.excluded_paths.contains(".git")); + assert_eq!( + snapshot.git, + GitHead::Unknown { + reference: None, + reason: GitProblem::ExternalGitDirectory + } + ); +} + +#[test] +fn uncertainty_is_never_inverted_to_a_boolean_pass() { + use EvidenceTruth::{False, True, Unknown}; + assert_eq!(Unknown.negate(), Unknown); + assert_eq!(EvidenceTruth::all([True, Unknown]), Unknown); + assert_eq!(EvidenceTruth::all([Unknown, False]), False); + assert_eq!(EvidenceTruth::any([False, Unknown]), Unknown); + assert_eq!(EvidenceTruth::any([Unknown, True]), True); + assert_eq!(EvidenceTruth::all([]), True); + assert_eq!(EvidenceTruth::any([]), False); +} + +#[test] +fn diff_rejects_unknown_versions_and_incompatible_scopes() { + let temp = tempdir().unwrap(); + let a = collect_forensic(temp.path()).unwrap(); + let mut other = a.clone(); + other.schema_version = "999.0".to_owned(); + assert!(diff_forensic(&a, &other).is_err()); + other = a.clone(); + other.exclusion_policy = "other-scope".to_owned(); + assert!(diff_forensic(&a, &other).is_err()); +} + +#[test] +fn missing_root_cannot_be_claimed_as_a_clean_snapshot() { + let temp = tempdir().unwrap(); + assert!(collect_forensic(&temp.path().join("missing")).is_err()); +} + +#[cfg(unix)] +#[test] +fn symlink_is_recorded_but_never_dereferenced() { + use std::os::unix::fs::symlink; + let outside = tempdir().unwrap(); + let private = outside.path().join("private.txt"); + write(&private, b"never include these bytes\n"); + let repo = tempdir().unwrap(); + symlink(&private, repo.path().join("link")).unwrap(); + let snapshot = collect_forensic(repo.path()).unwrap(); + assert!(snapshot.scope_complete); + assert!(matches!( + snapshot.paths.get("link"), + Some(PathEvidence::Symlink { .. }) + )); + assert_eq!(snapshot.paths.len(), 1); +} + +#[cfg(unix)] +#[test] +fn git_administrative_symlinks_are_not_followed() { + use std::os::unix::fs::symlink; + let outside = tempdir().unwrap(); + let secret = outside.path().join("outside-ref"); + write(&secret, format!("{}\n", "a".repeat(40))); + let repo = tempdir().unwrap(); + write(&repo.path().join(".git/HEAD"), b"ref: refs/heads/main\n"); + fs::create_dir_all(repo.path().join(".git/refs/heads")).unwrap(); + symlink(&secret, repo.path().join(".git/refs/heads/main")).unwrap(); + let snapshot = collect_forensic(repo.path()).unwrap(); + assert_eq!( + snapshot.git, + GitHead::Unknown { + reference: Some("refs/heads/main".into()), + reason: GitProblem::MissingReference + } + ); +} + +#[cfg(unix)] +#[test] +fn unsupported_socket_is_visible_as_incomplete_evidence() { + use std::os::unix::net::UnixListener; + let repo = tempdir().unwrap(); + let _listener = UnixListener::bind(repo.path().join("socket")).unwrap(); + let snapshot = collect_forensic(repo.path()).unwrap(); + assert!(!snapshot.scope_complete); + assert!(matches!( + snapshot.paths.get("socket"), + Some(PathEvidence::Unknown { .. }) + )); + assert_eq!(snapshot.issues.len(), 1); +} + +#[cfg(unix)] +#[test] +fn non_utf8_paths_are_not_silently_normalised() { + use std::os::unix::ffi::OsStringExt; + let repo = tempdir().unwrap(); + let name = std::ffi::OsString::from_vec(vec![0xff, 0xfe]); + write(&repo.path().join(name), b"bytes\n"); + let snapshot = collect_forensic(repo.path()).unwrap(); + assert!(!snapshot.scope_complete); + assert!(!snapshot.issues.is_empty()); +} + +#[test] +fn sha256_matches_published_known_answer() { + let repo = tempdir().unwrap(); + write(&repo.path().join("bytes"), b"abc"); + let snapshot = collect_forensic(repo.path()).unwrap(); + assert_eq!( + sha256_of(&snapshot, "bytes"), + "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" + ); +} From 2b9d095ca195f85f8fc6ffdd86c38f753391403c Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:53:23 +0000 Subject: [PATCH 7/7] fix(plasma): harden forensic reads against symlink races and reject invalid SPDX minor versions --- Cargo.lock | 1 + plasma-engine/Cargo.toml | 3 + plasma-engine/src/forensic.rs | 191 +++++++++++++++++++---- plasma-engine/tests/forensic_evidence.rs | 80 ++++++++++ plasma-parser/src/spdx/mod.rs | 21 ++- 5 files changed, 263 insertions(+), 33 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 588d552..10a4c6b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -335,6 +335,7 @@ dependencies = [ "glob", "plasma-parser", "regex", + "rustix", "serde", "serde_json", "sha2", diff --git a/plasma-engine/Cargo.toml b/plasma-engine/Cargo.toml index f656506..d339b4a 100644 --- a/plasma-engine/Cargo.toml +++ b/plasma-engine/Cargo.toml @@ -21,5 +21,8 @@ regex = "1" sha2 = "0.10" thiserror = "2" +[target.'cfg(unix)'.dependencies] +rustix = { version = "1", features = ["fs"] } + [dev-dependencies] tempfile = "3" diff --git a/plasma-engine/src/forensic.rs b/plasma-engine/src/forensic.rs index 2862238..e9da038 100644 --- a/plasma-engine/src/forensic.rs +++ b/plasma-engine/src/forensic.rs @@ -220,10 +220,84 @@ fn normalized_relative(root: &Path, path: &Path) -> Option { Some(segments.join("/")) } +/// Resolve every component through an owned directory handle. Non-Unix +/// platforms fail closed until an equivalent no-follow implementation exists. +#[cfg(unix)] +fn open_directory(path: &Path) -> io::Result { + use rustix::fs::{open, openat, Mode, OFlags}; + use std::path::Component; + let flags = OFlags::RDONLY | OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::CLOEXEC; + let mut dir = File::from(open(".", flags, Mode::empty())?); + for component in path.components() { + let name = match component { + Component::RootDir => Path::new("/"), + Component::CurDir => continue, + Component::ParentDir => Path::new(".."), + Component::Normal(name) => Path::new(name), + _ => return Err(io::ErrorKind::InvalidInput.into()), + }; + dir = File::from(openat(&dir, name, flags, Mode::empty())?); + } + Ok(dir) +} + +#[cfg(not(unix))] +fn open_directory(_: &Path) -> io::Result { + Err(io::ErrorKind::Unsupported.into()) +} + +#[cfg(unix)] +fn open_relative(dir: &File, relative: &Path) -> io::Result { + use rustix::fs::{openat, Mode, OFlags}; + let mut dir = dir.try_clone()?; + let mut parts = relative.components().peekable(); + while let Some(part) = parts.next() { + let std::path::Component::Normal(name) = part else { + return Err(io::ErrorKind::InvalidInput.into()); + }; + let mut flags = OFlags::RDONLY | OFlags::NOFOLLOW | OFlags::CLOEXEC | OFlags::NONBLOCK; + if parts.peek().is_some() { + flags |= OFlags::DIRECTORY; + } + dir = File::from(openat(&dir, name, flags, Mode::empty())?); + } + if !dir.metadata()?.is_file() { + return Err(io::ErrorKind::InvalidInput.into()); + } + Ok(dir) +} + +#[cfg(not(unix))] +fn open_relative(_: &File, _: &Path) -> io::Result { + Err(io::ErrorKind::Unsupported.into()) +} + +fn same_file(before: &fs::Metadata, after: &fs::Metadata) -> bool { + #[cfg(unix)] + { + use std::os::unix::fs::MetadataExt; + if before.dev() != after.dev() || before.ino() != after.ino() { + return false; + } + } + before.is_file() + && after.is_file() + && before.len() == after.len() + && before.modified().ok() == after.modified().ok() +} + /// SHA-256 digest of exact bytes with bounded memory, not a text decoding. -fn hash_regular_file(path: &Path) -> Result<(u64, String), IssueKind> { +fn hash_regular_file( + root: &File, + relative: &Path, + path: &Path, +) -> Result<(u64, String), IssueKind> { let before = fs::symlink_metadata(path).map_err(|_| IssueKind::ReadFailed)?; - let mut file = File::open(path).map_err(|_| IssueKind::ReadFailed)?; + let mut file = open_relative(root, relative).map_err(|_| IssueKind::ReadFailed)?; + let opened = file.metadata().map_err(|_| IssueKind::ReadFailed)?; + if !same_file(&before, &opened) { + return Err(IssueKind::ChangedDuringRead); + } let mut hasher = Sha256::new(); let mut buffer = [0_u8; 64 * 1024]; let mut size = 0_u64; @@ -236,7 +310,10 @@ fn hash_regular_file(path: &Path) -> Result<(u64, String), IssueKind> { hasher.update(&buffer[..n]); } let after = fs::symlink_metadata(path).map_err(|_| IssueKind::ReadFailed)?; - if !after.is_file() + if !same_file( + &before, + &file.metadata().map_err(|_| IssueKind::ReadFailed)?, + ) || !same_file(&before, &after) || size != before.len() || size != after.len() || before.modified().ok() != after.modified().ok() @@ -259,6 +336,7 @@ pub fn collect_forensic(root: &Path) -> Result return Err(ForensicError::InvalidRoot(root.display().to_string())); } + let root_handle = open_directory(root)?; let mut paths = BTreeMap::new(); let mut excluded_paths = BTreeSet::new(); let mut issues = Vec::new(); @@ -310,7 +388,7 @@ pub fn collect_forensic(root: &Path) -> Result continue; } }; - if entry.depth() == 0 || entry.file_type().is_dir() { + if entry.depth() == 0 { continue; } let Some(path) = normalized_relative(root, entry.path()) else { @@ -320,8 +398,11 @@ pub fn collect_forensic(root: &Path) -> Result }); continue; }; + if entry.file_type().is_dir() { + continue; + } let evidence = if entry.file_type().is_file() { - match hash_regular_file(entry.path()) { + match hash_regular_file(&root_handle, Path::new(&path), entry.path()) { Ok((size, sha256)) => PathEvidence::Regular { size, sha256 }, Err(reason) => { issues.push(ObservationIssue { @@ -392,44 +473,39 @@ fn valid_oid(value: &str) -> bool { /// Read only a regular administrative file without following any symbolic /// link in its path. A repository must not redirect the auditor outside its /// declared Git directory using malicious ref or HEAD symlinks. -fn read_git_text(dir: &Path, relative: &str) -> Option { - let mut path = dir.to_path_buf(); - for part in Path::new(relative).components() { - let std::path::Component::Normal(name) = part else { - return None; - }; - path.push(name); - let metadata = fs::symlink_metadata(&path).ok()?; - if metadata.file_type().is_symlink() { - return None; - } - } - if !fs::symlink_metadata(&path).ok()?.is_file() { - return None; +fn read_git_text(dir: &File, relative: &str) -> io::Result { + let mut file = open_relative(dir, Path::new(relative))?; + let before = file.metadata()?; + let mut text = String::new(); + file.read_to_string(&mut text)?; + if !same_file(&before, &file.metadata()?) { + return Err(io::ErrorKind::InvalidData.into()); } - fs::read_to_string(path).ok() + Ok(text) } -fn read_reference(dir: &Path, reference: &str) -> Option { +fn read_reference(dir: &File, reference: &str) -> Option { // Ref names are untrusted repository content; disallow absolute paths, // traversal, empty segments and special components. if !reference.starts_with("refs/") || !reference .bytes() - .all(|byte| byte.is_ascii_alphanumeric() || b"._-/".contains(&byte)) + .all(|byte| byte > b' ' && byte != 127 && !b"~^:?*[\\".contains(&byte)) || reference .split('/') .any(|s| s.is_empty() || s == "." || s == ".." || s.starts_with('.')) { return None; } - if let Some(oid) = read_git_text(dir, reference) { - let oid = oid.trim(); - if valid_oid(oid) { - return Some(oid.to_owned()); + match read_git_text(dir, reference) { + Ok(oid) => { + let oid = oid.trim(); + return valid_oid(oid).then(|| oid.to_owned()); } + Err(error) if error.kind() == io::ErrorKind::NotFound => {} + Err(_) => return None, } - let packed = read_git_text(dir, "packed-refs")?; + let packed = read_git_text(dir, "packed-refs").ok()?; packed .lines() .filter(|line| !line.starts_with('#') && !line.starts_with('^')) @@ -457,9 +533,18 @@ fn read_git_head(root: &Path) -> GitHead { reason: GitProblem::ExternalGitDirectory, }; } - let head = match read_git_text(&dotgit, "HEAD") { - Some(head) => head, - None => { + let dir = match open_directory(&dotgit) { + Ok(dir) => dir, + Err(_) => { + return GitHead::Unknown { + reference: None, + reason: GitProblem::UnreadableHead, + } + } + }; + let head = match read_git_text(&dir, "HEAD") { + Ok(head) => head, + Err(_) => { return GitHead::Unknown { reference: None, reason: GitProblem::UnreadableHead, @@ -469,7 +554,7 @@ fn read_git_head(root: &Path) -> GitHead { let head = head.trim(); if let Some(reference) = head.strip_prefix("ref: ") { let reference = reference.to_owned(); - return match read_reference(&dotgit, &reference) { + return match read_reference(&dir, &reference) { Some(commit) => GitHead::Resolved { reference: Some(reference), commit, @@ -492,3 +577,47 @@ fn read_git_head(root: &Path) -> GitHead { } } } + +#[cfg(all(test, unix))] +mod handle_tests { + use super::*; + use std::os::unix::fs::symlink; + + #[test] + fn refuses_final_and_parent_symlinks_before_reading() { + let temp = tempfile::tempdir().unwrap(); + let outside = tempfile::tempdir().unwrap(); + fs::write(outside.path().join("file"), "redirected").unwrap(); + let root = open_directory(temp.path()).unwrap(); + symlink(outside.path().join("file"), temp.path().join("file")).unwrap(); + symlink(outside.path(), temp.path().join("parent")).unwrap(); + assert!(open_relative(&root, Path::new("file")).is_err()); + assert!(open_relative(&root, Path::new("parent/file")).is_err()); + assert!(read_git_text(&root, "file").is_err()); + assert!(read_git_text(&root, "parent/file").is_err()); + } + + #[test] + fn pinned_directory_survives_path_replacement() { + let temp = tempfile::tempdir().unwrap(); + let outside = tempfile::tempdir().unwrap(); + fs::create_dir(temp.path().join("git")).unwrap(); + fs::write(temp.path().join("git/HEAD"), "original").unwrap(); + fs::write(outside.path().join("HEAD"), "redirected").unwrap(); + let dir = open_directory(&temp.path().join("git")).unwrap(); + fs::rename(temp.path().join("git"), temp.path().join("saved")).unwrap(); + symlink(outside.path(), temp.path().join("git")).unwrap(); + assert_eq!(read_git_text(&dir, "HEAD").unwrap(), "original"); + } + + #[test] + fn detects_replacement_even_with_matching_length() { + let temp = tempfile::tempdir().unwrap(); + let path = temp.path().join("file"); + fs::write(&path, "old").unwrap(); + let before = fs::symlink_metadata(&path).unwrap(); + fs::rename(&path, temp.path().join("old")).unwrap(); + fs::write(&path, "new").unwrap(); + assert!(!same_file(&before, &fs::metadata(path).unwrap())); + } +} diff --git a/plasma-engine/tests/forensic_evidence.rs b/plasma-engine/tests/forensic_evidence.rs index fe2bfa6..4447405 100644 --- a/plasma-engine/tests/forensic_evidence.rs +++ b/plasma-engine/tests/forensic_evidence.rs @@ -285,3 +285,83 @@ fn sha256_matches_published_known_answer() { "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" ); } + +#[test] +fn resolves_plus_branch_from_loose_and_packed_refs() { + for packed in [false, true] { + let temp = tempdir().unwrap(); + let git = temp.path().join(".git"); + write(&git.join("HEAD"), "ref: refs/heads/topic+fix\n"); + let oid = "a".repeat(40); + if packed { + write( + &git.join("packed-refs"), + format!("{oid} refs/heads/topic+fix\n"), + ); + } else { + write(&git.join("refs/heads/topic+fix"), &oid); + } + assert_eq!( + collect_forensic(temp.path()).unwrap().git, + GitHead::Resolved { + reference: Some("refs/heads/topic+fix".into()), + commit: oid, + } + ); + } +} + +#[test] +fn malformed_loose_ref_does_not_fall_back_to_packed() { + let temp = tempdir().unwrap(); + let git = temp.path().join(".git"); + write(&git.join("HEAD"), "ref: refs/heads/main\n"); + write(&git.join("refs/heads/main"), "invalid"); + write( + &git.join("packed-refs"), + format!("{} refs/heads/main\n", "a".repeat(40)), + ); + assert!(matches!( + collect_forensic(temp.path()).unwrap().git, + GitHead::Unknown { .. } + )); +} + +#[cfg(unix)] +#[test] +fn refused_loose_refs_do_not_fall_back_to_packed() { + use std::os::unix::fs::symlink; + for dangling in [false, true] { + let temp = tempdir().unwrap(); + let git = temp.path().join(".git"); + write(&git.join("HEAD"), "ref: refs/heads/main\n"); + write( + &git.join("packed-refs"), + format!("{} refs/heads/main\n", "a".repeat(40)), + ); + fs::create_dir_all(git.join("refs/heads")).unwrap(); + let target = temp.path().join("target-ref"); + if !dangling { + write(&target, "b".repeat(40)); + } + symlink(&target, git.join("refs/heads/main")).unwrap(); + assert!(matches!( + collect_forensic(temp.path()).unwrap().git, + GitHead::Unknown { .. } + )); + } +} + +#[cfg(unix)] +#[test] +fn invalid_utf8_empty_directory_marks_scope_incomplete() { + use std::os::unix::ffi::OsStrExt; + let temp = tempdir().unwrap(); + fs::create_dir(temp.path().join(std::ffi::OsStr::from_bytes(b"bad-\xff"))).unwrap(); + let snapshot = collect_forensic(temp.path()).unwrap(); + assert!(!snapshot.scope_complete); + assert!(snapshot + .issues + .iter() + .any(|issue| issue.kind == plasma_engine::forensic::IssueKind::InvalidUtf8Path)); +} diff --git a/plasma-parser/src/spdx/mod.rs b/plasma-parser/src/spdx/mod.rs index c64115d..925fc95 100644 --- a/plasma-parser/src/spdx/mod.rs +++ b/plasma-parser/src/spdx/mod.rs @@ -186,8 +186,14 @@ impl Parser { if matches!(self.peek(), Some(Token::Dot)) { self.advance(); // consume Dot parts.push(".".to_string()); - if let Some(Token::Number(m)) = self.advance() { - parts.push(m.to_string()); + match self.advance() { + Some(Token::Number(m)) => parts.push(m.to_string()), + Some(token) => { + return Err(SpdxParseError::UnexpectedToken(format!( + "{token:?}" + ))) + } + None => return Err(SpdxParseError::UnexpectedEnd), } } } @@ -324,3 +330,14 @@ mod tests { assert!(matches!(expr, SpdxExpr::Or(_, _))); } } + +#[cfg(test)] +mod invalid_minor_regressions { + #[test] + fn rejects_invalid_minor_versions() { + for input in ["PMPL-1.@", "PMPL-1.4294967296", "PMPL-1."] { + assert!(super::parse_spdx_expr(input).is_err(), "{input}"); + } + assert!(super::parse_spdx_expr("PMPL-1.0").is_ok()); + } +}