openmls/group/mls_group/

builder.rs

use openmls_traits::{crypto::OpenMlsCrypto, signatures::Signer, types::Ciphersuite};
use tls_codec::Serialize;

#[cfg(feature = "extensions-draft")]
use crate::schedule::application_export_tree::ApplicationExportTree;
use crate::{
    binary_tree::{array_representation::TreeSize, LeafNodeIndex},
    credentials::CredentialWithKey,
    error::LibraryError,
    extensions::Extensions,
    group::{
        config::PastEpochDeletionPolicy, past_secrets::MessageSecretsStore,
        public_group::errors::PublicGroupBuildError, BranchInfo, CommitBuilderStageError,
        CommitMessageBundle, CreateCommitError, GroupContext, GroupId, MlsGroup,
        MlsGroupCreateConfig, MlsGroupCreateConfigBuilder, MlsGroupState, NewGroupError,
        PublicGroup, ReInitInfo, WireFormatPolicy,
    },
    key_packages::{KeyPackage, Lifetime},
    schedule::{
        psk::{load_psks, store::ResumptionPskStore, PskSecret},
        EpochSecretsResult, InitSecret, JoinerSecret, KeySchedule, PreSharedKeyId,
    },
    storage::OpenMlsProvider,
    tree::sender_ratchet::SenderRatchetConfiguration,
    treesync::{
        errors::LeafNodeValidationError,
        node::leaf_node::{Capabilities, CapabilitiesPolicy, LeafNode},
    },
};

#[cfg(feature = "virtual-clients-draft")]
use crate::treesync::node::leaf_node::{resolve_capabilities, LeafNodeConstraints};

/// Builder struct for an [`MlsGroup`].
#[derive(Default, Debug)]
pub struct MlsGroupBuilder {
    group_id: Option<GroupId>,
    mls_group_create_config_builder: MlsGroupCreateConfigBuilder,
    replace_old_group: bool,
    psk_ids: Vec<PreSharedKeyId>,
    /// The emulation group to create this group as a virtual client of. The
    /// derivation epoch is resolved from its state when [`Self::build`] runs.
    #[cfg(feature = "virtual-clients-draft")]
    vc_emulation_group_id: Option<GroupId>,
}

impl MlsGroupBuilder {
    pub(super) fn new() -> Self {
        Self::default()
    }

    /// Sets the group ID of the [`MlsGroup`].
    pub fn with_group_id(mut self, group_id: GroupId) -> Self {
        self.group_id = Some(group_id);
        self
    }

    /// Create the group as a virtual client of the emulation group named by
    /// `emulation_group_id`.
    ///
    /// The group is created from the newest derivation epoch of the emulation
    /// group, which is what the draft requires of every new virtual-client
    /// operation. The epoch is resolved when [`Self::build`] runs, against the
    /// emulation group's state at that point.
    ///
    /// The creator's leaf is `key_package`-sourced and its key material is
    /// derived from a fresh `key_package` operation secret of that epoch (so
    /// sibling emulator clients can reconstruct it), and the epoch-0
    /// `epoch_secret` is derived from the same KeyPackage seed rather than
    /// transmitted. Siblings bootstrap into the group with
    /// [`MlsGroup::vc_join_at_creation`].
    ///
    /// [`MlsGroup::vc_join_at_creation`]: crate::group::MlsGroup::vc_join_at_creation
    #[cfg(feature = "virtual-clients-draft")]
    pub fn vc_emulation(mut self, emulation_group_id: &GroupId) -> Self {
        self.vc_emulation_group_id = Some(emulation_group_id.clone());
        self
    }

    /// Instruct the builder to replace any existing group with the same ID.
    pub fn replace_old_group(mut self) -> Self {
        self.replace_old_group = true;
        self
    }

    /// Turn this builder into a [`BranchGroupBuilder`] to build a sub-group
    /// [RFC 9420 §11.3].
    ///
    /// The parent group's parameters are provided via `branch_info`, which the
    /// parent exports with
    /// [`MlsGroup::branch_info`](crate::group::MlsGroup::branch_info). The
    /// sub-group is created with the parent's ciphersuite. Set any other group
    /// configuration on this builder before calling `branch`, then create the
    /// sub-group and its branch commit with
    /// [`BranchGroupBuilder::build_branch`].
    ///
    /// [RFC 9420 §11.3]: https://www.rfc-editor.org/rfc/rfc9420.html#name-subgroup-branching
    pub fn branch(self, branch_info: BranchInfo) -> BranchGroupBuilder {
        BranchGroupBuilder {
            group_builder: self,
            branch_info,
            extensions: None,
            force_self_update: false,
        }
    }

    /// Turn this builder into a [`ReInitGroupBuilder`] to build a reinitialized successor
    /// group [RFC 9420 §11.2].
    ///
    /// The reinit parameters are provided via `reinit_info`, which the predecessor
    /// exports with [`MlsGroup::reinit_info`](crate::group::MlsGroup::reinit_info).
    /// The successor is created with the ReInit proposal's protocol version, group_id,
    /// ciphersuite, group_context extensions. Set any other group
    /// configuration on this builder before calling `reinit`, then create the
    /// new group and its reinit commit with
    /// [`ReInitGroupBuilder::build_reinit`].
    ///
    /// [RFC 9420 §11.2]: https://www.rfc-editor.org/rfc/rfc9420.html#name-reinitialization
    pub fn reinit(self, reinit_info: ReInitInfo) -> ReInitGroupBuilder {
        ReInitGroupBuilder {
            group_builder: self,
            reinit_info,
            force_self_update: false,
        }
    }

    /// Build a new group as configured by this builder.
    #[openmls_traits::maybe_async]
    pub async fn build<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        signer: &impl Signer,
        credential_with_key: CredentialWithKey,
    ) -> Result<MlsGroup, NewGroupError<Provider::StorageError>> {
        self.build_internal(provider, signer, credential_with_key, None)
            .await
    }

    /// Build a new group with the given group ID.
    ///
    /// If an [`MlsGroupCreateConfig`] is provided, it will be used to configure the
    /// group. Otherwise, the internal builder is used to build one with the
    /// parameters set on this builder.
    ///
    /// If a group with the same ID already exists in storage and
    /// `replace_old_group` was not set, an error will be returned.
    #[openmls_traits::maybe_async]
    pub(super) async fn build_internal<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        signer: &impl Signer,
        credential_with_key: CredentialWithKey,
        mls_group_create_config_option: Option<MlsGroupCreateConfig>,
    ) -> Result<MlsGroup, NewGroupError<Provider::StorageError>> {
        let mls_group_create_config = mls_group_create_config_option
            .unwrap_or_else(|| self.mls_group_create_config_builder.build());
        let group_id = self
            .group_id
            .unwrap_or_else(|| GroupId::random(provider.rand()));
        let ciphersuite = mls_group_create_config.ciphersuite;

        provider
            .crypto()
            .supports(ciphersuite)
            .map_err(|_| NewGroupError::UnsupportedCiphersuite(ciphersuite))?;

        #[cfg(feature = "virtual-clients-draft")]
        if let Some(emulation_group_id) = &self.vc_emulation_group_id {
            let epoch_id =
                crate::components::vc_derivation_info::require_newest_vc_derivation_epoch(
                    provider.storage(),
                    emulation_group_id,
                )
                .await?;
            return build_vc_internal(
                provider,
                signer,
                credential_with_key,
                mls_group_create_config,
                group_id,
                self.replace_old_group,
                epoch_id,
            )
            .await;
        }

        if !self.replace_old_group
            && MlsGroup::load(provider.storage(), &group_id)
                .await
                .map_err(NewGroupError::StorageError)?
                .is_some()
        {
            return Err(NewGroupError::GroupAlreadyExists);
        }

        let (public_group_builder, commit_secret, leaf_keypair) =
            PublicGroup::builder(group_id, ciphersuite, credential_with_key)
                .with_group_context_extensions(
                    mls_group_create_config.group_context_extensions.clone(),
                )
                .with_leaf_node_extensions(mls_group_create_config.leaf_node_extensions.clone())
                .with_lifetime(*mls_group_create_config.lifetime())
                .with_capabilities(mls_group_create_config.capabilities.clone())
                .with_capabilities_policy(mls_group_create_config.capabilities_policy)
                .get_secrets(provider, signer)
                .map_err(|e| match e {
                    PublicGroupBuildError::LibraryError(e) => NewGroupError::LibraryError(e),
                    PublicGroupBuildError::InvalidExtensions(e) => e.into(),
                    PublicGroupBuildError::LeafNodeBuild(e) => e.into(),
                })?;

        let serialized_group_context = public_group_builder
            .group_context()
            .tls_serialize_detached()
            .map_err(LibraryError::missing_bound_check)?;

        // Derive an initial joiner secret based on the commit secret.
        // Derive an epoch secret from the joiner secret.
        // We use a random `InitSecret` for initialization.
        let joiner_secret = JoinerSecret::new(
            provider.crypto(),
            ciphersuite,
            commit_secret,
            &InitSecret::random(ciphersuite, provider.rand())
                .map_err(LibraryError::unexpected_crypto_error)?,
            &serialized_group_context,
        )
        .map_err(LibraryError::unexpected_crypto_error)?;

        // TODO(#1357)
        let mut resumption_psk_store = ResumptionPskStore::new(32);

        // Prepare the PskSecret
        let psk_secret = load_psks(provider.storage(), &resumption_psk_store, &self.psk_ids)
            .await
            .and_then(|psks| PskSecret::new(provider.crypto(), ciphersuite, psks))
            .map_err(|e| {
                log::debug!("Unexpected PSK error: {e:?}");
                LibraryError::custom("Unexpected PSK error")
            })?;

        let mut key_schedule =
            KeySchedule::init(ciphersuite, provider.crypto(), &joiner_secret, psk_secret)?;
        key_schedule
            .add_context(provider.crypto(), &serialized_group_context)
            .map_err(|_| LibraryError::custom("Using the key schedule in the wrong state"))?;

        let EpochSecretsResult {
            epoch_secrets,
            #[cfg(feature = "extensions-draft")]
            application_exporter,
        } = key_schedule
            .epoch_secrets(provider.crypto(), ciphersuite)
            .map_err(|_| LibraryError::custom("Using the key schedule in the wrong state"))?;

        let (group_epoch_secrets, message_secrets) = epoch_secrets.split_secrets(
            serialized_group_context,
            TreeSize::new(1),
            LeafNodeIndex::new(0u32),
        );

        let initial_confirmation_tag = message_secrets
            .confirmation_key()
            .tag(provider.crypto(), ciphersuite, &[])
            .map_err(LibraryError::unexpected_crypto_error)?;

        let message_secrets_store = MessageSecretsStore::new_with_secret(
            mls_group_create_config
                .join_config
                .past_epoch_deletion_policy(),
            message_secrets,
        );

        let public_group = public_group_builder
            .with_confirmation_tag(initial_confirmation_tag)
            .build(provider.crypto())?;

        // We already add a resumption PSK for epoch 0 to make things more unified.
        let resumption_psk = group_epoch_secrets.resumption_psk();
        resumption_psk_store.add(public_group.group_context().epoch(), resumption_psk.clone());

        #[cfg(feature = "extensions-draft")]
        #[cfg_attr(not(feature = "virtual-clients-draft"), allow(unused_mut))]
        let mut application_export_tree = ApplicationExportTree::new(application_exporter);

        // The initial epoch of an emulation group is a derivation epoch.
        #[cfg(feature = "virtual-clients-draft")]
        if mls_group_create_config.emulation_group {
            crate::components::vc_derivation_info::register_vc_derivation_epoch(
                provider.crypto(),
                provider.storage(),
                Some(&mut application_export_tree),
                crate::components::vc_derivation_info::VcDerivationEpochParams::for_public_group(
                    &public_group,
                    LeafNodeIndex::new(0),
                    mls_group_create_config
                        .join_config
                        .vc_derivation_epoch_retention_policy()
                        .clone(),
                ),
            )
            .await?;
        }

        let mls_group = MlsGroup {
            mls_group_config: mls_group_create_config.join_config.clone(),
            own_leaf_nodes: vec![],
            aad: vec![],
            #[cfg(feature = "extensions-draft")]
            safe_aad: crate::framing::SafeAad::empty(),
            group_state: MlsGroupState::Operational,
            public_group,
            group_epoch_secrets,
            own_leaf_index: LeafNodeIndex::new(0),
            message_secrets_store,
            resumption_psk_store,
            #[cfg(feature = "extensions-draft")]
            application_export_tree: Some(application_export_tree),
            #[cfg(feature = "virtual-clients-draft")]
            emulation_group: mls_group_create_config.emulation_group,
        };

        mls_group
            .store(provider.storage())
            .await
            .map_err(NewGroupError::StorageError)?;
        mls_group
            .store_epoch_keypairs(provider.storage(), &[leaf_keypair])
            .await
            .map_err(NewGroupError::StorageError)?;

        Ok(mls_group)
    }

    // MlsGroupCreateConfigBuilder options

    /// Sets the `wire_format` property of the MlsGroup.
    pub fn with_wire_format_policy(mut self, wire_format_policy: WireFormatPolicy) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .wire_format_policy(wire_format_policy);
        self
    }

    /// Sets the `padding_size` property of the MlsGroup.
    pub fn padding_size(mut self, padding_size: usize) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .padding_size(padding_size);
        self
    }

    /// Sets the `max_past_epochs` property of the MlsGroup.
    /// This allows application messages from previous epochs to be decrypted.
    ///
    /// This method overrides the policy set by [`Self::set_past_epoch_deletion_policy()`],
    /// and is equivalent to setting the past epoch deletion policy to
    /// `PastEpochDeletionPolicy::MaxEpochs(max_past_epochs)`.
    ///
    /// **WARNING**
    ///
    ///
    /// This feature enables the storage of message secrets from past epochs.
    /// It is a trade-off between functionality and forward secrecy and should only be enabled
    /// if the Delivery Service cannot guarantee that application messages will be sent in
    /// the same epoch in which they were generated. The number for `max_epochs` should be
    /// as low as possible.
    ///
    /// NOTE: This function will be deprecated in future releases.
    pub fn max_past_epochs(mut self, max_past_epochs: usize) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .max_past_epochs(max_past_epochs);
        self
    }

    /// Set the policy for deleting past epoch secrets.
    ///
    /// By default, storage of past epoch secrets is disabled.
    ///
    /// This method overrides the configuration set by [`Self::max_past_epochs()`].
    ///
    /// **WARNING**
    ///
    /// This feature enables the storage of message secrets from past epochs.
    /// It is a trade-off between functionality and forward secrecy and should only be enabled
    /// if the Delivery Service cannot guarantee that application messages will be sent in
    /// the same epoch in which they were generated. The number for `max_epochs` should be
    /// as low as possible.
    pub fn set_past_epoch_deletion_policy(mut self, policy: PastEpochDeletionPolicy) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .set_past_epoch_deletion_policy(policy);
        self
    }

    /// Sets the derivation-epoch retention policy. See
    /// [`VcDerivationEpochRetentionPolicy`](crate::group::VcDerivationEpochRetentionPolicy).
    #[cfg(feature = "virtual-clients-draft")]
    pub fn set_vc_derivation_epoch_retention_policy(
        mut self,
        policy: crate::group::VcDerivationEpochRetentionPolicy,
    ) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .set_vc_derivation_epoch_retention_policy(policy);
        self
    }

    /// Sets the `number_of_resumption_psks` property of the MlsGroup.
    pub fn number_of_resumption_psks(mut self, number_of_resumption_psks: usize) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .number_of_resumption_psks(number_of_resumption_psks);
        self
    }

    /// Sets the `use_ratchet_tree_extension` property of the MlsGroup.
    pub fn use_ratchet_tree_extension(mut self, use_ratchet_tree_extension: bool) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .use_ratchet_tree_extension(use_ratchet_tree_extension);
        self
    }

    /// Sets the `sender_ratchet_configuration` property of the MlsGroup.
    /// See [`SenderRatchetConfiguration`] for more information.
    pub fn sender_ratchet_configuration(
        mut self,
        sender_ratchet_configuration: SenderRatchetConfiguration,
    ) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .sender_ratchet_configuration(sender_ratchet_configuration);
        self
    }

    /// Sets the `lifetime` of the group creator's leaf.
    pub fn lifetime(mut self, lifetime: Lifetime) -> Self {
        self.mls_group_create_config_builder =
            self.mls_group_create_config_builder.lifetime(lifetime);
        self
    }

    /// Sets the `ciphersuite` of the MlsGroup.
    pub fn ciphersuite(mut self, ciphersuite: Ciphersuite) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .ciphersuite(ciphersuite);
        self
    }

    /// Sets the initial group context extensions
    pub fn with_group_context_extensions(mut self, extensions: Extensions<GroupContext>) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .with_group_context_extensions(extensions);
        self
    }

    /// Sets the initial leaf node extensions
    pub fn with_leaf_node_extensions(
        mut self,
        extensions: Extensions<LeafNode>,
    ) -> Result<Self, LeafNodeValidationError> {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .with_leaf_node_extensions(extensions)?;
        Ok(self)
    }

    /// Sets the group creator's [`Capabilities`]
    ///
    /// See [`MlsGroupCreateConfigBuilder::capabilities`] for what setting them
    /// explicitly implies.
    pub fn with_capabilities(mut self, capabilities: Capabilities) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .capabilities(capabilities);
        self
    }

    /// Sets how the group creator's [`Capabilities`] are treated when they
    /// don't cover what the leaf needs.
    ///
    /// See [`MlsGroupCreateConfigBuilder::capabilities_policy`].
    pub fn with_capabilities_policy(mut self, policy: CapabilitiesPolicy) -> Self {
        self.mls_group_create_config_builder = self
            .mls_group_create_config_builder
            .capabilities_policy(policy);
        self
    }
}

/// Builder that creates a fresh sub-group and its branch commit in a single
/// step, as described in [RFC 9420 §11.3].
///
/// Create this with [`MlsGroupBuilder::branch`].
///
/// [RFC 9420 §11.3]: https://www.rfc-editor.org/rfc/rfc9420.html#name-subgroup-branching
pub struct BranchGroupBuilder {
    group_builder: MlsGroupBuilder,
    branch_info: BranchInfo,
    extensions: Option<Extensions<GroupContext>>,
    force_self_update: bool,
}

impl BranchGroupBuilder {
    /// Add a [`GroupContextExtensions`](crate::extensions::Extensions) proposal
    /// to the branch commit. See
    /// [`CommitBuilder::propose_group_context_extensions`](crate::group::CommitBuilder::propose_group_context_extensions).
    pub fn propose_group_context_extensions(
        mut self,
        extensions: Extensions<GroupContext>,
    ) -> Self {
        self.extensions = Some(extensions);
        self
    }

    /// Force a self-update (path) in the branch commit. See
    /// [`CommitBuilder::force_self_update`](crate::group::CommitBuilder::force_self_update).
    pub fn force_self_update(mut self, force_self_update: bool) -> Self {
        self.force_self_update = force_self_update;
        self
    }

    /// Create the sub-group and the branch commit that adds `new_members` to it.
    ///
    /// This creates a fresh group with the parent's ciphersuite, adds the branch
    /// resumption PSK (mixing in the parent's resumption PSK secret), and commits
    /// the additions (plus any extra proposals set via
    /// [`Self::propose_group_context_extensions`] / [`Self::force_self_update`]).
    /// It returns the new (epoch-0) sub-group and the [`CommitMessageBundle`]
    /// carrying the branch commit and `Welcome`.
    ///
    /// The commit is staged but **not** merged: merge it with
    /// [`MlsGroup::merge_pending_commit`](crate::group::MlsGroup::merge_pending_commit)
    /// only once the delivery service has confirmed it.
    #[openmls_traits::maybe_async]
    pub async fn build_branch<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        signer: &impl Signer,
        credential_with_key: CredentialWithKey,
        new_members: Vec<KeyPackage>,
    ) -> Result<(MlsGroup, CommitMessageBundle), BranchError<Provider::StorageError>> {
        // The sub-group must use the same ciphersuite as the parent group.
        let group_builder = self
            .group_builder
            .ciphersuite(self.branch_info.ciphersuite());
        let mut group = group_builder
            .build(provider, signer, credential_with_key)
            .await?;

        let mut builder = group
            .commit_builder()
            .branch(provider.rand(), &self.branch_info)?
            .propose_adds(new_members);
        if let Some(extensions) = self.extensions {
            builder = builder.propose_group_context_extensions(extensions)?;
        }
        if self.force_self_update {
            builder = builder.force_self_update(true);
        }
        let bundle = builder
            .load_psks(provider.storage())
            .await?
            .build(provider.rand(), provider.crypto(), signer, |_| true)?
            .stage_commit(provider)
            .await?;

        Ok((group, bundle))
    }
}

/// Indicates an error occurred while creating a sub-group branch with
/// [`BranchGroupBuilder::build_branch`].
#[derive(Debug, thiserror::Error)]
pub enum BranchError<StorageError> {
    /// An error occurred while creating the sub-group.
    #[error(transparent)]
    NewGroup(#[from] NewGroupError<StorageError>),
    /// An error occurred while creating the branch commit.
    #[error(transparent)]
    CreateCommit(#[from] CreateCommitError),
    /// An error occurred while staging the branch commit.
    #[error(transparent)]
    CommitBuilderStage(#[from] CommitBuilderStageError<StorageError>),
}

/// Builder that creates a freshly reinitialized group and its reinit commit in a single
/// step, as described in [RFC 9420 §11.2].
///
/// This overrides the group_id, ciphersuite and group_context.extensions of the group_builder
/// with value from the ReInit proposal.
///
/// Create this with [`MlsGroupBuilder::reinit`].
///
/// [RFC 9420 §11.2]: https://www.rfc-editor.org/rfc/rfc9420.html#name-reinitialization
pub struct ReInitGroupBuilder {
    group_builder: MlsGroupBuilder,
    reinit_info: ReInitInfo,
    force_self_update: bool,
}

impl ReInitGroupBuilder {
    /// Force a self-update (path) in the reinit commit. See
    /// [`CommitBuilder::force_self_update`](crate::group::CommitBuilder::force_self_update).
    pub fn force_self_update(mut self, force_self_update: bool) -> Self {
        self.force_self_update = force_self_update;
        self
    }

    /// Create the reinitialized group and a reinit commit that adds `members` to it.
    /// The application must ensure that `members` match the members of the predecessor group,
    /// otherwise joiners will reject the Welcome, see also [`JoinBuilder::check_members`](crate::group::mls_group::creation::JoinBuilder::check_members).
    ///
    /// This creates a fresh group with the ReInit proposal's group_id, ciphersuite and
    /// group_context.extensions, adds the reinit
    /// resumption PSK (mixing in the old group's resumption PSK secret), and commits
    /// the additions (plus [`Self::force_self_update`]).
    /// It returns the new (epoch-0) group and the [`CommitMessageBundle`]
    /// carrying the first commit and `Welcome`.
    ///
    /// The commit is staged but **not** merged: merge it with
    /// [`MlsGroup::merge_pending_commit`](crate::group::MlsGroup::merge_pending_commit)
    /// only once the delivery service has confirmed it.
    #[openmls_traits::maybe_async]
    pub async fn build_reinit<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        signer: &impl Signer,
        credential_with_key: CredentialWithKey,
        members: impl IntoIterator<Item = KeyPackage>,
    ) -> Result<(MlsGroup, CommitMessageBundle), ReInitError<Provider::StorageError>> {
        // The group must match the proposal.
        let ReInitInfo {
            proposal,
            old_group_id,
            old_group_epoch,
            resumption_psk_secret,
            member_credentials: _,
        } = self.reinit_info;
        let group_builder = self
            .group_builder
            .ciphersuite(proposal.ciphersuite)
            .with_group_id(proposal.group_id)
            .with_group_context_extensions(proposal.extensions);
        let mut group = group_builder
            .build(provider, signer, credential_with_key)
            .await?;

        let mut commit_builder = group
            .commit_builder()
            .reinit(
                provider.rand(),
                old_group_id,
                old_group_epoch,
                resumption_psk_secret,
            )?
            .propose_adds(members);
        if self.force_self_update {
            commit_builder = commit_builder.force_self_update(true);
        }
        let bundle = commit_builder
            .load_psks(provider.storage())
            .await?
            .build(provider.rand(), provider.crypto(), signer, |_| true)?
            .stage_commit(provider)
            .await?;

        Ok((group, bundle))
    }
}

/// Indicates an error occurred while creating a reinitialized group with
/// [`ReInitGroupBuilder::build_reinit`].
#[derive(Debug, thiserror::Error)]
pub enum ReInitError<StorageError> {
    /// An error occurred while creating the sub-group.
    #[error(transparent)]
    NewGroup(#[from] NewGroupError<StorageError>),
    /// An error occurred while creating the reinit commit.
    #[error(transparent)]
    CreateCommit(#[from] CreateCommitError),
    /// An error occurred while staging the reinit commit.
    #[error(transparent)]
    CommitBuilderStage(#[from] CommitBuilderStageError<StorageError>),
}

/// Create a new group with the virtual client as the creator (epoch 0, single
/// leaf).
///
/// The creator's leaf is `key_package`-sourced and its key material is derived
/// from a fresh `key_package` operation secret of the derivation epoch
/// `epoch_id` (batch index 0). The epoch-0 `epoch_secret` is derived from the
/// same KeyPackage seed under the created group's ciphersuite. A sibling
/// emulator client reconstructs this exact state with
/// [`MlsGroup::vc_join_at_creation`]: it shares the operation secret tree, so it
/// rederives the same seed and hence the same epoch secret without any secret
/// travelling on the wire. Because the `epoch_secret` is derived rather than run
/// through the joiner key schedule, this path bypasses it entirely.
///
/// [`MlsGroup::vc_join_at_creation`]: crate::group::MlsGroup::vc_join_at_creation
#[cfg(feature = "virtual-clients-draft")]
#[allow(clippy::too_many_arguments)]
#[openmls_traits::maybe_async]
async fn build_vc_internal<Provider: OpenMlsProvider>(
    provider: &Provider,
    signer: &impl Signer,
    credential_with_key: CredentialWithKey,
    mls_group_create_config: MlsGroupCreateConfig,
    group_id: GroupId,
    replace_old_group: bool,
    epoch_id: crate::components::vc_derivation_info::EpochId,
) -> Result<MlsGroup, NewGroupError<Provider::StorageError>> {
    use openmls_traits::storage::StorageProvider as _;

    use crate::{
        components::vc_derivation_info::{
            load_vc_epoch_state_and_tree, DerivationInfo, DerivationInfoTbe,
            VirtualClientOperationType, VirtualClientsError,
        },
        schedule::EpochSecrets,
        treesync::TreeSync,
    };

    if !replace_old_group
        && MlsGroup::load(provider.storage(), &group_id)
            .await
            .map_err(NewGroupError::StorageError)?
            .is_some()
    {
        return Err(NewGroupError::GroupAlreadyExists);
    }

    let ciphersuite = mls_group_create_config.ciphersuite;
    let (capabilities, capabilities_policy) = resolve_capabilities(
        mls_group_create_config.capabilities.clone(),
        mls_group_create_config.capabilities_policy,
    );

    // Validate that the creator's leaf declares `AppDataDictionary` and lists
    // `VC_COMPONENT_ID` before allocating a generation, so a deterministic
    // precondition failure does not burn an operation secret.
    let resolved_dictionary = crate::components::vc_derivation_info::resolve_vc_leaf_dictionary(
        Some(&capabilities),
        Some(&mls_group_create_config.leaf_node_extensions),
        None,
    )?;

    // Load the derivation epoch state and operation tree, allocate a fresh
    // `key_package` generation (empty operation context, matching the KeyPackage
    // batch path), and persist the advanced tree right away. A retried creation
    // consumes a fresh generation.
    let (state, mut operation_tree) = load_vc_epoch_state_and_tree(provider, &epoch_id).await?;
    let (emulation_leaf_index, epoch_encryption_key, emulation_ciphersuite) = state.into_parts();
    let (generation, operation_secret) = operation_tree.next_operation_secret(
        provider.crypto(),
        emulation_ciphersuite,
        &epoch_id,
        emulation_leaf_index,
        VirtualClientOperationType::KeyPackage,
        b"",
    )?;
    provider
        .storage()
        .write_vc_operation_tree(&epoch_id, &operation_tree)
        .await
        .map_err(NewGroupError::StorageError)?;

    // The creator batch consists of this single derivation and is closed
    // immediately: no `KeyPackageUpload` is sent and no
    // `RetainedKeyPackageMaterial` is written, because a creator leaf has no
    // KeyPackage / KeyPackageRef. Import the per-KeyPackage seed (index 0) under
    // the created group's ciphersuite, then derive the creator leaf's encryption
    // keypair and the epoch-0 secret from that seed.
    let key_package_index = 0;
    let key_package_seed = operation_secret.derive_key_package_seed_secret(
        provider.crypto(),
        ciphersuite,
        key_package_index,
    )?;
    let leaf_encryption_keypair = key_package_seed
        .derive_encryption_key_secret(provider.crypto(), ciphersuite)?
        .generate_encryption_key_pair(provider.crypto(), ciphersuite)?;
    let epoch_secret =
        key_package_seed.derive_group_creation_secret(provider.crypto(), ciphersuite)?;

    // Wrap the derivation info under the per-epoch AEAD key, bound to the leaf
    // via its serialized encryption key.
    let leaf_encryption_key = leaf_encryption_keypair
        .public_key()
        .tls_serialize_detached()
        .map_err(VirtualClientsError::from)?;
    let tbe = DerivationInfoTbe::KeyPackage {
        leaf_index: emulation_leaf_index,
        generation,
        key_package_index,
    };
    let derivation_info = DerivationInfo::encrypt(
        provider.crypto(),
        emulation_ciphersuite,
        &epoch_encryption_key,
        epoch_id.clone(),
        &leaf_encryption_key,
        &tbe,
    )?;
    let derivation_info_bytes = derivation_info
        .tls_serialize_detached()
        .map_err(VirtualClientsError::from)?;
    let leaf_extensions = crate::components::vc_derivation_info::merge_vc_derivation_info(
        Some(&mls_group_create_config.leaf_node_extensions),
        resolved_dictionary,
        derivation_info_bytes,
    )?;

    // Build the single-leaf tree with the derived key_package-sourced leaf.
    let (treesync, leaf_keypair) = TreeSync::new_vc(
        provider,
        signer,
        ciphersuite,
        credential_with_key,
        *mls_group_create_config.lifetime(),
        capabilities,
        leaf_extensions,
        leaf_encryption_keypair,
        LeafNodeConstraints::from_group_context_extensions(
            &mls_group_create_config.group_context_extensions,
        ),
        capabilities_policy,
    )?;
    let group_context = GroupContext::create_initial_group_context(
        ciphersuite,
        group_id.clone(),
        treesync.tree_hash().to_vec(),
        mls_group_create_config.group_context_extensions.clone(),
    );
    let serialized_group_context = group_context
        .tls_serialize_detached()
        .map_err(LibraryError::missing_bound_check)?;

    // Derive epoch-0 secrets from the epoch secret derived above.
    let epoch_secrets =
        EpochSecrets::from_epoch_secret(provider.crypto(), ciphersuite, epoch_secret)
            .map_err(LibraryError::unexpected_crypto_error)?;
    let (group_epoch_secrets, message_secrets) = epoch_secrets.split_secrets(
        serialized_group_context,
        TreeSize::new(1),
        LeafNodeIndex::new(0),
    );
    let initial_confirmation_tag = message_secrets
        .confirmation_key()
        .tag(provider.crypto(), ciphersuite, &[])
        .map_err(LibraryError::unexpected_crypto_error)?;
    let message_secrets_store = MessageSecretsStore::new_with_secret(
        mls_group_create_config
            .join_config
            .past_epoch_deletion_policy(),
        message_secrets,
    );
    let public_group = PublicGroup::new(
        provider.crypto(),
        treesync,
        group_context,
        initial_confirmation_tag,
    )?;

    let mut resumption_psk_store = ResumptionPskStore::new(32);
    let resumption_psk = group_epoch_secrets.resumption_psk();
    resumption_psk_store.add(public_group.group_context().epoch(), resumption_psk.clone());

    let mls_group = MlsGroup {
        mls_group_config: mls_group_create_config.join_config.clone(),
        own_leaf_nodes: vec![],
        aad: vec![],
        safe_aad: crate::framing::SafeAad::empty(),
        group_state: MlsGroupState::Operational,
        public_group,
        group_epoch_secrets,
        own_leaf_index: LeafNodeIndex::new(0),
        message_secrets_store,
        resumption_psk_store,
        // Reconstructed VC groups do not populate the application export tree,
        // matching the other VC group-entry paths.
        application_export_tree: None,
        // A group a virtual client creates is not itself an emulation group.
        emulation_group: false,
    };

    // Bind epoch 0 of the new group to the derivation epoch so later VC
    // operations in this group resolve the right derivation epoch state.
    // Written before the group itself, so an error between the writes cannot
    // leave a loadable group without a binding (a bound group is required for
    // the reuse-guard MUST).
    let max_entries = mls_group.message_secrets_store.max_epochs.saturating_add(1);
    crate::components::vc_derivation_info::write_vc_emulation_binding_with_pruning(
        provider.storage(),
        &group_id,
        mls_group.epoch(),
        epoch_id,
        max_entries,
    )
    .await
    .map_err(NewGroupError::StorageError)?;

    mls_group
        .store(provider.storage())
        .await
        .map_err(NewGroupError::StorageError)?;
    mls_group
        .store_epoch_keypairs(provider.storage(), &[leaf_keypair])
        .await
        .map_err(NewGroupError::StorageError)?;

    Ok(mls_group)
}