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};
5use std::sync::atomic::{AtomicBool, Ordering};
6
7use anyhow::{Context, Result, anyhow, bail};
8use base64::Engine;
9use base64::engine::general_purpose::STANDARD as B64;
10use chacha20poly1305::aead::{Aead, KeyInit, OsRng};
11use chacha20poly1305::{XChaCha20Poly1305, XNonce};
12use rand_core::RngCore;
13
14const KEY_LEN: usize = 32;
15const NONCE_LEN: usize = 24;
16
17const MAGIC_PLAINTEXT: u8 = 0x00;
18const MAGIC_XCHACHA: u8 = 0x01;
19
20static LEGACY_WARNED: AtomicBool = AtomicBool::new(false);
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            // legacy payloads written before encryption was added carry no AEAD
78            // frame, so pass them through and warn once that re-sync will encrypt.
79            Some(&MAGIC_PLAINTEXT) | None => {
80                warn_legacy_once();
81                Ok(framed.get(1..).unwrap_or(&[]).to_vec())
82            }
83            Some(&MAGIC_XCHACHA) => {
84                if framed.len() < 1 + NONCE_LEN {
85                    bail!("encrypted payload too short to contain a nonce");
86                }
87                let nonce = XNonce::from_slice(&framed[1..1 + NONCE_LEN]);
88                let ct = &framed[1 + NONCE_LEN..];
89                self.cipher().decrypt(nonce, ct).map_err(|e| {
90                    anyhow!("xchacha20poly1305 decrypt failed (bad key or tampered payload): {e}")
91                })
92            }
93            Some(other) => bail!("unknown sync payload magic byte: {other:#x}"),
94        }
95    }
96}
97
98/// Seal one plaintext JSONL record into a single base64 line safe for the
99/// line-oriented SSH transport. base64 is required because the AEAD frame is
100/// binary and the wire is newline-delimited text.
101pub fn seal_line(enc: &dyn SyncEncryptor, plaintext: &[u8]) -> Result<String> {
102    let framed = enc.encrypt(plaintext)?;
103    Ok(B64.encode(framed))
104}
105
106/// Open one wire line back into the plaintext JSONL record. A line that is not
107/// valid base64 is treated as a legacy plaintext JSONL record and returned as-is
108/// (with a one-time warning), so logs written before encryption still import.
109pub fn open_line(enc: &dyn SyncEncryptor, line: &str) -> Result<Vec<u8>> {
110    match B64.decode(line.trim()) {
111        Ok(framed) => enc.decrypt(&framed),
112        Err(_) => {
113            warn_legacy_once();
114            Ok(line.as_bytes().to_vec())
115        }
116    }
117}
118
119fn warn_legacy_once() {
120    if !LEGACY_WARNED.swap(true, Ordering::Relaxed) {
121        tracing::warn!(
122            "importing legacy plaintext sync payload; re-running sync will encrypt it going forward"
123        );
124    }
125}
126
127pub fn default_key_path() -> Result<PathBuf> {
128    let home = dirs::home_dir().context("cannot determine home directory")?;
129    Ok(home.join(".second-brain").join("sync.key"))
130}
131
132/// Load the 32-byte sync key from `path`, generating and persisting a fresh one
133/// if absent. The file is written 0600 because the key grants full read of every
134/// synced memory (safety: file perms must be 0600).
135pub fn load_or_create_key(path: &Path) -> Result<[u8; KEY_LEN]> {
136    match fs::read_to_string(path) {
137        Ok(contents) => {
138            let trimmed = contents.trim();
139            let raw = B64.decode(trimmed).context("decoding base64 sync key")?;
140            let key: [u8; KEY_LEN] = raw.as_slice().try_into().map_err(|_| {
141                anyhow!("sync key must decode to {KEY_LEN} bytes, got {}", raw.len())
142            })?;
143            // correct an over-permissive key file left by an earlier write or manual copy.
144            fs::set_permissions(path, fs::Permissions::from_mode(0o600))
145                .context("tightening sync key permissions to 0600")?;
146            Ok(key)
147        }
148        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
149            let mut key = [0u8; KEY_LEN];
150            OsRng.fill_bytes(&mut key);
151            write_key(path, &key)?;
152            Ok(key)
153        }
154        Err(e) => Err(e).context("reading sync key"),
155    }
156}
157
158fn write_key(path: &Path, key: &[u8; KEY_LEN]) -> Result<()> {
159    if let Some(parent) = path.parent()
160        && !parent.as_os_str().is_empty()
161    {
162        fs::create_dir_all(parent).context("creating sync key parent dir")?;
163    }
164    let mut file = fs::OpenOptions::new()
165        .create(true)
166        .write(true)
167        .truncate(true)
168        .mode(0o600)
169        .open(path)
170        .context("opening sync key for write")?;
171    file.write_all(B64.encode(key).as_bytes())
172        .context("writing sync key")?;
173    file.write_all(b"\n").context("writing sync key newline")?;
174    // because OpenOptions::mode only applies on creation, enforce 0600 even when
175    // truncating an existing file (safety: file perms must be 0600).
176    fs::set_permissions(path, fs::Permissions::from_mode(0o600))
177        .context("setting sync key mode 0600")?;
178    Ok(())
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    fn test_key(seed: u8) -> [u8; KEY_LEN] {
186        [seed; KEY_LEN]
187    }
188
189    #[test]
190    fn round_trip_returns_plaintext() {
191        let enc = XChaChaEncryptor::new(test_key(7));
192        let plaintext = b"sensitive memory line as jsonl";
193        let ct = enc.encrypt(plaintext).unwrap();
194        assert_ne!(
195            ct.as_slice(),
196            plaintext,
197            "ciphertext must differ from plaintext"
198        );
199        let pt = enc.decrypt(&ct).unwrap();
200        assert_eq!(pt, plaintext);
201    }
202
203    #[test]
204    fn nonce_is_random_per_message() {
205        let enc = XChaChaEncryptor::new(test_key(3));
206        let a = enc.encrypt(b"same input").unwrap();
207        let b = enc.encrypt(b"same input").unwrap();
208        assert_ne!(a, b, "fresh random nonce must yield distinct ciphertext");
209    }
210
211    #[test]
212    fn decrypt_with_wrong_key_fails() {
213        let enc = XChaChaEncryptor::new(test_key(1));
214        let other = XChaChaEncryptor::new(test_key(2));
215        let ct = enc.encrypt(b"secret").unwrap();
216        assert!(
217            other.decrypt(&ct).is_err(),
218            "AEAD must reject a payload sealed under a different key"
219        );
220    }
221
222    #[test]
223    fn flipped_ciphertext_byte_fails() {
224        let enc = XChaChaEncryptor::new(test_key(9));
225        let mut ct = enc.encrypt(b"tamper me").unwrap();
226        let last = ct.len() - 1;
227        ct[last] ^= 0x01;
228        assert!(
229            enc.decrypt(&ct).is_err(),
230            "Poly1305 tag must reject a single flipped byte"
231        );
232    }
233
234    #[test]
235    fn legacy_plaintext_passes_through() {
236        let enc = XChaChaEncryptor::new(test_key(5));
237        let mut legacy = vec![MAGIC_PLAINTEXT];
238        legacy.extend_from_slice(b"{\"local_seq\":1}");
239        let out = enc.decrypt(&legacy).unwrap();
240        assert_eq!(out, b"{\"local_seq\":1}");
241    }
242
243    #[test]
244    fn empty_frame_decodes_as_empty_plaintext() {
245        let enc = XChaChaEncryptor::new(test_key(5));
246        let out = enc.decrypt(&[]).unwrap();
247        assert!(out.is_empty());
248    }
249
250    #[test]
251    fn seal_open_line_round_trips() {
252        let enc = XChaChaEncryptor::new(test_key(4));
253        let record = b"{\"local_seq\":42,\"op\":\"Create\"}";
254        let line = seal_line(&enc, record).unwrap();
255        assert!(!line.contains('\n'), "wire line must be single-line");
256        let out = open_line(&enc, &line).unwrap();
257        assert_eq!(out, record);
258    }
259
260    #[test]
261    fn open_line_passes_through_legacy_jsonl() {
262        let enc = XChaChaEncryptor::new(test_key(4));
263        let legacy = "{\"local_seq\":1,\"op\":\"Create\"}";
264        let out = open_line(&enc, legacy).unwrap();
265        assert_eq!(out, legacy.as_bytes());
266    }
267
268    #[test]
269    fn load_or_create_key_creates_0600_and_is_idempotent() {
270        let dir = tempfile::tempdir().unwrap();
271        let path = dir.path().join("nested").join("sync.key");
272        let first = load_or_create_key(&path).unwrap();
273
274        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
275        assert_eq!(mode, 0o600, "key file must be 0600");
276
277        let second = load_or_create_key(&path).unwrap();
278        assert_eq!(
279            first, second,
280            "second load must return the same persisted key"
281        );
282    }
283}