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}