Skip to main content

coven_sync/
operation_types.rs

1//! Application values for operations, members, circles and invitations (api.md).
2
3use coven_crypto::SecretText;
4use coven_foundation::id_source::{InviteId, MemberId};
5use std::time::{Duration, SystemTime};
6
7pub use coven_database::{
8    Circle, CircleMemberInfo, DeviceInfo, DeviceState, MemberInfo, OperationId,
9};
10/// An operation failure retains the same typed causes as an ordinary sync call.
11pub type OperationError = crate::SyncError;
12
13/// The purpose of an unfinished operation, including maintenance.
14#[derive(
15    Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
16)]
17pub enum OperationKind {
18    /// Create the store's first slot.
19    CreateStore,
20    /// Record how the store's first admin reaches storage, which fixes how
21    /// every member does (§10.3).
22    SetUpStorage,
23    /// Set the store name.
24    RenameStore,
25    /// Register this installation.
26    AddDevice,
27    /// Set a member's role.
28    SetRole,
29    /// Replace provider access.
30    SetAccess,
31    /// Remove a member.
32    RemoveMember,
33    /// Remove an installation.
34    RemoveDevice,
35    /// Rename a circle.
36    RenameCircle,
37    /// Remove a circle member.
38    RemoveCircleMember,
39    /// Advance the floor and delete the covered prefix.
40    RetainSequence,
41    /// Delete unreferenced files after establishing retained-object protection.
42    RetainFiles,
43    /// Write and verify a maintenance snapshot.
44    WriteSnapshot,
45    /// Publish the app's migrated schema and its audience snapshots.
46    SchemaChange,
47    /// Snapshot this device and reset one audience to that state.
48    Reset,
49    /// Reload snapshots at the app's request, keeping waiting writes.
50    ReloadFromSnapshot,
51    /// Reload what sync requires: a changed schema or reset, a returning
52    /// circle, joining or recovery.
53    RequiredReload,
54    /// Publish a fresh audience key and its sealed copies.
55    RotateKey,
56    /// Send an older audience key to a current member whose sealing key has
57    /// no copy of it.
58    SendKeyCopy,
59    /// Create a circle and its first key.
60    CreateCircle,
61    /// Seal a circle's history to a member.
62    AddCircleMember,
63    /// Publish a circle's deletion; its rows are taken out from that slot
64    /// (§15.9).
65    DeleteCircle,
66    /// Share storage and settle an invitation: record the invite's share
67    /// and its end (§13.2).
68    Invite,
69    /// Claim an approved join request's admission, which admits the member
70    /// or rebinds their pair, and registers the request's device (§13.2).
71    ApproveJoin,
72    /// Look for a pairing's request, put its handover or marker in the
73    /// request's place (§13.2).
74    Pairing,
75    /// Align one provider account's grants with members and open invitations.
76    RevokeAccess,
77    /// Replace a member's signing and sealing pair: this member's own, with a
78    /// candidate kept in identity custody, or a prepared pair as an admin (§10).
79    ReplaceMemberKeys,
80    /// Set up storage on this device: check the provider, then create the
81    /// store or reconnect to it (§11.6, §20.8).
82    StorageSetup,
83}
84
85impl OperationKind {
86    /// The purpose of the operation that claims `change`.
87    pub(crate) fn of(change: &coven_format::admin::StoreChange) -> Self {
88        use coven_format::admin::StoreChange;
89        use OperationKind as K;
90        match change {
91            StoreChange::CreateStore { .. } => K::CreateStore,
92            StoreChange::SetUpStorage { .. } => K::SetUpStorage,
93            StoreChange::RenameStore { .. } => K::RenameStore,
94            StoreChange::AdmitMember { .. } | StoreChange::RecoverMember { .. } => K::ApproveJoin,
95            StoreChange::AddInviteShare { .. } | StoreChange::EndInviteShare { .. } => K::Invite,
96            StoreChange::RemoveMember { .. } => K::RemoveMember,
97            StoreChange::ChangeRole { .. } => K::SetRole,
98            StoreChange::SetAccess { .. } => K::SetAccess,
99            StoreChange::ReplaceMemberKeys { .. } => K::ReplaceMemberKeys,
100            StoreChange::AddDevice { .. } => K::AddDevice,
101            StoreChange::RemoveDevice { .. } => K::RemoveDevice,
102            StoreChange::CreateCircle { .. } => K::CreateCircle,
103            StoreChange::RenameCircle { .. } => K::RenameCircle,
104            StoreChange::DeleteCircle { .. } => K::DeleteCircle,
105            StoreChange::AddCircleMember { .. } => K::AddCircleMember,
106            StoreChange::RemoveCircleMember { .. } => K::RemoveCircleMember,
107            StoreChange::RotateKey { .. } => K::RotateKey,
108            StoreChange::RaiseSchema { .. } => K::SchemaChange,
109            StoreChange::Reset { .. } => K::Reset,
110        }
111    }
112
113    /// Coven's own work, which no app call retries or discards: a failed
114    /// attempt retries under the shared backoff (§11, E5).
115    pub(crate) fn coven_owned(self) -> bool {
116        matches!(
117            self,
118            Self::WriteSnapshot
119                | Self::RetainSequence
120                | Self::RetainFiles
121                | Self::RequiredReload
122                | Self::RotateKey
123                | Self::SendKeyCopy
124                | Self::RevokeAccess
125        )
126    }
127}
128
129/// How the invited person reaches the store's provider.
130#[derive(Clone)]
131pub enum InviteAccess {
132    /// Share with the named provider account.
133    ProviderAccount {
134        /// The account's email address.
135        email: String,
136    },
137    /// Credentials created in the S3 console for this invite.
138    S3AccessKey {
139        /// Public key identifier.
140        access_key_id: String,
141        /// The key's secret, carried only in the invitation.
142        secret_access_key: SecretText,
143    },
144    /// The S3 key this device connects with, which coven reads from its
145    /// custody, so the secret never reaches the app (§14.3).
146    HeldS3AccessKey,
147}
148
149/// How long an invite stays open after it is made, by the inviting
150/// device's clock (§13.2).
151#[derive(Clone, Copy, Debug, PartialEq, Eq)]
152pub enum InviteLifetime {
153    /// Seven days.
154    SevenDays,
155    /// Thirty days.
156    ThirtyDays,
157}
158
159impl InviteLifetime {
160    pub(crate) fn duration(self) -> Duration {
161        Duration::from_secs(match self {
162            Self::SevenDays => 7 * 86_400,
163            Self::ThirtyDays => 30 * 86_400,
164        })
165    }
166}
167
168/// One of this device's open invites (§13.2).
169#[derive(Clone, Debug, PartialEq, Eq)]
170pub struct Invite {
171    /// The one-time request path's identity.
172    pub id: InviteId,
173    /// The invite's operation, which names its pending record in
174    /// `coven_pending` while its check or its grant waits or is refused.
175    pub operation: coven_database::OperationId,
176    /// The stable member id the invite fixed.
177    pub member: MemberId,
178    /// Whether the invite admits a new person or a member's new keys.
179    pub admits: coven_format::codes::InviteAdmits,
180    /// The access the invite grants: the account shared with, or the id of
181    /// the S3 key it carries, never its secret (§14.3).
182    pub access: coven_format::MemberAccess,
183    /// The invite's lifetime after creation, on the inviting device's clock.
184    pub expires_at: SystemTime,
185    /// Where the invite is: granting its access, waiting for its request or
186    /// the app's decision, or approving its request.
187    pub stage: InviteStage,
188}
189
190/// Where one of this device's open invites is (§13.2).
191#[derive(Clone, PartialEq, Eq)]
192pub enum InviteStage {
193    /// The app's write made the invite. A pass checks it against the
194    /// history it catches up with and grants its storage access, and then
195    /// it shows its code. A check that refuses it, or a failed grant, is
196    /// its pending record under its operation; cancelling ends it.
197    Granting,
198    /// The code is shown, and the request, once one has arrived and been
199    /// checked, waits for the app to approve or decline it.
200    Waiting {
201        /// Code the app may show as a QR code, again whenever the admin
202        /// asks. Contains secrets.
203        code: String,
204        /// The checked request, once one has arrived.
205        request: Option<JoinRequest>,
206    },
207    /// Approval of this request has begun, and finishes without the app:
208    /// approving, declining or cancelling the invite fail with
209    /// `InvitationChanged`. The approval is the app's own, and
210    /// `coven_operations` lists its binding until the app acknowledges the
211    /// outcome.
212    Approving {
213        /// The code first shown, which the joining device scanned.
214        /// Contains secrets.
215        code: String,
216        /// The request being approved.
217        request: JoinRequest,
218        /// The operation that claims the request's copies and binds its
219        /// pair.
220        binding: coven_database::OperationId,
221    },
222}
223
224impl std::fmt::Debug for InviteStage {
225    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
226        match self {
227            Self::Granting => f.write_str("Granting"),
228            Self::Waiting { request, .. } => f
229                .debug_struct("Waiting")
230                .field("code", &"[REDACTED]")
231                .field("request", request)
232                .finish(),
233            Self::Approving { request, binding, .. } => f
234                .debug_struct("Approving")
235                .field("code", &"[REDACTED]")
236                .field("request", request)
237                .field("binding", binding)
238                .finish(),
239        }
240    }
241}
242
243/// A checked request, presented with the account from its local invitation.
244#[derive(Clone, Debug, PartialEq, Eq)]
245pub struct JoinRequest {
246    /// Invitation being answered.
247    pub invite: InviteId,
248    /// The stable member id the invite fixed and the request repeats.
249    pub member: MemberId,
250    /// The fresh public pair the request's signature proves it holds;
251    /// approval binds exactly this pair to `member` (§13.2).
252    pub keys: coven_crypto::MemberPublicKeys,
253    /// The device's name, covered by its signature.
254    pub device_name: String,
255    /// Who asks: a new person with the name they typed, or a recovery. It
256    /// matches the invite's kind (§13.2).
257    pub joiner: crate::Joiner,
258    /// Account invited by the owner, absent on S3.
259    pub provider_account_email: Option<String>,
260    /// Computed from the invite id and `keys`; the requester's device shows
261    /// the same number (format.md D11).
262    pub confirmation: coven_crypto::ConfirmationNumber,
263    pub(crate) record: Vec<u8>,
264}