Skip to main content

hyprstream_rpc/crypto/
group_key.rs

1//! Controller-managed hybrid group epochs for record-backed fan-out.
2//!
3//! Epoch secrets are fresh random values and are sealed independently to every
4//! admitted member's accepted-state-bound HyKEM recipient with COSE_Encrypt0.
5//! Relays receive only ordinary encrypted MOQT object bytes; epoch grants are
6//! control-plane objects and MUST NOT be published on a relay track.
7//!
8//! Membership changes use an explicit prepare/commit transaction. Preparing a
9//! change creates and seals the next epoch but does not expose it as current.
10//! Committing swaps membership version, epoch, key, and member set atomically.
11//! A crash before commit therefore leaves the prior committed epoch intact.
12
13use std::collections::HashMap;
14use std::sync::Arc;
15use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
16
17use parking_lot::RwLock;
18use zeroize::Zeroizing;
19
20use crate::crypto::cose_encrypt;
21use crate::crypto::hybrid_kem::{RecipientKeypair, RecipientPublic};
22
23pub const MAX_KEY_LIFETIME: Duration = Duration::from_secs(86_400);
24pub const DEFAULT_ROTATION_INTERVAL: Duration = Duration::from_secs(3_600);
25pub const GRACE_PERIOD: Duration = Duration::from_secs(120);
26
27#[derive(Clone, Debug)]
28pub enum RekeyPolicy {
29    Scheduled {
30        interval: Duration,
31    },
32    Immediate,
33    Jittered {
34        interval: Duration,
35        jitter: Duration,
36    },
37}
38
39impl Default for RekeyPolicy {
40    fn default() -> Self {
41        Self::Scheduled {
42            interval: DEFAULT_ROTATION_INTERVAL,
43        }
44    }
45}
46
47impl RekeyPolicy {
48    pub fn validate(&self) -> Result<(), String> {
49        match self {
50            Self::Scheduled { interval } | Self::Jittered { interval, .. }
51                if *interval > MAX_KEY_LIFETIME =>
52            {
53                Err(format!(
54                    "interval {interval:?} exceeds MAX_KEY_LIFETIME ({MAX_KEY_LIFETIME:?})"
55                ))
56            }
57            _ => Ok(()),
58        }
59    }
60}
61
62/// Encrypted event payload. `publisher_pubkey` is an anchored Ed25519 key id;
63/// `signature` is a mandatory hybrid COSE composite (Ed25519 + ML-DSA-65).
64#[derive(Debug, Clone)]
65pub struct EncryptedEvent {
66    pub topic: String,
67    pub tag: Vec<u8>,
68    pub ciphertext: Vec<u8>,
69    pub nonce: [u8; 12],
70    pub key_commitment: [u8; 16],
71    pub lk_tag: Vec<u8>,
72    pub signature: Vec<u8>,
73    pub publisher_pubkey: [u8; 32],
74    pub timestamp: i64,
75    /// CSPRNG lifecycle identifier that scopes one publisher/track epoch key.
76    pub session_id: [u8; 16],
77    /// Controller-committed membership version and epoch are sender-authenticated.
78    pub membership_version: u64,
79    pub epoch: u64,
80    /// Monotonic per-sender/track sequence within the session-scoped key.
81    pub sequence: u64,
82}
83
84#[derive(Debug, Clone)]
85pub struct WrappedKeyEntry {
86    /// Random recipient-local routing tag; regenerated every epoch.
87    pub routing_tag: [u8; 16],
88    /// Accepted `#mesh-kem` recipient key id.
89    pub recipient_key_id: Vec<u8>,
90    /// Canonical COSE_Encrypt0 carrying the epoch secret and HyKEM shares.
91    pub wrapped_blob: Vec<u8>,
92}
93
94#[derive(Debug, Clone)]
95pub struct RotationResult {
96    pub wrapped_keys: Vec<WrappedKeyEntry>,
97    pub effective_at_millis: i64,
98    pub membership_version: u64,
99    pub epoch: u64,
100}
101
102#[derive(Clone, Debug, Eq, PartialEq, Hash)]
103pub struct GroupRef {
104    pub group_uri: String,
105    pub keyset_id: String,
106}
107
108impl GroupRef {
109    pub fn new(group_uri: impl Into<String>, keyset_id: impl Into<String>) -> Self {
110        Self {
111            group_uri: group_uri.into(),
112            keyset_id: keyset_id.into(),
113        }
114    }
115}
116
117/// State that identifies the controller and the accepted CID512/did:at9p view.
118#[derive(Clone, Debug, Eq, PartialEq)]
119pub struct ControllerBinding {
120    pub controller_did: String,
121    pub accepted_state: Vec<u8>,
122    /// Controller-authorized sender identity for this epoch profile.
123    pub sender_did: String,
124    pub sender_ed25519: [u8; 32],
125    pub sender_ml_dsa_65: Vec<u8>,
126    /// Canonical policy identifiers, authenticated into every member grant.
127    pub retention_policy: Vec<u8>,
128    pub opaque_routing_policy: Vec<u8>,
129    pub expires_at_millis: i64,
130}
131
132/// A member admission resolved from authenticated policy/record state.
133///
134/// `blinded_routing_key` is a fresh subscriber-generated Ristretto presentation.
135/// It retains the old construction's unlinkability property, but is only an
136/// authenticated opaque binding: it is never used to derive key material. Epoch
137/// confidentiality comes solely from the separate HyKEM recipient.
138#[derive(Clone, Debug)]
139pub struct GroupMembership {
140    pub group_uri: String,
141    pub subject_did: String,
142    pub accepted_state: Vec<u8>,
143    pub capability: Vec<u8>,
144    pub recipient_key_id: Vec<u8>,
145    pub recipient: RecipientPublic,
146    pub blinded_routing_key: [u8; 32],
147    pub expires_at_millis: i64,
148}
149
150impl GroupMembership {
151    fn validate(&self, group_uri: &str) -> Result<(), String> {
152        if self.group_uri != group_uri {
153            return Err("membership group does not match requested group".to_owned());
154        }
155        if self.subject_did.is_empty()
156            || self.accepted_state.is_empty()
157            || self.capability.is_empty()
158            || self.recipient_key_id.is_empty()
159        {
160            return Err("membership binding is incomplete".to_owned());
161        }
162        if self.blinded_routing_key == [0; 32] {
163            return Err("blinded routing key must not be all zero".to_owned());
164        }
165        self.recipient.validate().map_err(|e| e.to_string())?;
166        let expected = recipient_key_id(&self.recipient);
167        if self.recipient_key_id != expected {
168            return Err("recipient key id does not match accepted HyKEM key".to_owned());
169        }
170        Ok(())
171    }
172}
173
174/// The TCB membership gate. Implementations validate accepted state, capability,
175/// expiry and the current `#mesh-kem` recipient before returning a binding.
176pub trait MembershipResolver: Send + Sync {
177    fn resolve(&self, requested: &GroupMembership) -> Result<GroupMembership, String>;
178}
179
180pub struct DenyAllResolver;
181impl MembershipResolver for DenyAllResolver {
182    fn resolve(&self, _requested: &GroupMembership) -> Result<GroupMembership, String> {
183        Err("MembershipResolver not wired — fail-closed".to_owned())
184    }
185}
186
187/// Subscriber-side unlinkable presentation retained from the prior blinded-DH
188/// protocol. It is intentionally not a KEX key in the hybrid construction.
189pub struct BlindedMember {
190    pub blinded_pubkey: [u8; 32],
191    pub blinding: [u8; 32],
192}
193
194impl BlindedMember {
195    pub fn new(member_pubkey: &[u8; 32]) -> Result<Self, String> {
196        let pub_obj = crate::crypto::RistrettoPublic::from_bytes(member_pubkey)
197            .ok_or_else(|| "invalid Ristretto255 member public key".to_owned())?;
198        let (blinded, blinding) = crate::crypto::rerandomize_pubkey(&pub_obj);
199        Ok(Self {
200            blinded_pubkey: blinded.to_bytes(),
201            blinding,
202        })
203    }
204}
205
206#[derive(Clone, Debug)]
207pub enum MembershipChange {
208    Join(GroupMembership),
209    Leave {
210        subject_did: String,
211    },
212    Revoke {
213        subject_did: String,
214    },
215    Expire {
216        subject_did: String,
217    },
218    RotateRecipient(GroupMembership),
219    ControllerChange(ControllerBinding),
220    AcceptedStateAdvance {
221        accepted_state: Vec<u8>,
222        members: Vec<GroupMembership>,
223    },
224}
225
226#[derive(Clone, Debug)]
227pub struct EpochGrant {
228    pub group_uri: String,
229    pub controller_did: String,
230    pub keyset_id: String,
231    pub subject_did: String,
232    pub accepted_state: Vec<u8>,
233    pub sender_did: String,
234    pub sender_ed25519: [u8; 32],
235    pub sender_ml_dsa_65: Vec<u8>,
236    pub retention_policy: Vec<u8>,
237    pub opaque_routing_policy: Vec<u8>,
238    pub capability: Vec<u8>,
239    pub recipient_key_id: Vec<u8>,
240    pub blinded_routing_key: [u8; 32],
241    pub membership_version: u64,
242    pub epoch: u64,
243    pub expires_at_millis: i64,
244    pub sealed_epoch_secret: Vec<u8>,
245}
246
247#[derive(Clone, Debug)]
248pub struct PreparedEpoch {
249    pub group_uri: String,
250    pub keyset_id: String,
251    pub membership_version: u64,
252    pub epoch: u64,
253    pub grants: Vec<EpochGrant>,
254}
255
256struct EpochState {
257    keyset_id: String,
258    membership_version: u64,
259    epoch: u64,
260    key: Zeroizing<[u8; 32]>,
261    controller: ControllerBinding,
262    members: HashMap<String, GroupMembership>,
263    created_at: Instant,
264}
265
266struct PendingEpoch {
267    state: EpochState,
268    public: PreparedEpoch,
269}
270
271struct GroupState {
272    current: EpochState,
273    pending: Option<PendingEpoch>,
274}
275
276pub struct GroupKeyRegistry<R: MembershipResolver> {
277    groups: Arc<RwLock<HashMap<GroupRef, GroupState>>>,
278    rekey_policy: RekeyPolicy,
279    resolver: R,
280}
281
282impl<R: MembershipResolver> GroupKeyRegistry<R> {
283    pub fn new(rekey_policy: RekeyPolicy, resolver: R) -> Result<Self, String> {
284        rekey_policy.validate()?;
285        Ok(Self {
286            groups: Arc::new(RwLock::new(HashMap::new())),
287            rekey_policy,
288            resolver,
289        })
290    }
291
292    pub async fn register_group(
293        &self,
294        group: GroupRef,
295        controller: ControllerBinding,
296    ) -> Result<(), String> {
297        validate_controller(&controller)?;
298        let state = EpochState {
299            keyset_id: group.keyset_id.clone(),
300            membership_version: 0,
301            epoch: 0,
302            key: random_epoch_key(),
303            controller,
304            members: HashMap::new(),
305            created_at: Instant::now(),
306        };
307        let mut groups = self.groups.write();
308        if groups.contains_key(&group) {
309            return Err(format!("group {group:?} already registered"));
310        }
311        groups.insert(
312            group,
313            GroupState {
314                current: state,
315                pending: None,
316            },
317        );
318        Ok(())
319    }
320
321    /// Prepare the next epoch and seal it independently to every resulting
322    /// member. Current state remains visible until [`Self::commit_prepared`].
323    pub async fn prepare_change(
324        &self,
325        group: &GroupRef,
326        change: MembershipChange,
327        new_keyset_id: impl Into<String>,
328    ) -> Result<PreparedEpoch, String> {
329        let mut groups = self.groups.write();
330        let state = groups
331            .get_mut(group)
332            .ok_or_else(|| format!("group {group:?} not registered"))?;
333        if state.pending.is_some() {
334            return Err("a membership/epoch transaction is already pending".to_owned());
335        }
336
337        let mut controller = state.current.controller.clone();
338        let mut members = state.current.members.clone();
339        match change {
340            MembershipChange::Join(requested) | MembershipChange::RotateRecipient(requested) => {
341                let resolved = self.resolver.resolve(&requested)?;
342                resolved.validate(&group.group_uri)?;
343                if resolved.subject_did != requested.subject_did
344                    || resolved.accepted_state != controller.accepted_state
345                {
346                    return Err("resolver returned mismatched or stale membership".to_owned());
347                }
348                members.insert(resolved.subject_did.clone(), resolved);
349            }
350            MembershipChange::Leave { subject_did }
351            | MembershipChange::Revoke { subject_did }
352            | MembershipChange::Expire { subject_did } => {
353                if members.remove(&subject_did).is_none() {
354                    return Err("member is not in the committed group".to_owned());
355                }
356            }
357            MembershipChange::ControllerChange(next) => {
358                validate_controller(&next)?;
359                controller = next;
360                // Controller/accepted-state changes invalidate every old grant.
361                members.clear();
362            }
363            MembershipChange::AcceptedStateAdvance {
364                accepted_state,
365                members: requested_members,
366            } => {
367                if accepted_state.is_empty() || accepted_state == controller.accepted_state {
368                    return Err(
369                        "accepted-state advance must install a fresh non-empty state".to_owned(),
370                    );
371                }
372                controller.accepted_state = accepted_state;
373                members.clear();
374                for requested in requested_members {
375                    let resolved = self.resolver.resolve(&requested)?;
376                    resolved.validate(&group.group_uri)?;
377                    if resolved.subject_did != requested.subject_did
378                        || resolved.accepted_state != controller.accepted_state
379                    {
380                        return Err("member is not bound to the advanced accepted state".to_owned());
381                    }
382                    members.insert(resolved.subject_did.clone(), resolved);
383                }
384            }
385        }
386
387        let membership_version =
388            state
389                .current
390                .membership_version
391                .checked_add(1)
392                .ok_or_else(|| {
393                    "membership version is exhausted; create a new group generation".to_owned()
394                })?;
395        let epoch = state
396            .current
397            .epoch
398            .checked_add(1)
399            .ok_or_else(|| "epoch is exhausted; create a new group generation".to_owned())?;
400        let keyset_id = new_keyset_id.into();
401        if keyset_id.is_empty() || keyset_id == state.current.keyset_id {
402            return Err("new epoch requires a fresh keyset id".to_owned());
403        }
404        let key = random_epoch_key();
405        let grants = members
406            .values()
407            .map(|member| {
408                seal_epoch_grant(
409                    group,
410                    &keyset_id,
411                    &controller,
412                    member,
413                    membership_version,
414                    epoch,
415                    &key,
416                )
417            })
418            .collect::<Result<Vec<_>, _>>()?;
419        let public = PreparedEpoch {
420            group_uri: group.group_uri.clone(),
421            keyset_id: keyset_id.clone(),
422            membership_version,
423            epoch,
424            grants,
425        };
426        state.pending = Some(PendingEpoch {
427            state: EpochState {
428                keyset_id,
429                membership_version,
430                epoch,
431                key,
432                controller,
433                members,
434                created_at: Instant::now(),
435            },
436            public: public.clone(),
437        });
438        Ok(public)
439    }
440
441    /// Atomically make a prepared membership version and epoch visible.
442    pub async fn commit_prepared(
443        &self,
444        group: &GroupRef,
445        membership_version: u64,
446        epoch: u64,
447    ) -> Result<(), String> {
448        let mut groups = self.groups.write();
449        let state = groups
450            .get_mut(group)
451            .ok_or_else(|| format!("group {group:?} not registered"))?;
452        let pending = state
453            .pending
454            .as_ref()
455            .ok_or_else(|| "no pending epoch".to_owned())?;
456        if pending.public.membership_version != membership_version || pending.public.epoch != epoch
457        {
458            return Err("commit coordinates do not match the pending transaction".to_owned());
459        }
460        let pending = state
461            .pending
462            .take()
463            .ok_or_else(|| "no pending epoch".to_owned())?;
464        state.current = pending.state;
465        Ok(())
466    }
467
468    /// Discard an uncommitted transaction. The committed epoch is untouched.
469    pub async fn abort_prepared(
470        &self,
471        group: &GroupRef,
472        keyset_id: &str,
473        membership_version: u64,
474        epoch: u64,
475    ) -> Result<(), String> {
476        let mut groups = self.groups.write();
477        let state = groups
478            .get_mut(group)
479            .ok_or_else(|| format!("group {group:?} not registered"))?;
480        let pending = state
481            .pending
482            .as_ref()
483            .ok_or_else(|| "no pending epoch".to_owned())?;
484        if pending.public.keyset_id != keyset_id
485            || pending.public.membership_version != membership_version
486            || pending.public.epoch != epoch
487        {
488            return Err("abort coordinates do not match the pending transaction".to_owned());
489        }
490        state.pending = None;
491        Ok(())
492    }
493
494    pub async fn committed_coordinates(&self, group: &GroupRef) -> Option<(String, u64, u64)> {
495        let groups = self.groups.read();
496        groups.get(group).map(|state| {
497            (
498                state.current.keyset_id.clone(),
499                state.current.membership_version,
500                state.current.epoch,
501            )
502        })
503    }
504
505    pub async fn pending_epoch(&self, group: &GroupRef) -> Option<PreparedEpoch> {
506        self.groups
507            .read()
508            .get(group)
509            .and_then(|state| state.pending.as_ref().map(|pending| pending.public.clone()))
510    }
511
512    pub async fn k_group(&self, group: &GroupRef) -> Option<[u8; 32]> {
513        self.groups
514            .read()
515            .get(group)
516            .map(|state| *state.current.key)
517    }
518
519    pub async fn contains_member(&self, group: &GroupRef, subject_did: &str) -> bool {
520        self.groups
521            .read()
522            .get(group)
523            .is_some_and(|state| state.current.members.contains_key(subject_did))
524    }
525
526    pub async fn needs_rotation(&self, group: &GroupRef) -> bool {
527        let groups = self.groups.read();
528        let Some(state) = groups.get(group) else {
529            return false;
530        };
531        let age = state.current.created_at.elapsed();
532        match self.rekey_policy {
533            RekeyPolicy::Immediate => false,
534            RekeyPolicy::Scheduled { interval } => age >= interval,
535            RekeyPolicy::Jittered { interval, jitter } => {
536                let digest = blake3::hash(group.group_uri.as_bytes());
537                let fraction = u16::from_be_bytes([digest.as_bytes()[0], digest.as_bytes()[1]])
538                    as f64
539                    / u16::MAX as f64;
540                age >= interval + Duration::from_secs_f64(jitter.as_secs_f64() * fraction)
541            }
542        }
543    }
544
545    pub fn rekey_policy(&self) -> &RekeyPolicy {
546        &self.rekey_policy
547    }
548
549    pub fn now_millis() -> i64 {
550        SystemTime::now()
551            .duration_since(UNIX_EPOCH)
552            .unwrap_or_default()
553            .as_millis() as i64
554    }
555}
556
557pub fn recipient_key_id(recipient: &RecipientPublic) -> Vec<u8> {
558    blake3::derive_key(
559        "hyprstream group HyKEM recipient key id v1",
560        &recipient.encode(),
561    )
562    .to_vec()
563}
564
565pub fn open_epoch_grant(
566    recipient: &RecipientKeypair,
567    grant: &EpochGrant,
568) -> Result<Zeroizing<[u8; 32]>, String> {
569    if recipient_key_id(&recipient.public()) != grant.recipient_key_id {
570        return Err("epoch grant is not addressed to this HyKEM recipient".to_owned());
571    }
572    let aad = epoch_grant_aad(grant);
573    let plaintext = cose_encrypt::open_from_recipient(
574        recipient,
575        &grant.sealed_epoch_secret,
576        &aad,
577        grant.epoch,
578        grant.membership_version,
579    )
580    .map_err(|e| format!("hybrid epoch unwrap failed: {e}"))?;
581    let key: [u8; 32] = plaintext
582        .try_into()
583        .map_err(|_| "epoch secret must be exactly 32 bytes".to_owned())?;
584    Ok(Zeroizing::new(key))
585}
586
587fn validate_controller(controller: &ControllerBinding) -> Result<(), String> {
588    if controller.controller_did.is_empty()
589        || controller.accepted_state.is_empty()
590        || controller.sender_did.is_empty()
591        || controller.sender_ed25519 == [0; 32]
592        || controller.sender_ml_dsa_65.is_empty()
593        || controller.retention_policy.is_empty()
594        || controller.opaque_routing_policy.is_empty()
595    {
596        return Err("controller binding is incomplete".to_owned());
597    }
598    ed25519_dalek::VerifyingKey::from_bytes(&controller.sender_ed25519)
599        .map_err(|_| "controller sender Ed25519 key is invalid".to_owned())?;
600    crate::crypto::pq::ml_dsa_vk_from_bytes(&controller.sender_ml_dsa_65)
601        .map_err(|_| "controller sender ML-DSA-65 key is invalid".to_owned())?;
602    Ok(())
603}
604
605fn random_epoch_key() -> Zeroizing<[u8; 32]> {
606    let mut key = Zeroizing::new([0; 32]);
607    rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut *key);
608    key
609}
610
611fn seal_epoch_grant(
612    group: &GroupRef,
613    keyset_id: &str,
614    controller: &ControllerBinding,
615    member: &GroupMembership,
616    membership_version: u64,
617    epoch: u64,
618    key: &[u8; 32],
619) -> Result<EpochGrant, String> {
620    let mut grant = EpochGrant {
621        group_uri: group.group_uri.clone(),
622        controller_did: controller.controller_did.clone(),
623        keyset_id: keyset_id.to_owned(),
624        subject_did: member.subject_did.clone(),
625        accepted_state: member.accepted_state.clone(),
626        sender_did: controller.sender_did.clone(),
627        sender_ed25519: controller.sender_ed25519,
628        sender_ml_dsa_65: controller.sender_ml_dsa_65.clone(),
629        retention_policy: controller.retention_policy.clone(),
630        opaque_routing_policy: controller.opaque_routing_policy.clone(),
631        capability: member.capability.clone(),
632        recipient_key_id: member.recipient_key_id.clone(),
633        blinded_routing_key: member.blinded_routing_key,
634        membership_version,
635        epoch,
636        expires_at_millis: member.expires_at_millis.min(controller.expires_at_millis),
637        sealed_epoch_secret: Vec::new(),
638    };
639    let aad = epoch_grant_aad(&grant);
640    grant.sealed_epoch_secret =
641        cose_encrypt::seal_to_recipient(&member.recipient, key, &aad, epoch, membership_version)
642            .map_err(|e| format!("hybrid epoch seal failed: {e}"))?;
643    Ok(grant)
644}
645
646fn epoch_grant_aad(grant: &EpochGrant) -> Vec<u8> {
647    fn lp(out: &mut Vec<u8>, value: &[u8]) {
648        out.extend_from_slice(&(value.len() as u32).to_be_bytes());
649        out.extend_from_slice(value);
650    }
651    let mut out = b"hyprstream controller group epoch grant v1".to_vec();
652    lp(&mut out, grant.group_uri.as_bytes());
653    lp(&mut out, grant.controller_did.as_bytes());
654    lp(&mut out, grant.keyset_id.as_bytes());
655    lp(&mut out, grant.subject_did.as_bytes());
656    lp(&mut out, &grant.accepted_state);
657    lp(&mut out, grant.sender_did.as_bytes());
658    lp(&mut out, &grant.sender_ed25519);
659    lp(&mut out, &grant.sender_ml_dsa_65);
660    lp(&mut out, &grant.retention_policy);
661    lp(&mut out, &grant.opaque_routing_policy);
662    lp(&mut out, &grant.capability);
663    lp(&mut out, &grant.recipient_key_id);
664    lp(&mut out, &grant.blinded_routing_key);
665    out.extend_from_slice(&grant.membership_version.to_be_bytes());
666    out.extend_from_slice(&grant.epoch.to_be_bytes());
667    out.extend_from_slice(&grant.expires_at_millis.to_be_bytes());
668    out
669}
670
671#[cfg(test)]
672mod tests {
673    #![allow(clippy::unwrap_used, clippy::expect_used)]
674    use super::*;
675    use crate::crypto::hybrid_kem::{generate_recipient, SuiteId};
676
677    struct AllowExact;
678    impl MembershipResolver for AllowExact {
679        fn resolve(&self, requested: &GroupMembership) -> Result<GroupMembership, String> {
680            Ok(requested.clone())
681        }
682    }
683
684    struct SwapsSubject;
685    impl MembershipResolver for SwapsSubject {
686        fn resolve(&self, requested: &GroupMembership) -> Result<GroupMembership, String> {
687            let mut resolved = requested.clone();
688            resolved.subject_did = "did:web:attacker".to_owned();
689            Ok(resolved)
690        }
691    }
692
693    fn group() -> GroupRef {
694        GroupRef::new("at://did:web:controller/events/g1", "ks-0")
695    }
696    fn controller(state: &[u8]) -> ControllerBinding {
697        let ed = ed25519_dalek::SigningKey::from_bytes(&[42; 32]);
698        let pq = crate::node_identity::derive_mesh_mldsa_key(&ed);
699        ControllerBinding {
700            controller_did: "did:web:controller".to_owned(),
701            accepted_state: state.to_vec(),
702            sender_did: "did:web:publisher".to_owned(),
703            sender_ed25519: ed.verifying_key().to_bytes(),
704            sender_ml_dsa_65: crate::crypto::pq::ml_dsa_sk_to_vk_bytes(&pq),
705            retention_policy: b"retention:bounded-v1".to_vec(),
706            opaque_routing_policy: b"routing:stock-moq-opaque-v1".to_vec(),
707            expires_at_millis: i64::MAX,
708        }
709    }
710    fn member(did: &str, recipient: &RecipientKeypair, blind: u8, state: &[u8]) -> GroupMembership {
711        let public = recipient.public();
712        GroupMembership {
713            group_uri: group().group_uri,
714            subject_did: did.to_owned(),
715            accepted_state: state.to_vec(),
716            capability: format!("cap:{did}:subscribe").into_bytes(),
717            recipient_key_id: recipient_key_id(&public),
718            recipient: public,
719            blinded_routing_key: [blind; 32],
720            expires_at_millis: i64::MAX,
721        }
722    }
723
724    #[tokio::test]
725    async fn deny_all_fails_before_epoch_release() {
726        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, DenyAllResolver).unwrap();
727        registry
728            .register_group(group(), controller(b"cid512:a"))
729            .await
730            .unwrap();
731        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
732        let result = registry
733            .prepare_change(
734                &group(),
735                MembershipChange::Join(member("did:web:m", &recipient, 7, b"cid512:a")),
736                "ks-1",
737            )
738            .await;
739        assert!(result.is_err());
740        assert_eq!(registry.committed_coordinates(&group()).await.unwrap().1, 0);
741    }
742
743    #[tokio::test]
744    async fn hybrid_join_unwraps_and_wrong_recipient_cannot() {
745        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, AllowExact).unwrap();
746        registry
747            .register_group(group(), controller(b"cid512:a"))
748            .await
749            .unwrap();
750        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
751        let wrong = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
752        let prepared = registry
753            .prepare_change(
754                &group(),
755                MembershipChange::Join(member("did:web:m", &recipient, 7, b"cid512:a")),
756                "ks-1",
757            )
758            .await
759            .unwrap();
760        assert_eq!(prepared.grants.len(), 1);
761        assert!(open_epoch_grant(&wrong, &prepared.grants[0]).is_err());
762        let opened = open_epoch_grant(&recipient, &prepared.grants[0]).unwrap();
763        registry.commit_prepared(&group(), 1, 1).await.unwrap();
764        assert_eq!(*opened, registry.k_group(&group()).await.unwrap());
765    }
766
767    #[tokio::test]
768    async fn prepare_is_invisible_and_abort_preserves_committed_epoch() {
769        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, AllowExact).unwrap();
770        registry
771            .register_group(group(), controller(b"cid512:a"))
772            .await
773            .unwrap();
774        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
775        registry
776            .prepare_change(
777                &group(),
778                MembershipChange::Join(member("did:web:m", &recipient, 8, b"cid512:a")),
779                "ks-1",
780            )
781            .await
782            .unwrap();
783        assert_eq!(
784            registry.committed_coordinates(&group()).await.unwrap(),
785            ("ks-0".to_owned(), 0, 0)
786        );
787        assert!(!registry.contains_member(&group(), "did:web:m").await);
788        registry
789            .abort_prepared(&group(), "ks-1", 1, 1)
790            .await
791            .unwrap();
792        assert_eq!(registry.committed_coordinates(&group()).await.unwrap().2, 0);
793    }
794
795    #[tokio::test]
796    async fn stale_abort_cannot_discard_a_newer_pending_epoch() {
797        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, AllowExact).unwrap();
798        registry
799            .register_group(group(), controller(b"cid512:a"))
800            .await
801            .unwrap();
802        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
803        let first = registry
804            .prepare_change(
805                &group(),
806                MembershipChange::Join(member("did:web:m", &recipient, 8, b"cid512:a")),
807                "ks-1",
808            )
809            .await
810            .unwrap();
811        registry
812            .abort_prepared(
813                &group(),
814                &first.keyset_id,
815                first.membership_version,
816                first.epoch,
817            )
818            .await
819            .unwrap();
820        let second = registry
821            .prepare_change(
822                &group(),
823                MembershipChange::Join(member("did:web:m", &recipient, 8, b"cid512:a")),
824                "ks-2",
825            )
826            .await
827            .unwrap();
828        assert!(registry
829            .abort_prepared(
830                &group(),
831                &first.keyset_id,
832                first.membership_version,
833                first.epoch,
834            )
835            .await
836            .is_err());
837        assert_eq!(
838            registry.pending_epoch(&group()).await.unwrap().keyset_id,
839            second.keyset_id
840        );
841    }
842
843    #[tokio::test]
844    async fn accepted_state_advance_rejects_a_resolver_subject_swap() {
845        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, SwapsSubject).unwrap();
846        registry
847            .register_group(group(), controller(b"cid512:a"))
848            .await
849            .unwrap();
850        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
851        let change = MembershipChange::AcceptedStateAdvance {
852            accepted_state: b"cid512:b".to_vec(),
853            members: vec![member("did:web:member", &recipient, 9, b"cid512:b")],
854        };
855        assert!(registry
856            .prepare_change(&group(), change, "ks-1")
857            .await
858            .is_err());
859        assert!(registry.pending_epoch(&group()).await.is_none());
860    }
861
862    #[tokio::test]
863    async fn revoke_rotates_and_excludes_revoked_member() {
864        let registry = GroupKeyRegistry::new(
865            RekeyPolicy::Scheduled {
866                interval: Duration::from_secs(3600),
867            },
868            AllowExact,
869        )
870        .unwrap();
871        registry
872            .register_group(group(), controller(b"cid512:a"))
873            .await
874            .unwrap();
875        let a = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
876        let b = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
877        let p = registry
878            .prepare_change(
879                &group(),
880                MembershipChange::Join(member("did:web:a", &a, 1, b"cid512:a")),
881                "ks-1",
882            )
883            .await
884            .unwrap();
885        registry
886            .commit_prepared(&group(), p.membership_version, p.epoch)
887            .await
888            .unwrap();
889        let p = registry
890            .prepare_change(
891                &group(),
892                MembershipChange::Join(member("did:web:b", &b, 2, b"cid512:a")),
893                "ks-2",
894            )
895            .await
896            .unwrap();
897        registry
898            .commit_prepared(&group(), p.membership_version, p.epoch)
899            .await
900            .unwrap();
901        let p = registry
902            .prepare_change(
903                &group(),
904                MembershipChange::Revoke {
905                    subject_did: "did:web:a".to_owned(),
906                },
907                "ks-3",
908            )
909            .await
910            .unwrap();
911        assert_eq!(
912            p.grants.len(),
913            1,
914            "revoked member receives no next-epoch material"
915        );
916        assert_eq!(p.grants[0].subject_did, "did:web:b");
917        assert!(open_epoch_grant(&a, &p.grants[0]).is_err());
918        assert!(open_epoch_grant(&b, &p.grants[0]).is_ok());
919        registry
920            .commit_prepared(&group(), p.membership_version, p.epoch)
921            .await
922            .unwrap();
923        assert!(!registry.contains_member(&group(), "did:web:a").await);
924    }
925
926    #[tokio::test]
927    async fn aad_mutation_and_classical_key_substitution_fail() {
928        let registry = GroupKeyRegistry::new(RekeyPolicy::Immediate, AllowExact).unwrap();
929        registry
930            .register_group(group(), controller(b"cid512:a"))
931            .await
932            .unwrap();
933        let recipient = generate_recipient(SuiteId::HyKemX25519MlKem768).unwrap();
934        let p = registry
935            .prepare_change(
936                &group(),
937                MembershipChange::Join(member("did:web:m", &recipient, 3, b"cid512:a")),
938                "ks-1",
939            )
940            .await
941            .unwrap();
942        let mut mutated = p.grants[0].clone();
943        mutated.controller_did = "did:web:attacker".to_owned();
944        assert!(
945            open_epoch_grant(&recipient, &mutated).is_err(),
946            "controller mutation must invalidate COSE AAD"
947        );
948        let mut substituted = p.grants[0].clone();
949        // Mutation-effective negative control for the removed signing-key-as-KEX bug:
950        // an arbitrary 32-byte classical signing public key cannot stand in for
951        // the separately accepted suite-identified HyKEM recipient.
952        substituted.recipient_key_id = vec![0xED; 32];
953        assert!(open_epoch_grant(&recipient, &substituted).is_err());
954    }
955
956    #[test]
957    fn blinded_presentations_remain_unlinkable_but_are_not_kex_keys() {
958        let (_, stable) = crate::crypto::generate_ephemeral_keypair();
959        let a = BlindedMember::new(&stable.to_bytes()).unwrap();
960        let b = BlindedMember::new(&stable.to_bytes()).unwrap();
961        assert_ne!(a.blinded_pubkey, stable.to_bytes());
962        assert_ne!(a.blinded_pubkey, b.blinded_pubkey);
963    }
964}