1use std::sync::Arc;
11use std::time::{Duration, Instant};
12
13use async_trait::async_trait;
14use chrono::{DateTime, Utc};
15use tokio::io::AsyncReadExt;
16
17use super::{RewriteKind, StoreState, admin, rewrite};
18use crate::clock::Clock;
19use crate::crypto::{DataKey, KdfParams, KeyId, Words};
20use crate::fs::{BoxRead, RemoteFs};
21use crate::model::{ContentHasher, ItemId, ItemMeta};
22use crate::store::{Store, StoreError};
23
24pub const HEARTBEAT_EVERY: Duration = Duration::from_secs(60);
27
28#[async_trait]
30pub trait EncryptionAdmin: Send + Sync {
31 async fn inspect(&self) -> Result<StoreState, StoreError>;
33
34 async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
37
38 async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
41
42 async fn join(&self, words: &Words) -> Result<DataKey, StoreError>;
44
45 async fn change_words(
48 &self,
49 current: &Words,
50 new: &Words,
51 kdf: KdfParams,
52 ) -> Result<KeyId, StoreError>;
53
54 async fn migrate(
57 &self,
58 words: &Words,
59 kdf: KdfParams,
60 clock: Arc<dyn Clock>,
61 ) -> Result<DataKey, StoreError>;
62
63 async fn rotate(
66 &self,
67 old: &DataKey,
68 words: &Words,
69 kdf: KdfParams,
70 clock: Arc<dyn Clock>,
71 ) -> Result<DataKey, StoreError>;
72
73 fn plain_store(&self) -> Box<dyn Store + '_>;
75
76 async fn remove_plain_if_empty(&self) -> Result<bool, StoreError>;
79
80 fn fs(&self) -> Option<&dyn RemoteFs> {
84 None
85 }
86
87 async fn open_rewrite(&self) -> Result<Option<OpenRewrite>, StoreError> {
91 Ok(None)
92 }
93
94 async fn resume_rewrite(
100 &self,
101 _new: &Words,
102 _device: Option<&DataKey>,
103 _old_words: Option<&Words>,
104 ) -> Result<DataKey, StoreError> {
105 Err(StoreError::Backend(
106 "this store keeps no re-encryption session".to_owned(),
107 ))
108 }
109
110 async fn abort_rewrite(&self) -> Result<(), StoreError> {
114 Err(StoreError::Backend(
115 "this store keeps no re-encryption session".to_owned(),
116 ))
117 }
118}
119
120#[derive(Debug, Clone, PartialEq, Eq)]
122pub struct OpenRewrite {
123 pub kind: RewriteKind,
125 pub mine: bool,
127 pub holder: String,
129 pub lease_ends: DateTime<Utc>,
132 pub new_key: KeyId,
134 pub old_key: Option<KeyId>,
137 pub staged: usize,
139 pub items: usize,
141}
142
143impl OpenRewrite {
144 pub fn lease_ended(&self, now: DateTime<Utc>) -> bool {
146 self.lease_ends <= now
147 }
148}
149
150#[async_trait]
154pub trait Rewrite: Send + Sync {
155 fn source(&self) -> &dyn Store;
157
158 fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError>;
164
165 async fn staged(&self, id: &ItemId) -> Result<bool, StoreError>;
168
169 async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError>;
172
173 async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError>;
175
176 async fn heartbeat(&self) -> Result<(), StoreError>;
178
179 fn heartbeat_every(&self) -> Duration {
181 HEARTBEAT_EVERY
182 }
183
184 async fn commit(&self) -> Result<(), StoreError>;
186}
187
188pub async fn run_rewrite(rewrite: &dyn Rewrite) -> Result<usize, StoreError> {
198 let mut alive = KeepAlive {
199 last: Instant::now(),
200 };
201 let source = rewrite.source();
202 let mut ids = source.list_ids().await?;
203 ids.reverse();
204 let mut metas = Vec::with_capacity(ids.len());
205 for id in &ids {
206 let meta = source.get_meta(id).await?;
207 if !rewrite.staged(&rewrite.target_id(&meta)?).await? {
208 let (meta, content) = source.get(id).await?;
209 rewrite.import(&meta, content).await?;
210 }
211 metas.push(meta);
212 alive.tick(rewrite).await?;
213 }
214 for meta in &metas {
215 verify(rewrite, meta).await?;
216 alive.tick(rewrite).await?;
217 }
218 rewrite.commit().await?;
219 Ok(metas.len())
220}
221
222struct KeepAlive {
224 last: Instant,
225}
226
227impl KeepAlive {
228 async fn tick(&mut self, rewrite: &dyn Rewrite) -> Result<(), StoreError> {
229 if self.last.elapsed() >= rewrite.heartbeat_every() {
230 rewrite.heartbeat().await?;
231 self.last = Instant::now();
232 }
233 Ok(())
234 }
235}
236
237async fn verify(rewrite: &dyn Rewrite, meta: &ItemMeta) -> Result<(), StoreError> {
240 let id = rewrite.target_id(meta)?;
241 let (_, mut content) = rewrite.read_back(&id).await?;
242 let mut hasher = ContentHasher::new();
243 let mut buf = vec![0_u8; 64 * 1024];
244 loop {
245 let n = content
246 .read(&mut buf)
247 .await
248 .map_err(|err| StoreError::Content(err.to_string()))?;
249 if n == 0 {
250 break;
251 }
252 hasher.update(&buf[..n]);
253 }
254 let digest = hasher.finalize();
255 if digest.sha256_hex() != meta.sha256 || digest.size() != meta.size {
256 return Err(StoreError::Corrupt {
257 id: id.to_string(),
258 reason: format!("its re-encrypted copy does not match {}", meta.id),
259 });
260 }
261 Ok(())
262}
263
264#[derive(Debug)]
266pub struct FsEncryptionAdmin<F> {
267 fs: F,
268}
269
270impl<F: RemoteFs> FsEncryptionAdmin<F> {
271 pub fn new(fs: F) -> Self {
273 Self { fs }
274 }
275}
276
277#[async_trait]
278impl<F: RemoteFs> EncryptionAdmin for FsEncryptionAdmin<F> {
279 async fn inspect(&self) -> Result<StoreState, StoreError> {
280 admin::inspect(&self.fs).await
281 }
282
283 async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
284 admin::set_up(&self.fs, words, kdf).await
285 }
286
287 async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
288 admin::fresh_start(&self.fs, words, kdf).await
289 }
290
291 async fn join(&self, words: &Words) -> Result<DataKey, StoreError> {
292 admin::join(&self.fs, words).await
293 }
294
295 async fn change_words(
296 &self,
297 current: &Words,
298 new: &Words,
299 kdf: KdfParams,
300 ) -> Result<KeyId, StoreError> {
301 admin::change_words(&self.fs, current, new, kdf).await
302 }
303
304 async fn migrate(
305 &self,
306 words: &Words,
307 kdf: KdfParams,
308 clock: Arc<dyn Clock>,
309 ) -> Result<DataKey, StoreError> {
310 rewrite::migrate(&self.fs, words, kdf, clock).await
311 }
312
313 async fn rotate(
314 &self,
315 old: &DataKey,
316 words: &Words,
317 kdf: KdfParams,
318 clock: Arc<dyn Clock>,
319 ) -> Result<DataKey, StoreError> {
320 rewrite::rotate(&self.fs, old, words, kdf, clock).await
321 }
322
323 fn plain_store(&self) -> Box<dyn Store + '_> {
324 Box::new(admin::plain_store(&self.fs))
325 }
326
327 async fn remove_plain_if_empty(&self) -> Result<bool, StoreError> {
328 admin::remove_plain_if_empty(&self.fs).await
329 }
330
331 fn fs(&self) -> Option<&dyn RemoteFs> {
332 Some(&self.fs)
333 }
334}
335
336#[cfg(test)]
337mod tests {
338 use super::*;
339 use crate::crypto::CryptoError;
340 use crate::fs::LocalFs;
341 use crate::model::NewItem;
342 use crate::testing::ManualClock;
343 use tempfile::TempDir;
344
345 use crate::encryption::rewrite::tests::{W1, W2, quick};
346
347 fn words(text: &str) -> Words {
348 Words::parse(text).unwrap()
349 }
350
351 fn clock() -> Arc<dyn Clock> {
352 Arc::new(ManualClock::at("2026-09-19T15:00:00Z"))
353 }
354
355 async fn put(dir: &TempDir, key: Option<&DataKey>, text: &str) {
356 let store = crate::encryption::open_with_key(
357 LocalFs::new(dir.path()),
358 key.cloned(),
359 clock(),
360 Box::new(crate::random::StdRandom::new()),
361 )
362 .await
363 .unwrap();
364 store
365 .put(
366 NewItem::text("box"),
367 Box::new(std::io::Cursor::new(text.as_bytes().to_vec())),
368 )
369 .await
370 .unwrap();
371 }
372
373 #[tokio::test]
374 async fn the_filesystem_admin_does_what_the_functions_do() {
375 let dir = TempDir::new().unwrap();
376 let admin = FsEncryptionAdmin::new(LocalFs::new(dir.path()));
377 assert!(admin.fs().is_some());
378 assert_eq!(
379 admin.inspect().await.unwrap(),
380 StoreState::Plain { items: 0 }
381 );
382
383 let key = admin.set_up(&words(W1), quick()).await.unwrap();
384 assert_eq!(
385 admin.inspect().await.unwrap(),
386 StoreState::Encrypted {
387 key_id: key.key_id(),
388 plain_left: 0
389 }
390 );
391 assert_eq!(admin.join(&words(W1)).await.unwrap().key_id(), key.key_id());
392 let id = admin
393 .change_words(&words(W1), &words(W2), quick())
394 .await
395 .unwrap();
396 assert_eq!(id, key.key_id());
397 assert!(matches!(
398 admin.join(&words(W1)).await,
399 Err(StoreError::Encryption(
400 crate::encryption::EncryptionError::Crypto(CryptoError::WrongWords)
401 ))
402 ));
403
404 put(&dir, Some(&key), "one").await;
405 put(&dir, Some(&key), "two").await;
406 let new = admin
407 .rotate(&key, &words(W1), quick(), clock())
408 .await
409 .unwrap();
410 assert_ne!(new.key_id(), key.key_id());
411 let store = crate::encryption::open_with_key(
412 LocalFs::new(dir.path()),
413 Some(new),
414 clock(),
415 Box::new(crate::random::StdRandom::new()),
416 )
417 .await
418 .unwrap();
419 assert_eq!(store.list().await.unwrap().len(), 2);
420 assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 0);
421 assert!(!admin.remove_plain_if_empty().await.unwrap());
422 }
423
424 #[tokio::test]
425 async fn a_migration_and_a_fresh_start_go_through_the_trait() {
426 let migrated = TempDir::new().unwrap();
427 put(&migrated, None, "keep me").await;
428 let admin: Box<dyn EncryptionAdmin> =
429 Box::new(FsEncryptionAdmin::new(LocalFs::new(migrated.path())));
430 let key = admin.migrate(&words(W1), quick(), clock()).await.unwrap();
431 assert!(matches!(
432 admin.inspect().await.unwrap(),
433 StoreState::Encrypted { key_id, plain_left: 0 } if key_id == key.key_id()
434 ));
435
436 let fresh = TempDir::new().unwrap();
437 put(&fresh, None, "set aside").await;
438 let admin = FsEncryptionAdmin::new(LocalFs::new(fresh.path()));
439 admin.fresh_start(&words(W1), quick()).await.unwrap();
440 assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 1);
441 }
442
443 struct Lying<'a> {
445 inner: &'a dyn Rewrite,
446 }
447
448 #[async_trait]
449 impl Rewrite for Lying<'_> {
450 fn source(&self) -> &dyn Store {
451 self.inner.source()
452 }
453 fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
454 self.inner.target_id(meta)
455 }
456 async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
457 self.inner.staged(id).await
458 }
459 async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
460 self.inner.import(meta, content).await
461 }
462 async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
463 let (meta, _) = self.inner.read_back(id).await?;
464 Ok((meta, Box::new(std::io::Cursor::new(b"altered".to_vec()))))
465 }
466 async fn heartbeat(&self) -> Result<(), StoreError> {
467 Ok(())
468 }
469 async fn commit(&self) -> Result<(), StoreError> {
470 panic!("a copy that does not match must not be committed")
471 }
472 }
473
474 struct Copying {
477 source: crate::store::FsStore<LocalFs>,
478 target: crate::store::FsStore<LocalFs>,
479 committed: std::sync::atomic::AtomicBool,
480 }
481
482 #[async_trait]
483 impl Rewrite for Copying {
484 fn source(&self) -> &dyn Store {
485 &self.source
486 }
487 fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
488 self.target.id_for(meta)
489 }
490 async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
491 self.target.exists(id).await
492 }
493 async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
494 self.target.import(meta, content).await
495 }
496 async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
497 self.target.get(id).await
498 }
499 async fn heartbeat(&self) -> Result<(), StoreError> {
500 Ok(())
501 }
502 async fn commit(&self) -> Result<(), StoreError> {
503 self.committed
504 .store(true, std::sync::atomic::Ordering::SeqCst);
505 Ok(())
506 }
507 }
508
509 #[tokio::test]
510 async fn the_engine_copies_verifies_and_commits_only_matching_copies() {
511 let from = TempDir::new().unwrap();
512 let to = TempDir::new().unwrap();
513 put(&from, None, "a").await;
514 put(&from, None, "b").await;
515 let rng = || Box::new(crate::random::StdRandom::new());
516 let copying = Copying {
517 source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
518 target: crate::store::FsStore::sealed(
519 LocalFs::new(to.path()),
520 clock(),
521 rng(),
522 crate::crypto::Sealer::new(DataKey::generate().unwrap()),
523 ),
524 committed: std::sync::atomic::AtomicBool::new(false),
525 };
526 assert!(matches!(
527 run_rewrite(&Lying { inner: ©ing }).await,
528 Err(StoreError::Corrupt { reason, .. }) if reason.contains("does not match")
529 ));
530 assert_eq!(run_rewrite(©ing).await.unwrap(), 2);
531 assert!(copying.committed.load(std::sync::atomic::Ordering::SeqCst));
532 assert_eq!(run_rewrite(©ing).await.unwrap(), 2);
534 assert_eq!(copying.target.list_ids().await.unwrap().len(), 2);
535 }
536
537 struct Slow<'a> {
540 inner: &'a Copying,
541 beats: std::sync::atomic::AtomicUsize,
542 }
543
544 #[async_trait]
545 impl Rewrite for Slow<'_> {
546 fn source(&self) -> &dyn Store {
547 self.inner.source()
548 }
549 fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
550 self.inner.target_id(meta)
551 }
552 async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
553 self.inner.staged(id).await
554 }
555 async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
556 tokio::time::sleep(Duration::from_millis(30)).await;
557 self.inner.import(meta, content).await
558 }
559 async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
560 self.inner.read_back(id).await
561 }
562 async fn heartbeat(&self) -> Result<(), StoreError> {
563 self.beats.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
564 Ok(())
565 }
566 fn heartbeat_every(&self) -> Duration {
567 Duration::from_millis(10)
568 }
569 async fn commit(&self) -> Result<(), StoreError> {
570 self.inner.commit().await
571 }
572 }
573
574 #[tokio::test]
575 async fn a_slow_rewrite_sends_heartbeats_as_often_as_its_store_asks() {
576 let from = TempDir::new().unwrap();
577 let to = TempDir::new().unwrap();
578 for text in ["a", "b", "c"] {
579 put(&from, None, text).await;
580 }
581 let rng = || Box::new(crate::random::StdRandom::new());
582 let copying = Copying {
583 source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
584 target: crate::store::FsStore::sealed(
585 LocalFs::new(to.path()),
586 clock(),
587 rng(),
588 crate::crypto::Sealer::new(DataKey::generate().unwrap()),
589 ),
590 committed: std::sync::atomic::AtomicBool::new(false),
591 };
592 let slow = Slow {
593 inner: ©ing,
594 beats: std::sync::atomic::AtomicUsize::new(0),
595 };
596 assert_eq!(run_rewrite(&slow).await.unwrap(), 3);
597 assert!(slow.beats.load(std::sync::atomic::Ordering::SeqCst) >= 3);
598 }
599}