Skip to main content

passalong_https/
admin.rs

1//! [`HttpEncryptionAdmin`]: changing a workspace's encryption through the
2//! server's API.
3//!
4//! What the filesystem does with a journal and renames is one call here:
5//! set-up is `enableEncryption`, a fresh start `freshStart`, and a change of
6//! words `replaceHeader`, each atomic on the server. The data key is made
7//! and wrapped on the device, as for every store; the server keeps only the
8//! wrapped key.
9//!
10//! Migrating and rotating run the shared engine, [`run_rewrite`], over the
11//! server's rewrite session: `beginRewrite` takes a lease, each copy is an
12//! upload into the staged generation, every copy is read back from there,
13//! and `commitRewrite` switches generation, header, and key at once. The
14//! server is the journal, so any device with the new words can finish it.
15
16use 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
37/// [`EncryptionAdmin`] for a passalong-server workspace.
38pub 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
51/// The refusal for a workspace in a state the operation cannot start from,
52/// as the filesystem gives it.
53fn 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
68/// The header as JSON for a request body, without the file's last newline.
69fn header_json(header: &StoreHeader) -> String {
70    String::from_utf8_lossy(&header.to_json())
71        .trim_end()
72        .to_owned()
73}
74
75impl HttpEncryptionAdmin {
76    /// Changes the encryption of the workspace behind `client`.
77    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    /// Sends a rewrite request and reads the session it answers with.
128    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    /// Re-encrypts every item under a new key wrapped with `words`: from
138    /// plaintext, or from the key `old` when rotating. A session whose
139    /// key an abort ended is begun again under another key.
140    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            // A header that does not open with the words would lock the
150            // workspace for good at the commit.
151            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    /// Runs the shared engine over the open session, from items under
187    /// `old`, or plaintext, to `key`.
188    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    /// The open session, and the workspace around it.
218    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    /// Makes this device the session's holder: renews its own lease, or
229    /// takes over one that has ended.
230    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
242/// Sends a rewrite request with `client` and reads the session it answers
243/// with.
244async 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
265/// Renews the lease every `every` until aborted: one item can take longer
266/// than a lease on a slow link, so the renewal cannot wait between items.
267fn 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                // Taken over: the next request of the rewrite says so.
274                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
281/// How often a session's heartbeat is due: a third of its lease, and at
282/// least once a minute.
283fn 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
291/// Refuses a header that does not open with `words` to `key`.
292fn 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
315/// A re-encryption through the server's rewrite session.
316struct 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        // `keep_lease` renews it all along.
347        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
362/// The workspace's key id, which a sealed workspace must name.
363fn 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        // An empty plain partition costs nothing; the server's janitor
628        // drops it.
629        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}