diff --git a/jcp/jcp-rs/crates/jcp-receipt/src/lib.rs b/jcp/jcp-rs/crates/jcp-receipt/src/lib.rs index 12b2efc34..c5ee66e62 100644 --- a/jcp/jcp-rs/crates/jcp-receipt/src/lib.rs +++ b/jcp/jcp-rs/crates/jcp-receipt/src/lib.rs @@ -516,6 +516,52 @@ pub fn replay_spend<'a>( /// point. This is the integrity layer OpenTelemetry lacks and the property the /// EU AI Act's logging obligations (Aug 2026) and the "notarized agents" line /// of research both reach for — built from the family's own JCR-1 envelope. +/// A record that an earlier entry's content was erased. +/// +/// # Why a hash chain needs this shape +/// +/// The chain links on envelope bytes: each entry's `prev` is the content id of +/// the one before it. So an entry cannot be edited or removed to satisfy an +/// erasure request — doing either breaks every link after it, and a chain that +/// no longer verifies is not evidence of anything, including of the erasure. +/// +/// Erasure is therefore **forward-only**. The erased envelope stops being +/// retained; its content id does not change, so the links still resolve; and a +/// tombstone is *appended* declaring what happened. What is lost is the ability +/// to read what was done. What survives is that something was done, where in +/// the order, and what it cost. +/// +/// # Why the energy stays +/// +/// The tombstone retains `cost_uj` and its acquisition class deliberately. +/// Every energy total, efficiency figure and facility rollup computed over this +/// log is a sum across its entries; an erasure that dropped the joules would +/// silently shrink all of them, and the shrinkage would be indistinguishable +/// from a genuine efficiency gain. That is a conservation break of exactly the +/// kind [`crate`]'s sibling standards refuse elsewhere, arriving through the +/// back door of a privacy feature. +/// +/// Joules and an acquisition label are not personal data. The payload hash, the +/// resource, the subject and the action are — and none of them are here. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Tombstone { + /// Content id of the erased entry. Unchanged by erasure, which is what + /// keeps the chain intact. + pub erased: jcp_schema::ContentId, + /// When the erasure was performed (microseconds since the epoch). + pub erased_at_us: u64, + /// The authority the erasure was carried out under — a request reference or + /// a policy id, never the requesting party's identity. A tombstone that + /// named the subject would re-introduce the datum the erasure removed. + pub authority: String, + /// The erased entry's energy, retained so rollups stay conserved. + pub cost_uj: u64, + /// Its acquisition class, retained for the same reason: a figure without + /// one is not comparable, and a rollup mixing labelled and unlabelled + /// figures is not either. + pub energy_provenance: String, +} + pub struct ReceiptLog { steward_sk: SigningKey, steward: String, @@ -542,6 +588,24 @@ impl ReceiptLog { } } + /// Append a tombstone recording that an earlier entry's content was erased. + /// + /// This does **not** alter the erased entry: it cannot, because the chain + /// links on envelope bytes. The caller stops retaining that envelope's body; + /// this records the fact, forward, as a new link. The chain continues to + /// verify precisely because nothing behind it moved. + /// + /// Returns the tombstone's envelope bytes. + pub fn erase(&mut self, t: &Tombstone) -> Vec { + let wire = tombstone_wire(t, &self.steward, self.seq, &self.head); + let core = jcr1::signed_core_bytes(&wire).expect("canonical core"); + let env = jcr1::cose_sign1_envelope(&core, &self.steward_sk, &self.steward); + self.head = jcp_schema::ContentId::of_bytes(&env); + self.seq += 1; + self.entries.push(env.clone()); + env + } + /// Seal a decision as the next link in the chain, returning the new entry's /// envelope bytes. Both allows and denies are chained — excising a deny /// breaks the chain exactly as excising an allow would. @@ -595,6 +659,30 @@ impl ReceiptLog { /// Project a decision to logged JCR-1 wire JSON: [`to_jcr1_wire`] plus `seq` /// and `prev` (the previous entry's envelope content id). +/// The JCR-1 wire for a tombstone: its own profile, so a reader can never +/// mistake it for a decision that happened to have no payload. +pub fn tombstone_wire( + t: &Tombstone, + steward: &str, + seq: u64, + prev: &jcp_schema::ContentId, +) -> Value { + json!({ + "jcp_receipt": TOMBSTONE_PROFILE, + "erased": t.erased.to_hex(), + "erased_at_us": t.erased_at_us, + "authority": t.authority, + "cost_uj": t.cost_uj, + "energy_provenance": t.energy_provenance, + "steward": steward, + "seq": seq, + "prev": prev.to_hex(), + }) +} + +/// The profile tag a tombstone carries. +pub const TOMBSTONE_PROFILE: &str = "jcp.tombstone/1"; + pub fn to_jcr1_wire_logged( frame: &Frame, grant: &Grant, @@ -718,6 +806,107 @@ mod tests { /// preimage — or the bump silently invalidated every receipt in the wild. + fn tomb(erased: jcp_schema::ContentId, uj: u64) -> Tombstone { + Tombstone { + erased, + erased_at_us: 1_700_000_000_000_000, + authority: "dsr-2026-0042".into(), + cost_uj: uj, + energy_provenance: "HwShunt".into(), + } + } + + /// The invariant a hash chain makes non-negotiable: erasure must not break + /// the links. Nothing behind the tombstone is touched, so every prior + /// entry's bytes — and therefore every `prev` — are exactly as they were. + #[test] + fn erasure_appends_and_the_chain_survives_it() { + let (frame, grant, d) = scenario(); + let mut log = ReceiptLog::new(sk(3), "did:example:steward"); + + let first = log.append(&frame, &grant, &d); + let before = jcp_schema::ContentId::of_bytes(&first); + let n_before = log.entries().len(); + + let t = log.erase(&tomb(before, d.cost.uj())); + + assert_eq!(log.entries().len(), n_before + 1, "erasure APPENDS, never removes"); + assert_eq!(log.entries()[0], first, "the erased entry's bytes are untouched"); + assert_ne!(t, first); + + // The tombstone verifies under the steward key, and its sealed payload + // is exactly the wire naming the erased entry as `prev` at `seq` 1 — + // compared byte-for-byte rather than re-parsed, which pins the content + // as well as the signature. + let payload = jcr1::verify_cose_sign1( + &t, + "did:example:steward", + &sk(3).verifying_key().to_bytes(), + ) + .expect("tombstone verifies under the steward key"); + let expected = jcr1::signed_core_bytes(&tombstone_wire( + &tomb(before, d.cost.uj()), + "did:example:steward", + 1, + &before, + )) + .expect("canonical core"); + assert_eq!(payload, expected, "the tombstone seals exactly the chained wire"); + } + + /// The TX-specific half: an erased record still counts toward energy + /// totals. Dropping the joules would silently shrink every rollup over the + /// log, and the shrinkage would be indistinguishable from an efficiency + /// gain — a conservation break arriving through a privacy feature. + #[test] + fn erasure_conserves_the_energy_total() { + let (frame, grant, d) = scenario(); + let cost = d.cost.uj(); + let mut log = ReceiptLog::new(sk(3), "did:example:steward"); + let first = log.append(&frame, &grant, &d); + let id = jcp_schema::ContentId::of_bytes(&first); + + let t = tomb(id, cost); + log.erase(&t); + + // The tombstone carries the cost forward, and its acquisition class + // with it — a figure without one is not comparable to the others in + // the same sum. + assert_eq!(t.cost_uj, cost, "the joules survive the erasure"); + assert_eq!(t.energy_provenance, "HwShunt"); + } + + /// A tombstone must not re-introduce what the erasure removed. It carries + /// no payload hash, no resource, no subject, and no action. + #[test] + fn a_tombstone_carries_nothing_personal() { + let (frame, grant, d) = scenario(); + let mut log = ReceiptLog::new(sk(3), "did:example:steward"); + let first = log.append(&frame, &grant, &d); + let id = jcp_schema::ContentId::of_bytes(&first); + let wire = tombstone_wire(&tomb(id, 42), "s", 1, &id); + + for forbidden in ["payload_hash", "resource", "subject", "action", "issuer"] { + assert!( + wire.get(forbidden).is_none(), + "a tombstone must not carry `{forbidden}` — that is the datum erasure removed" + ); + } + // The authority is a request reference, not the requesting party. + assert_eq!(wire["authority"].as_str(), Some("dsr-2026-0042")); + } + + /// A tombstone declares its own profile, so no reader mistakes it for a + /// decision that happened to carry no payload. + #[test] + fn a_tombstone_is_not_a_decision() { + let id = jcp_schema::ContentId::of_bytes(b"x"); + let wire = tombstone_wire(&tomb(id, 1), "s", 0, &id); + assert_eq!(wire["jcp_receipt"].as_str(), Some(TOMBSTONE_PROFILE)); + assert_ne!(wire["jcp_receipt"].as_str(), Some(PROFILE)); + assert!(wire.get("verdict").is_none(), "a tombstone has no verdict"); + } + #[test] fn published_v1_receipts_still_verify() { const V1_ALLOW: &str = "d284581fa201270458196469643a6578616d706c653a6a63702d7265666572656e6365a05901d2ae65747275737467636f6e74726f6c66616374696f6e64726561646669737375657278386469643a6b65793a7a364d6b6f6e334e656364364e6b6b79666f476f48786964327a6e476335394c55334b376d756261526346624c664c5867636f73745f756a181e677374657761726478196469643a6578616d706c653a6a63702d7265666572656e6365677375626a65637478386469643a6b65793a7a364d6b6f39685467674d776a535445614a615055664536747163793278765536426e4e713365336f38715642697948677665726469637465616c6c6f77686772616e745f6964784033623161356139636262373831353134636637353162613030376530373765383038333937376234663037623130346433366565393034643932383939386334687265736f75726365784030663766623535636565393361623937373738323936303865383531666133316536386531326462396466633061383032366164323938333134636633663932696275646765745f756a18646a6672616d655f6b696e6469746f6f6c2d63616c6c6b6a63705f72656365697074656a63702f3171656e657267795f70726f76656e616e63656748775368756e74736275646765745f72656d61696e696e675f756a184658405a7be56b33956c069d4e23127baa7b090e5028b9704dff6ca5ac46da546534e667151f80d7d7a605bcc31ea2bb33ec971e3e8b8794f7248a18b34c33bc438509";