From 78919e8e6aecb949a39500c3479996ddf3b00cc1 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 12:33:54 +0300 Subject: [PATCH 1/3] feat(repo): sc rewrap --rotate re-seals protected paths under fresh keys (ADR-0051) A plain rewrap drops a revoked recipient's wrap but keeps the DEK, so a recipient with an old wrap still opens the tip. --rotate reuses the convergent-upgrade branch to decrypt each protected blob and re-seal it under a fresh DEK to the rule's granted set plus escrow: one commit, one oplog record, skip-and-report, new ciphertext ids. History keeps the old ciphertext (rotation is not erasure). Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/sc-cli-reference/SKILL.md | 6 +- ARCHITECTURE.md | 2 +- CLAUDE.md | 9 +- ROADMAP.md | 9 +- crates/cli/src/main.rs | 22 +- crates/repo/src/rewrap.rs | 216 ++++++++++++++++-- demo/run_rewrap_demo.sh | 18 ++ .../0043-randomized-protected-encryption.md | 4 +- docs/adr/0051-rotate-protected-paths.md | 29 +++ docs/adr/README.md | 1 + 10 files changed, 278 insertions(+), 38 deletions(-) create mode 100644 docs/adr/0051-rotate-protected-paths.md diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index c27a5048..abb437af 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -114,7 +114,7 @@ cargo run --bin sc -- secret rotate --identity # same value, fre cargo run --bin sc -- escrow set # break-glass recovery key # (replace-with-one sugar, P17) bash demo/run_lifecycle_demo.sh # rotation + escrow proof -cargo run --bin sc -- rewrap [--identity ] [--dry-run] # one-commit bulk reseal of all +cargo run --bin sc -- rewrap [--identity ] [--dry-run] [--rotate] # one-commit bulk reseal of all # secrets + protected wrap lists to current # recipient/escrow sets (skip-and-report; # exits 1 when entries were skipped); also @@ -122,7 +122,9 @@ cargo run --bin sc -- rewrap [--identity ] [--dry-run] # one-commit bulk # protected blob RANDOMIZED (P33) — so a rewrap # that upgrades content is no longer tree-identical, # while a second rewrap over an all-randomized tip - # converges back to policy-only + # converges back to policy-only; --rotate also re-seals + # every protected blob under a FRESH key (ADR-0051), so + # a recipient with an old wrap cannot open the tip cargo run --bin sc -- escrow add # append a break-glass key (list) cargo run --bin sc -- escrow remove cargo run --bin sc -- escrow show # lists all escrow keys diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index de70bc0e..40f4e127 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -508,7 +508,7 @@ re-wrap (`grant`/`revoke`). `sc secret revoke` remains metadata-only and now hints to run `rotate` for the actual cryptographic cutover. (**P33/ADR-0043:** the security-meaningless objection dissolves for **randomized** content — a random DEK is independent of the plaintext — so a genuine rotate-for-paths -cutover is now coherent and recorded as an unlocked follow-on, not yet built.) +cutover is coherent, and is built as `sc rewrap --rotate` (ADR-0051).) `sc escrow set ` / `sc escrow show` configure a single break-glass recipient key (`[escrow]` in `.sc/recipients.toml`) that is diff --git a/CLAUDE.md b/CLAUDE.md index da7a9031..2cc56a15 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -194,14 +194,17 @@ transport-adjacent. The rest, imperatively: their prior wrap list. Use `sc grant` (or `sc rewrap`) to add a recipient to existing content. Fails safe: under-grants, never over-grants. - **`sc rewrap` is content-changing when it upgrades** still-convergent blobs - to randomized; only a rewrap over an all-randomized tip is policy-only. + to randomized, or with `--rotate`; only a plain rewrap over an all-randomized + tip is policy-only. - **`.sc/local-key` and the per-checkout protected caches (`.sc/protected-cache`, `.sc/ws/cache-`) are never committed and never transferred.** Cache saves are best-effort and ordered after ref moves; a cache failure may cause a spurious re-seal but never incorrectness. - **Revoke is standing-only.** A revoked recipient keeps decrypting ciphertext sealed before the revoke (they hold the old wraps); cryptographic cutover is - `sc rewrap` at the tip plus rotating the underlying credential. + `sc rewrap --rotate` at the tip (fresh key per protected blob; a plain + `sc rewrap` only replaces wrap lists) plus rotating the underlying credential. + History keeps the old ciphertext (rotation is not erasure). - **The oplog is local-only** (like a reflog) — it never travels over fetch/push/clone. `sc undo` twice = redo; undoing the initial commit is refused. @@ -260,7 +263,7 @@ transport-adjacent. The rest, imperatively: Deferred work is tracked in **`ROADMAP.md` → Deferred** (single source of truth — do not re-list items here). Notable standing entries: transparent lazy-fetch for partial clones, per-case gap-tolerant merge/replay on partial -clones, rotate-for-paths (unlocked by P33, recorded not built), fd/stdin +clones, fd/stdin secret injection, CA-path validation alongside TOFU pinning, and pin-management UX (`sc tls`). diff --git a/ROADMAP.md b/ROADMAP.md index 48c1b488..09c36459 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -786,12 +786,9 @@ scale-&-reach horizon): it: all new protected content seals under a fresh random DEK + nonce (dual-read for pre-P33 convergent history; `sc rewrap` upgrades a tip on demand). Moved from deferred to Done above. -- **Rotate-for-paths (P33 follow-on).** ADR-0019 declared per-path DEK rotation - "security-meaningless" under convergent encryption. That objection dissolves - for randomized content (a random DEK is independent of the plaintext), so a - `sc protect … rotate`-style genuine per-path cryptographic cutover — the - protected-path analogue of `sc secret rotate` — is now coherent. Recorded in - ADR-0043, not built. +- **Rotate-for-paths — shipped (ADR-0051).** `sc rewrap --rotate` re-seals every + protected blob at the tip under a fresh DEK (the path analogue of `sc secret + rotate`); history keeps the old ciphertext (rotation is not erasure). - **`sc rewrap` on partial clones — refused (P37).** `Repo::rewrap` calls `refuse_on_partial`; a paths-only/streaming rebuild that would lift the refusal remains a possible follow-on. diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index f579368d..cbbff50b 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -465,6 +465,11 @@ enum Cmd { /// Report what would be re-wrapped without committing. #[arg(long)] dry_run: bool, + /// Also re-seal every protected file under a fresh key, so a + /// recipient revoked earlier cannot open the tip with an old wrap. + /// Changes ciphertext ids (and the root tree); history is untouched. + #[arg(long)] + rotate: bool, }, /// Revert the last operation (run again to redo). Undo, @@ -1038,7 +1043,11 @@ fn main() -> Result<()> { include_encrypted, } => run_export(to, r#ref, include_encrypted), Cmd::Escrow { op } => run_escrow(op), - Cmd::Rewrap { identity, dry_run } => run_rewrap(identity, dry_run), + Cmd::Rewrap { + identity, + dry_run, + rotate, + } => run_rewrap(identity, dry_run, rotate), Cmd::Undo => run_undo(), Cmd::Oplog => run_oplog(), Cmd::Sign { r#ref, identity } => run_sign(&r#ref, identity), @@ -4246,7 +4255,7 @@ fn run_gc(prune_expire: &str) -> Result<()> { Ok(()) } -fn run_rewrap(identity: Option, dry_run: bool) -> Result<()> { +fn run_rewrap(identity: Option, dry_run: bool, rotate: bool) -> Result<()> { let repo = open_repo()?; let sk = load_identity(identity)?; let recipients_path = repo.layout().dot_sc.join("recipients.toml"); @@ -4267,7 +4276,7 @@ fn run_rewrap(identity: Option, dry_run: bool) -> Result<()> { known.push(me); } - let report = repo.rewrap(&sk, &escrows, &known, dry_run)?; + let report = repo.rewrap_with(&sk, &escrows, &known, dry_run, rotate)?; let verb = if dry_run { "would rewrap" } else { "rewrapped" }; println!( "{verb} {} secret(s), {} protected blob(s)", @@ -4285,6 +4294,13 @@ fn run_rewrap(identity: Option, dry_run: bool) -> Result<()> { report.blobs_resealed ); } + if report.blobs_rotated > 0 { + let rotate_verb = if dry_run { "would rotate" } else { "rotated" }; + println!( + "{rotate_verb} {} protected blob(s) under fresh keys", + report.blobs_rotated + ); + } if let Some(id) = &report.commit { println!("commit: {}", id.short()); } diff --git a/crates/repo/src/rewrap.rs b/crates/repo/src/rewrap.rs index 22575f3a..ae2cfeda 100644 --- a/crates/repo/src/rewrap.rs +++ b/crates/repo/src/rewrap.rs @@ -17,6 +17,9 @@ pub struct RewrapReport { /// Convergent (pre-P33) protected blobs eagerly re-sealed randomized /// (fresh DEK + nonce, new ciphertext id) during this run (P33 Task 10). pub blobs_resealed: usize, + /// Already-randomized protected blobs re-sealed under a fresh DEK because + /// the run asked to rotate (`rewrap_with` / `sc rewrap --rotate`). + pub blobs_rotated: usize, /// (entry label e.g. "secret db-pass" / "path secret/db.txt", reason) pub skipped: Vec<(String, String)>, /// The commit id; None on --dry-run or when nothing needed rewrapping. @@ -43,6 +46,24 @@ impl Repo { escrows: &[PublicKey], known_keys: &[PublicKey], dry_run: bool, + ) -> Result { + self.rewrap_with(identity, escrows, known_keys, dry_run, false) + } + + /// [`Repo::rewrap`] with `rotate`: also re-seal every already-randomized + /// protected blob under a FRESH DEK (the protected-path analogue of + /// `sc secret rotate`, ADR-0051). A plain rewrap replaces wrap lists only, + /// so a recipient revoked earlier who kept an old wrap can still open the + /// tip's ciphertext; rotating makes that ciphertext unreadable to them. It + /// changes ciphertext ids, so the root tree changes. History is untouched + /// (rotation is not erasure). + pub fn rewrap_with( + &self, + identity: &SecretKey, + escrows: &[PublicKey], + known_keys: &[PublicKey], + dry_run: bool, + rotate: bool, ) -> Result { self.refuse_on_private("sc rewrap")?; self.refuse_on_partial("sc rewrap")?; @@ -137,6 +158,7 @@ impl Repo { let mut protection = snap.protection.clone(); let mut blobs_rewrapped = 0usize; let mut blobs_resealed = 0usize; + let mut blobs_rotated = 0usize; // path -> (new blob id, new perms) for eagerly-upgraded entries; the // commit tail rebuilds the root iff this is non-empty. let mut retargets: std::collections::BTreeMap = @@ -220,10 +242,12 @@ impl Repo { target_pks.push(e.clone()); } } - if perms & scl_core::RANDOMIZED == 0 { - // Convergent (pre-P33): eager upgrade. Decrypt with the DEK - // we just unwrapped, re-seal randomized, retarget the tree - // entry + wraps to the fresh ciphertext id. + let convergent = perms & scl_core::RANDOMIZED == 0; + if convergent || rotate { + // Convergent (pre-P33): eager upgrade. Randomized with + // `rotate`: a genuine cutover to a fresh DEK. Either way: + // decrypt with the DEK we just unwrapped, re-seal randomized, + // retarget the tree entry + wraps to the fresh ciphertext id. let cipher = { let arc = self.store_arc(); let obj = arc.lock().unwrap().get(blob_id)?; @@ -249,7 +273,11 @@ impl Repo { } }; if dry_run { - blobs_resealed += 1; + if convergent { + blobs_resealed += 1; + } else { + blobs_rotated += 1; + } continue; } let (new_cipher, new_dek) = scl_crypto::encrypt_path_randomized(&pt); @@ -280,7 +308,11 @@ impl Repo { // at the next commit, never incorrectness. c.record(path, &pt, new_id); } - blobs_resealed += 1; + if convergent { + blobs_resealed += 1; + } else { + blobs_rotated += 1; + } continue; } if dry_run { @@ -328,12 +360,14 @@ impl Repo { || (secrets_rewrapped.is_empty() && new_secret_objs.is_empty() && blobs_rewrapped == 0 - && blobs_resealed == 0) + && blobs_resealed == 0 + && blobs_rotated == 0) { return Ok(RewrapReport { secrets_rewrapped, blobs_rewrapped, blobs_resealed, + blobs_rotated, skipped, commit: None, }); @@ -380,20 +414,17 @@ impl Repo { }; let head = crate::refs::current_branch(self.layout())?; let before = crate::refs::read_branch_tip(self.layout(), &head)?; - let msg = if blobs_resealed > 0 { - format!( - "rewrap: {} secret(s), {} blob(s), {} re-sealed randomized", - secrets_rewrapped.len(), - blobs_rewrapped, - blobs_resealed - ) - } else { - format!( - "rewrap: {} secret(s), {} blob(s)", - secrets_rewrapped.len(), - blobs_rewrapped - ) - }; + let mut msg = format!( + "rewrap: {} secret(s), {} blob(s)", + secrets_rewrapped.len(), + blobs_rewrapped + ); + if blobs_resealed > 0 { + msg.push_str(&format!(", {blobs_resealed} re-sealed randomized")); + } + if blobs_rotated > 0 { + msg.push_str(&format!(", {blobs_rotated} rotated")); + } let id = self.commit_snapshot(new_root, vec![tip], registry, protection, "system", &msg)?; crate::oplog::record( self.layout(), @@ -414,6 +445,7 @@ impl Repo { secrets_rewrapped, blobs_rewrapped, blobs_resealed, + blobs_rotated, skipped, commit: Some(id), }) @@ -1011,4 +1043,146 @@ mod tests { drop(repo); std::fs::remove_dir_all(&root).unwrap(); } + + /// ADR-0051: a plain rewrap strips a revoked recipient's wrap but leaves + /// the ciphertext and its DEK alone, so a recipient who kept the old wrap + /// still opens the tip; `--rotate` re-seals under a fresh DEK and closes it. + #[test] + fn rotate_makes_the_tip_unreadable_with_a_revoked_recipients_old_dek() { + let root = tmp_root("rotate"); + let repo = Repo::init(&root).unwrap(); + let (alice_sk, alice_pk) = scl_crypto::generate_keypair(); + let (bob_sk, bob_pk) = scl_crypto::generate_keypair(); + repo.protect("secret/", std::slice::from_ref(&alice_pk), None) + .unwrap(); + std::fs::create_dir_all(root.join("secret")).unwrap(); + std::fs::write(root.join("secret/db.txt"), b"hunter2").unwrap(); + repo.commit("me", "add").unwrap(); + repo.grant("secret/", &alice_sk, &bob_pk).unwrap(); + let tip0 = repo.head_tip().unwrap().unwrap(); + let (old_id, perms) = entry_at(&repo, tip0, "secret/db.txt"); + assert_ne!(perms & scl_core::RANDOMIZED, 0, "premise: randomized"); + + // Bob's DEK, as he holds it from before the revoke. + let bob_dek = { + let wks = repo.snapshot(&tip0).unwrap().protection.wrapped[&old_id].clone(); + let w = wks + .iter() + .find(|w| w.recipient_id == bob_pk.recipient_id().to_string()) + .expect("bob holds a wrap"); + scl_crypto::unwrap_dek_with(w, &bob_sk).unwrap() + }; + let opens_with_bob_dek = |tip: ObjectId| { + let (id, _) = entry_at(&repo, tip, "secret/db.txt"); + let cipher = { + let arc = repo.store_arc(); + let obj = arc.lock().unwrap().get(&id).unwrap(); + match obj { + Object::Blob(b) => b.to_vec(), + other => panic!("not a blob: {other:?}"), + } + }; + scl_crypto::decrypt_path(&cipher, &bob_dek).is_ok() + }; + repo.revoke("secret/", &bob_pk.recipient_id()).unwrap(); + + // Plain rewrap: wraps change, ciphertext does not, bob's old DEK opens. + let plain = repo + .rewrap(&alice_sk, &[], std::slice::from_ref(&alice_pk), false) + .unwrap(); + let tip1 = plain.commit.unwrap(); + assert_eq!(entry_at(&repo, tip1, "secret/db.txt").0, old_id); + assert_eq!(plain.blobs_rotated, 0); + assert!(opens_with_bob_dek(tip1), "the gap rotation closes"); + + // Dry-run reports without committing. + let dry = repo + .rewrap_with(&alice_sk, &[], std::slice::from_ref(&alice_pk), true, true) + .unwrap(); + assert_eq!(dry.blobs_rotated, 1); + assert!(dry.commit.is_none()); + assert_eq!(repo.head_tip().unwrap(), Some(tip1)); + + // Rotate: new ciphertext id, same plaintext for alice, bob's DEK fails. + let rot = repo + .rewrap_with(&alice_sk, &[], std::slice::from_ref(&alice_pk), false, true) + .unwrap(); + assert_eq!(rot.blobs_rotated, 1); + assert_eq!(rot.blobs_resealed, 0, "nothing was convergent"); + assert!(rot.skipped.is_empty()); + let tip2 = rot.commit.unwrap(); + let (new_id, perms2) = entry_at(&repo, tip2, "secret/db.txt"); + assert_ne!(new_id, old_id, "a fresh seal has a new id"); + assert_ne!(perms2 & scl_core::RANDOMIZED, 0); + assert!(!opens_with_bob_dek(tip2), "the old DEK no longer opens it"); + assert_eq!( + decrypt_at(&repo, tip2, "secret/db.txt", &alice_sk), + b"hunter2" + ); + let snap2 = repo.snapshot(&tip2).unwrap(); + assert!( + !snap2.protection.wrapped.contains_key(&old_id), + "the old ciphertext's wraps are dropped from the tip" + ); + assert_eq!(repo.snapshot(&tip2).unwrap().parents, vec![tip1]); + // The unchanged working file still reads as clean: no spurious diff. + let st = repo.status().unwrap(); + assert!( + st.modified.is_empty() && st.deleted.is_empty() && st.added.is_empty(), + "status after rotate: {st:?}" + ); + + // Rotating again is again a fresh seal (not a no-op), and undo restores. + let again = repo + .rewrap_with(&alice_sk, &[], std::slice::from_ref(&alice_pk), false, true) + .unwrap(); + let tip3 = again.commit.unwrap(); + assert_ne!(entry_at(&repo, tip3, "secret/db.txt").0, new_id); + repo.undo().unwrap(); + assert_eq!(repo.head_tip().unwrap(), Some(tip2)); + + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } + + /// A path the identity cannot open is skipped by a rotating run, as by a + /// plain one, and the rest of the sweep still lands. + #[test] + fn rotate_skips_a_path_the_identity_cannot_open_and_rotates_the_rest() { + let root = tmp_root("rotate-skip"); + let repo = Repo::init(&root).unwrap(); + let (alice_sk, alice_pk) = scl_crypto::generate_keypair(); + let (_bob_sk, bob_pk) = scl_crypto::generate_keypair(); + repo.protect("mine/", std::slice::from_ref(&alice_pk), None) + .unwrap(); + repo.protect("theirs/", std::slice::from_ref(&bob_pk), None) + .unwrap(); + std::fs::create_dir_all(root.join("mine")).unwrap(); + std::fs::create_dir_all(root.join("theirs")).unwrap(); + std::fs::write(root.join("mine/a.txt"), b"alice's").unwrap(); + std::fs::write(root.join("theirs/b.txt"), b"bob's").unwrap(); + repo.commit("me", "add").unwrap(); + let tip0 = repo.head_tip().unwrap().unwrap(); + let theirs_before = entry_at(&repo, tip0, "theirs/b.txt").0; + let mine_before = entry_at(&repo, tip0, "mine/a.txt").0; + + let report = repo + .rewrap_with(&alice_sk, &[], std::slice::from_ref(&alice_pk), false, true) + .unwrap(); + assert_eq!(report.blobs_rotated, 1); + assert_eq!( + report.skipped.len(), + 1, + "bob's path is reported, not hidden" + ); + let tip = report.commit.unwrap(); + assert_ne!(entry_at(&repo, tip, "mine/a.txt").0, mine_before); + assert_eq!( + entry_at(&repo, tip, "theirs/b.txt").0, + theirs_before, + "an unopenable blob is left exactly as it was" + ); + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + } } diff --git a/demo/run_rewrap_demo.sh b/demo/run_rewrap_demo.sh index ae722aef..eee74f27 100755 --- a/demo/run_rewrap_demo.sh +++ b/demo/run_rewrap_demo.sh @@ -123,7 +123,25 @@ grep -q "skipped (no key): secret/db.txt" "$work/post-rewrap-switch.err" \ [ "$(cat secret/db.txt)" = "hunter2" ] \ || fail "alice must still decrypt secret/db.txt after rewrap" +# 7. ROTATE (ADR-0051): `sc rewrap --rotate` re-seals every protected file +# under a FRESH key, so a recipient who kept an old wrap cannot open the +# new ciphertext. It reports the rotated blobs, alice still reads the file, +# and bob is still skipped. +rot_out=$("$SC" rewrap --rotate --identity "$keys/alice" 2>"$work/rotate.err") +echo "$rot_out" | grep -q "rotated 1 protected blob(s) under fresh keys" \ + || fail "rewrap --rotate must report 1 rotated blob, got: $rot_out" +"$SC" switch main --identity "$keys/alice" >/dev/null +[ "$(cat secret/db.txt)" = "hunter2" ] \ + || fail "alice must still decrypt secret/db.txt after rotate" +"$SC" switch main --identity "$keys/bob" 2>"$work/post-rotate-switch.err" >/dev/null \ + || fail "switch itself must still succeed for bob after rotate" +grep -q "skipped (no key): secret/db.txt" "$work/post-rotate-switch.err" \ + || fail "bob must stay skipped (no key) for secret/db.txt after rotate" +"$SC" switch main --identity "$keys/alice" >/dev/null + echo "RESULT: bulk rewrap proven -- escrow sweep re-sealed the pre-escrow secret," echo "one undo/redo pair flipped the whole sweep atomically (2 -> 1 -> 2" echo "recipients), and on that same rewrapped tip the R1 re-attached wrap was" echo "stripped (bob's decrypt flipped success -> skipped)." +echo "and rewrap --rotate re-sealed the protected file under a fresh key (alice" +echo "still decrypts, bob stays skipped)." diff --git a/docs/adr/0043-randomized-protected-encryption.md b/docs/adr/0043-randomized-protected-encryption.md index 513ed912..3e9f542e 100644 --- a/docs/adr/0043-randomized-protected-encryption.md +++ b/docs/adr/0043-randomized-protected-encryption.md @@ -149,7 +149,7 @@ cannot be safely keyed without it). One command, one commit, one oplog record, skip-and-report semantics unchanged; sealing to an empty granted set still fails loudly. -### Unlocked follow-on: rotate-for-paths (recorded, not built) +### Unlocked follow-on: rotate-for-paths (built in ADR-0051) ADR-0019 declared per-path DEK rotation "security-meaningless" under convergent encryption — the DEK is a deterministic function of the plaintext, so @@ -158,7 +158,7 @@ for randomized content:** a randomized DEK is independent of the plaintext, so re-sealing a protected path under a fresh DEK is a genuine cryptographic cutover, exactly as `sc secret rotate` already is for secrets. A `sc protect … rotate`-style surface is now a coherent follow-on, recorded here -and in `ROADMAP.md`, **not built** in this phase. +and in `ROADMAP.md`, and built later as `sc rewrap --rotate` (ADR-0051). ## Consequences diff --git a/docs/adr/0051-rotate-protected-paths.md b/docs/adr/0051-rotate-protected-paths.md new file mode 100644 index 00000000..c618eedd --- /dev/null +++ b/docs/adr/0051-rotate-protected-paths.md @@ -0,0 +1,29 @@ +# ADR-0051: Rotating protected paths (`sc rewrap --rotate`) + +- **Status:** Accepted (built) +- **Date:** 2026-10-19 +- **Builds on:** ADR-0043 (randomized protected sealing), ADR-0027 (bulk rewrap), ADR-0019 (secret lifecycle), ADR-0026 (revocation) + +## Context + +`sc revoke` is standing-only, and `sc rewrap` replaces wrap lists: it drops a revoked recipient's wrap from the tip. Neither changes the DEK. A recipient revoked earlier who still holds the old wrap (a clone made before the revoke) keeps opening the tip's ciphertext, because the DEK that opens it has not changed. For secrets this is closed by `sc secret rotate` (fresh DEK). For protected paths ADR-0019 called rotation "security-meaningless" because convergent encryption derives the DEK from the plaintext. ADR-0043 removed that objection for randomized content and recorded rotate-for-paths as an unlocked follow-on. + +## Decision + +`sc rewrap --rotate` (`Repo::rewrap_with(.., rotate = true)`) re-seals every protected blob at the tip under a fresh random DEK and nonce, to exactly the rule's granted set plus escrow. It reuses the existing convergent-upgrade branch of rewrap, which already does the whole job: unwrap the blob's DEK with the identity, decrypt, `encrypt_path_randomized`, wrap the new DEK per recipient, retarget the tree entry, drop the old ciphertext's wrap entry once nothing references it, and record the working file in the stat cache so status stays clean. + +- One command, one commit, one oplog record (`sc undo` reverts it), skip-and-report for entries the identity cannot open, exactly as a plain rewrap. An unopenable blob is left byte-for-byte as it was. +- It changes ciphertext ids, so the root tree changes. A plain rewrap over an all-randomized tip stays policy-only. +- Secrets are re-sealed with a fresh DEK by every rewrap already. +- Reports a separate `blobs_rotated` count; `blobs_resealed` stays the convergent upgrade count. +- All existing guards apply: private branches and partial clones refuse, and an in-progress merge, pick or rebase refuses. + +## Consequences + +- A recipient revoked before the rotation, holding an old wrap and DEK, can no longer open the tip's ciphertext. The test seals a file, grants and revokes a second recipient, shows a plain rewrap leaves their old DEK working, and shows a rotate closes it. +- **Rotation is not erasure.** Every earlier snapshot keeps the old ciphertext and its wraps, and content addressing keeps those reachable; anyone who fetched them can still open them. Rotating the underlying credential remains the real cutover for secret content. +- **Cost.** Every protected blob at the tip is rewritten, so the CAS gains one new blob per protected file per rotation and the old ones become gc-eligible only once nothing reaches them (history does). Rotation is a deliberate operation, not a routine one. + +## Tests + +`rewrap::tests::rotate_makes_the_tip_unreadable_with_a_revoked_recipients_old_dek` (plain rewrap leaves the old DEK working; dry-run reports without committing; rotate changes the id, closes the old DEK, keeps alice's plaintext, drops the old wraps, leaves status clean, rotates again to yet another id, and undoes) and `rotate_skips_a_path_the_identity_cannot_open_and_rotates_the_rest`. `demo/run_rewrap_demo.sh` step 7 proves it through the CLI. diff --git a/docs/adr/README.md b/docs/adr/README.md index a4cbd65e..75b6325c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -61,6 +61,7 @@ supersedes the old one and update the **Status** line of the superseded record. | [0048](0048-presence-based-partial-clones.md) | Presence-based walks for partial clones | Accepted (37b-i, 37b-ii built) | 37b | | [0049](0049-merge-on-partial-clones.md) | Merge on partial clones | Proposed (37c-i to 37c-iv built) | 37c | | [0050](0050-sessions-on-partial-clones.md) | Agent sessions on partial clones | Accepted | 37d | +| [0051](0051-rotate-protected-paths.md) | Rotating protected paths (`sc rewrap --rotate`) | Accepted | — | See [`ROADMAP.md`](../../ROADMAP.md) for the phase sequence. ADR numbers are assigned in creation order, so 0017 — the secret scanner — sequences as phase P5, From 9328135a7565eab7ff0ede5dca9752ccc5960d4f Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 12:40:15 +0300 Subject: [PATCH 2/3] fix(cli): keep --rotate in the skipped-entry retry hint Co-Authored-By: Claude Sonnet 5.5 --- crates/cli/src/main.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index cbbff50b..b6d2d10b 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -4309,7 +4309,12 @@ fn run_rewrap(identity: Option, dry_run: bool, rotate: bool) -> Result< for (entry, reason) in &report.skipped { eprintln!(" {entry}: {reason}"); } - eprintln!("re-run `sc rewrap` with an identity that can open them to complete the sweep"); + let again = if rotate { + "sc rewrap --rotate" + } else { + "sc rewrap" + }; + eprintln!("re-run `{again}` with an identity that can open them to complete the sweep"); } eprintln!( "note: rewrap cuts the live tip only — snapshots already in history keep \ From 74e0fa21b82ad7aef333ce2ae8a0d671fad94ada Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 12:45:57 +0300 Subject: [PATCH 3/3] docs: keep ADR-0043 immutable; point the cutover guidance at sc rewrap --rotate ADR-0051 carries the new decision. The threat model and ARCHITECTURE said a plain sc rewrap is the cryptographic cutover, which leaves a revoked holder's key working; they now name --rotate. Co-Authored-By: Claude Sonnet 5.5 --- ARCHITECTURE.md | 8 +++++--- docs/THREAT-MODEL.md | 6 ++++-- docs/adr/0043-randomized-protected-encryption.md | 4 ++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 40f4e127..22b4e23f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -500,15 +500,17 @@ is recovered via `--identity` and re-sealed. Recipients default to the secret's current set (reverse `recipient_id` lookup against `.sc/recipients.toml`), overridable with `--to`. -Rotation is **secrets-only**: pre-P33 protected paths used convergent +`sc secret rotate` rotates secrets. Protected paths could not be rotated before randomized sealing (P33): they used convergent encryption (`DEK = HKDF(BLAKE3(plaintext))`), so a recipient who checked the file out could re-derive the key — "rotating" a convergent path's DEK is either -dedup-breaking or security-meaningless. Path lifecycle stays on recipient +dedup-breaking or security-meaningless, so their lifecycle stayed on recipient re-wrap (`grant`/`revoke`). `sc secret revoke` remains metadata-only and now hints to run `rotate` for the actual cryptographic cutover. (**P33/ADR-0043:** the security-meaningless objection dissolves for **randomized** content — a random DEK is independent of the plaintext — so a genuine rotate-for-paths -cutover is coherent, and is built as `sc rewrap --rotate` (ADR-0051).) +cutover is coherent and is built as `sc rewrap --rotate` (ADR-0051): it +re-seals every protected blob under a fresh key, where a plain `sc rewrap` +only replaces wrap lists and keeps the key.) `sc escrow set ` / `sc escrow show` configure a single break-glass recipient key (`[escrow]` in `.sc/recipients.toml`) that is diff --git a/docs/THREAT-MODEL.md b/docs/THREAT-MODEL.md index cd20dcb8..d4dc6252 100644 --- a/docs/THREAT-MODEL.md +++ b/docs/THREAT-MODEL.md @@ -78,8 +78,10 @@ too, not just the src-control-side metadata. pre-revoke branches (revocation tombstones, ADR-0026), so a revoked recipient never seals a *fresh* DEK again. But a recipient who already held a wrap can still decrypt the ciphertext sealed *before* the revoke — cryptographic cutover - is rotation (`sc rewrap` on the live tip), not revoke, and history keeps the old - wraps regardless. + is rotation, not revoke: `sc rewrap --rotate` on the live tip re-seals every + protected blob under a fresh key (ADR-0051), whereas a plain `sc rewrap` only + replaces wrap lists and leaves the key a revoked holder already has. History + keeps the old wraps and ciphertext regardless. ## Private branches (`sc branch --private` / `sc branch publish`) — ADR-0044 diff --git a/docs/adr/0043-randomized-protected-encryption.md b/docs/adr/0043-randomized-protected-encryption.md index 3e9f542e..513ed912 100644 --- a/docs/adr/0043-randomized-protected-encryption.md +++ b/docs/adr/0043-randomized-protected-encryption.md @@ -149,7 +149,7 @@ cannot be safely keyed without it). One command, one commit, one oplog record, skip-and-report semantics unchanged; sealing to an empty granted set still fails loudly. -### Unlocked follow-on: rotate-for-paths (built in ADR-0051) +### Unlocked follow-on: rotate-for-paths (recorded, not built) ADR-0019 declared per-path DEK rotation "security-meaningless" under convergent encryption — the DEK is a deterministic function of the plaintext, so @@ -158,7 +158,7 @@ for randomized content:** a randomized DEK is independent of the plaintext, so re-sealing a protected path under a fresh DEK is a genuine cryptographic cutover, exactly as `sc secret rotate` already is for secrets. A `sc protect … rotate`-style surface is now a coherent follow-on, recorded here -and in `ROADMAP.md`, and built later as `sc rewrap --rotate` (ADR-0051). +and in `ROADMAP.md`, **not built** in this phase. ## Consequences