Repository navigation
P34: per-branch access control — private branches (ADR-0044) - #46
Conversation
Adds the last thesis pillar: staging an embargoed fix on a branch that is fully opaque to non-recipients (content, file paths, commit messages, DAG shape) until a coordinated release, then made public atomically. - crates/core: two additive object kinds — Object::Sealed (nonce‖AEAD of an inner object's encoding) and Object::Manifest (BranchManifest: base, prev chain, sealed-closure list, KEK-encrypted index, per-recipient KEK wraps). No existing object format changes. - crates/crypto/private.rs: seal_object/open_object (per-object random DEK, distinct AAD), the branch KEK (reusing the P2 X25519 envelope), and the encrypted BranchIndex (inner id → sealed id + DEK). RustCrypto stays quarantined. - crates/repo/private.rs: copy-on-write sealing (unchanged content keeps its public id), private commit/switch/status/diff/log, merge-public-into- private, grant (O(1) wrap), revoke (atomic KEK rotation + rewrap, zero content plaintext, zero id churn), and publish (two-phase: scanner gate over decrypted content before any public write, then replay to plaintext snapshots). Refusals centralized via refuse_on_private + PrivateIntegration. - gc/reachable manifest dispatch; is_ancestor over the manifest prev chain + publish transition; filtered clones exclude private refs; PROTOCOL_VERSION 3 → 4 (sealed kinds cross the wire). - CLI: sc branch <name> --private --to / grant / revoke / publish / list; --identity on status/diff/log; export + git-push refusals. - Docs: ADR-0044, THREAT-MODEL section, CLAUDE.md/ARCHITECTURE/ROADMAP, demo/run_private_branch_demo.sh (opacity, membership, valve, publish, zero residue — run twice). 717 workspace tests pass (14 new private-branch tests incl. a wire-pack decode opacity check); every existing demo green. Claude-Session: https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB
Advisor review caught a blocking transfer/gc bug: merge_into_private carries the merged-in public tip's objects into the sealed inner tree as unsealed public references (copy-on-write), but the manifest only anchored `base` (the fork point) — so a public object added after the fork and merged in was reachable through no root a keyless transfer or gc could follow. Pushing just the private branch to a peer lacking those commits would strand the sealed tree. Masked in-repo because `main` + the oplog kept the objects alive. Fix: cumulative plaintext `anchors: Vec<ObjectId>` on BranchManifest — the merged-in public tips — walked as reachability roots alongside `base` in reachable_objects_filtered. Threaded through every manifest constructor (commit merge-completion, both merge_into_private paths). Costs one metadata leak (which public commits were merged in), same class as `base`. Two regression tests: reachability from the manifest alone now includes the merged blob, and a peer cloned without the public source still opens the merged private branch. 719 workspace tests pass. Claude-Session: https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB
…fer test - THREAT-MODEL.md: record the second reachability-anchor metadata leak (which public commits were merged in) alongside the fork-point leak, so it agrees with the ADR "As built" section. - Extend merge_public_into_private_clean_then_conflicted to assert the CONFLICT-completion path also anchors merged-in public content (reachable_objects from the manifest includes the public blob) — the clean path was already transfer-tested; this covers the shared machinery on the conflict branch. 719 workspace tests pass. Claude-Session: https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB
There was a problem hiding this comment.
Pull request overview
Implements Phase 34 “private branches” (ADR-0044): branch refs can point to a sealed-branch manifest that keeps branch contents, file paths, commit metadata, and inner DAG shape opaque to non-recipients until an explicit sc branch publish, including transport/gc reachability support and CLI surface area.
Changes:
- Adds two new object kinds (
Object::Sealed,Object::Manifest) plus branch-level crypto/indexing to support per-branch sealing with grant/revoke/publish workflows. - Updates repo operations/guards (status/diff/log/switch/merge/export/push/etc.) to correctly refuse or dispatch when HEAD/targets are private, and ensures filtered clones exclude private branches.
- Bumps wire protocol to v4 and adds documentation + demo coverage for the new security boundaries and operational semantics.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| ROADMAP.md | Records deferred follow-ons for private branches (publish squash, no-escrow, manifest privacy/scalability, etc.). |
| docs/THREAT-MODEL.md | Documents defended properties and accepted metadata leaks for private branches. |
| docs/adr/0044-per-branch-access-control.md | Adds the accepted ADR specifying the design and rationale for private branches. |
| demo/run_private_branch_demo.sh | Adds an end-to-end demo script covering opacity, membership, valve behavior, publish, and residue checks. |
| crates/repo/src/ws.rs | Refuses sc ws fork when on a private branch. |
| crates/repo/src/workspace.rs | Refuses sc work when on a private branch. |
| crates/repo/src/wire.rs | Bumps PROTOCOL_VERSION from 3 to 4 with rationale. |
| crates/repo/src/transport.rs | Filters manifest wants for filtered transfers; plumbs updated want handling into reachability. |
| crates/repo/src/transcripts.rs | Refuses transcript attach on manifest tips. |
| crates/repo/src/sync.rs | Skips excluded private refs in filtered clones; avoids materializing private HEAD on clone. |
| crates/repo/src/sparse.rs | Refuses sparse operations on private branches. |
| crates/repo/src/signatures.rs | Refuses signing a manifest tip. |
| crates/repo/src/secrets.rs | Refuses secret ops and sc run on private branches. |
| crates/repo/src/rewrap.rs | Refuses sc rewrap on private branches. |
| crates/repo/src/repo.rs | Routes/guards core repo operations for private branches; shares diff rendering helper with private diff. |
| crates/repo/src/replay.rs | Refuses cherry-pick/rebase on private branches and blocks integrating from private refs. |
| crates/repo/src/reachable.rs | Adds manifest-aware reachability + filtered-clone exclusion of manifest wants. |
| crates/repo/src/protect_ops.rs | Refuses protect/grant/revoke/list on private branches. |
| crates/repo/src/private.rs | Introduces the private-branch implementation (manifests, copy-on-write sealing, grant/revoke, merge-in, publish, tests). |
| crates/repo/src/oplog.rs | Updates undo behavior to avoid rematerializing when manifest tips are involved. |
| crates/repo/src/merge.rs | Extends ancestry logic to understand manifest chains and publish transitions. |
| crates/repo/src/lib.rs | Exposes the new private module. |
| crates/repo/src/error.rs | Adds new private-branch error variants and messages. |
| crates/crypto/src/private.rs | Adds sealed-object encryption + KEK wrapping + encrypted BranchIndex codec. |
| crates/crypto/src/lib.rs | Exposes the new crypto private-branch primitives. |
| crates/core/src/object.rs | Adds new tags and encode/decode support for sealed objects and branch manifests. |
| crates/core/src/lib.rs | Re-exports new core object types. |
| crates/cli/src/main.rs | Adds CLI surface for private branches and identity plumbing for status/diff/log; blocks git bridge operations for private branches. |
| CLAUDE.md | Updates working guide with P34 commands, boundaries, and protocol version note. |
| ARCHITECTURE.md | Adds Phase 34 architectural overview section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /// Whether `anc` is an ancestor of (or equal to) `desc`. | ||
| /// | ||
| /// Private branches (P34): a branch manifest's "parents" are its superseded | ||
| /// manifest (`prev`) plus its public base, so the push fast-forward check | ||
| /// works over manifest chains unchanged. One extra rule covers the publish | ||
| /// transition: a manifest `anc` also counts as an ancestor of a snapshot | ||
| /// `desc` when its BASE is — publishing rewrites the branch to plaintext | ||
| /// snapshots forked at that base, and a remote holding the pre-publish | ||
| /// manifest must accept the published tip as a forward move. | ||
| pub fn is_ancestor(store: &mut Store, anc: ObjectId, desc: ObjectId) -> Result<bool> { | ||
| Ok(ancestors(store, desc)?.contains(&anc)) | ||
| let desc_anc = ancestors(store, desc)?; | ||
| if desc_anc.contains(&anc) { | ||
| return Ok(true); | ||
| } | ||
| // Publish transition ONLY: `desc` must be a snapshot. Between two | ||
| // manifests, ancestry is exclusively the prev chain (already covered | ||
| // above) — treating "shares my base" as ancestry there would let a | ||
| // stale manifest fast-forward over a newer one, rolling back grants/ | ||
| // revokes/commits. | ||
| if let Ok(Object::Manifest(m)) = store.get(&anc) { | ||
| if matches!(store.get(&desc), Ok(Object::Snapshot(_))) { | ||
| return Ok(desc_anc.contains(&m.base)); | ||
| } | ||
| } |
There was a problem hiding this comment.
Good catch — this was a real data-loss hole, and it also contradicted the ADR's own statement that publish is a non-fast-forward rewrite. Since publish severs the manifest→snapshot id chain by construction (a sealed id is BLAKE3(ciphertext), a public id BLAKE3(plaintext)), there's no sound way to check the published snapshot descends from the specific manifest being replaced — so I removed the special case entirely. is_ancestor is now purely the prev-chain walk, making a rollback-republish (or any publish-push over a remote still holding the private manifest) a genuine non-fast-forward: the remote fetches, or the operator force-pushes, same posture as amend/rebase. Fixed in fc174f5; the ancestry test now pins the safe behavior including the exact rollback case you described.
| /// The working-tree file paths (repo-relative, sorted) that `commit` would | ||
| /// snapshot — the same set `sc protect` encrypts when they match a prefix. | ||
| pub fn worktree_paths(&self) -> Result<Vec<String>> { | ||
| self.refuse_on_private("this operation")?; |
There was a problem hiding this comment.
Fixed in fc174f5. worktree_paths now names the operation ('listing the working-tree paths') instead of 'this operation', and run_protect skips the cosmetic low-entropy nudge (its only caller) on a private branch, so the authoritative message from repo.protect() — 'sc protect is not supported on a private branch (publish it first: sc branch publish)' — is what the user actually sees.
…guard msg
Two review comments:
1. (data loss) `is_ancestor` had a manifest→snapshot special case treating a
manifest as an ancestor of any snapshot sharing its `base`. That let a
rolled-back older manifest (same fork point) re-published over a newer
remote manifest pass the push fast-forward check and silently clobber the
remote's grants/revokes/commits. It also contradicted ADR-0044's own
statement that publish is a non-fast-forward rewrite. Since publish severs
the id chain by construction, no sound "descends from THIS manifest" check
exists — so the special case is removed: `is_ancestor` is purely the prev-
chain walk, and a publish-push over a remote still holding the private
manifest is a genuine non-ff (fetch or force-push, same as amend/rebase).
Test renamed + rewritten to pin the safe behavior (incl. the rollback case).
2. (message quality) `worktree_paths` refused with an unhelpful "this
operation" string. Now names it ("listing the working-tree paths"), and
run_protect skips the cosmetic low-entropy nudge on a private branch so the
authoritative "sc protect is not supported on a private branch" message
from repo.protect() surfaces instead.
ADR "As built" records both fixes. 719 workspace tests pass; demo + clippy clean.
Claude-Session: https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB
Adds the last thesis pillar: staging an embargoed fix (canonically a CVE) on a
branch that is fully opaque to non-recipients — content, file paths, commit
messages, and DAG shape all sealed — until a coordinated
sc branch publish.What it does
sc branch <name> --private --to <recipient>...creates a branch whose refpoints at a sealed-branch manifest, not a snapshot. Every object a private
commit introduces (snapshot, tree, blob) is individually sealed
(
Object::Sealed, fresh random DEK); an encrypted index maps inner ids →sealed ids under a per-branch KEK wrapped per recipient + escrow.
forked from
mainseals nothing until something actually changes.sc branch grant(O(1) KEK wrap) /sc branch revoke(atomic KEK rotation +rewrap — zero content plaintext, zero object-id churn; a revoked recipient
keeps what they already fetched, rotation ≠ erasure).
sc branch publishreplays the sealed history as plaintext public commits(messages/authors preserved, new ids by construction, published commits start
unsigned); the P5 scanner runs over all decrypted content before any
public object is written.
current); the reverse — and git export/push of a private branch — is refused
everywhere except publish.
only. Filtered clones exclude private branches.
PROTOCOL_VERSION3 → 4 forthe two additive object kinds; no existing object format changes.
Layout
crates/core:Object::Sealed+Object::Manifest(two additive tags).crates/crypto/private.rs:seal_object/open_object, the branch KEK, theencrypted
BranchIndex— RustCrypto stays quarantined.crates/repo/private.rs: create/switch/commit/status/diff/log, merge-public-in, grant/revoke, two-phase publish; refusals centralized via
refuse_on_private+PrivateIntegration.is_ancestorover the manifest chain + publishtransition, filtered-clone exclusion.
sc branch --private/grant/revoke/publish/list;--identityonstatus/diff/log; export + git-push refusals.
Review fix included
An advisor review caught a blocking transfer/gc bug:
merge_into_privatecarriedmerged-in public objects into the sealed tree as unsealed references the manifest
didn't anchor, so pushing just the private branch to a peer lacking those commits
would strand the sealed tree (masked in-repo by
main+ the oplog). Fixed withcumulative plaintext reachability anchors on the manifest, walked as roots
alongside
base. Two regression tests pin it (reachability from the manifestalone; a peer cloned without the public source still opens the branch); the
conflict-completion path is covered too.
Docs
ADR-0044 (Accepted), THREAT-MODEL.md section (defends / leaks-by-design incl. the
anchor metadata), CLAUDE.md + ARCHITECTURE.md + ROADMAP.md, and
demo/run_private_branch_demo.sh(opacity, membership, the integration valve,publish, zero residue — run twice).
Verification
719 workspace tests pass (16 private-branch tests incl. a wire-pack decode
opacity check and the two anchor-transfer tests); every existing demo green;
clippy + fmt clean.
https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB