use std::sync::Arc;
use super::header::encryption_dir;
use super::header_change::run_change;
use super::journal::{HeaderChangeKind, count_staged, sweep_staged};
use super::open::rewrite_started;
use super::rewrite::fold;
use super::{
EncryptionError, PLAIN_DIR, REWRITE_DIR, STOP_FILE, StoreHeader, read_header, write_stop_file,
};
use crate::clock::SystemClock;
use crate::crypto::{DataKey, KdfParams, KeyId, Words, unwrap, wrap};
use crate::fs::{FsError, RemoteFs, RemotePath, SubFs};
use crate::random::StdRandom;
use crate::store::{FsStore, Store, StoreError};
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum StoreState {
Plain {
items: usize,
},
Encrypted {
key_id: KeyId,
plain_left: usize,
},
Rewriting {
started: Option<String>,
},
Broken,
}
pub(super) enum Layout {
Rewriting {
started: Option<String>,
},
Encrypted(StoreHeader),
Broken,
Plain,
}
pub(super) async fn classify<F: RemoteFs + ?Sized>(fs: &F) -> Result<Layout, StoreError> {
if fs.stat(&RemotePath::new(REWRITE_DIR)?).await?.is_some() {
return Ok(Layout::Rewriting {
started: rewrite_started(fs).await,
});
}
let items = fs.stat(&items_path()).await?;
let items_folder = items.as_ref().is_some_and(|meta| meta.is_dir);
if fs.stat(&encryption_dir()?).await?.is_some() {
return Ok(match read_header(fs).await? {
Some(header) if !items_folder => Layout::Encrypted(header),
_ => Layout::Broken,
});
}
Ok(if items.is_some() && !items_folder {
Layout::Broken
} else {
Layout::Plain
})
}
fn items_path() -> RemotePath {
RemotePath::new(STOP_FILE).expect("a valid path")
}
fn plain_path() -> RemotePath {
RemotePath::new(PLAIN_DIR).expect("a valid path")
}
pub(super) fn plain_tmp() -> RemotePath {
RemotePath::new("tmp").expect("a valid path")
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct Leftovers {
pub plaintext_staging: usize,
pub staged_journals: usize,
}
impl Leftovers {
pub fn is_empty(&self) -> bool {
self.plaintext_staging == 0 && self.staged_journals == 0
}
pub(crate) fn plaintext(n: usize) -> Self {
Self {
plaintext_staging: n,
staged_journals: 0,
}
}
}
impl std::fmt::Display for Leftovers {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let mut parts = Vec::new();
if self.plaintext_staging > 0 {
let n = self.plaintext_staging;
let noun = if n == 1 { "leftover" } else { "leftovers" };
parts.push(format!("{n} unencrypted {noun} of cut-short uploads"));
}
if self.staged_journals > 0 {
let n = self.staged_journals;
let noun = if n == 1 { "journal" } else { "journals" };
parts.push(format!("{n} unused {noun}"));
}
if parts.is_empty() {
return f.write_str("no leftovers");
}
f.write_str(&parts.join(", "))
}
}
pub async fn leftovers<F: RemoteFs + ?Sized>(fs: &F) -> Result<Leftovers, StoreError> {
match inspect(fs).await? {
StoreState::Encrypted { .. } => count_leftovers(fs).await,
other => Err(refuse(other)),
}
}
async fn count_leftovers<F: RemoteFs + ?Sized>(fs: &F) -> Result<Leftovers, StoreError> {
let plaintext_staging = match fs.read_dir(&plain_tmp()).await {
Ok(entries) => entries.len(),
Err(FsError::NotFound(_)) => 0,
Err(err) => return Err(err.into()),
};
Ok(Leftovers {
plaintext_staging,
staged_journals: count_staged(fs).await?,
})
}
pub async fn remove_leftovers<F: RemoteFs + ?Sized>(fs: &F) -> Result<Leftovers, StoreError> {
let found = leftovers(fs).await?;
fs.remove_dir_all(&plain_tmp()).await?;
sweep_staged(fs).await?;
Ok(found)
}
pub fn plain_store<F: RemoteFs + ?Sized>(fs: &F) -> FsStore<SubFs<&F>> {
FsStore::new(
SubFs::new(fs, plain_path()),
Arc::new(SystemClock),
Box::new(StdRandom::new()),
)
}
pub async fn inspect<F: RemoteFs + ?Sized>(fs: &F) -> Result<StoreState, StoreError> {
Ok(match classify(fs).await? {
Layout::Rewriting { started } => StoreState::Rewriting { started },
Layout::Encrypted(header) => StoreState::Encrypted {
key_id: header.key_id(),
plain_left: plain_store(fs).list_ids().await?.len(),
},
Layout::Broken => StoreState::Broken,
Layout::Plain => {
let plain = FsStore::new(fs, Arc::new(SystemClock), Box::new(StdRandom::new()));
StoreState::Plain {
items: plain.list_ids().await?.len(),
}
}
})
}
pub(super) fn refuse(state: StoreState) -> StoreError {
match state {
StoreState::Plain { .. } => EncryptionError::NotEncrypted.into(),
StoreState::Encrypted { .. } => EncryptionError::AlreadyEncrypted.into(),
StoreState::Rewriting { started } => EncryptionError::Rewriting { started }.into(),
StoreState::Broken => EncryptionError::HeaderMissing.into(),
}
}
fn new_key(words: &Words, kdf: KdfParams) -> Result<(DataKey, StoreHeader), StoreError> {
let key = DataKey::generate()?;
let header = StoreHeader::new(wrap(&key, words, kdf)?);
Ok((key, header))
}
pub async fn set_up<F: RemoteFs + ?Sized>(
fs: &F,
words: &Words,
kdf: KdfParams,
) -> Result<DataKey, StoreError> {
match inspect(fs).await? {
StoreState::Plain { items: 0 } => {}
StoreState::Plain { items } => {
return Err(EncryptionError::Layout(format!(
"the store holds {items} items; encrypt it with a fresh start or by migrating"
))
.into());
}
other => return Err(refuse(other)),
}
let items = items_path();
if fs.stat(&items).await?.is_some_and(|meta| meta.is_dir)
&& !fs.read_dir(&items).await?.is_empty()
{
return Err(EncryptionError::Layout(format!(
"`{STOP_FILE}` holds files that are not items; move them away first"
))
.into());
}
let (key, header) = new_key(words, kdf)?;
run_change(fs, HeaderChangeKind::SetUp, &header, None).await?;
Ok(key)
}
pub async fn fresh_start<F: RemoteFs + ?Sized>(
fs: &F,
words: &Words,
kdf: KdfParams,
) -> Result<DataKey, StoreError> {
match inspect(fs).await? {
StoreState::Plain { .. } => {}
other => return Err(refuse(other)),
}
let (key, header) = new_key(words, kdf)?;
run_change(fs, HeaderChangeKind::FreshStart, &header, None).await?;
Ok(key)
}
pub(super) async fn stop_old_clients<F: RemoteFs + ?Sized>(fs: &F) -> Result<(), StoreError> {
clear_items(fs).await?;
if let Err(err) = write_stop_file(fs).await {
if !matches!(err, StoreError::Encryption(EncryptionError::Layout(_))) {
return Err(err);
}
clear_items(fs).await?;
write_stop_file(fs).await?;
}
fs.remove_dir_all(&plain_tmp()).await?;
Ok(())
}
async fn clear_items<F: RemoteFs + ?Sized>(fs: &F) -> Result<(), StoreError> {
let items = items_path();
if !fs.stat(&items).await?.is_some_and(|meta| meta.is_dir) {
return Ok(());
}
if fs.read_dir(&items).await?.is_empty() {
fs.remove_dir_all(&items).await?;
return Ok(());
}
move_items_to_plain(fs).await
}
pub(super) async fn restore_items<F: RemoteFs + ?Sized>(fs: &F) -> Result<(), StoreError> {
let items = items_path();
if fs.stat(&items).await?.is_some_and(|meta| !meta.is_dir) {
fs.remove_file(&items).await?;
}
let kept = plain_path().join(STOP_FILE)?;
if fs.stat(&kept).await?.is_some() {
fold(fs, &kept, &items).await?;
}
let plain = plain_path();
if fs.stat(&plain).await?.is_some() && fs.read_dir(&plain).await?.is_empty() {
fs.remove_dir_all(&plain).await?;
}
Ok(())
}
async fn move_items_to_plain<F: RemoteFs + ?Sized>(fs: &F) -> Result<(), StoreError> {
let items = items_path();
if !fs.stat(&items).await?.is_some_and(|meta| meta.is_dir) {
return Ok(());
}
let target = plain_path().join(STOP_FILE)?;
fs.create_dir_all(&plain_path()).await?;
if fs.stat(&target).await?.is_none() {
fs.rename(&items, &target).await?;
return Ok(());
}
for entry in fs.read_dir(&items).await? {
let from = items.join(&entry.name)?;
match fs.rename(&from, &target.join(&entry.name)?).await {
Ok(()) => {}
Err(FsError::AlreadyExists(_)) => fs.remove_dir_all(&from).await?,
Err(err) => return Err(err.into()),
}
}
fs.remove_dir_all(&items).await?;
Ok(())
}
pub async fn join<F: RemoteFs + ?Sized>(fs: &F, words: &Words) -> Result<DataKey, StoreError> {
match inspect(fs).await? {
StoreState::Encrypted { .. } => {}
other => return Err(refuse(other)),
}
let header = read_header(fs)
.await?
.ok_or(EncryptionError::HeaderMissing)?;
Ok(unwrap(header.wrapped(), words)?)
}
pub async fn change_words<F: RemoteFs + ?Sized>(
fs: &F,
current: &Words,
new: &Words,
kdf: KdfParams,
) -> Result<KeyId, StoreError> {
let key = join(fs, current).await?;
let old = read_header(fs)
.await?
.ok_or(EncryptionError::HeaderMissing)?;
let header = StoreHeader::new(wrap(&key, new, kdf)?);
run_change(fs, HeaderChangeKind::Words, &header, Some(&old)).await?;
Ok(key.key_id())
}
pub async fn remove_plain_if_empty<F: RemoteFs + ?Sized>(fs: &F) -> Result<bool, StoreError> {
let plain = plain_path();
if fs.stat(&plain).await?.is_none() || !plain_store(fs).list_ids().await?.is_empty() {
return Ok(false);
}
fs.remove_dir_all(&plain).await?;
Ok(true)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::crypto::{CryptoError, KDF_SALT_LEN};
use crate::encryption::open_with_key;
use crate::fs::LocalFs;
use crate::model::NewItem;
use crate::testing::ManualClock;
use tempfile::TempDir;
const W1: &str = "abacus abdomen abdominal abide abiding ability";
const W2: &str = "zoom zoom zoom zoom zoom zoom";
fn words(text: &str) -> Words {
Words::parse(text).unwrap()
}
fn quick() -> KdfParams {
KdfParams {
m_kib: 64,
t: 1,
p: 1,
salt: [4; KDF_SALT_LEN],
}
}
fn text(bytes: &[u8]) -> crate::fs::BoxRead {
Box::new(std::io::Cursor::new(bytes.to_vec()))
}
async fn seed(fs: &LocalFs, n: usize) {
let store = FsStore::new(
fs.clone(),
Arc::new(ManualClock::at("2026-09-12T09:53:11Z")),
Box::new(StdRandom::new()),
);
for i in 0..n {
store
.put(NewItem::text("box"), text(format!("old {i}").as_bytes()))
.await
.unwrap();
}
}
async fn open(fs: &LocalFs, key: &DataKey) -> Box<dyn Store> {
open_with_key(
fs.clone(),
Some(key.clone()),
Arc::new(SystemClock),
Box::new(StdRandom::new()),
)
.await
.unwrap()
}
fn is(err: StoreError, want: &EncryptionError) -> bool {
matches!(err, StoreError::Encryption(got) if got == *want)
}
#[tokio::test]
async fn inspect_tells_every_state_apart() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
assert_eq!(inspect(&fs).await.unwrap(), StoreState::Plain { items: 0 });
seed(&fs, 2).await;
assert_eq!(inspect(&fs).await.unwrap(), StoreState::Plain { items: 2 });
let other = TempDir::new().unwrap();
let fs = LocalFs::new(other.path());
write_stop_file(&fs).await.unwrap();
assert_eq!(inspect(&fs).await.unwrap(), StoreState::Broken);
std::fs::create_dir(other.path().join(".rewrite")).unwrap();
assert_eq!(
inspect(&fs).await.unwrap(),
StoreState::Rewriting { started: None }
);
}
#[tokio::test]
async fn leftovers_are_counted_and_removed_on_an_encrypted_store() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
assert!(is(
leftovers(&fs).await.unwrap_err(),
&EncryptionError::NotEncrypted
));
set_up(&fs, &words(W1), quick()).await.unwrap();
assert!(leftovers(&fs).await.unwrap().is_empty());
std::fs::create_dir_all(dir.path().join("tmp/0123")).unwrap();
std::fs::write(dir.path().join("tmp/0123/content"), "plaintext").unwrap();
std::fs::create_dir_all(dir.path().join("tmp/deleted-x")).unwrap();
std::fs::create_dir(dir.path().join(".rewrite-00ff")).unwrap();
let found = leftovers(&fs).await.unwrap();
assert_eq!((found.plaintext_staging, found.staged_journals), (2, 1));
assert_eq!(
found.to_string(),
"2 unencrypted leftovers of cut-short uploads, 1 unused journal"
);
assert_eq!(remove_leftovers(&fs).await.unwrap(), found);
assert!(leftovers(&fs).await.unwrap().is_empty());
assert!(!dir.path().join("tmp").exists());
}
#[tokio::test]
async fn parts_of_an_encrypted_layout_are_broken_never_plain() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
seed(&fs, 1).await;
std::fs::create_dir(dir.path().join("encryption")).unwrap();
assert_eq!(inspect(&fs).await.unwrap(), StoreState::Broken);
let header = crate::encryption::header::tests::quick_header(&DataKey::generate().unwrap());
std::fs::write(dir.path().join("encryption/header.json"), header.to_json()).unwrap();
assert_eq!(inspect(&fs).await.unwrap(), StoreState::Broken);
}
#[tokio::test]
async fn set_up_encrypts_an_empty_store_once() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
std::fs::create_dir(dir.path().join("items")).unwrap();
let key = set_up(&fs, &words(W1), quick()).await.unwrap();
assert_eq!(
inspect(&fs).await.unwrap(),
StoreState::Encrypted {
key_id: key.key_id(),
plain_left: 0
}
);
assert!(dir.path().join("items").is_file());
open(&fs, &key)
.await
.put(NewItem::text("box"), text(b"sealed"))
.await
.unwrap();
assert!(is(
set_up(&fs, &words(W1), quick()).await.unwrap_err(),
&EncryptionError::AlreadyEncrypted
));
}
#[tokio::test]
async fn set_up_refuses_a_store_with_items_or_other_files() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
seed(&fs, 1).await;
assert!(matches!(
set_up(&fs, &words(W1), quick()).await,
Err(StoreError::Encryption(EncryptionError::Layout(_)))
));
let other = TempDir::new().unwrap();
std::fs::create_dir_all(other.path().join("items/not-an-item")).unwrap();
let fs = LocalFs::new(other.path());
assert!(matches!(
set_up(&fs, &words(W1), quick()).await,
Err(StoreError::Encryption(EncryptionError::Layout(_)))
));
assert!(!other.path().join("encryption").exists());
}
#[tokio::test]
async fn a_fresh_start_keeps_the_old_items_in_plain() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
seed(&fs, 2).await;
let before = FsStore::new(
fs.clone(),
Arc::new(SystemClock),
Box::new(StdRandom::new()),
)
.list_ids()
.await
.unwrap();
let key = fresh_start(&fs, &words(W1), quick()).await.unwrap();
assert_eq!(
inspect(&fs).await.unwrap(),
StoreState::Encrypted {
key_id: key.key_id(),
plain_left: 2
}
);
assert_eq!(plain_store(&fs).list_ids().await.unwrap(), before);
assert!(open(&fs, &key).await.list().await.unwrap().is_empty());
assert!(!remove_plain_if_empty(&fs).await.unwrap());
let plain = plain_store(&fs);
for id in &before {
plain.delete(id).await.unwrap();
}
assert!(remove_plain_if_empty(&fs).await.unwrap());
assert!(!dir.path().join("plain").exists());
assert!(!remove_plain_if_empty(&fs).await.unwrap());
}
#[tokio::test]
async fn a_fresh_start_merges_into_an_existing_plain_folder() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
seed(&fs, 2).await;
let first = FsStore::new(
fs.clone(),
Arc::new(SystemClock),
Box::new(StdRandom::new()),
)
.list_ids()
.await
.unwrap()[0]
.clone();
std::fs::create_dir_all(dir.path().join("plain/items")).unwrap();
let copy = dir.path().join(format!("plain/items/{first}"));
std::fs::create_dir(©).unwrap();
fresh_start(&fs, &words(W1), quick()).await.unwrap();
assert_eq!(plain_store(&fs).list_ids().await.unwrap().len(), 2);
assert!(dir.path().join("items").is_file());
}
#[tokio::test]
async fn joining_needs_the_store_s_words() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
assert!(is(
join(&fs, &words(W1)).await.unwrap_err(),
&EncryptionError::NotEncrypted
));
let key = set_up(&fs, &words(W1), quick()).await.unwrap();
assert_eq!(
join(&fs, &words(W1)).await.unwrap().as_bytes(),
key.as_bytes()
);
assert!(is(
join(&fs, &words(W2)).await.unwrap_err(),
&EncryptionError::Crypto(CryptoError::WrongWords)
));
}
#[tokio::test]
async fn new_words_keep_the_key_and_rewrite_no_item() {
let dir = TempDir::new().unwrap();
let fs = LocalFs::new(dir.path());
let key = set_up(&fs, &words(W1), quick()).await.unwrap();
let item = open(&fs, &key)
.await
.put(NewItem::text("box"), text(b"kept"))
.await
.unwrap()
.meta;
let content = dir.path().join(format!("v2/items/{}/content", item.id));
let before = std::fs::read(&content).unwrap();
assert!(is(
change_words(&fs, &words(W2), &words(W2), quick())
.await
.unwrap_err(),
&EncryptionError::Crypto(CryptoError::WrongWords)
));
let id = change_words(&fs, &words(W1), &words(W2), quick())
.await
.unwrap();
assert_eq!(id, key.key_id());
assert_eq!(
join(&fs, &words(W2)).await.unwrap().as_bytes(),
key.as_bytes()
);
assert!(join(&fs, &words(W1)).await.is_err());
assert_eq!(std::fs::read(&content).unwrap(), before);
assert_eq!(open(&fs, &key).await.list().await.unwrap(), vec![item]);
}
}