Skip to main content

coven/
storage.rs

1//! Application storage setup, credential custody and connection control.
2
3use crate::{
4    error::{setup_error, unlock_error},
5    *,
6};
7use coven_crypto::custody::{KeySession, PersonEntries};
8use coven_foundation::locks::lock_unpoisoned;
9use coven_foundation::progress::ProgressReport;
10use coven_storage::{
11    providers::{OAuthExchange, OAuthFlow, StorageConnector},
12    ConnectionCredentials, ProviderAuth, PublicationGate, SetupWaits, Storage, StorageConnection,
13    StorageCredentials,
14};
15use coven_sync::{
16    DeviceCredentials, LastPass, RestoreCodes, SequenceState, SequenceSync, SessionSignIn, SyncLoop,
17};
18use std::{
19    future::Future,
20    sync::{
21        atomic::{AtomicBool, AtomicU64, Ordering},
22        Arc,
23    },
24};
25
26/// Whether this device's custody holds opened store keys.
27#[derive(Clone, Copy, Debug, PartialEq, Eq)]
28pub enum StoreKeyState {
29    /// Store keys are held by custody.
30    Available,
31    /// Store keys must be opened from this member's sealed copy.
32    Locked,
33}
34
35/// The configured location and the result of opening this device's keys.
36#[derive(Clone, Debug)]
37pub struct ConnectedStorage {
38    /// The connected provider location.
39    pub storage: StorageConfig,
40    /// This device's key availability.
41    pub key_state: StoreKeyState,
42}
43
44/// Storage setup's committed connection and this member's restore code.
45#[derive(Clone, Debug)]
46pub struct StorageSetup {
47    /// The location and availability of its store keys.
48    pub connection: ConnectedStorage,
49    /// The code for restoring this member on another installation.
50    pub restore_code: SecretText,
51}
52
53/// What using a new S3 key did (E9, §14.3).
54#[derive(Clone, Debug, PartialEq, Eq)]
55pub struct AccessKeyUsed {
56    /// The key id this member's access record named before the call, when
57    /// the call recorded another: the key the person deletes in the
58    /// provider's console. None when the record already named the new key.
59    pub replaced: Option<String>,
60}
61
62/// Where a setup call reports its steps, for the handle to forward to the app.
63pub(crate) type SetupProgress = tokio::sync::watch::Sender<Option<Progress<StorageSetupStep>>>;
64
65/// Write what the sync state starts from as a store opens: whether a
66/// storage location is recorded here and its credentials held, that no pass
67/// moves, and, for a store joining or restoring read to its end, when sync
68/// finished (E5); then end each invite whose lifetime ended while it was
69/// closed (§13.2). Opening writes them before the handle exists, so no app
70/// reads a move a process that closed left behind, or an invite that has
71/// expired.
72pub(crate) async fn record_opened(
73    database: &coven_database::StoreDatabase,
74    clock: &ClockRef,
75    location: coven_database::RecordedLocation<StorageConfig>,
76    finished: Option<std::time::SystemTime>,
77) -> Result<(), SyncError> {
78    coven_sync::record_opened(database, location, finished).await?;
79    coven_sync::InviteExpiry::opened(database, clock.now()).await.map_err(SyncError::from)?;
80    // No screen shows a pairing a closed handle or a crash left.
81    coven_sync::pairings_opened(database).await.map_err(SyncError::from)
82}
83
84/// A read-only handle publishes nothing.
85pub(crate) struct NoPublications;
86
87impl PublicationGate for NoPublications {
88    fn check(&self, _: &ObjectPath) -> Result<(), StorageError> {
89        Err(StorageFailure::PermissionDenied.with_source("a read-only handle publishes nothing"))
90    }
91}
92
93/// One provider connection's sequence owner and loop.
94struct Live {
95    sync: Arc<SequenceSync>,
96    sync_loop: SyncLoop,
97}
98
99/// Bootstrap retains its loaded provider before its sequence worker is needed.
100enum ConnectionState {
101    Released,
102    Loaded(Arc<StorageConnection>),
103    Active(Live),
104}
105
106struct ConnectionAttempt {
107    epoch: u64,
108    task: crate::task::OwnedTask,
109    /// Each time the attempt has taken everything that can wake its
110    /// backoff and waits.
111    #[cfg(test)]
112    parks: coven_sync::Parks,
113}
114
115pub(crate) struct StorageConnections {
116    /// The store's credential owner, connected or not; a change that needs
117    /// the connection is given its sequence owner.
118    codes: RestoreCodes,
119    database: coven_database::StoreDatabase,
120    files: coven_sync::Files,
121    identity: Arc<KeySession<MemberIdentity>>,
122    /// The person's entries, for each connection's sequence owner.
123    person: Arc<PersonEntries>,
124    credentials: Arc<DeviceCredentials>,
125    /// The sequence state whose gate every connection publishes through.
126    state: Arc<SequenceState>,
127    directory: StoreDir,
128    waits: Arc<coven_sync::RetryWaits>,
129    transfers: Arc<coven_storage::TransferBudget>,
130    keys: std::sync::Mutex<Option<Arc<KeySession<StoreKeyring>>>>,
131    connector: Arc<dyn StorageConnector>,
132    oauth: Option<OAuthFlow>,
133    /// The app's clients, which refresh a session sign-in.
134    clients: Option<OAuthExchange>,
135    /// The latest sign-in, held for this session until setup publishes it.
136    authentication: tokio::sync::Mutex<Option<Arc<SessionSignIn>>>,
137    /// The connection, if any; held while it changes or works.
138    live: tokio::sync::Mutex<ConnectionState>,
139    /// Ends invites as their lifetimes end, connected or not (§13.2).
140    expiry: coven_sync::InviteExpiry,
141    /// The connection's loop, for requests that return at once.
142    control: std::sync::Mutex<Option<SyncLoop>>,
143    /// Whether custody held storage credentials when last recorded: start
144    /// connects only then, without reading custody before the first attempt.
145    configured: AtomicBool,
146    /// Changed by a new start, stop or close: a connection attempt or a
147    /// queued stop acts only while no later request has superseded it.
148    epoch: AtomicU64,
149    /// Wakes a connection attempt's backoff when stopping is requested.
150    stopped: tokio::sync::Notify,
151    /// The started loop's connection attempts, awaited when closing.
152    attempts: std::sync::Mutex<Option<ConnectionAttempt>>,
153    device: DeviceId,
154    ids: IdSourceRef,
155    clock: ClockRef,
156    calls: tokio::sync::Mutex<()>,
157    /// How many times a call has found the call lock held and waited.
158    #[cfg(test)]
159    call_waits: tokio::sync::watch::Sender<usize>,
160    /// A failure the next close returns after closing, for a test of what
161    /// follows a failed close.
162    #[cfg(test)]
163    close_failure: std::sync::Mutex<Option<SyncError>>,
164    /// Run where the next deletion is about to write its record.
165    #[cfg(test)]
166    deletion_gate: std::sync::Mutex<Option<Box<dyn FnOnce() + Send>>>,
167    /// This store's device-only entries, where a setup keeps its own
168    /// credentials until it finishes (§11.6).
169    keychain: Arc<coven_crypto::custody::StoreKeychain>,
170    /// Where this session's storage setup stands (E5).
171    setup: std::sync::Mutex<setup::SetupRun>,
172    /// Wakes a setup checking the provider when the app cancels it.
173    setup_cancelled: tokio::sync::Notify,
174    /// What the next setup does at one of its stops, for a test.
175    #[cfg(test)]
176    setup_hook: std::sync::Mutex<Option<setup::SetupHook>>,
177}
178
179impl StorageConnections {
180    pub(crate) fn new(
181        database: coven_database::StoreDatabase,
182        files: coven_sync::Files,
183        identity: Arc<KeySession<MemberIdentity>>,
184        person: Arc<PersonEntries>,
185        credentials: Arc<DeviceCredentials>,
186        codes: RestoreCodes,
187        state: Arc<SequenceState>,
188        directory: StoreDir,
189        waits: Arc<coven_sync::RetryWaits>,
190        transfers: Arc<coven_storage::TransferBudget>,
191        keys: Arc<KeySession<StoreKeyring>>,
192        connector: Arc<dyn StorageConnector>,
193        oauth: Option<OAuthFlow>,
194        clients: Option<OAuthExchange>,
195        authentication: Option<Arc<SessionSignIn>>,
196        storage: Option<Arc<StorageConnection>>,
197        configured: bool,
198        keychain: Arc<coven_crypto::custody::StoreKeychain>,
199        setup_finishing: bool,
200        device: DeviceId,
201        ids: IdSourceRef,
202        clock: ClockRef,
203    ) -> Self {
204        let expiry = coven_sync::InviteExpiry::start(
205            database.clone(),
206            clock.clone(),
207            waits.clone(),
208            state.clone(),
209        );
210        Self {
211            codes,
212            expiry,
213            database,
214            files,
215            identity,
216            person,
217            credentials,
218            state,
219            directory,
220            waits,
221            transfers,
222            keys: std::sync::Mutex::new(Some(keys)),
223            connector,
224            oauth,
225            clients,
226            authentication: tokio::sync::Mutex::new(authentication),
227            live: tokio::sync::Mutex::new(match storage {
228                Some(storage) => ConnectionState::Loaded(storage),
229                None => ConnectionState::Released,
230            }),
231            control: std::sync::Mutex::new(None),
232            configured: AtomicBool::new(configured),
233            epoch: AtomicU64::new(0),
234            stopped: tokio::sync::Notify::new(),
235            attempts: std::sync::Mutex::new(None),
236            device,
237            ids,
238            clock,
239            calls: tokio::sync::Mutex::new(()),
240            #[cfg(test)]
241            call_waits: tokio::sync::watch::channel(0).0,
242            #[cfg(test)]
243            close_failure: std::sync::Mutex::new(None),
244            #[cfg(test)]
245            deletion_gate: std::sync::Mutex::new(None),
246            keychain,
247            setup: std::sync::Mutex::new(match setup_finishing {
248                true => setup::SetupRun::Finishing,
249                false => setup::SetupRun::Idle,
250            }),
251            setup_cancelled: tokio::sync::Notify::new(),
252            #[cfg(test)]
253            setup_hook: std::sync::Mutex::new(None),
254        }
255    }
256
257    /// Initialize a loaded connection when a caller first needs its sequence owner.
258    async fn ready(&self, live: &mut ConnectionState) -> Result<(), SyncError> {
259        if let ConnectionState::Loaded(storage) = &*live {
260            let storage = storage.clone();
261            self.attach(live, storage).await?;
262        }
263        Ok(())
264    }
265
266    fn store(&self) -> StoreId {
267        self.directory.id()
268    }
269
270    /// Write how sync failed outside a pass's end, starting or stopping, as
271    /// the last pass's failure, in the step that fails (E5). A failed write
272    /// has failed the store's handle with its cause, which the caller
273    /// returns.
274    pub(crate) async fn show(&self, failure: LastPass) -> Result<(), SyncError> {
275        failure.record(&self.database).await.map_err(SyncError::from)
276    }
277
278    /// Write whether a storage location is recorded here and custody holds
279    /// its credentials, and keep whether starting connects (E5). `finished`,
280    /// for setup, is when it read the store to its end. A failed write has
281    /// failed the store's handle with its cause, which the caller returns.
282    pub(crate) async fn record_location(
283        &self,
284        location: coven_database::RecordedLocation<StorageConfig>,
285        finished: Option<std::time::SystemTime>,
286    ) -> Result<(), SyncError> {
287        self.configured.store(location.is_connected(), Ordering::SeqCst);
288        coven_sync::record_location(&self.database, location, finished).await
289    }
290
291    /// Record the location as custody holds it now, as `record_location`
292    /// does: after credentials change, or a connection is released.
293    pub(crate) async fn record_custody(&self) -> Result<(), SyncError> {
294        let location = self.credentials.location()?;
295        self.record_location(location, None).await
296    }
297
298    pub(crate) async fn storage_config(&self) -> Result<Option<StorageConfig>, SyncError> {
299        let _call = self.lock_open().await?;
300        self.codes.location().await
301    }
302
303    /// Run `use_keys` on this session's store keys, holding the keys lock
304    /// throughout so closing cannot take them away mid-use. `StoreClosed`
305    /// once they are gone.
306    fn with_keys<T>(
307        &self,
308        use_keys: impl FnOnce(&Arc<KeySession<StoreKeyring>>) -> Result<T, KeyError>,
309    ) -> Result<T, KeyError> {
310        let keys = lock_unpoisoned(&self.keys);
311        use_keys(keys.as_ref().ok_or(KeyError::StoreClosed)?)
312    }
313
314    /// The call lock, which one call holds at a time; a test hears each
315    /// call that finds it held and waits.
316    pub(super) async fn lock_calls(&self) -> tokio::sync::MutexGuard<'_, ()> {
317        #[cfg(test)]
318        match self.calls.try_lock() {
319            Ok(call) => return call,
320            Err(_) => self.call_waits.send_modify(|waits| *waits += 1),
321        }
322        self.calls.lock().await
323    }
324
325    async fn lock_open(&self) -> Result<tokio::sync::MutexGuard<'_, ()>, KeyError> {
326        let call = self.lock_calls().await;
327        self.with_keys(|_| Ok(()))?;
328        Ok(call)
329    }
330
331    // The task owns both the call and its lock until it finishes, even if the
332    // awaiting app future is dropped. Sign-in deliberately does not spawn.
333    async fn call<T, E, F>(
334        self: &Arc<Self>,
335        run: impl FnOnce(Arc<Self>) -> F + Send + 'static,
336    ) -> Result<T, E>
337    where
338        T: Send + 'static,
339        E: From<KeyError>
340            + From<crate::task::TaskFailed>
341            + crate::task::CarriesBug
342            + Send
343            + 'static,
344        F: Future<Output = Result<T, E>> + Send,
345    {
346        let owner = self.clone();
347        let call = async move {
348            let _call = owner.lock_open().await?;
349            Box::pin(run(owner.clone())).await
350        };
351        crate::task::spawn_completing("storage call", self.database.bugs().clone(), call).await?
352    }
353
354    /// Compose a sequence owner and its loop on `storage` as this store's
355    /// connection.
356    async fn attach(
357        &self,
358        live: &mut ConnectionState,
359        storage: Arc<StorageConnection>,
360    ) -> Result<(), SyncError> {
361        let sync = self.sequence(storage.clone(), live).await?;
362        self.files.set_storage(Some(storage), std::future::ready(Ok(()))).await?;
363        self.activate(live, sync, false).await
364    }
365
366    /// Compose a candidate without replacing the committed connection.
367    async fn sequence(
368        &self,
369        storage: Arc<StorageConnection>,
370        previous: &ConnectionState,
371    ) -> Result<Arc<SequenceSync>, SyncError> {
372        if let ConnectionState::Active(previous) = previous {
373            return Ok(Arc::new(previous.sync.reconnect(storage)));
374        }
375        let keys = self.with_keys(|keys| Ok(keys.clone()))?;
376        Ok(Arc::new(
377            SequenceSync::open(
378                self.database.clone(),
379                storage,
380                self.directory.clone(),
381                self.device,
382                keys,
383                self.identity.clone(),
384                self.person.clone(),
385                self.state.clone(),
386                self.clock.clone(),
387                self.ids.clone(),
388                self.waits.clone(),
389                self.files.clone(),
390            )
391            .await?,
392        ))
393    }
394
395    /// Install the sequence owner only after connection custody commits.
396    async fn activate(
397        &self,
398        live: &mut ConnectionState,
399        sync: Arc<SequenceSync>,
400        start: bool,
401    ) -> Result<(), SyncError> {
402        let sync_loop = SyncLoop::new(sync.clone(), self.codes.clone());
403        let started = if start { sync_loop.start().await } else { Ok(()) };
404        *lock_unpoisoned(&self.control) = Some(sync_loop.clone());
405        *live = ConnectionState::Active(Live { sync, sync_loop });
406        started
407    }
408
409    /// Run `work` with the active connection's passes held: uploads run
410    /// beside them, as during a connection change (§17.4). Work that fails
411    /// or panics lets the passes run again, keeping a failure to resume them
412    /// as cleanup; work that succeeds leaves them held for the caller to
413    /// end. Unwound, a panic would leave them held for as long as the store
414    /// stays open (E15).
415    async fn with_passes_held<T>(
416        live: &ConnectionState,
417        work: impl std::future::Future<Output = Result<T, SyncError>>,
418    ) -> Result<T, SyncError> {
419        let ConnectionState::Active(previous) = live else {
420            return work.await;
421        };
422        previous.sync_loop.pause().await?;
423        let done = crate::task::caught("work with the passes held", work)
424            .await
425            .unwrap_or_else(|bug| Err(SyncError::Bug(bug)));
426        done.map_err(|error| match previous.sync_loop.resume() {
427            Ok(()) => error,
428            Err(cleanup) => SyncError::cleanup(error, cleanup),
429        })
430    }
431
432    /// Leave the connection released. An active one closes after its pass
433    /// and transfers, and after the credential change running on it, even
434    /// one whose caller stopped waiting.
435    async fn close_live(&self, live: &mut ConnectionState) -> Result<(), SyncError> {
436        match std::mem::replace(live, ConnectionState::Released) {
437            ConnectionState::Active(previous) => {
438                let result = previous.sync_loop.close().await;
439                self.codes.settled().await;
440                result
441            }
442            ConnectionState::Released | ConnectionState::Loaded(_) => Ok(()),
443        }
444    }
445
446    /// End the sync loop: retries waiting for a pass are answered
447    /// `NotSyncing`, as no connection plans afterwards, and the connection's
448    /// owners close after its active pass. Answers whether the retries heard
449    /// so, then whether the owners closed.
450    async fn end_loop(
451        &self,
452        live: &mut ConnectionState,
453    ) -> (Result<(), DbError>, Result<(), SyncError>) {
454        let stopped = self.waits.sync_stopped().await;
455        lock_unpoisoned(&self.control).take();
456        (stopped, self.close_live(live).await)
457    }
458
459    /// Release the current connection after its active pass and transfers,
460    /// with the files' provider client.
461    async fn release(&self, live: &mut ConnectionState) -> Result<(), SyncError> {
462        let (stopped, closed) = self.end_loop(live).await;
463        let released = self.files.set_storage(None, std::future::ready(Ok(()))).await;
464        closed.and(released).and(stopped.map_err(SyncError::from))
465    }
466
467    /// Connect with custody's credentials unless this session already has a
468    /// connection, without starting the loop.
469    pub(crate) async fn connected(&self) -> Result<(), SyncError> {
470        let mut live = self.live.lock().await;
471        if let ConnectionState::Active(_) = &*live {
472            return Ok(());
473        }
474        self.connect(&mut live).await
475    }
476
477    /// Reach the recorded location with custody's credentials, removing
478    /// what recorded detection runs left there (§20.7), or finish the setup
479    /// a crash cut past its point of no return (§11.6).
480    async fn connect(&self, live: &mut ConnectionState) -> Result<(), SyncError> {
481        if self.setup_finishing() {
482            if let Some(journal) = coven_sync::SetupJournal::running(&self.database).await? {
483                return self.resume_setup(live, journal).await;
484            }
485        }
486        if let ConnectionState::Loaded(storage) = live {
487            let storage = storage.clone();
488            return self.attach(live, storage).await;
489        }
490        let data = self.codes.connection().await?.ok_or(SyncError::NoStorage)?;
491        self.connect_with(live, data).await
492    }
493
494    /// Reach the recorded location with `data`'s credentials, as a
495    /// connection made from custody does; the credentials may not be in
496    /// custody yet.
497    async fn connect_with(
498        &self,
499        live: &mut ConnectionState,
500        data: ConnectionCredentials,
501    ) -> Result<(), SyncError> {
502        let storage = self
503            .connector
504            .connect(
505                data.location.clone(),
506                self.codes.provider_auth(data.credentials),
507                self.device,
508                self.state.clone(),
509                self.waits.clone(),
510                self.transfers.clone(),
511            )
512            .await?;
513        storage.check_location_claim(self.store()).await?;
514        record_reached(&self.codes, &self.database, self.store(), &data.location, &storage).await?;
515        self.attach(live, storage).await
516    }
517
518    pub(crate) fn key_state(&self) -> Result<StoreKeyState, KeyError> {
519        let held = self.with_keys(|keys| keys.read())?;
520        Ok(match held {
521            Some(_) => StoreKeyState::Available,
522            None => StoreKeyState::Locked,
523        })
524    }
525
526    pub(crate) async fn authenticate(&self, access: OAuthAccess) -> Result<(), StorageSetupError> {
527        let _call = self.lock_open().await?;
528        let flow = self.oauth.as_ref().ok_or(OAuthError::Unavailable(access.provider()))?;
529        let tokens = flow.authenticate(access).await?;
530        *self.authentication.lock().await = Some(SessionSignIn::new(tokens, self.clients.clone()));
531        Ok(())
532    }
533
534    pub(crate) async fn setup_oauth(
535        self: &Arc<Self>,
536        storage: StorageConfig,
537        progress: SetupProgress,
538    ) -> Result<StorageSetup, StorageSetupError> {
539        let call = self.start_setup()?;
540        self.call(move |owner| async move {
541            let mut progress = ProgressReport::new(progress, owner.clock.clone());
542            let waits = SetupWaits::default();
543            let provider = storage.provider();
544            if !provider.signs_in_with_oauth() {
545                return Err(OAuthError::Unavailable(provider).into());
546            }
547            owner.check_location(&storage).await?;
548            let mut held = owner.authentication.lock().await;
549            let (auth, sign_in) = match held.as_ref() {
550                Some(sign_in) => {
551                    let auth = crate::authentication::held_auth(sign_in, provider)?;
552                    (auth, Some(sign_in.clone()))
553                }
554                None => {
555                    let data = owner
556                        .codes
557                        .connection()
558                        .await
559                        .map_err(setup_error)?
560                        .ok_or(OAuthError::Reauthorize(provider))?;
561                    if data.location.provider() != provider {
562                        return Err(OAuthError::Reauthorize(provider).into());
563                    }
564                    (owner.codes.provider_auth(data.credentials), None)
565                }
566            };
567            let journal = owner.begin_setup(call, &auth.credentials()).await?;
568            let setup = owner.run_setup(journal, async |journal| {
569                owner
570                    .check_new_location(journal, &storage, auth.clone(), &waits, &mut progress)
571                    .await?;
572                let (connector, cooldown) = (owner.connector.as_ref(), &owner.waits);
573                let (location, signed_in) = (&storage, &auth);
574                let reading = waits.resend(owner.clock.as_ref(), move || {
575                    crate::authentication::label_location(
576                        connector,
577                        location.clone(),
578                        signed_in.clone(),
579                        cooldown.clone(),
580                    )
581                });
582                let storage =
583                    setup_step::single(&mut progress, StorageSetupStep::ReadingAccount, reading)
584                        .await?;
585                owner.setup_connection(journal, storage, auth, sign_in, waits, &mut progress).await
586            });
587            let result = setup.await?;
588            held.take();
589            Ok(result)
590        })
591        .await
592    }
593
594    pub(crate) async fn setup_cloudkit(
595        self: &Arc<Self>,
596        container: &str,
597        progress: SetupProgress,
598    ) -> Result<StorageSetup, StorageSetupError> {
599        let container = container.to_owned();
600        let call = self.start_setup()?;
601        self.call(move |owner| async move {
602            let mut progress = ProgressReport::new(progress, owner.clock.clone());
603            let waits = SetupWaits::default();
604            let recorded = owner.codes.location().await.map_err(setup_error)?;
605            if recorded.as_ref().is_some_and(|recorded| {
606                !matches!(recorded, StorageConfig::CloudKit { container: kept, .. } if *kept == container)
607            }) {
608                return Err(StorageSetupError::LocationChangeUnsupported);
609            }
610            let journal = owner.begin_setup(call, &StorageCredentials::CloudKit).await?;
611            owner
612                .run_setup(journal, async |journal| {
613                    let storage = match recorded {
614                        Some(storage) => storage,
615                        None => {
616                            // Preparing reads the account and saves the zone,
617                            // as it does for a zone that already exists: a
618                            // refusal can be sent again.
619                            let (connector, container, store) =
620                                (owner.connector.as_ref(), container.as_str(), owner.store());
621                            let preparing = waits.resend(owner.clock.as_ref(), move || {
622                                connector.prepare_cloudkit(container, store)
623                            });
624                            setup_step::single(
625                                &mut progress,
626                                StorageSetupStep::PreparingZone,
627                                preparing,
628                            )
629                            .await?
630                        }
631                    };
632                    owner
633                        .setup_connection(
634                            journal,
635                            storage,
636                            ProviderAuth::CloudKit,
637                            None,
638                            waits,
639                            &mut progress,
640                        )
641                        .await
642                })
643                .await
644        })
645        .await
646    }
647
648    /// Before a store's first setup at a location every member reaches
649    /// whole, check that it holds nothing but this store (§20.3). Reads only,
650    /// so it runs before setup's first write; a location that holds several
651    /// stores, and a reconnect, check nothing here.
652    async fn check_new_location(
653        &self,
654        journal: &coven_sync::SetupJournal,
655        config: &StorageConfig,
656        auth: ProviderAuth,
657        waits: &SetupWaits,
658        progress: &mut ProgressReport<StorageSetupStep>,
659    ) -> Result<(), StorageSetupError> {
660        if !journal.creating() || !config.holds_one_store() {
661            return Ok(());
662        }
663        let checking = self.connector.check_new_store(config.clone(), auth, self.store(), waits);
664        setup_step::single(progress, StorageSetupStep::CheckingLocation, checking).await?;
665        Ok(())
666    }
667
668    async fn check_location(&self, config: &StorageConfig) -> Result<(), StorageSetupError> {
669        if self
670            .codes
671            .location()
672            .await
673            .map_err(setup_error)?
674            .is_some_and(|recorded| !recorded.same_location(config))
675        {
676            return Err(StorageSetupError::LocationChangeUnsupported);
677        }
678        Ok(())
679    }
680
681    fn forget_keys(&self) -> Result<(), KeyError> {
682        self.with_keys(|keys| keys.forget())
683    }
684
685    pub(crate) async fn unlock(self: &Arc<Self>) -> Result<ConnectedStorage, StoreKeyUnlockError> {
686        self.call(|owner| async move {
687            let data = owner
688                .codes
689                .connection()
690                .await
691                .map_err(unlock_error)?
692                .ok_or(StoreKeyUnlockError::NoStorage)?;
693            let config = data.location.clone();
694            let mut live = owner.live.lock().await;
695            owner.release(&mut live).await.map_err(unlock_error)?;
696            owner.connect(&mut live).await.map_err(unlock_error)?;
697            let unlocked = match &*live {
698                ConnectionState::Active(candidate) => candidate.sync.unlock().await,
699                _ => Err(SyncError::NoStorage),
700            };
701            if let Err(error) = unlocked {
702                let error = match owner.release(&mut live).await {
703                    Ok(()) => error,
704                    Err(cleanup) => SyncError::cleanup(error, cleanup),
705                };
706                let error = match owner.publish_released(Ok(())).await {
707                    Ok(()) => error,
708                    Err(cleanup) => SyncError::cleanup(error, cleanup),
709                };
710                return Err(unlock_error(error));
711            }
712            // Connected without syncing.
713            owner.publish_released(Ok(())).await.map_err(unlock_error)?;
714            Ok(ConnectedStorage { storage: config, key_state: StoreKeyState::Available })
715        })
716        .await
717    }
718
719    /// Load a store a join published once it found its admission, before
720    /// anything of it was loaded: connect, through the connection the join
721    /// made, and read forward with the keys its copies opened, sending each
722    /// of loading's steps to `progress` (§13.2, §13.4). The loop doesn't
723    /// start; a failure leaves the store as a failed pass would, for the
724    /// loop's passes to go on from.
725    pub(crate) async fn load_joined(
726        self: &Arc<Self>,
727        progress: tokio::sync::watch::Sender<Option<Progress<coven_database::LoadStep>>>,
728    ) -> Result<(), SyncError> {
729        self.call(|owner| async move {
730            let mut live = owner.live.lock().await;
731            if !matches!(&*live, ConnectionState::Active(_)) {
732                owner.connect(&mut live).await?;
733            }
734            let ConnectionState::Active(candidate) = &*live else {
735                return Err(SyncError::NoStorage);
736            };
737            candidate.sync.load_joined(progress).await
738        })
739        .await
740    }
741
742    pub(crate) async fn forget_store_keys(self: &Arc<Self>) -> Result<(), KeyError> {
743        self.call(|owner| async move {
744            let mut live = owner.live.lock().await;
745            let result = async {
746                Self::with_passes_held(
747                    &live,
748                    owner
749                        .files
750                        .set_storage(None, async { owner.forget_keys().map_err(SyncError::from) }),
751                )
752                .await?;
753                let (stopped, released) = owner.end_loop(&mut live).await;
754                // Forgetting succeeded. A worker release failure is recorded
755                // as the last pass's failure; no later custody read can turn
756                // removal into an error. Stopping writes nothing else the
757                // sync state reads. A failed write has failed the handle.
758                if let Err(error) = released {
759                    owner.show(LastPass::failed(error)).await?;
760                }
761                Ok(stopped?)
762            }
763            .await;
764            result.map_err(|error| match error {
765                SyncError::SecureStorage(error) => error,
766                SyncError::Database(DbError::StoreClosed) => KeyError::StoreClosed,
767                // A bug is the call's own `Bug`, never custody that is
768                // unavailable (E15).
769                error => match crate::task::CarriesBug::bug(&error) {
770                    Some(bug) => KeyError::Bug(bug.clone()),
771                    None => KeyError::Unavailable(Box::new(error)),
772                },
773            })
774        })
775        .await
776    }
777}
778
779#[path = "storage_attempt.rs"]
780mod attempt;
781
782#[path = "storage_control.rs"]
783mod control;
784
785#[path = "storage_folders.rs"]
786mod folders;
787#[cfg(test)]
788pub(crate) use folders::with_folder_label;
789
790#[path = "storage_s3.rs"]
791mod s3;
792
793#[path = "storage_setup_step.rs"]
794mod setup_step;
795pub use setup_step::StorageSetupStep;
796
797#[path = "storage_setup.rs"]
798mod setup;
799pub(crate) use setup::settle_opened;
800pub use setup::SetupCancellation;
801#[cfg(test)]
802pub(crate) use setup::SetupHook;
803
804#[path = "storage_admin.rs"]
805mod admin;
806pub use admin::GuidedAccessKey;
807
808#[path = "storage_operations.rs"]
809mod operations;
810
811/// Record what `storage`, a new connection to `location` whose claim it
812/// checked, finds as it attaches: the folder's label as its provider names it
813/// now, so a rename since the last connection shows (§20.2), and the end of
814/// each detection run whose probes it removed (§20.7).
815pub(crate) async fn record_reached(
816    codes: &RestoreCodes,
817    database: &coven_database::StoreDatabase,
818    store: StoreId,
819    location: &StorageConfig,
820    storage: &StorageConnection,
821) -> Result<(), SyncError> {
822    codes.record_labels(&storage.labelled_config().await?).await?;
823    s3::end_detection_runs(database, store, location, storage).await
824}
825
826/// How this member reaches storage over `storage` signed in with
827/// `credentials`: the S3 key, or the signed-in account (§20.2).
828pub(crate) async fn member_access(
829    credentials: &StorageCredentials,
830    storage: &StorageConnection,
831) -> Result<coven_format::MemberAccess, coven_storage::StorageError> {
832    Ok(match credentials {
833        StorageCredentials::S3(keys) => {
834            coven_format::MemberAccess::S3AccessKey { access_key_id: keys.access_key_id.clone() }
835        }
836        _ => coven_format::MemberAccess::ProviderAccount(storage.account().await?),
837    })
838}
839
840/// The entry recording `access` as `member`'s own, when history records
841/// another: setup and restore keep the recorded access the one the member
842/// uses (§14.2).
843pub(crate) fn access_change(
844    state: &coven_database::StoreState,
845    member: MemberId,
846    access: coven_format::MemberAccess,
847) -> Result<Option<coven_format::admin::StoreChange>, SyncError> {
848    let recorded =
849        state.active_member(&member).ok_or(SyncError::Removed(coven_database::Removal::Member))?;
850    let current = recorded.access.as_ref().is_some_and(|held| held.same_credential(&access));
851    Ok((!current).then_some(coven_format::admin::StoreChange::SetAccess { member, access }))
852}
853
854#[cfg(test)]
855#[path = "storage_tests.rs"]
856mod tests;