Skip to main content

arachne_security/
management.rs

1//! Exact administrator actions, verified against the receiver's accepted state.
2//! Verification alone does not adopt, persist, disseminate or finalize a change.
3use super::{AUTHORITY, JoinProof, Workspace, bootstrap, storage};
4use openmls::prelude::tls_codec::{Deserialize, Serialize};
5use openmls::prelude::*;
6use openmls_traits::{OpenMlsProvider, crypto::OpenMlsCrypto, signatures::Signer};
7
8/// One authenticated membership or invitation-management intent.
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum ManagementAction {
11    Promote([u8; 32]),
12    Demote([u8; 32]),
13    Remove([u8; 32]),
14    /// A member's signature authorizes only their own departure from this branch.
15    Leave([u8; 32], [u8; 64]),
16    CreateInvitation([u8; 32], u64, bool),
17    CreateAutomaticInvitation([u8; 32], u64),
18    CreateRequestInvitation([u8; 32], u64),
19    DeclineInvitationRequest([u8; 32], [u8; 32]),
20    DisableInvitation([u8; 32]),
21    ApproveInvitation([u8; 32], [u8; 32]),
22}
23
24impl ManagementAction {
25    pub fn target(self) -> [u8; 32] {
26        match self {
27            Self::Promote(id)
28            | Self::Demote(id)
29            | Self::Remove(id)
30            | Self::Leave(id, _)
31            | Self::CreateInvitation(id, ..)
32            | Self::CreateRequestInvitation(id, ..)
33            | Self::DeclineInvitationRequest(id, _)
34            | Self::CreateAutomaticInvitation(id, ..)
35            | Self::DisableInvitation(id)
36            | Self::ApproveInvitation(id, _) => id,
37        }
38    }
39    fn removes(self) -> bool {
40        matches!(self, Self::Remove(_) | Self::Leave(..))
41    }
42}
43
44fn leave_payload(context: &GroupContext, member: [u8; 32]) -> Result<Vec<u8>, &'static str> {
45    let mut bytes = b"data-fabric/leave/v1\0".to_vec();
46    bytes.extend(
47        context
48            .tls_serialize_detached()
49            .map_err(|_| "leave context encoding failed")?,
50    );
51    bytes.extend(member);
52    Ok(bytes)
53}
54
55fn verify_leave(
56    crypto: &impl OpenMlsCrypto,
57    context: &GroupContext,
58    key: &[u8],
59    action: ManagementAction,
60) -> Result<(), &'static str> {
61    if let ManagementAction::Leave(id, signature) = action {
62        crypto
63            .verify_signature(
64                super::SUITE.signature_algorithm(),
65                &leave_payload(context, id)?,
66                key,
67                &signature,
68            )
69            .map_err(|_| "invalid leave signature or membership branch")?;
70    }
71    Ok(())
72}
73
74/// Provisional local change. Save the returned workspace before adopting it or
75/// distributing the commit; the original owner is unchanged.
76pub struct PreparedManagement {
77    pub workspace: Workspace,
78    pub action: ManagementAction,
79    pub commit: Vec<u8>,
80}
81
82/// One provisional receiver result. Hosts must persist the matching variant
83/// before adoption, and must never configure data delivery from Removed.
84pub enum PreparedManagementUpdate {
85    Active(Box<Workspace>),
86    Removed(super::RemovedMembership),
87}
88
89impl Workspace {
90    /// Sign a departure from this exact membership branch. Another admitted
91    /// member must commit it; signing alone neither leaves nor changes keys.
92    pub fn leave_action(&self) -> Result<ManagementAction, &'static str> {
93        let member = self.member().ok_or("member identity required")?;
94        let roster = self.member_roster()?;
95        if roster
96            .iter()
97            .any(|m| m.id == member.id() && m.administrator)
98            && roster.iter().filter(|m| m.administrator).count() == 1
99        {
100            return Err("Make another member an administrator before leaving.");
101        }
102        let signature = self
103            ._signer
104            .sign(&leave_payload(
105                super::MembershipVerifier::from_workspace(self)?
106                    .group
107                    .group_context(),
108                member.id(),
109            )?)
110            .map_err(|_| "leave signing failed")?
111            .try_into()
112            .map_err(|_| "invalid leave signature length")?;
113        Ok(ManagementAction::Leave(member.id(), signature))
114    }
115
116    /// A one-member workspace has no peer to notify or remaining keys to rotate.
117    /// Persist this terminal record before shutting down its local owner.
118    pub fn prepare_solo_leave(&self) -> Result<super::RemovedMembership, &'static str> {
119        if self.member_count() != 1 {
120            return Err("another member must accept the departure");
121        }
122        let member = self.member().ok_or("member identity required")?;
123        use sha2::Digest;
124        Ok(super::RemovedMembership::verified(
125            self.id,
126            self.endpoint,
127            member.clone(),
128            self.epoch(),
129            sha2::Sha256::digest(leave_payload(
130                super::MembershipVerifier::from_workspace(self)?
131                    .group
132                    .group_context(),
133                member.id(),
134            )?)
135            .into(),
136        )
137        .for_solo_leave())
138    }
139
140    /// Copy accepted state for one provisional operation without serializing it.
141    /// Discard rejected candidates; persist an accepted candidate before adopting
142    /// it or emitting its output. Never use copies as independent senders: their
143    /// ratchets and counters start at the same position.
144    pub fn provisional_copy(&self) -> Result<Workspace, &'static str> {
145        // ponytail: copies the full native state; use provider transactions if
146        // measured staging memory or latency requires incremental copies.
147        let provider = storage::copy_provider(&self.provider)?;
148        let group = MlsGroup::load(provider.storage(), &GroupId::from_slice(&self.id))
149            .map_err(|_| "workspace state copy failed")?
150            .ok_or("missing workspace state copy")?;
151        let signer = openmls_basic_credential::SignatureKeyPair::read(
152            provider.storage(),
153            self._signer.public(),
154            super::SUITE.signature_algorithm(),
155        )
156        .ok_or("missing workspace signer")?;
157        Ok(Workspace {
158            provider,
159            group,
160            _signer: signer,
161            id: self.id,
162            endpoint: self.endpoint,
163            member: self.member.clone(),
164            admissions: self.admissions.clone(),
165            join_history: self.join_history.clone(),
166            invitation_checkpoints: self.invitation_checkpoints.clone(),
167        })
168    }
169
170    pub fn prepare_management(
171        &self,
172        action: ManagementAction,
173    ) -> Result<PreparedManagement, &'static str> {
174        let mut admins = bootstrap::authority(self.group.extensions())?;
175        if !matches!(action, ManagementAction::Leave(..))
176            && !admins.iter().any(|key| key == self._signer.public())
177        {
178            return Err("management actor is not an administrator");
179        }
180        if matches!(
181            action,
182            ManagementAction::CreateInvitation(..)
183                | ManagementAction::CreateRequestInvitation(..)
184                | ManagementAction::DeclineInvitationRequest(..)
185                | ManagementAction::CreateAutomaticInvitation(..)
186                | ManagementAction::DisableInvitation(_)
187                | ManagementAction::ApproveInvitation(..)
188        ) {
189            return super::invitation_controls::prepare(self, action);
190        }
191        let id = action.target();
192        let target = self
193            .group
194            .members()
195            .find(|m| bootstrap::binding(&m.credential).is_ok_and(|b| b.0 == id))
196            .ok_or("management target is not a current member")?;
197        verify_leave(
198            self.provider.crypto(),
199            super::MembershipVerifier::from_workspace(self)?
200                .group
201                .group_context(),
202            &target.signature_key,
203            action,
204        )?;
205        let had_role = admins.contains(&target.signature_key);
206        match action {
207            ManagementAction::CreateInvitation(..)
208            | ManagementAction::CreateRequestInvitation(..)
209            | ManagementAction::DeclineInvitationRequest(..)
210            | ManagementAction::CreateAutomaticInvitation(..)
211            | ManagementAction::DisableInvitation(_)
212            | ManagementAction::ApproveInvitation(..) => unreachable!(),
213            ManagementAction::Promote(_) => {
214                if had_role {
215                    return Err("member is already an administrator");
216                }
217                admins.push(target.signature_key.clone());
218                admins.sort();
219            }
220            ManagementAction::Demote(_) => {
221                if !had_role {
222                    return Err("member is not an administrator");
223                }
224                admins.retain(|key| key != &target.signature_key);
225            }
226            ManagementAction::Remove(_) | ManagementAction::Leave(..) => {
227                if target.index == self.group.own_leaf_index() {
228                    return Err("self removal requires a separate leave operation");
229                }
230                admins.retain(|key| key != &target.signature_key);
231            }
232        }
233        if admins.is_empty() {
234            return Err("cannot remove the last administrator");
235        }
236        let mut candidate = self.provisional_copy()?;
237        let role_change = !action.removes() || had_role;
238        let mut builder = candidate.group.commit_builder();
239        if action.removes() {
240            builder = builder.propose_removals([target.index]);
241        }
242        if role_change {
243            let bytes =
244                super::invitation_controls::replace_admins(self.group.extensions(), &admins)?;
245            let extensions = Extensions::from_vec(
246                self.group
247                    .extensions()
248                    .iter()
249                    .map(|e| {
250                        if e.extension_type() == ExtensionType::Unknown(AUTHORITY) {
251                            Extension::Unknown(AUTHORITY, UnknownExtension(bytes.clone()))
252                        } else {
253                            e.clone()
254                        }
255                    })
256                    .collect(),
257            )
258            .map_err(|_| "invalid management extensions")?;
259            builder = builder
260                .propose_group_context_extensions(extensions)
261                .map_err(|_| "management proposal failed")?;
262        }
263        let commit = builder
264            .load_psks(candidate.provider.storage())
265            .map_err(|_| "management proposal state failed")?
266            .build(
267                candidate.provider.rand(),
268                candidate.provider.crypto(),
269                &candidate._signer,
270                |_| true,
271            )
272            .map_err(|_| "management preparation failed")?
273            .stage_commit(&candidate.provider)
274            .map_err(|_| "management staging failed")?
275            .into_contents()
276            .0
277            .to_bytes()
278            .map_err(|_| "management encoding failed")?;
279        let mut proof = super::MembershipVerifier::from_workspace(self)?;
280        proof.apply_transition(&super::MembershipAuthorization::Management(action), &commit)?;
281        candidate
282            .group
283            .merge_pending_commit(&candidate.provider)
284            .map_err(|_| "management merge failed")?;
285        candidate.join_history =
286            Some(self.append_history(super::MembershipAuthorization::Management(action), &commit)?);
287        if !proof.matches_workspace(&candidate)? {
288            return Err("management branch mismatch");
289        }
290        Ok(PreparedManagement {
291            workspace: candidate,
292            action,
293            commit,
294        })
295    }
296
297    /// Stage verified management without changing this owner. Removal returns
298    /// metadata without group keys, for replacement of the active saved record.
299    pub fn prepare_management_update(
300        &self,
301        action: ManagementAction,
302        commit: &[u8],
303    ) -> Result<PreparedManagementUpdate, &'static str> {
304        self.verify_management(action, commit)?;
305        let mut proof = super::MembershipVerifier::from_workspace(self)?;
306        proof.apply_transition(&super::MembershipAuthorization::Management(action), commit)?;
307        let mut candidate = self.provisional_copy()?;
308        let processed = candidate
309            .group
310            .process_message(
311                &candidate.provider,
312                MlsMessageIn::tls_deserialize_exact(commit)
313                    .map_err(|_| "invalid management commit")?
314                    .try_into_protocol_message()
315                    .map_err(|_| "expected management commit")?,
316            )
317            .map_err(|_| "management authentication failed")?;
318        let ProcessedMessageContent::StagedCommitMessage(staged) = processed.into_content() else {
319            return Err("not a management commit");
320        };
321        candidate
322            .group
323            .merge_staged_commit(&candidate.provider, *staged)
324            .map_err(|_| "management merge failed")?;
325        if !candidate.group.is_active() {
326            let member = self.member().ok_or("removed owner lacks member identity")?;
327            if !action.removes() || action.target() != member.id() {
328                return Err("removal does not match local member");
329            }
330            use sha2::Digest;
331            return Ok(PreparedManagementUpdate::Removed(
332                super::RemovedMembership::verified(
333                    self.id,
334                    self.endpoint,
335                    member.clone(),
336                    proof.epoch(),
337                    sha2::Sha256::digest(commit).into(),
338                ),
339            ));
340        }
341        candidate.join_history =
342            Some(self.append_history(super::MembershipAuthorization::Management(action), commit)?);
343        candidate.prune_invitation_checkpoints()?;
344        if !proof.matches_workspace(&candidate)? {
345            return Err("management branch mismatch");
346        }
347        Ok(PreparedManagementUpdate::Active(Box::new(candidate)))
348    }
349
350    /// Authenticate an exact public MLS management commit without changing this
351    /// owner. The expected action is untrusted until it matches the signed commit.
352    /// This checks one branch; it cannot establish global finality across partitions.
353    pub fn verify_management(
354        &self,
355        action: ManagementAction,
356        commit: &[u8],
357    ) -> Result<(), &'static str> {
358        JoinProof::from_workspace(self)?.verify_management(action, commit)?;
359        // PublicGroup checks signatures/policy but cannot check membership tags.
360        // Use a disposable private owner as well; never consume the live state.
361        let provider = storage::copy_provider(&self.provider)?;
362        let mut group = MlsGroup::load(provider.storage(), &GroupId::from_slice(&self.id))
363            .map_err(|_| "workspace state copy failed")?
364            .ok_or("missing workspace state copy")?;
365        let message = MlsMessageIn::tls_deserialize_exact(commit)
366            .map_err(|_| "invalid management commit")?
367            .try_into_protocol_message()
368            .map_err(|_| "expected management commit")?;
369        let processed = group
370            .process_message(&provider, message)
371            .map_err(|_| "management authentication failed")?;
372        if !matches!(
373            processed.into_content(),
374            ProcessedMessageContent::StagedCommitMessage(_)
375        ) {
376            return Err("not a management commit");
377        }
378        Ok(())
379    }
380}
381
382pub(super) fn verify(
383    crypto: &impl OpenMlsCrypto,
384    group: &PublicGroup,
385    sender: &Sender,
386    staged: &StagedCommit,
387    action: ManagementAction,
388) -> Result<(), &'static str> {
389    let Sender::Member(actor_index) = sender else {
390        return Err("management actor is not a member");
391    };
392    let members: Vec<_> = group.members().collect();
393    let actor = members
394        .iter()
395        .find(|m| m.index == *actor_index)
396        .ok_or("unknown management actor")?;
397    let before = bootstrap::authority(group.group_context().extensions())?;
398    if !matches!(action, ManagementAction::Leave(..)) && !before.contains(&actor.signature_key) {
399        return Err("management actor is not an administrator");
400    }
401    if matches!(
402        action,
403        ManagementAction::CreateInvitation(..)
404            | ManagementAction::CreateRequestInvitation(..)
405            | ManagementAction::DeclineInvitationRequest(..)
406            | ManagementAction::CreateAutomaticInvitation(..)
407            | ManagementAction::DisableInvitation(_)
408            | ManagementAction::ApproveInvitation(..)
409    ) {
410        return super::invitation_controls::verify(group, sender, actor, staged, action);
411    }
412    let id = action.target();
413    let mut target = None;
414    for member in &members {
415        if bootstrap::binding(&member.credential)?.0 == id {
416            if target.is_some() {
417                return Err("ambiguous management target");
418            }
419            target = Some(member);
420        }
421    }
422    let target = target.ok_or("management target is not a current member")?;
423    verify_leave(crypto, group.group_context(), &target.signature_key, action)?;
424    if before
425        .iter()
426        .any(|key| members.iter().filter(|m| &m.signature_key == key).count() != 1)
427    {
428        return Err("administrator key must identify one current member");
429    }
430    let was_admin = before.contains(&target.signature_key);
431    let mut expected = before.clone();
432    match action {
433        ManagementAction::CreateInvitation(..)
434        | ManagementAction::CreateRequestInvitation(..)
435        | ManagementAction::DeclineInvitationRequest(..)
436        | ManagementAction::CreateAutomaticInvitation(..)
437        | ManagementAction::DisableInvitation(_)
438        | ManagementAction::ApproveInvitation(..) => unreachable!(),
439        ManagementAction::Promote(_) => {
440            if was_admin {
441                return Err("member is already an administrator");
442            }
443            if members
444                .iter()
445                .filter(|m| m.signature_key == target.signature_key)
446                .count()
447                != 1
448            {
449                return Err("administrator key must identify one current member");
450            }
451            expected.push(target.signature_key.clone());
452            expected.sort();
453        }
454        ManagementAction::Demote(_) => {
455            if !was_admin {
456                return Err("member is not an administrator");
457            }
458            expected.retain(|key| key != &target.signature_key);
459        }
460        ManagementAction::Remove(_) | ManagementAction::Leave(..) => {
461            if target.index == actor.index {
462                return Err("self removal requires a separate leave operation");
463            }
464            expected.retain(|key| key != &target.signature_key);
465        }
466    }
467    if expected.is_empty() {
468        return Err("cannot remove the last administrator");
469    }
470    if super::invitation_controls::policy_bytes(group.group_context().extensions())?
471        != super::invitation_controls::policy_bytes(staged.group_context().extensions())?
472    {
473        return Err("member management changed invitation controls");
474    }
475    let after = bootstrap::authority(staged.group_context().extensions())?;
476    if expected != after {
477        return Err("management authority change does not match intent");
478    }
479    let unrelated = |ext: &Extensions<GroupContext>| {
480        ext.iter()
481            .filter(|e| e.extension_type() != ExtensionType::Unknown(AUTHORITY))
482            .cloned()
483            .collect::<Vec<_>>()
484    };
485    if unrelated(group.group_context().extensions())
486        != unrelated(staged.group_context().extensions())
487    {
488        return Err("management cannot change unrelated group policy");
489    }
490    if let Some(leaf) = staged.update_path_leaf_node()
491        && (leaf.credential() != &actor.credential
492            || leaf.signature_key().as_slice() != actor.signature_key)
493    {
494        return Err("management cannot replace committer identity");
495    }
496    let mut removals = 0;
497    let mut roles = 0;
498    for proposal in staged.queued_proposals() {
499        if proposal.sender() != sender
500            || proposal.proposal_or_ref_type() != ProposalOrRefType::Proposal
501        {
502            return Err("management requires inline actor-authored proposals");
503        }
504        match proposal.proposal() {
505            Proposal::Remove(remove) if action.removes() && remove.removed() == target.index => {
506                removals += 1
507            }
508            Proposal::GroupContextExtensions(_) => roles += 1,
509            _ => return Err("management includes an unrelated proposal"),
510        }
511    }
512    if removals != usize::from(action.removes()) || roles != usize::from(before != expected) {
513        return Err("management proposal count does not match intent");
514    }
515    Ok(())
516}
517
518#[cfg(test)]
519mod tests {
520    use super::*;
521    use crate::{PendingJoin, StorageKey};
522    use openmls::prelude::tls_codec::Deserialize;
523    use openmls_traits::OpenMlsProvider;
524
525    fn add(admin: Workspace, endpoint: u8) -> (Workspace, Workspace, crate::PreparedAdmission) {
526        let (invite, checkpoint) = admin.issue_invitation().unwrap();
527        let pending =
528            PendingJoin::from_invitation(&invite, &checkpoint, [endpoint; 32], "Field member")
529                .unwrap();
530        let prepared = admin
531            .prepare_admission([endpoint; 32], pending.admission_request().unwrap())
532            .unwrap();
533        let mut proof = pending.join_proof().unwrap();
534        proof
535            .apply_add(&prepared.authorization, &prepared.commit)
536            .unwrap();
537        let member = pending
538            .prepare_workspace(&proof, &prepared.welcome)
539            .unwrap();
540        (admin, member, prepared)
541    }
542    fn pair() -> (Workspace, Workspace) {
543        let (_, member, prepared) = add(Workspace::create([1; 32], "Coordinator").unwrap(), 2);
544        (prepared.workspace, member)
545    }
546
547    #[test]
548    fn incremental_verification_has_no_workspace_lifetime_counter() {
549        let (mut admin, member) = pair();
550        let checkpoint = admin.join_checkpoint().unwrap();
551        use sha2::{Digest, Sha256};
552        let mut verifier = crate::MembershipVerifier::from_trusted_checkpoint(
553            admin.id(),
554            Sha256::digest(&checkpoint).into(),
555            &checkpoint,
556        )
557        .unwrap();
558        let id = member.member().unwrap().id();
559        // Raw MLS generation isolates verification from the legacy snapshot and
560        // inline history format. This is not a runtime persistence/scale claim.
561        for sequence in 0..128 {
562            let mut keys = vec![admin._signer.public().to_vec()];
563            let (action, wrong) = if sequence % 2 == 0 {
564                keys.push(member._signer.public().to_vec());
565                (ManagementAction::Promote(id), ManagementAction::Demote(id))
566            } else {
567                (ManagementAction::Demote(id), ManagementAction::Promote(id))
568            };
569            let commit = role_commit(&mut admin, keys);
570            let epoch = verifier.epoch();
571            assert!(
572                verifier
573                    .apply_transition(&crate::MembershipAuthorization::Management(wrong), &commit,)
574                    .is_err()
575            );
576            assert_eq!(verifier.epoch(), epoch);
577            verifier
578                .apply_transition(&crate::MembershipAuthorization::Management(action), &commit)
579                .unwrap_or_else(|error| panic!("transition {}: {error}", sequence + 1));
580            assert!(
581                verifier
582                    .apply_transition(&crate::MembershipAuthorization::Management(action), &commit)
583                    .is_err()
584            );
585            assert_eq!(verifier.epoch(), epoch + 1);
586            admin.group.merge_pending_commit(&admin.provider).unwrap();
587            assert!(verifier.matches_workspace(&admin).unwrap());
588        }
589        assert_eq!(verifier.epoch(), 129);
590    }
591    fn extensions(owner: &Workspace, mut keys: Vec<Vec<u8>>) -> Extensions<GroupContext> {
592        keys.sort();
593        let mut encoded = vec![1, keys.len() as u8];
594        encoded.extend(keys.into_iter().flatten());
595        Extensions::from_vec(
596            owner
597                .group
598                .extensions()
599                .iter()
600                .map(|e| {
601                    if e.extension_type() == ExtensionType::Unknown(AUTHORITY) {
602                        Extension::Unknown(AUTHORITY, UnknownExtension(encoded.clone()))
603                    } else {
604                        e.clone()
605                    }
606                })
607                .collect(),
608        )
609        .unwrap()
610    }
611    fn role_commit(owner: &mut Workspace, keys: Vec<Vec<u8>>) -> Vec<u8> {
612        owner
613            .group
614            .update_group_context_extensions(
615                &owner.provider,
616                extensions(owner, keys),
617                &owner._signer,
618            )
619            .unwrap()
620            .0
621            .to_bytes()
622            .unwrap()
623    }
624    // Test-only merge after the production receiver guard succeeds. No product
625    // management save/adopt/history support is implied by this helper.
626    fn accept(owner: &mut Workspace, action: ManagementAction, commit: &[u8]) {
627        owner.verify_management(action, commit).unwrap();
628        let message = MlsMessageIn::tls_deserialize_exact(commit)
629            .unwrap()
630            .try_into_protocol_message()
631            .unwrap();
632        let processed = owner
633            .group
634            .process_message(&owner.provider, message)
635            .unwrap();
636        let ProcessedMessageContent::StagedCommitMessage(staged) = processed.into_content() else {
637            panic!("not commit")
638        };
639        owner
640            .group
641            .merge_staged_commit(&owner.provider, *staged)
642            .unwrap();
643    }
644    #[test]
645    fn exact_promotion_and_demotion_with_creator_absent() {
646        let (mut admin, mut member) = pair();
647        let member_id = member.member().unwrap().id();
648        let keys = vec![
649            admin._signer.to_public_vec(),
650            member._signer.to_public_vec(),
651        ];
652        let commit = role_commit(&mut admin, keys);
653        let epoch = member.epoch();
654        member
655            .verify_management(ManagementAction::Promote(member_id), &commit)
656            .unwrap();
657        assert_eq!(member.epoch(), epoch);
658        assert!(
659            member
660                .verify_management(ManagementAction::Demote(member_id), &commit)
661                .is_err()
662        );
663        assert!(
664            member
665                .verify_management(ManagementAction::Promote([99; 32]), &commit)
666                .is_err()
667        );
668        let unrelated = Workspace::create([9; 32], "Other workspace").unwrap();
669        assert!(
670            unrelated
671                .verify_management(ManagementAction::Promote(member_id), &commit)
672                .is_err()
673        );
674        let mut tampered = commit.clone();
675        *tampered.last_mut().unwrap() ^= 1;
676        assert!(
677            member
678                .verify_management(ManagementAction::Promote(member_id), &tampered)
679                .is_err()
680        );
681        accept(&mut member, ManagementAction::Promote(member_id), &commit);
682        admin.group.merge_pending_commit(&admin.provider).unwrap();
683        assert!(
684            member
685                .verify_management(ManagementAction::Promote(member_id), &commit)
686                .is_err()
687        );
688        assert!(member.issue_invitation().is_ok());
689        // A current second admin may demote the absent creator, without waiting
690        // for it. The old snapshot is an independent receiver at the parent epoch.
691        let key = StorageKey::derive(&[8; 32]).unwrap();
692        let snapshot = admin.seal(&key).unwrap();
693        let admin_id = admin.member().unwrap().id();
694        let workspace = admin.id();
695        drop(admin);
696        let next_keys = vec![member._signer.to_public_vec()];
697        let demotion = role_commit(&mut member, next_keys);
698        let mut returning = Workspace::restore(&key, [1; 32], workspace, &snapshot).unwrap();
699        accept(
700            &mut returning,
701            ManagementAction::Demote(admin_id),
702            &demotion,
703        );
704        assert!(returning.issue_invitation().is_err());
705        assert_eq!(returning.member_count(), 2);
706    }
707    #[test]
708    fn ordinary_member_cannot_promote_or_remove() {
709        let (admin, mut member) = pair();
710        let member_id = member.member().unwrap().id();
711        let keys = vec![
712            admin._signer.to_public_vec(),
713            member._signer.to_public_vec(),
714        ];
715        let attack = role_commit(&mut member, keys);
716        assert_eq!(
717            admin.verify_management(ManagementAction::Promote(member_id), &attack),
718            Err("management actor is not an administrator")
719        );
720        member
721            .group
722            .clear_pending_commit(member.provider.storage())
723            .unwrap();
724        let index = member
725            .group
726            .members()
727            .find(|m| m.signature_key == admin._signer.public())
728            .unwrap()
729            .index;
730        let attack = member
731            .group
732            .remove_members(&member.provider, &member._signer, &[index])
733            .unwrap()
734            .0
735            .to_bytes()
736            .unwrap();
737        assert_eq!(
738            admin.verify_management(
739                ManagementAction::Remove(admin.member().unwrap().id()),
740                &attack
741            ),
742            Err("management actor is not an administrator")
743        );
744    }
745    #[test]
746    fn exact_removal_and_last_admin_guard() {
747        let (mut admin, mut member) = pair();
748        let id = member.member().unwrap().id();
749        let index = admin
750            .group
751            .members()
752            .find(|m| m.signature_key == member._signer.public())
753            .unwrap()
754            .index;
755        let removal = admin
756            .group
757            .remove_members(&admin.provider, &admin._signer, &[index])
758            .unwrap()
759            .0
760            .to_bytes()
761            .unwrap();
762        member
763            .verify_management(ManagementAction::Remove(id), &removal)
764            .unwrap();
765        assert!(
766            member
767                .verify_management(
768                    ManagementAction::Remove(admin.member().unwrap().id()),
769                    &removal
770                )
771                .is_err()
772        );
773        accept(&mut member, ManagementAction::Remove(id), &removal);
774        assert!(!member.group.is_active());
775        admin
776            .group
777            .clear_pending_commit(admin.provider.storage())
778            .unwrap();
779        let last = role_commit(&mut admin, vec![]);
780        assert_eq!(
781            admin.verify_management(
782                ManagementAction::Demote(admin.member().unwrap().id()),
783                &last
784            ),
785            Err("cannot remove the last administrator")
786        );
787    }
788    fn trio() -> (Workspace, Workspace, Workspace) {
789        let (admin, second) = pair();
790        let (_, third, prepared) = add(admin, 3);
791        let second = second
792            .prepare_admission_update(&prepared.authorization, &prepared.commit)
793            .unwrap();
794        (prepared.workspace, second, third)
795    }
796    fn two_admins() -> (Workspace, Workspace, Workspace) {
797        let (mut admin, mut second, mut third) = trio();
798        let id = second.member().unwrap().id();
799        let keys = vec![
800            admin._signer.to_public_vec(),
801            second._signer.to_public_vec(),
802        ];
803        let commit = role_commit(&mut admin, keys);
804        accept(&mut second, ManagementAction::Promote(id), &commit);
805        accept(&mut third, ManagementAction::Promote(id), &commit);
806        admin.group.merge_pending_commit(&admin.provider).unwrap();
807        (admin, second, third)
808    }
809    #[test]
810    fn administrator_removal_excludes_keys_and_old_invites() {
811        let (mut admin, mut removed, mut survivor) = two_admins();
812        let removed_id = removed.member().unwrap().id();
813        let (invite, checkpoint) = removed.issue_invitation().unwrap();
814        let pending =
815            PendingJoin::from_invitation(&invite, &checkpoint, [4; 32], "Late arrival").unwrap();
816        let ext = extensions(&admin, vec![admin._signer.to_public_vec()]);
817        let index = admin
818            .group
819            .members()
820            .find(|m| m.signature_key == removed._signer.public())
821            .unwrap()
822            .index;
823        let commit = admin
824            .group
825            .commit_builder()
826            .propose_removals([index])
827            .propose_group_context_extensions(ext)
828            .unwrap()
829            .load_psks(admin.provider.storage())
830            .unwrap()
831            .build(
832                admin.provider.rand(),
833                admin.provider.crypto(),
834                &admin._signer,
835                |_| true,
836            )
837            .unwrap()
838            .stage_commit(&admin.provider)
839            .unwrap()
840            .into_contents()
841            .0
842            .to_bytes()
843            .unwrap();
844        accept(&mut survivor, ManagementAction::Remove(removed_id), &commit);
845        admin.group.merge_pending_commit(&admin.provider).unwrap();
846        assert_eq!(survivor.member_count(), 2);
847        assert!(
848            !survivor
849                .member_endpoints()
850                .unwrap()
851                .contains(&removed.endpoint())
852        );
853        let fresh = admin
854            .protect_object(b"test", b"current members only")
855            .unwrap();
856        assert_eq!(
857            survivor
858                .unprotect_object(b"test", &fresh)
859                .unwrap()
860                .message
861                .payload,
862            b"current members only"
863        );
864        assert!(removed.unprotect_object(b"test", &fresh).is_err());
865        let stale = removed
866            .protect_object(b"test", b"old admin publication")
867            .unwrap();
868        assert!(survivor.unprotect_object(b"test", &stale).is_err());
869        assert_eq!(
870            admin
871                .prepare_admission([4; 32], pending.admission_request().unwrap())
872                .err(),
873            Some("invitation issuer is no longer an administrator")
874        );
875    }
876    #[test]
877    fn competing_admin_actions_do_not_silently_overwrite_accepted_state() {
878        let (mut admin, mut second, mut observer) = two_admins();
879        let admin_id = admin.member().unwrap().id();
880        let second_id = second.member().unwrap().id();
881        let first_keys = vec![admin._signer.to_public_vec()];
882        let other_keys = vec![second._signer.to_public_vec()];
883        let first = role_commit(&mut admin, first_keys);
884        let other = role_commit(&mut second, other_keys);
885        observer
886            .verify_management(ManagementAction::Demote(second_id), &first)
887            .unwrap();
888        observer
889            .verify_management(ManagementAction::Demote(admin_id), &other)
890            .unwrap();
891        accept(&mut observer, ManagementAction::Demote(second_id), &first);
892        let epoch = observer.epoch();
893        assert!(
894            observer
895                .verify_management(ManagementAction::Demote(admin_id), &other)
896                .is_err()
897        );
898        assert_eq!(observer.epoch(), epoch);
899        // Explicit rejection is evidence of no overwrite, not branch convergence.
900    }
901    #[test]
902    fn an_exact_action_does_not_authorize_bulk_role_or_policy_changes() {
903        let (mut admin, second, third) = trio();
904        let id = second.member().unwrap().id();
905        let keys = vec![
906            admin._signer.to_public_vec(),
907            second._signer.to_public_vec(),
908            third._signer.to_public_vec(),
909        ];
910        let bulk = role_commit(&mut admin, keys);
911        assert_eq!(
912            second.verify_management(ManagementAction::Promote(id), &bulk),
913            Err("management authority change does not match intent")
914        );
915        admin
916            .group
917            .clear_pending_commit(admin.provider.storage())
918            .unwrap();
919        let keys = vec![
920            admin._signer.to_public_vec(),
921            second._signer.to_public_vec(),
922        ];
923        let ext = Extensions::from_vec(
924            extensions(&admin, keys)
925                .iter()
926                .map(|e| {
927                    if e.extension_type() == ExtensionType::RequiredCapabilities {
928                        Extension::RequiredCapabilities(RequiredCapabilitiesExtension::new(
929                            &[ExtensionType::Unknown(AUTHORITY)],
930                            &[],
931                            &[CredentialType::Basic],
932                        ))
933                    } else {
934                        e.clone()
935                    }
936                })
937                .collect(),
938        )
939        .unwrap();
940        let changed = admin
941            .group
942            .update_group_context_extensions(&admin.provider, ext, &admin._signer)
943            .unwrap()
944            .0
945            .to_bytes()
946            .unwrap();
947        assert_eq!(
948            second.verify_management(ManagementAction::Promote(id), &changed),
949            Err("management cannot change unrelated group policy")
950        );
951    }
952    #[test]
953    fn staged_role_change_restores_and_old_invitation_crosses_mixed_history() {
954        let admin = Workspace::create([1; 32], "Coordinator").unwrap();
955        let (old_invitation, old_checkpoint) = admin.issue_invitation().unwrap();
956        let (mut admin, helper) = {
957            let (_, helper, prepared) = add(admin, 2);
958            (prepared.workspace, helper)
959        };
960        let key = StorageKey::derive(&[7; 32]).unwrap();
961        let helper_id = helper.member().unwrap().id();
962        let before = helper.epoch();
963        let action = ManagementAction::Promote(helper_id);
964        assert!(helper.prepare_management(action).is_err());
965        let prepared = admin.prepare_management(action).unwrap();
966        assert_eq!(admin.epoch(), before);
967        let PreparedManagementUpdate::Active(promoted) = helper
968            .prepare_management_update(action, &prepared.commit)
969            .unwrap()
970        else {
971            panic!("promotion removed member")
972        };
973        assert_eq!(helper.epoch(), before);
974        assert!(helper.issue_invitation().is_err());
975        assert_eq!(
976            &promoted
977                .join_history
978                .as_ref()
979                .unwrap()
980                .inline(promoted.id())
981                .unwrap()[..5],
982            b"DFJH\x02"
983        );
984        let snapshot = promoted.seal(&key).unwrap();
985        let promoted = Workspace::restore(&key, [2; 32], helper.id(), &snapshot).unwrap();
986        let mut records = promoted.export_records().unwrap();
987        let promoted = Workspace::restore_records([2; 32], helper.id(), &records).unwrap();
988        let history_key = records
989            .keys()
990            .find(|name| name.starts_with(b"security/history/step/"))
991            .unwrap()
992            .clone();
993        let bytes = records.get_mut(&history_key).unwrap();
994        assert_eq!(bytes[0], 0); // Admission authorization record.
995        bytes[33] ^= 1; // Administrator grant signature; publicly verifiable.
996        assert!(Workspace::restore_records([2; 32], helper.id(), &records).is_err());
997        assert!(promoted.issue_invitation().is_ok());
998        admin = prepared.workspace;
999        let saved_admin = admin.seal(&key).unwrap();
1000        admin = Workspace::restore(&key, [1; 32], admin.id(), &saved_admin).unwrap();
1001        let late =
1002            PendingJoin::from_invitation(&old_invitation, &old_checkpoint, [3; 32], "Late member")
1003                .unwrap();
1004        let request = late.admission_request().unwrap();
1005        for owner in [&admin, &promoted] {
1006            let steps = owner
1007                .membership_history([3; 32], request, &old_checkpoint)
1008                .unwrap();
1009            assert_eq!(steps.len(), 2);
1010            let mut proof = late.join_proof().unwrap();
1011            for (auth, commit) in steps {
1012                proof.apply_transition(&auth, &commit).unwrap();
1013            }
1014            assert!(proof.matches_workspace(owner).unwrap());
1015            assert_eq!(
1016                owner
1017                    .admission_history([3; 32], request, &old_checkpoint)
1018                    .err(),
1019                Some("membership history requires management support")
1020            );
1021        }
1022        drop(admin);
1023        drop(helper);
1024        let admitted = promoted.prepare_admission([3; 32], request).unwrap();
1025        let steps = admitted
1026            .workspace
1027            .membership_history([3; 32], request, &old_checkpoint)
1028            .unwrap();
1029        let mut proof = late.join_proof().unwrap();
1030        for (auth, commit) in &steps {
1031            proof.apply_transition(auth, commit).unwrap();
1032        }
1033        let joined = late.prepare_workspace(&proof, &admitted.welcome).unwrap();
1034        let restored =
1035            Workspace::restore(&key, [3; 32], joined.id(), &joined.seal(&key).unwrap()).unwrap();
1036        assert_eq!(restored.member_count(), 3);
1037        assert_eq!(restored.epoch(), 3);
1038        let encoded = proof.history();
1039        assert!(
1040            JoinProof::from_history(joined.id(), old_invitation.checkpoint_digest(), encoded)
1041                .unwrap()
1042                .matches_workspace(&restored)
1043                .unwrap()
1044        );
1045        // Wrong tags, intent, truncation and replay must not advance accepted proof.
1046        let prefix = 41 + u32::from_be_bytes(encoded[37..41].try_into().unwrap()) as usize;
1047        let mut bad = encoded.to_vec();
1048        bad[prefix] = 99;
1049        assert!(
1050            JoinProof::from_history(joined.id(), old_invitation.checkpoint_digest(), &bad).is_err()
1051        );
1052        for length in [4, 40, prefix + 1, encoded.len() - 1] {
1053            assert!(
1054                JoinProof::from_history(
1055                    joined.id(),
1056                    old_invitation.checkpoint_digest(),
1057                    &encoded[..length]
1058                )
1059                .is_err()
1060            );
1061        }
1062        let mut wrong = late.join_proof().unwrap();
1063        wrong.apply_transition(&steps[0].0, &steps[0].1).unwrap();
1064        let epoch = wrong.epoch();
1065        assert!(
1066            wrong
1067                .apply_management(ManagementAction::Demote(helper_id), &steps[1].1)
1068                .is_err()
1069        );
1070        assert_eq!(wrong.epoch(), epoch);
1071        wrong.apply_transition(&steps[1].0, &steps[1].1).unwrap();
1072        assert!(wrong.apply_transition(&steps[1].0, &steps[1].1).is_err());
1073    }
1074    #[test]
1075    fn staged_removal_restores_survivor_without_reopening_removed_owner() {
1076        let (admin, mut removed, survivor) = trio();
1077        let action = ManagementAction::Remove(removed.member().unwrap().id());
1078        let prepared = admin.prepare_management(action).unwrap();
1079        let PreparedManagementUpdate::Active(updated) = survivor
1080            .prepare_management_update(action, &prepared.commit)
1081            .unwrap()
1082        else {
1083            panic!("survivor removed")
1084        };
1085        assert_eq!(admin.epoch(), 2);
1086        assert_eq!(survivor.epoch(), 2);
1087        let PreparedManagementUpdate::Removed(record) = removed
1088            .prepare_management_update(action, &prepared.commit)
1089            .unwrap()
1090        else {
1091            panic!("removed recipient returned active state")
1092        };
1093        assert_eq!(record.epoch(), 3);
1094        let key = StorageKey::derive(&[9; 32]).unwrap();
1095        let sealed_removal = record.seal(&key).unwrap();
1096        let restored_removal = crate::RemovedMembership::restore(
1097            &key,
1098            removed.endpoint(),
1099            removed.id(),
1100            &sealed_removal,
1101        )
1102        .unwrap();
1103        assert_eq!(record, restored_removal);
1104        assert!(
1105            Workspace::restore(&key, removed.endpoint(), removed.id(), &sealed_removal).is_err()
1106        );
1107        assert_eq!(removed.epoch(), 2);
1108        let key = StorageKey::derive(&[9; 32]).unwrap();
1109        let restored = Workspace::restore(
1110            &key,
1111            survivor.endpoint(),
1112            survivor.id(),
1113            &updated.seal(&key).unwrap(),
1114        )
1115        .unwrap();
1116        assert_eq!(restored.member_count(), 2);
1117        assert_eq!(restored.epoch(), 3);
1118        let mut sender = prepared.workspace;
1119        let payload = sender
1120            .protect_object(b"removal", b"surviving members")
1121            .unwrap();
1122        assert_eq!(
1123            restored
1124                .unprotect_object(b"removal", &payload)
1125                .unwrap()
1126                .message
1127                .payload,
1128            b"surviving members"
1129        );
1130        assert!(removed.unprotect_object(b"removal", &payload).is_err());
1131        let stale = removed.protect_object(b"removal", b"old member").unwrap();
1132        assert!(restored.unprotect_object(b"removal", &stale).is_err());
1133    }
1134    #[test]
1135    fn removed_record_is_context_bound_and_cannot_restore_active_keys() {
1136        use crate::RemovedMembership;
1137        let (admin, removed, _) = trio();
1138        let key = StorageKey::derive(&[5; 32]).unwrap();
1139        let action = ManagementAction::Remove(removed.member().unwrap().id());
1140        let prepared = admin.prepare_management(action).unwrap();
1141        let mut bad_commit = prepared.commit.clone();
1142        *bad_commit.last_mut().unwrap() ^= 1;
1143        assert!(
1144            removed
1145                .prepare_management_update(action, &bad_commit)
1146                .is_err()
1147        );
1148        assert!(
1149            removed
1150                .prepare_management_update(
1151                    ManagementAction::Remove(admin.member().unwrap().id()),
1152                    &prepared.commit
1153                )
1154                .is_err()
1155        );
1156        let PreparedManagementUpdate::Removed(record) = removed
1157            .prepare_management_update(action, &prepared.commit)
1158            .unwrap()
1159        else {
1160            panic!("removed recipient returned keys")
1161        };
1162        let workspace = removed.id();
1163        let endpoint = removed.endpoint();
1164        let active = removed.seal(&key).unwrap();
1165        assert_eq!(record.member(), removed.member().unwrap());
1166        assert_eq!(record.workspace_id(), workspace);
1167        assert_eq!(record.endpoint(), endpoint);
1168        use sha2::Digest;
1169        assert_eq!(
1170            record.commit_digest().as_slice(),
1171            sha2::Sha256::digest(&prepared.commit).as_slice()
1172        );
1173        drop(removed);
1174        let sealed = record.seal(&key).unwrap();
1175        assert!(sealed.len() <= crate::MAX_SEALED_REMOVAL);
1176        assert_ne!(sealed, record.seal(&key).unwrap());
1177        assert_eq!(
1178            RemovedMembership::restore(&key, endpoint, workspace, &sealed).unwrap(),
1179            record
1180        );
1181        assert!(Workspace::restore(&key, endpoint, workspace, &sealed).is_err());
1182        assert!(RemovedMembership::restore(&key, endpoint, workspace, &active).is_err());
1183        assert!(
1184            RemovedMembership::restore(
1185                &StorageKey::derive(&[6; 32]).unwrap(),
1186                endpoint,
1187                workspace,
1188                &sealed
1189            )
1190            .is_err()
1191        );
1192        assert!(RemovedMembership::restore(&key, [9; 32], workspace, &sealed).is_err());
1193        assert!(RemovedMembership::restore(&key, endpoint, [9; 32], &sealed).is_err());
1194        for length in 0..sealed.len() {
1195            assert!(
1196                RemovedMembership::restore(&key, endpoint, workspace, &sealed[..length]).is_err()
1197            );
1198        }
1199        for offset in [0, 4, 5, 37, 49, sealed.len() - 1] {
1200            let mut bad = sealed.clone();
1201            bad[offset] ^= 1;
1202            assert!(RemovedMembership::restore(&key, endpoint, workspace, &bad).is_err());
1203        }
1204        let plain = key
1205            .unprotect(b"DFRM\x01", workspace, endpoint, &sealed)
1206            .unwrap();
1207        for malformed in [
1208            {
1209                let mut v = plain.to_vec();
1210                v[..8].fill(0);
1211                v
1212            },
1213            {
1214                let mut v = plain.to_vec();
1215                v[8..40].fill(0);
1216                v
1217            },
1218            {
1219                let mut v = plain.to_vec();
1220                v[40..44].copy_from_slice(&u32::MAX.to_be_bytes());
1221                v
1222            },
1223            {
1224                let mut v = plain.to_vec();
1225                v.push(0);
1226                v
1227            },
1228        ] {
1229            let bad = key
1230                .protect(
1231                    &admin.provider,
1232                    b"DFRM\x01",
1233                    workspace,
1234                    endpoint,
1235                    &malformed,
1236                )
1237                .unwrap();
1238            assert!(RemovedMembership::restore(&key, endpoint, workspace, &bad).is_err());
1239        }
1240    }
1241}
1242
1243#[test]
1244fn provisional_copy_exceeds_legacy_size_and_isolates_sender_state() {
1245    let owner = Workspace::create([1; 32], "Publisher").unwrap();
1246    // An opaque provider record crosses the old serialization size boundary.
1247    owner.provider.storage().values.write().unwrap().insert(
1248        b"test/large-native-record".to_vec(),
1249        vec![7; storage::MAX_PLAIN],
1250    );
1251    let key = super::StorageKey::derive(&[2; 32]).unwrap();
1252    assert!(owner.seal(&key).is_err());
1253    let before = owner.export_records().unwrap();
1254    let mut candidate = owner.provisional_copy().unwrap();
1255    assert_eq!(candidate.export_records().unwrap(), before);
1256    candidate
1257        .protect_object(b"stream", b"provisional output")
1258        .unwrap();
1259    assert_eq!(candidate.object_counter().unwrap(), 1);
1260    assert_eq!(owner.object_counter().unwrap(), 0);
1261    assert_eq!(owner.export_records().unwrap(), before);
1262    // Dropping a rejected candidate must leave the next attempt unchanged.
1263    drop(candidate);
1264    assert_eq!(
1265        owner.provisional_copy().unwrap().export_records().unwrap(),
1266        before
1267    );
1268}