1use 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
51fn 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}