Skip to main content

arachne_security/
invitation_controls.rs

1//! Invitation controls in the existing authority extension. A disabled grant
2//! cannot authorize a later Add on this branch. Wall-clock expiry is checked
3//! when handling a new request, independently of replaying accepted history.
4use super::{AUTHORITY, ManagementAction, PreparedManagement, Workspace, bootstrap};
5use openmls::prelude::*;
6use openmls_traits::OpenMlsProvider;
7
8pub const INVITATION_DISABLED: &str =
9    "This invitation has been disabled. Ask an administrator for a new link.";
10pub const INVITATION_EXPIRED: &str =
11    "This invitation has expired. Ask an administrator for a new link.";
12pub const INVITATION_APPROVAL_REQUIRED: &str =
13    "This personal invitation needs administrator approval for your join request.";
14pub const INVITATION_AUTOMATIC_APPROVAL_REQUIRED: &str =
15    "This personal invitation is waiting for an administrator to bind its first join request.";
16const AUTOMATIC_APPROVAL: [u8; 32] = [0xff; 32];
17const REQUEST_ACCESS: [u8; 32] = [0xfe; 32];
18
19#[derive(Clone, Debug, PartialEq, Eq)]
20pub struct InvitationControl {
21    pub key: [u8; 32],
22    pub expires_at: u64,
23    pub enabled: bool,
24    pub personal: bool,
25    pub approved_package: [u8; 32],
26}
27
28impl InvitationControl {
29    pub fn automatic(&self) -> bool {
30        self.personal && self.approved_package == AUTOMATIC_APPROVAL
31    }
32
33    pub fn approved(&self) -> bool {
34        self.personal
35            && self.approved_package != [0; 32]
36            && !self.automatic()
37            && !self.request_access()
38    }
39
40    pub fn request_access(&self) -> bool {
41        self.personal && self.approved_package == REQUEST_ACCESS
42    }
43
44    pub fn is_request_decision(&self, controls: &[Self]) -> bool {
45        controls.iter().any(|parent| {
46            parent.request_access() && self.key == decision_key(parent.key, self.approved_package)
47        })
48    }
49}
50
51// Domain separation keeps decisions bound to both the invitation and exact request.
52fn decision_key(invitation: [u8; 32], package: [u8; 32]) -> [u8; 32] {
53    use sha2::{Digest, Sha256};
54    let mut hash = Sha256::new();
55    hash.update(b"data-fabric/invitation-request/v1\0");
56    hash.update(invitation);
57    hash.update(package);
58    hash.finalize().into()
59}
60
61fn decide(
62    controls: &mut Vec<InvitationControl>,
63    parent: &InvitationControl,
64    package: [u8; 32],
65    approved: bool,
66) -> Result<(), &'static str> {
67    if !parent.enabled || [[0; 32], AUTOMATIC_APPROVAL, REQUEST_ACCESS].contains(&package) {
68        return Err("invalid or disabled invitation request");
69    }
70    let key = decision_key(parent.key, package);
71    if controls.iter().any(|c| c.key == key) {
72        return Err("join request already decided");
73    }
74    controls.push(InvitationControl {
75        key,
76        expires_at: parent.expires_at,
77        enabled: approved,
78        personal: true,
79        approved_package: package,
80    });
81    Ok(())
82}
83
84pub(super) fn decode(bytes: &[u8]) -> Result<(bool, Vec<InvitationControl>), &'static str> {
85    if bytes.len() < 3 || bytes.len() > 16 * 1024 || bytes[0] > 1 {
86        return Err("invalid invitation controls");
87    }
88    let count = u16::from_be_bytes(bytes[1..3].try_into().unwrap()) as usize;
89    if bytes.len() != 3 + count * 74 {
90        return Err("invalid invitation control length");
91    }
92    let mut controls = Vec::with_capacity(count);
93    for row in bytes[3..].as_chunks::<74>().0 {
94        let key: [u8; 32] = row[..32].try_into().unwrap();
95        if row[40] > 1
96            || row[41] > 1
97            || key == [0; 32]
98            || controls.iter().any(|c: &InvitationControl| c.key == key)
99        {
100            return Err("invalid invitation control");
101        }
102        controls.push(InvitationControl {
103            key,
104            expires_at: u64::from_be_bytes(row[32..40].try_into().unwrap()),
105            enabled: row[40] == 1,
106            personal: row[41] == 1,
107            approved_package: row[42..74].try_into().unwrap(),
108        });
109    }
110    Ok((bytes[0] == 1, controls))
111}
112
113pub(super) fn policy_bytes(extensions: &Extensions<GroupContext>) -> Result<Vec<u8>, &'static str> {
114    let keys = bootstrap::authority(extensions)?;
115    let bytes = &extensions.unknown(AUTHORITY).ok_or("missing authority")?.0;
116    Ok(if bytes[0] == 1 {
117        vec![1, 0, 0]
118    } else {
119        bytes[2 + keys.len() * 32..].to_vec()
120    })
121}
122
123pub(super) fn replace_admins(
124    extensions: &Extensions<GroupContext>,
125    admins: &[Vec<u8>],
126) -> Result<Vec<u8>, &'static str> {
127    let old = &extensions.unknown(AUTHORITY).ok_or("missing authority")?.0;
128    let mut bytes = vec![old[0], admins.len() as u8];
129    bytes.extend(admins.iter().flatten());
130    if old[0] == 2 {
131        bytes.extend(policy_bytes(extensions)?);
132    }
133    Ok(bytes)
134}
135
136pub(super) fn check(
137    extensions: &Extensions<GroupContext>,
138    key: [u8; 32],
139    now: Option<u64>,
140    package: &KeyPackage,
141) -> Result<(), &'static str> {
142    let (legacy, controls) = decode(&policy_bytes(extensions)?)?;
143    match controls.iter().find(|c| c.key == key) {
144        Some(c) if !c.enabled => Err(INVITATION_DISABLED),
145        Some(c) if c.expires_at != 0 && now.is_some_and(|n| n >= c.expires_at) => {
146            Err(INVITATION_EXPIRED)
147        }
148        Some(c) if c.automatic() => Err(INVITATION_AUTOMATIC_APPROVAL_REQUIRED),
149        Some(c) if c.request_access() => {
150            let package = package_digest(package)?;
151            match controls
152                .iter()
153                .find(|decision| decision.key == decision_key(c.key, package))
154            {
155                Some(decision) if !decision.enabled => Err(INVITATION_DISABLED),
156                Some(decision) if decision.personal && decision.approved_package == package => {
157                    Ok(())
158                }
159                _ => Err(INVITATION_APPROVAL_REQUIRED),
160            }
161        }
162        Some(c) if c.personal && !c.approved() => Err(INVITATION_APPROVAL_REQUIRED),
163        Some(c) if c.personal && c.approved_package != package_digest(package)? => {
164            Err(INVITATION_APPROVAL_REQUIRED)
165        }
166        Some(_) => Ok(()),
167        None if legacy => Ok(()),
168        None => Err(INVITATION_DISABLED),
169    }
170}
171
172pub(super) fn package_digest(package: &KeyPackage) -> Result<[u8; 32], &'static str> {
173    use openmls::prelude::tls_codec::Serialize;
174    use sha2::{Digest, Sha256};
175    Ok(Sha256::digest(
176        package
177            .tls_serialize_detached()
178            .map_err(|_| "join request encoding failed")?,
179    )
180    .into())
181}
182
183pub(super) fn now() -> Result<u64, &'static str> {
184    std::time::SystemTime::now()
185        .duration_since(std::time::UNIX_EPOCH)
186        .map(|v| v.as_secs())
187        .map_err(|_| "device clock is invalid")
188}
189
190fn changed(
191    extensions: &Extensions<GroupContext>,
192    action: ManagementAction,
193) -> Result<Extensions<GroupContext>, &'static str> {
194    let (mut legacy, mut controls) = decode(&policy_bytes(extensions)?)?;
195    match action {
196        ManagementAction::CreateInvitation(key, expires_at, personal) => {
197            if key == [0; 32] || controls.iter().any(|c| c.key == key) {
198                return Err("invitation already registered or invalid");
199            }
200            controls.push(InvitationControl {
201                key,
202                expires_at,
203                enabled: true,
204                personal,
205                approved_package: [0; 32],
206            });
207        }
208        ManagementAction::CreateAutomaticInvitation(key, expires_at)
209        | ManagementAction::CreateRequestInvitation(key, expires_at) => {
210            if key == [0; 32] || controls.iter().any(|c| c.key == key) {
211                return Err("invitation already registered or invalid");
212            }
213            controls.push(InvitationControl {
214                key,
215                expires_at,
216                enabled: true,
217                personal: true,
218                approved_package: if matches!(action, ManagementAction::CreateRequestInvitation(..))
219                {
220                    REQUEST_ACCESS
221                } else {
222                    AUTOMATIC_APPROVAL
223                },
224            });
225        }
226        ManagementAction::ApproveInvitation(key, package) => {
227            let parent = controls
228                .iter()
229                .find(|c| c.key == key)
230                .cloned()
231                .ok_or("unknown invitation")?;
232            if parent.request_access() {
233                decide(&mut controls, &parent, package, true)?;
234            } else {
235                let control = controls
236                    .iter_mut()
237                    .find(|c| c.key == key)
238                    .ok_or("unknown personal invitation")?;
239                if !control.personal
240                    || !control.enabled
241                    || (control.approved_package != [0; 32] && !control.automatic())
242                    || package == [0; 32]
243                    || package == AUTOMATIC_APPROVAL
244                    || package == REQUEST_ACCESS
245                {
246                    return Err("personal invitation is already approved or disabled");
247                }
248                control.approved_package = package;
249            }
250        }
251        ManagementAction::DeclineInvitationRequest(key, package) => {
252            let parent = controls
253                .iter()
254                .find(|c| c.key == key)
255                .cloned()
256                .ok_or("unknown invitation")?;
257            if !parent.request_access() {
258                return Err("expected a request-access invitation");
259            }
260            decide(&mut controls, &parent, package, false)?;
261        }
262        ManagementAction::DisableInvitation(key) => {
263            if key == [0; 32] {
264                if !legacy {
265                    return Err("older invitations already disabled");
266                }
267                legacy = false;
268            } else {
269                let control = controls
270                    .iter_mut()
271                    .find(|c| c.key == key)
272                    .ok_or("unknown invitation")?;
273                if !control.enabled {
274                    return Err("invitation already disabled");
275                }
276                control.enabled = false;
277            }
278        }
279        _ => return Err("expected invitation control action"),
280    }
281    let admins = bootstrap::authority(extensions)?;
282    let mut bytes = vec![2, admins.len() as u8];
283    bytes.extend(admins.into_iter().flatten());
284    let mut policy = vec![u8::from(legacy)];
285    policy.extend((controls.len() as u16).to_be_bytes());
286    for c in controls {
287        policy.extend(c.key);
288        policy.extend(c.expires_at.to_be_bytes());
289        policy.push(u8::from(c.enabled));
290        policy.push(u8::from(c.personal));
291        policy.extend(c.approved_package);
292    }
293    decode(&policy)?;
294    bytes.extend(policy);
295    Extensions::from_vec(
296        extensions
297            .iter()
298            .map(|e| {
299                if e.extension_type() == ExtensionType::Unknown(AUTHORITY) {
300                    Extension::Unknown(AUTHORITY, UnknownExtension(bytes.clone()))
301                } else {
302                    e.clone()
303                }
304            })
305            .collect(),
306    )
307    .map_err(|_| "invalid invitation policy")
308}
309
310impl Workspace {
311    pub fn invitation_controls(&self) -> Result<(bool, Vec<InvitationControl>), &'static str> {
312        decode(&policy_bytes(self.group.extensions())?)
313    }
314}
315
316pub(super) fn prepare(
317    owner: &Workspace,
318    action: ManagementAction,
319) -> Result<PreparedManagement, &'static str> {
320    let extensions = changed(owner.group.extensions(), action)?;
321    let mut candidate = owner.provisional_copy()?;
322    let commit = candidate
323        .group
324        .commit_builder()
325        .propose_group_context_extensions(extensions)
326        .map_err(|_| "invitation control proposal failed")?
327        .load_psks(candidate.provider.storage())
328        .map_err(|_| "invitation control state failed")?
329        .build(
330            candidate.provider.rand(),
331            candidate.provider.crypto(),
332            &candidate._signer,
333            |_| true,
334        )
335        .map_err(|_| "invitation control preparation failed")?
336        .stage_commit(&candidate.provider)
337        .map_err(|_| "invitation control staging failed")?
338        .into_contents()
339        .0
340        .to_bytes()
341        .map_err(|_| "invitation control encoding failed")?;
342    let mut proof = super::MembershipVerifier::from_workspace(owner)?;
343    proof.apply_transition(&super::MembershipAuthorization::Management(action), &commit)?;
344    candidate
345        .group
346        .merge_pending_commit(&candidate.provider)
347        .map_err(|_| "invitation control merge failed")?;
348    candidate.join_history =
349        Some(owner.append_history(super::MembershipAuthorization::Management(action), &commit)?);
350    candidate.prune_invitation_checkpoints()?;
351    if !proof.matches_workspace(&candidate)? {
352        return Err("invitation control branch mismatch");
353    }
354    Ok(PreparedManagement {
355        workspace: candidate,
356        action,
357        commit,
358    })
359}
360
361pub(super) fn verify(
362    group: &PublicGroup,
363    sender: &Sender,
364    actor: &Member,
365    staged: &StagedCommit,
366    action: ManagementAction,
367) -> Result<(), &'static str> {
368    if staged.group_context().extensions() != &changed(group.group_context().extensions(), action)?
369    {
370        return Err("invitation action changed unrelated policy");
371    }
372    if let Some(leaf) = staged.update_path_leaf_node()
373        && (leaf.credential() != &actor.credential
374            || leaf.signature_key().as_slice() != actor.signature_key)
375    {
376        return Err("invitation action replaced actor identity");
377    }
378    if staged.queued_proposals().count() != 1
379        || !staged.queued_proposals().all(|p| {
380            p.sender() == sender
381                && p.proposal_or_ref_type() == ProposalOrRefType::Proposal
382                && matches!(p.proposal(), Proposal::GroupContextExtensions(_))
383        })
384    {
385        return Err("invitation action requires exactly its inline policy proposal");
386    }
387    Ok(())
388}