Skip to main content

second_brain_core/keys/
aside.rs

1use std::fs;
2use std::io::ErrorKind;
3use std::path::{Path, PathBuf};
4
5use anyhow::{Context, Result, anyhow, bail, ensure};
6use chrono::{DateTime, NaiveDateTime};
7
8use super::device::sync_dir;
9use super::{KeyStorage, open_device_store};
10use crate::machine::MachineIdentity;
11use crate::sqlite_store::SqliteStore;
12use crate::sqlite_store::encrypt_migration::{FileState, db_file_state};
13
14/// How long a data dir moved aside by a restore or a pairing is kept
15/// before the daemon deletes it.
16pub const ASIDE_RETENTION_MICROS: i64 = 90 * 86_400 * 1_000_000;
17
18pub(super) const RESTORE_MARKER: &str = ".before-restore-";
19const PAIR_MARKER: &str = ".before-pair-";
20const ASIDE_MARKERS: &[&str] = &[RESTORE_MARKER, PAIR_MARKER];
21const DB_FILE: &str = "brain.db";
22const MACHINE_FILE: &str = "machine.toml";
23/// Host files a data dir moved aside for pairing leaves in its fresh
24/// replacement.
25const KEPT_HOST_FILES: &[&str] = &["config.toml", "service.json"];
26const STAMP_FORMAT: &str = "%Y%m%d-%H%M%S";
27const STAMP_LEN: usize = 15;
28
29/// A data dir moved aside beside `data_dir` and when it was moved, read
30/// from its name.
31#[derive(Debug, Clone, PartialEq, Eq)]
32pub struct MovedAside {
33    pub path: PathBuf,
34    pub moved_at_micros: i64,
35}
36
37/// The data dirs a restore or a pairing moved aside beside `data_dir`. Symlinks and
38/// names whose stamp does not parse are left out, so nothing else is ever
39/// taken for one.
40pub fn moved_aside_dirs(data_dir: &Path) -> Result<Vec<MovedAside>> {
41    let (Some(parent), Some(base)) = (data_dir.parent(), data_dir.file_name()) else {
42        return Ok(Vec::new());
43    };
44    let base = base.to_string_lossy();
45    let entries = match fs::read_dir(parent) {
46        Ok(entries) => entries,
47        Err(e) if e.kind() == ErrorKind::NotFound => return Ok(Vec::new()),
48        Err(e) => return Err(e).with_context(|| format!("reading {}", parent.display())),
49    };
50    let mut found = Vec::new();
51    for entry in entries {
52        let entry = entry?;
53        let name = entry.file_name();
54        let name = name.to_string_lossy();
55        let Some(stamp) = ASIDE_MARKERS
56            .iter()
57            .find_map(|marker| name.strip_prefix(&*base)?.strip_prefix(marker))
58        else {
59            continue;
60        };
61        let Some(moved_at_micros) = parse_stamp(stamp) else {
62            continue;
63        };
64        if !entry.file_type()?.is_dir() {
65            continue;
66        }
67        found.push(MovedAside {
68            path: entry.path(),
69            moved_at_micros,
70        });
71    }
72    found.sort_by(|a, b| a.path.cmp(&b.path));
73    Ok(found)
74}
75
76/// Deletes the moved-aside data dirs older than `ASIDE_RETENTION_MICROS`
77/// and returns them. One that cannot be deleted is logged and does not stop
78/// the others.
79pub fn remove_expired_asides(data_dir: &Path, now_micros: i64) -> Result<Vec<PathBuf>> {
80    let mut removed = Vec::new();
81    for aside in moved_aside_dirs(data_dir)? {
82        if now_micros.saturating_sub(aside.moved_at_micros) < ASIDE_RETENTION_MICROS {
83            continue;
84        }
85        match fs::remove_dir_all(&aside.path) {
86            Ok(()) => removed.push(aside.path),
87            Err(e) => tracing::warn!("could not delete {}: {e}", aside.path.display()),
88        }
89    }
90    Ok(removed)
91}
92
93/// Moves `data_dir` aside to `<base>.before-pair-<stamp>` and puts an empty
94/// private dir in its place holding only the host's config.toml and
95/// service.json, plus an empty file for each name in `marks`. The moved dir
96/// keeps its own machine id and keys, so
97/// `open_moved_aside` still reads it. When a step after the rename fails,
98/// the old dir is moved back.
99pub fn move_aside_for_pairing(data_dir: &Path, now_micros: i64, marks: &[&str]) -> Result<PathBuf> {
100    let meta = fs::symlink_metadata(data_dir)
101        .with_context(|| format!("reading {}", data_dir.display()))?;
102    ensure!(
103        !meta.file_type().is_symlink(),
104        "{} is a symlink; only a real data dir is moved aside",
105        data_dir.display()
106    );
107    ensure!(meta.is_dir(), "{} is not a directory", data_dir.display());
108    let parent = match data_dir.parent() {
109        Some(dir) if !dir.as_os_str().is_empty() => dir.to_path_buf(),
110        Some(_) => PathBuf::from("."),
111        None => bail!("{} has no parent directory", data_dir.display()),
112    };
113    let base = data_dir
114        .file_name()
115        .ok_or_else(|| anyhow!("{} has no directory name", data_dir.display()))?
116        .to_string_lossy();
117    let aside = aside_path(&parent, &base, PAIR_MARKER, now_micros);
118    fs::rename(data_dir, &aside)
119        .with_context(|| format!("moving {} aside to {}", data_dir.display(), aside.display()))?;
120    if let Err(e) = create_private_dir(data_dir) {
121        return Err(put_back(e, &aside, data_dir, false));
122    }
123    let carried = KEPT_HOST_FILES
124        .iter()
125        .try_for_each(|name| carry_over(&aside.join(name), &data_dir.join(name)))
126        .and_then(|()| {
127            marks.iter().try_for_each(|name| {
128                let path = data_dir.join(name);
129                fs::write(&path, b"").with_context(|| format!("writing {}", path.display()))
130            })
131        })
132        .and_then(|()| sync_dir(data_dir))
133        .and_then(|()| sync_dir(&parent));
134    match carried {
135        Ok(()) => Ok(aside),
136        Err(e) => Err(put_back(e, &aside, data_dir, true)),
137    }
138}
139
140fn put_back(error: anyhow::Error, aside: &Path, data_dir: &Path, created: bool) -> anyhow::Error {
141    let cleared = if created {
142        fs::remove_dir_all(data_dir)
143    } else {
144        Ok(())
145    };
146    match cleared.and_then(|()| fs::rename(aside, data_dir)) {
147        Ok(()) => error,
148        Err(back) => error.context(format!(
149            "the data dir is now {} and could not be moved back to {} ({back})",
150            aside.display(),
151            data_dir.display()
152        )),
153    }
154}
155
156/// Opens the store of a data dir moved aside under the machine id and keys
157/// that dir holds. Nothing missing is created in it.
158pub fn open_moved_aside(aside: &Path) -> Result<SqliteStore> {
159    let machine_file = aside.join(MACHINE_FILE);
160    let machine = MachineIdentity::load(aside)
161        .with_context(|| format!("reading {}", machine_file.display()))?
162        .ok_or_else(|| anyhow!("{} is missing", machine_file.display()))?;
163    let db = aside.join(DB_FILE);
164    ensure!(
165        db_file_state(&db)? != FileState::Absent,
166        "{} is missing or empty",
167        db.display()
168    );
169    let opened =
170        open_device_store(&db, aside, machine.id, &KeyStorage::detect_for(aside)).map(|o| o.store);
171    opened.with_context(|| format!("opening {}", db.display()))
172}
173
174/// Where `<base>` moves aside under `marker` at `now_micros`, beside it in
175/// `parent`, in the form `moved_aside_dirs` reads back.
176pub(super) fn aside_path(parent: &Path, base: &str, marker: &str, now_micros: i64) -> PathBuf {
177    let stamp = DateTime::from_timestamp_micros(now_micros)
178        .unwrap_or_default()
179        .format(STAMP_FORMAT);
180    free_path(parent, &format!("{base}{marker}{stamp}"))
181}
182
183fn free_path(parent: &Path, name: &str) -> PathBuf {
184    let first = parent.join(name);
185    if !first.exists() {
186        return first;
187    }
188    (2..)
189        .map(|n| parent.join(format!("{name}-{n}")))
190        .find(|p| !p.exists())
191        .unwrap_or(first)
192}
193
194pub(super) fn carry_over(from: &Path, to: &Path) -> Result<()> {
195    match fs::copy(from, to).and_then(|_| fs::File::open(to)?.sync_all()) {
196        Ok(()) => Ok(()),
197        Err(e) if e.kind() == ErrorKind::NotFound => Ok(()),
198        Err(e) => Err(e).with_context(|| format!("copying {} to {}", from.display(), to.display())),
199    }
200}
201
202pub(super) fn create_private_dir(dir: &Path) -> Result<()> {
203    let mut builder = fs::DirBuilder::new();
204    #[cfg(unix)]
205    std::os::unix::fs::DirBuilderExt::mode(&mut builder, crate::private_files::PRIVATE_DIR_MODE);
206    builder
207        .create(dir)
208        .with_context(|| format!("creating {}", dir.display()))
209}
210
211/// `free_path` adds `-<n>` when the stamped name is taken.
212fn parse_stamp(rest: &str) -> Option<i64> {
213    let stamp = rest.get(..STAMP_LEN)?;
214    let suffix = &rest[STAMP_LEN..];
215    if !suffix.is_empty()
216        && !suffix
217            .strip_prefix('-')
218            .is_some_and(|n| !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit()))
219    {
220        return None;
221    }
222    let moved = NaiveDateTime::parse_from_str(stamp, STAMP_FORMAT).ok()?;
223    Some(moved.and_utc().timestamp_micros())
224}
225
226#[cfg(test)]
227mod tests {
228    use super::*;
229
230    use crate::machine::MachineIdentity;
231    use crate::schema::{Memory, MemoryType};
232    use crate::store::Store;
233
234    const DAY: i64 = 86_400 * 1_000_000;
235
236    fn micros(stamp: &str) -> i64 {
237        parse_stamp(stamp).unwrap()
238    }
239
240    #[test]
241    fn asides_older_than_ninety_days_are_deleted_and_nothing_else() {
242        let home = tempfile::tempdir().unwrap();
243        let data_dir = home.path().join(".second-brain");
244        fs::create_dir(&data_dir).unwrap();
245        let old = home
246            .path()
247            .join(".second-brain.before-restore-20260101-120000");
248        let old_again = home
249            .path()
250            .join(".second-brain.before-restore-20260101-120000-2");
251        let recent = home
252            .path()
253            .join(".second-brain.before-restore-20260301-000000");
254        let unrelated = home.path().join(".second-brain.before-restore-notes");
255        let other_base = home.path().join(".other.before-restore-20260101-120000");
256        let file = home
257            .path()
258            .join(".second-brain.before-restore-20250101-000000");
259        for dir in [&old, &old_again, &recent, &unrelated, &other_base] {
260            fs::create_dir(dir).unwrap();
261            fs::write(dir.join("brain.db"), b"x").unwrap();
262        }
263        fs::write(&file, b"not a dir").unwrap();
264        let link = home
265            .path()
266            .join(".second-brain.before-restore-20250102-000000");
267        std::os::unix::fs::symlink(&data_dir, &link).unwrap();
268
269        let now = micros("20260101-120000") + 90 * DAY;
270        let removed = remove_expired_asides(&data_dir, now).unwrap();
271        assert_eq!(removed, vec![old.clone(), old_again.clone()]);
272        assert!(!old.exists() && !old_again.exists());
273        for kept in [&recent, &unrelated, &other_base, &file, &data_dir] {
274            assert!(kept.exists(), "{} must stay", kept.display());
275        }
276        assert!(fs::symlink_metadata(&link).is_ok());
277        assert!(data_dir.exists());
278
279        assert!(
280            remove_expired_asides(&data_dir, now - 1)
281                .unwrap()
282                .is_empty()
283        );
284    }
285
286    #[test]
287    fn an_aside_that_cannot_be_deleted_does_not_stop_the_others() {
288        use std::os::unix::fs::PermissionsExt;
289
290        let home = tempfile::tempdir().unwrap();
291        let data_dir = home.path().join(".second-brain");
292        fs::create_dir(&data_dir).unwrap();
293        let stuck = home
294            .path()
295            .join(".second-brain.before-restore-20250101-000000");
296        let gone = home
297            .path()
298            .join(".second-brain.before-restore-20250102-000000");
299        for dir in [&stuck, &gone] {
300            fs::create_dir_all(dir.join("indexes")).unwrap();
301            fs::write(dir.join("indexes").join("seg"), b"x").unwrap();
302        }
303        fs::set_permissions(stuck.join("indexes"), fs::Permissions::from_mode(0o500)).unwrap();
304
305        let now = micros("20260601-000000");
306        let removed = remove_expired_asides(&data_dir, now);
307        fs::set_permissions(stuck.join("indexes"), fs::Permissions::from_mode(0o700)).unwrap();
308        assert_eq!(removed.unwrap(), vec![gone.clone()]);
309        assert!(!gone.exists());
310        assert!(stuck.exists());
311    }
312
313    #[test]
314    fn a_stamp_with_trailing_text_is_not_an_aside() {
315        assert!(parse_stamp("20260101-120000").is_some());
316        assert!(parse_stamp("20260101-120000-12").is_some());
317        assert!(parse_stamp("20260101-120000-").is_none());
318        assert!(parse_stamp("20260101-120000x").is_none());
319        assert!(parse_stamp("2026").is_none());
320    }
321
322    fn names(dir: &Path) -> Vec<String> {
323        let mut names: Vec<String> = fs::read_dir(dir)
324            .unwrap()
325            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
326            .collect();
327        names.sort();
328        names
329    }
330
331    fn populated_data_dir(home: &Path) -> PathBuf {
332        let data_dir = home.join(".second-brain");
333        fs::create_dir(&data_dir).unwrap();
334        for (name, body) in [
335            ("brain.db", "db"),
336            ("machine.toml", "machine"),
337            ("device.key", "device"),
338            ("store.key", "store"),
339            ("sync.key", "sync"),
340            ("config.toml", "config"),
341            ("service.json", "service"),
342        ] {
343            fs::write(data_dir.join(name), body).unwrap();
344        }
345        fs::create_dir(data_dir.join("indexes")).unwrap();
346        fs::write(data_dir.join("indexes").join("seg"), "seg").unwrap();
347        data_dir
348    }
349
350    fn memory(content: &str) -> Memory {
351        Memory::new(
352            content.to_string(),
353            MemoryType::Semantic,
354            "test".to_string(),
355            String::new(),
356        )
357    }
358
359    #[test]
360    fn moving_aside_for_pairing_keeps_the_old_dir_and_carries_only_host_files() {
361        use std::os::unix::fs::PermissionsExt;
362
363        let home = tempfile::tempdir().unwrap();
364        let data_dir = populated_data_dir(home.path());
365        let now = micros("20261103-101500");
366
367        let aside = move_aside_for_pairing(&data_dir, now, &["join-marker"]).unwrap();
368        assert_eq!(
369            aside,
370            home.path()
371                .join(".second-brain.before-pair-20261103-101500")
372        );
373        assert_eq!(
374            names(&aside),
375            [
376                "brain.db",
377                "config.toml",
378                "device.key",
379                "indexes",
380                "machine.toml",
381                "service.json",
382                "store.key",
383                "sync.key"
384            ]
385        );
386        assert_eq!(
387            fs::read_to_string(aside.join("device.key")).unwrap(),
388            "device"
389        );
390        assert_eq!(
391            fs::read_to_string(aside.join("indexes").join("seg")).unwrap(),
392            "seg"
393        );
394        assert_eq!(
395            names(&data_dir),
396            ["config.toml", "join-marker", "service.json"]
397        );
398        assert_eq!(
399            fs::read_to_string(data_dir.join("config.toml")).unwrap(),
400            "config"
401        );
402        assert_eq!(
403            fs::read_to_string(data_dir.join("service.json")).unwrap(),
404            "service"
405        );
406        let mode = fs::metadata(&data_dir).unwrap().permissions().mode() & 0o777;
407        assert_eq!(mode, crate::private_files::PRIVATE_DIR_MODE);
408
409        let again = move_aside_for_pairing(&data_dir, now, &[]).unwrap();
410        assert_eq!(
411            again,
412            home.path()
413                .join(".second-brain.before-pair-20261103-101500-2")
414        );
415        assert_eq!(
416            names(&again),
417            ["config.toml", "join-marker", "service.json"]
418        );
419        assert_eq!(names(&data_dir), ["config.toml", "service.json"]);
420
421        assert_eq!(
422            moved_aside_dirs(&data_dir).unwrap(),
423            vec![
424                MovedAside {
425                    path: aside.clone(),
426                    moved_at_micros: now,
427                },
428                MovedAside {
429                    path: again.clone(),
430                    moved_at_micros: now,
431                },
432            ]
433        );
434        assert!(
435            remove_expired_asides(&data_dir, now + 90 * DAY - 1)
436                .unwrap()
437                .is_empty()
438        );
439        assert_eq!(
440            remove_expired_asides(&data_dir, now + 90 * DAY).unwrap(),
441            vec![aside.clone(), again.clone()]
442        );
443        assert!(!aside.exists() && !again.exists());
444        assert!(data_dir.exists());
445    }
446
447    #[test]
448    fn a_data_dir_without_host_files_moves_aside_into_an_empty_dir() {
449        let home = tempfile::tempdir().unwrap();
450        let data_dir = home.path().join(".second-brain");
451        fs::create_dir(&data_dir).unwrap();
452        fs::write(data_dir.join("brain.db"), "db").unwrap();
453
454        let aside = move_aside_for_pairing(&data_dir, micros("20261103-101500"), &[]).unwrap();
455        assert_eq!(names(&aside), ["brain.db"]);
456        assert!(names(&data_dir).is_empty());
457    }
458
459    #[test]
460    fn a_missing_or_linked_data_dir_is_not_moved() {
461        let home = tempfile::tempdir().unwrap();
462        let now = micros("20261103-101500");
463        let missing = home.path().join(".second-brain");
464        let err = format!(
465            "{:#}",
466            move_aside_for_pairing(&missing, now, &[]).unwrap_err()
467        );
468        assert!(err.contains(&missing.display().to_string()), "{err}");
469        assert!(names(home.path()).is_empty());
470
471        fs::create_dir(home.path().join("elsewhere")).unwrap();
472        let target = populated_data_dir(&home.path().join("elsewhere"));
473        std::os::unix::fs::symlink(&target, &missing).unwrap();
474        let err = format!(
475            "{:#}",
476            move_aside_for_pairing(&missing, now, &[]).unwrap_err()
477        );
478        assert!(err.contains("symlink"), "{err}");
479        assert!(
480            fs::symlink_metadata(&missing)
481                .unwrap()
482                .file_type()
483                .is_symlink()
484        );
485        assert_eq!(names(home.path()), [".second-brain", "elsewhere"]);
486        assert!(target.join("brain.db").exists());
487    }
488
489    #[test]
490    fn a_move_that_fails_after_the_rename_puts_the_data_dir_back() {
491        let home = tempfile::tempdir().unwrap();
492        let data_dir = home.path().join(".second-brain");
493        fs::create_dir(&data_dir).unwrap();
494        fs::write(data_dir.join("brain.db"), "db").unwrap();
495        fs::create_dir(data_dir.join("config.toml")).unwrap();
496
497        assert!(move_aside_for_pairing(&data_dir, micros("20261103-101500"), &[]).is_err());
498        assert_eq!(names(home.path()), [".second-brain"]);
499        assert_eq!(names(&data_dir), ["brain.db", "config.toml"]);
500    }
501
502    #[test]
503    fn a_moved_aside_plaintext_store_opens_with_its_own_machine_id() {
504        let home = tempfile::tempdir().unwrap();
505        let data_dir = home.path().join(".second-brain");
506        let machine = MachineIdentity::load_or_create(&data_dir).unwrap();
507        let kept = memory("written before pairing");
508        {
509            let store = SqliteStore::open(&data_dir.join("brain.db"), machine.id.clone()).unwrap();
510            store.store_memory(&kept).unwrap();
511        }
512
513        let aside = move_aside_for_pairing(&data_dir, micros("20261103-101500"), &[]).unwrap();
514        let store = open_moved_aside(&aside).unwrap();
515        assert_eq!(store.machine_id(), machine.id);
516        assert_eq!(
517            store.get_memory(kept.id).unwrap().unwrap().content,
518            kept.content
519        );
520    }
521
522    #[test]
523    fn an_aside_without_a_store_or_machine_file_names_what_is_missing() {
524        let home = tempfile::tempdir().unwrap();
525        let aside = home
526            .path()
527            .join(".second-brain.before-pair-20261103-101500");
528        fs::create_dir(&aside).unwrap();
529        let err = format!("{:#}", open_moved_aside(&aside).err().unwrap());
530        assert!(
531            err.contains(&aside.join("machine.toml").display().to_string()),
532            "{err}"
533        );
534
535        MachineIdentity::load_or_create(&aside).unwrap();
536        let err = format!("{:#}", open_moved_aside(&aside).err().unwrap());
537        assert!(
538            err.contains(&aside.join("brain.db").display().to_string()),
539            "{err}"
540        );
541        assert!(!aside.join("brain.db").exists());
542    }
543
544    #[cfg(feature = "encryption")]
545    #[test]
546    fn a_moved_aside_encrypted_store_opens_with_the_asides_own_keys() {
547        let home = tempfile::tempdir().unwrap();
548        let data_dir = home.path().join(".second-brain");
549        let machine = MachineIdentity::load_or_create(&data_dir).unwrap();
550        let device =
551            crate::keys::create_device_keys(&data_dir, &crate::keys::KeyStorage::File).unwrap();
552        let kept = memory("encrypted before pairing");
553        {
554            let store = SqliteStore::open(&data_dir.join("brain.db"), machine.id.clone()).unwrap();
555            store.store_memory(&kept).unwrap();
556            crate::keys::encrypt_store(&store, &data_dir, &device).unwrap();
557        }
558
559        let aside = move_aside_for_pairing(&data_dir, micros("20261103-101500"), &[]).unwrap();
560        assert_eq!(
561            crate::sqlite_store::encrypt_migration::db_file_state(&aside.join("brain.db")).unwrap(),
562            crate::sqlite_store::encrypt_migration::FileState::Encrypted
563        );
564        let store = open_moved_aside(&aside).unwrap();
565        assert_eq!(
566            store.get_memory(kept.id).unwrap().unwrap().content,
567            kept.content
568        );
569        drop(store);
570
571        fs::remove_file(aside.join(crate::keys::DEVICE_KEY_FILE)).unwrap();
572        let err = format!("{:#}", open_moved_aside(&aside).err().unwrap());
573        assert!(err.contains(&aside.display().to_string()), "{err}");
574    }
575
576    #[test]
577    fn a_missing_parent_has_no_asides() {
578        let home = tempfile::tempdir().unwrap();
579        let data_dir = home.path().join("gone").join(".second-brain");
580        assert!(moved_aside_dirs(&data_dir).unwrap().is_empty());
581    }
582}