use std::sync::Arc;
use std::time::{Duration, Instant};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use tokio::io::AsyncReadExt;
use super::{RewriteKind, StoreState, admin, rewrite};
use crate::clock::Clock;
use crate::crypto::{DataKey, KdfParams, KeyId, Words};
use crate::fs::{BoxRead, RemoteFs};
use crate::model::{ContentHasher, ItemId, ItemMeta};
use crate::store::{Store, StoreError};
pub const HEARTBEAT_EVERY: Duration = Duration::from_secs(60);
#[async_trait]
pub trait EncryptionAdmin: Send + Sync {
async fn inspect(&self) -> Result<StoreState, StoreError>;
async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
async fn join(&self, words: &Words) -> Result<DataKey, StoreError>;
async fn change_words(
&self,
current: &Words,
new: &Words,
kdf: KdfParams,
) -> Result<KeyId, StoreError>;
async fn migrate(
&self,
words: &Words,
kdf: KdfParams,
clock: Arc<dyn Clock>,
) -> Result<DataKey, StoreError>;
async fn rotate(
&self,
old: &DataKey,
words: &Words,
kdf: KdfParams,
clock: Arc<dyn Clock>,
) -> Result<DataKey, StoreError>;
fn plain_store(&self) -> Box<dyn Store + '_>;
async fn remove_plain_if_empty(&self) -> Result<bool, StoreError>;
fn fs(&self) -> Option<&dyn RemoteFs> {
None
}
async fn open_rewrite(&self) -> Result<Option<OpenRewrite>, StoreError> {
Ok(None)
}
async fn resume_rewrite(
&self,
_new: &Words,
_device: Option<&DataKey>,
_old_words: Option<&Words>,
) -> Result<DataKey, StoreError> {
Err(StoreError::Backend(
"this store keeps no re-encryption session".to_owned(),
))
}
async fn abort_rewrite(&self) -> Result<(), StoreError> {
Err(StoreError::Backend(
"this store keeps no re-encryption session".to_owned(),
))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OpenRewrite {
pub kind: RewriteKind,
pub mine: bool,
pub holder: String,
pub lease_ends: DateTime<Utc>,
pub new_key: KeyId,
pub old_key: Option<KeyId>,
pub staged: usize,
pub items: usize,
}
impl OpenRewrite {
pub fn lease_ended(&self, now: DateTime<Utc>) -> bool {
self.lease_ends <= now
}
}
#[async_trait]
pub trait Rewrite: Send + Sync {
fn source(&self) -> &dyn Store;
fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError>;
async fn staged(&self, id: &ItemId) -> Result<bool, StoreError>;
async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError>;
async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError>;
async fn heartbeat(&self) -> Result<(), StoreError>;
fn heartbeat_every(&self) -> Duration {
HEARTBEAT_EVERY
}
async fn commit(&self) -> Result<(), StoreError>;
}
pub async fn run_rewrite(rewrite: &dyn Rewrite) -> Result<usize, StoreError> {
let mut alive = KeepAlive {
last: Instant::now(),
};
let source = rewrite.source();
let mut ids = source.list_ids().await?;
ids.reverse();
let mut metas = Vec::with_capacity(ids.len());
for id in &ids {
let meta = source.get_meta(id).await?;
if !rewrite.staged(&rewrite.target_id(&meta)?).await? {
let (meta, content) = source.get(id).await?;
rewrite.import(&meta, content).await?;
}
metas.push(meta);
alive.tick(rewrite).await?;
}
for meta in &metas {
verify(rewrite, meta).await?;
alive.tick(rewrite).await?;
}
rewrite.commit().await?;
Ok(metas.len())
}
struct KeepAlive {
last: Instant,
}
impl KeepAlive {
async fn tick(&mut self, rewrite: &dyn Rewrite) -> Result<(), StoreError> {
if self.last.elapsed() >= rewrite.heartbeat_every() {
rewrite.heartbeat().await?;
self.last = Instant::now();
}
Ok(())
}
}
async fn verify(rewrite: &dyn Rewrite, meta: &ItemMeta) -> Result<(), StoreError> {
let id = rewrite.target_id(meta)?;
let (_, mut content) = rewrite.read_back(&id).await?;
let mut hasher = ContentHasher::new();
let mut buf = vec![0_u8; 64 * 1024];
loop {
let n = content
.read(&mut buf)
.await
.map_err(|err| StoreError::Content(err.to_string()))?;
if n == 0 {
break;
}
hasher.update(&buf[..n]);
}
let digest = hasher.finalize();
if digest.sha256_hex() != meta.sha256 || digest.size() != meta.size {
return Err(StoreError::Corrupt {
id: id.to_string(),
reason: format!("its re-encrypted copy does not match {}", meta.id),
});
}
Ok(())
}
#[derive(Debug)]
pub struct FsEncryptionAdmin<F> {
fs: F,
}
impl<F: RemoteFs> FsEncryptionAdmin<F> {
pub fn new(fs: F) -> Self {
Self { fs }
}
}
#[async_trait]
impl<F: RemoteFs> EncryptionAdmin for FsEncryptionAdmin<F> {
async fn inspect(&self) -> Result<StoreState, StoreError> {
admin::inspect(&self.fs).await
}
async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
admin::set_up(&self.fs, words, kdf).await
}
async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
admin::fresh_start(&self.fs, words, kdf).await
}
async fn join(&self, words: &Words) -> Result<DataKey, StoreError> {
admin::join(&self.fs, words).await
}
async fn change_words(
&self,
current: &Words,
new: &Words,
kdf: KdfParams,
) -> Result<KeyId, StoreError> {
admin::change_words(&self.fs, current, new, kdf).await
}
async fn migrate(
&self,
words: &Words,
kdf: KdfParams,
clock: Arc<dyn Clock>,
) -> Result<DataKey, StoreError> {
rewrite::migrate(&self.fs, words, kdf, clock).await
}
async fn rotate(
&self,
old: &DataKey,
words: &Words,
kdf: KdfParams,
clock: Arc<dyn Clock>,
) -> Result<DataKey, StoreError> {
rewrite::rotate(&self.fs, old, words, kdf, clock).await
}
fn plain_store(&self) -> Box<dyn Store + '_> {
Box::new(admin::plain_store(&self.fs))
}
async fn remove_plain_if_empty(&self) -> Result<bool, StoreError> {
admin::remove_plain_if_empty(&self.fs).await
}
fn fs(&self) -> Option<&dyn RemoteFs> {
Some(&self.fs)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::crypto::CryptoError;
use crate::fs::LocalFs;
use crate::model::NewItem;
use crate::testing::ManualClock;
use tempfile::TempDir;
use crate::encryption::rewrite::tests::{W1, W2, quick};
fn words(text: &str) -> Words {
Words::parse(text).unwrap()
}
fn clock() -> Arc<dyn Clock> {
Arc::new(ManualClock::at("2026-09-19T15:00:00Z"))
}
async fn put(dir: &TempDir, key: Option<&DataKey>, text: &str) {
let store = crate::encryption::open_with_key(
LocalFs::new(dir.path()),
key.cloned(),
clock(),
Box::new(crate::random::StdRandom::new()),
)
.await
.unwrap();
store
.put(
NewItem::text("box"),
Box::new(std::io::Cursor::new(text.as_bytes().to_vec())),
)
.await
.unwrap();
}
#[tokio::test]
async fn the_filesystem_admin_does_what_the_functions_do() {
let dir = TempDir::new().unwrap();
let admin = FsEncryptionAdmin::new(LocalFs::new(dir.path()));
assert!(admin.fs().is_some());
assert_eq!(
admin.inspect().await.unwrap(),
StoreState::Plain { items: 0 }
);
let key = admin.set_up(&words(W1), quick()).await.unwrap();
assert_eq!(
admin.inspect().await.unwrap(),
StoreState::Encrypted {
key_id: key.key_id(),
plain_left: 0
}
);
assert_eq!(admin.join(&words(W1)).await.unwrap().key_id(), key.key_id());
let id = admin
.change_words(&words(W1), &words(W2), quick())
.await
.unwrap();
assert_eq!(id, key.key_id());
assert!(matches!(
admin.join(&words(W1)).await,
Err(StoreError::Encryption(
crate::encryption::EncryptionError::Crypto(CryptoError::WrongWords)
))
));
put(&dir, Some(&key), "one").await;
put(&dir, Some(&key), "two").await;
let new = admin
.rotate(&key, &words(W1), quick(), clock())
.await
.unwrap();
assert_ne!(new.key_id(), key.key_id());
let store = crate::encryption::open_with_key(
LocalFs::new(dir.path()),
Some(new),
clock(),
Box::new(crate::random::StdRandom::new()),
)
.await
.unwrap();
assert_eq!(store.list().await.unwrap().len(), 2);
assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 0);
assert!(!admin.remove_plain_if_empty().await.unwrap());
}
#[tokio::test]
async fn a_migration_and_a_fresh_start_go_through_the_trait() {
let migrated = TempDir::new().unwrap();
put(&migrated, None, "keep me").await;
let admin: Box<dyn EncryptionAdmin> =
Box::new(FsEncryptionAdmin::new(LocalFs::new(migrated.path())));
let key = admin.migrate(&words(W1), quick(), clock()).await.unwrap();
assert!(matches!(
admin.inspect().await.unwrap(),
StoreState::Encrypted { key_id, plain_left: 0 } if key_id == key.key_id()
));
let fresh = TempDir::new().unwrap();
put(&fresh, None, "set aside").await;
let admin = FsEncryptionAdmin::new(LocalFs::new(fresh.path()));
admin.fresh_start(&words(W1), quick()).await.unwrap();
assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 1);
}
struct Lying<'a> {
inner: &'a dyn Rewrite,
}
#[async_trait]
impl Rewrite for Lying<'_> {
fn source(&self) -> &dyn Store {
self.inner.source()
}
fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
self.inner.target_id(meta)
}
async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
self.inner.staged(id).await
}
async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
self.inner.import(meta, content).await
}
async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
let (meta, _) = self.inner.read_back(id).await?;
Ok((meta, Box::new(std::io::Cursor::new(b"altered".to_vec()))))
}
async fn heartbeat(&self) -> Result<(), StoreError> {
Ok(())
}
async fn commit(&self) -> Result<(), StoreError> {
panic!("a copy that does not match must not be committed")
}
}
struct Copying {
source: crate::store::FsStore<LocalFs>,
target: crate::store::FsStore<LocalFs>,
committed: std::sync::atomic::AtomicBool,
}
#[async_trait]
impl Rewrite for Copying {
fn source(&self) -> &dyn Store {
&self.source
}
fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
self.target.id_for(meta)
}
async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
self.target.exists(id).await
}
async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
self.target.import(meta, content).await
}
async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
self.target.get(id).await
}
async fn heartbeat(&self) -> Result<(), StoreError> {
Ok(())
}
async fn commit(&self) -> Result<(), StoreError> {
self.committed
.store(true, std::sync::atomic::Ordering::SeqCst);
Ok(())
}
}
#[tokio::test]
async fn the_engine_copies_verifies_and_commits_only_matching_copies() {
let from = TempDir::new().unwrap();
let to = TempDir::new().unwrap();
put(&from, None, "a").await;
put(&from, None, "b").await;
let rng = || Box::new(crate::random::StdRandom::new());
let copying = Copying {
source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
target: crate::store::FsStore::sealed(
LocalFs::new(to.path()),
clock(),
rng(),
crate::crypto::Sealer::new(DataKey::generate().unwrap()),
),
committed: std::sync::atomic::AtomicBool::new(false),
};
assert!(matches!(
run_rewrite(&Lying { inner: ©ing }).await,
Err(StoreError::Corrupt { reason, .. }) if reason.contains("does not match")
));
assert_eq!(run_rewrite(©ing).await.unwrap(), 2);
assert!(copying.committed.load(std::sync::atomic::Ordering::SeqCst));
assert_eq!(run_rewrite(©ing).await.unwrap(), 2);
assert_eq!(copying.target.list_ids().await.unwrap().len(), 2);
}
struct Slow<'a> {
inner: &'a Copying,
beats: std::sync::atomic::AtomicUsize,
}
#[async_trait]
impl Rewrite for Slow<'_> {
fn source(&self) -> &dyn Store {
self.inner.source()
}
fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
self.inner.target_id(meta)
}
async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
self.inner.staged(id).await
}
async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
tokio::time::sleep(Duration::from_millis(30)).await;
self.inner.import(meta, content).await
}
async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
self.inner.read_back(id).await
}
async fn heartbeat(&self) -> Result<(), StoreError> {
self.beats.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
Ok(())
}
fn heartbeat_every(&self) -> Duration {
Duration::from_millis(10)
}
async fn commit(&self) -> Result<(), StoreError> {
self.inner.commit().await
}
}
#[tokio::test]
async fn a_slow_rewrite_sends_heartbeats_as_often_as_its_store_asks() {
let from = TempDir::new().unwrap();
let to = TempDir::new().unwrap();
for text in ["a", "b", "c"] {
put(&from, None, text).await;
}
let rng = || Box::new(crate::random::StdRandom::new());
let copying = Copying {
source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
target: crate::store::FsStore::sealed(
LocalFs::new(to.path()),
clock(),
rng(),
crate::crypto::Sealer::new(DataKey::generate().unwrap()),
),
committed: std::sync::atomic::AtomicBool::new(false),
};
let slow = Slow {
inner: ©ing,
beats: std::sync::atomic::AtomicUsize::new(0),
};
assert_eq!(run_rewrite(&slow).await.unwrap(), 3);
assert!(slow.beats.load(std::sync::atomic::Ordering::SeqCst) >= 3);
}
}