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
30pub 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 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
77pub fn write_store_key(dir: &Path, name: &str, key: &StoreKey, device: &DeviceKeys) -> Result<()> {
80 write_store_key_to(dir, name, key, &[device])
81}
82
83pub(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
106pub 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
127pub 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 NoIdentity,
262}
263
264pub 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
308pub 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
337pub 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
397pub(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
416pub 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}