Skip to content
Merged
8 changes: 4 additions & 4 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ a retired pre-P16 snapshot encoding, refused with a clear error):
other object, so it flows through fork/checkout/clone untouched and stays
ciphertext until an authorized context decrypts it.
- **Signature** (P22) — a bytes-only object over a domain-separated snapshot id
(`Ed25519`), indexed on the side (`.sc/signatures`); the crypto stays
(`Ed25519`), indexed on the side (`.sc/signatures.v2`); the crypto stays
quarantined in `crates/crypto`, so `core` sees only opaque bytes.
- **Transcript** (P30) — a sealed agent-session record attached to the snapshot
it motivated: the same envelope shape as a `Secret` (fresh DEK wrapped per
Expand Down Expand Up @@ -291,7 +291,7 @@ recipient/escrow set. See ADR-0019/0027.
HKDF-derived into *both* an X25519 encryption key and an Ed25519 signing key,
written as a single `scl-id-<hex>` file (a pre-P22 v1 `scl-sk-` identity still
parses and encrypts but cannot sign). Signatures are bytes-only CAS objects over
a domain-separated snapshot id, indexed in `.sc/signatures`; `sc verify` walks
a domain-separated snapshot id, indexed in `.sc/signatures.v2`; `sc verify` walks
history and reports a four-state status (trusted ✓ / untrusted ? / invalid ✗ /
unsigned). Session transcripts (P30) reuse the same signing machinery under a
distinct domain. Signing binds identity to a *snapshot id*, detecting history
Expand Down Expand Up @@ -816,7 +816,7 @@ generic `"abandoned"` a manual `ws abandon` still shows. See ADR-0031.

Signatures are ordinary CAS objects (`TAG_SIGNATURE`, bytes-only in
`crates/core` — no crypto crosses the quarantine) over the domain-separated
snapshot id; a local `.sc/signatures` index maps snapshot → signature ids,
snapshot id; a local `.sc/signatures.v2` index maps (snapshot, signer) → signature id,
gc-rooted and pruned alongside dead snapshots. `sc keygen` now emits a **v2
identity**: one random seed, HKDF-derived into *both* an X25519 encryption
key and an Ed25519 signing key in a single `scl-id-<hex>` file (a v1
Expand Down Expand Up @@ -983,7 +983,7 @@ a keyless clone gets ciphertext only. A one-to-many `.sc/transcripts` index
(snapshot → transcript ids) means history-editing ops start each fresh
snapshot with none attached, so there is no stale-provenance carry-forward
to reason about. Signing is opt-in and reuses P22's machinery outright —
same `SignatureObj` type, same `.sc/signatures` index, no second index —
same `SignatureObj` type, same `.sc/signatures.v2` index, no second index —
under a distinct signature domain string.

Because transcripts are ordinary content-addressed CAS objects, transfer
Expand Down
6 changes: 5 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ the code, those win.
| P27 | Partial clone: `sc clone --filter <prefix…>`, `.sc/promisor`, `sc backfill [--all]`; wire `PROTOCOL_VERSION` 3. Blob-size filter (#217): `--filter blob:limit=<size>` (combinable with prefixes; `blob:` is reserved) leaves out blobs of at least that size unless a ref tip reaches them, evaluated by the server (`GetPack.blob_limit`, wire v6); the gap is absence as in ADR-0048, `sc backfill <path>` or a lazy fill repairs it, `.sc/promisor-blob-limit` records limit and scope; `sc fetch` from the promisor origin sends the recorded limit again (`--no-blob-limit` opts out for one fetch); no object-count limit (rejected) | [0037](docs/adr/0037-partial-clone.md), [0055](docs/adr/0055-blob-size-clone-filter.md) |
| P28 | Security hardening: a max object size (default 256 MiB; `--max-object-size` / `SC_MAX_OBJECT_SIZE`, 2 MiB to 1 GiB) caps 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 add [--expires]`/`rotate`/`remove`/`list`; an expired token gets the same 401 as an unknown one), `--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/drop`, always-encrypted body, gc-coupled index; `--no-transcripts` on fetch/clone/push (client-side, per command); drop = grow-only tombstone (a bare `Transcript` object, no wire change), kept by gc, hides the body from fetch/reindex; retained signed tombstones ride a transfer when their snapshot is in it or was collected by the sender, only verifying signatures are indexed, and held-but-untrusted tombstones are re-judged from `.sc/transcript-pending` when the trusted-signer set changes (#230) | [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; `--no-transcripts` on fetch/clone/push (client-side, per command); drop = grow-only tombstone (a bare `Transcript` object, no wire change), kept by gc, hides the body from fetch/reindex; retained signed tombstones ride a transfer when their snapshot is in it or was collected by the sender, only verifying signatures are indexed, and held-but-untrusted tombstones are re-judged from `.sc/transcript-pending` when the trusted-signer set changes (#230); the signature index (`.sc/signatures.v2`) holds one slot per (target, signer) so attacker-made keys cannot crowd out a drop (#257), and serve-path index updates take a short `.sc/index.lock` distinct from the repo lock (#260) | [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; later `--max-conn-bytes` per-connection write budget (#233) | [0041](docs/adr/0041-listener-resource-limits.md) |
| P32 | In-binary TLS: `sc+https://` via leaf crate `tlsio`; accept-new TOFU pinning (`sc tls list/forget/pin/path` manages the pin file); `SC_HTTPS_CA_FILE`/`SC_HTTPS_CA=system` validate against a CA instead; client connect/handshake bounded; public plaintext bind no longer justified by tokens alone | [0042](docs/adr/0042-in-binary-tls-sc-https.md), [0053](docs/adr/0053-tls-pin-management.md), [0054](docs/adr/0054-tls-ca-validation.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) |
Expand Down Expand Up @@ -243,6 +243,10 @@ transport-adjacent. The rest, imperatively:
`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 signature index is `.sc/signatures.v2` (#257).** `.sc/signatures` is the
pre-#257 file, kept only for the one-time import. Do not run an older binary's
`sc gc` on a repo this build has signed in or ingested into: it roots only the
legacy file and sweeps the signatures v2 lists (ADR-0038).
- **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.
Expand Down
4 changes: 3 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -494,7 +494,9 @@ across every phase.
a stale peer is told), only verifying signatures enter the signature index,
and a remote that held a tombstone before trusting the signer re-judges it
from a capped `.sc/transcript-pending` index when the trusted-signer set
changes. Crowding by valid signatures from attacker keys is tracked in #257.
changes. Valid signatures from attacker keys cannot crowd out a drop (#257: the
signature index holds one slot per (target, signer)), and serve-path index
updates take a short index lock (#260).

- **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"
Expand Down
4 changes: 4 additions & 0 deletions crates/repo/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ pub enum Error {
RepoExists(String),
#[error("repo is locked by another process (remove {0} if stale)")]
Locked(String),
/// The short index-update lock (`.sc/index.lock`) stayed busy past its wait.
/// Never remove that file: it is an OS lock on a file that stays in place.
#[error("the index update lock {0} stayed busy; retry (do not remove the file)")]
IndexBusy(String),
#[error("object {0} is corrupt (failed hash verification on read)")]
CorruptObject(ObjectId),
#[error("malformed ref: {0}")]
Expand Down
37 changes: 25 additions & 12 deletions crates/repo/src/gc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ fn walk_decided_root(
pub fn run(layout: &Layout, store: &mut Store, grace: Duration) -> Result<GcStats> {
let mut stats = GcStats::default();

// A pre-#257 signature index must be imported before it is pruned: an
// unread legacy file would otherwise root nothing and lose its objects.
signatures::migrate_legacy(layout, store)?;

// Trim oplog records past the grace window BEFORE computing roots, so a
// just-trimmed record's snapshot doesn't linger as a root this pass (it
// always keeps the newest record regardless of cutoff).
Expand Down Expand Up @@ -164,18 +168,27 @@ pub fn run(layout: &Layout, store: &mut Store, grace: Duration) -> Result<GcStat
// didn't survive are dropped from the index, and their now-unrooted
// transcript object falls through to the ordinary loose-object
// aging/pruning sweep below like any other unreachable object.
stats.transcripts_pruned = transcripts::gc_prune(layout, &mut reachable)?;

// Signature index (P22): a SignatureObj is reachable from no tree/parent
// walk (it isn't referenced by any snapshot), so it needs its own root
// decision here, in the same window the merge/pick/rebase decided-root
// roots above use — after every other root source has contributed to
// `reachable`, but before packing. Entries whose snapshot survived above
// get their signature object rooted into `reachable`; entries whose
// snapshot didn't are dropped from the index, and their now-unrooted
// signature object falls through to the ordinary loose-object
// aging/pruning sweep below like any other unreachable object.
stats.signatures_pruned = signatures::gc_prune(layout, &mut reachable)?;
//
// Both prunes run under one index lock: a serve-path ingest indexing a
// transcript and its signature between them would have the signature
// dropped (its transcript was not rooted).
let (transcripts_pruned, signatures_pruned) = crate::lock::with_index_lock(layout, || {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Hold the index lock across both ingest passes

A serve-path ingest still releases the index lock after signatures::index_incoming (transport.rs:634) and reacquires it separately in transcripts::index_incoming (transport.rs:637). If GC enters this new combined section between those calls, transcript pruning cannot root the newly stored transcript, so signature pruning removes its just-indexed signature; the ingest then adds the transcript entry without its provenance, and a signed tombstone can likewise become neither honored nor pending. The fresh evidence beyond the prior race is this remaining gap between the two ingest passes, so the ingest side also needs one encompassing index-lock transaction.

Useful? React with 👍 / 👎.

let transcripts = transcripts::gc_prune(layout, &mut reachable)?;

// Signature index (P22): a SignatureObj is reachable from no tree/parent
// walk (it isn't referenced by any snapshot), so it needs its own root
// decision here, in the same window the merge/pick/rebase decided-root
// roots above use — after every other root source has contributed to
// `reachable`, but before packing. Entries whose snapshot survived above
// get their signature object rooted into `reachable`; entries whose
// snapshot didn't are dropped from the index, and their now-unrooted
// signature object falls through to the ordinary loose-object
// aging/pruning sweep below like any other unreachable object.
let signatures = signatures::gc_prune(layout, &mut reachable)?;
Ok((transcripts, signatures))
})?;
stats.transcripts_pruned = transcripts_pruned;
stats.signatures_pruned = signatures_pruned;

// 1. Repack the entire reachable set into one fresh pack (skip if empty).
let new_hash = if reachable.is_empty() {
Expand Down
11 changes: 9 additions & 2 deletions crates/repo/src/layout.rs
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,16 @@ impl Layout {
pub fn oplog_path(&self) -> PathBuf {
self.dot_sc.join("oplog")
}
/// `.sc/signatures` — the append-only snapshot-signature index (P22):
/// one `<snapshot-hex> <sig-object-hex>` line per indexed signature.
/// `.sc/signatures.v2` — the signature index (P22, keyed per
/// `(target, signer)` since #257): one `<target-hex> <sig-object-hex>
/// <signer-hex>` line per indexed signature.
pub fn signatures_path(&self) -> PathBuf {
self.dot_sc.join("signatures.v2")
}
/// `.sc/signatures` — the pre-#257 index (`<target> <sig>` lines). Read
/// once by the migration into [`Self::signatures_path`], then left alone
/// so an older binary keeps a file it understands.
pub fn signatures_legacy_path(&self) -> PathBuf {
self.dot_sc.join("signatures")
}
/// `.sc/sparse` — the sparse-checkout prefix spec (P24): one prefix per
Expand Down
120 changes: 120 additions & 0 deletions crates/repo/src/lock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,77 @@ impl RepoLock {
}
}

thread_local! {
/// Index locks this thread holds (by path), so a nested critical section
/// on the same thread reuses the held lock instead of deadlocking on it.
static HELD_INDEX_LOCKS: std::cell::RefCell<Vec<PathBuf>> = const { std::cell::RefCell::new(Vec::new()) };
}

/// How long [`with_index_lock`] waits for another holder before giving up.
/// Tests get a long wait: their threads queue behind durable (fsynced) writes
/// on a loaded machine; the timeout path is tested with `with_index_lock_for`.
const INDEX_LOCK_WAIT: std::time::Duration =
std::time::Duration::from_secs(if cfg!(test) { 300 } else { 30 });

/// Run `f` holding the short-lived index lock (`.sc/index.lock`, ADR-0038
/// "Index lock", #260). It serializes the read-modify-write of the derived
/// index files (`signatures.v2`, `transcripts`, `transcript-pending`...)
/// between concurrent serve-path ingests and local commands, WITHOUT being
/// [`RepoLock`]: it is held only around one index update (or one coupled
/// group of them), never for a command's lifetime, so it never turns a busy repo into `Locked` for a
/// local `sc` command.
///
/// An advisory `flock` on a file that is never removed: the OS drops it when
/// the holder dies, so there is no stale-lock breaking (and none of its
/// races). Polls up to [`INDEX_LOCK_WAIT`], then `Error::IndexBusy`. Reentrant per
/// thread. Lock order: this lock is a leaf. Never acquire [`RepoLock`] (or
/// wait on anything else) while holding it; taking it under `RepoLock` is fine.
pub(crate) fn with_index_lock<T>(layout: &Layout, f: impl FnOnce() -> Result<T>) -> Result<T> {
with_index_lock_for(layout, INDEX_LOCK_WAIT, f)
}

fn with_index_lock_for<T>(
layout: &Layout,
wait: std::time::Duration,
f: impl FnOnce() -> Result<T>,
) -> Result<T> {
let path = layout.dot_sc.join("index.lock");
if HELD_INDEX_LOCKS.with(|h| h.borrow().contains(&path)) {
return f();
}
let file = std::fs::OpenOptions::new()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(&path)?;
let deadline = std::time::Instant::now() + wait;
loop {
match file.try_lock() {
Ok(()) => break,
Err(std::fs::TryLockError::WouldBlock) if std::time::Instant::now() < deadline => {
std::thread::sleep(std::time::Duration::from_millis(2));
}
Err(std::fs::TryLockError::WouldBlock) => {
return Err(Error::IndexBusy(path.display().to_string()))
}
Comment on lines +108 to +110

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Do not tell users to remove the live flock file

When index-lock contention lasts longer than ten seconds, this reuses Error::Locked, whose rendered message says to remove the named lock file if stale. Unlike the PID-based repo lock, .sc/index.lock is intentionally never removed: on Unix, unlinking it while the holder still owns the old inode lets the next process create and lock a different inode, so two writers can enter the protected index sections concurrently and lose entries. Return a distinct timeout error without the removal instruction.

Useful? React with 👍 / 👎.

Err(std::fs::TryLockError::Error(e)) => return Err(e.into()),
}
}
HELD_INDEX_LOCKS.with(|h| h.borrow_mut().push(path.clone()));
// Pops the entry (and unlocks via `file`'s drop) even if `f` panics.
struct Release(PathBuf);
impl Drop for Release {
fn drop(&mut self) {
HELD_INDEX_LOCKS.with(|h| h.borrow_mut().retain(|p| p != &self.0));
}
}
let _release = Release(path);
let out = f();
drop(file);
out
}

/// True only when the lock file names a PID we can *prove* is not running.
/// Unreadable file, no parseable PID, or an inconclusive probe all return
/// false (respect the lock).
Expand Down Expand Up @@ -143,4 +214,53 @@ mod tests {
assert_eq!(content.trim(), std::process::id().to_string());
std::fs::remove_dir_all(&layout.root).unwrap();
}

#[test]
fn index_lock_is_not_the_repo_lock() {
// Holding either never makes the other fail: a local command keeps
// `RepoLock` for its lifetime while a serve-path ingest takes the short
// index lock, and vice versa (#260).
let layout = tmp_layout("idx-indep");
let repo_lock = RepoLock::acquire(&layout).unwrap();
with_index_lock(&layout, || Ok(())).unwrap();
assert!(matches!(RepoLock::acquire(&layout), Err(Error::Locked(_))));
drop(repo_lock);
with_index_lock(&layout, || {
// Reentrant on the same thread, and RepoLock is still free.
with_index_lock(&layout, || Ok(()))?;
drop(RepoLock::acquire(&layout)?);
Ok(())
})
.unwrap();
std::fs::remove_dir_all(&layout.root).unwrap();
assert!(!layout.root.exists());
}

#[test]
fn index_lock_serializes_threads_and_times_out_with_locked() {
let layout = tmp_layout("idx-wait");
let (held_tx, held_rx) = std::sync::mpsc::channel();
let (release_tx, release_rx) = std::sync::mpsc::channel::<()>();
let l2 = layout.clone();
let holder = std::thread::spawn(move || {
with_index_lock(&l2, || {
held_tx.send(()).unwrap();
release_rx.recv().unwrap();
Ok(())
})
.unwrap();
});
held_rx.recv().unwrap();
// Another thread of the same process waits, then gives up.
assert!(matches!(
with_index_lock_for(&layout, std::time::Duration::from_millis(100), || Ok(())),
Err(Error::IndexBusy(_))
));
release_tx.send(()).unwrap();
holder.join().unwrap();
// Released: free again, and the failed waiter left no held entry.
with_index_lock(&layout, || Ok(())).unwrap();
std::fs::remove_dir_all(&layout.root).unwrap();
assert!(!layout.root.exists());
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}
5 changes: 5 additions & 0 deletions crates/repo/src/repo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,11 @@ impl Repo {
fn open_layout(layout: Layout, budget_bytes: usize) -> Result<Repo> {
let lock = RepoLock::acquire(&layout)?;
let mut store = Store::open_persistent(layout.objects_dir(), budget_bytes)?;
// Import a pre-#257 signature index first (best effort; every writer
// and gc retry it and fail rather than start a v2 file without it): the
// re-evaluation below reads that index, and a pass that saw it empty
// would record the trust as judged.
let _ = crate::signatures::migrate_legacy(&layout, &mut store);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Skip trust re-evaluation when migration fails

When the legacy import fails transiently—particularly with IndexBusy while another process holds .sc/index.lock—discarding this error and then unconditionally re-evaluating pending tombstones can let the second call acquire the lock, observe an empty v2 index, and persist the current trust fingerprint. A later open may successfully import the validating signature but skip re-evaluation because that fingerprint now matches, leaving a trusted drop inert until another trust change. The fresh case left after reordering is the ignored migration failure immediately before the re-evaluation; only re-evaluate after a successful import, or keep the trust state dirty when import fails.

Useful? React with 👍 / 👎.

// Honor held tombstones once the trusted-signer set changed (#230). Best
// effort: a failure must not stop an open, and the next open retries.
let _ = crate::transcripts::reevaluate_if_trust_changed(&layout, &mut store);
Expand Down
Loading
Loading