Skip to content

P34: per-branch access control — private branches (ADR-0044) - #46

Merged
tonibergholm merged 4 commits into
mainfrom
p34-private-branches
Jul 11, 2026
Merged

tonibergholm merged 4 commits into
mainfrom
p34-private-branches

Conversation

@tonibergholm

Copy link
Copy Markdown
Member

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 ref
    points 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.
  • Copy-on-write sealing: unchanged content keeps its public id, so a branch
    forked from main seals 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 publish replays 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.
  • Merging a public branch into a private one is allowed (keeps an embargo
    current); the reverse — and git export/push of a private branch — is refused
    everywhere except publish.
  • Opaque over every transport: a keyless clone gets ciphertext + a name marker
    only. Filtered clones exclude private branches. PROTOCOL_VERSION 3 → 4 for
    the 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, the
    encrypted 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.
  • gc/reachable manifest dispatch, is_ancestor over the manifest chain + publish
    transition, filtered-clone exclusion.
  • CLI sc branch --private/grant/revoke/publish/list; --identity on
    status/diff/log; export + git-push refusals.

Review fix included

An advisor review caught a blocking transfer/gc bug: merge_into_private carried
merged-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 with
cumulative plaintext reachability anchors on the manifest, walked as roots
alongside base. Two regression tests pin it (reachability from the manifest
alone; 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

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

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread crates/repo/src/merge.rs Outdated
Comment on lines +37 to +60
/// 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));
}
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread crates/repo/src/repo.rs Outdated
/// 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")?;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@tonibergholm
tonibergholm merged commit 347f9c7 into main Jul 11, 2026
5 checks passed
@tonibergholm
tonibergholm deleted the p34-private-branches branch July 11, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants