openmls/group/mls_group/

proposal.rs

use openmls_traits::{signatures::Signer, storage::StorageProvider as _};

#[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
use super::CreateGroupContextExtProposalError;
#[cfg(feature = "virtual-clients-draft")]
use super::HandshakeConfirmationData;
use super::{
    errors::{ProposalError, ProposeAddMemberError, ProposeRemoveMemberError, RemoveProposalError},
    AddProposal, CustomProposal, FramingParameters, HandshakeFramingOutput, MlsGroup,
    PreSharedKeyProposal, Proposal, QueuedProposal, ReInitProposal, RemoveProposal, UpdateProposal,
    WireFormat,
};
#[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
use crate::messages::group_info::GroupInfo;
use crate::{
    binary_tree::LeafNodeIndex,
    ciphersuite::hash_ref::ProposalRef,
    credentials::{Credential, NewSignerBundle},
    error::LibraryError,
    extensions::Extensions,
    framing::{mls_auth_content::AuthenticatedContent, MlsMessageOut},
    group::{errors::CreateAddProposalError, GroupContext, ValidationError},
    key_packages::KeyPackage,
    messages::proposals::ProposalOrRefType,
    schedule::PreSharedKeyId,
    storage::{OpenMlsProvider, StorageProvider},
    treesync::{LeafNode, LeafNodeParameters},
};

#[cfg(feature = "extensions-draft")]
use crate::{
    component::ComponentId,
    messages::proposals::{AppDataUpdateOperation, AppDataUpdateProposal},
};

/// Helper for building a proposal based on the raw values.
#[derive(Debug, PartialEq, Clone)]
pub enum Propose {
    /// An add proposal requires a key package of the addee.
    Add(KeyPackage),

    /// An update proposal requires a new leaf node.
    ///
    /// An update proposal is always queued by reference as per RFC 9420 a
    /// member must not commit its own update proposal.
    Update(LeafNodeParameters),

    /// A remove proposal consists of the leaf index of the leaf to be removed.
    Remove(u32),

    /// A remove proposal for the leaf with the credential.
    RemoveCredential(Credential),

    /// A PSK proposal gets a pre shared key id.
    PreSharedKey(PreSharedKeyId),

    /// Propose adding new group context extensions.
    GroupContextExtensions(Extensions<GroupContext>),

    #[cfg(feature = "extensions-draft")]
    /// Propose an update to a component in the
    /// [`AppDataDictionary`](crate::extensions::AppDataDictionary)
    UpdateAppDataComponent {
        /// The component_id to update in the dictionary
        component_id: ComponentId,
        /// The data representing the update
        update: Vec<u8>,
    },
    #[cfg(feature = "extensions-draft")]
    /// Propose removal of a component in the
    /// [`AppDataDictionary`](crate::extensions::AppDataDictionary)
    RemoveAppDataComponent {
        /// The component_id to remove in the dictionary
        component_id: ComponentId,
    },

    /// A custom proposal with semantics to be implemented by the application.
    Custom(CustomProposal),
}

macro_rules! impl_propose_fun {
    ($name:ident, $impl_name:ident, $value_ty:ty, $group_fun:ident, $ref_or_value:expr, $doc:expr) => {
        /// Builds the proposal, queues it, and frames it, returning the framing
        /// output so callers can surface the handshake confirmation data.
        #[openmls_traits::maybe_async]
        async fn $impl_name<Provider: OpenMlsProvider>(
            &mut self,
            provider: &Provider,
            signer: &impl Signer,
            value: $value_ty,
        ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposalError<Provider::StorageError>> {
            self.is_operational()?;

            let aad = self.outgoing_authenticated_data()?;
            let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
            let proposal = self.$group_fun(framing_parameters, value, signer)?;

            let queued_proposal = QueuedProposal::from_authenticated_content(
                self.ciphersuite(),
                provider.crypto(),
                proposal.clone(),
                $ref_or_value,
            )?;
            let proposal_ref = queued_proposal.proposal_reference();

            log::trace!("Storing proposal in queue {:?}", queued_proposal);
            provider
                .storage()
                .queue_proposal(self.group_id(), &proposal_ref, &queued_proposal)
                .await
                .map_err(ProposalError::StorageError)?;
            self.proposal_store_mut().add(queued_proposal);

            let framing = self.content_to_mls_message(proposal, provider).await?;

            self.reset_aad();
            Ok((framing, proposal_ref))
        }

        #[doc = $doc]
        ///
        /// Returns an error if there is a pending commit.
        ///
        /// Under the `virtual-clients-draft` feature this function is
        /// unavailable. Use [`Self::propose_unconfirmed`], which retains the
        /// handshake secret and returns the confirmation data.
        #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
        #[openmls_traits::maybe_async]
        pub async fn $name<Provider: OpenMlsProvider>(
            &mut self,
            provider: &Provider,
            signer: &impl Signer,
            value: $value_ty,
        ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
            let (framing, proposal_ref) = self.$impl_name(provider, signer, value).await?;
            Ok((framing.message, proposal_ref))
        }
    };
}

impl MlsGroup {
    impl_propose_fun!(
        propose_add_member_by_value,
        propose_add_member_by_value_impl,
        KeyPackage,
        create_add_proposal,
        ProposalOrRefType::Proposal,
        "Creates a proposal to add a member to the group, committed by value."
    );

    impl_propose_fun!(
        propose_remove_member_by_value,
        propose_remove_member_by_value_impl,
        LeafNodeIndex,
        create_remove_proposal,
        ProposalOrRefType::Proposal,
        "Creates a proposal to remove a member from the group, committed by value."
    );

    impl_propose_fun!(
        propose_pre_shared_key,
        propose_pre_shared_key_impl,
        PreSharedKeyId,
        create_presharedkey_proposal,
        ProposalOrRefType::Reference,
        "Creates a proposal to add a pre-shared key to the key schedule, committed by reference."
    );

    impl_propose_fun!(
        propose_pre_shared_key_by_value,
        propose_pre_shared_key_by_value_impl,
        PreSharedKeyId,
        create_presharedkey_proposal,
        ProposalOrRefType::Proposal,
        "Creates a proposal to add a pre-shared key to the key schedule, committed by value."
    );

    /// Creates proposals to add a non-resumption PSK to the key schedule.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[deprecated(
        note = "Renamed to `propose_pre_shared_key`; works for any non-resumption PSK, not just external"
    )]
    #[openmls_traits::maybe_async]
    pub async fn propose_external_psk<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        value: PreSharedKeyId,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        self.propose_pre_shared_key(provider, signer, value).await
    }

    /// Creates proposals to add a non-resumption PSK to the key schedule by value.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[deprecated(
        note = "Renamed to `propose_pre_shared_key_by_value`; works for any non-resumption PSK, not just external"
    )]
    #[openmls_traits::maybe_async]
    pub async fn propose_external_psk_by_value<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        value: PreSharedKeyId,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        self.propose_pre_shared_key_by_value(provider, signer, value)
            .await
    }

    impl_propose_fun!(
        propose_custom_proposal_by_value,
        propose_custom_proposal_by_value_impl,
        CustomProposal,
        create_custom_proposal,
        ProposalOrRefType::Proposal,
        "Creates a custom proposal, committed by value."
    );

    impl_propose_fun!(
        propose_custom_proposal_by_reference,
        propose_custom_proposal_by_reference_impl,
        CustomProposal,
        create_custom_proposal,
        ProposalOrRefType::Reference,
        "Creates a custom proposal, committed by reference."
    );

    /// Generate a proposal.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        propose: Propose,
        ref_or_value: ProposalOrRefType,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        let (framing, proposal_ref) = self
            .propose_dispatch(provider, signer, propose, ref_or_value)
            .await?;
        Ok((framing.message, proposal_ref))
    }

    /// Like [`Self::propose`], but retains the handshake secret and returns the
    /// [`HandshakeConfirmationData`] alongside the framed proposal, so a
    /// virtual client can confirm the proposal with
    /// [`MlsGroup::confirm_handshake_message`] once the DS has accepted it. The
    /// confirmation is `None` for a proposal framed as a plaintext
    /// PublicMessage.
    ///
    /// [`MlsGroup::confirm_handshake_message`]: crate::group::MlsGroup::confirm_handshake_message
    #[cfg(feature = "virtual-clients-draft")]
    #[openmls_traits::maybe_async]
    pub async fn propose_unconfirmed<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        propose: Propose,
        ref_or_value: ProposalOrRefType,
    ) -> Result<
        (
            MlsMessageOut,
            ProposalRef,
            Option<HandshakeConfirmationData>,
        ),
        ProposalError<Provider::StorageError>,
    > {
        let (framing, proposal_ref) = self
            .propose_dispatch(provider, signer, propose, ref_or_value)
            .await?;
        Ok((framing.message, proposal_ref, framing.confirmation))
    }

    /// Shared dispatch for [`Self::propose`] and [`Self::propose_unconfirmed`].
    /// Routes to the per-proposal-type helpers and returns the framing output
    /// so the caller can decide whether to surface the confirmation data.
    #[openmls_traits::maybe_async]
    async fn propose_dispatch<Provider: OpenMlsProvider, S: Signer>(
        &mut self,
        provider: &Provider,
        signer: &S,
        propose: Propose,
        ref_or_value: ProposalOrRefType,
    ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposalError<Provider::StorageError>> {
        match propose {
            Propose::Add(key_package) => match ref_or_value {
                ProposalOrRefType::Proposal => {
                    self.propose_add_member_by_value_impl(provider, signer, key_package)
                        .await
                }
                ProposalOrRefType::Reference => self
                    .propose_add_member_impl(provider, signer, &key_package)
                    .await
                    .map_err(|e| e.into()),
            },

            Propose::Update(leaf_node_parameters) => self
                .propose_self_update_internal(
                    provider,
                    signer,
                    None::<NewSignerBundle<'_, S>>,
                    leaf_node_parameters,
                )
                .await
                .map_err(|e| e.into()),

            Propose::Remove(leaf_index) => match ref_or_value {
                ProposalOrRefType::Proposal => {
                    self.propose_remove_member_by_value_impl(
                        provider,
                        signer,
                        LeafNodeIndex::new(leaf_index),
                    )
                    .await
                }
                ProposalOrRefType::Reference => self
                    .propose_remove_member_impl(provider, signer, LeafNodeIndex::new(leaf_index))
                    .await
                    .map_err(|e| e.into()),
            },

            Propose::RemoveCredential(credential) => match ref_or_value {
                ProposalOrRefType::Proposal => {
                    self.propose_remove_member_by_credential_by_value_impl(
                        provider,
                        signer,
                        &credential,
                    )
                    .await
                }
                ProposalOrRefType::Reference => self
                    .propose_remove_member_by_credential_impl(provider, signer, &credential)
                    .await
                    .map_err(|e| e.into()),
            },
            Propose::PreSharedKey(psk_id) => {
                match psk_id.psk() {
                    crate::schedule::Psk::External(_) => {}
                    #[cfg(feature = "extensions-draft")]
                    crate::schedule::Psk::Application(_) => {}
                    crate::schedule::Psk::Resumption(_) => {
                        return Err(ProposalError::LibraryError(LibraryError::custom(
                            "Invalid PSk argument",
                        )))
                    }
                };
                match ref_or_value {
                    ProposalOrRefType::Proposal => {
                        self.propose_pre_shared_key_by_value_impl(provider, signer, psk_id)
                            .await
                    }
                    ProposalOrRefType::Reference => {
                        self.propose_pre_shared_key_impl(provider, signer, psk_id)
                            .await
                    }
                }
            }
            Propose::GroupContextExtensions(extensions) => {
                self.propose_group_context_extensions_impl(
                    provider,
                    extensions,
                    signer,
                    ref_or_value,
                )
                .await
            }
            // extensions-draft
            #[cfg(feature = "extensions-draft")]
            Propose::UpdateAppDataComponent {
                component_id,
                update,
            } => {
                self.propose_app_data_update_impl(
                    provider,
                    signer,
                    component_id,
                    AppDataUpdateOperation::Update(update.into()),
                    ref_or_value,
                )
                .await
            }
            #[cfg(feature = "extensions-draft")]
            Propose::RemoveAppDataComponent { component_id } => {
                self.propose_app_data_update_impl(
                    provider,
                    signer,
                    component_id,
                    AppDataUpdateOperation::Remove,
                    ref_or_value,
                )
                .await
            }

            // custom
            Propose::Custom(custom_proposal) => match ref_or_value {
                ProposalOrRefType::Proposal => {
                    self.propose_custom_proposal_by_value_impl(provider, signer, custom_proposal)
                        .await
                }
                ProposalOrRefType::Reference => {
                    self.propose_custom_proposal_by_reference_impl(
                        provider,
                        signer,
                        custom_proposal,
                    )
                    .await
                }
            },
        }
    }

    /// Creates proposals to add members to the group.
    ///
    /// Returns an error if there is a pending commit.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose_add_member<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        key_package: &KeyPackage,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposeAddMemberError<Provider::StorageError>> {
        let (framing, proposal_ref) = self
            .propose_add_member_impl(provider, signer, key_package)
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[openmls_traits::maybe_async]
    async fn propose_add_member_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        key_package: &KeyPackage,
    ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposeAddMemberError<Provider::StorageError>>
    {
        self.is_operational()?;

        let aad = self.outgoing_authenticated_data()?;
        let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
        let add_proposal = self
            .create_add_proposal(framing_parameters, key_package.clone(), signer)
            .map_err(|e| match e {
                CreateAddProposalError::LibraryError(e) => e.into(),
                CreateAddProposalError::LeafNodeValidation(error) => {
                    ProposeAddMemberError::LeafNodeValidation(error)
                }
            })?;

        let proposal = QueuedProposal::from_authenticated_content_by_ref(
            self.ciphersuite(),
            provider.crypto(),
            add_proposal.clone(),
        )?;
        let proposal_ref = proposal.proposal_reference();
        provider
            .storage()
            .queue_proposal(self.group_id(), &proposal_ref, &proposal)
            .await
            .map_err(ProposeAddMemberError::StorageError)?;
        self.proposal_store_mut().add(proposal);

        let framing = self.content_to_mls_message(add_proposal, provider).await?;

        self.reset_aad();
        Ok((framing, proposal_ref))
    }

    /// Creates proposals to remove members from the group.
    /// The `member` has to be the member's leaf index.
    ///
    /// Returns an error if there is a pending commit.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose_remove_member<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: LeafNodeIndex,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposeRemoveMemberError<Provider::StorageError>>
    {
        let (framing, proposal_ref) = self
            .propose_remove_member_impl(provider, signer, member)
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[openmls_traits::maybe_async]
    async fn propose_remove_member_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: LeafNodeIndex,
    ) -> Result<
        (HandshakeFramingOutput, ProposalRef),
        ProposeRemoveMemberError<Provider::StorageError>,
    > {
        self.is_operational()?;

        let aad = self.outgoing_authenticated_data()?;
        let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
        let remove_proposal = self
            .create_remove_proposal(framing_parameters, member, signer)
            .map_err(|_| ProposeRemoveMemberError::UnknownMember)?;

        let proposal = QueuedProposal::from_authenticated_content_by_ref(
            self.ciphersuite(),
            provider.crypto(),
            remove_proposal.clone(),
        )?;
        let proposal_ref = proposal.proposal_reference();
        provider
            .storage()
            .queue_proposal(self.group_id(), &proposal_ref, &proposal)
            .await
            .map_err(ProposeRemoveMemberError::StorageError)?;
        self.proposal_store_mut().add(proposal);

        let framing = self
            .content_to_mls_message(remove_proposal, provider)
            .await?;

        self.reset_aad();
        Ok((framing, proposal_ref))
    }

    /// Creates proposals to remove members from the group.
    /// The `member` has to be the member's credential.
    ///
    /// Returns an error if there is a pending commit.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose_remove_member_by_credential<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: &Credential,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposeRemoveMemberError<Provider::StorageError>>
    {
        let (framing, proposal_ref) = self
            .propose_remove_member_by_credential_impl(provider, signer, member)
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[openmls_traits::maybe_async]
    async fn propose_remove_member_by_credential_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: &Credential,
    ) -> Result<
        (HandshakeFramingOutput, ProposalRef),
        ProposeRemoveMemberError<Provider::StorageError>,
    > {
        // Find the user for the credential first.
        let member_index = self
            .public_group()
            .members()
            .find(|m| &m.credential == member)
            .map(|m| m.index);

        if let Some(member_index) = member_index {
            self.propose_remove_member_impl(provider, signer, member_index)
                .await
        } else {
            Err(ProposeRemoveMemberError::UnknownMember)
        }
    }

    /// Creates proposals to remove members from the group.
    /// The `member` has to be the member's credential.
    ///
    /// Returns an error if there is a pending commit.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose_remove_member_by_credential_by_value<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: &Credential,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        let (framing, proposal_ref) = self
            .propose_remove_member_by_credential_by_value_impl(provider, signer, member)
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[openmls_traits::maybe_async]
    async fn propose_remove_member_by_credential_by_value_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        member: &Credential,
    ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposalError<Provider::StorageError>> {
        // Find the user for the credential first.
        let member_index = self
            .public_group()
            .members()
            .find(|m| &m.credential == member)
            .map(|m| m.index);

        if let Some(member_index) = member_index {
            self.propose_remove_member_by_value_impl(provider, signer, member_index)
                .await
        } else {
            Err(ProposalError::ProposeRemoveMemberError(
                ProposeRemoveMemberError::UnknownMember,
            ))
        }
    }

    /// Creates a proposals with a new set of `extensions` for the group context.
    ///
    /// Returns an error when the group does not support all the required capabilities
    /// in the new `extensions`.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`] with
    /// [`Propose::GroupContextExtensions`], which retains the handshake secret
    /// and returns the confirmation data.
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[openmls_traits::maybe_async]
    pub async fn propose_group_context_extensions<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        extensions: Extensions<GroupContext>,
        signer: &impl Signer,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        let (framing, proposal_ref) = self
            .propose_group_context_extensions_impl(
                provider,
                extensions,
                signer,
                ProposalOrRefType::Reference,
            )
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[openmls_traits::maybe_async]
    async fn propose_group_context_extensions_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        extensions: Extensions<GroupContext>,
        signer: &impl Signer,
        ref_or_value: ProposalOrRefType,
    ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposalError<Provider::StorageError>> {
        self.is_operational()?;

        let aad = self.outgoing_authenticated_data()?;
        let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
        let proposal = self.create_group_context_ext_proposal::<Provider>(
            framing_parameters,
            extensions,
            signer,
        )?;

        let queued_proposal = QueuedProposal::from_authenticated_content(
            self.ciphersuite(),
            provider.crypto(),
            proposal.clone(),
            ref_or_value,
        )?;

        let proposal_ref = queued_proposal.proposal_reference();
        provider
            .storage()
            .queue_proposal(self.group_id(), &proposal_ref, &queued_proposal)
            .await
            .map_err(ProposalError::StorageError)?;
        self.proposal_store_mut().add(queued_proposal);

        let framing = self.content_to_mls_message(proposal, provider).await?;

        self.reset_aad();
        Ok((framing, proposal_ref))
    }

    /// Creates proposals to reinitialize the group into a successor group with
    /// the parameters described by `reinit_proposal` (a new group id, protocol
    /// version, ciphersuite and group context extensions).
    ///
    /// Committing to a ReInit proposal suspends the group: once the commit is
    /// merged, the group becomes inoperable and can only be used to seed the
    /// successor group (see [`MlsGroupBuilder::reinit`] and
    /// [`StagedWelcome::build_from_reinit`]).
    ///
    /// Returns an error if the group is not operational (e.g. there is a pending
    /// commit).
    ///
    /// [`MlsGroupBuilder::reinit`]: crate::group::MlsGroupBuilder::reinit
    /// [`StagedWelcome::build_from_reinit`]: crate::group::StagedWelcome::build_from_reinit
    #[openmls_traits::maybe_async]
    pub async fn propose_reinit<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        reinit_proposal: ReInitProposal,
        signer: &impl Signer,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        self.is_operational()?;

        let aad = self.outgoing_authenticated_data()?;
        let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
        let proposal = self.create_reinit_proposal(framing_parameters, reinit_proposal, signer)?;

        let queued_proposal = QueuedProposal::from_authenticated_content(
            self.ciphersuite(),
            provider.crypto(),
            proposal.clone(),
            ProposalOrRefType::Reference,
        )?;

        let proposal_ref = queued_proposal.proposal_reference();
        provider
            .storage()
            .queue_proposal(self.group_id(), &proposal_ref, &queued_proposal)
            .await
            .map_err(ProposalError::StorageError)?;
        self.proposal_store_mut().add(queued_proposal);

        let framing = self.content_to_mls_message(proposal, provider).await?;

        self.reset_aad();
        Ok((framing.message, proposal_ref))
    }

    /// Updates Group Context Extensions
    ///
    /// Commits to the Group Context Extension inline proposal using the [`Extensions`]
    ///
    /// Returns an error when the group does not support all the required capabilities
    /// in the new `extensions` or if there is a pending commit.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`MlsGroup::commit_builder`], whose
    /// [`CommitMessageBundle::confirmation`](crate::group::CommitMessageBundle::confirmation)
    /// surfaces the handshake confirmation data.
    //// FIXME: #1217
    #[cfg(any(not(feature = "virtual-clients-draft"), feature = "test-utils", test))]
    #[allow(clippy::type_complexity)]
    #[openmls_traits::maybe_async]
    pub async fn update_group_context_extensions<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        extensions: Extensions<GroupContext>,
        signer: &impl Signer,
    ) -> Result<
        (MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>),
        CreateGroupContextExtProposalError<Provider::StorageError>,
    > {
        self.is_operational()?;

        // Build and stage Commit containing GroupContextExtensions proposal
        let bundle = self
            .commit_builder()
            .propose_group_context_extensions(extensions)?
            .load_psks(provider.storage())
            .await?
            .build(provider.rand(), provider.crypto(), signer, |_| true)?
            .stage_commit(provider)
            .await?;

        // Extract messages and convert Welcome to MlsMessageOut
        let (commit, welcome, group_info) = bundle.into_contents();
        let welcome = welcome.map(|welcome| MlsMessageOut::from_welcome(welcome, self.version()));

        Ok((commit, welcome, group_info))
    }

    /// Updates the AppDataDictionary, committed by value.
    ///
    /// Under the `virtual-clients-draft` feature this function is unavailable.
    /// Use [`Self::propose_unconfirmed`], which retains the handshake secret and
    /// returns the confirmation data.
    #[cfg(all(
        feature = "extensions-draft",
        any(not(feature = "virtual-clients-draft"), feature = "test-utils", test)
    ))]
    #[openmls_traits::maybe_async]
    pub async fn propose_app_data_update<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        component_id: ComponentId,
        operation: AppDataUpdateOperation,
    ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>> {
        let (framing, proposal_ref) = self
            .propose_app_data_update_impl(
                provider,
                signer,
                component_id,
                operation,
                ProposalOrRefType::Proposal,
            )
            .await?;
        Ok((framing.message, proposal_ref))
    }

    #[cfg(feature = "extensions-draft")]
    #[openmls_traits::maybe_async]
    async fn propose_app_data_update_impl<Provider: OpenMlsProvider>(
        &mut self,
        provider: &Provider,
        signer: &impl Signer,
        component_id: ComponentId,
        operation: AppDataUpdateOperation,
        ref_or_value: ProposalOrRefType,
    ) -> Result<(HandshakeFramingOutput, ProposalRef), ProposalError<Provider::StorageError>> {
        self.is_operational()?;

        let aad = self.outgoing_authenticated_data()?;
        let framing_parameters = FramingParameters::new(&aad, self.outgoing_wire_format());
        let proposal = self.create_app_data_update_proposal(
            framing_parameters,
            component_id,
            operation,
            signer,
        )?;

        let queued_proposal = QueuedProposal::from_authenticated_content(
            self.ciphersuite(),
            provider.crypto(),
            proposal.clone(),
            ref_or_value,
        )?;
        let proposal_ref = queued_proposal.proposal_reference();

        log::trace!("Storing proposal in queue {:?}", queued_proposal);
        provider
            .storage()
            .queue_proposal(self.group_id(), &proposal_ref, &queued_proposal)
            .await
            .map_err(ProposalError::StorageError)?;
        self.proposal_store_mut().add(queued_proposal);

        let framing = self.content_to_mls_message(proposal, provider).await?;

        self.reset_aad();
        Ok((framing, proposal_ref))
    }

    /// Removes a specific proposal from the store.
    #[openmls_traits::maybe_async]
    pub async fn remove_pending_proposal<Storage: StorageProvider>(
        &mut self,
        storage: &Storage,
        proposal_ref: &ProposalRef,
    ) -> Result<(), RemoveProposalError<Storage::Error>> {
        storage
            .remove_proposal(self.group_id(), proposal_ref)
            .await
            .map_err(RemoveProposalError::Storage)?;
        self.proposal_store_mut()
            .remove(proposal_ref)
            .ok_or(RemoveProposalError::ProposalNotFound)
    }

    // === Create handshake messages ===

    // 12.1.1. Add
    // struct {
    //     KeyPackage key_package;
    // } Add;
    pub(crate) fn create_add_proposal(
        &self,
        framing_parameters: FramingParameters,
        joiner_key_package: KeyPackage,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, CreateAddProposalError> {
        if let Some(required_capabilities) = self.required_capabilities() {
            joiner_key_package
                .leaf_node()
                .capabilities()
                .supports_required_capabilities(required_capabilities)?;
        }
        let add_proposal = AddProposal {
            key_package: joiner_key_package,
        };
        let proposal = Proposal::add(add_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
        .map_err(|e| e.into())
    }

    // 12.1.2. Update
    // struct {
    //     LeafNode leaf_node;
    // } Update;
    pub(crate) fn create_update_proposal(
        &self,
        framing_parameters: FramingParameters,
        // XXX: There's no need to own this. The [`UpdateProposal`] should
        //      operate on a reference to make this more efficient.
        leaf_node: LeafNode,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let update_proposal = UpdateProposal { leaf_node };
        let proposal = Proposal::update(update_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }

    // 12.1.3. Remove
    // struct {
    //     uint32 removed;
    // } Remove;
    pub(crate) fn create_remove_proposal(
        &self,
        framing_parameters: FramingParameters,
        removed: LeafNodeIndex,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, ValidationError> {
        if self.public_group().leaf(removed).is_none() {
            return Err(ValidationError::UnknownMember);
        }
        let remove_proposal = RemoveProposal { removed };
        let proposal = Proposal::remove(remove_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
        .map_err(ValidationError::LibraryError)
    }

    /// Create a SelfRemove proposal. Note that SelfRemove proposals are always
    /// sent as PublicMessages.
    pub(crate) fn create_self_remove_proposal(
        &self,
        aad: &[u8],
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let proposal = Proposal::SelfRemove;
        let framing_parameters = FramingParameters::new(aad, WireFormat::PublicMessage);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }

    // 12.1.4. PreSharedKey
    // struct {
    //     PreSharedKeyID psk;
    // } PreSharedKey;
    pub(crate) fn create_presharedkey_proposal(
        &self,
        framing_parameters: FramingParameters,
        psk: PreSharedKeyId,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let presharedkey_proposal = PreSharedKeyProposal::new(psk);
        let proposal = Proposal::psk(presharedkey_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }

    // 12.1.5. ReInit
    // struct {
    //     opaque group_id<V>;
    //     ProtocolVersion version;
    //     CipherSuite cipher_suite;
    //     Extension extensions<V>;
    // } ReInit;
    pub(crate) fn create_reinit_proposal(
        &self,
        framing_parameters: FramingParameters,
        reinit_proposal: ReInitProposal,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let proposal = Proposal::re_init(reinit_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }

    #[cfg(feature = "extensions-draft")]
    pub(crate) fn create_app_data_update_proposal(
        &self,
        framing_parameters: FramingParameters,
        component_id: ComponentId,
        operation: AppDataUpdateOperation,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let proposal = Proposal::AppDataUpdate(Box::new(AppDataUpdateProposal::new(
            component_id,
            operation,
        )));
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }

    pub(crate) fn create_custom_proposal(
        &self,
        framing_parameters: FramingParameters,
        custom_proposal: CustomProposal,
        signer: &impl Signer,
    ) -> Result<AuthenticatedContent, LibraryError> {
        let proposal = Proposal::custom(custom_proposal);
        AuthenticatedContent::member_proposal(
            framing_parameters,
            self.own_leaf_index(),
            proposal,
            self.context(),
            signer,
        )
    }
}