1use std::sync::Arc;
17use std::time::Duration;
18
19use async_trait::async_trait;
20use chrono::{DateTime, Utc};
21use passalong_core::clock::Clock;
22use passalong_core::crypto::{DataKey, KdfParams, KeyId, Sealer, Words, unwrap, wrap};
23use passalong_core::encryption::{
24 EncryptionAdmin, EncryptionError, HEARTBEAT_EVERY, OpenRewrite, Rewrite, RewriteKind,
25 StoreHeader, StoreState, run_rewrite,
26};
27use passalong_core::fs::BoxRead;
28use passalong_core::model::{ItemId, ItemMeta};
29use passalong_core::store::{Store, StoreError};
30use reqwest::header::CONTENT_TYPE;
31
32use crate::api::{self, EncryptionState};
33use crate::client::{Client, json};
34use crate::error::{Code, HttpsError};
35use crate::store::{HttpStore, Partition, store_error};
36
37pub struct HttpEncryptionAdmin {
39 client: Arc<Client>,
40 clock: Arc<dyn Clock>,
41}
42
43impl std::fmt::Debug for HttpEncryptionAdmin {
44 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45 f.debug_struct("HttpEncryptionAdmin")
46 .field("client", &self.client)
47 .finish_non_exhaustive()
48 }
49}
50
51fn refuse(state: StoreState) -> StoreError {
54 match state {
55 StoreState::Plain { .. } => EncryptionError::NotEncrypted.into(),
56 StoreState::Encrypted { .. } => EncryptionError::AlreadyEncrypted.into(),
57 StoreState::Rewriting { started } => EncryptionError::Rewriting { started }.into(),
58 _ => EncryptionError::HeaderMissing.into(),
59 }
60}
61
62fn new_key(words: &Words, kdf: KdfParams) -> Result<(DataKey, StoreHeader), StoreError> {
63 let key = DataKey::generate()?;
64 let header = StoreHeader::new(wrap(&key, words, kdf)?);
65 Ok((key, header))
66}
67
68fn header_json(header: &StoreHeader) -> String {
70 String::from_utf8_lossy(&header.to_json())
71 .trim_end()
72 .to_owned()
73}
74
75impl HttpEncryptionAdmin {
76 pub fn new(client: Arc<Client>, clock: Arc<dyn Clock>) -> Self {
78 Self { client, clock }
79 }
80
81 async fn workspace(&self) -> Result<api::Workspace, StoreError> {
82 self.client.workspace().await.map_err(store_error)
83 }
84
85 fn state_of(
86 &self,
87 workspace: &api::Workspace,
88 plain_left: usize,
89 ) -> Result<StoreState, StoreError> {
90 Ok(match workspace.encryption.state {
91 EncryptionState::Plaintext => StoreState::Plain {
92 items: usize::try_from(workspace.item_count).unwrap_or(usize::MAX),
93 },
94 EncryptionState::Sealed => StoreState::Encrypted {
95 key_id: key_id_of(&workspace.encryption)?,
96 plain_left,
97 },
98 EncryptionState::Rewriting => StoreState::Rewriting { started: None },
99 _ => {
100 return Err(StoreError::Backend(
101 "the server reports an encryption state this version of passalong does not know"
102 .to_owned(),
103 ));
104 }
105 })
106 }
107
108 async fn send_json(
109 &self,
110 what: &str,
111 method: reqwest::Method,
112 path: &str,
113 body: String,
114 ) -> Result<(), StoreError> {
115 let url = self.client.url(path);
116 self.client
117 .send(what, |http| {
118 http.request(method.clone(), &url)
119 .header(CONTENT_TYPE, "application/json")
120 .body(body.clone())
121 })
122 .await
123 .map_err(store_error)?;
124 Ok(())
125 }
126
127 async fn session_call(
129 &self,
130 what: &str,
131 path: &str,
132 body: Option<String>,
133 ) -> Result<api::RewriteSession, HttpsError> {
134 session_call(&self.client, what, path, body).await
135 }
136
137 async fn rewrite(
141 &self,
142 kind: RewriteKind,
143 old: Option<&DataKey>,
144 words: &Words,
145 kdf: KdfParams,
146 ) -> Result<DataKey, StoreError> {
147 for attempt in 0..2 {
148 let (key, header) = new_key(words, kdf)?;
149 check_header(&header, words, &key)?;
152 let body = format!(
153 "{{\"kind\":\"{}\",\"expectedKeyId\":{},\"newKeyId\":\"{}\",\"newHeader\":{}}}",
154 match kind {
155 RewriteKind::Migrate => "migrate",
156 _ => "rotate",
157 },
158 match old {
159 Some(old) => format!("\"{}\"", old.key_id()),
160 None => "null".to_owned(),
161 },
162 key.key_id(),
163 header_json(&header)
164 );
165 match self
166 .session_call("beginRewrite", "/rewrite", Some(body))
167 .await
168 {
169 Ok(session) => {
170 self.drive(&session, old.cloned(), &key).await?;
171 return Ok(key);
172 }
173 Err(err) if err.code() == Some(Code::RewriteEnded) && attempt == 0 => {
174 tracing::info!(
175 "the server ended a rewrite under that key; beginning again under a new one"
176 );
177 }
178 Err(err) => return Err(store_error(err)),
179 }
180 }
181 Err(StoreError::Backend(
182 "the server ended the rewrite twice; nothing was changed".to_owned(),
183 ))
184 }
185
186 async fn drive(
189 &self,
190 session: &api::RewriteSession,
191 old: Option<DataKey>,
192 key: &DataKey,
193 ) -> Result<(), StoreError> {
194 let rewrite = HttpRewrite {
195 admin: self,
196 source: HttpStore::new(
197 self.client.clone(),
198 old.map(Sealer::new),
199 self.clock.clone(),
200 ),
201 target: HttpStore::in_partition(
202 self.client.clone(),
203 Some(Sealer::new(key.clone())),
204 self.clock.clone(),
205 Partition::Staged,
206 ),
207 new_key: key.key_id(),
208 };
209 let lease = keep_lease(self.client.clone(), heartbeat_every(session, Utc::now()));
210 let result = run_rewrite(&rewrite).await;
211 lease.abort();
212 let items = result?;
213 tracing::info!(items, key = %key.key_id().short(), "items re-encrypted, verified, and committed");
214 Ok(())
215 }
216
217 async fn open_session(&self) -> Result<(api::Workspace, api::RewriteSession), StoreError> {
219 let mut workspace = self.workspace().await?;
220 match workspace.encryption.rewrite.take() {
221 Some(session) => Ok((workspace, session)),
222 None => Err(StoreError::Backend(
223 "no re-encryption is open on the server".to_owned(),
224 )),
225 }
226 }
227
228 async fn hold(&self, session: &api::RewriteSession) -> Result<api::RewriteSession, StoreError> {
231 let (what, path) = if session.holder == self.client.key().id() {
232 ("heartbeatRewrite", "/rewrite/heartbeat")
233 } else {
234 ("takeOverRewrite", "/rewrite/take-over")
235 };
236 self.session_call(what, path, None)
237 .await
238 .map_err(store_error)
239 }
240}
241
242async fn session_call(
245 client: &Client,
246 what: &str,
247 path: &str,
248 body: Option<String>,
249) -> Result<api::RewriteSession, HttpsError> {
250 let url = client.url(path);
251 let response = client
252 .send(what, |http| {
253 let request = http.post(&url);
254 match &body {
255 Some(body) => request
256 .header(CONTENT_TYPE, "application/json")
257 .body(body.clone()),
258 None => request,
259 }
260 })
261 .await?;
262 json(response).await
263}
264
265fn keep_lease(client: Arc<Client>, every: Duration) -> tokio::task::JoinHandle<()> {
268 tokio::spawn(async move {
269 loop {
270 tokio::time::sleep(every).await;
271 match session_call(&client, "heartbeatRewrite", "/rewrite/heartbeat", None).await {
272 Ok(_) => {}
273 Err(err) if err.code() == Some(Code::LeaseHeld) => return,
275 Err(err) => tracing::debug!(error = %err, "renewing the rewrite's lease failed"),
276 }
277 }
278 })
279}
280
281fn heartbeat_every(session: &api::RewriteSession, now: DateTime<Utc>) -> Duration {
284 let lease = DateTime::parse_from_rfc3339(&session.lease_expires_at)
285 .ok()
286 .and_then(|ends| (ends.with_timezone(&Utc) - now).to_std().ok())
287 .unwrap_or(HEARTBEAT_EVERY);
288 (lease / 3).clamp(Duration::from_millis(200), HEARTBEAT_EVERY)
289}
290
291fn check_header(header: &StoreHeader, words: &Words, key: &DataKey) -> Result<(), StoreError> {
293 let opened = unwrap(header.wrapped(), words)?;
294 if opened.key_id() != key.key_id() {
295 return Err(EncryptionError::Header(format!(
296 "the new header opens key {}, not {}; nothing was changed",
297 opened.key_id().short(),
298 key.key_id().short()
299 ))
300 .into());
301 }
302 Ok(())
303}
304
305fn rewrite_kind(session: &api::RewriteSession) -> Result<RewriteKind, StoreError> {
306 match session.kind.as_str() {
307 "migrate" => Ok(RewriteKind::Migrate),
308 "rotate" => Ok(RewriteKind::Rotate),
309 other => Err(StoreError::Backend(format!(
310 "the server reports a rewrite of kind `{other}`, which this version of passalong does not know"
311 ))),
312 }
313}
314
315struct HttpRewrite<'a> {
317 admin: &'a HttpEncryptionAdmin,
318 source: HttpStore,
319 target: HttpStore,
320 new_key: KeyId,
321}
322
323#[async_trait]
324impl Rewrite for HttpRewrite<'_> {
325 fn source(&self) -> &dyn Store {
326 &self.source
327 }
328
329 fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
330 self.target.id_for(meta)
331 }
332
333 async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
334 self.target.exists(id).await
335 }
336
337 async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
338 self.target.import(meta, content).await
339 }
340
341 async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
342 self.target.get(id).await
343 }
344
345 async fn heartbeat(&self) -> Result<(), StoreError> {
346 Ok(())
348 }
349
350 async fn commit(&self) -> Result<(), StoreError> {
351 self.admin
352 .send_json(
353 "commitRewrite",
354 reqwest::Method::POST,
355 "/rewrite/commit",
356 format!("{{\"newKeyId\":\"{}\"}}", self.new_key),
357 )
358 .await
359 }
360}
361
362fn key_id_of(encryption: &api::Encryption) -> Result<KeyId, StoreError> {
364 let id = encryption.key_id.as_deref().unwrap_or_default();
365 KeyId::parse(id).map_err(|_| {
366 StoreError::Backend(format!(
367 "the server names the key id `{id}`, which is not one"
368 ))
369 })
370}
371
372#[async_trait]
373impl EncryptionAdmin for HttpEncryptionAdmin {
374 async fn inspect(&self) -> Result<StoreState, StoreError> {
375 let workspace = self.workspace().await?;
376 let plain_left = if workspace.encryption.state == EncryptionState::Sealed {
377 self.plain_store().list_ids().await?.len()
378 } else {
379 0
380 };
381 self.state_of(&workspace, plain_left)
382 }
383
384 async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
385 match self.inspect().await? {
386 StoreState::Plain { items: 0 } => {}
387 StoreState::Plain { items } => {
388 return Err(EncryptionError::Layout(format!(
389 "the store holds {items} items; encrypt it with a fresh start or by migrating"
390 ))
391 .into());
392 }
393 other => return Err(refuse(other)),
394 }
395 let (key, header) = new_key(words, kdf)?;
396 let body = format!(
397 "{{\"header\":{},\"keyId\":\"{}\"}}",
398 header_json(&header),
399 key.key_id()
400 );
401 self.send_json(
402 "enableEncryption",
403 reqwest::Method::PUT,
404 "/workspace/encryption",
405 body,
406 )
407 .await?;
408 Ok(key)
409 }
410
411 async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
412 match self.inspect().await? {
413 StoreState::Plain { .. } => {}
414 other => return Err(refuse(other)),
415 }
416 let (key, header) = new_key(words, kdf)?;
417 let body = format!(
418 "{{\"header\":{},\"keyId\":\"{}\"}}",
419 header_json(&header),
420 key.key_id()
421 );
422 self.send_json(
423 "freshStart",
424 reqwest::Method::POST,
425 "/workspace/encryption/fresh-start",
426 body,
427 )
428 .await?;
429 Ok(key)
430 }
431
432 async fn join(&self, words: &Words) -> Result<DataKey, StoreError> {
433 let workspace = self.workspace().await?;
434 let state = self.state_of(&workspace, 0)?;
435 let StoreState::Encrypted { key_id, .. } = state else {
436 return Err(refuse(state));
437 };
438 let raw = workspace
439 .encryption
440 .header
441 .as_ref()
442 .ok_or(EncryptionError::HeaderMissing)?;
443 let header = StoreHeader::parse(raw.get().as_bytes())?;
444 if header.key_id() != key_id {
445 return Err(EncryptionError::Header(format!(
446 "the header is for key {}, but the server names key {}",
447 header.key_id().short(),
448 key_id.short()
449 ))
450 .into());
451 }
452 Ok(unwrap(header.wrapped(), words)?)
453 }
454
455 async fn change_words(
456 &self,
457 current: &Words,
458 new: &Words,
459 kdf: KdfParams,
460 ) -> Result<KeyId, StoreError> {
461 let key = self.join(current).await?;
462 let header = StoreHeader::new(wrap(&key, new, kdf)?);
463 let body = format!(
464 "{{\"expectedKeyId\":\"{}\",\"header\":{}}}",
465 key.key_id(),
466 header_json(&header)
467 );
468 self.send_json(
469 "replaceHeader",
470 reqwest::Method::PUT,
471 "/workspace/encryption/header",
472 body,
473 )
474 .await?;
475 Ok(key.key_id())
476 }
477
478 async fn migrate(
479 &self,
480 words: &Words,
481 kdf: KdfParams,
482 _clock: Arc<dyn Clock>,
483 ) -> Result<DataKey, StoreError> {
484 match self.inspect().await? {
485 StoreState::Plain { .. } => {}
486 other => return Err(refuse(other)),
487 }
488 self.rewrite(RewriteKind::Migrate, None, words, kdf).await
489 }
490
491 async fn rotate(
492 &self,
493 old: &DataKey,
494 words: &Words,
495 kdf: KdfParams,
496 _clock: Arc<dyn Clock>,
497 ) -> Result<DataKey, StoreError> {
498 match self.inspect().await? {
499 StoreState::Encrypted { key_id, .. } if key_id == old.key_id() => {}
500 StoreState::Encrypted { key_id, .. } => {
501 return Err(EncryptionError::KeyMismatch {
502 device: old.key_id().short(),
503 store: key_id.short(),
504 }
505 .into());
506 }
507 StoreState::Plain { .. } => return Err(EncryptionError::NotEncrypted.into()),
508 other => return Err(refuse(other)),
509 }
510 self.rewrite(RewriteKind::Rotate, Some(old), words, kdf)
511 .await
512 }
513
514 async fn open_rewrite(&self) -> Result<Option<OpenRewrite>, StoreError> {
515 let workspace = self.workspace().await?;
516 let Some(session) = &workspace.encryption.rewrite else {
517 return Ok(None);
518 };
519 let lease_ends = DateTime::parse_from_rfc3339(&session.lease_expires_at)
520 .map_err(|err| {
521 StoreError::Backend(format!(
522 "the server's leaseExpiresAt `{}` is not a time: {err}",
523 session.lease_expires_at
524 ))
525 })?
526 .with_timezone(&Utc);
527 let new_key = KeyId::parse(&session.new_key_id).map_err(|_| {
528 StoreError::Backend(format!(
529 "the server names the key id `{}`, which is not one",
530 session.new_key_id
531 ))
532 })?;
533 let kind = rewrite_kind(session)?;
534 let old_key = match kind {
535 RewriteKind::Migrate => None,
536 _ => Some(key_id_of(&workspace.encryption)?),
537 };
538 Ok(Some(OpenRewrite {
539 kind,
540 mine: session.holder == self.client.key().id(),
541 holder: session.holder.clone(),
542 lease_ends,
543 new_key,
544 old_key,
545 staged: session.staged_ids.len(),
546 items: usize::try_from(session.source_items).unwrap_or(usize::MAX),
547 }))
548 }
549
550 async fn resume_rewrite(
551 &self,
552 new: &Words,
553 device: Option<&DataKey>,
554 old_words: Option<&Words>,
555 ) -> Result<DataKey, StoreError> {
556 let (workspace, session) = self.open_session().await?;
557 let raw = session.new_header.as_ref().ok_or_else(|| {
558 StoreError::Backend(
559 "the server does not give the rewrite's new header; it needs a passalong-server whose rewrite sessions carry newHeader".to_owned(),
560 )
561 })?;
562 let header = StoreHeader::parse(raw.get().as_bytes())?;
563 let key = unwrap(header.wrapped(), new)?;
564 if key.key_id().to_string() != session.new_key_id {
565 return Err(EncryptionError::Header(format!(
566 "the rewrite's header opens key {}, but the server names key {}",
567 key.key_id().short(),
568 session.new_key_id
569 ))
570 .into());
571 }
572 let old = match rewrite_kind(&session)? {
573 RewriteKind::Migrate => None,
574 _ => {
575 let old_id = key_id_of(&workspace.encryption)?;
576 match (device, old_words) {
577 (Some(device), _) if device.key_id() == old_id => Some(device.clone()),
578 (_, Some(words)) => {
579 let raw = workspace
580 .encryption
581 .header
582 .as_ref()
583 .ok_or(EncryptionError::HeaderMissing)?;
584 let old =
585 unwrap(StoreHeader::parse(raw.get().as_bytes())?.wrapped(), words)?;
586 if old.key_id() != old_id {
587 return Err(EncryptionError::Header(format!(
588 "the old words open key {}, but the items are under key {}",
589 old.key_id().short(),
590 old_id.short()
591 ))
592 .into());
593 }
594 Some(old)
595 }
596 _ => return Err(EncryptionError::NoKey.into()),
597 }
598 }
599 };
600 let session = self.hold(&session).await?;
601 self.drive(&session, old, &key).await?;
602 Ok(key)
603 }
604
605 async fn abort_rewrite(&self) -> Result<(), StoreError> {
606 let (_, session) = self.open_session().await?;
607 let session = self.hold(&session).await?;
608 self.send_json(
609 "abortRewrite",
610 reqwest::Method::POST,
611 "/rewrite/abort",
612 format!("{{\"newKeyId\":\"{}\"}}", session.new_key_id),
613 )
614 .await
615 }
616
617 fn plain_store(&self) -> Box<dyn Store + '_> {
618 Box::new(HttpStore::in_partition(
619 self.client.clone(),
620 None,
621 self.clock.clone(),
622 Partition::Plain,
623 ))
624 }
625
626 async fn remove_plain_if_empty(&self) -> Result<bool, StoreError> {
627 Ok(false)
630 }
631}
632
633#[cfg(test)]
634mod tests {
635 use super::*;
636
637 fn quick() -> KdfParams {
638 KdfParams {
639 m_kib: 64,
640 t: 1,
641 p: 1,
642 salt: [7; 16],
643 }
644 }
645
646 #[test]
647 fn a_header_that_opens_another_key_or_not_at_all_is_refused() {
648 let words = Words::parse("abacus abdomen abdominal abide abiding ability").unwrap();
649 let other = Words::parse("zoom zoom zoom zoom zoom zoom").unwrap();
650 let (key, header) = new_key(&words, quick()).unwrap();
651 check_header(&header, &words, &key).unwrap();
652 assert!(check_header(&header, &other, &key).is_err());
653 let (_, stranger) = new_key(&words, quick()).unwrap();
654 match check_header(&stranger, &words, &key) {
655 Err(StoreError::Encryption(EncryptionError::Header(reason))) => {
656 assert!(reason.contains("nothing was changed"), "{reason}");
657 }
658 other => panic!("unexpected {other:?}"),
659 }
660 }
661
662 #[test]
663 fn the_heartbeat_comes_three_times_a_lease_and_at_least_once_a_minute() {
664 let now = DateTime::parse_from_rfc3339("2026-09-19T12:00:00Z")
665 .unwrap()
666 .with_timezone(&Utc);
667 let session = |ends: &str| {
668 serde_json::from_value::<api::RewriteSession>(serde_json::json!({
669 "kind": "migrate", "holder": "k", "leaseExpiresAt": ends,
670 "newKeyId": "x", "stagedIds": [], "sourceItems": 0,
671 }))
672 .unwrap()
673 };
674 assert_eq!(
675 heartbeat_every(&session("2026-09-19T12:10:00Z"), now),
676 HEARTBEAT_EVERY
677 );
678 assert_eq!(
679 heartbeat_every(&session("2026-09-19T12:00:03Z"), now),
680 Duration::from_secs(1)
681 );
682 assert_eq!(
683 heartbeat_every(&session("2026-09-19T11:59:00Z"), now),
684 HEARTBEAT_EVERY / 3,
685 "an ended lease is renewed well within a minute"
686 );
687 assert_eq!(
688 heartbeat_every(&session("2026-09-19T12:00:00.300Z"), now),
689 Duration::from_millis(200)
690 );
691 }
692}