OXYGENHUB
# 0a45ba84393a oxygen / crates / oxy-core / src / repo / sync.rs
30.1 KiB · Rust · last changed Trust policy: policy objects, init/grant/revoke, enforcement on push and fetch, propagation with downgrade protection (spec 0.6) 1 month ago source blame history raw
1 
//! Serving and talking to remotes (spec §10.2, §16).
2
3 
use super::*;
4
5 
/// What a fetch brought in.
6 
#[derive(Debug, Clone, PartialEq, Eq, Default)]
7 
pub struct FetchReport {
8 
    /// Bookmark name, its heads, and how many changes were new.
9 
    pub refs: Vec<(String, Vec<ChangeHash>, usize)>,
10 
    /// The remote has never presented a policy, so nothing was verified
11 
    /// against one (spec §14.5: warn loudly).
12 
    pub unverified: bool,
13 
}
14
15 
#[derive(Debug, Clone, PartialEq, Eq)]
16 
pub struct PullReport {
17 
    pub heads: Vec<ChangeHash>,
18 
    pub changed: bool,
19 
    pub checked_out: bool,
20 
}
21
22 
impl Repo {
23 
    // ------------------------------------------------------------ serving (spec §16)
24
25 
    fn ref_attest_path(&self, bookmark: &str) -> PathBuf {
26 
        self.oxy.join("attest").join(bookmark)
27 
    }
28
29 
    /// The latest reference attestation stored for a bookmark.
30 
    pub fn latest_ref_attest(&self, bookmark: &str) -> Result<Option<(ObjectRef, SignedAttest)>> {
31 
        match fs::read_to_string(self.ref_attest_path(bookmark)) {
32 
            Ok(h) => {
33 
                let r = ObjectRef::from_hex(h.trim()).ok_or_else(|| RepoError::Msg("corrupt attestation pointer".into()))?;
34 
                Ok(Some((r, SignedAttest { attest: self.store.get_attest(&r)?, sigs: self.store.signatures(&r)? })))
35 
            }
36 
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
37 
            Err(e) => Err(e.into()),
38 
        }
39 
    }
40
41 
    fn set_ref_attest(&self, bookmark: &str, r: &ObjectRef) -> Result<()> {
42 
        fs::create_dir_all(self.oxy.join("attest"))?;
43 
        write_atomic(&self.ref_attest_path(bookmark), r.to_hex().as_bytes())
44 
    }
45
46 
    pub fn remote_refs(&self) -> Result<RefsResponse> {
47 
        let view = self.view()?;
48 
        let mut out = Vec::new();
49 
        for (name, state) in &view.bookmarks {
50 
            let latest = self.latest_ref_attest(name)?.map(|(_, a)| a);
51 
            let last_serial = latest.as_ref().and_then(|a| match a.attest.body {
52 
                AttestBody::Ref { serial, .. } => Some(serial),
53 
                _ => None,
54 
            });
55 
            let attestation = latest.filter(|a| matches!(&a.attest.body, AttestBody::Ref { new_state, .. } if new_state == state));
56 
            out.push(RemoteRef { name: name.clone(), state: *state, heads: self.store.get_state(state)?.heads, attestation, last_serial });
57 
        }
58 
        Ok(RefsResponse { refs: out, policy: self.current_policy()?.map(|(_, sp)| sp) })
59 
    }
60
61 
    /// Every change reachable from `heads` that is in the store.
62 
    fn closure_in_store(&self, heads: &[ChangeHash]) -> Result<BTreeSet<ChangeHash>> {
63 
        let mut seen = BTreeSet::new();
64 
        let mut stack: Vec<ChangeHash> = heads.to_vec();
65 
        while let Some(h) = stack.pop() {
66 
            if seen.contains(&h) || !self.store.has(&h) {
67 
                continue;
68 
            }
69 
            seen.insert(h);
70 
            stack.extend(self.store.get_change(&h)?.deps);
71 
        }
72 
        Ok(seen)
73 
    }
74
75 
    /// `closure(want) \ closure(have)`, dependencies first (spec §16.2).
76 
    pub fn negotiate(&self, have: &[ChangeHash], want: &[ChangeHash]) -> Result<Vec<ChangeHash>> {
77 
        let have = self.closure_in_store(have)?;
78 
        let mut out = Vec::new();
79 
        let mut done: BTreeSet<ChangeHash> = have.clone();
80 
        // Iterative post-order DFS.
81 
        let mut stack: Vec<(ChangeHash, bool)> = want.iter().rev().map(|h| (*h, false)).collect();
82 
        while let Some((h, expanded)) = stack.pop() {
83 
            if done.contains(&h) {
84 
                continue;
85 
            }
86 
            if !self.store.has(&h) {
87 
                return fail(format!("change {} is not in this repository", h.short(12)));
88 
            }
89 
            if expanded {
90 
                done.insert(h);
91 
                out.push(h);
92 
                continue;
93 
            }
94 
            stack.push((h, true));
95 
            for d in self.store.get_change(&h)?.deps {
96 
                if !done.contains(&d) {
97 
                    stack.push((d, false));
98 
                }
99 
            }
100 
        }
101 
        Ok(out)
102 
    }
103
104 
    /// Bundle changes (in the given dependency order) with their signatures,
105 
    /// seals, identities, blobs, chunks.
106 
    pub fn bundle_for(&self, changes: &[ChangeHash]) -> Result<Bundle> {
107 
        let mut bundle = Bundle::default();
108 
        let mut objects: BTreeSet<ObjectRef> = BTreeSet::new();
109 
        let mut seals: BTreeSet<ObjectRef> = BTreeSet::new();
110 
        let add_object = |r: &ObjectRef, objects: &mut BTreeSet<ObjectRef>| {
111 
            if !r.is_zero() && self.store.has(r) {
112 
                objects.insert(*r);
113 
            }
114 
        };
115 
        for h in changes {
116 
            let c = self.store.get_change(h)?;
117 
            let sigs = self.store.signatures(h)?;
118 
            add_object(&c.author, &mut objects);
119 
            for s in &sigs {
120 
                add_object(&s.key, &mut objects);
121 
            }
122 
            for e in &c.edits {
123 
                if let Edit::Replace { old, new, .. } = e {
124 
                    for b in [old, new].into_iter().flatten() {
125 
                        if self.store.has(b) {
126 
                            objects.insert(*b);
127 
                            if let Ok(blob) = Blob::decode(&self.store.get_typed(b, ObjectType::Blob)?) {
128 
                                objects.extend(blob.chunks.iter().copied());
129 
                            }
130 
                        }
131 
                    }
132 
                }
133 
            }
134 
            for s in self.store.seals_for(h)? {
135 
                seals.insert(s);
136 
            }
137 
            bundle.changes.push((c, sigs));
138 
        }
139 
        for r in seals {
140 
            let attest = self.store.get_attest(&r)?;
141 
            let sigs = self.store.signatures(&r)?;
142 
            for s in &sigs {
143 
                add_object(&s.key, &mut objects);
144 
            }
145 
            bundle.attests.push(SignedAttest { attest, sigs });
146 
        }
147 
        for r in objects {
148 
            let (ty, body) = self.store.get(&r)?;
149 
            bundle.objects.push((ty, body));
150 
        }
151 
        Ok(bundle)
152 
    }
153
154 
    /// Store a bundle's contents. With `strict`, every change must
155 
    /// authenticate (signature or seal by its author or a delegate).
156 
    pub fn import_bundle(&self, bundle: &Bundle, strict: bool) -> Result<Vec<ChangeHash>> {
157 
        for (ty, body) in &bundle.objects {
158 
            match ty {
159 
                ObjectType::Chunk | ObjectType::Blob | ObjectType::Identity | ObjectType::State => {
160 
                    self.store.put(*ty, body)?;
161 
                }
162 
                other => return fail(format!("bundle may not carry {} objects", other.name())),
163 
            }
164 
        }
165 
        for sa in &bundle.attests {
166 
            let r = self.store.put_attest(&sa.attest)?;
167 
            for sig in &sa.sigs {
168 
                self.store.put_signature(&r, sig)?;
169 
            }
170 
            if let AttestBody::Seal { hashes } = &sa.attest.body {
171 
                for h in hashes {
172 
                    self.store.index_seal(h, &r)?;
173 
                }
174 
            }
175 
        }
176 
        let incoming: BTreeSet<ChangeHash> = bundle.changes.iter().map(|(c, _)| c.hash()).collect();
177 
        let mut imported = Vec::new();
178 
        for (c, sigs) in &bundle.changes {
179 
            let h = c.hash();
180 
            for d in &c.deps {
181 
                if !self.store.has(d) && !incoming.contains(d) {
182 
                    return fail(format!("change {} depends on {}, which is neither stored nor in the bundle", h.short(12), d.short(12)));
183 
                }
184 
            }
185 
            self.store.put_change(c)?;
186 
            for sig in sigs {
187 
                self.store.put_signature(&h, sig)?;
188 
            }
189 
            imported.push(h);
190 
        }
191 
        if strict {
192 
            for h in &imported {
193 
                if !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. }) {
194 
                    return fail(format!("change {} is not authenticated by its author", h.short(12)));
195 
                }
196 
            }
197 
        }
198 
        Ok(imported)
199 
    }
200
201 
    /// Verify a reference attestation against an update it claims to describe.
202 
    /// `allow_equal` lets a client re-read the attestation it already has; a
203 
    /// server receiving a push requires a strictly greater serial.
204 
    fn check_ref_attest(&self, sa: &SignedAttest, name: &str, old_state: &ObjectRef, new_state: &ObjectRef, last_serial: Option<u64>, allow_equal: bool) -> std::result::Result<u64, String> {
205 
        let AttestBody::Ref { name: n, old_state: o, new_state: nw, serial } = &sa.attest.body else {
206 
            return Err("attestation is not a ref attestation".into());
207 
        };
208 
        if n != name || o != old_state || nw != new_state {
209 
            return Err("attestation does not describe this update".into());
210 
        }
211 
        if sa.attest.repo != self.id().map_err(|e| e.to_string())? {
212 
            return Err("attestation is for a different repository".into());
213 
        }
214 
        if let Some(last) = last_serial {
215 
            if *serial < last || (*serial == last && !allow_equal) {
216 
                return Err(format!("attestation serial {serial} is not greater than the last seen {last}"));
217 
            }
218 
        }
219 
        let r = sa.attest.hash();
220 
        let sig = sa.sigs.first().ok_or("attestation carries no signature")?;
221 
        let id = self.store.get_identity(&sig.key).map_err(|_| format!("unknown key {}", sig.key.short(12)))?;
222 
        verify_signature(&id, sig, Domain::Attest, &r).map_err(|e| e.to_string())?;
223 
        Ok(*serial)
224 
    }
225
226 
    /// Accept a push (spec §16.4). Without a trust policy every repository
227 
    /// is unverified, so unsigned changes and unattested updates are accepted;
228 
    /// attestations that are present must still be valid. With a policy,
229 
    /// every change and update is checked against it. A newer policy in the
230 
    /// push is applied first when it is signed by the current roots.
231 
    pub fn receive_push(&self, bundle: Bundle, updates: Vec<RefUpdate>, policy: Option<SignedPolicy>) -> Result<Vec<RefResult>> {
232 
        let mut results = Vec::new();
233 
        if let Some(sp) = policy {
234 
            let current = self.current_policy()?.map(|(_, c)| c.policy);
235 
            match self.check_policy(&sp, current.as_ref()) {
236 
                Ok(()) => {
237 
                    self.set_policy(&sp, &format!("push received: policy serial {}", sp.policy.serial))?;
238 
                    results.push(RefResult { name: "policy".into(), ok: true, reason: format!("serial {}", sp.policy.serial) });
239 
                }
240 
                Err(e) => {
241 
                    results.push(RefResult { name: "policy".into(), ok: false, reason: e });
242 
                    for u in updates {
243 
                        results.push(RefResult { name: u.name, ok: false, reason: "policy update was rejected".into() });
244 
                    }
245 
                    return Ok(results);
246 
                }
247 
            }
248 
        }
249 
        let policy = self.current_policy()?.map(|(_, sp)| sp.policy);
250 
        if let Err(e) = self.import_bundle(&bundle, policy.is_some()) {
251 
            for u in updates {
252 
                results.push(RefResult { name: u.name, ok: false, reason: e.to_string() });
253 
            }
254 
            return Ok(results);
255 
        }
256 
        let (op_ref, op) = self.head_op()?;
257 
        let mut view = op.view.clone();
258 
        let mut names = Vec::new();
259 
        for u in updates {
260 
            let outcome = self.apply_update(&mut view, &u, policy.as_ref());
261 
            let (ok, reason) = match outcome {
262 
                Ok(()) => (true, String::new()),
263 
                Err(e) => (false, e),
264 
            };
265 
            if ok {
266 
                names.push(u.name.clone());
267 
            }
268 
            results.push(RefResult { name: u.name, ok, reason });
269 
        }
270 
        if !names.is_empty() {
271 
            self.record_op(&[op_ref], &format!("push received: {}", names.join(" ")), view)?;
272 
        }
273 
        Ok(results)
274 
    }
275
276 
    fn apply_update(&self, view: &mut View, u: &RefUpdate, policy: Option<&crate::policy::Policy>) -> std::result::Result<(), String> {
277 
        if u.name == "policy" {
278 
            return Err("the policy reference is updated by sending a policy, not a bookmark update".into());
279 
        }
280 
        let empty = self.store.put_state(&StateObject::new(vec![])).map_err(|e| e.to_string())?;
281 
        let current = view.bookmarks.get(&u.name).copied().unwrap_or(empty);
282 
        if current != u.old_state {
283 
            return Err("stale: the remote bookmark has moved; pull first".into());
284 
        }
285 
        let new_state = self.store.get_state(&u.new_state).map_err(|_| "new state object is missing".to_string())?;
286 
        for h in &new_state.heads {
287 
            if !self.store.has(h) {
288 
                return Err(format!("head {} is missing", h.short(12)));
289 
            }
290 
        }
291 
        if !u.force {
292 
            let old_heads = self.store.get_state(&current).map_err(|e| e.to_string())?.heads;
293 
            let closure = self.closure_in_store(&new_state.heads).map_err(|e| e.to_string())?;
294 
            if let Some(h) = old_heads.iter().find(|h| !closure.contains(h)) {
295 
                return Err(format!("not a fast-forward: current head {} would be dropped (use --force)", h.short(12)));
296 
            }
297 
        }
298 
        if let Some(p) = policy {
299 
            let Some(sa) = &u.attestation else {
300 
                return Err(format!("{:?} requires a signed reference attestation under this repository's policy", u.name));
301 
            };
302 
            let signer = sa.sigs.first().map(|s| s.key).ok_or("attestation carries no signature")?;
303 
            if !p.authorizes(&signer, &u.name) {
304 
                return Err(format!("key {} may not update {:?} under this repository's policy", signer.short(12), u.name));
305 
            }
306 
            let old_heads = self.store.get_state(&current).map_err(|e| e.to_string())?.heads;
307 
            self.state_allowed(&old_heads, &new_state.heads, p, &u.name)?;
308 
        }
309 
        if let Some(sa) = &u.attestation {
310 
            let last = self.latest_ref_attest(&u.name).map_err(|e| e.to_string())?.and_then(|(_, a)| match a.attest.body {
311 
                AttestBody::Ref { serial, .. } => Some(serial),
312 
                _ => None,
313 
            });
314 
            self.check_ref_attest(sa, &u.name, &u.old_state, &u.new_state, last, false)?;
315 
            let r = self.store.put_attest(&sa.attest).map_err(|e| e.to_string())?;
316 
            for sig in &sa.sigs {
317 
                self.store.put_signature(&r, sig).map_err(|e| e.to_string())?;
318 
            }
319 
            self.set_ref_attest(&u.name, &r).map_err(|e| e.to_string())?;
320 
        }
321 
        view.bookmarks.insert(u.name.clone(), u.new_state);
322 
        Ok(())
323 
    }
324
325 
    // ------------------------------------------------------------ client side
326
327 
    fn remote_url(&self, name: &str) -> Result<String> {
328 
        self.config.remotes.get(name).cloned().ok_or_else(|| RepoError::Msg(format!("no remote named {name:?}; add one with `oxy remote add`")))
329 
    }
330
331 
    /// Credentials and trust for a remote: `remote.<name>.token` (else
332 
    /// `$OXY_TOKEN`) and `remote.<name>.ca` (else `$OXY_CA`).
333 
    fn remote_options(&self, name: &str) -> RemoteOptions {
334 
        RemoteOptions {
335 
            token: self.config.remote_tokens.get(name).cloned().or_else(|| std::env::var("OXY_TOKEN").ok()),
336 
            ca: self.config.remote_cas.get(name).map(PathBuf::from).or_else(|| std::env::var("OXY_CA").ok().map(PathBuf::from)),
337 
        }
338 
    }
339
340 
    fn open_named_remote(&self, name: &str) -> Result<Box<dyn crate::protocol::Remote>> {
341 
        open_remote(&self.remote_url(name)?, &self.remote_options(name))
342 
    }
343
344 
    fn serial_path(&self, remote: &str, bookmark: &str) -> PathBuf {
345 
        self.oxy.join("remotes").join(remote).join(format!("{bookmark}.serial"))
346 
    }
347
348 
    fn last_seen_serial(&self, remote: &str, bookmark: &str) -> Option<u64> {
349 
        fs::read_to_string(self.serial_path(remote, bookmark)).ok().and_then(|s| s.trim().parse().ok())
350 
    }
351
352 
    fn record_serial(&self, remote: &str, bookmark: &str, serial: u64) -> Result<()> {
353 
        let p = self.serial_path(remote, bookmark);
354 
        fs::create_dir_all(p.parent().unwrap())?;
355 
        write_atomic(&p, serial.to_string().as_bytes())
356 
    }
357
358 
    fn policy_serial_path(&self, remote: &str) -> PathBuf {
359 
        self.oxy.join("remotes").join(remote).join("policy.serial")
360 
    }
361
362 
    /// The highest policy serial `remote` has ever presented.
363 
    fn remote_policy_serial(&self, remote: &str) -> Option<u64> {
364 
        fs::read_to_string(self.policy_serial_path(remote)).ok().and_then(|s| s.trim().parse().ok())
365 
    }
366
367 
    fn record_policy_serial(&self, remote: &str, serial: u64) -> Result<()> {
368 
        let p = self.policy_serial_path(remote);
369 
        fs::create_dir_all(p.parent().unwrap())?;
370 
        write_atomic(&p, serial.to_string().as_bytes())
371 
    }
372
373 
    /// Every head this repository knows: bookmarks, remote tracking, working copy.
374 
    fn known_heads(&self, view: &View) -> Result<Vec<ChangeHash>> {
375 
        let mut have: BTreeSet<ChangeHash> = BTreeSet::new();
376 
        for st in view.bookmarks.values().chain(view.remotes.values().flat_map(|b| b.values())) {
377 
            if let Ok(s) = self.store.get_state(st) {
378 
                have.extend(s.heads);
379 
            }
380 
        }
381 
        have.extend(view.workspaces.values().copied());
382 
        Ok(have.into_iter().collect())
383 
    }
384
385 
    /// Fetch every bookmark of a remote into `remotes/<name>/bookmarks/*` (spec §10.2).
386 
    pub fn fetch(&self, remote_name: &str) -> Result<FetchReport> {
387 
        let remote = self.open_named_remote(remote_name)?;
388 
        if remote.repo_id()? != self.id()? {
389 
            return fail(format!("remote {remote_name:?} is a different repository (repository IDs differ)"));
390 
        }
391 
        let resp = remote.refs()?;
392 
        // Trust policy (spec §14.5). Adopt the remote's policy when it is newer
393 
        // and signed by roots we trust, or on first contact. A remote that
394 
        // once presented a policy may never present none or an older one:
395 
        // that is a downgrade. A remote that never presented one is
396 
        // unverified, and this fetch is checked only as far as possible.
397 
        let local_policy = self.current_policy()?.map(|(_, sp)| sp.policy);
398 
        let seen = self.remote_policy_serial(remote_name);
399 
        let mut unverified = false;
400 
        match &resp.policy {
401 
            Some(sp) => {
402 
                if seen.is_some_and(|s| sp.policy.serial < s) {
403 
                    return fail(format!("{remote_name} presents policy serial {} but presented {} before: refusing the downgrade", sp.policy.serial, seen.unwrap()));
404 
                }
405 
                match &local_policy {
406 
                    Some(l) if sp.policy.serial < l.serial => {}
407 
                    Some(l) if sp.policy.serial == l.serial => {
408 
                        if sp.policy.hash() != l.hash() {
409 
                            return fail(format!("{remote_name} presents a different policy with the same serial {}", l.serial));
410 
                        }
411 
                    }
412 
                    local => {
413 
                        self.check_policy(sp, local.as_ref()).map_err(|e| RepoError::Msg(format!("policy from {remote_name}: {e}")))?;
414 
                        self.set_policy(sp, &format!("oxy fetch {remote_name} (policy serial {})", sp.policy.serial))?;
415 
                    }
416 
                }
417 
                self.record_policy_serial(remote_name, sp.policy.serial)?;
418 
            }
419 
            None => {
420 
                if seen.is_some() {
421 
                    return fail(format!("{remote_name} presented a policy before but has none now: refusing the downgrade"));
422 
                }
423 
                unverified = true;
424 
            }
425 
        }
426 
        let policy = if unverified { None } else { self.current_policy()?.map(|(_, sp)| sp.policy) };
427 
        let (op_ref, op) = self.head_op()?;
428 
        let mut view = op.view.clone();
429 
        let have = self.known_heads(&view)?;
430 
        let mut report = Vec::new();
431 
        for r in resp.refs {
432 
            let needed = remote.negotiate(&have, &r.heads)?;
433 
            let bundle = remote.fetch(&needed)?;
434 
            // Changes are not individually re-verified here: the bookmark's
435 
            // attestation (checked below) binds its whole state, and the
436 
            // receiver of the push verified the added changes at that time.
437 
            let imported = self.import_bundle(&bundle, false)?;
438 
            for h in &r.heads {
439 
                if !self.store.has(h) {
440 
                    return fail(format!("remote did not send head {}", h.short(12)));
441 
                }
442 
            }
443 
            let state = self.store.put_state(&StateObject::new(r.heads.clone()))?;
444 
            if state != r.state {
445 
                return fail(format!("remote state {} does not match its heads", r.state.short(12)));
446 
            }
447 
            if let Some(p) = &policy {
448 
                let Some(sa) = &r.attestation else {
449 
                    return fail(format!("{remote_name}/{} has no attestation, which its policy requires", r.name));
450 
                };
451 
                let signer = sa.sigs.first().map(|s| s.key).ok_or_else(|| RepoError::Msg("attestation carries no signature".into()))?;
452 
                if !p.authorizes(&signer, &r.name) {
453 
                    return fail(format!("{remote_name}/{}: attested by {}, which the policy does not authorize", r.name, signer.short(12)));
454 
                }
455 
            }
456 
            if let Some(sa) = &r.attestation {
457 
                let AttestBody::Ref { old_state, new_state, .. } = &sa.attest.body else {
458 
                    return fail("remote sent a non-ref attestation for a bookmark");
459 
                };
460 
                let (old_state, new_state) = (*old_state, *new_state);
461 
                let serial = self
462 
                    .check_ref_attest(sa, &r.name, &old_state, &new_state, self.last_seen_serial(remote_name, &r.name), true)
463 
                    .map_err(|e| RepoError::Msg(format!("attestation for {}/{}: {e}", remote_name, r.name)))?;
464 
                if new_state != r.state {
465 
                    return fail(format!("attestation for {}/{} does not cover its current state", remote_name, r.name));
466 
                }
467 
                let ar = self.store.put_attest(&sa.attest)?;
468 
                for sig in &sa.sigs {
469 
                    self.store.put_signature(&ar, sig)?;
470 
                }
471 
                self.record_serial(remote_name, &r.name, serial)?;
472 
            }
473 
            view.remotes.entry(remote_name.to_string()).or_default().insert(r.name.clone(), state);
474 
            report.push((r.name, r.heads, imported.len()));
475 
        }
476 
        if view != op.view {
477 
            self.record_op(&[op_ref], &format!("oxy fetch {remote_name}"), view)?;
478 
        }
479 
        Ok(FetchReport { refs: report, unverified })
480 
    }
481
482 
    /// Fetch, then take the union of the local bookmark's state with the
483 
    /// remote's: no merge change, conflicts become reified (spec §9.4).
484 
    pub fn pull(&self, remote_name: &str) -> Result<PullReport> {
485 
        self.fetch(remote_name)?;
486 
        let (op_ref, op) = self.head_op()?;
487 
        let bookmark = self.config.bookmark.clone();
488 
        let local = self.heads_of(&op.view, &bookmark)?;
489 
        let Some(remote_state) = op.view.remotes.get(remote_name).and_then(|b| b.get(&bookmark)).copied() else {
490 
            return Ok(PullReport { heads: local, changed: false, checked_out: false });
491 
        };
492 
        let remote_heads = self.store.get_state(&remote_state)?.heads;
493 
        let mut all = local.clone();
494 
        all.extend(remote_heads);
495 
        let st = self.load_state(&all)?;
496 
        let mut heads = st.maximal(&all);
497 
        heads.sort();
498 
        let mut sorted_local = local.clone();
499 
        sorted_local.sort();
500 
        if heads == sorted_local {
501 
            return Ok(PullReport { heads, changed: false, checked_out: false });
502 
        }
503 
        let mut view = op.view.clone();
504 
        view.bookmarks.insert(bookmark.clone(), self.store.put_state(&StateObject::new(heads.clone()))?);
505 
        self.record_op(&[op_ref], &format!("oxy pull {remote_name}"), view)?;
506 
        // Follow along if the working copy was clean and on the old heads.
507 
        let snap = self.snapshot("oxy pull")?;
508 
        let clean = snap.wc.tree_ops.is_empty() && snap.wc.edits.is_empty();
509 
        let mut base = snap.base.maximal(&snap.wc.deps);
510 
        base.sort();
511 
        let mut checked_out = false;
512 
        if clean && base == sorted_local {
513 
            self.checkout(&heads, false, "oxy pull (checkout)")?;
514 
            checked_out = true;
515 
        }
516 
        Ok(PullReport { heads, changed: true, checked_out })
517 
    }
518
519 
    /// Push the current bookmark (spec §16.3), sealing this author's unsigned
520 
    /// changes and attesting the reference when a key is available.
521 
    pub fn push(&self, remote_name: &str, force: bool) -> Result<Vec<RefResult>> {
522 
        let remote = self.open_named_remote(remote_name)?;
523 
        if remote.repo_id()? != self.id()? {
524 
            return fail(format!("remote {remote_name:?} is a different repository (repository IDs differ)"));
525 
        }
526 
        let (op_ref, op) = self.head_op()?;
527 
        let bookmark = self.config.bookmark.clone();
528 
        let local_heads = self.heads_of(&op.view, &bookmark)?;
529 
        let resp = remote.refs()?;
530 
        let local_policy = self.current_policy()?.map(|(_, sp)| sp);
531 
        let policy_to_send = match (&local_policy, &resp.policy) {
532 
            (Some(l), Some(r)) if l.policy.serial > r.policy.serial => Some(l.clone()),
533 
            (Some(l), None) => Some(l.clone()),
534 
            (Some(l), Some(r)) if l.policy.serial < r.policy.serial => {
535 
                return fail(format!("{remote_name} has a newer policy (serial {}); fetch first", r.policy.serial));
536 
            }
537 
            _ => None,
538 
        };
539 
        let remote_has_policy = resp.policy.is_some() || policy_to_send.is_some();
540 
        if remote_has_policy && self.secret_key()?.is_none() {
541 
            return fail(format!("{remote_name} enforces a trust policy; pushing needs an identity (`oxy identity create`)"));
542 
        }
543 
        let refs = resp.refs;
544 
        let empty = self.store.put_state(&StateObject::new(vec![]))?;
545 
        let (remote_state, remote_heads, last_serial) = match refs.iter().find(|r| r.name == bookmark) {
546 
            Some(r) => (r.state, r.heads.clone(), r.last_serial),
547 
            None => (empty, vec![], None),
548 
        };
549 
        let new_state = self.store.put_state(&StateObject::new(local_heads.clone()))?;
550 
        // A push that carries a policy re-attests the bookmark even when its
551 
        // state is unchanged, so the current attestation is always by a key
552 
        // the current policy authorizes (a revoked key's attestation would
553 
        // otherwise be refused by every later fetch).
554 
        if new_state == remote_state && policy_to_send.is_none() {
555 
            return Ok(vec![RefResult { name: bookmark, ok: true, reason: "already up to date".into() }]);
556 
        }
557 
        for h in &remote_heads {
558 
            if !self.store.has(h) {
559 
                return fail(format!("the remote has change {} which you do not; pull first", h.short(12)));
560 
            }
561 
        }
562 
        if !force {
563 
            let closure = self.closure_in_store(&local_heads)?;
564 
            if let Some(h) = remote_heads.iter().find(|h| !closure.contains(h)) {
565 
                return fail(format!("not a fast-forward: remote head {} is not in your state; pull first or use --force", h.short(12)));
566 
            }
567 
        }
568 
        let to_send = self.negotiate(&remote_heads, &local_heads)?;
569 
        let mut bundle = self.bundle_for(&to_send)?;
570 
        let key = self.secret_key()?.map(|(k, _)| k);
571 
        if let Some(key) = key {
572 
            // Seal this author's changes that carry no valid authenticator.
573 
            let mut unsigned = Vec::new();
574 
            for h in &to_send {
575 
                let c = self.store.get_change(h)?;
576 
                if c.author == key && !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. }) {
577 
                    unsigned.push(*h);
578 
                }
579 
            }
580 
            for chunk in unsigned.chunks(crate::attest::MAX_SEAL_HASHES) {
581 
                let sa = self.sign_attest(&Attest::seal(self.id()?, chunk.to_vec()))?;
582 
                bundle.attests.push(sa);
583 
            }
584 
            bundle = self.bundle_for(&to_send)?;
585 
        }
586 
        bundle.objects.push((ObjectType::State, StateObject::new(local_heads.clone()).encode()));
587 
        let attestation = match key {
588 
            Some(_) => Some(self.sign_attest(&Attest {
589 
                repo: self.id()?,
590 
                hlc: Hlc::now(),
591 
                body: AttestBody::Ref { name: bookmark.clone(), old_state: remote_state, new_state, serial: last_serial.unwrap_or(0) + 1 },
592 
            })?),
593 
            None => None,
594 
        };
595 
        let serial = attestation.as_ref().and_then(|a| match a.attest.body {
596 
            AttestBody::Ref { serial, .. } => Some(serial),
597 
            _ => None,
598 
        });
599 
        let sent_serial = policy_to_send.as_ref().map(|p| p.policy.serial);
600 
        let results = remote.push(bundle, vec![RefUpdate { name: bookmark.clone(), old_state: remote_state, new_state, force, attestation }], policy_to_send)?;
601 
        if let (Some(serial), true) = (sent_serial, results.iter().any(|r| r.ok && r.name == "policy")) {
602 
            self.record_policy_serial(remote_name, serial)?;
603 
        }
604 
        if results.iter().any(|r| r.ok && r.name == bookmark) {
605 
            let mut view = op.view.clone();
606 
            view.remotes.entry(remote_name.to_string()).or_default().insert(bookmark.clone(), new_state);
607 
            self.record_op(&[op_ref], &format!("oxy push {remote_name}"), view)?;
608 
            if let Some(s) = serial {
609 
                self.record_serial(remote_name, &bookmark, s)?;
610 
            }
611 
        }
612 
        Ok(results)
613 
    }
614
615 
    /// Clone a remote into `dest`: same repository ID, `origin` remote,
616 
    /// bookmark set to the remote's, working copy checked out.
617 
    pub fn clone(url: &str, dest: &Path) -> Result<Repo> {
618 
        let options = RemoteOptions {
619 
            token: std::env::var("OXY_TOKEN").ok(),
620 
            ca: std::env::var("OXY_CA").ok().map(PathBuf::from),
621 
        };
622 
        let remote = open_remote(url, &options)?;
623 
        let id = remote.repo_id()?;
624 
        let mut repo = Repo::init_with_id(dest, id)?;
625 
        repo.config.set("remote.origin.url", url)?;
626 
        repo.save_config()?;
627 
        repo.fetch("origin")?;
628 
        let (op_ref, op) = repo.head_op()?;
629 
        let bookmark = repo.config.bookmark.clone();
630 
        if let Some(state) = op.view.remotes.get("origin").and_then(|b| b.get(&bookmark)).copied() {
631 
            let heads = repo.store.get_state(&state)?.heads;
632 
            let mut view = op.view.clone();
633 
            view.bookmarks.insert(bookmark, state);
634 
            repo.record_op(&[op_ref], &format!("oxy clone {url}"), view)?;
635 
            repo.checkout(&heads, false, "oxy clone (checkout)")?;
636 
        }
637 
        Ok(repo)
638 
    }
639 
}