Skip to main content

wechat_protocol/calls/
audio_packet.rs

1//! Selected Live96 envelope and ordinary95 Opus-primary framing. Encoding these
2//! bytes does not establish negotiated capabilities, room ownership or permission
3//! to send. Media transmission requires a separately admitted generation/scope.
4
5use anyhow::{bail, ensure, Result};
6use openssl::{
7    hash::MessageDigest,
8    memcmp,
9    pkey::{Id, PKey},
10    sign::Signer,
11    symm::{Cipher, Crypter, Mode},
12};
13use std::collections::BTreeMap;
14use zeroize::Zeroizing;
15
16const HEADER: usize = 19;
17const MAX_PACKET: usize = 1519;
18const MAX_CONF: usize = 1024;
19const WINDOW: u16 = 64;
20const MAX_NONCE_VARIANTS: usize = 8;
21// Leave 60,000 sequences for the current 20-minute limit at 50 audio packets/sec.
22const MAX_LEGACY_AUDIO_START: u16 = u16::MAX - 59_999;
23
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub struct MediaEpoch {
26    pub account_generation: u64,
27    pub logout_epoch: u64,
28    pub call_generation: u64,
29    pub key_generation: u64,
30}
31impl MediaEpoch {
32    fn validate(self) -> Result<()> {
33        ensure!(
34            self.account_generation != 0 && self.call_generation != 0 && self.key_generation != 0,
35            "Inactive media generation"
36        );
37        Ok(())
38    }
39}
40
41#[derive(Clone, Copy, Debug, PartialEq, Eq)]
42pub struct MediaContext {
43    pub room_id: u64,
44    pub own_member: u16,
45    pub peer_member: u16,
46    pub connection_id: u16,
47}
48
49/// An untrusted routing hint for selecting a roster-bound receiver. The chosen
50/// receiver must still authenticate the packet and check its protected member.
51pub fn unverified_live96_member(packet: &[u8]) -> Result<u16> {
52    ensure!(
53        (38..=MAX_PACKET).contains(&packet.len()) && packet[..2] == [0x96, 19],
54        "Unsupported Live96 packet shape"
55    );
56    Ok(u16::from_le_bytes(packet[10..12].try_into()?))
57}
58
59/// The owner must establish a fresh media generation before authorizing sends.
60/// The legacy relay scope trades cross-direction audio nonce uniqueness for
61/// interoperability with peers that share media key material. It also permits
62/// authenticated receive nonce reuse, with bounded ciphertext replay filtering.
63pub enum TransmitScope {
64    VerifiedGeneration {
65        key_generation: u64,
66    },
67    LegacyRelayAudio {
68        key_generation: u64,
69    },
70    IsolatedCompatibilityTest {
71        intent_id: [u8; 32],
72        deadline_ms: u64,
73        allow_known_audio_overlap: bool,
74    },
75}
76
77/// Authenticated current-generation payload. Clear headers are not fully in AAD;
78/// protected member equality and external source/room/roster checks remain needed.
79/// Contents have no Debug/Serialize implementation.
80pub struct OpenedPayload {
81    pub packed_kind: u8,
82    pub sequence: u16,
83    payload: Zeroizing<Vec<u8>>,
84    epoch: MediaEpoch,
85    context: MediaContext,
86}
87impl OpenedPayload {
88    pub fn payload(&self) -> &[u8] {
89        &self.payload
90    }
91}
92
93/// One key/base/generation owner. No Clone, reset or implicit rekey is provided.
94/// The 64-sequence RX window is a local policy; rollover requires a verified new
95/// generation. Socket-source validation must happen before `open`.
96pub struct Live96 {
97    key: Zeroizing<[u8; 32]>,
98    base: Zeroizing<u64>,
99    context: MediaContext,
100    epoch: MediaEpoch,
101    tx_scope: Option<TransmitScope>,
102    receive_only: bool,
103    first_tx_audio: u16,
104    next_audio: u32,
105    next_control: u32,
106    clear_sequence: u32,
107    rx_highest: BTreeMap<u8, u16>,
108    rx_seen: BTreeMap<u8, Box<[u64; 1024]>>,
109    rx: BTreeMap<[u8; 8], Vec<[u8; 32]>>,
110    legacy_receive_nonce_reuse: bool,
111    receive_nonce_reuses: BTreeMap<u8, u64>,
112    audio_overlaps: u64,
113    closed: bool,
114}
115impl Live96 {
116    pub fn new(
117        key: [u8; 32],
118        nonce_base: u64,
119        context: MediaContext,
120        epoch: MediaEpoch,
121    ) -> Result<Self> {
122        Self::create(key, nonce_base, context, epoch, false)
123    }
124
125    /// Receive-only room inspection can include relayed self-member packets.
126    /// The caller still checks socket source and roster membership before any
127    /// audio delivery. This instance can never acquire transmit permission.
128    pub fn new_receive_only(
129        key: [u8; 32],
130        nonce_base: u64,
131        context: MediaContext,
132        epoch: MediaEpoch,
133    ) -> Result<Self> {
134        Self::create(key, nonce_base, context, epoch, true)
135    }
136
137    /// Legacy relay reception tolerates authenticated nonce reuse without
138    /// resetting counters or granting transmit permission. Exact ciphertext
139    /// replays are filtered within the receive window; excess variants for one
140    /// nonce are dropped rather than closing the receiver.
141    pub fn new_legacy_receive_only(
142        key: [u8; 32],
143        nonce_base: u64,
144        context: MediaContext,
145        epoch: MediaEpoch,
146    ) -> Result<Self> {
147        let mut channel = Self::create(key, nonce_base, context, epoch, true)?;
148        channel.legacy_receive_nonce_reuse = true;
149        Ok(channel)
150    }
151
152    fn create(
153        key: [u8; 32],
154        nonce_base: u64,
155        context: MediaContext,
156        epoch: MediaEpoch,
157        receive_only: bool,
158    ) -> Result<Self> {
159        epoch.validate()?;
160        ensure!(
161            context.room_id != 0
162                && nonce_base != 0
163                && (receive_only || context.own_member != context.peer_member),
164            "Invalid media room/member context"
165        );
166        Ok(Self {
167            key: Zeroizing::new(key),
168            base: Zeroizing::new(nonce_base),
169            context,
170            epoch,
171            tx_scope: None,
172            receive_only,
173            first_tx_audio: 0,
174            next_audio: 0,
175            next_control: 0,
176            clear_sequence: 0,
177            rx_highest: BTreeMap::new(),
178            rx_seen: BTreeMap::new(),
179            rx: BTreeMap::new(),
180            legacy_receive_nonce_reuse: false,
181            receive_nonce_reuses: BTreeMap::new(),
182            audio_overlaps: 0,
183            closed: false,
184        })
185    }
186    fn check(&mut self, current: MediaEpoch) -> Result<()> {
187        if self.closed || self.epoch != current {
188            self.close();
189            bail!("Media generation changed or closed");
190        }
191        Ok(())
192    }
193    pub fn authorize_transmit(&mut self, current: MediaEpoch, scope: TransmitScope) -> Result<()> {
194        self.check(current)?;
195        ensure!(!self.receive_only, "Receive-only media cannot transmit");
196        ensure!(
197            self.tx_scope.is_none(),
198            "Media transmit scope already installed"
199        );
200        match &scope {
201            TransmitScope::VerifiedGeneration { key_generation }
202            | TransmitScope::LegacyRelayAudio { key_generation } => ensure!(
203                *key_generation == current.key_generation,
204                "Media key generation mismatch"
205            ),
206            TransmitScope::IsolatedCompatibilityTest {
207                intent_id,
208                deadline_ms,
209                ..
210            } => ensure!(
211                *intent_id != [0; 32] && *deadline_ms != 0,
212                "Missing isolated media test scope"
213            ),
214        };
215        if matches!(scope, TransmitScope::LegacyRelayAudio { .. }) {
216            self.first_tx_audio = self.legacy_audio_start()?;
217            self.next_audio = u32::from(self.first_tx_audio);
218            self.legacy_receive_nonce_reuse = true;
219        }
220        self.tx_scope = Some(scope);
221        Ok(())
222    }
223    fn legacy_audio_start(&self) -> Result<u16> {
224        let key = PKey::hmac(&self.key[..])?;
225        let mut mac = Signer::new(MessageDigest::sha256(), &key)?;
226        mac.update(b"agent-wechat/live96/audio-start/v1")?;
227        mac.update(&self.context.room_id.to_le_bytes())?;
228        mac.update(&self.base.to_le_bytes())?;
229        mac.update(&self.context.own_member.to_le_bytes())?;
230        let digest = Zeroizing::new(mac.sign_to_vec()?);
231        let prefix = u32::from_le_bytes(digest[..4].try_into()?);
232        Ok((prefix % u32::from(MAX_LEGACY_AUDIO_START) + 1) as u16)
233    }
234    fn tx_check(&mut self, current: MediaEpoch, now_ms: u64) -> Result<()> {
235        self.check(current)?;
236        match &self.tx_scope {
237            None => bail!("Media transmission is not authorized"),
238            Some(
239                TransmitScope::VerifiedGeneration { .. } | TransmitScope::LegacyRelayAudio { .. },
240            ) => Ok(()),
241            Some(TransmitScope::IsolatedCompatibilityTest { deadline_ms, .. }) => {
242                if now_ms >= *deadline_ms {
243                    self.close();
244                    bail!("Isolated media test expired");
245                }
246                Ok(())
247            }
248        }
249    }
250    fn nonce(&self, kind: u8, sequence: u16) -> [u8; 8] {
251        self.base
252            .wrapping_add(u64::from(kind) << 32)
253            .wrapping_add(u64::from(sequence))
254            .to_le_bytes()
255    }
256    fn diagnostic_audio_overlap(&mut self, kind: u8) -> Result<()> {
257        if kind == 0x10
258            && matches!(
259                self.tx_scope,
260                Some(
261                    TransmitScope::LegacyRelayAudio { .. }
262                        | TransmitScope::IsolatedCompatibilityTest {
263                            allow_known_audio_overlap: true,
264                            ..
265                        }
266                )
267            )
268        {
269            self.audio_overlaps = self
270                .audio_overlaps
271                .checked_add(1)
272                .ok_or_else(|| anyhow::anyhow!("Media diagnostic count exhausted"))?;
273            Ok(())
274        } else {
275            self.close();
276            bail!("Known media cross-direction nonce reuse")
277        }
278    }
279    pub fn known_audio_overlaps(&self) -> u64 {
280        self.audio_overlaps
281    }
282    pub fn received_nonce_reuses(&self) -> &BTreeMap<u8, u64> {
283        &self.receive_nonce_reuses
284    }
285    pub fn seal_audio(
286        &mut self,
287        current: MediaEpoch,
288        now_ms: u64,
289        conf_payload: &[u8],
290    ) -> Result<Vec<u8>> {
291        parse_ordinary95(conf_payload)?;
292        self.seal(current, now_ms, 0x10, conf_payload)
293    }
294    fn seal(
295        &mut self,
296        current: MediaEpoch,
297        now_ms: u64,
298        kind: u8,
299        payload: &[u8],
300    ) -> Result<Vec<u8>> {
301        self.tx_check(current, now_ms)?;
302        ensure!(
303            !payload.is_empty() && payload.len() <= 1482,
304            "Invalid media payload extent"
305        );
306        let next = match kind {
307            0x10 => &mut self.next_audio,
308            0x70 => &mut self.next_control,
309            _ => bail!("Unsupported media sender family"),
310        };
311        ensure!(
312            *next <= u32::from(u16::MAX) && self.clear_sequence < u32::MAX,
313            "Media sequence exhausted; verified rekey required"
314        );
315        let sequence = *next as u16;
316        *next += 1;
317        let nonce = self.nonce(kind, sequence);
318        if self
319            .rx_seen
320            .get(&kind)
321            .is_some_and(|seen| seen[usize::from(sequence) / 64] & (1u64 << (sequence % 64)) != 0)
322        {
323            self.diagnostic_audio_overlap(kind)?;
324        }
325        let mut protected = Zeroizing::new(Vec::with_capacity(payload.len() + 2));
326        protected.extend(self.context.own_member.to_le_bytes());
327        protected.extend(payload);
328        let cipher = seal_original(&self.key, nonce, &protected)?;
329        let mut packet = Vec::with_capacity(HEADER + cipher.len());
330        packet.extend([0x96, 19]);
331        packet.extend(self.context.room_id.to_le_bytes());
332        packet.extend(self.context.own_member.to_le_bytes());
333        packet.extend((self.clear_sequence as u16).to_le_bytes());
334        packet.push(kind);
335        packet.extend(sequence.to_le_bytes());
336        packet.extend([0, self.context.connection_id as u8]);
337        packet.extend(cipher);
338        self.clear_sequence += 1;
339        Ok(packet)
340    }
341    pub fn open(&mut self, current: MediaEpoch, packet: &[u8]) -> Result<Option<OpenedPayload>> {
342        self.check(current)?;
343        let member = unverified_live96_member(packet)?;
344        ensure!(
345            u64::from_le_bytes(packet[2..10].try_into()?) == self.context.room_id
346                && member == self.context.peer_member,
347            "Media room/member mismatch"
348        );
349        let kind = packet[14];
350        ensure!(
351            matches!(kind, 0x10 | 0x20 | 0x70) && packet[17] == 0,
352            "Unsupported Live96 packet family or extension"
353        );
354        let sequence = u16::from_le_bytes(packet[15..17].try_into()?);
355        let nonce = self.nonce(kind, sequence);
356        let clear = open_original(&self.key, nonce, &packet[HEADER..])?;
357        ensure!(
358            clear.len() > 2
359                && clear.len() <= 1484
360                && u16::from_le_bytes(clear[..2].try_into()?) == self.context.peer_member,
361            "Protected media member mismatch or extent"
362        );
363        let digest: [u8; 32] = openssl::sha::sha256(&packet[HEADER..]);
364        if let Some(previous) = self.rx.get(&nonce) {
365            if previous.contains(&digest) {
366                return Ok(None);
367            }
368            if !self.legacy_receive_nonce_reuse {
369                self.close();
370                bail!("Authenticated media nonce conflict");
371            }
372            let count = self.receive_nonce_reuses.entry(kind).or_default();
373            *count = count.saturating_add(1);
374            if previous.len() >= MAX_NONCE_VARIANTS {
375                return Ok(None);
376            }
377        }
378        let own_next = if kind == 0x10 {
379            self.next_audio
380        } else if kind == 0x70 {
381            self.next_control
382        } else {
383            0
384        };
385        if u32::from(sequence) < own_next && (kind != 0x10 || sequence >= self.first_tx_audio) {
386            self.diagnostic_audio_overlap(kind)?;
387        }
388        // Retire every authenticated, sender-bound nonce before payload classification.
389        // Fixed 65536-bit ledgers preserve known cross-direction overlap checks
390        // after ciphertext digests leave the smaller reordering window.
391        let seen = self
392            .rx_seen
393            .entry(kind)
394            .or_insert_with(|| Box::new([0; 1024]));
395        seen[usize::from(sequence) / 64] |= 1u64 << (sequence % 64);
396        if self
397            .rx_highest
398            .get(&kind)
399            .is_some_and(|high| sequence < *high && *high - sequence >= WINDOW)
400        {
401            return Ok(None);
402        }
403        let high = self.rx_highest.entry(kind).or_insert(sequence);
404        *high = (*high).max(sequence);
405        let minimum = high.saturating_sub(WINDOW - 1);
406        let base = *self.base;
407        self.rx.retain(|nonce, _| {
408            let combined = u64::from_le_bytes(*nonce).wrapping_sub(base);
409            let k = (combined >> 32) as u8;
410            let s = combined as u16;
411            k != kind || s >= minimum
412        });
413        self.rx.entry(nonce).or_default().push(digest);
414        // RX connection ID is not assumed equal to the local TX connection ID.
415        Ok(Some(OpenedPayload {
416            packed_kind: kind,
417            sequence,
418            payload: Zeroizing::new(clear[2..].to_vec()),
419            epoch: current,
420            context: self.context,
421        }))
422    }
423    /// Reply only to the exact selected authenticated faking_type1 probe. A
424    /// periodic/control response receives no echo. No general control sender is
425    /// inferred, and retries would consume another semantic operation.
426    pub fn reply_to_probe(
427        &mut self,
428        current: MediaEpoch,
429        now_ms: u64,
430        opened: &OpenedPayload,
431    ) -> Result<Option<Vec<u8>>> {
432        self.check(current)?;
433        ensure!(
434            opened.epoch == current && opened.context == self.context,
435            "Stale authenticated control payload"
436        );
437        if opened.packed_kind != 0x70 {
438            return Ok(None);
439        }
440        match opened.payload() {
441            [8, 1, 18, 2, 8, 1] => {
442                // Leave the probe unanswered if a reply would consume an
443                // inbound nonce. The sender's reuse fence stays unchanged.
444                if self.next_control <= u32::from(u16::MAX)
445                    && self.rx_seen.get(&0x70).is_some_and(|seen| {
446                        let sequence = self.next_control as usize;
447                        seen[sequence / 64] & (1u64 << (sequence % 64)) != 0
448                    })
449                {
450                    return Ok(None);
451                }
452                Ok(Some(self.seal(
453                    current,
454                    now_ms,
455                    0x70,
456                    &[8, 1, 18, 2, 8, 2],
457                )?))
458            }
459            [8, 1, 18, 2, 8, 0 | 2] => Ok(None),
460            // Other authenticated control messages have no implemented reply.
461            // Ignore them without inventing a response or stopping audio.
462            _ => Ok(None),
463        }
464    }
465    pub fn close(&mut self) {
466        self.key = Zeroizing::new([0; 32]);
467        self.base = Zeroizing::new(0);
468        self.tx_scope = None;
469        self.closed = true;
470        self.rx.clear();
471        self.rx_highest.clear();
472        self.rx_seen.clear();
473    }
474}
475
476/// Member metadata accompanying one nested audio payload. The member list does
477/// not establish independent PCM tracks or prove that every listed member spoke.
478pub struct AggregateAudio<'a> {
479    pub members: Vec<(u16, u8)>,
480    pub nested_kind: u8,
481    pub nested_payload: &'a [u8],
482}
483
484/// Header marker for classifying an ordinary audio variant. This does not
485/// validate its codec body or grant decoder admission.
486pub fn ordinary_audio_marker(payload: &[u8]) -> Option<[u8; 2]> {
487    (payload.len() >= 6 && payload[0] == 1).then(|| [payload[4], payload[5]])
488}
489
490pub fn parse_aggregate_audio(payload: &[u8]) -> Result<AggregateAudio<'_>> {
491    ensure!(
492        payload.len() >= 3 && payload.len() <= 1482 && payload[0] == 0x65,
493        "Invalid aggregate audio extent"
494    );
495    let count = usize::from(payload[1]);
496    ensure!(count <= 128, "Too many aggregate audio members");
497    let end = 2 + 3 * count;
498    ensure!(
499        end + 1 < payload.len() && matches!(payload[end], 1 | 19),
500        "Truncated or unsupported aggregate audio"
501    );
502    let members = payload[2..end]
503        .chunks_exact(3)
504        .map(|entry| (u16::from_le_bytes([entry[0], entry[1]]), entry[2]))
505        .collect();
506    Ok(AggregateAudio {
507        members,
508        nested_kind: payload[end],
509        nested_payload: &payload[end + 1..],
510    })
511}
512
513/// Configured ordinary95/74 N1 sender for format106.
514pub fn ordinary95_single(
515    metadata: u8,
516    sequence: u16,
517    timestamp: u32,
518    frame: &[u8],
519) -> Result<Vec<u8>> {
520    ensure!(
521        !frame.is_empty() && frame.len() <= 1023 && 15 + frame.len() <= MAX_CONF,
522        "Invalid ordinary95 primary extent"
523    );
524    let mut out = Vec::with_capacity(15 + frame.len());
525    out.extend([1, metadata, 0, 0, 0x95, 0x74]);
526    out.extend(sequence.to_be_bytes());
527    out.extend(timestamp.to_be_bytes());
528    out.push(1);
529    out.extend((frame.len() as i16).to_le_bytes());
530    out.extend(frame);
531    Ok(out)
532}
533
534/// Configured ordinary95/74 N2 sender. RTP sequence/time identify the LAST
535/// primary, independent from cryptographic counters and clear room sequence.
536pub fn ordinary95_pair(
537    metadata: u8,
538    last_sequence: u16,
539    last_timestamp: u32,
540    first: &[u8],
541    second: &[u8],
542) -> Result<Vec<u8>> {
543    ensure!(
544        !first.is_empty()
545            && !second.is_empty()
546            && first.len() <= 1023
547            && second.len() <= 1023
548            && 17 + first.len() + second.len() <= MAX_CONF,
549        "Invalid ordinary95 primary extent"
550    );
551    let mut out = Vec::with_capacity(17 + first.len() + second.len());
552    out.extend([1, metadata, 0, 0, 0x95, 0x74]);
553    out.extend(last_sequence.to_be_bytes());
554    out.extend(last_timestamp.to_be_bytes());
555    out.push(2);
556    out.extend((first.len() as i16).to_le_bytes());
557    out.extend((second.len() as i16).to_le_bytes());
558    out.extend(first);
559    out.extend(second);
560    Ok(out)
561}
562
563/// Encoded Opus primaries, not decoded audio. The caller must establish that the
564/// current negotiation selects this codec/layout before decoding.
565pub struct OrdinaryAudio<'a> {
566    pub metadata: [u8; 4],
567    pub last_sequence: u16,
568    pub last_timestamp: u32,
569    pub primaries: Vec<&'a [u8]>,
570}
571pub fn parse_ordinary95(payload: &[u8]) -> Result<OrdinaryAudio<'_>> {
572    ensure!(
573        (16..=MAX_CONF).contains(&payload.len())
574            && payload[0] == 1
575            && payload[4..6] == [0x95, 0x74],
576        "Unsupported ordinary95 audio shape"
577    );
578    let count = usize::from(payload[12]);
579    ensure!(
580        (1..=3).contains(&count) && 13 + 2 * count <= payload.len(),
581        "Invalid ordinary95 primary count"
582    );
583    let mut cursor = 13 + 2 * count;
584    let mut primaries = Vec::with_capacity(count);
585    for n in 0..count {
586        let length = i16::from_le_bytes(payload[13 + 2 * n..15 + 2 * n].try_into()?);
587        ensure!(
588            (1..=1023).contains(&length),
589            "Invalid ordinary95 primary length"
590        );
591        let length = length as usize;
592        ensure!(
593            length <= payload.len() - cursor,
594            "Truncated ordinary95 primary"
595        );
596        primaries.push(&payload[cursor..cursor + length]);
597        cursor += length;
598    }
599    ensure!(cursor == payload.len(), "Trailing ordinary95 bytes");
600    Ok(OrdinaryAudio {
601        metadata: payload[..4].try_into()?,
602        last_sequence: u16::from_be_bytes(payload[6..8].try_into()?),
603        last_timestamp: u32::from_be_bytes(payload[8..12].try_into()?),
604        primaries,
605    })
606}
607fn xor(key: &[u8; 32], nonce: [u8; 8], counter: u64, input: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
608    let mut iv = Zeroizing::new([0; 16]);
609    iv[..8].copy_from_slice(&counter.to_le_bytes());
610    iv[8..].copy_from_slice(&nonce);
611    let cipher = Cipher::chacha20();
612    let mut crypter = Crypter::new(cipher, Mode::Encrypt, key, Some(&*iv))?;
613    crypter.pad(false);
614    let mut out = Zeroizing::new(vec![0; input.len() + cipher.block_size()]);
615    let n = crypter.update(input, &mut out)?;
616    let end = crypter.finalize(&mut out[n..])?;
617    out.truncate(n + end);
618    ensure!(out.len() == input.len(), "Unexpected call cipher size");
619    Ok(out)
620}
621fn tag(key: &[u8; 32], nonce: [u8; 8], cipher: &[u8]) -> Result<[u8; 16]> {
622    let one = xor(key, nonce, 0, &[0; 32])?;
623    let key = PKey::private_key_from_raw_bytes(&one, Id::POLY1305)?;
624    let mut signer = Signer::new_without_digest(&key)?;
625    signer.update(&0u64.to_le_bytes())?;
626    signer.update(cipher)?;
627    signer.update(&(cipher.len() as u64).to_le_bytes())?;
628    let mut tag = [0; 16];
629    ensure!(signer.sign(&mut tag)? == 16, "Unexpected call tag size");
630    Ok(tag)
631}
632fn seal_original(key: &[u8; 32], nonce: [u8; 8], clear: &[u8]) -> Result<Vec<u8>> {
633    ensure!(clear.len() <= 1484, "Call cipher input too large");
634    let cipher = xor(key, nonce, 1, clear)?;
635    let tag = tag(key, nonce, &cipher)?;
636    let mut out = Vec::with_capacity(cipher.len() + 16);
637    out.extend(&*cipher);
638    out.extend(tag);
639    Ok(out)
640}
641fn open_original(key: &[u8; 32], nonce: [u8; 8], sealed: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
642    ensure!(
643        (16..=1500).contains(&sealed.len()),
644        "Invalid call ciphertext extent"
645    );
646    let (cipher, expected) = sealed.split_at(sealed.len() - 16);
647    let actual = tag(key, nonce, cipher)?;
648    ensure!(
649        memcmp::eq(&actual, expected),
650        "Call media authentication failed"
651    );
652    xor(key, nonce, 1, cipher)
653}
654
655#[cfg(test)]
656mod tests {
657    use super::*;
658    #[test]
659    fn aggregate_keeps_member_metadata_separate_from_single_nested_payload() {
660        let bytes = [0x65, 2, 0x34, 0x12, 7, 0x78, 0x56, 9, 1, 0xaa];
661        let aggregate = parse_aggregate_audio(&bytes).unwrap();
662        assert_eq!(aggregate.members, [(0x1234, 7), (0x5678, 9)]);
663        assert_eq!(aggregate.nested_kind, 1);
664        assert_eq!(aggregate.nested_payload, [0xaa]);
665        for length in 0..bytes.len() {
666            assert!(parse_aggregate_audio(&bytes[..length]).is_err());
667        }
668        assert!(parse_aggregate_audio(&[0x65, 0, 2, 1]).is_err());
669    }
670
671    #[test]
672    fn receive_only_context_observes_protected_self_member_without_transmit_permission() {
673        let mut receive = Live96::new_receive_only(
674            [7; 32],
675            11,
676            MediaContext {
677                own_member: 1,
678                peer_member: 1,
679                ..context()
680            },
681            epoch(),
682        )
683        .unwrap();
684        let raw = ordinary95_single(0, 0, 0, &[1]).unwrap();
685        let mut sending = peer();
686        let packet = sending.seal_audio(epoch(), 1, &raw).unwrap();
687        assert!(receive.open(epoch(), &packet).unwrap().is_some());
688        assert!(receive
689            .authorize_transmit(
690                epoch(),
691                TransmitScope::LegacyRelayAudio { key_generation: 1 }
692            )
693            .is_err());
694        assert!(receive.seal_audio(epoch(), 1, &raw).is_err());
695    }
696    fn epoch() -> MediaEpoch {
697        MediaEpoch {
698            account_generation: 1,
699            logout_epoch: 0,
700            call_generation: 1,
701            key_generation: 1,
702        }
703    }
704    fn context() -> MediaContext {
705        MediaContext {
706            room_id: 9,
707            own_member: 0,
708            peer_member: 1,
709            connection_id: 2,
710        }
711    }
712    fn receiver() -> Live96 {
713        Live96::new([7; 32], 11, context(), epoch()).unwrap()
714    }
715    fn peer() -> Live96 {
716        let mut c = context();
717        std::mem::swap(&mut c.own_member, &mut c.peer_member);
718        let mut sender = Live96::new([7; 32], 11, c, epoch()).unwrap();
719        sender
720            .authorize_transmit(
721                epoch(),
722                TransmitScope::VerifiedGeneration { key_generation: 1 },
723            )
724            .unwrap();
725        sender
726    }
727    #[test]
728    fn legacy_audio_start_depends_on_the_authenticated_member() {
729        let mut local = receiver();
730        let mut peer_context = context();
731        std::mem::swap(&mut peer_context.own_member, &mut peer_context.peer_member);
732        let mut remote = Live96::new([7; 32], 11, peer_context, epoch()).unwrap();
733        for channel in [&mut local, &mut remote] {
734            channel
735                .authorize_transmit(
736                    epoch(),
737                    TransmitScope::LegacyRelayAudio { key_generation: 1 },
738                )
739                .unwrap();
740        }
741        // Independent HMAC-SHA256 vectors for the same room and two member IDs.
742        assert_eq!(local.first_tx_audio, 440);
743        assert_eq!(remote.first_tx_audio, 429);
744        assert_eq!(local.next_audio, 440);
745        assert_eq!(remote.next_audio, 429);
746    }
747
748    #[test]
749    fn legacy_relay_allows_opposite_direction_audio_overlap_in_either_order() {
750        let raw = ordinary95_pair(0, 1, 320, &[1], &[2]).unwrap();
751        for transmit_first in [false, true] {
752            let mut local = receiver();
753            local
754                .authorize_transmit(
755                    epoch(),
756                    TransmitScope::LegacyRelayAudio { key_generation: 1 },
757                )
758                .unwrap();
759            let mut remote = peer();
760            remote.next_audio = u32::from(local.first_tx_audio);
761            let inbound = remote.seal_audio(epoch(), 0, &raw).unwrap();
762            if transmit_first {
763                local.seal_audio(epoch(), 0, &raw).unwrap();
764            }
765            assert_eq!(
766                local.open(epoch(), &inbound).unwrap().unwrap().payload(),
767                raw
768            );
769            if !transmit_first {
770                local.seal_audio(epoch(), 0, &raw).unwrap();
771            }
772            assert!(local.open(epoch(), &inbound).unwrap().is_none());
773            assert_eq!(local.known_audio_overlaps(), 1);
774
775            let mut conflicting_peer = peer();
776            conflicting_peer.next_audio = u32::from(local.first_tx_audio);
777            let different = ordinary95_pair(0, 1, 320, &[3], &[4]).unwrap();
778            let conflict = conflicting_peer.seal_audio(epoch(), 0, &different).unwrap();
779            assert_eq!(
780                local.open(epoch(), &conflict).unwrap().unwrap().payload(),
781                different
782            );
783            assert!(local.open(epoch(), &conflict).unwrap().is_none());
784            assert!(local.open(epoch(), &inbound).unwrap().is_none());
785            assert_eq!(local.received_nonce_reuses().get(&0x10), Some(&1));
786            assert!(local.seal_audio(epoch(), 0, &raw).is_ok());
787        }
788    }
789
790    #[test]
791    fn legacy_receive_reuse_filters_all_retained_variants_without_closing() {
792        for kind in [0x10, 0x70] {
793            let mut receive =
794                Live96::new_legacy_receive_only([7; 32], 11, context(), epoch()).unwrap();
795            let mut packets = Vec::new();
796            for variant in 0..=MAX_NONCE_VARIANTS {
797                let packet = peer().seal(epoch(), 0, kind, &[8, variant as u8]).unwrap();
798                let opened = receive.open(epoch(), &packet).unwrap();
799                assert_eq!(opened.is_some(), variant < MAX_NONCE_VARIANTS);
800                packets.push(packet);
801            }
802            for packet in &packets {
803                assert!(receive.open(epoch(), packet).unwrap().is_none());
804            }
805            assert_eq!(receive.rx.len(), 1);
806            assert_eq!(
807                receive.rx.values().next().unwrap().len(),
808                MAX_NONCE_VARIANTS
809            );
810            let mut sending = peer();
811            sending.seal(epoch(), 0, kind, &[8, 0]).unwrap();
812            let next = sending.seal(epoch(), 0, kind, &[8, 1]).unwrap();
813            assert!(receive.open(epoch(), &next).unwrap().is_some());
814            assert!(receive
815                .authorize_transmit(
816                    epoch(),
817                    TransmitScope::LegacyRelayAudio { key_generation: 1 }
818                )
819                .is_err());
820        }
821    }
822
823    #[test]
824    fn strict_receive_conflicting_ciphertext_still_closes() {
825        let first = peer().seal(epoch(), 0, 0x70, &[8, 1]).unwrap();
826        let different = peer().seal(epoch(), 0, 0x70, &[8, 2]).unwrap();
827        let mut receive = receiver();
828        receive.open(epoch(), &first).unwrap();
829        assert!(receive.open(epoch(), &different).is_err());
830        assert!(receive.open(epoch(), &first).is_err());
831    }
832
833    #[test]
834    fn forged_clear_sender_cannot_poison_a_legacy_receivers_nonce_ledger() {
835        let mut receive = Live96::new_legacy_receive_only([7; 32], 11, context(), epoch()).unwrap();
836        let mut sending = peer();
837        let first = sending.seal(epoch(), 0, 0x70, &[8, 1]).unwrap();
838        receive.open(epoch(), &first).unwrap();
839        let mut wrong = Live96::new(
840            [7; 32],
841            11,
842            MediaContext {
843                own_member: 2,
844                ..context()
845            },
846            epoch(),
847        )
848        .unwrap();
849        wrong
850            .authorize_transmit(
851                epoch(),
852                TransmitScope::VerifiedGeneration { key_generation: 1 },
853            )
854            .unwrap();
855        let mut forged = wrong.seal(epoch(), 0, 0x70, &[8, 2]).unwrap();
856        forged[10..12].copy_from_slice(&context().peer_member.to_le_bytes());
857        assert_eq!(
858            receive.open(epoch(), &forged).err().unwrap().to_string(),
859            "Protected media member mismatch or extent"
860        );
861        assert!(receive.received_nonce_reuses().is_empty());
862        assert!(receive.open(epoch(), &first).unwrap().is_none());
863        let next = sending.seal(epoch(), 0, 0x70, &[8, 3]).unwrap();
864        assert!(receive.open(epoch(), &next).unwrap().is_some());
865    }
866
867    #[test]
868    fn legacy_relay_keeps_control_and_send_exhaustion_fences() {
869        let mut local = receiver();
870        local
871            .authorize_transmit(
872                epoch(),
873                TransmitScope::LegacyRelayAudio { key_generation: 1 },
874            )
875            .unwrap();
876        let mut remote = peer();
877        local.seal(epoch(), 0, 0x70, &[8, 1, 18, 2, 8, 2]).unwrap();
878        let control = remote.seal(epoch(), 0, 0x70, &[8, 1, 18, 2, 8, 1]).unwrap();
879        assert!(local.open(epoch(), &control).is_err());
880
881        let mut local = receiver();
882        local
883            .authorize_transmit(
884                epoch(),
885                TransmitScope::LegacyRelayAudio { key_generation: 1 },
886            )
887            .unwrap();
888        local.next_audio = u32::from(u16::MAX);
889        let raw = ordinary95_pair(0, 1, 320, &[1], &[2]).unwrap();
890        local.seal_audio(epoch(), 0, &raw).unwrap();
891        assert!(local.seal_audio(epoch(), 0, &raw).is_err());
892    }
893
894    #[test]
895    fn original_aead_matches_independent_literal_vectors() {
896        // Independent original eight-byte-nonce ChaCha/Poly1305 known answers.
897        // This tests the primitive only, not a relay envelope or key lifecycle.
898        let vectors = [
899            (
900                "43b718d5a398bf36a5f3904a469febac12f7b5b22efa1ae5cc5deb54e75f5574",
901                "f06be3d7749e299c",
902                "",
903                "a02210edb5c4fd736d7366ae81089103",
904            ),
905            (
906                "9456a10f0c4b0644e9524fedcc329f052c443f55df5d911f4c172e07121e3740",
907                "beb908121cb81960",
908                "67736a080137aef7b92f53145b6ec56622",
909                "4576fc20a665cd99f668062c319677cd82a2bbd02898dbd27db411e002570cf3d5",
910            ),
911            (
912                "4b0fdc9081934247c7e945a10ca2ef52989dad5a2477fe041a6780e06d9254ed",
913                "948fb8afa967f654",
914                "1169e988a0972d513ca73734aad2e21f053d292b78d3eb9d3a6486da320d3e9bc67871bb80fdceb0f18b197aa8862b69b2b83993bab8bff256ff7c87ff9a486beb",
915                "ff673095b4835ccdbbd73719c1351799309fca1063534ccd3fb8a5a5b4492b282ef72fa53cb0af85ed86900773e081dcd78ae54215970a122fef411d62561ad3dd67a359f949c8d666c180287b67f297d3",
916            ),
917        ];
918        for (key_hex, nonce_hex, plaintext_hex, expected_hex) in vectors {
919            let key = hex::decode(key_hex).unwrap().try_into().unwrap();
920            let nonce = hex::decode(nonce_hex).unwrap().try_into().unwrap();
921            let plaintext = hex::decode(plaintext_hex).unwrap();
922            let expected = hex::decode(expected_hex).unwrap();
923            assert_eq!(seal_original(&key, nonce, &plaintext).unwrap(), expected);
924            assert_eq!(&*open_original(&key, nonce, &expected).unwrap(), &plaintext);
925        }
926    }
927    #[test]
928    fn literal_primary_layout_and_extent() {
929        let single = ordinary95_single(3, 1, 320, &[1, 2]).unwrap();
930        assert_eq!(
931            single,
932            [1, 3, 0, 0, 0x95, 0x74, 0, 1, 0, 0, 1, 64, 1, 2, 0, 1, 2]
933        );
934        assert_eq!(
935            parse_ordinary95(&single).unwrap().primaries,
936            vec![&[1, 2][..]]
937        );
938        let raw = ordinary95_pair(3, 1, 320, &[1, 2], &[3]).unwrap();
939        assert_eq!(
940            &raw[..17],
941            &[1, 3, 0, 0, 0x95, 0x74, 0, 1, 0, 0, 1, 64, 2, 2, 0, 1, 0]
942        );
943        let decoded = parse_ordinary95(&raw).unwrap();
944        assert_eq!(decoded.primaries, vec![&[1, 2][..], &[3][..]]);
945        let mut trailing = raw;
946        trailing.push(0);
947        assert!(parse_ordinary95(&trailing).is_err());
948    }
949    #[test]
950    fn unauthorized_sender_fails_and_authenticated_receiver_rejects_replay() {
951        let raw = ordinary95_pair(0, 1, 320, &[1], &[2]).unwrap();
952        let mut receiver = receiver();
953        assert!(receiver.seal_audio(epoch(), 0, &raw).is_err());
954        let mut peer = peer();
955        let packet = peer.seal_audio(epoch(), 0, &raw).unwrap();
956        assert_eq!(&packet[..2], &[0x96, 19]);
957        let clear = receiver.open(epoch(), &packet).unwrap().unwrap();
958        assert_eq!(clear.payload(), raw);
959        assert!(receiver.open(epoch(), &packet).unwrap().is_none());
960        let mut corrupt = packet;
961        *corrupt.last_mut().unwrap() ^= 1;
962        assert!(receiver.open(epoch(), &corrupt).is_err());
963    }
964    #[test]
965    fn clear_header_member_cannot_replace_protected_member() {
966        let raw = ordinary95_pair(0, 1, 320, &[1], &[2]).unwrap();
967        let mut peer = peer();
968        let mut packet = peer.seal_audio(epoch(), 0, &raw).unwrap();
969        packet[10..12].copy_from_slice(&2u16.to_le_bytes());
970        assert!(receiver().open(epoch(), &packet).is_err());
971    }
972    #[test]
973    fn strict_scope_rejects_overlap_and_isolated_scope_expires() {
974        let raw = ordinary95_pair(0, 1, 320, &[1], &[2]).unwrap();
975        let mut peer = peer();
976        let packet = peer.seal_audio(epoch(), 0, &raw).unwrap();
977        let mut receiver = receiver();
978        receiver.open(epoch(), &packet).unwrap();
979        receiver
980            .authorize_transmit(
981                epoch(),
982                TransmitScope::VerifiedGeneration { key_generation: 1 },
983            )
984            .unwrap();
985        assert!(receiver.seal_audio(epoch(), 0, &raw).is_err());
986        // The same collision fails closed when local transmission happens first.
987        let mut sender_first = self::receiver();
988        sender_first
989            .authorize_transmit(
990                epoch(),
991                TransmitScope::VerifiedGeneration { key_generation: 1 },
992            )
993            .unwrap();
994        sender_first.seal_audio(epoch(), 0, &raw).unwrap();
995        assert!(sender_first.open(epoch(), &packet).is_err());
996        assert!(sender_first.seal_audio(epoch(), 1, &raw).is_err());
997        let mut diagnostic = self::receiver();
998        diagnostic
999            .authorize_transmit(
1000                epoch(),
1001                TransmitScope::IsolatedCompatibilityTest {
1002                    intent_id: [1; 32],
1003                    deadline_ms: 100,
1004                    allow_known_audio_overlap: true,
1005                },
1006            )
1007            .unwrap();
1008        diagnostic.open(epoch(), &packet).unwrap();
1009        assert!(diagnostic.seal_audio(epoch(), 1, &raw).is_ok());
1010        assert_eq!(diagnostic.known_audio_overlaps(), 1);
1011        assert!(diagnostic.seal_audio(epoch(), 100, &raw).is_err());
1012    }
1013    #[test]
1014    fn authenticated_controls_preserve_nonce_fence_and_ignore_unhandled_messages() {
1015        let mut other_peer = peer();
1016        let other = other_peer.seal(epoch(), 0, 0x70, &[8, 7]).unwrap();
1017        let mut other_receiver = receiver();
1018        let opened = other_receiver.open(epoch(), &other).unwrap().unwrap();
1019        assert!(other_receiver
1020            .reply_to_probe(epoch(), 0, &opened)
1021            .unwrap()
1022            .is_none());
1023        assert!(other_receiver.check(epoch()).is_ok());
1024
1025        let mut peer = peer();
1026        let request = peer.seal(epoch(), 0, 0x70, &[8, 1, 18, 2, 8, 1]).unwrap();
1027        let mut receiver = receiver();
1028        let opened = receiver.open(epoch(), &request).unwrap().unwrap();
1029        receiver
1030            .authorize_transmit(
1031                epoch(),
1032                TransmitScope::VerifiedGeneration { key_generation: 1 },
1033            )
1034            .unwrap();
1035        assert!(receiver
1036            .reply_to_probe(epoch(), 0, &opened)
1037            .unwrap()
1038            .is_none());
1039        assert!(receiver.check(epoch()).is_ok());
1040        // Omitting a reply does not disable the underlying reuse fence.
1041        assert!(receiver
1042            .seal(epoch(), 0, 0x70, &[8, 1, 18, 2, 8, 2])
1043            .is_err());
1044    }
1045}