second-brain-sync 0.13.3

Bidirectional sync for second-brain: SSH transport, JSONL change log, conflict resolution
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
use std::collections::BTreeSet;
use std::fmt;

use anyhow::Result;
use second_brain_core::keys::{
    Epoch, EpochCause, IdentityKey, IdentityTag, Revocation, SignedRecord, SignedRevocation,
    newest_epoch, wrap, wrap_for_recovery,
};
use serde::Serialize;

use super::{IdentityMismatch, Keyring};
use crate::crypto::{line_epoch, open_line};
use crate::snapshot::SnapshotKey;

/// A removal the caller asked for that can't be done, as opposed to a store
/// failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RemovalRefused(pub String);

impl fmt::Display for RemovalRefused {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl std::error::Error for RemovalRefused {}

fn refused(message: impl Into<String>) -> anyhow::Error {
    RemovalRefused(message.into()).into()
}

/// What `sb device remove` revokes, or would revoke.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Removal {
    pub target: String,
    /// Every device the revocation newly revokes, the target included.
    pub revoked: Vec<String>,
    /// The epoch minted for the devices that remain; None for a preview.
    pub epoch: Option<Epoch>,
}

impl Keyring<'_> {
    /// What removing `target` would revoke, keeping `keep` and this device.
    pub fn removal_preview(&self, target: &str, keep: &BTreeSet<String>) -> Result<Removal> {
        let revocation = self.revocation_of(target, keep, 0)?;
        Ok(Removal {
            target: target.to_string(),
            revoked: self.newly_reached(&revocation)?,
            epoch: None,
        })
    }

    /// Signs a revocation of `target` and of every device whose first row
    /// it signed, transitively, except `keep` and this device, then mints
    /// the next epoch for the devices that remain. Peers wrap it to each
    /// other in their handshakes, never to a revoked device.
    pub fn remove_device(
        &self,
        target: &str,
        keep: &BTreeSet<String>,
        now_micros: i64,
    ) -> Result<Removal> {
        let revocation = self.revocation_of(target, keep, now_micros)?;
        let tag = IdentityTag::from(revocation.identity_tag.clone());
        let revoked = self.newly_reached(&revocation)?;
        self.vouch_for_kept(&revocation, &revoked)?;
        let signed = revocation.sign(self.device.signing_key());
        self.store
            .put_revocation(&signed, &self.device.verifying_key())?;
        self.store.apply_revocations(&tag)?;
        let epoch = self.rotate_if_needed(now_micros)?;
        Ok(Removal {
            target: target.to_string(),
            revoked,
            epoch,
        })
    }

    fn revocation_of(
        &self,
        target: &str,
        keep: &BTreeSet<String>,
        now_micros: i64,
    ) -> Result<Revocation> {
        let Some(tag) = &self.identity else {
            return Err(refused(
                "this device holds no sync identity, so it has no devices to remove",
            ));
        };
        if target == self.own() {
            return Err(refused(
                "a device can't remove itself; run `sb device remove` on another device",
            ));
        }
        let Some((_, revoked)) = self.member_row(target)? else {
            return Err(refused(format!(
                "no device {target} belongs to this sync identity"
            )));
        };
        if revoked {
            return Err(refused(format!("device {target} was already removed")));
        }
        let mut keep = keep.clone();
        keep.insert(self.own().to_string());
        Ok(Revocation {
            identity_tag: tag.as_str().to_string(),
            revoker: self.own().to_string(),
            target: target.to_string(),
            keep,
            created_at_micros: now_micros,
        })
    }

    /// Countersigns the first row of each kept device whose signer chain
    /// runs through a device this revocation reaches, so peers that never
    /// saw it can still take it from an active signer.
    fn vouch_for_kept(&self, revocation: &Revocation, revoked: &[String]) -> Result<()> {
        let tag = IdentityTag::from(revocation.identity_tag.clone());
        let unkept = Revocation {
            keep: BTreeSet::from([self.own().to_string()]),
            ..revocation.clone()
        };
        let reached_without_keep = self.store.revoked_by_rule(&tag, Some(&unkept))?;
        for id in &revocation.keep {
            if id == self.own() || revoked.contains(id) || !reached_without_keep.contains(id) {
                continue;
            }
            let Some(row) = self.store.device_record(id)? else {
                continue;
            };
            if row.revoked || row.first.signatures.iter().any(|s| s.signer == self.own()) {
                continue;
            }
            let mut first = row.first;
            first.countersign(self.own(), self.device.signing_key());
            self.store.insert_first_device_record(
                &first,
                self.own(),
                &self.device.verifying_key(),
            )?;
        }
        Ok(())
    }

    fn newly_reached(&self, revocation: &Revocation) -> Result<Vec<String>> {
        let tag = IdentityTag::from(revocation.identity_tag.clone());
        let before = self.store.revoked_by_rule(&tag, None)?;
        let after = self.store.revoked_by_rule(&tag, Some(revocation))?;
        Ok(after.difference(&before).cloned().collect())
    }

    /// A device's current row and whether it is revoked, when it belongs to
    /// this identity.
    pub(super) fn member_row(&self, machine_id: &str) -> Result<Option<(SignedRecord, bool)>> {
        let Some(tag) = &self.identity else {
            return Ok(None);
        };
        Ok(self
            .store
            .device_record(machine_id)?
            .filter(|row| row.current.record.identity_tag == tag.as_str())
            .map(|row| (row.current, row.revoked)))
    }

    pub(super) fn is_revoked(&self, machine_id: &str) -> Result<bool> {
        Ok(self
            .member_row(machine_id)?
            .is_some_and(|(_, revoked)| revoked))
    }

    /// Refuses a sync with a revoked peer, and every sync once this device
    /// is revoked itself.
    pub(super) fn refuse_revoked(&self, peer: &str) -> Result<()> {
        if self.is_revoked(self.own())? {
            let own = self.device_name(self.own());
            return Err(IdentityMismatch(format!(
                "{own} was removed from its sync identity by another device, so it cannot sync \
                 under this machine id; join another device's identity with `sb pair <code>` \
                 on {own}, nothing was applied"
            ))
            .into());
        }
        if self.is_revoked(peer)? {
            let peer = self.device_name(peer);
            return Err(IdentityMismatch(format!(
                "{peer} was removed from this sync identity with `sb device remove`, so it \
                 cannot sync under its machine id; join it to another identity with \
                 `sb pair <code>` on {peer}, nothing was applied"
            ))
            .into());
        }
        Ok(())
    }

    /// Takes each revocation signed by a device of this identity, revoked
    /// or not. Revocations apply as a union, so peers end with the same
    /// revoked set whatever order they arrive in. From a peer already
    /// revoked here, only revocations of the devices that revoked it are
    /// taken: that settles a race between a thief and its owner as a union,
    /// which is also all a removed device can still do until its ssh access
    /// is gone. Such a revocation reaches what its target signed, as any
    /// revocation does.
    pub(super) fn accept_revocations(
        &self,
        peer: &str,
        revocations: &[SignedRevocation],
        revoked_peer: bool,
    ) -> Result<()> {
        let Some(tag) = &self.identity else {
            return Ok(());
        };
        let allowed = if revoked_peer {
            Some(self.store.revokers_of(tag, peer)?)
        } else {
            None
        };
        for signed in revocations {
            let revocation = &signed.revocation;
            if revocation.identity_tag != tag.as_str() {
                continue;
            }
            if allowed
                .as_ref()
                .is_some_and(|revokers| !revokers.contains(&revocation.target))
            {
                continue;
            }
            let Some((revoker, _)) = self.member_row(&revocation.revoker)? else {
                tracing::debug!(
                    "holding back the revocation of {} from {peer}: its revoker {} is unknown here",
                    revocation.target,
                    revocation.revoker
                );
                continue;
            };
            if let Err(e) = self
                .store
                .put_revocation(signed, &revoker.record.signing_public_key()?)
            {
                tracing::warn!("{peer} sent a revocation this device refuses: {e:#}");
            }
        }
        self.store.apply_revocations(tag)?;
        Ok(())
    }

    pub(super) fn causes(&self) -> Result<Vec<(Epoch, EpochCause)>> {
        let Some(tag) = &self.identity else {
            return Ok(Vec::new());
        };
        let held = self.held_epochs();
        let mut causes = Vec::new();
        for stored in self.store.key_epochs(tag)? {
            if !held.contains(&stored.epoch) {
                continue;
            }
            let cause = EpochCause::from_stored(stored.cause.as_deref())?;
            if !cause.is_empty() {
                causes.push((stored.epoch, cause));
            }
        }
        Ok(causes)
    }

    fn revocation_ids(&self, tag: &IdentityTag) -> Result<BTreeSet<String>> {
        Ok(self
            .store
            .revocations(tag)?
            .iter()
            .map(SignedRevocation::id)
            .collect())
    }

    /// The cause a peer gave for `epoch`, when every revocation in it is
    /// held here; None while one is missing, so the epoch waits. Its
    /// retirements never hold it back, since storing the cause retires them.
    pub(super) fn applicable_cause(
        &self,
        epoch: &Epoch,
        causes: &[(Epoch, EpochCause)],
    ) -> Result<Option<EpochCause>> {
        let Some(tag) = &self.identity else {
            return Ok(None);
        };
        let cause = causes
            .iter()
            .find(|(e, _)| e == epoch)
            .map(|(_, cause)| cause.clone())
            .unwrap_or_default();
        let held = self.revocation_ids(tag)?;
        Ok(cause.revocations.is_subset(&held).then_some(cause))
    }

    pub(super) fn fill_causes(
        &self,
        causes: &[(Epoch, EpochCause)],
        now_micros: i64,
    ) -> Result<()> {
        let Some(tag) = &self.identity else {
            return Ok(());
        };
        for (epoch, _) in causes {
            if self.key(epoch).is_none() {
                continue;
            }
            if let Some(cause) = self.applicable_cause(epoch, causes)? {
                self.store
                    .put_key_epoch(tag, epoch, Some(&cause.to_json()?), now_micros)?;
            }
        }
        Ok(())
    }

    /// Mints the next epoch when this device holds a revocation, or a
    /// retirement that calls for rotation, that its newest epoch's cause
    /// lacks, or when that epoch is wrapped to a retired phrase here: after
    /// a removal, when a concurrent rotation with another set wins, or when
    /// a revoked device or retired phrase may hold the newest epoch. Two
    /// devices minting at once mint equal sets, which settle by key id
    /// without another round.
    pub(super) fn rotate_if_needed(&self, now_micros: i64) -> Result<Option<Epoch>> {
        let Some(tag) = &self.identity else {
            return Ok(None);
        };
        let held_revocations = self.revocation_ids(tag)?;
        let rotating = self.store.rotating_retirements(tag)?;
        if (held_revocations.is_empty() && rotating.is_empty()) || self.is_revoked(self.own())? {
            return Ok(None);
        }
        let reloaded = Keyring::load(self.store, self.data_dir)?;
        let held = reloaded.held_epochs();
        let Some(current) = newest_epoch(&held) else {
            return Ok(None);
        };
        let covered = reloaded
            .causes()?
            .into_iter()
            .find(|(epoch, _)| *epoch == current)
            .is_some_and(|(_, cause)| {
                held_revocations.is_subset(&cause.revocations)
                    && rotating.is_subset(&cause.retirements)
            });
        if covered
            && !self
                .store
                .epochs_wrapped_to_retired(tag)?
                .contains(&current)
        {
            return Ok(None);
        }
        let number = held.iter().map(|e| e.number).max().unwrap_or(0) + 1;
        let key = IdentityKey::generate()?;
        let epoch = Epoch {
            number,
            key_id: key.key_id(),
        };
        let cause = EpochCause {
            revocations: held_revocations,
            retirements: self.store.retired_fingerprints()?,
        };
        self.store
            .put_key_epoch(tag, &epoch, Some(&cause.to_json()?), now_micros)?;
        self.store.put_envelope(&wrap(
            &key,
            number,
            tag,
            &self.device.age_recipient(),
            Some(self.own().to_string()),
        )?)?;
        let recovery = self.store.recovery_recipients(tag)?;
        wrap_for_recovery(self.store, tag, &[(epoch, &key)], &recovery)?;
        tracing::info!(
            "minted sync identity epoch {number} after a device removal or a recovery phrase \
             retirement"
        );
        Ok(Some(epoch))
    }

    /// Opens wire lines from `peer`, refusing any under an epoch numbered
    /// below its floor. Once `peer` seals under an epoch a revocation
    /// caused, that epoch's number becomes its floor, so a holder of an
    /// older epoch can't pose as it. Without a peer the floor is the newest
    /// epoch a revocation caused here.
    pub fn open_lines(&self, peer: Option<&str>, lines: &[String]) -> Result<Vec<Vec<u8>>> {
        let opener = self.opener()?;
        let epochs: Vec<Epoch> = lines.iter().filter_map(|line| line_epoch(line)).collect();
        self.refuse_stale_epochs(peer, &epochs, "records")?;
        let opened = lines
            .iter()
            .map(|line| open_line(&opener, line))
            .collect::<Result<Vec<_>>>()?;
        self.raise_frame_floor_from(peer, &epochs)?;
        Ok(opened)
    }

    /// The key to open a snapshot `exporter` sealed under `epoch`, refused
    /// under the floor and revocations `open_lines` applies to its frames.
    pub fn snapshot_opening_key(&self, exporter: &str, epoch: &Epoch) -> Result<SnapshotKey> {
        self.refuse_stale_epochs(Some(exporter), std::slice::from_ref(epoch), "a snapshot")?;
        self.snapshot_key(epoch)
    }

    /// Raises `exporter`'s floor from a snapshot whose frames all opened,
    /// as `open_lines` does from frames.
    pub fn opened_snapshot(&self, exporter: &str, epoch: &Epoch) -> Result<()> {
        self.raise_frame_floor_from(Some(exporter), std::slice::from_ref(epoch))
    }

    fn refuse_stale_epochs(&self, peer: Option<&str>, epochs: &[Epoch], what: &str) -> Result<()> {
        let floor = match (peer, &self.identity) {
            (Some(peer), Some(tag)) => {
                self.refuse_revoked(peer)?;
                self.store.frame_floor(tag, peer)?
            }
            _ => newest_epoch(self.causes()?.iter().map(|(epoch, _)| epoch)).map(|e| e.number),
        };
        let floor = floor.unwrap_or(0);
        if let Some(stale) = epochs.iter().find(|epoch| epoch.number < floor) {
            return Err(IdentityMismatch(format!(
                "{} sealed {what} under key epoch {}, older than epoch {floor} it already used \
                 after a device was removed; whoever sent them holds only a key from before the \
                 removal, nothing was applied",
                peer.unwrap_or("the sender"),
                stale.number
            ))
            .into());
        }
        Ok(())
    }

    fn raise_frame_floor_from(&self, peer: Option<&str>, epochs: &[Epoch]) -> Result<()> {
        if let (Some(peer), Some(tag)) = (peer, &self.identity) {
            let caused: Vec<Epoch> = self.causes()?.into_iter().map(|(e, _)| e).collect();
            let used = epochs
                .iter()
                .filter(|epoch| caused.contains(epoch))
                .map(|epoch| epoch.number)
                .max();
            if let Some(number) = used {
                self.store.raise_frame_floor(tag, peer, number)?;
            }
        }
        Ok(())
    }
}