1  //! Core API for MLS group operations.
 2  //!
 3  //! This module provides the fundamental building blocks for MLS group management.
 4  //! All functions operate on [`GroupHandle`] instances for app-level state and
 5  //! [`MlsService`] for MLS cryptographic operations.
 6  //!
 7  //! # Overview
 8  //!
 9  //! The API is organized into three categories:
10  //!
11  //! ## Group Lifecycle
12  //! - [`create_group`] - Create a new group as steward
13  //! - [`prepare_to_join`] - Prepare a handle for joining
14  //! - [`join_group_from_invite`] - Complete join with welcome message
15  //!
16  //! ## Message Operations
17  //! - [`build_message`] - Encrypt an application message for the group
18  //! - [`build_key_package_message`] - Create key package for joining
19  //!
20  //! ## Inbound Processing
21  //! - [`process_inbound`] - Process received packets, returns [`ProcessResult`]
22  //!
23  //! ## Steward Operations
24  //! - [`create_commit_candidate`] - Build/broadcast commit candidate (no immediate merge)
25  //! - [`finalize_freeze_round`] - Select and apply a buffered candidate
26  
27  use openmls_rust_crypto::MemoryStorage;
28  use prost::Message;
29  use sha2::{Digest, Sha256};
30  use std::collections::{HashMap, VecDeque};
31  use tracing::{info, warn};
32  
33  use crate::core::{
34      ProposalId,
35      error::CoreError,
36      group_handle::{BufferedCommitCandidate, GroupHandle},
37      types::ProcessResult,
38      types::invitation_from_bytes,
39  };
40  use crate::ds::{APP_MSG_SUBTOPIC, OutboundPacket, WELCOME_SUBTOPIC};
41  use crate::mls_crypto::{
42      CommitCandidate as MlsCommitCandidate, DeMlsStorage, DecryptResult, GroupUpdate,
43      KeyPackageBytes, MlsMessageKind, MlsProposalAction, MlsService, StagedCommitResult,
44      key_package_bytes_from_json,
45  };
46  use crate::protos::de_mls::messages::v1::{
47      AppMessage, CommitCandidate, GroupUpdateRequest, InviteMember, UserKeyPackage,
48      ViolationEvidence, WelcomeMessage, app_message, group_update_request, welcome_message,
49  };
50  
51  mod freeze;
52  mod inbound;
53  mod lifecycle;
54  mod steward;
55  mod validation;
56  
57  #[cfg(test)]
58  mod tests;
59  
60  pub use freeze::{FreezeFinalizeResult, finalize_freeze_round};
61  pub use inbound::process_inbound;
62  pub use lifecycle::{
63      build_key_package_message, build_message, create_group, join_group_from_invite, prepare_to_join,
64  };
65  pub use steward::{
66      approved_proposals, approved_proposals_count, create_commit_candidate, epoch_history,
67      group_members,
68  };
69  
70  #[cfg(test)]
71  pub(crate) use validation::validate_commit_candidate;