feat: audit provenance — content hashes, taint/span rendering, OAuth mint effect-audit.

Signed-off-by: Teryl Taylor <terylt@ibm.com>

Author: terylt

CHANGELOG.md

@@ -18,6 +18,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 ### Added
 
 - **Out-of-process host for existing Python CPEX plugins.** A new `cpex-hosts-python` crate registers `kind: isolated_venv`, running an unmodified Python CPEX plugin in its own cached virtualenv as a subprocess instead of in-process through the PyO3 bindings. Each plugin gets a venv keyed by a SHA-256 fingerprint of its requirements + manifest (rebuilt when either changes, `rmtree`d rather than upgraded in place so a removed dependency actually disappears), and the host drives the Python framework's `worker.py` over a newline-delimited JSON stdio protocol. Hook payloads, `context`, and the capability-filtered `Extensions` view cross as JSON; returns come back as a serialized `PluginResult`, with `modified_extensions` merged through the executor's existing copy-on-write tier validation — the host implements no tier logic of its own. Failure modes the executor cannot otherwise distinguish (venv build failure, worker death mid-flight, a task over `max_content_size`, per-invocation timeout) map to distinct `PluginError`s carrying a stable `code` and structured `details`, so the executor's configured `on_error` policy applies unchanged. Pure Rust plus a subprocess — no libpython link, so the crate is in `default-members` and a plain `cargo build` does not require a Python dev install. The wire contract is pinned in `docs/specs/extensions-wire-contract.md`; CMF §3 remains normative for the extension slots themselves. (#149)
+- **First-class decision and effect auditing.** CPEX can now audit its own enforcement — every allow, deny, and modify — instead of only the allowed post-hook traffic an observation plugin happened to see. A new `AuditHook` family, auto-attached by the `PluginManager`, fires at the executor's verdict return points (not a pipeline phase), so a blocked call, a scope narrowing, and a clean allow all produce a record. Each carries a `DecisionLog` — executor-owned and handed only to audit sinks, never placed on `PluginContext` — with the ordered plugin steps, the terminal verdict, the invocation's W3C trace span (`trace_id` / `span_id` / `parent_span_id`, child-span model: a fresh span whose parent is the request's span, for causal-DAG reconstruction), the taint labels the request arrived with, and, opt-in, a content hash of the payload at entry. Irreversible external effects (a token mint, an approval grant) are audited as their own events through a capability-gated, write-ahead protocol: a plugin holding `emit_effect` calls `ext.begin_effect` to durably record intent *before* the act (fail-closed — no durable record, no act) and `ext.complete_effect` to record the outcome (`confirmed` / `rejected` / `unknown`). A durable `FileEffectLog` write-ahead log (append + `fsync`, serialized against concurrent writers, self-compacting at a configurable threshold) makes the intent crash-safe; startup recovery (`PluginManager::recover_effects`) compacts completed effects and reconciles crash-orphaned ones against the issuing participant through an `EffectReconciler` seam (the default logs and leaves them `unknown`). `Extensions::perform_effect` brackets the two-phase protocol so a caller cannot skip, reorder, or forget it. Opt-in throughout: no effect WAL and no content hashing unless `plugin_settings.effect_log_path` / `plugin_settings.capture_content_provenance` are set. (#XXX)
+- **The OAuth delegator emits write-ahead audit for the tokens it mints.** `cpex-plugin-delegator-oauth` now brackets both mint legs — the workload `client_assertion` base-token mint and the RFC 8693 exchange — with `begin_effect` / `complete_effect`, mapping a successful exchange to `confirmed`, a definitive IdP rejection to `rejected`, and a timeout or unreachable IdP to `unknown` (reconciled later, never assumed minted). Effects are emitted only when the operator grants the plugin `emit_effect` and configures an effect WAL; otherwise the mint path is unchanged. There is deliberately no OAuth-specific reconciler — an IdP exposes no lookup by mint key, so the core default (log and leave `unknown`) is the honest behavior. (#XXX)
+- **The reference `audit-logger` renders the new provenance.** Decision records now include the invocation `span`, a `taint` object (the labels the request arrived with vs. the labels after the pipeline — their difference is the taint this node added), and, when content provenance is enabled, a `content` object with the input and output payload hashes (`sha256:…`, digests only, never the content itself). (#XXX)
 
 ### Fixed
 

Cargo.lock

@@ -230,6 +230,54 @@ impl AuditLogger {
                 })
                 .collect();
             map.insert("decision_steps".into(), json!(steps));
+
+            // The invocation's node identity in the decision graph: its own
+            // span, the upstream call that triggered it (causal parent), and
+            // the trace they share. Downstream joins these into a causal DAG.
+            if let Some(span) = decisions.span() {
+                map.insert(
+                    "span".into(),
+                    json!({
+                        "trace_id": span.trace_id,
+                        "span_id": span.span_id,
+                        "parent_span_id": span.parent_span_id,
+                    }),
+                );
+            }
+
+            // Taint provenance: the labels the request arrived with vs. the
+            // labels after the pipeline. Their difference is the taint this
+            // node added — a taint edge in the decision graph.
+            let input_labels: Vec<&String> = decisions.input_labels().iter().collect();
+            let final_labels: Vec<String> = ext
+                .security
+                .as_ref()
+                .map(|s| {
+                    let mut l: Vec<String> = s.labels.iter().cloned().collect();
+                    l.sort_unstable();
+                    l
+                })
+                .unwrap_or_default();
+            if !input_labels.is_empty() || !final_labels.is_empty() {
+                map.insert(
+                    "taint".into(),
+                    json!({ "input": input_labels, "final": final_labels }),
+                );
+            }
+
+            // Content-addressed provenance: the input hash (captured at entry
+            // when enabled) plus this node's output hash. Gated on input_hash
+            // presence — when provenance is off it is `None` and we emit
+            // neither. Only digests, never content.
+            if let Some(input_hash) = decisions.input_hash() {
+                let output_hash = payload
+                    .and_then(|p| p.audit_bytes())
+                    .map(|b| cpex_core::hooks::payload::content_hash(&b));
+                map.insert(
+                    "content".into(),
+                    json!({ "input_hash": input_hash, "output_hash": output_hash }),
+                );
+            }
         }
         record
     }
@@ -348,7 +396,8 @@ mod tests {
         assert_eq!(record["tool_call"]["args"]["employee_id"], "EMP-001234");
         // Always-allow contract: handler returns continue_processing.
         let mut ctx = PluginContext::default();
-        let r = <AuditLogger as HookHandler<CmfHook>>::handle(&plugin, &payload, &ext, &mut ctx).await;
+        let r =
+            <AuditLogger as HookHandler<CmfHook>>::handle(&plugin, &payload, &ext, &mut ctx).await;
         assert!(r.continue_processing);
         assert!(r.violation.is_none());
     }
@@ -371,6 +420,72 @@ mod tests {
         assert_eq!(record["verdict"]["deny"]["code"], "missing_permission");
         assert_eq!(record["decision_steps"][0]["plugin"], "cedar-pdp");
         assert_eq!(record["decision_steps"][0]["action"], "Denied");
+        // No span was set on this log → no span field emitted.
+        assert!(record.get("span").is_none());
+    }
+
+    #[test]
+    fn decision_record_includes_span_when_set() {
+        use cpex_core::decision::Span;
+
+        let plugin = AuditLogger::new(cfg()).unwrap();
+        let mut log = DecisionLog::new();
+        log.set_span(Span::for_request(Some("trace-abc"), Some("upstream-span")));
+        log.finalize(Verdict::Allow);
+
+        let record = plugin.build_decision_record(None, &Extensions::default(), &log);
+        assert_eq!(record["span"]["trace_id"], "trace-abc");
+        assert_eq!(record["span"]["parent_span_id"], "upstream-span");
+        assert!(record["span"]["span_id"]
+            .as_str()
+            .is_some_and(|s| !s.is_empty()));
+    }
+
+    #[test]
+    fn decision_record_includes_taint_delta() {
+        let plugin = AuditLogger::new(cfg()).unwrap();
+        let mut log = DecisionLog::new();
+        log.set_input_labels(vec!["PII".into()]); // the request arrived carrying PII
+        log.finalize(Verdict::Allow);
+
+        // Final state: the pipeline added `secret`.
+        let mut sec = SecurityExtension::default();
+        sec.labels.insert("PII".into());
+        sec.labels.insert("secret".into());
+        let ext = Extensions {
+            security: Some(Arc::new(sec)),
+            ..Default::default()
+        };
+
+        let record = plugin.build_decision_record(None, &ext, &log);
+        assert_eq!(record["taint"]["input"], serde_json::json!(["PII"]));
+        assert_eq!(
+            record["taint"]["final"],
+            serde_json::json!(["PII", "secret"])
+        );
+    }
+
+    #[test]
+    fn decision_record_includes_content_hashes_when_captured() {
+        let plugin = AuditLogger::new(cfg()).unwrap();
+        let mut log = DecisionLog::new();
+        log.set_input_hash(Some("sha256:deadbeef".into()));
+        log.finalize(Verdict::Allow);
+
+        // No payload on this dispatch → output_hash is null, input present.
+        let record = plugin.build_decision_record(None, &Extensions::default(), &log);
+        assert_eq!(record["content"]["input_hash"], "sha256:deadbeef");
+        assert!(record["content"]["output_hash"].is_null());
+    }
+
+    #[test]
+    fn no_content_field_without_input_hash() {
+        // Provenance off (input_hash None) → no content field at all.
+        let plugin = AuditLogger::new(cfg()).unwrap();
+        let mut log = DecisionLog::new();
+        log.finalize(Verdict::Allow);
+        let record = plugin.build_decision_record(None, &Extensions::default(), &log);
+        assert!(record.get("content").is_none());
     }
 
     #[test]

builtins/plugins/audit-logger/src/logger.rs

@@ -59,6 +59,8 @@ serde_json = { workspace = true }
 tokio = { workspace = true }
 chrono = { workspace = true }
 tracing = { workspace = true }
+# `uuid` for the per-mint effect key (a unique attempt id in the effect WAL).
+uuid = { workspace = true }
 
 # `base64` decodes the minted token's JWT payload for a best-effort,
 # read-only interop check (did the IdP honor the RFC 8693 `actor_token`