1use crate::request_at::{Placed, RequestAt};
4use crate::{Joiner, SyncError};
5use coven_crypto::{
6 CircleKey, ConfirmationNumber, EncryptionKey, InviteSecret, MemberIdentity, MemberKeys,
7 ObjectHasher,
8};
9use coven_format::invite_end::InviteEnd;
10use coven_format::{
11 admin::NewCircle,
12 codes::InviteCode,
13 objects::{JoinRequest, JoiningCircle},
14 sealed_key::{CopyBox, KeyCopyPrefix},
15 sealed_single::{SingleChunkObject, SingleChunkPrefix},
16 sealed_slot::SlotObjectPrefix,
17 Object,
18};
19use coven_foundation::files::StoreDirAccess;
20use coven_foundation::files::{AtomicFile, StoreDir, StoreFile};
21use coven_foundation::id_source::{CircleId, DeviceId, IdSource, KeyId};
22use coven_storage::{ObjectPath, Storage, StorageFailure};
23use zeroize::Zeroizing;
24
25pub fn sealed_join_request(
28 secret: &InviteSecret,
29 path: &ObjectPath,
30 request: &JoinRequest,
31 signer: &MemberKeys,
32) -> Result<Vec<u8>, SyncError> {
33 let prefix = SingleChunkPrefix::JoinRequest;
34 let plain = Object::JoinRequest(request.clone()).encode()?;
35 let chunk = secret.join_request_key().seal_object_chunk(
36 path.as_str(),
37 &prefix.encode()?,
38 0,
39 0,
40 &plain,
41 )?;
42 let mut hash = ObjectHasher::new();
43 hash.update(&prefix.encode_chunk(&chunk)?);
44 Ok(SingleChunkObject::JoinRequest {
45 chunk: &chunk,
46 signature: signer.sign_object(path.as_str(), &hash.finish()),
47 }
48 .encode()?)
49}
50
51pub(crate) fn opened_join_request(
56 secret: &InviteSecret,
57 path: &ObjectPath,
58 bytes: &[u8],
59) -> Result<Option<(JoinRequest, Vec<u8>)>, SyncError> {
60 let envelope = SingleChunkObject::decode(bytes)?;
61 let SingleChunkObject::JoinRequest { chunk, signature } = &envelope;
62 let plain = secret.join_request_key().open_object_chunk(
63 path.as_str(),
64 &envelope.prefix().encode()?,
65 0,
66 0,
67 chunk,
68 )?;
69 let Object::JoinRequest(request) = Object::decode(&plain)? else {
70 return Ok(None);
71 };
72 let mut hash = ObjectHasher::new();
73 hash.update(&envelope.signed_bytes()?);
74 request.keys.signing.verify_object(path.as_str(), &hash.finish(), signature)?;
75 Ok(Some((request, plain)))
76}
77
78#[derive(Clone, Debug, PartialEq, Eq)]
81pub struct CircleTerms {
82 pub name: String,
84 pub breaking_version: u32,
87}
88
89pub struct JoiningIdentity {
96 file: AtomicFile,
99 identity: MemberIdentity,
100 request: Vec<u8>,
101 path: ObjectPath,
102 state: JoinStage,
103 sealing: Sealing,
105 device_name: String,
107 joiner: Joiner,
109 circle: JoiningCircle,
111 inviting_writer: DeviceId,
112 read_through: u64,
113 expires_at: u64,
116 confirmation: ConfirmationNumber,
118}
119
120#[derive(Clone, Copy, Debug, PartialEq, Eq)]
122enum JoinStage {
123 Unsent,
126 Accepted,
130 Sent,
132 Opened,
135 Ended,
139}
140
141impl JoinStage {
142 fn byte(self) -> u8 {
143 match self {
144 Self::Unsent => 0,
145 Self::Accepted => 1,
146 Self::Sent => 2,
147 Self::Opened => 3,
148 Self::Ended => 4,
149 }
150 }
151
152 fn from_byte(byte: u8) -> Option<Self> {
153 match byte {
154 0 => Some(Self::Unsent),
155 1 => Some(Self::Accepted),
156 2 => Some(Self::Sent),
157 3 => Some(Self::Opened),
158 4 => Some(Self::Ended),
159 _ => None,
160 }
161 }
162}
163
164struct Sealing {
167 key: EncryptionKey,
168 binding: Zeroizing<Vec<u8>>,
169 path: String,
170}
171
172impl Sealing {
173 fn new(code: &InviteCode) -> Result<Self, SyncError> {
174 Ok(Self {
175 key: code.secret.join_request_key(),
176 binding: code.to_bytes()?,
177 path: local_path(code),
178 })
179 }
180}
181
182impl JoiningIdentity {
183 pub fn prepare(
191 directory: &StoreDir,
192 code: &InviteCode,
193 device: DeviceId,
194 device_name: &str,
195 name: Option<String>,
196 circle: &CircleTerms,
197 ids: &dyn IdSource,
198 ) -> Result<Self, SyncError> {
199 let joiner = match name {
200 Some(name) => Joiner::NewPerson { name },
201 None => Joiner::MemberKeys,
202 };
203 if joiner.admits() != code.admits {
204 return Err(crate::CodeError::WrongJoiner {
205 expected: code.admits,
206 actual: joiner.admits(),
207 }
208 .into());
209 }
210 match Self::saved(directory, code)? {
211 Some(saved)
212 if saved.device_name != device_name
213 || saved.joiner != joiner
214 || saved.circle.circle.name != circle.name =>
215 {
216 Err(SyncError::InvitationChanged)
217 }
218 Some(saved) => Ok(saved),
219 None => Self::create(directory, code, device, device_name, joiner, circle, ids),
220 }
221 }
222
223 #[cfg(any(test, feature = "test-utils"))]
226 pub fn prepare_for_test(
227 directory: &StoreDir,
228 code: &InviteCode,
229 device: DeviceId,
230 device_name: &str,
231 name: Option<String>,
232 ) -> Result<Self, SyncError> {
233 let circle = CircleTerms { name: "Circle".into(), breaking_version: 0 };
234 Self::prepare(
235 directory,
236 code,
237 device,
238 device_name,
239 name,
240 &circle,
241 &coven_foundation::id_source::UuidIds,
242 )
243 }
244
245 pub fn resume(directory: &StoreDir, code: &InviteCode) -> Result<Self, SyncError> {
249 Self::saved(directory, code)?.ok_or_else(|| coven_database::DbError::DamagedDatabase.into())
250 }
251
252 #[expect(
255 clippy::map_err_ignore,
256 reason = "a request for the member's own device is no invite's, so the invitation changed"
257 )]
258 fn saved(directory: &StoreDir, code: &InviteCode) -> Result<Option<Self>, SyncError> {
259 crate::CodeError::require_store(directory.id(), code.store)?;
260 let file = directory.owned_file(StoreFile::Bootstrap);
261 let sealing = Sealing::new(code)?;
262 let path = code.request_path();
263 let Some(sealed) = file.read_optional()? else {
264 return Ok(None);
265 };
266 let bytes = Zeroizing::new(sealing.key.open_object_chunk(
267 &sealing.path,
268 &sealing.binding,
269 0,
270 0,
271 &sealed,
272 )?);
273 let state = bytes
274 .first()
275 .copied()
276 .and_then(JoinStage::from_byte)
277 .ok_or(coven_database::DbError::DamagedDatabase)?;
278 let key_length = bytes.get(1..5).ok_or(coven_database::DbError::DamagedDatabase)?;
279 let key_length = u32::from_be_bytes(key_length.try_into().expect("four bytes")) as usize;
280 let end = 5usize.checked_add(key_length).ok_or(coven_database::DbError::DamagedDatabase)?;
281 let identity = MemberIdentity::new(
282 code.member,
283 MemberKeys::from_secret_bytes(
284 bytes.get(5..end).ok_or(coven_database::DbError::DamagedDatabase)?,
285 )?,
286 );
287 let keys = identity.keys().public_keys();
288 let request = bytes.get(end..).ok_or(coven_database::DbError::DamagedDatabase)?.to_vec();
289 let (opened, _) = opened_join_request(&code.secret, &path, &request)?
290 .ok_or(coven_database::DbError::DamagedDatabase)?;
291 if opened.invite != code.invite || opened.member != code.member || opened.keys != keys {
292 return Err(SyncError::InvitationChanged);
293 }
294 let circle = opened.joiner.circle().cloned().ok_or(SyncError::InvitationChanged)?;
297 Ok(Some(Self {
298 file,
299 confirmation: ConfirmationNumber::of(code.invite, &keys),
300 identity,
301 request,
302 path,
303 state,
304 sealing,
305 device_name: opened.device_name,
306 joiner: opened.joiner.try_into().map_err(|_| SyncError::InvitationChanged)?,
307 circle,
308 inviting_writer: code.inviting_writer,
309 read_through: code.read_through,
310 expires_at: code.expires_at,
311 }))
312 }
313
314 fn create(
315 directory: &StoreDir,
316 code: &InviteCode,
317 device: DeviceId,
318 device_name: &str,
319 joiner: Joiner,
320 terms: &CircleTerms,
321 ids: &dyn IdSource,
322 ) -> Result<Self, SyncError> {
323 let path = code.request_path();
324 let identity = MemberIdentity::generate(code.member)?;
327 let circle = joining_circle(
328 code.store,
329 code.member,
330 &identity.keys().public_keys().sealing,
331 terms,
332 ids,
333 )?;
334 let request = sealed_join_request(
335 &code.secret,
336 &path,
337 &JoinRequest {
338 invite: code.invite,
339 member: code.member,
340 keys: identity.keys().public_keys(),
341 device,
342 device_name: device_name.into(),
343 joiner: joiner.clone().requesting(circle.clone()),
344 },
345 identity.keys(),
346 )?;
347 let identity = Self {
348 file: directory.owned_file(StoreFile::Bootstrap),
349 confirmation: ConfirmationNumber::of(code.invite, &identity.keys().public_keys()),
350 identity,
351 request,
352 path,
353 state: JoinStage::Unsent,
354 sealing: Sealing::new(code)?,
355 device_name: device_name.into(),
356 joiner,
357 circle,
358 inviting_writer: code.inviting_writer,
359 read_through: code.read_through,
360 expires_at: code.expires_at,
361 };
362 identity.save()?;
363 Ok(identity)
364 }
365
366 pub fn identity(&self) -> MemberIdentity {
369 self.identity.clone()
370 }
371
372 pub fn approver(&self) -> DeviceId {
374 self.inviting_writer
375 }
376
377 pub fn read_through(&self) -> u64 {
380 self.read_through
381 }
382
383 pub fn device_name(&self) -> &str {
386 &self.device_name
387 }
388
389 pub fn circle_name(&self) -> &str {
391 &self.circle.circle.name
392 }
393
394 #[cfg(any(test, feature = "test-utils"))]
396 pub fn circle(&self) -> &JoiningCircle {
397 &self.circle
398 }
399
400 pub fn joiner(&self) -> &Joiner {
403 &self.joiner
404 }
405
406 pub fn confirmation(&self) -> ConfirmationNumber {
409 self.confirmation
410 }
411
412 pub fn path(&self) -> &ObjectPath {
414 &self.path
415 }
416
417 pub fn attempted(&self) -> bool {
419 matches!(self.state, JoinStage::Sent | JoinStage::Opened)
420 }
421
422 pub fn accepted(&self) -> bool {
426 self.state == JoinStage::Accepted
427 }
428
429 pub fn ended(&self) -> bool {
432 self.state == JoinStage::Ended
433 }
434
435 pub fn opened(&self) -> bool {
439 self.state == JoinStage::Opened
440 }
441
442 pub fn record_acceptance(&mut self) -> Result<(), SyncError> {
447 match self.state {
448 JoinStage::Unsent => self.record(JoinStage::Accepted),
449 JoinStage::Accepted | JoinStage::Sent | JoinStage::Opened | JoinStage::Ended => Ok(()),
450 }
451 }
452
453 pub fn record_attempt(&mut self) -> Result<(), SyncError> {
457 self.record(JoinStage::Sent)
458 }
459
460 pub fn record_refusal(&mut self) -> Result<(), SyncError> {
464 self.record(JoinStage::Accepted)
465 }
466
467 pub(crate) fn record_opened(&mut self) -> Result<(), SyncError> {
471 self.record(JoinStage::Opened)
472 }
473
474 fn record(&mut self, state: JoinStage) -> Result<(), SyncError> {
475 self.state = state;
476 self.save()
477 }
478
479 fn save(&self) -> Result<(), SyncError> {
480 let keys = self.identity.keys().to_secret_bytes();
481 let mut plain =
482 Zeroizing::new(Vec::with_capacity(5 + keys.as_bytes().len() + self.request.len()));
483 plain.push(self.state.byte());
484 plain.extend_from_slice(&(keys.as_bytes().len() as u32).to_be_bytes());
485 plain.extend_from_slice(keys.as_bytes());
486 plain.extend_from_slice(&self.request);
487 let sealed = self.sealing.key.seal_object_chunk(
488 &self.sealing.path,
489 &self.sealing.binding,
490 0,
491 0,
492 &plain,
493 )?;
494 self.file.replace(&sealed)?;
495 Ok(())
496 }
497
498 fn at(&self) -> RequestAt<'_> {
501 RequestAt { path: &self.path, request: &self.request, showing: self.inviting_writer }
502 }
503
504 pub async fn publish(&self, storage: &dyn Storage) -> Result<bool, SyncError> {
509 let at = self.at();
510 if at.showing_gone(storage).await? {
511 return Ok(false);
512 }
513 match at.place(storage).await? {
514 Placed::Ours => Ok(true),
515 Placed::Other(found) if InviteEnd::decode(&found).is_ok() => Ok(false),
518 Placed::Other(_) => Err(SyncError::InvitationChanged),
519 }
520 }
521
522 pub(crate) async fn resend(&self, storage: &dyn Storage) -> Result<(), SyncError> {
529 match storage.read(&self.path).await {
530 Ok(_) => Ok(()),
531 Err(error) if error.failure() == StorageFailure::NotFound => {
532 self.publish(storage).await.map(drop)
533 }
534 Err(error) => Err(error.into()),
535 }
536 }
537
538 pub(crate) async fn pending(&self, storage: &dyn Storage) -> Result<bool, SyncError> {
543 self.at().pending(storage).await
544 }
545
546 pub(crate) fn open_at(&self, now: std::time::SystemTime) -> bool {
548 now.duration_since(std::time::UNIX_EPOCH)
549 .map_or(true, |since| since.as_secs() < self.expires_at)
550 }
551}
552
553pub(crate) fn joining_circle(
558 store: coven_foundation::id_source::StoreId,
559 member: coven_foundation::id_source::MemberId,
560 sealing: &coven_crypto::SealingKey,
561 terms: &CircleTerms,
562 ids: &dyn IdSource,
563) -> Result<JoiningCircle, SyncError> {
564 let circle = CircleId(ids.new_id());
565 let key_id = KeyId(ids.new_id());
566 let key = CircleKey::generate(circle, key_id)?;
567 let routing = KeyCopyPrefix {
568 audience: coven_merge::Audience::Circle(circle),
569 key: key_id,
570 member,
571 sealing: *sealing,
572 };
573 let binding = SlotObjectPrefix::own_binding(store, &routing)?;
574 let sealed = coven_crypto::seal_own_circle_key(&key, &routing.sealing, &binding)?;
575 Ok(JoiningCircle {
576 circle: NewCircle {
577 circle,
578 name: terms.name.clone(),
579 breaking_version: terms.breaking_version,
580 key: key_id,
581 key_hash: key.hash(),
582 },
583 copy: CopyBox { routing, sealed },
584 })
585}
586
587#[cfg(any(test, feature = "test-utils"))]
591pub fn test_joining_circle(
592 store: coven_foundation::id_source::StoreId,
593 member: coven_foundation::id_source::MemberId,
594 sealing: &coven_crypto::SealingKey,
595 ids: &dyn IdSource,
596) -> Result<JoiningCircle, SyncError> {
597 joining_circle(
598 store,
599 member,
600 sealing,
601 &CircleTerms { name: "Circle".into(), breaking_version: 0 },
602 ids,
603 )
604}
605
606#[cfg(any(test, feature = "test-utils"))]
610#[expect(clippy::too_many_arguments, reason = "an admission's every field")]
611pub fn admitting(
612 store: coven_foundation::id_source::StoreId,
613 member: coven_foundation::id_source::MemberId,
614 keys: coven_crypto::MemberPublicKeys,
615 role: coven_format::admin::MemberRole,
616 access: coven_format::MemberAccess,
617 device: DeviceId,
618 device_name: &str,
619 ids: &dyn IdSource,
620) -> Result<(coven_format::admin::StoreChange, CopyBox), SyncError> {
621 let terms = CircleTerms { name: format!("circle of {member}"), breaking_version: 0 };
622 let JoiningCircle { circle, copy } = joining_circle(store, member, &keys.sealing, &terms, ids)?;
623 Ok((
624 coven_format::admin::StoreChange::AdmitMember {
625 member,
626 keys,
627 role,
628 access,
629 device,
630 device_name: device_name.into(),
631 person: format!("person {member}"),
632 circle,
633 },
634 copy,
635 ))
636}
637
638pub fn record_ending(directory: &StoreDir, code: &InviteCode) -> Result<(), SyncError> {
643 match JoiningIdentity::saved(directory, code)? {
644 Some(mut saved) => saved.record(JoinStage::Ended),
645 None => Ok(()),
646 }
647}
648
649pub fn ended_for(directory: &StoreDir, code: &InviteCode) -> Result<bool, SyncError> {
652 Ok(JoiningIdentity::saved(directory, code)?.is_some_and(|saved| saved.ended()))
653}
654
655fn local_path(code: &InviteCode) -> String {
656 format!("coven/local-join/{}/{}", code.store, code.invite)
657}