Skip to main content

second_brain_api/
store_encryption.rs

1//! Moves a plaintext store in the data dir to SQLCipher at the first quiet
2//! minute after an upgrade, rotates the store key after a revocation or a
3//! recovery phrase retirement, and keeps `store.key.wrapped` under the
4//! newest epoch.
5
6use std::path::PathBuf;
7use std::sync::Arc;
8use std::time::{Duration, Instant};
9
10use anyhow::Result;
11use chrono::Utc;
12use second_brain_core::keys::{
13    self, DeviceKeys, KeyStorage, StoreEncryption, WrapRefresh, encrypt_store, rotate_store_key,
14};
15use second_brain_core::sqlite_store::encrypt_migration::{
16    NotReopened, ReadsHeld, Rewrite, remove_plaintext_copies,
17};
18use second_brain_core::sqlite_store::{SqliteStore, VacuumSpace};
19use tokio::task::JoinHandle;
20use tokio::time::MissedTickBehavior;
21
22use crate::health::{EncryptionState, Health};
23use crate::write_gate::WriteGate;
24
25pub const TICK: Duration = Duration::from_secs(60);
26const RETRY_AFTER_FAILURE: Duration = Duration::from_secs(24 * 3600);
27const RETRY_AFTER_HELD_READS: Duration = Duration::from_secs(3600);
28pub const PLAINTEXT_COPY_LIFETIME: Duration = Duration::from_secs(24 * 3600);
29const NOTICE_SHOWN_FOR_MICROS: i64 = 7 * 24 * 3600 * 1_000_000;
30
31pub struct StoreEncryptor {
32    pub store: Arc<SqliteStore>,
33    pub gate: Arc<WriteGate>,
34    pub health: Arc<Health>,
35    pub data_dir: PathBuf,
36    pub storage: KeyStorage,
37    pub space: fn(&SqliteStore) -> Result<VacuumSpace>,
38    in_data_dir: bool,
39    pending: bool,
40    waiting_for_space: bool,
41    last_writes: Option<u64>,
42    retry_at: Option<Instant>,
43}
44
45#[derive(Debug, PartialEq, Eq)]
46pub enum Tick {
47    Idle,
48    NotQuiet,
49    NoSpace,
50    Encrypted(Duration),
51    Rotated(Duration),
52    Failed(String),
53}
54
55impl StoreEncryptor {
56    pub fn new(
57        store: Arc<SqliteStore>,
58        gate: Arc<WriteGate>,
59        health: Arc<Health>,
60        data_dir: PathBuf,
61        storage: KeyStorage,
62        encryption: StoreEncryption,
63    ) -> Self {
64        let in_data_dir = keys::store_in_data_dir(&store, &data_dir);
65        if !in_data_dir {
66            tracing::info!(
67                "the store is outside {}, so its key files are left to the dir it is in",
68                data_dir.display()
69            );
70        }
71        let pending = encryption == StoreEncryption::Pending;
72        let state = match encryption {
73            StoreEncryption::Encrypted => EncryptionState::Encrypted,
74            StoreEncryption::Pending => EncryptionState::Pending,
75            _ => EncryptionState::Plaintext,
76        };
77        health.encryption(state, None, Utc::now());
78        if let Ok(Some(record)) = store.encrypted_record() {
79            let recent = Utc::now().timestamp_micros() - record.at_micros < NOTICE_SHOWN_FOR_MICROS;
80            health.encryption_migrated(record.pause_ms, recent, Utc::now());
81        }
82        Self {
83            store,
84            gate,
85            health,
86            data_dir,
87            storage,
88            space: SqliteStore::rewrite_space,
89            in_data_dir,
90            pending,
91            waiting_for_space: false,
92            last_writes: None,
93            retry_at: None,
94        }
95    }
96
97    /// Ticks on an unconditional interval, not gated on
98    /// `config.maintenance.enabled`. Exits the process when a rewrite left
99    /// the store unopened, so the supervisor restarts it into the new file.
100    pub fn spawn(mut self) -> JoinHandle<()> {
101        tokio::spawn(async move {
102            let mut interval = tokio::time::interval(TICK);
103            interval.set_missed_tick_behavior(MissedTickBehavior::Delay);
104            loop {
105                interval.tick().await;
106                let ticked = tokio::task::spawn_blocking(move || {
107                    let outcome = self.tick(Instant::now());
108                    (self, outcome)
109                })
110                .await;
111                match ticked {
112                    Ok((encryptor, outcome)) => {
113                        self = encryptor;
114                        log(&outcome);
115                    }
116                    Err(e) => {
117                        tracing::error!("store encryption tick panicked: {e}");
118                        return;
119                    }
120                }
121            }
122        })
123    }
124
125    pub fn tick(&mut self, now: Instant) -> Tick {
126        if let Err(e) = remove_plaintext_copies(&self.data_dir, Some(PLAINTEXT_COPY_LIFETIME)) {
127            tracing::warn!("cannot remove old plaintext copies: {e:#}");
128        }
129        if !self.in_data_dir {
130            return Tick::Idle;
131        }
132        let writes = self.store.write_count();
133        let quiet = self.last_writes == Some(writes);
134        self.last_writes = Some(writes);
135        let device = match keys::load_device_keys_in(&self.data_dir, &self.storage) {
136            Ok(Some(device)) => device,
137            Ok(None) => return Tick::Idle,
138            Err(e) => return Tick::Failed(format!("{e:#}")),
139        };
140        if self.store.is_encrypted() {
141            self.refresh_wrap(&device);
142        }
143        let due = if self.pending {
144            true
145        } else if self.store.is_encrypted() {
146            match (
147                self.store.revocations_after_store_key(),
148                self.store.retirements_after_store_key(),
149            ) {
150                (Ok(revoked), Ok(retired)) => !revoked.is_empty() || !retired.is_empty(),
151                (Err(e), _) | (_, Err(e)) => return Tick::Failed(format!("{e:#}")),
152            }
153        } else {
154            false
155        };
156        if !due || self.retry_at.is_some_and(|at| now < at) {
157            return Tick::Idle;
158        }
159        let space = match (self.space)(&self.store) {
160            Ok(space) => space,
161            Err(e) => return Tick::Failed(format!("{e:#}")),
162        };
163        if !space.fits() {
164            if self.pending {
165                self.waiting_for_space = true;
166                self.health
167                    .encryption(EncryptionState::WaitingForSpace, Some(space), Utc::now());
168            }
169            return Tick::NoSpace;
170        }
171        if std::mem::take(&mut self.waiting_for_space) {
172            self.health
173                .encryption(EncryptionState::Pending, None, Utc::now());
174        }
175        if !quiet {
176            return Tick::NotQuiet;
177        }
178        let outcome = self.rewrite(&device);
179        match outcome {
180            Ok(tick) => {
181                self.last_writes = Some(self.store.write_count());
182                tick
183            }
184            Err(e) => {
185                if e.downcast_ref::<NotReopened>().is_some() {
186                    tracing::error!("{e:#}");
187                    std::process::exit(1);
188                }
189                let message = format!("{e:#}");
190                self.retry_at = Some(now + retry_after(&e));
191                let state = if self.pending {
192                    EncryptionState::Pending
193                } else {
194                    EncryptionState::Encrypted
195                };
196                self.health.encryption(state, None, Utc::now());
197                self.health.encryption_failed(&message, Utc::now());
198                Tick::Failed(message)
199            }
200        }
201    }
202
203    fn rewrite(&mut self, device: &DeviceKeys) -> Result<Tick> {
204        let _closed = self.gate.close();
205        if self.pending {
206            self.health
207                .encryption(EncryptionState::Encrypting, None, Utc::now());
208            let Rewrite { pause, .. } = encrypt_store(&self.store, &self.data_dir, device)?;
209            self.pending = false;
210            self.health
211                .encryption(EncryptionState::Encrypted, None, Utc::now());
212            self.health.encryption_migrated(
213                u64::try_from(pause.as_millis()).unwrap_or(u64::MAX),
214                true,
215                Utc::now(),
216            );
217            Ok(Tick::Encrypted(pause))
218        } else {
219            self.health
220                .encryption(EncryptionState::Rotating, None, Utc::now());
221            let Rewrite { pause, .. } = rotate_store_key(&self.store, &self.data_dir, device)?;
222            self.health
223                .encryption(EncryptionState::Encrypted, None, Utc::now());
224            Ok(Tick::Rotated(pause))
225        }
226    }
227
228    fn refresh_wrap(&self, device: &DeviceKeys) {
229        match keys::refresh_store_key_wrap(&self.store, &self.data_dir, device) {
230            Ok(WrapRefresh::Written) => {
231                tracing::info!("store.key.wrapped follows the newest epoch")
232            }
233            Ok(_) => {}
234            Err(e) => tracing::warn!("cannot refresh store.key.wrapped: {e:#}"),
235        }
236    }
237}
238
239fn retry_after(error: &anyhow::Error) -> Duration {
240    if error.downcast_ref::<ReadsHeld>().is_some() {
241        RETRY_AFTER_HELD_READS
242    } else {
243        RETRY_AFTER_FAILURE
244    }
245}
246
247fn log(outcome: &Tick) {
248    match outcome {
249        Tick::Encrypted(pause) => tracing::info!(
250            pause_ms = pause.as_millis() as u64,
251            "the store is encrypted; writes waited for the rewrite"
252        ),
253        Tick::Rotated(pause) => tracing::info!(
254            pause_ms = pause.as_millis() as u64,
255            "the store key was rotated after a revocation or a recovery phrase retirement"
256        ),
257        Tick::Failed(e) => tracing::warn!("store encryption: {e}"),
258        Tick::NoSpace => tracing::warn!("store encryption waits for disk space"),
259        Tick::Idle | Tick::NotQuiet => {}
260    }
261}
262
263#[cfg(test)]
264mod tests {
265    use std::collections::BTreeSet;
266    use std::path::Path;
267
268    use second_brain_core::keys::{
269        KeyStorage, RecoveryPhrase, Retirement, Revocation, STORE_KEY_FILE, found_identity,
270        load_device_keys_in, open_device_store, read_store_key,
271    };
272    use second_brain_core::schema::{Memory, MemoryType};
273    use second_brain_core::sqlite_store::encrypt_migration::{FileState, db_file_state};
274    use second_brain_core::store::Store;
275
276    use super::*;
277
278    fn remember(store: &SqliteStore, content: &str) {
279        store
280            .store_memory(&Memory::new(
281                content.to_string(),
282                MemoryType::Semantic,
283                "test".to_string(),
284                String::new(),
285            ))
286            .unwrap();
287    }
288
289    fn encryptor(dir: &Path) -> (StoreEncryptor, Arc<Health>) {
290        let opened = open_device_store(
291            &dir.join("brain.db"),
292            dir,
293            "machine-a".to_string(),
294            &KeyStorage::File,
295        )
296        .unwrap();
297        let store = Arc::new(opened.store);
298        keys::ensure_device_keys(&store, dir).unwrap();
299        let health = Arc::new(Health::new(Utc::now(), None));
300        let encryptor = StoreEncryptor::new(
301            store,
302            Arc::new(WriteGate::default()),
303            health.clone(),
304            dir.to_path_buf(),
305            KeyStorage::File,
306            opened.encryption,
307        );
308        (encryptor, health)
309    }
310
311    fn plaintext_data_dir() -> tempfile::TempDir {
312        let dir = tempfile::tempdir().unwrap();
313        let store = SqliteStore::open(&dir.path().join("brain.db"), "machine-a".into()).unwrap();
314        remember(&store, "written before the upgrade");
315        dir
316    }
317
318    #[test]
319    fn a_plaintext_store_is_encrypted_after_a_minute_with_no_write() {
320        let dir = plaintext_data_dir();
321        let (mut enc, health) = encryptor(dir.path());
322        assert_eq!(health.report().encryption.state, EncryptionState::Pending);
323        let t0 = Instant::now();
324
325        assert_eq!(enc.tick(t0), Tick::NotQuiet);
326        remember(&enc.store, "a write in the first minute");
327        assert_eq!(enc.tick(t0 + TICK), Tick::NotQuiet);
328        assert!(matches!(enc.tick(t0 + TICK * 2), Tick::Encrypted(_)));
329
330        let report = health.report().encryption;
331        assert_eq!(report.state, EncryptionState::Encrypted);
332        assert!(report.migration_pause_ms.is_some());
333        assert!(report.notice.is_some_and(|n| n.contains("full-disk")));
334        assert!(enc.store.is_encrypted());
335        assert_eq!(enc.store.memory_count().unwrap(), 2);
336        assert_eq!(enc.tick(t0 + TICK * 3), Tick::Idle);
337        drop(enc);
338        assert_eq!(
339            db_file_state(&dir.path().join("brain.db")).unwrap(),
340            FileState::Encrypted
341        );
342
343        let (_again, health) = encryptor(dir.path());
344        let report = health.report().encryption;
345        assert_eq!(report.state, EncryptionState::Encrypted);
346        assert!(report.notice.is_some(), "the notice survives a restart");
347    }
348
349    fn no_room(_: &SqliteStore) -> Result<VacuumSpace> {
350        Ok(VacuumSpace {
351            path: PathBuf::from("/data"),
352            needed_bytes: 5_000_000_000,
353            free_bytes: 1_000_000_000,
354        })
355    }
356
357    #[test]
358    fn a_disk_without_room_holds_the_migration_and_says_how_much_it_needs() {
359        let dir = plaintext_data_dir();
360        let (mut enc, health) = encryptor(dir.path());
361        enc.space = no_room;
362        let t0 = Instant::now();
363        enc.tick(t0);
364        assert_eq!(enc.tick(t0 + TICK), Tick::NoSpace);
365        let report = health.report();
366        assert_eq!(report.encryption.state, EncryptionState::WaitingForSpace);
367        let reason = report.reason.unwrap_or_default();
368        assert!(
369            reason.contains("encryption pending, needs 5000 MB"),
370            "{reason}"
371        );
372        assert!(!enc.store.is_encrypted());
373    }
374
375    #[test]
376    fn the_space_notice_clears_once_room_frees_without_waiting_for_a_quiet_minute() {
377        let dir = plaintext_data_dir();
378        let (mut enc, health) = encryptor(dir.path());
379        enc.space = no_room;
380        let t0 = Instant::now();
381        assert_eq!(enc.tick(t0), Tick::NoSpace);
382        assert_eq!(
383            health.report().encryption.state,
384            EncryptionState::WaitingForSpace
385        );
386
387        enc.space = SqliteStore::rewrite_space;
388        remember(&enc.store, "a write that keeps the minute busy");
389        assert_eq!(enc.tick(t0 + TICK), Tick::NotQuiet);
390        let report = health.report();
391        assert_eq!(report.encryption.state, EncryptionState::Pending);
392        assert!(
393            !report.reason.unwrap_or_default().contains("needs"),
394            "the space reason is gone"
395        );
396    }
397
398    #[test]
399    fn a_revocation_of_another_device_rotates_the_store_key() {
400        let dir = tempfile::tempdir().unwrap();
401        let (mut enc, _health) = encryptor(dir.path());
402        assert!(enc.store.is_encrypted());
403        let device = load_device_keys_in(dir.path(), &KeyStorage::File)
404            .unwrap()
405            .unwrap();
406        let founded = found_identity(&enc.store, &device, "machine-a", &[], 1).unwrap();
407        let t0 = Instant::now();
408        enc.tick(t0);
409        assert_eq!(enc.tick(t0 + TICK), Tick::Idle, "nothing to rotate for");
410
411        let before = read_store_key(&dir.path().join(STORE_KEY_FILE), &device)
412            .unwrap()
413            .unwrap();
414        let signed = Revocation {
415            identity_tag: founded.tag.as_str().to_string(),
416            revoker: "machine-a".to_string(),
417            target: "lost-laptop".to_string(),
418            keep: BTreeSet::new(),
419            created_at_micros: 2,
420        }
421        .sign(device.signing_key());
422        enc.store
423            .put_revocation(&signed, &device.verifying_key())
424            .unwrap();
425        assert_eq!(enc.tick(t0 + TICK * 2), Tick::NotQuiet);
426        let rotated = enc.tick(t0 + TICK * 3);
427        assert!(matches!(rotated, Tick::Rotated(_)), "{rotated:?}");
428        let after = read_store_key(&dir.path().join(STORE_KEY_FILE), &device)
429            .unwrap()
430            .unwrap();
431        assert_ne!(after.expose(), before.expose());
432        assert_eq!(
433            enc.tick(t0 + TICK * 4),
434            Tick::Idle,
435            "one rotation per revocation"
436        );
437    }
438
439    #[test]
440    fn a_retired_phrase_rotates_the_store_key_once_and_a_made_up_one_does_not() {
441        let dir = tempfile::tempdir().unwrap();
442        let (mut enc, _health) = encryptor(dir.path());
443        let device = load_device_keys_in(dir.path(), &KeyStorage::File)
444            .unwrap()
445            .unwrap();
446        let phrase = RecoveryPhrase::generate().unwrap();
447        let founded = found_identity(
448            &enc.store,
449            &device,
450            "machine-a",
451            &[phrase.recipient().unwrap()],
452            1,
453        )
454        .unwrap();
455        let t0 = Instant::now();
456        enc.tick(t0);
457        assert_eq!(enc.tick(t0 + TICK), Tick::Idle, "nothing to rotate for");
458        let key_now = || {
459            read_store_key(&dir.path().join(STORE_KEY_FILE), &device)
460                .unwrap()
461                .unwrap()
462        };
463        let store = enc.store.clone();
464        let retire = |fingerprint: String| {
465            let signed = Retirement {
466                identity_tag: founded.tag.as_str().to_string(),
467                retirer: "machine-a".to_string(),
468                fingerprint,
469                created_at_micros: 2,
470            }
471            .sign(device.signing_key());
472            store
473                .put_retirement(&signed, &device.verifying_key())
474                .unwrap();
475            store.mark_rotating_retirements(&founded.tag).unwrap();
476        };
477
478        let before = key_now();
479        retire("00112233445566ff".to_string());
480        for i in 2..5 {
481            assert_eq!(enc.tick(t0 + TICK * i), Tick::Idle, "made up");
482        }
483        assert_eq!(key_now().expose(), before.expose());
484
485        retire(phrase.fingerprint().unwrap());
486        let ticks: Vec<Tick> = (5..8).map(|i| enc.tick(t0 + TICK * i)).collect();
487        let rotations = ticks
488            .iter()
489            .filter(|t| matches!(t, Tick::Rotated(_)))
490            .count();
491        assert_eq!(rotations, 1, "one rotation per retirement: {ticks:?}");
492        assert_ne!(key_now().expose(), before.expose());
493    }
494
495    #[test]
496    fn held_reads_retry_within_the_hour_and_other_failures_the_next_day() {
497        let held = anyhow::Error::from(ReadsHeld(Duration::from_secs(30)))
498            .context("rotating the store key");
499        assert_eq!(retry_after(&held), RETRY_AFTER_HELD_READS);
500        assert_eq!(
501            retry_after(&anyhow::anyhow!("the copy failed its check")),
502            RETRY_AFTER_FAILURE
503        );
504    }
505
506    #[test]
507    fn a_store_outside_the_data_dir_is_left_alone() {
508        let data = tempfile::tempdir().unwrap();
509        let elsewhere = tempfile::tempdir().unwrap();
510        let opened = open_device_store(
511            &elsewhere.path().join("copy.db"),
512            data.path(),
513            "m".into(),
514            &KeyStorage::File,
515        )
516        .unwrap();
517        let store = Arc::new(opened.store);
518        keys::ensure_device_keys(&store, data.path()).unwrap();
519        let health = Arc::new(Health::new(Utc::now(), None));
520        let mut enc = StoreEncryptor::new(
521            store,
522            Arc::new(WriteGate::default()),
523            health.clone(),
524            data.path().to_path_buf(),
525            KeyStorage::File,
526            opened.encryption,
527        );
528        let t0 = Instant::now();
529        for i in 0..3 {
530            assert_eq!(enc.tick(t0 + TICK * i), Tick::Idle);
531        }
532        assert_eq!(health.report().encryption.state, EncryptionState::Plaintext);
533    }
534
535    #[test]
536    fn an_encrypted_copy_outside_the_data_dir_is_neither_rewrapped_nor_rotated() {
537        let data = tempfile::tempdir().unwrap();
538        let elsewhere = tempfile::tempdir().unwrap();
539        let opened = open_device_store(
540            &elsewhere.path().join("brain.db"),
541            elsewhere.path(),
542            "m".into(),
543            &KeyStorage::File,
544        )
545        .unwrap();
546        assert_eq!(opened.encryption, StoreEncryption::Encrypted);
547        let store = Arc::new(opened.store);
548        keys::ensure_device_keys(&store, data.path()).unwrap();
549        let device = load_device_keys_in(data.path(), &KeyStorage::File)
550            .unwrap()
551            .unwrap();
552        let founded = found_identity(&store, &device, "m", &[], 1).unwrap();
553        let signed = Revocation {
554            identity_tag: founded.tag.as_str().to_string(),
555            revoker: "m".to_string(),
556            target: "lost-laptop".to_string(),
557            keep: BTreeSet::new(),
558            created_at_micros: 2,
559        }
560        .sign(device.signing_key());
561        store
562            .put_revocation(&signed, &device.verifying_key())
563            .unwrap();
564        let health = Arc::new(Health::new(Utc::now(), None));
565        let mut enc = StoreEncryptor::new(
566            store,
567            Arc::new(WriteGate::default()),
568            health,
569            data.path().to_path_buf(),
570            KeyStorage::File,
571            opened.encryption,
572        );
573        let t0 = Instant::now();
574        for i in 0..3 {
575            assert_eq!(enc.tick(t0 + TICK * i), Tick::Idle);
576        }
577        assert!(!data.path().join(keys::WRAPPED_STORE_KEY_FILE).exists());
578    }
579
580    #[test]
581    fn old_plaintext_copies_are_removed_by_the_tick() {
582        let dir = tempfile::tempdir().unwrap();
583        let (mut enc, _health) = encryptor(dir.path());
584        let copy = enc.store.write_plaintext_copy(dir.path()).unwrap();
585        enc.tick(Instant::now());
586        assert!(copy.exists(), "a fresh copy stays for its lifetime");
587        let old = std::time::SystemTime::now() - PLAINTEXT_COPY_LIFETIME * 2;
588        std::fs::File::options()
589            .write(true)
590            .open(&copy)
591            .unwrap()
592            .set_modified(old)
593            .unwrap();
594        enc.tick(Instant::now());
595        assert!(!copy.exists());
596    }
597}