Skip to main content

second_brain_core/keys/
store_key.rs

1use std::collections::BTreeSet;
2use std::fmt;
3use std::fs;
4use std::io::{ErrorKind, Read, Write};
5use std::path::{Path, PathBuf};
6
7use anyhow::{Context, Result, anyhow, bail, ensure};
8use chacha20poly1305::aead::{Aead, KeyInit, Payload};
9use chacha20poly1305::{XChaCha20Poly1305, XNonce};
10use rand::TryRngCore;
11use rand::rngs::OsRng;
12use serde::{Deserialize, Serialize};
13use zeroize::Zeroizing;
14
15use super::device::{create_private_dir, sync_dir, write_private_file};
16use super::identity::{Envelope, Epoch, IdentityKey, IdentityTag, newest_epoch};
17use super::subkey::{Subkey, derive_subkey};
18use super::{DeviceKeys, HeldEpoch, KeyGuard, RecoveryPhrase, hex};
19use crate::sqlite_store::SqliteStore;
20use crate::sqlite_store::encrypt_migration::key_opens_file;
21
22const KEY_LEN: usize = 32;
23pub const STORE_KEY_FILE: &str = "store.key";
24pub const NEXT_STORE_KEY_FILE: &str = "store.key.next";
25pub const WRAPPED_STORE_KEY_FILE: &str = "store.key.wrapped";
26const WRAPPED_VERSION: u32 = 1;
27const WRAP_AAD_DOMAIN: &[u8] = b"second-brain store.key.wrapped v1";
28const NONCE_LEN: usize = 24;
29
30/// The raw 32-byte key SQLCipher encrypts one device's `brain.db` under.
31pub struct StoreKey(KeyGuard<[u8; KEY_LEN]>);
32
33impl StoreKey {
34    pub fn generate() -> Result<Self> {
35        Ok(Self(KeyGuard::random()?))
36    }
37
38    pub fn from_bytes(bytes: KeyGuard<[u8; KEY_LEN]>) -> Self {
39        Self(bytes)
40    }
41
42    pub fn expose(&self) -> &[u8; KEY_LEN] {
43        self.0.expose()
44    }
45
46    /// The key as SQLCipher's raw-key literal, `x'<hex>'`, which it uses
47    /// as-is with no passphrase derivation.
48    pub(crate) fn sql_literal(&self) -> Zeroizing<String> {
49        let hex = Zeroizing::new(hex(self.expose()));
50        Zeroizing::new(format!("x'{}'", hex.as_str()))
51    }
52
53    pub(crate) fn duplicate(&self) -> Self {
54        let mut bytes = KeyGuard::new([0u8; KEY_LEN]);
55        bytes.expose_mut().copy_from_slice(self.expose());
56        Self(bytes)
57    }
58
59    fn from_slice(bytes: &[u8]) -> Result<Self> {
60        ensure!(
61            bytes.len() == KEY_LEN,
62            "a store key holds {KEY_LEN} bytes, not {}",
63            bytes.len()
64        );
65        let mut key = KeyGuard::new([0u8; KEY_LEN]);
66        key.expose_mut().copy_from_slice(bytes);
67        Ok(Self(key))
68    }
69}
70
71impl fmt::Debug for StoreKey {
72    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
73        f.write_str("StoreKey(..)")
74    }
75}
76
77/// Installs `key` age-encrypted to this device at `dir/name`, replacing
78/// any file there, synced before it returns.
79pub fn write_store_key(dir: &Path, name: &str, key: &StoreKey, device: &DeviceKeys) -> Result<()> {
80    write_store_key_to(dir, name, key, &[device])
81}
82
83/// Like `write_store_key`, with the key opening for any of `devices`.
84pub(super) fn write_store_key_to(
85    dir: &Path,
86    name: &str,
87    key: &StoreKey,
88    devices: &[&DeviceKeys],
89) -> Result<()> {
90    let recipients: Vec<age::x25519::Recipient> =
91        devices.iter().map(|d| d.age_recipient()).collect();
92    let encryptor =
93        age::Encryptor::with_recipients(recipients.iter().map(|r| r as &dyn age::Recipient))
94            .map_err(|e| anyhow!("sealing the store key to this device: {e}"))?;
95    let mut sealed = Vec::new();
96    let mut writer = encryptor
97        .wrap_output(&mut sealed)
98        .context("sealing the store key to this device")?;
99    writer
100        .write_all(key.expose())
101        .and_then(|()| writer.finish().map(drop))
102        .context("sealing the store key to this device")?;
103    replace_private_file(dir, name, &sealed)
104}
105
106/// None when the file is absent.
107pub fn read_store_key(path: &Path, device: &DeviceKeys) -> Result<Option<StoreKey>> {
108    let sealed = match fs::read(path) {
109        Ok(bytes) => bytes,
110        Err(e) if e.kind() == ErrorKind::NotFound => return Ok(None),
111        Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
112    };
113    let decryptor = age::Decryptor::new_buffered(sealed.as_slice())
114        .map_err(|e| anyhow!("{} is not a sealed store key: {e}", path.display()))?;
115    let mut reader = decryptor
116        .decrypt(std::iter::once(device.age_identity() as &dyn age::Identity))
117        .map_err(|e| anyhow!("this device's key does not open {}: {e}", path.display()))?;
118    let mut plaintext = Zeroizing::new(Vec::with_capacity(KEY_LEN));
119    reader
120        .read_to_end(&mut plaintext)
121        .with_context(|| format!("reading {}", path.display()))?;
122    StoreKey::from_slice(&plaintext)
123        .map(Some)
124        .with_context(|| format!("{} is corrupt", path.display()))
125}
126
127/// The store key that opens `db`: `store.key`, or else `store.key.next`
128/// left by a rotation that renamed its copy into place but stopped before
129/// promoting its key, which is then promoted.
130pub fn store_key_for(db: &Path, device: &DeviceKeys) -> Result<StoreKey> {
131    let dir = dir_of(db);
132    let current = read_store_key(&dir.join(STORE_KEY_FILE), device)?;
133    let next_path = dir.join(NEXT_STORE_KEY_FILE);
134    if let Some(key) = current
135        && key_opens_file(db, &key)
136    {
137        remove_if_present(&next_path)?;
138        return Ok(key);
139    }
140    if let Some(next) = read_store_key(&next_path, device)?
141        && key_opens_file(db, &next)
142    {
143        fs::rename(&next_path, dir.join(STORE_KEY_FILE))
144            .with_context(|| format!("promoting {}", next_path.display()))?;
145        sync_dir(dir)?;
146        return Ok(next);
147    }
148    bail!(
149        "no store key in {} opens the encrypted store {}; restore the data dir from a \
150         backup with `sb restore`",
151        dir.display(),
152        db.display()
153    )
154}
155
156#[derive(Serialize, Deserialize)]
157struct WrappedFile {
158    version: u32,
159    identity_tag: IdentityTag,
160    epoch: Epoch,
161    nonce: String,
162    sealed: String,
163    recovery: Vec<Envelope>,
164}
165
166impl WrappedFile {
167    fn aad(tag: &IdentityTag, epoch: &Epoch) -> Vec<u8> {
168        let mut aad = WRAP_AAD_DOMAIN.to_vec();
169        aad.extend_from_slice(tag.as_str().as_bytes());
170        aad.push(0);
171        aad.extend_from_slice(&epoch.number.to_be_bytes());
172        aad.extend_from_slice(&epoch.key_id.0);
173        aad
174    }
175
176    fn seal(
177        key: &StoreKey,
178        tag: &IdentityTag,
179        epoch: &Epoch,
180        identity: &IdentityKey,
181        recovery: Vec<Envelope>,
182    ) -> Result<Self> {
183        let wrap_key = derive_subkey(identity, epoch, Subkey::StoreWrap)?;
184        let cipher = XChaCha20Poly1305::new(wrap_key.expose().into());
185        let mut nonce = [0u8; NONCE_LEN];
186        OsRng
187            .try_fill_bytes(&mut nonce)
188            .map_err(|e| anyhow!("reading OS randomness: {e}"))?;
189        let aad = Self::aad(tag, epoch);
190        let sealed = cipher
191            .encrypt(
192                XNonce::from_slice(&nonce),
193                Payload {
194                    msg: key.expose(),
195                    aad: &aad,
196                },
197            )
198            .map_err(|_| anyhow!("sealing the store key"))?;
199        Ok(Self {
200            version: WRAPPED_VERSION,
201            identity_tag: tag.clone(),
202            epoch: *epoch,
203            nonce: hex(&nonce),
204            sealed: hex(&sealed),
205            recovery,
206        })
207    }
208
209    fn open(&self, identity: &IdentityKey) -> Result<StoreKey> {
210        ensure!(
211            self.version == WRAPPED_VERSION,
212            "{WRAPPED_STORE_KEY_FILE} has version {}, not {WRAPPED_VERSION}",
213            self.version
214        );
215        let wrap_key = derive_subkey(identity, &self.epoch, Subkey::StoreWrap)?;
216        let cipher = XChaCha20Poly1305::new(wrap_key.expose().into());
217        let nonce = unhex_vec(&self.nonce)?;
218        ensure!(
219            nonce.len() == NONCE_LEN,
220            "{WRAPPED_STORE_KEY_FILE} has a bad nonce"
221        );
222        let aad = Self::aad(&self.identity_tag, &self.epoch);
223        let plaintext = Zeroizing::new(
224            cipher
225                .decrypt(
226                    XNonce::from_slice(&nonce),
227                    Payload {
228                        msg: &unhex_vec(&self.sealed)?,
229                        aad: &aad,
230                    },
231                )
232                .map_err(|_| anyhow!("the identity key does not open {WRAPPED_STORE_KEY_FILE}"))?,
233        );
234        StoreKey::from_slice(&plaintext)
235    }
236
237    fn recipients(&self) -> BTreeSet<&str> {
238        self.recovery.iter().map(|e| e.recipient.as_str()).collect()
239    }
240
241    fn read(dir: &Path) -> Result<Option<Self>> {
242        let path = dir.join(WRAPPED_STORE_KEY_FILE);
243        let text = match fs::read_to_string(&path) {
244            Ok(text) => text,
245            Err(e) if e.kind() == ErrorKind::NotFound => return Ok(None),
246            Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
247        };
248        serde_json::from_str(&text)
249            .map(Some)
250            .with_context(|| format!("{} is corrupt", path.display()))
251    }
252}
253
254#[derive(Debug, Clone, Copy, PartialEq, Eq)]
255#[non_exhaustive]
256pub enum WrapRefresh {
257    Written,
258    Current,
259    /// This device holds no epoch of its identity that may wrap at rest
260    /// (epoch 0 never does), so no backup of it can be opened by `K_id`.
261    NoIdentity,
262}
263
264/// Keeps `store.key.wrapped` sealed under the newest epoch of this
265/// device's identity, holding that epoch's recovery envelopes, so a
266/// data-dir backup opens with the phrase or another device's `K_id`.
267pub fn refresh_wrapped_store_key(
268    store: &SqliteStore,
269    data_dir: &Path,
270    device: &DeviceKeys,
271    key: &StoreKey,
272) -> Result<WrapRefresh> {
273    store_file_in(store, data_dir)?;
274    let recipient = device.age_recipient().to_string();
275    let Some((tag, own)) = store.own_identity_envelopes(&recipient)? else {
276        return Ok(WrapRefresh::NoIdentity);
277    };
278    let usable: Vec<&Envelope> = own.iter().filter(|e| e.epoch.number >= 1).collect();
279    let Some(epoch) = newest_epoch(usable.iter().map(|e| &e.epoch)) else {
280        return Ok(WrapRefresh::NoIdentity);
281    };
282    let envelope = usable
283        .iter()
284        .find(|e| e.epoch == epoch)
285        .expect("the newest epoch comes from these envelopes");
286    let identity = envelope.open(device.age_identity())?;
287    let recovery: Vec<Envelope> = store
288        .envelopes_for_epoch(&tag, &epoch)?
289        .into_iter()
290        .filter(|e| e.machine_id.is_none())
291        .collect();
292    if let Some(existing) = WrappedFile::read(data_dir)?
293        && existing.identity_tag == tag
294        && existing.epoch == epoch
295        && existing.recipients() == recovery.iter().map(|e| e.recipient.as_str()).collect()
296        && existing
297            .open(&identity)
298            .is_ok_and(|k| k.expose() == key.expose())
299    {
300        return Ok(WrapRefresh::Current);
301    }
302    let file = WrappedFile::seal(key, &tag, &epoch, &identity, recovery)?;
303    let text = serde_json::to_vec_pretty(&file)?;
304    replace_private_file(data_dir, WRAPPED_STORE_KEY_FILE, &text)?;
305    Ok(WrapRefresh::Written)
306}
307
308/// The store key of a data-dir backup, opened through the recovery phrase:
309/// the phrase opens `K_id` from an envelope beside the wrapped key. None
310/// when the backup holds no `store.key.wrapped`.
311pub fn unwrap_store_key_with_phrase(
312    backup_dir: &Path,
313    phrase: &RecoveryPhrase,
314) -> Result<Option<StoreKey>> {
315    let Some(file) = WrappedFile::read(backup_dir)? else {
316        return Ok(None);
317    };
318    let identity = phrase.identity()?;
319    let recipient = phrase.recipient()?.to_string();
320    let envelope = file
321        .recovery
322        .iter()
323        .find(|e| {
324            e.recipient == recipient && e.identity_tag == file.identity_tag && e.epoch == file.epoch
325        })
326        .ok_or_else(|| {
327            anyhow!(
328                "this recovery phrase is not among the recipients of the backup's \
329                 {WRAPPED_STORE_KEY_FILE}; check the phrase, or restore a backup of a device \
330                 that trusted it"
331            )
332        })?;
333    let key = envelope.open(&identity)?;
334    file.open(&key).map(Some)
335}
336
337/// The store key of a data-dir backup, opened with an epoch of `K_id`
338/// another device handed over or this device held. None when the backup
339/// holds no `store.key.wrapped`.
340pub fn unwrap_store_key_with_epochs(
341    backup_dir: &Path,
342    held: &[HeldEpoch],
343) -> Result<Option<StoreKey>> {
344    let Some(file) = WrappedFile::read(backup_dir)? else {
345        return Ok(None);
346    };
347    let held = held
348        .iter()
349        .find(|h| h.identity == file.identity_tag && h.epoch == file.epoch)
350        .ok_or_else(|| {
351            anyhow!(
352                "the backup's {WRAPPED_STORE_KEY_FILE} is sealed under epoch {} of identity {}, \
353                 which none of the keys at hand is; use keys from a device that held it",
354                file.epoch.number,
355                file.identity_tag.as_str()
356            )
357        })?;
358    file.open(&held.key).map(Some)
359}
360
361pub(super) fn replace_private_file(dir: &Path, name: &str, bytes: &[u8]) -> Result<()> {
362    create_private_dir(dir)?;
363    let temp = dir.join(format!(".{name}.{}.tmp", uuid::Uuid::new_v4().simple()));
364    if let Err(e) = write_private_file(&temp, bytes) {
365        return Err(with_temp_removed(e, &temp));
366    }
367    let target = dir.join(name);
368    if let Err(e) = fs::rename(&temp, &target) {
369        let e = anyhow::Error::from(e).context(format!("installing {}", target.display()));
370        return Err(with_temp_removed(e, &temp));
371    }
372    sync_dir(dir)
373}
374
375fn with_temp_removed(error: anyhow::Error, temp: &Path) -> anyhow::Error {
376    match remove_if_present(temp) {
377        Ok(()) => error,
378        Err(cleanup) => error.context(format!("{cleanup:#}")),
379    }
380}
381
382pub(super) fn remove_if_present(path: &Path) -> Result<()> {
383    match fs::remove_file(path) {
384        Ok(()) => Ok(()),
385        Err(e) if e.kind() == ErrorKind::NotFound => Ok(()),
386        Err(e) => Err(e).with_context(|| format!("removing {}", path.display())),
387    }
388}
389
390pub(super) fn dir_of(path: &Path) -> &Path {
391    match path.parent() {
392        Some(dir) if !dir.as_os_str().is_empty() => dir,
393        _ => Path::new("."),
394    }
395}
396
397/// The store's file, refused unless it sits in `data_dir`: a copy elsewhere
398/// keeps its key files beside it, so writing them into `data_dir` would
399/// leave `data_dir`'s wrap opening no store there.
400pub(super) fn store_file_in(store: &SqliteStore, data_dir: &Path) -> Result<PathBuf> {
401    let db = store.file_path()?.ok_or_else(|| {
402        anyhow!(
403            "the store has no file whose key files {} holds",
404            data_dir.display()
405        )
406    })?;
407    ensure!(
408        same_dir(dir_of(&db), data_dir),
409        "{} keeps its key files beside it, not in {}",
410        db.display(),
411        data_dir.display()
412    );
413    Ok(db)
414}
415
416/// True when the store's file sits in `data_dir`, so its key files are
417/// that dir's to write.
418pub fn store_in_data_dir(store: &SqliteStore, data_dir: &Path) -> bool {
419    store_file_in(store, data_dir).is_ok()
420}
421
422pub(super) fn same_dir(a: &Path, b: &Path) -> bool {
423    let resolve = |p: &Path| fs::canonicalize(p).unwrap_or_else(|_| PathBuf::from(p));
424    resolve(a) == resolve(b)
425}
426
427fn unhex_vec(text: &str) -> Result<Vec<u8>> {
428    ensure!(
429        text.len() % 2 == 0,
430        "odd-length hex in {WRAPPED_STORE_KEY_FILE}"
431    );
432    (0..text.len())
433        .step_by(2)
434        .map(|i| {
435            u8::from_str_radix(&text[i..i + 2], 16)
436                .map_err(|_| anyhow!("bad hex in {WRAPPED_STORE_KEY_FILE}"))
437        })
438        .collect()
439}