Skip to main content

second_brain_sync/
crypto.rs

1use std::fs;
2use std::io::Write;
3use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
4use std::path::{Path, PathBuf};
5
6use anyhow::{Context, Result, anyhow, bail, ensure};
7use base64::Engine;
8use base64::engine::general_purpose::STANDARD as B64;
9use chacha20poly1305::aead::{Aead, KeyInit, OsRng, Payload};
10use chacha20poly1305::{XChaCha20Poly1305, XNonce};
11use rand_core::RngCore;
12use second_brain_core::keys::{Epoch, IdentityKey, KeyGuard, KeyId, Subkey, derive_subkey};
13
14const KEY_LEN: usize = 32;
15const NONCE_LEN: usize = 24;
16
17const MAGIC_PLAINTEXT: u8 = 0x00;
18const MAGIC_XCHACHA: u8 = 0x01;
19const MAGIC_EPOCH: u8 = 0x02;
20const EPOCH_PREFIX_LEN: usize = 1 + 4 + 8;
21
22pub trait SyncEncryptor: Send + Sync {
23    fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>>;
24    fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>>;
25}
26
27pub struct PassthroughEncryptor;
28
29impl SyncEncryptor for PassthroughEncryptor {
30    fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
31        Ok(plaintext.to_vec())
32    }
33
34    fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>> {
35        Ok(ciphertext.to_vec())
36    }
37}
38
39pub struct XChaChaEncryptor {
40    key: [u8; KEY_LEN],
41}
42
43impl XChaChaEncryptor {
44    pub fn new(key: [u8; KEY_LEN]) -> Self {
45        Self { key }
46    }
47
48    pub fn key_base64(&self) -> String {
49        B64.encode(self.key)
50    }
51
52    fn cipher(&self) -> XChaCha20Poly1305 {
53        XChaCha20Poly1305::new((&self.key).into())
54    }
55}
56
57impl SyncEncryptor for XChaChaEncryptor {
58    fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
59        let mut nonce_bytes = [0u8; NONCE_LEN];
60        OsRng.fill_bytes(&mut nonce_bytes);
61        let nonce = XNonce::from_slice(&nonce_bytes);
62
63        let ct = self
64            .cipher()
65            .encrypt(nonce, plaintext)
66            .map_err(|e| anyhow!("xchacha20poly1305 encrypt failed: {e}"))?;
67
68        let mut framed = Vec::with_capacity(1 + NONCE_LEN + ct.len());
69        framed.push(MAGIC_XCHACHA);
70        framed.extend_from_slice(&nonce_bytes);
71        framed.extend_from_slice(&ct);
72        Ok(framed)
73    }
74
75    fn decrypt(&self, framed: &[u8]) -> Result<Vec<u8>> {
76        match framed.first() {
77            None => bail!("empty sync payload"),
78            Some(&MAGIC_PLAINTEXT) => bail!("refusing an unencrypted sync payload"),
79            Some(&MAGIC_XCHACHA) => {
80                if framed.len() < 1 + NONCE_LEN {
81                    bail!("encrypted payload too short to contain a nonce");
82                }
83                let nonce = XNonce::from_slice(&framed[1..1 + NONCE_LEN]);
84                let ct = &framed[1 + NONCE_LEN..];
85                self.cipher().decrypt(nonce, ct).map_err(|e| {
86                    anyhow!("xchacha20poly1305 decrypt failed (bad key or tampered payload): {e}")
87                })
88            }
89            Some(other) => bail!("unknown sync payload magic byte: {other:#x}"),
90        }
91    }
92}
93
94/// The wire subkey of one identity key epoch.
95pub struct WireKey {
96    epoch: Epoch,
97    key: KeyGuard<[u8; KEY_LEN]>,
98}
99
100impl WireKey {
101    pub fn derive(identity: &IdentityKey, epoch: &Epoch) -> Result<Self> {
102        Ok(Self {
103            epoch: *epoch,
104            key: derive_subkey(identity, epoch, Subkey::Wire)?,
105        })
106    }
107
108    pub fn epoch(&self) -> &Epoch {
109        &self.epoch
110    }
111
112    fn cipher(&self) -> XChaCha20Poly1305 {
113        XChaCha20Poly1305::new(self.key.expose().into())
114    }
115}
116
117/// Seals under one epoch and opens frames of any epoch it holds. Each frame
118/// names its epoch and key id, which the AEAD binds as associated data.
119pub struct EpochSealer {
120    keys: Vec<WireKey>,
121    seal_with: Option<Epoch>,
122}
123
124impl EpochSealer {
125    /// `seal_with` must be one of `keys`' epochs; None makes an opener only.
126    pub fn new(keys: Vec<WireKey>, seal_with: Option<Epoch>) -> Result<Self> {
127        if let Some(epoch) = &seal_with {
128            ensure!(
129                keys.iter().any(|k| k.epoch == *epoch),
130                "no wire key held for epoch {} (key id {})",
131                epoch.number,
132                epoch.key_id
133            );
134        }
135        Ok(Self { keys, seal_with })
136    }
137
138    pub fn sealing_epoch(&self) -> Option<&Epoch> {
139        self.seal_with.as_ref()
140    }
141
142    fn key(&self, epoch: &Epoch) -> Option<&WireKey> {
143        self.keys.iter().find(|k| k.epoch == *epoch)
144    }
145}
146
147/// The epoch an epoch-sealed frame names, None for any other frame.
148pub fn frame_epoch(framed: &[u8]) -> Option<Epoch> {
149    let prefix = framed.get(..EPOCH_PREFIX_LEN)?;
150    if prefix[0] != MAGIC_EPOCH {
151        return None;
152    }
153    let mut number = [0u8; 4];
154    number.copy_from_slice(&prefix[1..5]);
155    let mut key_id = [0u8; 8];
156    key_id.copy_from_slice(&prefix[5..]);
157    Some(Epoch {
158        number: u32::from_be_bytes(number),
159        key_id: KeyId(key_id),
160    })
161}
162
163/// The epoch a sealed wire line names, None when it names none.
164pub fn line_epoch(line: &str) -> Option<Epoch> {
165    frame_epoch(&B64.decode(line.trim()).ok()?)
166}
167
168fn epoch_prefix(epoch: &Epoch) -> [u8; EPOCH_PREFIX_LEN] {
169    let mut prefix = [0u8; EPOCH_PREFIX_LEN];
170    prefix[0] = MAGIC_EPOCH;
171    prefix[1..5].copy_from_slice(&epoch.number.to_be_bytes());
172    prefix[5..].copy_from_slice(&epoch.key_id.0);
173    prefix
174}
175
176impl SyncEncryptor for EpochSealer {
177    fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
178        let epoch = self
179            .seal_with
180            .as_ref()
181            .context("this sync key set only opens frames; it has no epoch to seal under")?;
182        let key = self
183            .key(epoch)
184            .context("the sealing epoch's key vanished")?;
185        let prefix = epoch_prefix(epoch);
186        let mut nonce_bytes = [0u8; NONCE_LEN];
187        OsRng.fill_bytes(&mut nonce_bytes);
188        let ct = key
189            .cipher()
190            .encrypt(
191                XNonce::from_slice(&nonce_bytes),
192                Payload {
193                    msg: plaintext,
194                    aad: &prefix,
195                },
196            )
197            .map_err(|e| anyhow!("xchacha20poly1305 encrypt failed: {e}"))?;
198        let mut framed = Vec::with_capacity(EPOCH_PREFIX_LEN + NONCE_LEN + ct.len());
199        framed.extend_from_slice(&prefix);
200        framed.extend_from_slice(&nonce_bytes);
201        framed.extend_from_slice(&ct);
202        Ok(framed)
203    }
204
205    fn decrypt(&self, framed: &[u8]) -> Result<Vec<u8>> {
206        match framed.first() {
207            None => bail!("empty sync payload"),
208            Some(&MAGIC_PLAINTEXT) => bail!("refusing an unencrypted sync payload"),
209            Some(&MAGIC_XCHACHA) => {
210                bail!("refusing a payload sealed with a sync.key by sync protocol 3 or older")
211            }
212            Some(&MAGIC_EPOCH) => {
213                if framed.len() < EPOCH_PREFIX_LEN + NONCE_LEN {
214                    bail!("encrypted payload too short to contain its epoch and nonce");
215                }
216                let epoch = frame_epoch(framed).context("frame has no epoch prefix")?;
217                let (prefix, rest) = framed.split_at(EPOCH_PREFIX_LEN);
218                let key = self.key(&epoch).with_context(|| {
219                    format!(
220                        "the payload is sealed under identity key epoch {} (key id {}), which this \
221                         device does not hold; if the sender belongs to another identity, pair it \
222                         with `sb pair`",
223                        epoch.number, epoch.key_id
224                    )
225                })?;
226                let (nonce, ct) = rest.split_at(NONCE_LEN);
227                key.cipher()
228                    .decrypt(
229                        XNonce::from_slice(nonce),
230                        Payload {
231                            msg: ct,
232                            aad: prefix,
233                        },
234                    )
235                    .map_err(|e| {
236                        anyhow!(
237                            "xchacha20poly1305 decrypt failed under epoch {} (tampered payload): {e}",
238                            epoch.number
239                        )
240                    })
241            }
242            Some(other) => bail!("unknown sync payload magic byte: {other:#x}"),
243        }
244    }
245}
246
247/// Seal one plaintext JSONL record into a single base64 line safe for the
248/// line-oriented SSH transport. base64 is required because the AEAD frame is
249/// binary and the wire is newline-delimited text.
250pub fn seal_line(enc: &dyn SyncEncryptor, plaintext: &[u8]) -> Result<String> {
251    let framed = enc.encrypt(plaintext)?;
252    Ok(B64.encode(framed))
253}
254
255/// Open one wire line back into the plaintext JSONL record.
256pub fn open_line(enc: &dyn SyncEncryptor, line: &str) -> Result<Vec<u8>> {
257    let framed = B64
258        .decode(line.trim())
259        .context("not an encrypted sync line (plaintext lines are refused)")?;
260    enc.decrypt(&framed)
261}
262
263#[cfg(test)]
264pub(crate) fn frame_format() -> String {
265    format!(
266        "base64({MAGIC_EPOCH:#04x} | epoch u32 be | key id[8] | nonce[{NONCE_LEN}] | \
267         xchacha20poly1305 ciphertext, aad = first {EPOCH_PREFIX_LEN} bytes)"
268    )
269}
270
271pub fn default_key_path() -> Result<PathBuf> {
272    let home = dirs::home_dir().context("cannot determine home directory")?;
273    Ok(home.join(".second-brain").join("sync.key"))
274}
275
276/// Load the 32-byte sync key from `path`, generating and persisting a fresh one
277/// if absent. The file is written 0600 because the key grants full read of every
278/// synced memory (safety: file perms must be 0600).
279pub fn load_or_create_key(path: &Path) -> Result<[u8; KEY_LEN]> {
280    if let Some(key) = read_key(path)? {
281        return Ok(key);
282    }
283    let mut key = [0u8; KEY_LEN];
284    OsRng.fill_bytes(&mut key);
285    if create_key(path, &key)? {
286        return Ok(key);
287    }
288    read_key(path)?.with_context(|| {
289        format!(
290            "{} exists but reads as missing; is it a dangling symlink?",
291            path.display()
292        )
293    })
294}
295
296/// Reads a `sync.key` written by sync protocol 3 or older without ever
297/// creating one.
298pub fn read_key_file(path: &Path) -> Result<Option<[u8; KEY_LEN]>> {
299    read_key(path)
300}
301
302fn read_key(path: &Path) -> Result<Option<[u8; KEY_LEN]>> {
303    let contents = match fs::read_to_string(path) {
304        Ok(contents) => contents,
305        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
306        Err(e) => return Err(e).context("reading sync key"),
307    };
308    let raw = B64
309        .decode(contents.trim())
310        .context("decoding base64 sync key")?;
311    let key: [u8; KEY_LEN] = raw
312        .as_slice()
313        .try_into()
314        .map_err(|_| anyhow!("sync key must decode to {KEY_LEN} bytes, got {}", raw.len()))?;
315    // correct an over-permissive key file left by an earlier write or manual copy.
316    fs::set_permissions(path, fs::Permissions::from_mode(0o600))
317        .context("tightening sync key permissions to 0600")?;
318    Ok(Some(key))
319}
320
321/// False when another caller created the key first. The key is staged under a
322/// name unique to this call and hard-linked into place, so a concurrent reader
323/// never sees a partial key and exactly one creator wins.
324fn create_key(path: &Path, key: &[u8; KEY_LEN]) -> Result<bool> {
325    if let Some(parent) = path.parent()
326        && !parent.as_os_str().is_empty()
327    {
328        fs::create_dir_all(parent).context("creating sync key parent dir")?;
329    }
330    let mut staged = path.as_os_str().to_owned();
331    staged.push(format!(".{:016x}.tmp", OsRng.next_u64()));
332    let staged = PathBuf::from(staged);
333    let mut file = fs::OpenOptions::new()
334        .write(true)
335        .create_new(true)
336        .mode(0o600)
337        .open(&staged)
338        .context("staging the sync key")?;
339    let written = file
340        .write_all(format!("{}\n", B64.encode(key)).as_bytes())
341        .and_then(|()| file.sync_all());
342    drop(file);
343    if let Err(e) = written {
344        let left = match fs::remove_file(&staged) {
345            Ok(()) => String::new(),
346            Err(cleanup) => format!("; {} was left behind: {cleanup}", staged.display()),
347        };
348        return Err(e).context(format!("writing sync key{left}"));
349    }
350    let linked = fs::hard_link(&staged, path);
351    if let Err(e) = fs::remove_file(&staged) {
352        tracing::warn!("could not remove {}: {e}", staged.display());
353    }
354    match linked {
355        Ok(()) => Ok(true),
356        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(false),
357        Err(e) => Err(e).context("linking the sync key into place"),
358    }
359}
360
361#[cfg(test)]
362mod tests {
363    use super::*;
364
365    fn test_key(seed: u8) -> [u8; KEY_LEN] {
366        [seed; KEY_LEN]
367    }
368
369    #[test]
370    fn round_trip_returns_plaintext() {
371        let enc = XChaChaEncryptor::new(test_key(7));
372        let plaintext = b"sensitive memory line as jsonl";
373        let ct = enc.encrypt(plaintext).unwrap();
374        assert_ne!(
375            ct.as_slice(),
376            plaintext,
377            "ciphertext must differ from plaintext"
378        );
379        let pt = enc.decrypt(&ct).unwrap();
380        assert_eq!(pt, plaintext);
381    }
382
383    #[test]
384    fn nonce_is_random_per_message() {
385        let enc = XChaChaEncryptor::new(test_key(3));
386        let a = enc.encrypt(b"same input").unwrap();
387        let b = enc.encrypt(b"same input").unwrap();
388        assert_ne!(a, b, "fresh random nonce must yield distinct ciphertext");
389    }
390
391    #[test]
392    fn decrypt_with_wrong_key_fails() {
393        let enc = XChaChaEncryptor::new(test_key(1));
394        let other = XChaChaEncryptor::new(test_key(2));
395        let ct = enc.encrypt(b"secret").unwrap();
396        assert!(
397            other.decrypt(&ct).is_err(),
398            "AEAD must reject a payload sealed under a different key"
399        );
400    }
401
402    #[test]
403    fn flipped_ciphertext_byte_fails() {
404        let enc = XChaChaEncryptor::new(test_key(9));
405        let mut ct = enc.encrypt(b"tamper me").unwrap();
406        let last = ct.len() - 1;
407        ct[last] ^= 0x01;
408        assert!(
409            enc.decrypt(&ct).is_err(),
410            "Poly1305 tag must reject a single flipped byte"
411        );
412    }
413
414    #[test]
415    fn legacy_plaintext_frame_is_rejected() {
416        let enc = XChaChaEncryptor::new(test_key(5));
417        let mut legacy = vec![MAGIC_PLAINTEXT];
418        legacy.extend_from_slice(b"{\"local_seq\":1}");
419        assert!(enc.decrypt(&legacy).is_err());
420    }
421
422    #[test]
423    fn empty_frame_is_rejected() {
424        let enc = XChaChaEncryptor::new(test_key(5));
425        assert!(enc.decrypt(&[]).is_err());
426    }
427
428    #[test]
429    fn seal_open_line_round_trips() {
430        let enc = XChaChaEncryptor::new(test_key(4));
431        let record = b"{\"local_seq\":42,\"op\":\"Create\"}";
432        let line = seal_line(&enc, record).unwrap();
433        assert!(!line.contains('\n'), "wire line must be single-line");
434        let out = open_line(&enc, &line).unwrap();
435        assert_eq!(out, record);
436    }
437
438    #[test]
439    fn open_line_rejects_legacy_jsonl() {
440        let enc = XChaChaEncryptor::new(test_key(4));
441        let legacy = "{\"local_seq\":1,\"op\":\"Create\"}";
442        let err = open_line(&enc, legacy).unwrap_err();
443        assert!(
444            err.to_string().contains("not an encrypted sync line"),
445            "unexpected error: {err:#}"
446        );
447    }
448
449    #[test]
450    fn open_line_rejects_base64_of_a_plaintext_frame() {
451        let enc = XChaChaEncryptor::new(test_key(4));
452        let mut legacy = vec![MAGIC_PLAINTEXT];
453        legacy.extend_from_slice(b"{\"local_seq\":1}");
454        assert!(open_line(&enc, &B64.encode(legacy)).is_err());
455    }
456
457    #[test]
458    fn load_or_create_key_creates_0600_and_is_idempotent() {
459        let dir = tempfile::tempdir().unwrap();
460        let path = dir.path().join("nested").join("sync.key");
461        let first = load_or_create_key(&path).unwrap();
462
463        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
464        assert_eq!(mode, 0o600, "key file must be 0600");
465
466        let second = load_or_create_key(&path).unwrap();
467        assert_eq!(
468            first, second,
469            "second load must return the same persisted key"
470        );
471    }
472
473    #[test]
474    fn a_dangling_key_symlink_is_an_error_naming_the_path() {
475        let dir = tempfile::tempdir().unwrap();
476        let path = dir.path().join("sync.key");
477        std::os::unix::fs::symlink(dir.path().join("gone"), &path).unwrap();
478        let error = load_or_create_key(&path).unwrap_err();
479        assert!(format!("{error:#}").contains("sync.key"), "{error:#}");
480    }
481
482    #[test]
483    fn callers_creating_the_key_at_once_all_get_the_one_on_disk() {
484        for _ in 0..50 {
485            let dir = tempfile::tempdir().unwrap();
486            let path = dir.path().join("sync.key");
487            let start = std::sync::Arc::new(std::sync::Barrier::new(16));
488            let keys: Vec<[u8; KEY_LEN]> = (0..16)
489                .map(|_| {
490                    let path = path.clone();
491                    let start = start.clone();
492                    std::thread::spawn(move || {
493                        start.wait();
494                        load_or_create_key(&path).unwrap()
495                    })
496                })
497                .collect::<Vec<_>>()
498                .into_iter()
499                .map(|handle| handle.join().unwrap())
500                .collect();
501            let on_disk = load_or_create_key(&path).unwrap();
502            assert!(keys.iter().all(|key| *key == on_disk));
503            assert_eq!(fs::read_dir(dir.path()).unwrap().count(), 1);
504        }
505    }
506
507    fn identity(seed: u8) -> IdentityKey {
508        IdentityKey::from_bytes(KeyGuard::new([seed; KEY_LEN]))
509    }
510
511    fn wire(seed: u8, number: u32) -> WireKey {
512        let key = identity(seed);
513        let epoch = Epoch {
514            number,
515            key_id: key.key_id(),
516        };
517        WireKey::derive(&key, &epoch).unwrap()
518    }
519
520    #[test]
521    fn an_epoch_frame_opens_with_any_holder_of_its_epoch() {
522        let one = wire(1, 1);
523        let epoch = *one.epoch();
524        let sealer = EpochSealer::new(vec![wire(0, 0), one], Some(epoch)).unwrap();
525        let opener = EpochSealer::new(vec![wire(1, 1), wire(0, 0)], None).unwrap();
526        let line = seal_line(&sealer, b"record").unwrap();
527        assert_eq!(open_line(&opener, &line).unwrap(), b"record");
528        let framed = B64.decode(&line).unwrap();
529        assert_eq!(framed[0], MAGIC_EPOCH);
530        assert_eq!(&framed[1..5], &1u32.to_be_bytes());
531        assert_eq!(&framed[5..13], &epoch.key_id.0);
532    }
533
534    #[test]
535    fn a_frame_under_an_epoch_not_held_names_the_epoch_and_pairing() {
536        let sealer = EpochSealer::new(vec![wire(1, 0)], Some(*wire(1, 0).epoch())).unwrap();
537        let opener = EpochSealer::new(vec![wire(2, 0)], None).unwrap();
538        let line = seal_line(&sealer, b"record").unwrap();
539        let err = format!("{:#}", open_line(&opener, &line).unwrap_err());
540        assert!(err.contains("epoch 0"), "{err}");
541        assert!(err.contains("sb pair"), "{err}");
542        assert!(!err.contains("decrypt failed"), "{err}");
543    }
544
545    #[test]
546    fn a_relabelled_epoch_header_fails_authentication() {
547        let a = wire(1, 1);
548        let mut relabelled = wire(1, 1);
549        relabelled.epoch.number = 2;
550        let a_epoch = *a.epoch();
551        let sealer = EpochSealer::new(vec![a], Some(a_epoch)).unwrap();
552        let mut framed = sealer.encrypt(b"record").unwrap();
553        framed[1..5].copy_from_slice(&2u32.to_be_bytes());
554        let opener = EpochSealer::new(vec![relabelled], None).unwrap();
555        let err = format!("{:#}", opener.decrypt(&framed).unwrap_err());
556        assert!(err.contains("tampered"), "{err}");
557    }
558
559    #[test]
560    fn an_opener_only_set_refuses_to_seal_and_a_sync_key_frame_is_refused() {
561        let opener = EpochSealer::new(vec![wire(1, 0)], None).unwrap();
562        assert!(opener.encrypt(b"x").is_err());
563        let legacy = XChaChaEncryptor::new(test_key(1)).encrypt(b"x").unwrap();
564        let err = format!("{:#}", opener.decrypt(&legacy).unwrap_err());
565        assert!(err.contains("protocol 3 or older"), "{err}");
566        assert!(EpochSealer::new(vec![wire(1, 0)], Some(*wire(2, 0).epoch())).is_err());
567    }
568}