From ddd11f7fb8d3e3420a587d6bd75becf6e63ceec0 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 08:36:43 +0300 Subject: [PATCH 1/8] feat(repo,cli): sc transcript drop with a resurrection tombstone (ref #212) A drop writes a tombstone shaped as a bare Transcript object, so it rides existing packs with no PROTOCOL_VERSION bump. A grow-only drop set in .sc/transcript-drops filters the live index; index_incoming and reindex honor it in either arrival order. gc roots tombstones forever and sweeps the dropped body after the grace window. Design in the ADR-0038 addendum. --- .claude/skills/sc-cli-reference/SKILL.md | 6 + CLAUDE.md | 2 +- ROADMAP.md | 11 +- crates/cli/src/main.rs | 14 ++ crates/cli/tests/transcripts.rs | 56 ++++++ crates/core/src/object.rs | 46 +++++ crates/gitio/src/export.rs | 2 +- crates/repo/src/gc.rs | 40 ++++ crates/repo/src/layout.rs | 6 + crates/repo/src/sync.rs | 47 +++++ crates/repo/src/transcripts.rs | 223 +++++++++++++++++++-- docs/adr/0038-agent-session-transcripts.md | 90 +++++++++ 12 files changed, 522 insertions(+), 21 deletions(-) diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index f0bc86d8..7108a728 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -220,6 +220,12 @@ cargo run --bin sc -- transcript show [--identity ] # decrypt + pri cargo run --bin sc -- transcript list [] [--json] # list transcripts (never decrypts) cargo run --bin sc -- transcript sign [--identity ] # retroactively sign a tip's # transcript(s) (P30) +cargo run --bin sc -- transcript drop # drop a transcript by id/hex prefix (see `list`): writes + # a tombstone that travels with fetch/clone so a peer + # that still has it cannot restore it; gc reclaims the + # body after the grace window. Not erasure; propagates + # on the peer's next fetch (push at an equal tip sends + # nothing). (ADR-0038 addendum) cargo run --bin sc -- ws harvest --transcript [--sign] [--identity ] # attach the # file to each harvested workspace's landed snapshot # (P30; landing status prints before the attach) diff --git a/CLAUDE.md b/CLAUDE.md index 7c22a353..9a48e004 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,7 +144,7 @@ the code, those win. | P27 | Partial clone: `sc clone --filter `, `.sc/promisor`, `sc backfill [--all]`; wire `PROTOCOL_VERSION` 3 | [0037](docs/adr/0037-partial-clone.md) | | P28 | Security hardening: `MAX_OBJECT_SIZE` (256 MiB) caps on every untrusted transfer length; strict ref-name validation | [0039](docs/adr/0039-security-hardening-sweep.md) | | P29 | `sc serve --http` access control: bearer tokens (`sc serve token`), `--read-only`, fail-closed non-loopback bind gate | [0040](docs/adr/0040-sc-http-access-control.md) | -| P30 | Sealed agent-session transcripts: `sc transcript attach/show/list/sign`, always-encrypted body, gc-coupled index | [0038](docs/adr/0038-agent-session-transcripts.md) | +| P30 | Sealed agent-session transcripts: `sc transcript attach/show/list/sign/drop`, always-encrypted body, gc-coupled index; drop = grow-only tombstone (a bare `Transcript` object, no wire change), kept by gc, hides the body from fetch/reindex | [0038](docs/adr/0038-agent-session-transcripts.md) | | P31 | Listener resource limits: `--max-connections`, `--timeout`, `--max-pack-size` (both transports), capped read-only drain, accept backoff | [0041](docs/adr/0041-listener-resource-limits.md) | | P32 | In-binary TLS: `sc+https://` via leaf crate `tlsio`; accept-new TOFU pinning; public plaintext bind no longer justified by tokens alone | [0042](docs/adr/0042-in-binary-tls-sc-https.md) | | P33 | Randomized protected sealing (fresh DEK + nonce; `RANDOMIZED` perms bit); dual-read of pre-P33 convergent ciphertext; per-checkout keyed stat cache; `sc rewrap` upgrades convergent blobs at the tip | [0043](docs/adr/0043-randomized-protected-encryption.md) | diff --git a/ROADMAP.md b/ROADMAP.md index 8ee5352b..b34c91d7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -476,7 +476,11 @@ across every phase. failing closed on ciphertext while the right identity decrypts the exact body bytes, the `sc log` marker, and `sc gc` pruning a deleted branch's transcript while the still-reachable one survives — run twice, zero - residue. No new dependency. (ADR-0038.) + residue. No new dependency. Issue #212 added `sc transcript drop `: a + grow-only drop tombstone (a bare `Transcript` object, so no wire change) + hides the body from `list`/`show`, travels with fetch/clone, blocks + resurrection in either arrival order, and is kept by gc while the dropped + body is swept after the grace window. (ADR-0038 addendum.) - **Phase 32 — In-binary TLS (`sc+https://`).** Closes the audit's High #1 (plaintext bearer tokens/traffic on `sc+http://`) and ADR-0036's "no TLS" @@ -872,11 +876,6 @@ scale-&-reach horizon): ` requires an explicit path today; auto-discovering a conventional transcript location (e.g. an agent-runner-written temp file) per workspace is deferred. -- **`sc transcript drop` + resurrection tombstone (P30).** There is no - command to remove an attached transcript short of gc-by-unreachability; - a first-class drop with a tombstone (so a later merge of a pre-drop - branch can't silently resurrect it, mirroring P16's revocation - tombstones) is deferred. - **Transcript access lifecycle (P30).** Transcripts have no rewrap/grant/revoke surface — sealed once, to the recipient set at attach time, permanently. Extending P17's rewrap and P16's diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 7efe3e88..ee941f69 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -591,6 +591,15 @@ enum TranscriptOp { #[arg(long)] json: bool, }, + /// Drop a transcript by id (or unique id prefix) from `sc transcript + /// list`. Records a tombstone that travels with fetch/push, so a peer + /// that still has the transcript cannot bring it back; `sc gc` reclaims + /// the body after its grace window. Not erasure: peers that never + /// receive the tombstone keep the sealed body. + Drop { + /// Transcript id as shown by `sc transcript list` (hex prefix). + id: String, + }, /// Sign every transcript attached to a ref's tip snapshot. Sign { /// Branch or remote-tracking ref whose tip snapshot's transcripts @@ -3003,6 +3012,11 @@ fn run_transcript(op: TranscriptOp) -> Result<()> { } Ok(()) } + TranscriptOp::Drop { id } => { + let tid = repo.drop_transcript(&id)?; + println!("dropped transcript {}", tid.short()); + Ok(()) + } TranscriptOp::Sign { r#ref, identity } => { let tip = resolve_ref_tip(&repo, &r#ref)?; let ident = load_identity_full(identity)?; diff --git a/crates/cli/tests/transcripts.rs b/crates/cli/tests/transcripts.rs index fa25209d..9b63472d 100644 --- a/crates/cli/tests/transcripts.rs +++ b/crates/cli/tests/transcripts.rs @@ -288,3 +288,59 @@ fn ws_harvest_transcript_prints_landing_before_reporting_attach_failure() { std::fs::remove_dir_all(&root).unwrap(); } + +#[test] +fn drop_removes_transcript_from_list_and_show() { + let root = tmp("drop"); + let repo = root.join("work"); + std::fs::create_dir_all(&repo).unwrap(); + let keys = root.join("keys"); + std::fs::create_dir_all(&keys).unwrap(); + let (id, enc_pk, _sig_pk) = keygen(&keys, "alice"); + assert!(sc(&repo, &["init"]).status.success()); + std::fs::write( + repo.join(".sc/recipients.toml"), + format!("[recipients]\nalice = \"{enc_pk}\"\n"), + ) + .unwrap(); + std::fs::write(repo.join("a.txt"), "hello\n").unwrap(); + assert!(sc(&repo, &["commit", "-m", "c1"]).status.success()); + let body = keys.join("session.txt"); + std::fs::write(&body, "USER: hi\n").unwrap(); + assert!(sc( + &repo, + &["transcript", "attach", "main", body.to_str().unwrap()] + ) + .status + .success()); + + let list = stdout(&sc(&repo, &["transcript", "list", "--json"])); + let tid = serde_json::from_str::(&list).unwrap()[0]["transcript"] + .as_str() + .unwrap() + .to_string(); + + let drop = sc(&repo, &["transcript", "drop", &tid[..12]]); + assert!( + drop.status.success(), + "{}", + String::from_utf8_lossy(&drop.stderr) + ); + assert!(stdout(&sc(&repo, &["transcript", "list"])).contains("no transcripts")); + let show = stdout(&sc( + &repo, + &[ + "transcript", + "show", + "main", + "--identity", + id.to_str().unwrap(), + ], + )); + assert!(show.contains("no transcripts attached"), "{show}"); + assert!( + !sc(&repo, &["transcript", "drop", &tid]).status.success(), + "dropping twice is an error" + ); + std::fs::remove_dir_all(&root).unwrap(); +} diff --git a/crates/core/src/object.rs b/crates/core/src/object.rs index 5505b0e0..a2904c9c 100644 --- a/crates/core/src/object.rs +++ b/crates/core/src/object.rs @@ -213,6 +213,36 @@ pub struct Transcript { pub wrapped_keys: Vec, } +impl Transcript { + /// `agent` marker of a drop tombstone (ADR-0038 addendum). + pub const DROP_AGENT: &'static str = "sc-transcript-drop-v1"; + + /// The tombstone for transcript `dropped` on `snapshot`: a transcript-shaped + /// object with no envelope, so it rides existing packs with no wire change. + pub fn drop_tombstone(snapshot: ObjectId, dropped: &ObjectId) -> Self { + Transcript { + snapshot, + agent: Self::DROP_AGENT.to_string(), + session: dropped.to_hex(), + nonce: Vec::new(), + ciphertext: Vec::new(), + wrapped_keys: Vec::new(), + } + } + + /// The transcript id this object drops, or `None` for a real transcript + /// (a sealed one always has a ciphertext and at least one wrap). + pub fn dropped_id(&self) -> Option { + let bare = + self.nonce.is_empty() && self.ciphertext.is_empty() && self.wrapped_keys.is_empty(); + if bare && self.agent == Self::DROP_AGENT { + self.session.parse().ok() + } else { + None + } + } +} + /// A sealed private-branch object (P34, ADR-0044): the canonical encoding of /// some inner object (snapshot, tree, or blob) encrypted under a fresh random /// per-object DEK — payload is `nonce(24) ‖ AEAD ciphertext`. Which inner kind @@ -1135,6 +1165,22 @@ mod tests { ); } + #[test] + fn drop_tombstone_round_trips_and_is_distinct_from_a_real_transcript() { + let snap = ObjectId::of(b"snap"); + let dropped = ObjectId::of(b"dropped"); + let tomb = Transcript::drop_tombstone(snap, &dropped); + let back = Object::decode(&Object::Transcript(tomb.clone()).encode()).unwrap(); + assert_eq!(back, Object::Transcript(tomb.clone())); + assert_eq!(tomb.dropped_id(), Some(dropped)); + // Same agent marker but a real envelope is not a tombstone. + let real = Transcript { + ciphertext: vec![1], + ..tomb + }; + assert_eq!(real.dropped_id(), None); + } + #[test] fn transcript_decode_rejects_fabricated_wrap_count() { // TAG_TRANSCRIPT(6) + snapshot(32) + agent str(0) + session str(0) diff --git a/crates/gitio/src/export.rs b/crates/gitio/src/export.rs index f6791966..7a210f5b 100644 --- a/crates/gitio/src/export.rs +++ b/crates/gitio/src/export.rs @@ -439,7 +439,7 @@ fn count_transcripts( let mut count = 0; for id in store.all_ids()? { if let Object::Transcript(t) = store.get(&id)? { - if seen_snaps.contains(&t.snapshot) { + if seen_snaps.contains(&t.snapshot) && t.dropped_id().is_none() { count += 1; } } diff --git a/crates/repo/src/gc.rs b/crates/repo/src/gc.rs index 6f0bf71f..b133c718 100644 --- a/crates/repo/src/gc.rs +++ b/crates/repo/src/gc.rs @@ -787,6 +787,46 @@ mod tests { std::fs::remove_dir_all(&root).unwrap(); } + #[test] + fn gc_reclaims_a_dropped_transcript_and_keeps_its_tombstone() { + let root = tmp_root("transcript-drop"); + let repo = crate::repo::Repo::init(&root).unwrap(); + std::fs::write(root.join("a.txt"), b"base").unwrap(); + let base = repo.commit("t", "base").unwrap(); + let (_s, identity) = scl_crypto::generate_identity_v2(); + let keep = repo + .attach_transcript(base, "a", "keep", b"keep", &[identity.enc.public()]) + .unwrap(); + let gone = repo + .attach_transcript(base, "a", "gone", b"gone", &[identity.enc.public()]) + .unwrap(); + repo.sign_transcript(gone, &identity).unwrap(); + repo.drop_transcript(&gone.to_hex()).unwrap(); + + repo.gc(Duration::from_secs(0)).unwrap(); + + let tomb = { + let drops = std::fs::read_to_string(repo.layout().transcript_drops_path()).unwrap(); + let line = drops.lines().next().expect("tombstone line survives gc"); + line.split_whitespace() + .nth(1) + .unwrap() + .parse::() + .unwrap() + }; + let arc = repo.vfs().store(); + let s = arc.lock().unwrap(); + assert!(!s.contains(&gone), "dropped body is reclaimed"); + assert!(s.contains(&keep), "other transcripts survive"); + assert!(s.contains(&tomb), "tombstone is rooted"); + drop(s); + assert!(repo.signatures_for(&gone).unwrap().is_empty()); + assert_eq!(transcripts::load(repo.layout()).unwrap().len(), 1); + + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } + /// Build a repo at `root` with `src/a.txt` and `docs/b.txt` in separate /// subtrees, one commit. Returns `(repo, src blob id, docs blob id)`. fn tmp_repo_with_src_and_docs( diff --git a/crates/repo/src/layout.rs b/crates/repo/src/layout.rs index 87ab597f..6ba9db37 100644 --- a/crates/repo/src/layout.rs +++ b/crates/repo/src/layout.rs @@ -84,6 +84,12 @@ impl Layout { pub fn transcripts_path(&self) -> PathBuf { self.dot_sc.join("transcripts") } + /// `.sc/transcript-drops` — the transcript drop-tombstone index (ADR-0038 + /// addendum): one ` ` line per + /// dropped transcript. Never pruned by gc. + pub fn transcript_drops_path(&self) -> PathBuf { + self.dot_sc.join("transcript-drops") + } /// `.sc/tmp` — scratch space for transient files (P25 streaming pack /// transfer: spilled sender/receiver pack bodies). Never durable state — /// safe to delete at any time; callers that write here are responsible diff --git a/crates/repo/src/sync.rs b/crates/repo/src/sync.rs index 5ca6a6a7..7c9ce380 100644 --- a/crates/repo/src/sync.rs +++ b/crates/repo/src/sync.rs @@ -869,6 +869,53 @@ mod tests { std::fs::remove_dir_all(&b_root).unwrap(); } + #[test] + fn dropped_transcript_is_not_resurrected_by_fetch_and_the_drop_propagates() { + let pid = std::process::id(); + let a_root = std::env::temp_dir().join(format!("scl-transdrop-a-{pid}")); + let b_root = std::env::temp_dir().join(format!("scl-transdrop-b-{pid}")); + let _ = std::fs::remove_dir_all(&a_root); + let _ = std::fs::remove_dir_all(&b_root); + std::fs::create_dir_all(&a_root).unwrap(); + + let a = Repo::init(&a_root).unwrap(); + std::fs::write(a_root.join("f1"), b"one").unwrap(); + let snap = a.commit("t", "c1").unwrap(); + let (_s, identity) = scl_crypto::generate_identity_v2(); + let tid = a + .attach_transcript(snap, "claude-code", "s1", b"body", &[identity.enc.public()]) + .unwrap(); + let b = Repo::clone_to(&a_root, &b_root).unwrap(); + assert_eq!(b.transcripts_for(&snap).unwrap().len(), 1); + drop(a); + + // B drops it; origin A still carries it. Fetching must not restore it. + b.drop_transcript(&tid.to_hex()).unwrap(); + b.fetch("origin").unwrap(); + assert!(b.transcripts_for(&snap).unwrap().is_empty()); + drop(b); + + // A fetching from B learns the drop and hides its own copy. + let a = Repo::open(&a_root).unwrap(); + assert_eq!(a.transcripts_for(&snap).unwrap().len(), 1); + a.remote_add("b", b_root.to_str().unwrap()).unwrap(); + a.fetch("b").unwrap(); + assert!(a.transcripts_for(&snap).unwrap().is_empty()); + drop(a); + + // A fresh clone of A (which still holds the body object) gets the + // tombstone via reindex and shows nothing. + let c_root = std::env::temp_dir().join(format!("scl-transdrop-c-{pid}")); + let _ = std::fs::remove_dir_all(&c_root); + let c = Repo::clone_to(&a_root, &c_root).unwrap(); + assert!(c.transcripts_for(&snap).unwrap().is_empty()); + + drop(c); + std::fs::remove_dir_all(&a_root).unwrap(); + std::fs::remove_dir_all(&b_root).unwrap(); + std::fs::remove_dir_all(&c_root).unwrap(); + } + #[test] fn signatures_ride_ssh_transport() { // The wire-protocol pipe harness `WireClient` <-> `wire::serve` IS diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index 2bb6ebaf..66ad90c5 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -18,6 +18,12 @@ //! `gc` rewrites the file atomically when it prunes dead entries; every //! other writer treats the file as append-only. Mirrors `signatures.rs`'s //! index discipline verbatim. +//! +//! Drops (ADR-0038 addendum): a second file `.sc/transcript-drops` holds one +//! ` ` line per drop tombstone (a +//! bare `Transcript`, see `Transcript::drop_tombstone`). The grow-only set of +//! dropped ids filters every read of the live index, so a dropped transcript +//! stays invisible whatever order its lines and objects arrive in. use std::collections::BTreeSet; @@ -42,7 +48,9 @@ fn parse_line(line: &str) -> Option<(ObjectId, ObjectId)> { Some((snap, tid)) } -fn read_index(layout: &Layout) -> Result> { +/// The live index file as written, including entries a tombstone has since +/// hidden (gc purges those). +fn read_raw(layout: &Layout) -> Result> { let path = layout.transcripts_path(); let contents = match std::fs::read_to_string(&path) { Ok(s) => s, @@ -52,6 +60,62 @@ fn read_index(layout: &Layout) -> Result> { Ok(contents.lines().filter_map(parse_line).collect()) } +/// The live index minus every dropped transcript. +fn read_index(layout: &Layout) -> Result> { + let dropped = dropped_ids(layout)?; + Ok(read_raw(layout)? + .into_iter() + .filter(|(_, tid)| !dropped.contains(tid)) + .collect()) +} + +/// One drop-tombstone line: `(snapshot, tombstone object, dropped transcript)`. +type DropEntry = (ObjectId, ObjectId, ObjectId); + +fn read_drops(layout: &Layout) -> Result> { + let contents = match std::fs::read_to_string(layout.transcript_drops_path()) { + Ok(s) => s, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()), + Err(e) => return Err(Error::Io(e)), + }; + Ok(contents + .lines() + .filter_map(|line| { + let mut p = line.split_whitespace().map(|f| f.parse::().ok()); + let e = (p.next()??, p.next()??, p.next()??); + p.next().is_none().then_some(e) + }) + .collect()) +} + +fn write_drops(layout: &Layout, entries: &[DropEntry]) -> Result<()> { + let mut out = String::new(); + for (snap, tomb, dropped) in entries { + out.push_str(&format!( + "{} {} {}\n", + snap.to_hex(), + tomb.to_hex(), + dropped.to_hex() + )); + } + scl_core::fsutil::atomic_write_durable(&layout.transcript_drops_path(), out.as_bytes())?; + Ok(()) +} + +fn dropped_ids(layout: &Layout) -> Result> { + Ok(read_drops(layout)?.into_iter().map(|(_, _, d)| d).collect()) +} + +/// Record one tombstone, deduping an identical existing line. +fn append_drop(layout: &Layout, entry: DropEntry) -> Result<()> { + let mut entries = read_drops(layout)?; + if !entries.contains(&entry) { + entries.push(entry); + write_drops(layout, &entries)?; + } + Ok(()) +} + /// Rewrite the whole index file atomically (temp file + rename), so a /// concurrent reader never observes a half-written index. fn write_index(layout: &Layout, entries: &[(ObjectId, ObjectId)]) -> Result<()> { @@ -70,6 +134,9 @@ pub(crate) fn append_index( snapshot: ObjectId, transcript_id: ObjectId, ) -> Result<()> { + if dropped_ids(layout)?.contains(&transcript_id) { + return Ok(()); + } let mut entries = read_index(layout)?; if entries .iter() @@ -101,22 +168,30 @@ pub fn load(layout: &Layout) -> Result> { /// Returns the number of dropped entries (0 when nothing needed pruning, in /// which case the index file is left untouched rather than rewritten). pub(crate) fn gc_prune(layout: &Layout, reachable: &mut BTreeSet) -> Result { - let entries = read_index(layout)?; - if entries.is_empty() { - return Ok(0); - } + // Tombstones are load-bearing against resurrection: root them (and keep + // their lines) even when their snapshot is dead. The dropped transcript + // itself is never rooted, so it is swept after the grace window. + let drops = read_drops(layout)?; + reachable.extend(drops.iter().map(|(_, tomb, _)| *tomb)); + let dropped: BTreeSet = drops.iter().map(|(_, _, d)| *d).collect(); + let entries = read_raw(layout)?; let mut kept = Vec::with_capacity(entries.len()); + let mut dead = 0; for (snap, tid) in &entries { + if dropped.contains(tid) { + continue; + } if reachable.contains(snap) { reachable.insert(*tid); kept.push((*snap, *tid)); + } else { + dead += 1; } } - let dropped = entries.len() - kept.len(); - if dropped > 0 { + if kept.len() != entries.len() { write_index(layout, &kept)?; } - Ok(dropped) + Ok(dead) } /// Receiver-side seam (Task 3/4): given a batch of object ids just written @@ -139,7 +214,10 @@ pub(crate) fn index_incoming( let mut count = 0; for id in ids { if let Object::Transcript(t) = store.get(id)? { - append_index(layout, t.snapshot, *id)?; + match t.dropped_id() { + Some(dropped) => append_drop(layout, (t.snapshot, *id, dropped))?, + None => append_index(layout, t.snapshot, *id)?, + } count += 1; } } @@ -154,22 +232,32 @@ pub(crate) fn index_incoming( /// stale entries from a half-written prior index are dropped too). pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result { let mut entries: Vec<(ObjectId, ObjectId)> = Vec::new(); + let mut drops: Vec = Vec::new(); for id in store.all_ids()? { if let Object::Transcript(t) = store.get(&id)? { - if store.contains(&t.snapshot) { - entries.push((t.snapshot, id)); + if !store.contains(&t.snapshot) { + continue; + } + match t.dropped_id() { + Some(dropped) => drops.push((t.snapshot, id, dropped)), + None => entries.push((t.snapshot, id)), } } } + drops.sort(); + drops.dedup(); + let dropped: BTreeSet = drops.iter().map(|(_, _, d)| *d).collect(); + entries.retain(|(_, tid)| !dropped.contains(tid)); entries.sort(); entries.dedup(); let count = entries.len(); write_index(layout, &entries)?; + write_drops(layout, &drops)?; Ok(count) } -/// Sender-side seam (Task 3/4): the indexed transcript object ids covering -/// any of `snapshots`, deduped and sorted — the set a push/export needs to +/// Sender-side seam (Task 3/4): the indexed transcript object ids (and drop +/// tombstones) covering any of `snapshots`, deduped and sorted — the set a push/export needs to /// carry alongside the snapshots themselves so the receiving repo's index /// stays complete. pub(crate) fn indexed_transcript_ids_for( @@ -183,6 +271,12 @@ pub(crate) fn indexed_transcript_ids_for( out.insert(tid); } } + // Tombstones travel with their snapshot so a drop propagates. + for (snap, tomb, _) in read_drops(layout)? { + if wanted.contains(&snap) { + out.insert(tomb); + } + } Ok(out.into_iter().collect()) } @@ -240,6 +334,39 @@ impl Repo { Ok(id) } + /// Drop the live transcript whose id starts with `id_prefix`: store a drop + /// tombstone and record it, so the transcript vanishes from `list`/`show` + /// and no later fetch can restore it (ADR-0038 addendum). The body object + /// is reclaimed by `gc` after its grace window. Returns the dropped id. + pub fn drop_transcript(&self, id_prefix: &str) -> Result { + let prefix = id_prefix.to_ascii_lowercase(); + let matches: BTreeSet<(ObjectId, ObjectId)> = read_index(self.layout())? + .into_iter() + .filter(|(_, tid)| !prefix.is_empty() && tid.to_hex().starts_with(&prefix)) + .collect(); + let mut it = matches.into_iter(); + let (snap, tid) = match (it.next(), it.next()) { + (Some(m), None) => m, + (None, _) => { + return Err(Error::InvalidArgument(format!( + "no live transcript matches {id_prefix:?} (see `sc transcript list`)" + ))) + } + _ => { + return Err(Error::InvalidArgument(format!( + "transcript id prefix {id_prefix:?} is ambiguous" + ))) + } + }; + let tomb = { + let arc = self.store_arc(); + let mut store = arc.lock().unwrap(); + store.put(Object::Transcript(Transcript::drop_tombstone(snap, &tid)))? + }; + append_drop(self.layout(), (snap, tomb, tid))?; + Ok(tid) + } + /// All indexed transcripts for `snapshot`, loaded from the CAS (id + /// object, still sealed — opening them is Task 3). pub fn transcripts_for(&self, snapshot: &ObjectId) -> Result> { @@ -459,4 +586,74 @@ mod tests { drop(repo); std::fs::remove_dir_all(&root).unwrap(); } + + #[test] + fn drop_hides_transcript_and_blocks_resurrection_in_either_order() { + let root = tmp_root("drop"); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("f"), b"x").unwrap(); + let snap = repo.commit("t", "c1").unwrap(); + let (_s, id) = scl_crypto::generate_identity_v2(); + let keep = repo + .attach_transcript(snap, "a", "keep", b"keep", &[id.enc.public()]) + .unwrap(); + let gone = repo + .attach_transcript(snap, "a", "gone", b"gone", &[id.enc.public()]) + .unwrap(); + + // Prefix resolution: empty and unknown prefixes are refused. + assert!(repo.drop_transcript("").is_err()); + assert!(repo.drop_transcript("zz").is_err()); + + assert_eq!(repo.drop_transcript(&gone.to_hex()[..12]).unwrap(), gone); + let live: Vec<_> = repo + .transcripts_for(&snap) + .unwrap() + .into_iter() + .map(|(t, _)| t) + .collect(); + assert_eq!(live, vec![keep], "only the kept transcript is listed"); + assert!( + repo.drop_transcript(&gone.to_hex()).is_err(), + "a dropped id is no longer live" + ); + + // Resurrection attempt: a fetch re-indexes the dropped body. + append_index(repo.layout(), snap, gone).unwrap(); + assert!(load(repo.layout()).unwrap().iter().all(|(_, t)| *t != gone)); + + // Opposite order: a receiver that sees the body BEFORE the tombstone. + let other_root = tmp_root("drop-order"); + let other = Repo::init(&other_root).unwrap(); + append_index(other.layout(), snap, gone).unwrap(); + assert_eq!(load(other.layout()).unwrap().len(), 1); + let tomb = { + let arc = repo.store_arc(); + let mut store = arc.lock().unwrap(); + store + .put(Object::Transcript(Transcript::drop_tombstone(snap, &gone))) + .unwrap() + }; + { + let arc = other.store_arc(); + let mut store = arc.lock().unwrap(); + store + .put(Object::Transcript(Transcript::drop_tombstone(snap, &gone))) + .unwrap(); + index_incoming(other.layout(), &mut store, &[tomb]).unwrap(); + } + assert!( + load(other.layout()).unwrap().is_empty(), + "an incoming tombstone hides an already-indexed transcript" + ); + // The sender ships the tombstone with its snapshot. + assert!(indexed_transcript_ids_for(repo.layout(), &[snap]) + .unwrap() + .contains(&tomb)); + + drop(repo); + drop(other); + std::fs::remove_dir_all(&root).unwrap(); + std::fs::remove_dir_all(&other_root).unwrap(); + } } diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index f00424a7..357433e1 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -148,3 +148,93 @@ pipe-safety discipline). Also does not defend: secrets echoed into a transcript remaining readable to *authorized* transcript recipients (scan-and-warn mitigates, rotation remedies); content quality or truthfulness of the recorded session. + +## Addendum: `sc transcript drop` and the drop tombstone (issue #212) + +Closes the deferral in D6 and the "Deletion semantics deferred" consequence. + +### Tombstone format + +A drop is recorded as a **drop tombstone: a `Transcript` object with an +empty `nonce`, `ciphertext` and `wrapped_keys`**, `agent` set to the marker +`sc-transcript-drop-v1`, `snapshot` copied from the dropped transcript, and +`session` set to the hex id of the dropped transcript. A real transcript is +always sealed to at least one recipient, so it never has an empty ciphertext +or wrap list; the two shapes cannot collide. `core` exposes +`Transcript::drop_tombstone` / `Transcript::dropped_id` (bytes only, no new +crypto). + +Reusing `TAG_TRANSCRIPT` is deliberate. A new object tag would be refused by +peers that predate it and force a `PROTOCOL_VERSION` bump (the P34 route). A +tombstone shaped as a transcript decodes everywhere and rides the existing +pack format, the existing `snapshot -> transcripts` over-send and the +existing receiver seam (`index_incoming`) with no wire change. + +### Semantics: grow-only set, not an epoch register + +P16 needs a last-writer-wins epoch because a recipient can be revoked and +then legitimately re-granted. A transcript cannot come back under the same +id: transcript ids are content hashes over a randomly sealed envelope, so +re-attaching a body mints a new id. Each `(snapshot, dropped id)` pair +therefore has exactly one transition, live to dropped, and the register +collapses to a grow-only set of dropped ids. A concurrent drop and keep +always resolve to dropped (the P16 tie rule, fail-closed). There is no +undrop; to restore a body, attach it again. + +### Local index and convergence + +A second local file, `.sc/transcript-drops`, holds one +` ` line per tombstone. It is a +derived cache like `.sc/transcripts`: `sc clone` rebuilds it with the same +full-store scan (`reindex`). The live index is read through the drop set, so +a dropped id is invisible to `list`, `show`, `sc log` markers and the +over-send, whatever order the lines landed in. + +- **drop:** write the tombstone object, append the drop line, then remove the + live entry. A crash between steps leaves the drop line present, so the + transcript is still hidden (fail-closed). +- **fetch/clone/push receive:** `index_incoming` records an incoming + tombstone as a drop and never indexes a transcript whose id is already + dropped, so a pack from a peer that still has the transcript cannot + restore it, in either arrival order. +- **sender:** the over-send for a transfer set includes the tombstones of its + snapshots, so fetching from the dropper (or a push that moves the ref) + propagates the drop. A peer that still holds the transcript object hides + it as soon as it ingests the tombstone. `push` still skips all I/O when + the remote tip already equals the local tip, so a drop alone does not push, + the same pre-existing behavior as a retroactive attach. +- **merge, cherry-pick, rebase:** transcripts are not part of snapshots, so + history operations neither carry nor restore them; only transfer can + reintroduce one, and that path is covered above. + +### gc + +The dropped transcript is no longer rooted, so its object falls to the +ordinary loose-object grace window and repack like any other unreachable +object, and its own signature entry is pruned with it (`signatures::gc_prune` +keys off the same `reachable` set). Tombstones are the opposite: gc roots +every tombstone object and keeps every drop line, **even when its snapshot is +dead**, as P16 keeps revocation tombstones forever. They are load-bearing +against a later fetch of the same history from a stale peer, and cost about +100 bytes each. This is the one place the drop index outlives its snapshot; +no transcript content does. + +### `sc verify` + +`sc verify` checks snapshot signatures only and never inspects transcripts, +so it is unchanged. A dropped transcript's own signature is no longer +reported anywhere (it is pruned by gc, hidden before that). + +### Limits + +- **Drop is not authenticated.** Anyone who can write to a store can drop any + transcript, the same trust level as attaching one. Signed drops are a + follow-on. +- **Drop is not erasure.** Peers that never receive the tombstone keep the + sealed body, and a recipient who already decrypted it keeps the plaintext. + Rotation is not erasure here either. +- **Older peers** that predate this change see a tombstone as an unopenable + transcript and do not honor it. Upgrade before relying on drop across a + shared remote. +- `sc export` still counts only transcripts that are not tombstones; a + dropped body that gc has not swept yet is still counted as dropped history. From 4143fb600435ccf2b46e794744a1644908e8651b Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 08:52:25 +0300 Subject: [PATCH 2/8] fix(repo,cli): authenticate incoming transcript drop tombstones (ref #212) An unsigned tombstone let any peer hide a transcript and let gc reclaim it. Receivers now honor a tombstone only when its snapshot exists locally, the dropped transcript (if held) is on the same snapshot, and a signature over the tombstone id comes from a key under [signers] trusted. sc transcript drop gains --identity to sign; an unsigned drop stays local-only. --- .claude/skills/sc-cli-reference/SKILL.md | 9 +- crates/cli/src/main.rs | 16 +- crates/cli/tests/transcripts.rs | 11 +- crates/repo/src/gc.rs | 8 +- crates/repo/src/sync.rs | 14 +- crates/repo/src/transcripts.rs | 206 +++++++++++++++++---- docs/adr/0038-agent-session-transcripts.md | 51 ++++- 7 files changed, 259 insertions(+), 56 deletions(-) diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index 7108a728..ce124aca 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -220,12 +220,13 @@ cargo run --bin sc -- transcript show [--identity ] # decrypt + pri cargo run --bin sc -- transcript list [] [--json] # list transcripts (never decrypts) cargo run --bin sc -- transcript sign [--identity ] # retroactively sign a tip's # transcript(s) (P30) -cargo run --bin sc -- transcript drop # drop a transcript by id/hex prefix (see `list`): writes +cargo run --bin sc -- transcript drop [--identity ] # drop a transcript by id/hex prefix (see `list`): writes # a tombstone that travels with fetch/clone so a peer # that still has it cannot restore it; gc reclaims the - # body after the grace window. Not erasure; propagates - # on the peer's next fetch (push at an equal tip sends - # nothing). (ADR-0038 addendum) + # body after the grace window. Not erasure. --identity + # signs the tombstone; peers honor it only if that key + # is under [signers] trusted (unsigned = local-only). + # Propagates on the peer's next fetch (ADR-0038 addendum) cargo run --bin sc -- ws harvest --transcript [--sign] [--identity ] # attach the # file to each harvested workspace's landed snapshot # (P30; landing status prints before the attach) diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index ee941f69..cdcd9ca0 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -595,10 +595,16 @@ enum TranscriptOp { /// list`. Records a tombstone that travels with fetch/push, so a peer /// that still has the transcript cannot bring it back; `sc gc` reclaims /// the body after its grace window. Not erasure: peers that never - /// receive the tombstone keep the sealed body. + /// receive the tombstone keep the sealed body. Without `--identity` the + /// drop is local-only: peers honor a tombstone only when it is signed by + /// a key in their `[signers] trusted` list. Drop { /// Transcript id as shown by `sc transcript list` (hex prefix). id: String, + /// Sign the tombstone with this v2 identity so trusting peers honor + /// it (default: unsigned, local-only). + #[arg(long)] + identity: Option, }, /// Sign every transcript attached to a ref's tip snapshot. Sign { @@ -3012,9 +3018,13 @@ fn run_transcript(op: TranscriptOp) -> Result<()> { } Ok(()) } - TranscriptOp::Drop { id } => { - let tid = repo.drop_transcript(&id)?; + TranscriptOp::Drop { id, identity } => { + let signer = identity.map(|p| load_identity_full(Some(p))).transpose()?; + let tid = repo.drop_transcript(&id, signer.as_ref())?; println!("dropped transcript {}", tid.short()); + if signer.is_none() { + eprintln!("note: unsigned drop is local-only; pass --identity to let trusting peers honor it"); + } Ok(()) } TranscriptOp::Sign { r#ref, identity } => { diff --git a/crates/cli/tests/transcripts.rs b/crates/cli/tests/transcripts.rs index 9b63472d..02f65c5f 100644 --- a/crates/cli/tests/transcripts.rs +++ b/crates/cli/tests/transcripts.rs @@ -320,7 +320,16 @@ fn drop_removes_transcript_from_list_and_show() { .unwrap() .to_string(); - let drop = sc(&repo, &["transcript", "drop", &tid[..12]]); + let drop = sc( + &repo, + &[ + "transcript", + "drop", + &tid[..12], + "--identity", + id.to_str().unwrap(), + ], + ); assert!( drop.status.success(), "{}", diff --git a/crates/repo/src/gc.rs b/crates/repo/src/gc.rs index b133c718..4cf84097 100644 --- a/crates/repo/src/gc.rs +++ b/crates/repo/src/gc.rs @@ -801,7 +801,8 @@ mod tests { .attach_transcript(base, "a", "gone", b"gone", &[identity.enc.public()]) .unwrap(); repo.sign_transcript(gone, &identity).unwrap(); - repo.drop_transcript(&gone.to_hex()).unwrap(); + repo.drop_transcript(&gone.to_hex(), Some(&identity)) + .unwrap(); repo.gc(Duration::from_secs(0)).unwrap(); @@ -821,6 +822,11 @@ mod tests { assert!(s.contains(&tomb), "tombstone is rooted"); drop(s); assert!(repo.signatures_for(&gone).unwrap().is_empty()); + assert_eq!( + repo.signatures_for(&tomb).unwrap().len(), + 1, + "the tombstone's signature is kept with it" + ); assert_eq!(transcripts::load(repo.layout()).unwrap().len(), 1); drop(repo); diff --git a/crates/repo/src/sync.rs b/crates/repo/src/sync.rs index 7c9ce380..0e4f50bb 100644 --- a/crates/repo/src/sync.rs +++ b/crates/repo/src/sync.rs @@ -890,7 +890,8 @@ mod tests { drop(a); // B drops it; origin A still carries it. Fetching must not restore it. - b.drop_transcript(&tid.to_hex()).unwrap(); + crate::transcripts::tests::trust_signer(&b, &identity); + b.drop_transcript(&tid.to_hex(), Some(&identity)).unwrap(); b.fetch("origin").unwrap(); assert!(b.transcripts_for(&snap).unwrap().is_empty()); drop(b); @@ -898,13 +899,20 @@ mod tests { // A fetching from B learns the drop and hides its own copy. let a = Repo::open(&a_root).unwrap(); assert_eq!(a.transcripts_for(&snap).unwrap().len(), 1); + // The origin only honors tombstones from a signer it trusts. a.remote_add("b", b_root.to_str().unwrap()).unwrap(); a.fetch("b").unwrap(); + assert_eq!( + a.transcripts_for(&snap).unwrap().len(), + 1, + "an untrusted signer's tombstone is ignored" + ); + crate::transcripts::tests::trust_signer(&a, &identity); + a.fetch("b").unwrap(); assert!(a.transcripts_for(&snap).unwrap().is_empty()); drop(a); - // A fresh clone of A (which still holds the body object) gets the - // tombstone via reindex and shows nothing. + // A fresh clone of A never receives the dropped body at all. let c_root = std::env::temp_dir().join(format!("scl-transdrop-c-{pid}")); let _ = std::fs::remove_dir_all(&c_root); let c = Repo::clone_to(&a_root, &c_root).unwrap(); diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index 66ad90c5..cb282684 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -148,6 +148,73 @@ pub(crate) fn append_index( write_index(layout, &entries) } +/// `[signing]` keys listed under `[signers] trusted` in `.sc/recipients.toml`: +/// the same trust set `sc verify` uses. Unreadable or malformed config yields +/// an empty set, so remote tombstones are ignored (fail-closed). +fn trusted_signers(layout: &Layout) -> std::collections::HashMap<[u8; 32], String> { + #[derive(serde::Deserialize, Default)] + struct Signers { + #[serde(default)] + trusted: Vec, + } + #[derive(serde::Deserialize, Default)] + struct TrustFile { + #[serde(default)] + signing: std::collections::BTreeMap, + #[serde(default)] + signers: Option, + } + let parsed: TrustFile = std::fs::read_to_string(layout.dot_sc.join("recipients.toml")) + .ok() + .and_then(|t| toml::from_str(&t).ok()) + .unwrap_or_default(); + let mut out = std::collections::HashMap::new(); + for name in parsed.signers.unwrap_or_default().trusted { + if let Some(pk) = parsed + .signing + .get(&name) + .and_then(|k| scl_crypto::SigPublicKey::from_key_string(k).ok()) + { + out.insert(pk.to_bytes(), name); + } + } + out +} + +/// Whether an incoming tombstone may hide its transcript (ADR-0038 addendum, +/// "Who may drop"). All of: the tombstone's snapshot exists locally; if the +/// dropped transcript is held locally it is a real transcript on that same +/// snapshot; and a signature over the tombstone id verifies under a key in +/// `trusted`. An unsigned or untrusted tombstone stays an inert object. +fn tombstone_honored( + layout: &Layout, + store: &mut scl_core::Store, + trusted: &std::collections::HashMap<[u8; 32], String>, + tomb: ObjectId, + t: &Transcript, + dropped: ObjectId, +) -> Result { + if !store.contains(&t.snapshot) { + return Ok(false); + } + if store.contains(&dropped) { + match store.get(&dropped)? { + Object::Transcript(d) if d.dropped_id().is_none() && d.snapshot == t.snapshot => {} + _ => return Ok(false), + } + } + for sid in crate::signatures::indexed_signature_ids_for(layout, &[tomb])? { + if let Object::Signature(sig) = store.get(&sid)? { + if trusted.contains_key(&sig.signer) + && scl_crypto::verify_transcript_sig(&sig.signer, tomb.as_bytes(), &sig.sig) + { + return Ok(true); + } + } + } + Ok(false) +} + /// Public snapshot->transcript index (one-to-many), for lookup/tests. pub fn load(layout: &Layout) -> Result> { read_index(layout) @@ -212,10 +279,16 @@ pub(crate) fn index_incoming( ids: &[ObjectId], ) -> Result { let mut count = 0; + let trusted = trusted_signers(layout); for id in ids { if let Object::Transcript(t) = store.get(id)? { match t.dropped_id() { - Some(dropped) => append_drop(layout, (t.snapshot, *id, dropped))?, + Some(dropped) => { + if !tombstone_honored(layout, store, &trusted, *id, &t, dropped)? { + continue; + } + append_drop(layout, (t.snapshot, *id, dropped))? + } None => append_index(layout, t.snapshot, *id)?, } count += 1; @@ -233,13 +306,18 @@ pub(crate) fn index_incoming( pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result { let mut entries: Vec<(ObjectId, ObjectId)> = Vec::new(); let mut drops: Vec = Vec::new(); + let trusted = trusted_signers(layout); for id in store.all_ids()? { if let Object::Transcript(t) = store.get(&id)? { if !store.contains(&t.snapshot) { continue; } match t.dropped_id() { - Some(dropped) => drops.push((t.snapshot, id, dropped)), + Some(dropped) => { + if tombstone_honored(layout, store, &trusted, id, &t, dropped)? { + drops.push((t.snapshot, id, dropped)); + } + } None => entries.push((t.snapshot, id)), } } @@ -338,7 +416,16 @@ impl Repo { /// tombstone and record it, so the transcript vanishes from `list`/`show` /// and no later fetch can restore it (ADR-0038 addendum). The body object /// is reclaimed by `gc` after its grace window. Returns the dropped id. - pub fn drop_transcript(&self, id_prefix: &str) -> Result { + /// + /// The local store always honors its own drop. With `signer`, the + /// tombstone is also signed (transcript domain) so peers whose + /// `[signers] trusted` list names that key honor it too; without one the + /// drop stays local-only (peers ignore an unsigned tombstone). + pub fn drop_transcript( + &self, + id_prefix: &str, + signer: Option<&scl_crypto::Identity>, + ) -> Result { let prefix = id_prefix.to_ascii_lowercase(); let matches: BTreeSet<(ObjectId, ObjectId)> = read_index(self.layout())? .into_iter() @@ -363,6 +450,9 @@ impl Repo { let mut store = arc.lock().unwrap(); store.put(Object::Transcript(Transcript::drop_tombstone(snap, &tid)))? }; + if let Some(identity) = signer { + self.sign_transcript(tomb, identity)?; + } append_drop(self.layout(), (snap, tomb, tid))?; Ok(tid) } @@ -478,7 +568,7 @@ impl Repo { } #[cfg(test)] -mod tests { +pub(crate) mod tests { use super::*; use crate::repo::Repo; @@ -587,8 +677,18 @@ mod tests { std::fs::remove_dir_all(&root).unwrap(); } + /// Trust `identity`'s signing key as `me` in `repo`'s recipients.toml. + pub(crate) fn trust_signer(repo: &Repo, identity: &scl_crypto::Identity) { + let key = identity.signing.as_ref().unwrap().public().to_key_string(); + std::fs::write( + repo.layout().dot_sc.join("recipients.toml"), + format!("[signing]\nme = \"{key}\"\n[signers]\ntrusted = [\"me\"]\n"), + ) + .unwrap(); + } + #[test] - fn drop_hides_transcript_and_blocks_resurrection_in_either_order() { + fn drop_hides_transcript_and_blocks_resurrection() { let root = tmp_root("drop"); let repo = Repo::init(&root).unwrap(); std::fs::write(root.join("f"), b"x").unwrap(); @@ -601,11 +701,14 @@ mod tests { .attach_transcript(snap, "a", "gone", b"gone", &[id.enc.public()]) .unwrap(); - // Prefix resolution: empty and unknown prefixes are refused. - assert!(repo.drop_transcript("").is_err()); - assert!(repo.drop_transcript("zz").is_err()); + // Empty and unknown prefixes are refused. + assert!(repo.drop_transcript("", None).is_err()); + assert!(repo.drop_transcript("zz", None).is_err()); - assert_eq!(repo.drop_transcript(&gone.to_hex()[..12]).unwrap(), gone); + assert_eq!( + repo.drop_transcript(&gone.to_hex()[..12], None).unwrap(), + gone + ); let live: Vec<_> = repo .transcripts_for(&snap) .unwrap() @@ -614,7 +717,7 @@ mod tests { .collect(); assert_eq!(live, vec![keep], "only the kept transcript is listed"); assert!( - repo.drop_transcript(&gone.to_hex()).is_err(), + repo.drop_transcript(&gone.to_hex(), None).is_err(), "a dropped id is no longer live" ); @@ -622,38 +725,69 @@ mod tests { append_index(repo.layout(), snap, gone).unwrap(); assert!(load(repo.layout()).unwrap().iter().all(|(_, t)| *t != gone)); - // Opposite order: a receiver that sees the body BEFORE the tombstone. - let other_root = tmp_root("drop-order"); - let other = Repo::init(&other_root).unwrap(); - append_index(other.layout(), snap, gone).unwrap(); - assert_eq!(load(other.layout()).unwrap().len(), 1); - let tomb = { - let arc = repo.store_arc(); + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } + + #[test] + fn incoming_tombstone_needs_a_trusted_signature_and_matching_snapshot() { + let root = tmp_root("forge"); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("f"), b"x").unwrap(); + let snap = repo.commit("t", "c1").unwrap(); + std::fs::write(root.join("f"), b"y").unwrap(); + let other_snap = repo.commit("t", "c2").unwrap(); + let (_s, owner) = scl_crypto::generate_identity_v2(); + let (_s, attacker) = scl_crypto::generate_identity_v2(); + let victim = repo + .attach_transcript(snap, "a", "v", b"victim", &[owner.enc.public()]) + .unwrap(); + trust_signer(&repo, &owner); + + let arc = repo.store_arc(); + let ingest = |tomb: Transcript, signer: Option<&scl_crypto::Identity>| -> bool { + let tomb_id = arc.lock().unwrap().put(Object::Transcript(tomb)).unwrap(); + if let Some(who) = signer { + repo.sign_transcript(tomb_id, who).unwrap(); + } let mut store = arc.lock().unwrap(); - store - .put(Object::Transcript(Transcript::drop_tombstone(snap, &gone))) + index_incoming(repo.layout(), &mut store, &[tomb_id]).unwrap(); + drop(store); + read_drops(repo.layout()) .unwrap() + .iter() + .any(|d| d.1 == tomb_id) }; - { - let arc = other.store_arc(); - let mut store = arc.lock().unwrap(); - store - .put(Object::Transcript(Transcript::drop_tombstone(snap, &gone))) - .unwrap(); - index_incoming(other.layout(), &mut store, &[tomb]).unwrap(); - } - assert!( - load(other.layout()).unwrap().is_empty(), - "an incoming tombstone hides an already-indexed transcript" - ); + + // Unsigned, signed by an untrusted key, and wrong-snapshot tombstones + // (even with a trusted signature) are all ignored. + let good = Transcript::drop_tombstone(snap, &victim); + assert!(!ingest(good.clone(), None)); + assert!(!ingest(good.clone(), Some(&attacker))); + assert!(!ingest( + Transcript::drop_tombstone(other_snap, &victim), + Some(&owner) + )); + // A tombstone for a snapshot this store has never seen is ignored too. + let unknown = ObjectId::of(b"unknown-snap"); + assert!(!ingest( + Transcript::drop_tombstone(unknown, &victim), + Some(&owner) + )); + assert_eq!(repo.transcripts_for(&snap).unwrap().len(), 1); + + // A trusted signature on a matching tombstone is honored. + assert!(ingest(good, Some(&owner))); + assert!(repo.transcripts_for(&snap).unwrap().is_empty()); // The sender ships the tombstone with its snapshot. - assert!(indexed_transcript_ids_for(repo.layout(), &[snap]) - .unwrap() - .contains(&tomb)); + assert_eq!( + indexed_transcript_ids_for(repo.layout(), &[snap]) + .unwrap() + .len(), + 1 + ); drop(repo); - drop(other); std::fs::remove_dir_all(&root).unwrap(); - std::fs::remove_dir_all(&other_root).unwrap(); } } diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index 357433e1..000c39f9 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -194,11 +194,14 @@ over-send, whatever order the lines landed in. live entry. A crash between steps leaves the drop line present, so the transcript is still hidden (fail-closed). - **fetch/clone/push receive:** `index_incoming` records an incoming - tombstone as a drop and never indexes a transcript whose id is already - dropped, so a pack from a peer that still has the transcript cannot - restore it, in either arrival order. -- **sender:** the over-send for a transfer set includes the tombstones of its - snapshots, so fetching from the dropper (or a push that moves the ref) + tombstone as a drop only after the checks in "Who may drop" pass, and never + indexes a transcript whose id is already dropped, so a pack from a peer + that still has the transcript cannot restore it, in either arrival order. + A tombstone that fails the checks stays an inert object and is simply + re-evaluated whenever it is sent again (for example after the operator + adds the signer to the trust list and fetches). +- **sender:** the over-send for a transfer set includes the tombstones (and + their signatures) of its snapshots, so fetching from the dropper (or a push that moves the ref) propagates the drop. A peer that still holds the transcript object hides it as soon as it ingests the tombstone. `push` still skips all I/O when the remote tip already equals the local tip, so a drop alone does not push, @@ -207,6 +210,41 @@ over-send, whatever order the lines landed in. history operations neither carry nor restore them; only transfer can reintroduce one, and that path is covered above. +### Who may drop + +P16 does not authenticate its tombstones: a revoke is a commit on a branch, +and the operator decides to merge that branch, so the merge is the trust +boundary. A drop tombstone has no such gate, because it arrives with a plain +fetch or push. Honoring it blindly would let any peer that can write to a +remote hide, and let gc reclaim, any transcript. The P16 trust model +therefore does not carry over, and drops are authenticated with the P22 +machinery instead. + +- **Local drop:** always honored by the store that ran it. +- **Signed drop:** `sc transcript drop --identity ` also signs the + tombstone id with the transcript domain (`sign_transcript`), stored in the + shared `.sc/signatures` index and sent with the tombstone. No new crypto. +- **Receiving a tombstone** (`index_incoming`, clone `reindex`) honors it + only if all of these hold: the tombstone's snapshot exists locally; if the + dropped transcript is held locally it is a real transcript on that same + snapshot; and a valid signature over the tombstone id comes from a key + under `[signers] trusted` in the receiver's `.sc/recipients.toml` (the set + `sc verify` already uses). Missing or malformed trust config trusts nobody. + If the dropped transcript is not held yet, the snapshot check is the only + structural one, so a trusted signer can drop an id ahead of its arrival. +- **Unsigned or untrusted tombstones are inert:** never recorded, so they + cannot hide a transcript and gc never reclaims a body because of them. + +Trade-offs. Trust is local configuration, not repository content, so a fresh +clone ignores tombstones until its operator trusts the signer and fetches +again (a clone of a store that already honored the drop never receives the +body in the first place). Trust is checked at ingest, not retroactively, so removing a signer +later does not undo drops already recorded. "Trusted signer" is the same +project-level authority that can sign commits; it is deliberately not +narrowed to the transcript's recipients or its own signer, because +transcripts are usually unsigned and recipient ids (X25519) do not map to +signing keys. An unsigned local drop does not propagate. + ### gc The dropped transcript is no longer rooted, so its object falls to the @@ -227,9 +265,6 @@ reported anywhere (it is pruned by gc, hidden before that). ### Limits -- **Drop is not authenticated.** Anyone who can write to a store can drop any - transcript, the same trust level as attaching one. Signed drops are a - follow-on. - **Drop is not erasure.** Peers that never receive the tombstone keep the sealed body, and a recipient who already decrypted it keeps the plaintext. Rotation is not erasure here either. From 70b4010cee5064cd31a6c28d049d7c900e98c517 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 08:56:10 +0300 Subject: [PATCH 3/8] docs: match ADR-0038 drop steps to the code, note tombstone retention limit (ref #212) --- docs/adr/0038-agent-session-transcripts.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index 000c39f9..a7330312 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -190,9 +190,11 @@ full-store scan (`reindex`). The live index is read through the drop set, so a dropped id is invisible to `list`, `show`, `sc log` markers and the over-send, whatever order the lines landed in. -- **drop:** write the tombstone object, append the drop line, then remove the - live entry. A crash between steps leaves the drop line present, so the - transcript is still hidden (fail-closed). +- **drop:** write the tombstone object (and its signature, if signing), then + append the drop line. The live `.sc/transcripts` line is not rewritten: + every read filters it through the drop set and gc purges it. A crash before + the drop line leaves only an unrooted tombstone object and the transcript + stays visible until the drop is retried. - **fetch/clone/push receive:** `index_incoming` records an incoming tombstone as a drop only after the checks in "Who may drop" pass, and never indexes a transcript whose id is already dropped, so a pack from a peer @@ -256,6 +258,12 @@ dead**, as P16 keeps revocation tombstones forever. They are load-bearing against a later fetch of the same history from a stale peer, and cost about 100 bytes each. This is the one place the drop index outlives its snapshot; no transcript content does. +Retention is local protection only. The sender selects tombstones through the +snapshots of the transfer set, and a snapshot gc has removed is never in it, +so a stale peer that still lists the body is not told about a drop whose +snapshot the dropper has since collected. Sending every retained tombstone on +every transfer would close that, at the cost of one object per drop per fetch +for receivers that cannot use it; deferred. ### `sc verify` From 2eab3b141c72bdd1e2913bebb38a0ee7ea351060 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 09:13:21 +0300 Subject: [PATCH 4/8] fix(repo): domain-separate drop signatures, send only signed tombstones (ref #212) Drop signatures cover BLAKE3("sc-transcript-drop-v1" || tombstone id), so a plain transcript signature over the tombstone id never authorizes a drop. Unsigned local drops are no longer over-sent. A v1 identity is refused before a tombstone is stored. ADR-0038 addendum and THREAT-MODEL document the mixed-version and push-only-remote caveats and the trusted-signer power. New tests: plain-signature rejection, push convergence, early tombstone, dead-snapshot gc retention, reindex honoring. --- crates/repo/src/sync.rs | 36 ++++ crates/repo/src/transcripts.rs | 207 ++++++++++++++++++++- docs/THREAT-MODEL.md | 10 + docs/adr/0038-agent-session-transcripts.md | 49 +++-- 4 files changed, 281 insertions(+), 21 deletions(-) diff --git a/crates/repo/src/sync.rs b/crates/repo/src/sync.rs index 0e4f50bb..e2b5df31 100644 --- a/crates/repo/src/sync.rs +++ b/crates/repo/src/sync.rs @@ -924,6 +924,42 @@ mod tests { std::fs::remove_dir_all(&c_root).unwrap(); } + #[test] + fn signed_drop_propagates_over_push() { + let pid = std::process::id(); + let a_root = std::env::temp_dir().join(format!("scl-transdrop-pa-{pid}")); + let b_root = std::env::temp_dir().join(format!("scl-transdrop-pb-{pid}")); + let _ = std::fs::remove_dir_all(&a_root); + let _ = std::fs::remove_dir_all(&b_root); + std::fs::create_dir_all(&a_root).unwrap(); + + let a = Repo::init(&a_root).unwrap(); + std::fs::write(a_root.join("f1"), b"one").unwrap(); + let snap = a.commit("t", "c1").unwrap(); + let (_s, identity) = scl_crypto::generate_identity_v2(); + let tid = a + .attach_transcript(snap, "claude-code", "s1", b"body", &[identity.enc.public()]) + .unwrap(); + crate::transcripts::tests::trust_signer(&a, &identity); + let b = Repo::clone_to(&a_root, &b_root).unwrap(); + drop(a); // push takes the origin's repo lock + + b.drop_transcript(&tid.to_hex(), Some(&identity)).unwrap(); + std::fs::write(b_root.join("f2"), b"two").unwrap(); + b.commit("t", "c2").unwrap(); + b.push("origin").unwrap(); + + let a = Repo::open(&a_root).unwrap(); + assert!( + a.transcripts_for(&snap).unwrap().is_empty(), + "a push carries the signed tombstone" + ); + drop(a); + drop(b); + std::fs::remove_dir_all(&a_root).unwrap(); + std::fs::remove_dir_all(&b_root).unwrap(); + } + #[test] fn signatures_ride_ssh_transport() { // The wire-protocol pipe harness `WireClient` <-> `wire::serve` IS diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index cb282684..2fcbd72d 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -181,6 +181,17 @@ fn trusted_signers(layout: &Layout) -> std::collections::HashMap<[u8; 32], Strin out } +/// The message a drop signature covers: a domain-separated digest of the +/// tombstone id, NOT the bare id. A plain `sign_transcript` signature over the +/// tombstone id (e.g. from an older binary's bulk `sc transcript sign`, which +/// indexes tombstones as live transcripts) must never authorize a drop. +fn drop_digest(tomb: &ObjectId) -> [u8; 32] { + let mut h = blake3::Hasher::new(); + h.update(Transcript::DROP_AGENT.as_bytes()); + h.update(tomb.as_bytes()); + *h.finalize().as_bytes() +} + /// Whether an incoming tombstone may hide its transcript (ADR-0038 addendum, /// "Who may drop"). All of: the tombstone's snapshot exists locally; if the /// dropped transcript is held locally it is a real transcript on that same @@ -206,7 +217,7 @@ fn tombstone_honored( for sid in crate::signatures::indexed_signature_ids_for(layout, &[tomb])? { if let Object::Signature(sig) = store.get(&sid)? { if trusted.contains_key(&sig.signer) - && scl_crypto::verify_transcript_sig(&sig.signer, tomb.as_bytes(), &sig.sig) + && scl_crypto::verify_transcript_sig(&sig.signer, &drop_digest(&tomb), &sig.sig) { return Ok(true); } @@ -335,7 +346,7 @@ pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result, ) -> Result { + if signer.is_some_and(|i| i.signing.is_none()) { + return Err(Error::InvalidArgument( + "identity has no signing half (v1 identity); a signed drop requires a v2 \ + (scl-id-) identity" + .into(), + )); + } let prefix = id_prefix.to_ascii_lowercase(); let matches: BTreeSet<(ObjectId, ObjectId)> = read_index(self.layout())? .into_iter() @@ -450,13 +472,29 @@ impl Repo { let mut store = arc.lock().unwrap(); store.put(Object::Transcript(Transcript::drop_tombstone(snap, &tid)))? }; - if let Some(identity) = signer { - self.sign_transcript(tomb, identity)?; + if let Some(signing) = signer.and_then(|i| i.signing.as_ref()) { + self.sign_drop(tomb, signing)?; } append_drop(self.layout(), (snap, tomb, tid))?; Ok(tid) } + /// Sign `tomb`'s drop digest and index the signature under the tombstone id + /// (shared `.sc/signatures` index, so the signature rides with the tombstone). + pub(crate) fn sign_drop(&self, tomb: ObjectId, key: &scl_crypto::SigningKey) -> Result<()> { + let sig_obj = SignatureObj { + snapshot: tomb, + signer: key.public().to_bytes(), + sig: scl_crypto::sign_transcript_id(key, &drop_digest(&tomb)), + }; + let id = { + let arc = self.store_arc(); + let i = arc.lock().unwrap().put(Object::Signature(sig_obj))?; + i + }; + crate::signatures::append_index(self.layout(), tomb, id) + } + /// All indexed transcripts for `snapshot`, loaded from the CAS (id + /// object, still sealed — opening them is Task 3). pub fn transcripts_for(&self, snapshot: &ObjectId) -> Result> { @@ -748,7 +786,8 @@ pub(crate) mod tests { let ingest = |tomb: Transcript, signer: Option<&scl_crypto::Identity>| -> bool { let tomb_id = arc.lock().unwrap().put(Object::Transcript(tomb)).unwrap(); if let Some(who) = signer { - repo.sign_transcript(tomb_id, who).unwrap(); + repo.sign_drop(tomb_id, who.signing.as_ref().unwrap()) + .unwrap(); } let mut store = arc.lock().unwrap(); index_incoming(repo.layout(), &mut store, &[tomb_id]).unwrap(); @@ -776,6 +815,27 @@ pub(crate) mod tests { )); assert_eq!(repo.transcripts_for(&snap).unwrap().len(), 1); + // A plain transcript signature over the bare tombstone id (what an + // older binary's bulk `sc transcript sign` would produce) is not a drop. + let plain = { + let id = arc + .lock() + .unwrap() + .put(Object::Transcript(Transcript::drop_tombstone( + snap, &victim, + ))) + .unwrap(); + repo.sign_transcript(id, &owner).unwrap(); + let mut store = arc.lock().unwrap(); + index_incoming(repo.layout(), &mut store, &[id]).unwrap(); + id + }; + assert!(read_drops(repo.layout()) + .unwrap() + .iter() + .all(|d| d.1 != plain)); + assert_eq!(repo.transcripts_for(&snap).unwrap().len(), 1); + // A trusted signature on a matching tombstone is honored. assert!(ingest(good, Some(&owner))); assert!(repo.transcripts_for(&snap).unwrap().is_empty()); @@ -790,4 +850,135 @@ pub(crate) mod tests { drop(repo); std::fs::remove_dir_all(&root).unwrap(); } + + #[test] + fn tombstone_honored_before_the_body_arrives_hides_it_on_arrival() { + let (_s, owner) = scl_crypto::generate_identity_v2(); + // Origin makes a real transcript and a signed drop for it. + let src_root = tmp_root("early-src"); + let src = Repo::init(&src_root).unwrap(); + std::fs::write(src_root.join("f"), b"x").unwrap(); + let snap = src.commit("t", "c1").unwrap(); + let body_id = src + .attach_transcript(snap, "a", "s", b"body", &[owner.enc.public()]) + .unwrap(); + let body = src.store_arc().lock().unwrap().get(&body_id).unwrap(); + src.drop_transcript(&body_id.to_hex(), Some(&owner)) + .unwrap(); + let (snap_, tomb, _) = read_drops(src.layout()).unwrap()[0]; + assert_eq!(snap_, snap); + + // Receiver already has the snapshot (same repo history) and trusts the signer. + let dst_root = tmp_root("early-dst"); + let dst = Repo::clone_to(&src_root, &dst_root).unwrap(); + trust_signer(&dst, &owner); + let arc = dst.store_arc(); + let mut store = arc.lock().unwrap(); + // Tombstone + its signature arrive first, body not held. + let tomb_obj = src.store_arc().lock().unwrap().get(&tomb).unwrap(); + store.put(tomb_obj).unwrap(); + for sid in crate::signatures::indexed_signature_ids_for(src.layout(), &[tomb]).unwrap() { + let o = src.store_arc().lock().unwrap().get(&sid).unwrap(); + store.put(o).unwrap(); + crate::signatures::index_incoming(dst.layout(), &mut store, &[sid]).unwrap(); + } + index_incoming(dst.layout(), &mut store, &[tomb]).unwrap(); + assert_eq!(read_drops(dst.layout()).unwrap().len(), 1, "honored early"); + // Then the body arrives: it must not be indexed. + let id = store.put(body).unwrap(); + assert_eq!(id, body_id); + index_incoming(dst.layout(), &mut store, &[id]).unwrap(); + drop(store); + assert!(dst.transcripts_for(&snap).unwrap().is_empty()); + + drop(src); + drop(dst); + std::fs::remove_dir_all(&src_root).unwrap(); + std::fs::remove_dir_all(&dst_root).unwrap(); + } + + #[test] + fn gc_prune_keeps_a_tombstone_whose_snapshot_died_and_never_roots_the_body() { + let root = tmp_root("gc-dead"); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("f"), b"x").unwrap(); + let snap = repo.commit("t", "c1").unwrap(); + let (_s, owner) = scl_crypto::generate_identity_v2(); + let body = repo + .attach_transcript(snap, "a", "s", b"body", &[owner.enc.public()]) + .unwrap(); + repo.drop_transcript(&body.to_hex(), Some(&owner)).unwrap(); + let tomb = read_drops(repo.layout()).unwrap()[0].1; + + // The snapshot is no longer reachable. + let mut reachable = BTreeSet::new(); + gc_prune(repo.layout(), &mut reachable).unwrap(); + assert!( + reachable.contains(&tomb), + "tombstone rooted despite dead snapshot" + ); + assert!(!reachable.contains(&body), "dropped body is never rooted"); + assert_eq!(read_drops(repo.layout()).unwrap().len(), 1); + assert!(load(repo.layout()).unwrap().is_empty()); + + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } + + #[test] + fn reindex_honors_a_signed_tombstone_only_for_a_trusted_signer() { + let root = tmp_root("reindex"); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("f"), b"x").unwrap(); + let snap = repo.commit("t", "c1").unwrap(); + let (_s, owner) = scl_crypto::generate_identity_v2(); + let body = repo + .attach_transcript(snap, "a", "s", b"body", &[owner.enc.public()]) + .unwrap(); + repo.drop_transcript(&body.to_hex(), Some(&owner)).unwrap(); + // Unsigned drops are local-only: never offered to a peer. + let keep = repo + .attach_transcript(snap, "a", "k", b"keep", &[owner.enc.public()]) + .unwrap(); + repo.drop_transcript(&keep.to_hex(), None).unwrap(); + let sent = indexed_transcript_ids_for(repo.layout(), &[snap]).unwrap(); + let drops = read_drops(repo.layout()).unwrap(); + assert_eq!(sent.len(), 1); + assert!(drops.iter().any(|d| sent.contains(&d.1) && d.2 == body)); + + // Both bodies (and the tombstones) sit in the store; rebuild indexes. + let arc = repo.store_arc(); + let mut store = arc.lock().unwrap(); + crate::signatures::reindex(repo.layout(), &mut store).unwrap(); + assert_eq!( + reindex(repo.layout(), &mut store).unwrap(), + 2, + "no trust: both bodies are live again" + ); + drop(store); + assert_eq!( + load(repo.layout()).unwrap().len(), + 2, + "untrusted: both visible" + ); + assert!(read_drops(repo.layout()).unwrap().is_empty()); + + trust_signer(&repo, &owner); + let mut store = arc.lock().unwrap(); + reindex(repo.layout(), &mut store).unwrap(); + drop(store); + let live: Vec<_> = load(repo.layout()) + .unwrap() + .into_iter() + .map(|e| e.1) + .collect(); + assert_eq!( + live, + vec![keep], + "signed drop honored, unsigned drop is not" + ); + + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } } diff --git a/docs/THREAT-MODEL.md b/docs/THREAT-MODEL.md index ba8d9ed0..af5743f1 100644 --- a/docs/THREAT-MODEL.md +++ b/docs/THREAT-MODEL.md @@ -187,6 +187,16 @@ too, not just the src-control-side metadata. transcript remaining readable to *authorized* transcript recipients (the P5 scanner warns at attach time but never blocks; rotation of the underlying secret remedies). +- **Drop tombstones (`sc transcript drop`, ADR-0038 addendum).** A drop is honored + by a peer only if it carries a signature over its drop digest from a key under + that peer's `[signers] trusted` list, and its snapshot checks out. An unsigned or + untrusted tombstone is inert. The new power: any trusted signer can hide + transcripts on every peer that trusts it and make those peers' gc reclaim the + bodies. Drop is not erasure: peers without the tombstone keep the body, + `GetObjects` serves it until gc sweeps it, and a peer that still holds it can + re-send it. A tombstone ignored on arrival stays ignored on a push-only or + served remote, so configure `[signers] trusted` there before the first drop + push. Trust is checked at ingest and is not retroactive. ## Network transport (`sc serve --http` / `sc+http(s)://` / `ssh://`) — ADR-0022/0036/0040/0041/0042 diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index a7330312..8e81671c 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -202,12 +202,14 @@ over-send, whatever order the lines landed in. A tombstone that fails the checks stays an inert object and is simply re-evaluated whenever it is sent again (for example after the operator adds the signer to the trust list and fetches). -- **sender:** the over-send for a transfer set includes the tombstones (and - their signatures) of its snapshots, so fetching from the dropper (or a push that moves the ref) - propagates the drop. A peer that still holds the transcript object hides - it as soon as it ingests the tombstone. `push` still skips all I/O when - the remote tip already equals the local tip, so a drop alone does not push, - the same pre-existing behavior as a retroactive attach. +- **sender:** the over-send for a transfer set includes the tombstones of its + snapshots that have an indexed signature, with those signatures. An + unsigned (local-only) drop is never sent. Fetching from the dropper (or a + push that moves the ref) propagates the drop. A peer that still holds the + transcript object hides it once it ingests an honored tombstone. `push` + still skips all I/O when the remote tip already equals the local tip, so a + drop alone does not push, the same pre-existing behavior as a retroactive + attach. - **merge, cherry-pick, rebase:** transcripts are not part of snapshots, so history operations neither carry nor restore them; only transfer can reintroduce one, and that path is covered above. @@ -223,13 +225,19 @@ therefore does not carry over, and drops are authenticated with the P22 machinery instead. - **Local drop:** always honored by the store that ran it. -- **Signed drop:** `sc transcript drop --identity ` also signs the - tombstone id with the transcript domain (`sign_transcript`), stored in the - shared `.sc/signatures` index and sent with the tombstone. No new crypto. +- **Signed drop:** `sc transcript drop --identity ` signs a + domain-separated digest, `BLAKE3("sc-transcript-drop-v1" || tombstone id)`, + with the existing transcript signing functions. The signature object is + keyed by the tombstone id in the shared `.sc/signatures` index so it rides + with the tombstone. A plain transcript signature over the bare tombstone id + does NOT authorize a drop. That matters because an older binary indexes a + tombstone as a live transcript, and its bulk `sc transcript sign ` + would sign it by trusted signers who never meant to drop anything. No new + crypto primitives. A v1 identity is refused before anything is stored. - **Receiving a tombstone** (`index_incoming`, clone `reindex`) honors it only if all of these hold: the tombstone's snapshot exists locally; if the dropped transcript is held locally it is a real transcript on that same - snapshot; and a valid signature over the tombstone id comes from a key + snapshot; and a valid signature over the drop digest comes from a key under `[signers] trusted` in the receiver's `.sc/recipients.toml` (the set `sc verify` already uses). Missing or malformed trust config trusts nobody. If the dropped transcript is not held yet, the snapshot check is the only @@ -237,6 +245,17 @@ machinery instead. - **Unsigned or untrusted tombstones are inert:** never recorded, so they cannot hide a transcript and gc never reclaims a body because of them. +Operational consequences. A tombstone that arrives while its signer is +untrusted is ignored and not recorded. On a fetching peer it is re-sent and +re-evaluated next time. A push-only or served remote has no such retry: if it +ignored the tombstone it stays ignored until the next push re-sends it, so +configure `[signers] trusted` on a remote before the first drop is pushed to +it. Any key under `[signers] trusted` can hide transcripts on every peer that +trusts it, and make that peer's gc reclaim the bodies. `GetObjects` still +serves a dropped body until gc sweeps it, and a peer that still holds the +body re-sends it on a later transfer, which restarts its grace window. All of +this follows from drop not being erasure. + Trade-offs. Trust is local configuration, not repository content, so a fresh clone ignores tombstones until its operator trusts the signer and fetches again (a clone of a store that already honored the drop never receives the @@ -276,8 +295,12 @@ reported anywhere (it is pruned by gc, hidden before that). - **Drop is not erasure.** Peers that never receive the tombstone keep the sealed body, and a recipient who already decrypted it keeps the plaintext. Rotation is not erasure here either. -- **Older peers** that predate this change see a tombstone as an unopenable - transcript and do not honor it. Upgrade before relying on drop across a - shared remote. +- **Mixed versions.** A binary that predates this change indexes a tombstone + as a live transcript: it shows in `sc transcript list` and the `sc log` + marker, and `sc transcript show ` fails on it with a not-a-recipient + error, because the empty envelope has no wraps. Upgrade every peer before + using drop on a shared remote. Such a peer's bulk `sc transcript sign` may + also sign the tombstone id; that signature is over the bare id, not the drop + digest, so it never authorizes a drop. - `sc export` still counts only transcripts that are not tombstones; a dropped body that gc has not swept yet is still counted as dropped history. From e27eb81ff3606894caa31bfdcb9e8b8c9fef0e29 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 09:17:52 +0300 Subject: [PATCH 5/8] docs: push never re-sends a held tombstone, so push-only remotes need trust first (ref #212) --- docs/adr/0038-agent-session-transcripts.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index 8e81671c..ddd258eb 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -199,9 +199,11 @@ over-send, whatever order the lines landed in. tombstone as a drop only after the checks in "Who may drop" pass, and never indexes a transcript whose id is already dropped, so a pack from a peer that still has the transcript cannot restore it, in either arrival order. - A tombstone that fails the checks stays an inert object and is simply - re-evaluated whenever it is sent again (for example after the operator - adds the signer to the trust list and fetches). + A tombstone that fails the checks stays an inert object. A fetching peer + re-evaluates it whenever it is sent again (for example after the operator + adds the signer to the trust list and fetches). `push` never re-sends an + object the remote already holds, so a remote that received the tombstone by + push before trusting the signer keeps it inert. - **sender:** the over-send for a transfer set includes the tombstones of its snapshots that have an indexed signature, with those signatures. An unsigned (local-only) drop is never sent. Fetching from the dropper (or a @@ -246,11 +248,11 @@ machinery instead. cannot hide a transcript and gc never reclaims a body because of them. Operational consequences. A tombstone that arrives while its signer is -untrusted is ignored and not recorded. On a fetching peer it is re-sent and -re-evaluated next time. A push-only or served remote has no such retry: if it -ignored the tombstone it stays ignored until the next push re-sends it, so -configure `[signers] trusted` on a remote before the first drop is pushed to -it. Any key under `[signers] trusted` can hide transcripts on every peer that +untrusted is ignored and not recorded. A fetching peer retries it on its next +fetch. A push-only or served remote has no retry: it already holds the object, +so a later push does not send it again and nothing re-runs the check, and the +drop stays inert there even after the signer is trusted. Configure +`[signers] trusted` on a remote before the first drop is pushed to it. Any key under `[signers] trusted` can hide transcripts on every peer that trusts it, and make that peer's gc reclaim the bodies. `GetObjects` still serves a dropped body until gc sweeps it, and a peer that still holds the body re-sends it on a later transfer, which restarts its grace window. All of From 391761852faf6d49e6366f10bb819bbc64fa974d Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 10:14:44 +0300 Subject: [PATCH 6/8] fix(repo): validate tombstone snapshot kind, read signature index once, fix grace-window docs (ref #212) Tombstone snapshots must be Snapshot objects. index_incoming and reindex load the signature index once per call. Packed dropped bodies are reclaimed at the next gc, not after the grace window; help, ADR, roadmap and skill say so. Delivery gaps are tracked in #230. --- .claude/skills/sc-cli-reference/SKILL.md | 2 +- ROADMAP.md | 3 ++- crates/cli/src/main.rs | 3 ++- crates/repo/src/signatures.rs | 12 ++++++++++ crates/repo/src/transcripts.rs | 28 ++++++++++++++++------ docs/adr/0038-agent-session-transcripts.md | 18 +++++++++----- 6 files changed, 50 insertions(+), 16 deletions(-) diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index 24192a51..3ae60e41 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -223,7 +223,7 @@ cargo run --bin sc -- transcript sign [--identity ] # retroactively cargo run --bin sc -- transcript drop [--identity ] # drop a transcript by id/hex prefix (see `list`): writes # a tombstone that travels with fetch/clone so a peer # that still has it cannot restore it; gc reclaims the - # body after the grace window. Not erasure. --identity + # body (loose: after the grace window; already packed: next gc). Not erasure. --identity # signs the tombstone; peers honor it only if that key # is under [signers] trusted (unsigned = local-only). # Propagates on the peer's next fetch (ADR-0038 addendum) diff --git a/ROADMAP.md b/ROADMAP.md index 9e7c3afe..249d756b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -480,7 +480,8 @@ across every phase. grow-only drop tombstone (a bare `Transcript` object, so no wire change) hides the body from `list`/`show`, travels with fetch/clone, blocks resurrection in either arrival order, and is kept by gc while the dropped - body is swept after the grace window. (ADR-0038 addendum.) + body is swept at gc (after the grace window if loose). (ADR-0038 addendum; + delivery gaps tracked in #230.) - **Phase 32 — In-binary TLS (`sc+https://`).** Closes the audit's High #1 (plaintext bearer tokens/traffic on `sc+http://`) and ADR-0036's "no TLS" diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 1461ea73..e6e23b53 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -594,7 +594,8 @@ enum TranscriptOp { /// Drop a transcript by id (or unique id prefix) from `sc transcript /// list`. Records a tombstone that travels with fetch/push, so a peer /// that still has the transcript cannot bring it back; `sc gc` reclaims - /// the body after its grace window. Not erasure: peers that never + /// the body (a loose one after `--prune-expire`, but one already packed + /// by an earlier gc at the next gc). Not erasure: peers that never /// receive the tombstone keep the sealed body. Without `--identity` the /// drop is local-only: peers honor a tombstone only when it is signed by /// a key in their `[signers] trusted` list. diff --git a/crates/repo/src/signatures.rs b/crates/repo/src/signatures.rs index 2c241753..5ee033db 100644 --- a/crates/repo/src/signatures.rs +++ b/crates/repo/src/signatures.rs @@ -183,6 +183,18 @@ pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result signature object ids`, read +/// once so a caller checking many targets does not rescan the file per target. +pub(crate) fn index_by_target( + layout: &Layout, +) -> Result>> { + let mut out: std::collections::HashMap> = Default::default(); + for (target, sig_id) in read_index(layout)? { + out.entry(target).or_default().push(sig_id); + } + Ok(out) +} + /// Sender-side seam (Task 3): the indexed signature object ids covering any /// of `snapshots`, deduped and sorted — the set a push/export needs to /// carry alongside the snapshots themselves so the receiving repo's index diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index 2fcbd72d..a480be65 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -195,17 +195,18 @@ fn drop_digest(tomb: &ObjectId) -> [u8; 32] { /// Whether an incoming tombstone may hide its transcript (ADR-0038 addendum, /// "Who may drop"). All of: the tombstone's snapshot exists locally; if the /// dropped transcript is held locally it is a real transcript on that same -/// snapshot; and a signature over the tombstone id verifies under a key in +/// snapshot; and a signature over the drop digest verifies under a key in /// `trusted`. An unsigned or untrusted tombstone stays an inert object. fn tombstone_honored( - layout: &Layout, store: &mut scl_core::Store, trusted: &std::collections::HashMap<[u8; 32], String>, + sigs: &std::collections::HashMap>, tomb: ObjectId, t: &Transcript, dropped: ObjectId, ) -> Result { - if !store.contains(&t.snapshot) { + // The claimed snapshot must be a real snapshot, not any object we hold. + if !store.contains(&t.snapshot) || !matches!(store.get(&t.snapshot)?, Object::Snapshot(_)) { return Ok(false); } if store.contains(&dropped) { @@ -214,8 +215,8 @@ fn tombstone_honored( _ => return Ok(false), } } - for sid in crate::signatures::indexed_signature_ids_for(layout, &[tomb])? { - if let Object::Signature(sig) = store.get(&sid)? { + for sid in sigs.get(&tomb).map(Vec::as_slice).unwrap_or_default() { + if let Object::Signature(sig) = store.get(sid)? { if trusted.contains_key(&sig.signer) && scl_crypto::verify_transcript_sig(&sig.signer, &drop_digest(&tomb), &sig.sig) { @@ -291,11 +292,12 @@ pub(crate) fn index_incoming( ) -> Result { let mut count = 0; let trusted = trusted_signers(layout); + let sigs = crate::signatures::index_by_target(layout)?; for id in ids { if let Object::Transcript(t) = store.get(id)? { match t.dropped_id() { Some(dropped) => { - if !tombstone_honored(layout, store, &trusted, *id, &t, dropped)? { + if !tombstone_honored(store, &trusted, &sigs, *id, &t, dropped)? { continue; } append_drop(layout, (t.snapshot, *id, dropped))? @@ -318,6 +320,7 @@ pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result = Vec::new(); let mut drops: Vec = Vec::new(); let trusted = trusted_signers(layout); + let sigs = crate::signatures::index_by_target(layout)?; for id in store.all_ids()? { if let Object::Transcript(t) = store.get(&id)? { if !store.contains(&t.snapshot) { @@ -325,7 +328,7 @@ pub(crate) fn reindex(layout: &Layout, store: &mut scl_core::Store) -> Result { - if tombstone_honored(layout, store, &trusted, id, &t, dropped)? { + if tombstone_honored(store, &trusted, &sigs, id, &t, dropped)? { drops.push((t.snapshot, id, dropped)); } } @@ -807,6 +810,17 @@ pub(crate) mod tests { Transcript::drop_tombstone(other_snap, &victim), Some(&owner) )); + // A tombstone whose "snapshot" is a blob we hold is ignored, even ahead + // of the body. + let blob = arc + .lock() + .unwrap() + .put(Object::Blob(std::sync::Arc::from(&b"not a snapshot"[..]))) + .unwrap(); + assert!(!ingest( + Transcript::drop_tombstone(blob, &ObjectId::of(b"future")), + Some(&owner) + )); // A tombstone for a snapshot this store has never seen is ignored too. let unknown = ObjectId::of(b"unknown-snap"); assert!(!ingest( diff --git a/docs/adr/0038-agent-session-transcripts.md b/docs/adr/0038-agent-session-transcripts.md index ddd258eb..4634f4ec 100644 --- a/docs/adr/0038-agent-session-transcripts.md +++ b/docs/adr/0038-agent-session-transcripts.md @@ -251,7 +251,8 @@ Operational consequences. A tombstone that arrives while its signer is untrusted is ignored and not recorded. A fetching peer retries it on its next fetch. A push-only or served remote has no retry: it already holds the object, so a later push does not send it again and nothing re-runs the check, and the -drop stays inert there even after the signer is trusted. Configure +drop stays inert there even after the signer is trusted (tracked in #230). +Configure `[signers] trusted` on a remote before the first drop is pushed to it. Any key under `[signers] trusted` can hide transcripts on every peer that trusts it, and make that peer's gc reclaim the bodies. `GetObjects` still serves a dropped body until gc sweeps it, and a peer that still holds the @@ -270,10 +271,13 @@ signing keys. An unsigned local drop does not propagate. ### gc -The dropped transcript is no longer rooted, so its object falls to the -ordinary loose-object grace window and repack like any other unreachable -object, and its own signature entry is pruned with it (`signatures::gc_prune` -keys off the same `reachable` set). Tombstones are the opposite: gc roots +The dropped transcript is no longer rooted, so a loose body falls to the +ordinary loose-object grace window (`--prune-expire`) like any other +unreachable object. A body an earlier gc already packed gets no grace: the +repack leaves it out of the new pack and deletes the superseded packs, so the +next gc reclaims it whatever `--prune-expire` says. Its own signature entry +is pruned with it (`signatures::gc_prune` keys off the same `reachable` set). +Tombstones are the opposite: gc roots every tombstone object and keeps every drop line, **even when its snapshot is dead**, as P16 keeps revocation tombstones forever. They are load-bearing against a later fetch of the same history from a stale peer, and cost about @@ -284,7 +288,9 @@ snapshots of the transfer set, and a snapshot gc has removed is never in it, so a stale peer that still lists the body is not told about a drop whose snapshot the dropper has since collected. Sending every retained tombstone on every transfer would close that, at the cost of one object per drop per fetch -for receivers that cannot use it; deferred. +for receivers that cannot use it; deferred to #230, together with the +push-only remote limit above (a tombstone rejected on arrival is never +re-evaluated there). ### `sc verify` From 6acfdbe2e3642ed72c6b9f8fec80831f8d380778 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 10:30:15 +0300 Subject: [PATCH 7/8] fix(repo): count tombstone-purged entries in GcStats::transcripts_pruned (ref #212) --- crates/repo/src/gc.rs | 9 +++++++-- crates/repo/src/transcripts.rs | 8 +++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/crates/repo/src/gc.rs b/crates/repo/src/gc.rs index 4cf84097..93859881 100644 --- a/crates/repo/src/gc.rs +++ b/crates/repo/src/gc.rs @@ -35,7 +35,8 @@ pub struct GcStats { /// to the ordinary loose-object prune, not counted here. pub signatures_pruned: usize, /// Transcript index entries dropped (P30) because their snapshot fell - /// out of the reachable set this pass; their transcript objects fall + /// out of the reachable set this pass, or because a drop tombstone hides + /// them; their transcript objects fall /// through to the ordinary loose-object prune, not counted here. pub transcripts_pruned: usize, } @@ -804,7 +805,11 @@ mod tests { repo.drop_transcript(&gone.to_hex(), Some(&identity)) .unwrap(); - repo.gc(Duration::from_secs(0)).unwrap(); + let stats = repo.gc(Duration::from_secs(0)).unwrap(); + assert_eq!( + stats.transcripts_pruned, 1, + "the dropped entry purged from the index is counted" + ); let tomb = { let drops = std::fs::read_to_string(repo.layout().transcript_drops_path()).unwrap(); diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index a480be65..e7d491b5 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -255,7 +255,6 @@ pub(crate) fn gc_prune(layout: &Layout, reachable: &mut BTreeSet) -> R let dropped: BTreeSet = drops.iter().map(|(_, _, d)| *d).collect(); let entries = read_raw(layout)?; let mut kept = Vec::with_capacity(entries.len()); - let mut dead = 0; for (snap, tid) in &entries { if dropped.contains(tid) { continue; @@ -263,14 +262,13 @@ pub(crate) fn gc_prune(layout: &Layout, reachable: &mut BTreeSet) -> R if reachable.contains(snap) { reachable.insert(*tid); kept.push((*snap, *tid)); - } else { - dead += 1; } } - if kept.len() != entries.len() { + let pruned = entries.len() - kept.len(); + if pruned > 0 { write_index(layout, &kept)?; } - Ok(dead) + Ok(pruned) } /// Receiver-side seam (Task 3/4): given a batch of object ids just written From a8d307b2f5b58e935b8474c8125b40936c266910 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Tue, 20 Oct 2026 10:42:29 +0300 Subject: [PATCH 8/8] perf(repo): read the signature index once when selecting tombstones to send (ref #212) --- crates/repo/src/transcripts.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/crates/repo/src/transcripts.rs b/crates/repo/src/transcripts.rs index e7d491b5..113b8cd4 100644 --- a/crates/repo/src/transcripts.rs +++ b/crates/repo/src/transcripts.rs @@ -364,11 +364,13 @@ pub(crate) fn indexed_transcript_ids_for( // Signed tombstones travel with their snapshot so a drop propagates. An // unsigned (local-only) drop is never sent: peers would ignore it, and an // older peer would index it as a live transcript. - for (snap, tomb, _) in read_drops(layout)? { - if wanted.contains(&snap) - && !crate::signatures::indexed_signature_ids_for(layout, &[tomb])?.is_empty() - { - out.insert(tomb); + let drops = read_drops(layout)?; + if !drops.is_empty() { + let sigs = crate::signatures::index_by_target(layout)?; + for (snap, tomb, _) in drops { + if wanted.contains(&snap) && sigs.contains_key(&tomb) { + out.insert(tomb); + } } } Ok(out.into_iter().collect())