Skip to main content

coven_sync/
sequence_member_keys.rs

1//! Replacing a member's signing and sealing pair (§10.1, §12.3, §11.5): this
2//! member's own, which pauses app writes, confirms the queue and keeps a
3//! candidate before claiming its copies and binding, or a prepared public
4//! pair for another member, which is only the entry and its copies.
5
6use super::{sequence_operations::Request, SequenceSync, Session};
7#[cfg(test)]
8use crate::operation_outcome::SettledByPass;
9use crate::sequence_sync::OperationState;
10use crate::{
11    OperationKind, OperationRejection, PendingReason, PendingRecord, PendingSubject, Prerequisite,
12    SyncError,
13};
14use coven_crypto::{MemberIdentity, MemberKeys, MemberPublicKeys, StoreKeyring};
15use coven_database::{NewOperation, OperationId, StoreState};
16use coven_format::admin::StoreChange;
17use coven_foundation::id_source::{DeviceId, MemberId};
18use coven_storage::StorageFailure;
19use serde::{Deserialize, Serialize};
20use std::sync::Arc;
21
22pub(crate) const MEMBER_KEYS: &str = "member-keys";
23
24/// Self-replacement keeps the write pause through the restore-code commit.
25#[derive(Serialize, Deserialize)]
26enum MemberKeysWork {
27    Draining,
28    Replacing(#[serde(with = "crate::pending_encoding::public_keys")] MemberPublicKeys),
29    RefreshingCode,
30}
31impl OperationState for MemberKeysWork {}
32
33/// This member's held active pair, or its kept candidate, must be its
34/// current binding: only those sign or install the replacement (§12.3).
35fn held_current(session: &Session, identity: &MemberIdentity) -> Result<(), SyncError> {
36    match session.history.state.members.get(&identity.member()) {
37        None => Err(SyncError::Rejected(OperationRejection::TargetGone(
38            crate::EntryTarget::Member(identity.member()),
39        ))),
40        Some(current) if current.removed => {
41            Err(SyncError::Removed(coven_database::Removal::Member))
42        }
43        Some(current)
44            if current.keys == identity.keys().public_keys()
45                || identity.candidate().is_some_and(|keys| keys.public_keys() == current.keys) =>
46        {
47            Ok(())
48        }
49        Some(_) => Err(SyncError::MemberKeysReplaced { member: identity.member() }),
50    }
51}
52
53/// This device's member, while the applied state has both active and binds
54/// the member to the pair this installation holds, or its kept candidate:
55/// only then does it author admin entries (§10, §12.3). A replaced binding
56/// fails with `MemberKeysReplaced`, as the pass that applied it reported.
57pub(crate) fn registered(
58    applied: &StoreState,
59    device: DeviceId,
60    held: &MemberIdentity,
61) -> Result<MemberId, SyncError> {
62    let member = applied.devices.get(&device).filter(|registered| registered.active()).and_then(
63        |registered| applied.active_member(&registered.member).map(|m| (registered.member, m)),
64    );
65    let Some((id, member)) = member else {
66        return Err(SyncError::Rejected(OperationRejection::NotAllowed));
67    };
68    if member.keys != held.keys().public_keys()
69        && held.candidate().map(|keys| keys.public_keys()) != Some(member.keys)
70    {
71        return Err(SyncError::MemberKeysReplaced { member: id });
72    }
73    Ok(id)
74}
75
76impl SequenceSync {
77    /// Replace this member's own pair and return the installed identity.
78    /// App writes wait with `MemberKeysChanging` until the binding applies
79    /// and identity and restore-code custody finish, or replacement fails (§12.3, E9).
80    pub async fn replace_member_keys(self: &Arc<Self>) -> Result<MemberIdentity, SyncError> {
81        let mut session = self.session.lock().await;
82        let identity = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
83        let mut ring = self.ring(&mut session, &identity).await?;
84        self.read_forward(&mut session, &mut ring, &identity).await?;
85        self.settle_open(&mut session, &mut ring, &identity).await?;
86        if !self.registered(&session) {
87            return Err(SyncError::Rejected(OperationRejection::NotAllowed));
88        }
89        let id = match self
90            .database
91            .operations()
92            .await?
93            .into_iter()
94            .find(|record| record.kind == MEMBER_KEYS)
95        {
96            Some(record) => record.id,
97            None => {
98                held_current(&session, &identity)?;
99                self.database
100                    .start_operation(NewOperation {
101                        kind: MEMBER_KEYS.into(),
102                        data: serde_json::to_vec(&MemberKeysWork::Draining)?,
103                        started_by: "replace_member_keys".into(),
104                        pauses_writes: true,
105                    })
106                    .await?
107            }
108        };
109        match self.advance_member_keys(&mut session, &mut ring, id).await {
110            Ok(Some(identity)) => Ok(identity),
111            Ok(None) => unreachable!("a self-replacement call runs to its binding"),
112            Err(error) => {
113                if self.database.operation(id).await?.is_some() {
114                    self.record_operation_error(
115                        id,
116                        OperationKind::ReplaceMemberKeys,
117                        crate::sequence_sync::OperationFailure::Returned(&error),
118                        &ring,
119                    )
120                    .await?;
121                }
122                Err(error)
123            }
124        }
125    }
126
127    /// Complete code custody before releasing this replacement's write pause.
128    /// Background attempts honor the operation's wait; its initiating call
129    /// reaches this step immediately after installing the selected identity.
130    pub(crate) async fn finish_member_keys(
131        &self,
132        foreground: bool,
133        refresh: impl FnOnce(
134            &MemberIdentity,
135            &coven_database::StoreIdentity,
136        ) -> Result<coven_crypto::SecretText, SyncError>,
137    ) -> Result<Option<coven_crypto::SecretText>, SyncError> {
138        let mut session = self.session.lock().await;
139        let Some(record) =
140            self.database.operations().await?.into_iter().find(|record| record.kind == MEMBER_KEYS)
141        else {
142            return Ok(None);
143        };
144        let work: MemberKeysWork = serde_json::from_slice(&record.data)?;
145        if !matches!(work, MemberKeysWork::RefreshingCode) {
146            return Ok(None);
147        }
148        let identity = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
149        let ring = self.ring(&mut session, &identity).await?;
150        if !foreground && !self.operation_ready(&record, &ring).await? {
151            return Ok(None);
152        }
153        let store = session.history.state.store.as_ref().ok_or(SyncError::NoStorage)?;
154        match refresh(&identity, store) {
155            Ok(code) => {
156                self.database.finish_operation(record.id).await?;
157                self.waits.operation_advanced(record.id);
158                Ok(Some(code))
159            }
160            Err(error) => {
161                self.record_operation_error(
162                    record.id,
163                    OperationKind::ReplaceMemberKeys,
164                    crate::sequence_sync::OperationFailure::Returned(&error),
165                    &ring,
166                )
167                .await?;
168                Err(error)
169            }
170        }
171    }
172
173    /// Resume an interrupted self-replacement in a pass.
174    pub(crate) async fn resume_member_keys(
175        &self,
176        session: &mut Session,
177        ring: &mut StoreKeyring,
178    ) -> Result<(), SyncError> {
179        for record in self.database.operations().await? {
180            if record.kind != MEMBER_KEYS || !self.operation_ready(&record, ring).await? {
181                continue;
182            }
183            let scope = self.waits.begin_attempt(record.id);
184            let result = coven_database::in_commit_scope(
185                scope,
186                self.advance_member_keys(session, ring, record.id),
187            )
188            .await;
189            self.settle_resumed(
190                record.id,
191                OperationKind::ReplaceMemberKeys,
192                result.map(drop),
193                ring,
194            )
195            .await?;
196        }
197        Ok(())
198    }
199
200    async fn advance_member_keys(
201        &self,
202        session: &mut Session,
203        ring: &mut StoreKeyring,
204        id: OperationId,
205    ) -> Result<Option<MemberIdentity>, SyncError> {
206        loop {
207            let record = self.database.operation(id).await?.ok_or(SyncError::NotPending(id))?;
208            let mut work: MemberKeysWork = serde_json::from_slice(&record.data)?;
209            let identity = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
210            let candidate = match work {
211                MemberKeysWork::RefreshingCode => return Ok(Some(identity)),
212                MemberKeysWork::Replacing(candidate) => Some(candidate),
213                MemberKeysWork::Draining => None,
214            };
215            let Some(candidate) = candidate else {
216                // Writes fixed under the pair about to be retired must reach
217                // storage first: after the binding they count for nothing (§12.3).
218                if let Some(through) = self.database.sendable_through().await? {
219                    self.send_writes(session, ring, &identity, through).await?;
220                    if self.database.waiting_snapshot_headers().await?.last().is_some() {
221                        return Err(SyncError::Pending(Box::new(PendingRecord::new(
222                            PendingSubject::Operation {
223                                id,
224                                kind: OperationKind::ReplaceMemberKeys,
225                            },
226                            PendingReason::Waits(Prerequisite::SequenceCatchUp),
227                        ))));
228                    }
229                }
230                held_current(session, &identity)?;
231                let candidate = match identity.candidate() {
232                    Some(candidate) => candidate.public_keys(),
233                    None => {
234                        let candidate = MemberKeys::generate()?;
235                        let keys = candidate.public_keys();
236                        // Recorded before custody keeps it, so no binding to
237                        // it can apply unrecorded (§12.3).
238                        self.database.hold_member_keys(vec![keys]).await?;
239                        self.member.persist(&identity.with_candidate(candidate))?;
240                        keys
241                    }
242                };
243                work = MemberKeysWork::Replacing(candidate);
244                self.database.advance_operation(work.update(&record)?).await?;
245                continue;
246            };
247            let current =
248                session.history.state.members.get(&identity.member()).map(|value| value.keys);
249            if current == Some(candidate) {
250                // The binding applied: install its pair, keeping the previous
251                // one for copies that name it (§12.3). Code custody still owns the pause.
252                let installed = identity
253                    .activate(&candidate)
254                    .ok_or(SyncError::MemberKeysReplaced { member: identity.member() })?;
255                self.member.persist(&installed)?;
256                self.database
257                    .advance_operation(MemberKeysWork::RefreshingCode.update(&record)?)
258                    .await?;
259                return Ok(Some(installed));
260            }
261            let change = StoreChange::ReplaceMemberKeys {
262                member: identity.member(),
263                expected: identity.keys().public_keys(),
264                keys: candidate,
265            };
266            match self
267                .start_request(session, ring, &identity, Request::Change(change), MEMBER_KEYS)
268                .await
269                .and_then(crate::operation_outcome::EntryOutcome::into_slot)
270            {
271                Ok(_) => continue,
272                Err(SyncError::Rejected(reason)) => {
273                    // Contention may have installed an unheld pair or this
274                    // candidate. Neither permits releasing the pause here (§12.3).
275                    held_current(session, &identity)?;
276                    if session.history.state.members[&identity.member()].keys == candidate {
277                        continue;
278                    }
279                    // A replacement that never became current leaves its
280                    // copies, so its pair stays held as retired (§12.3).
281                    self.member.persist(&identity.retire_candidate())?;
282                    self.database.finish_operation(id).await?;
283                    return Err(SyncError::Rejected(reason));
284                }
285                Err(error) => return Err(error),
286            }
287        }
288    }
289}
290
291#[cfg(test)]
292impl SequenceSync {
293    /// Publish a prepared public pair for another active member, journaled
294    /// by the app's write step, then run a pass that settles it, returning
295    /// its rejection as the error.
296    pub(crate) async fn replace_member_keys_for(
297        &self,
298        member: coven_foundation::id_source::MemberId,
299        keys: MemberPublicKeys,
300    ) -> Result<(), SyncError> {
301        let steps = self.operation_steps();
302        let outcome: Option<crate::FreshChangeOutcome> = self
303            .journal_and_pass(move |sql| steps.replace_member_keys_for(sql, member, keys))
304            .await?;
305        outcome.map_or(Ok(()), SettledByPass::settled)
306    }
307}
308
309#[cfg(test)]
310#[path = "sequence_member_keys_tests.rs"]
311mod tests;