Skip to main content

coven/
bootstrap.rs

1//! New-device composition roots. Sync owns admission and loading; foundation
2//! owns unpublished directories and crypto owns final key custody (§13, E10).
3
4use super::*;
5#[cfg(test)]
6use coven_crypto::custody::Keychain;
7use coven_crypto::custody::{InMemoryCustody, PersonEntries, StoreKeychain};
8use coven_database::StoreDatabase;
9use coven_format::codes::{InviteCode, RestoreCode};
10use coven_foundation::files::StoreDirAccess;
11use coven_foundation::files::{
12    BootstrapDirectoryError, BootstrapStore, Registration, ReplacedBy, ReplacementStore,
13};
14use coven_storage::{
15    ConnectionCredentials, InviteStorage, RestoreStorage, StorageCredentials, StorageFailure,
16};
17use coven_sync::{HeldIntervals, Parks, SequenceSync, SyncOften};
18use std::{sync::Arc, time::Duration};
19use tokio::sync::watch;
20
21#[path = "bootstrap_authentication.rs"]
22mod authentication;
23use authentication::{
24    account_sign_in, connect_storage, join_sign_in, provider_auth, SignInCustody,
25};
26use coven_sync::SessionSignIn;
27
28#[path = "bootstrap_commit.rs"]
29mod commit;
30
31#[path = "bootstrap_join.rs"]
32mod join;
33
34#[path = "bootstrap_admitted.rs"]
35mod admitted;
36
37#[path = "bootstrap_pairing.rs"]
38mod pairing;
39pub use pairing::join_with_pairing;
40use pairing::Start;
41
42#[path = "bootstrap_replace.rs"]
43mod replace;
44pub(super) use replace::{restore_device, resume_replacement};
45
46#[path = "bootstrap_reset.rs"]
47mod reset;
48pub(super) use reset::reset_device;
49
50#[path = "bootstrap_restore.rs"]
51mod restore;
52#[cfg(test)]
53use restore::keychain_code;
54pub use restore::{restore_from_code, restore_from_saved_code};
55pub(super) use restore::{resume_restore, unfinished_restores};
56
57#[path = "restore_credentials.rs"]
58mod credentials;
59use credentials::restore_connection;
60
61#[path = "bootstrap_unfinished.rs"]
62mod unfinished;
63use unfinished::{begin_installation, kept, Kept};
64
65#[path = "bootstrap_end.rs"]
66mod end;
67use end::{record_ending, remove_unfinished};
68
69#[path = "bootstrap_error.rs"]
70mod error;
71pub use error::BootstrapError;
72
73#[path = "bootstrap_status.rs"]
74mod status;
75pub use status::BootstrapStatus;
76use status::{loading, open_installation};
77
78/// Accept provider access, retain one signed request across restarts, and wait
79/// for approval. Returns the open store, or None when declined or expired.
80/// `name` is the name the new person typed when the invite admits a new
81/// person, and `None` when it admits a member's new keys, as the invite's
82/// `InviteInfo::admits` says; the other fails with `CodeError::WrongJoiner`
83/// before anything changes. `circle_name` names the circle the request makes
84/// for the person, which the admission creates with them as its only member
85/// (§13.2). Dropping the future before the join finds its
86/// admission preserves the unfinished join for a subsequent call with the
87/// same invite, device name, name and circle name, or `resume_join`. On Dropbox and
88/// OneDrive the builder's sign-in is kept on the device beside the saved code
89/// until the join ends, and a later call without one uses it (§13.2).
90/// `control` cancels the join or asks for a check for approval at once.
91/// Cancelling before the request may have been sent removes the unpublished
92/// installation; after, the call ends with `BootstrapError::JoinRequestSent`
93/// and keeps it, as dropping does. Once the join finds its admission it
94/// publishes the store, a cancel notwithstanding, then loads it, reporting
95/// `Loading`; a failure while it loads returns `BootstrapError::Published`
96/// with the open handle (§13.2). A store whose unfinished installation
97/// holds a restore's record is refused with `StoreLockError::BootstrapPending`
98/// before anything changes (§13.4).
99pub async fn join_with_invite(
100    builder: CovenBuilder,
101    code: &str,
102    name: Option<String>,
103    circle_name: &str,
104    device_name: &str,
105    on_status: impl Fn(BootstrapStatus),
106    control: &JoinControl,
107) -> Result<Option<CovenHandle>, BootstrapError> {
108    // Whether a cancel may still remove the join is known only once its
109    // saved request is read, so the call checks after preparing it.
110    let cancel = control.cancel.subscribe();
111    Box::pin(bootstrap_device(
112        builder,
113        BootstrapRequest::Join {
114            code: coven_sync::read_invite_code(code)?,
115            terms: RequestTerms::Given {
116                device_name: device_name.into(),
117                name,
118                circle_name: circle_name.into(),
119            },
120            held: control.often.subscribe(),
121            parks: control.parks.clone(),
122        },
123        on_status,
124        &cancel,
125    ))
126    .await
127}
128
129/// The joins under way on this device, ordered by store id: each unfinished
130/// first installation with a saved invite code, as `decode_invite_info` reads
131/// it (`CovenBuilder::unfinished_joins`).
132pub(super) async fn unfinished_joins(
133    builder: &CovenBuilder,
134) -> Result<Vec<InviteInfo>, BootstrapError> {
135    let keychain = builder.keychain()?;
136    let mut joins = Vec::new();
137    for store in builder.directories.unfinished_first_installations().await? {
138        // An unfinished restore saves no code; an installation that keeps
139        // nothing is reclaimed.
140        let entries = StoreKeychain::new(keychain.clone(), store);
141        let Kept::Join(text) = kept(builder, &entries, store).await? else {
142            continue;
143        };
144        let info = coven_sync::decode_invite_info(text.as_str())?;
145        CodeError::require_store(store, info.metadata.store_id)?;
146        joins.push(info);
147    }
148    Ok(joins)
149}
150
151/// Continue an unfinished join from its saved code and the device name and
152/// person its saved request carries (`CovenBuilder::resume_join`).
153pub(super) async fn resume_join(
154    builder: CovenBuilder,
155    store: StoreId,
156    on_status: impl Fn(BootstrapStatus),
157    control: &JoinControl,
158) -> Result<Option<CovenHandle>, BootstrapError> {
159    let code = saved_invite_code(&StoreKeychain::new(builder.keychain()?, store), store)?
160        .ok_or(BootstrapError::NoUnfinishedJoin(store))?;
161    let cancel = control.cancel.subscribe();
162    Box::pin(bootstrap_device(
163        builder,
164        BootstrapRequest::Join {
165            code,
166            terms: RequestTerms::Saved,
167            held: control.often.subscribe(),
168            parks: control.parks.clone(),
169        },
170        on_status,
171        &cancel,
172    ))
173    .await
174}
175
176/// The invite code a join under way saved for `store`.
177fn saved_invite_code(
178    keychain: &StoreKeychain,
179    store: StoreId,
180) -> Result<Option<InviteCode>, BootstrapError> {
181    let Some(text) = keychain.invite_code()? else {
182        return Ok(None);
183    };
184    let code = coven_sync::read_invite_code(text.as_str())?;
185    CodeError::require_store(store, code.store)?;
186    Ok(Some(code))
187}
188
189/// The app's hold on a running join: cancel it, or ask it to check for
190/// approval often while the app shows the wait.
191pub struct JoinControl {
192    cancel: watch::Sender<bool>,
193    often: SyncOften,
194    /// Where the join's wait parks, for tests.
195    parks: Parks,
196}
197
198impl JoinControl {
199    /// A control no join has used yet.
200    pub fn new() -> Self {
201        Self { cancel: watch::channel(false).0, often: SyncOften::new(), parks: Parks::new() }
202    }
203
204    /// Cancel the join this control was passed to.
205    pub fn cancel(&self) {
206        self.cancel.send_replace(true);
207    }
208
209    /// Have the join check for approval at most `interval` after its last
210    /// check ended, until the guard drops; a check already that overdue runs
211    /// at once. With several guards held, the shortest interval wins. Checks
212    /// that find the request waiting still count toward the backoff, and a
213    /// provider cooldown still holds every check (§13.2).
214    pub fn check_often(&self, interval: Duration) -> SyncOftenGuard {
215        self.often.hold(interval)
216    }
217
218    /// Wait until the join's wait parks in a poll begun after this call,
219    /// having seen all the caller did before.
220    #[cfg(any(test, feature = "test-utils"))]
221    pub fn parked_from_now(&self) -> impl std::future::Future<Output = ()> + Send + 'static {
222        self.parks.parked_from_now()
223    }
224}
225
226enum BootstrapRequest {
227    Restore {
228        code: RestoreCode,
229        data: ConnectionCredentials,
230        /// Where an OAuth connection refreshes: the session, or the store's
231        /// device credentials a recorded restore kept its sign-in in.
232        sign_in: SignInCustody,
233        name: String,
234    },
235    Join {
236        code: InviteCode,
237        terms: RequestTerms,
238        /// The intervals the app asks the join to check at.
239        held: HeldIntervals,
240        parks: Parks,
241    },
242}
243
244/// The device name, the new person's name and the circle's name a join's
245/// request carries.
246enum RequestTerms {
247    /// What the app passed, which a saved request must repeat.
248    Given { device_name: String, name: Option<String>, circle_name: String },
249    /// What the saved request carries: the join resumes from it.
250    Saved,
251}
252
253/// Its state runs to tens of KiB, so the public calls await it boxed and the
254/// futures apps hold stay small (application_api_tests bounds them).
255async fn bootstrap_device(
256    mut builder: CovenBuilder,
257    start: impl Into<Start>,
258    status: impl Fn(BootstrapStatus),
259    cancel: &watch::Receiver<bool>,
260) -> Result<Option<CovenHandle>, BootstrapError> {
261    let start = start.into();
262    if matches!(start, Start::Pair(_) | Start::Request(BootstrapRequest::Restore { .. })) {
263        check_cancel(cancel)?;
264    }
265    let keychain = builder.keychain()?;
266    let id = start.store();
267    let device_entries = StoreKeychain::new(keychain.clone(), id);
268    let clock = builder.clock.clone();
269    let started = clock.elapsed();
270    #[cfg(test)]
271    let recorder = builder.loading_recorder.clone();
272    // A deletion of the store a cut call left recorded still holds its id
273    // (§19.3): it is finished first.
274    if builder.directories.deletion_recorded(id).await.map_err(BootstrapDirectoryError::from)? {
275        let directory = builder.directories.store_dir(&id);
276        let keys = StoreKeychain::new(keychain.clone(), id);
277        crate::coven::finish_deletion::<BootstrapError>(&directory, keys).await?;
278    }
279    let pending = begin_installation(&builder, id, &device_entries).await?;
280    // The store's one unfinished installation lists one call. A restore on
281    // a waiting join's installation, or a join on a recorded restore's,
282    // would remove the other's listing when it ends without the store, with
283    // its request or registration possibly in storage (§13.4).
284    let other = match &start {
285        Start::Request(BootstrapRequest::Restore { .. }) => device_entries.invite_code()?.is_some(),
286        Start::Request(BootstrapRequest::Join { .. }) => device_entries.restore_record()?.is_some(),
287        Start::Pair(_) => {
288            device_entries.invite_code()?.is_some() || device_entries.restore_record()?.is_some()
289        }
290    };
291    if other {
292        return Err(BootstrapDirectoryError::from(StoreLockError::BootstrapPending(id)).into());
293    }
294    // A join that decided to end and stopped part way through deleting
295    // what it kept finishes that, without connecting: the sign-in it would
296    // connect with may be gone already (§13.4).
297    if let Start::Request(BootstrapRequest::Join { code, .. }) = &start {
298        if coven_sync::ended_for(&pending.directory(), code)? {
299            return remove_unfinished(&device_entries, &pending, Ok(None));
300        }
301    }
302    // A pairing asks first, keeping nothing on the device, and then goes down
303    // the restore path with what its handover carried. Until that restore
304    // records itself, whatever ends the call removes the installation.
305    let asked = matches!(start, Start::Pair(_));
306    let request = match start {
307        Start::Pair(pair) => {
308            match pairing::handed_over(&mut builder, &pending, pair, &status, cancel).await {
309                Ok(Some(restore)) => restore,
310                result => {
311                    return remove_unfinished(&device_entries, &pending, result.map(|_| None));
312                }
313            }
314        }
315        Start::Request(request) => request,
316    };
317    // The asking reported the opening and the connecting, and a phase never
318    // comes back (E10).
319    let status = |next: BootstrapStatus| {
320        if !(asked && matches!(next, BootstrapStatus::Opening(_) | BootstrapStatus::Connecting)) {
321            status(next);
322        }
323    };
324    let result =
325        prepare_and_load(&mut builder, Installing::New(&pending), &request, None, &status, cancel)
326            .await;
327    match result {
328        Ok(Some(Loaded {
329            code,
330            location,
331            credentials,
332            sign_in,
333            ring,
334            database,
335            storage,
336            state,
337            waits,
338        })) => {
339            let requests = storage.requests();
340            status(BootstrapStatus::Committing);
341            // The saved code's name, read before the final steps, which no
342            // await separates; so is the status the published store opens
343            // with (E5). A join publishes before it loads, with the name its
344            // invite carries (§13.2).
345            let name = match &request {
346                BootstrapRequest::Join { code, .. } => commit::joined_name(&database, code).await,
347                BootstrapRequest::Restore { .. } => commit::loaded_name(&database).await,
348            };
349            let name = match name {
350                Ok(name) => crate::storage::record_opened(
351                    &database,
352                    &clock,
353                    coven_database::RecordedLocation::Connected(location.clone()),
354                    Some(clock.now()),
355                )
356                .await
357                .map(|()| name)
358                .map_err(BootstrapError::from),
359                Err(error) => Err(error),
360            };
361            let result = match name.and_then(|name| {
362                // A loaded restore registered its device: a cancel can't take
363                // it back, and ends the call (§13.1). A join that found its
364                // admission publishes, cancelled or not (§13.2).
365                if matches!(request, BootstrapRequest::Restore { .. })
366                    && check_cancel(cancel).is_err()
367                {
368                    return Err(BootstrapError::RestoreRegistered);
369                }
370                builder.authentication.take();
371                let credentials = match &sign_in {
372                    // A join's kept sign-in is already this store's device
373                    // credentials: the handle refreshes through the same
374                    // custody as the connection it continues.
375                    SignInCustody::Device { credentials, .. } => Some(credentials.clone()),
376                    _ => None,
377                };
378                let owners = builder.owners(
379                    pending.directory(),
380                    Arc::new(StoreKeychain::new(keychain, id)),
381                    crate::builder::Continuing::Loaded { state, storage, credentials },
382                )?;
383                Ok((owners, name))
384            }) {
385                // No cancellable await separates final custody, publication
386                // and the handle.
387                Ok((owners, name)) => {
388                    let publishing = clock.elapsed();
389                    let published = commit::publish_bootstrap(
390                        &pending,
391                        code,
392                        location,
393                        name,
394                        credentials,
395                        sign_in,
396                        ring,
397                        owners,
398                        database.clone(),
399                        waits,
400                    )
401                    .await;
402                    tracing::info!(
403                        published = published.is_ok(),
404                        time = ?(clock.elapsed() - publishing),
405                        "committed keys and credentials and published the store"
406                    );
407                    tracing::info!(
408                        restore = matches!(request, BootstrapRequest::Restore { .. }),
409                        published = published.is_ok(),
410                        time = ?(clock.elapsed() - started),
411                        %requests,
412                        "ended the new installation's bootstrap"
413                    );
414                    published
415                }
416                Err(error) => Err(error),
417            };
418            // A published store no longer needs what its join or restore
419            // kept to finish it.
420            let result = match &request {
421                BootstrapRequest::Join { .. } => {
422                    forget_kept(result, || device_entries.delete_invite_code())
423                }
424                BootstrapRequest::Restore { .. } => {
425                    forget_kept(result, || device_entries.delete_restore_record())
426                }
427            };
428            match result {
429                Ok(handle) => match &request {
430                    BootstrapRequest::Join { .. } => {
431                        let (progress, watch) = watch::channel(None);
432                        #[cfg(test)]
433                        if let Some(recorder) = &recorder {
434                            recorder.watch(watch.clone());
435                        }
436                        admitted::load_joined(handle, &status, &clock, progress, watch)
437                            .await
438                            .map(Some)
439                    }
440                    BootstrapRequest::Restore { .. } => Ok(Some(handle)),
441                },
442                Err(error @ BootstrapError::Published { .. }) => Err(error),
443                // A loaded join or restore is past cancelling: it stays for
444                // the next call.
445                Err(error) => combine(Err(error), close_database(&database).await),
446            }
447        }
448        // Only a join ends without a store: declined or expired.
449        Ok(None) => match record_ending(&request, &pending) {
450            Ok(()) => remove_unfinished(&device_entries, &pending, Ok(None)),
451            Err(error) => Err(error),
452        },
453        Err(error) => match &request {
454            BootstrapRequest::Restore { .. } => {
455                restore::ended(&builder, &pending, &device_entries, error).await
456            }
457            BootstrapRequest::Join { .. } if matches!(error, BootstrapError::Cancelled) => {
458                match record_ending(&request, &pending) {
459                    Ok(()) => remove_unfinished(&device_entries, &pending, Err(error)),
460                    Err(recording) => combine(Err(error), Err(recording)),
461                }
462            }
463            // Before its admission nothing ends a join but its outcome: it
464            // stays listed for the next call (§13.2).
465            BootstrapRequest::Join { .. } => Err(error),
466        },
467    }
468}
469
470/// A published join no longer needs its saved code, nor a published restore
471/// its record: `delete` deletes it. Failing to is reported with the open
472/// handle, as other failures after publication are.
473fn forget_kept(
474    result: Result<CovenHandle, BootstrapError>,
475    delete: impl FnOnce() -> Result<(), KeyError>,
476) -> Result<CovenHandle, BootstrapError> {
477    let (handle, published) = match result {
478        Ok(handle) => (handle, None),
479        Err(BootstrapError::Published { handle, source }) => (handle, Some(*source)),
480        Err(error) => return Err(error),
481    };
482    let deleted = delete().map_err(BootstrapError::from);
483    match (published.map_or(Ok(()), Err), deleted) {
484        (Ok(()), Ok(())) => Ok(handle),
485        (failed, deleted) => Err(BootstrapError::Published {
486            handle,
487            source: Box::new(combine(failed, deleted).expect_err("a failure")),
488        }),
489    }
490}
491
492/// Where a new installation loads: a new device's unpublished store, or the
493/// replacement of this device's installation (§19.3).
494#[derive(Clone, Copy)]
495enum Installing<'a> {
496    New(&'a BootstrapStore),
497    Replacing(&'a ReplacementStore),
498}
499
500impl Installing<'_> {
501    fn directory(&self) -> StoreDir {
502        match self {
503            Self::New(pending) => pending.directory(),
504            Self::Replacing(replacement) => replacement.directory(),
505        }
506    }
507}
508
509enum Admission {
510    Restoring,
511    Joining(join::InviteJoin),
512}
513
514impl Admission {
515    /// Once a join's request may have been sent, cancelling can't take it
516    /// back: approval could land after its keys were thrown away, leaving a
517    /// member no device can act as (§13.2). The join stays unfinished.
518    fn cancellable<T>(&self, result: Result<T, BootstrapError>) -> Result<T, BootstrapError> {
519        match (result, self) {
520            (Err(BootstrapError::Cancelled), Self::Joining(joining)) if joining.sent() => {
521                Err(BootstrapError::JoinRequestSent)
522            }
523            (result, _) => result,
524        }
525    }
526
527    /// Whether a join may have accepted the share without sending its
528    /// request.
529    fn accepted(&self) -> bool {
530        matches!(self, Self::Joining(joining) if joining.accepted())
531    }
532
533    /// A join cancelled before sending takes back the acceptance it recorded
534    /// before it is removed. An undo that fails fails the cancel, and the
535    /// join stays listed for another (§13.2).
536    async fn leave_cancelled<T>(
537        &self,
538        sync: &SequenceSync,
539        result: Result<T, BootstrapError>,
540    ) -> Result<T, BootstrapError> {
541        match (result, self) {
542            (Err(BootstrapError::Cancelled), Self::Joining(joining)) if joining.accepted() => {
543                combine(Err(BootstrapError::Cancelled), joining.leave(sync).await)
544            }
545            (result, _) => result,
546        }
547    }
548}
549
550/// What a new installation does once what it reads from storage is read.
551enum Finishing {
552    /// A join that found its admission, which registered its device,
553    /// publishes the store, recording `labelled`, the location as the
554    /// joining account names it; the store loads after (§13.2).
555    Publish { labelled: StorageConfig },
556    /// A restore or replacement, loaded, registers its device unless an
557    /// interrupted call's registration is `registered` already, and records
558    /// `access`, the access it reaches storage with (§13.1, §19.3).
559    Register { access: coven_format::MemberAccess, registered: bool, labelled: StorageConfig },
560}
561
562/// A loaded store awaiting publication, with what reaches its storage.
563struct Loaded {
564    code: RestoreCode,
565    /// The location as loading's connection labelled it, which the commit
566    /// records (§20.2).
567    location: StorageConfig,
568    credentials: StorageCredentials,
569    sign_in: SignInCustody,
570    ring: StoreKeyring,
571    database: StoreDatabase,
572    storage: Arc<coven_storage::StorageConnection>,
573    /// The sequence state the handle continues, which gates the connection.
574    state: Arc<coven_sync::SequenceState>,
575    waits: Arc<coven_sync::RetryWaits>,
576}
577
578/// Load the store into `pending` and register its device. A join loads
579/// nothing here: once it finds its admission, which registered its device,
580/// it returns the store to publish, which loads after (§13.2). A replacement
581/// runs the app's `prepare` step on its loaded installation, then keeps what
582/// finishing needs and records itself, before it registers (§19.3).
583async fn prepare_and_load(
584    builder: &mut CovenBuilder,
585    pending: Installing<'_>,
586    request: &BootstrapRequest,
587    prepare: Option<replace::Prepare>,
588    status: &impl Fn(BootstrapStatus),
589    cancel: &watch::Receiver<bool>,
590) -> Result<Option<Loaded>, BootstrapError> {
591    let directory = pending.directory();
592    let (member, mut data, mut sign_in, device_name, mut admission) = match request {
593        BootstrapRequest::Restore { code, data, sign_in, name } => (
594            MemberIdentity::new(code.member, code.member_keys.clone()),
595            data.clone(),
596            sign_in.clone(),
597            name.clone(),
598            Admission::Restoring,
599        ),
600        BootstrapRequest::Join { code, terms, held, parks } => {
601            let (joining, data, sign_in) = join::prepare_request(
602                builder,
603                &directory,
604                code,
605                terms,
606                held.clone(),
607                parks.clone(),
608            )
609            .await?;
610            (
611                joining.identity(),
612                data,
613                sign_in,
614                joining.device_name().to_owned(),
615                Admission::Joining(joining),
616            )
617        }
618    };
619    // A join that may have accepted the share connects even when cancelled
620    // already, so its cancel can take the acceptance back (§13.2).
621    if !admission.accepted() {
622        admission.cancellable(check_cancel(cancel))?;
623    }
624    // A restore records itself before it registers: a new device's (§13.1),
625    // and a replacement of this device's installation (§19.3).
626    let recording = match (request, pending) {
627        (BootstrapRequest::Restore { code, name, .. }, Installing::New(_)) => {
628            Some(restore::Recording::new(builder, code.store, name)?)
629        }
630        (BootstrapRequest::Restore { code, name, .. }, Installing::Replacing(_)) => {
631            Some(restore::Recording::replacement(builder, code.store, name)?)
632        }
633        _ => None,
634    };
635    let mut prepare = prepare;
636    let provider = data.location.provider();
637    let settings = directory.settings().map_err(CovenError::from)?;
638    let state = Arc::new(coven_sync::SequenceState::new());
639    let ring = Arc::new(KeySession::open(Arc::new(InMemoryCustody::<StoreKeyring>::empty()))?);
640    let identity = Arc::new(KeySession::open(Arc::new(InMemoryCustody::new(member.clone())))?);
641    // A replacement registers the fresh id as the old one's replacement.
642    let replacement = match pending {
643        Installing::Replacing(replacement) => Some(replacement),
644        Installing::New(_) => None,
645    };
646    // The database opens before connecting: its persisted waits and provider
647    // cooldown hold the joiner's polls and every request across restarts (§6.7).
648    let clock = builder.clock.clone();
649    let database = open_installation(builder.database(directory.clone())?, status).await?;
650    status(BootstrapStatus::Connecting);
651    let connected = async {
652        let connecting = clock.elapsed();
653        let waits = Arc::new(
654            coven_sync::RetryWaits::open(database.clone(), builder.clock.clone())
655                .await
656                .map_err(CovenError::from)?,
657        );
658        let storage =
659            connect_storage(builder, &mut data, &sign_in, settings.device_id, &state, &waits)
660                .await?;
661        if matches!(admission, Admission::Restoring) {
662            storage.check_location_claim(settings.id).await.map_err(SyncError::from)?;
663        }
664        tracing::info!(
665            ?provider,
666            time = ?(clock.elapsed() - connecting),
667            requests = %storage.requests(),
668            "connected to storage"
669        );
670        // The loading owner's transfers end with loading; the handle's start
671        // with the handle.
672        let files = coven_sync::Files::new(
673            coven_database::FileDatabase::new(database.clone()),
674            directory.clone(),
675            None,
676            state.clone(),
677            waits.clone(),
678            builder.ids.clone(),
679            builder.transfers.clone(),
680            builder.files.clone(),
681            clock.clone(),
682            coven_foundation::network_watch::NetworkWatch::unwatched().view(),
683        );
684        let sync = SequenceSync::open(
685            database.clone(),
686            storage.clone(),
687            directory.clone(),
688            settings.device_id,
689            ring.clone(),
690            identity,
691            Arc::new(PersonEntries::new(builder.keychain()?, settings.id)),
692            state.clone(),
693            builder.clock.clone(),
694            builder.ids.clone(),
695            waits.clone(),
696            files.clone(),
697        )
698        .await;
699        match sync {
700            Ok(sync) => Ok::<_, BootstrapError>((waits, storage, files, Arc::new(sync))),
701            Err(error) => {
702                files.close().await;
703                Err(error.into())
704            }
705        }
706    }
707    .await;
708    let (waits, storage, files, sync) = match connected {
709        Ok(connected) => connected,
710        Err(error) => {
711            return combine(sign_in.refused(provider, Err(error)), close_database(&database).await)
712        }
713    };
714    #[cfg(test)]
715    if let Some(recorder) = &builder.loading_recorder {
716        recorder.watch_progress(sync.subscribe_progress());
717    }
718    // The location as the joining account names it, read once the share is
719    // accepted (§20.2): the store a join publishes records it, and no storage
720    // request comes between finding the admission and publishing (§13.2).
721    let approval = coven_sync::ApprovalWaits::new(database.clone(), waits.clone(), clock.clone());
722    let mut accepted_label = None;
723    let loading = async {
724        if let Admission::Joining(joining) = &mut admission {
725            if !joining.accept(&sync, status).await? {
726                return Ok(None);
727            }
728            let labelled = storage.labelled_config().await.map_err(SyncError::from)?;
729            accepted_label = Some(labelled.clone());
730            if !joining.admit(&sync, &approval, &database, status).await? {
731                return Ok(None);
732            }
733            // Its admission found, which registered its device, the join
734            // publishes the store, which loads after (§13.2): nothing is
735            // left to register, and no access to record.
736            return Ok(Some(Finishing::Publish { labelled }));
737        }
738        // Reading forward opens this member's copies and loads the floor's
739        // snapshots and the slots after them; an interrupted bootstrap's
740        // registration is already applied.
741        let unlocking = (clock.elapsed(), storage.requests());
742        loading(&sync, sync.unlock(), status).await?;
743        tracing::info!(
744            time = ?(clock.elapsed() - unlocking.0),
745            requests = %storage.requests().since(&unlocking.1),
746            "read the store forward with this member's keys"
747        );
748        // The folder's label as this member's account names it (§20.2).
749        let labelled = storage.labelled_config().await.map_err(SyncError::from)?;
750        let registered = database
751            .store_state()
752            .await?
753            .devices
754            .get(&settings.device_id)
755            .is_some_and(|device| device.member == member.member());
756        // A restore checks the access it reaches storage with before it
757        // registers, and records it after, as setup does, so the member's
758        // recorded access is the one in use (§13.1).
759        status(BootstrapStatus::Registering);
760        let access = crate::storage::member_access(&data.credentials, &storage)
761            .await
762            .map_err(SyncError::from)?;
763        sync.check_access(&access).await?;
764        Ok::<_, BootstrapError>(Some(Finishing::Register { access, registered, labelled }))
765    };
766    let mut cancellation = cancel.clone();
767    let loaded = tokio::select! {
768        biased;
769        _ = cancelled(&mut cancellation) => Err(BootstrapError::Cancelled),
770        result = loading => result,
771    };
772    // A join whose keys opened in this call has found its admission, which
773    // registered its device: it publishes the store, cancelled or not, since
774    // nothing is left for a cancel to take back (§13.2).
775    let loaded = match (loaded, &admission, accepted_label) {
776        (Err(BootstrapError::Cancelled), Admission::Joining(_), Some(labelled))
777            if ring.read()?.is_some() =>
778        {
779            Ok(Some(Finishing::Publish { labelled }))
780        }
781        (loaded, ..) => loaded,
782    };
783    let result = match loaded {
784        // A join that found its admission has nothing left to write.
785        Ok(Some(Finishing::Publish { labelled })) => {
786            data.location = labelled;
787            Ok(true)
788        }
789        Ok(Some(Finishing::Register { access, registered, labelled })) => {
790            data.location = labelled;
791            // The work that writes to storage. A cancel stops it only between
792            // its steps: one under way, a registration on its way above all,
793            // runs to its end first (§11.6).
794            let registering = async {
795                if !registered {
796                    check_cancel(cancel)?;
797                    match (replacement, &recording) {
798                        (Some(replacement), Some(recording)) => {
799                            sign_in = replace::record_replacement(
800                                replacement,
801                                recording,
802                                &database,
803                                prepare.take(),
804                                (&member, settings.id, &data),
805                                sign_in.clone(),
806                            )
807                            .await?;
808                        }
809                        (None, Some(recording)) => {
810                            sign_in =
811                                recording.record(&member, settings.id, &data, sign_in.clone())?;
812                        }
813                        _ => {}
814                    }
815                    // A copy that found its id in use leaves the old id to the
816                    // installation that kept it (§19.3).
817                    let replaces =
818                        replacement.and_then(|replacement| match replacement.registration() {
819                            Registration::ReplacesOld => {
820                                Some(replacement.device_reset().old_device)
821                            }
822                            Registration::NewDevice => None,
823                        });
824                    let registering = (clock.elapsed(), storage.requests());
825                    sync.register_device(device_name, replaces).await?;
826                    tracing::info!(
827                        time = ?(clock.elapsed() - registering.0),
828                        requests = %storage.requests().since(&registering.1),
829                        "registered this device"
830                    );
831                }
832                let state = database.store_state().await?;
833                if let Some(change) =
834                    crate::storage::access_change(&state, member.member(), access)?
835                {
836                    check_cancel(cancel)?;
837                    sync.administer(change).await?;
838                }
839                // The notice commits before any handle is published (E5).
840                if let Some(replacement) = replacement {
841                    check_cancel(cancel)?;
842                    #[cfg(test)]
843                    if builder.fail_device_reset_notice {
844                        database.test_fail_device_reset().await.map_err(CovenError::from)?;
845                    }
846                    reset::carry_discarded_provider_work(&sync, &database, replacement).await?;
847                }
848                Ok::<_, BootstrapError>(true)
849            };
850            tokio::pin!(registering);
851            let ended = tokio::select! {
852                biased;
853                _ = cancelled(&mut cancellation) => None,
854                result = &mut registering => Some(result),
855            };
856            match ended {
857                Some(result) => result,
858                None => match registering.await {
859                    Err(error) if crate::task::CarriesBug::bug(&error).is_some() => Err(error),
860                    _ => Err(BootstrapError::Cancelled),
861                },
862            }
863        }
864        Ok(None) => Ok(false),
865        Err(error) => Err(error),
866    };
867    let result = admission.leave_cancelled(&sync, admission.cancellable(result)).await;
868    let result = sign_in.refused(provider, result);
869    files.close().await;
870    drop(sync);
871    let result = result.and_then(|loaded| {
872        if !loaded {
873            return Ok(None);
874        }
875        let ring = ring.read()?.ok_or(SyncError::from(StorageFailure::MemberKeysMissing))?;
876        Ok(Some((
877            coven_sync::location_code(settings.id, &member, data.location.clone())?,
878            data.location,
879            data.credentials,
880            ring,
881        )))
882    });
883    match result {
884        Ok(Some((code, location, credentials, ring))) => Ok(Some(Loaded {
885            code,
886            location,
887            credentials,
888            sign_in,
889            ring,
890            database,
891            storage,
892            state,
893            waits,
894        })),
895        result => {
896            let closed = close_database(&database).await;
897            combine(result.map(|_| None), closed)
898        }
899    }
900}
901
902fn check_cancel(cancel: &watch::Receiver<bool>) -> Result<(), BootstrapError> {
903    if *cancel.borrow() {
904        Err(BootstrapError::Cancelled)
905    } else {
906        Ok(())
907    }
908}
909
910async fn cancelled(cancel: &mut watch::Receiver<bool>) {
911    loop {
912        if *cancel.borrow_and_update() {
913            return;
914        }
915        if cancel.changed().await.is_err() {
916            std::future::pending::<()>().await;
917        }
918    }
919}
920
921/// Close the installation's database; its failure is the bootstrap's.
922async fn close_database(database: &StoreDatabase) -> Result<(), BootstrapError> {
923    database.close().await.map_err(CovenError::from).map_err(BootstrapError::from)
924}
925
926fn combine<T>(
927    result: Result<T, BootstrapError>,
928    cleanup: Result<(), BootstrapError>,
929) -> Result<T, BootstrapError> {
930    match (result, cleanup) {
931        (result, Ok(())) => result,
932        (Ok(_), Err(error)) => Err(error),
933        (Err(operation), Err(cleanup)) => Err(BootstrapError::Cleanup {
934            operation: Box::new(operation),
935            cleanup: Box::new(cleanup),
936        }),
937    }
938}
939
940/// Every entry under `path` with its contents, sorted, so a test can show
941/// that a refused replacement changed nothing. Lock files (`.<id>.lock`) and
942/// SQLite `-shm` files are left out: they hold no row or key, and Windows
943/// locks them while a store is open, so reading one fails with a lock
944/// violation (OS error 33).
945#[cfg(test)]
946fn files_under(path: &std::path::Path) -> Vec<(std::path::PathBuf, Option<Vec<u8>>)> {
947    let mut found = Vec::new();
948    for entry in std::fs::read_dir(path).unwrap_or_else(|error| panic!("list {path:?}: {error}")) {
949        let entry = entry.unwrap();
950        let relative = std::path::PathBuf::from(entry.file_name());
951        let name = entry.file_name().to_string_lossy().into_owned();
952        if name.ends_with(".lock") || name.ends_with("-shm") {
953            continue;
954        }
955        if entry.file_type().unwrap().is_dir() {
956            found.extend(
957                files_under(&entry.path())
958                    .into_iter()
959                    .map(|(inner, bytes)| (relative.join(inner), bytes)),
960            );
961            found.push((relative, None));
962        } else {
963            let bytes = std::fs::read(entry.path())
964                .unwrap_or_else(|error| panic!("read {:?}: {error}", entry.path()));
965            found.push((relative, Some(bytes)));
966        }
967    }
968    found.sort();
969    found
970}
971
972#[cfg(test)]
973#[path = "bootstrap_tests.rs"]
974mod tests;