xmtp_mls_common: add invite::encrypted_group_info + XMTP_EXTERNAL_INVITE_LABEL

[tylerhawkes]

Summary

Adds the encryption envelope for the QR-invite flow (XIP-82), layered on the payload_encryption primitives:

• xmtp_mls_common::invite::encrypted_group_info — wrap_group_info / unwrap_group_info around EncryptedGroupInfoBlobV1 using ChaCha20Poly1305, with the v1 AAD pinned by the XIP: epoch || expires_at_ns (8-byte BE each) || group_state_hash.digest. All plaintext metadata is authenticated — a keyless writer cannot doctor a captured blob (e.g. reset its expiry to "never"); tampering any envelope field fails the unwrap. Dedicated tests tamper each field individually.
• Typed GroupStateHash with the digest length enforced to the ciphersuite hash length (32 bytes) at both wrap and unwrap (GROUP_STATE_HASH_LEN).
• effective_expires_at_ns — the blob's single expiry field carries the earlier of the policy's campaign expiry and the staleness deadline (epoch_start + expire_in_ns, saturating; 0 = no bound drops out). The joiner's one expiry check then also skips candidates validators would reject as stale (no "zombie joins" — a joiner believing it joined a group whose every member rejected the commit), and service TTL-GC naturally collects staleness-dead blobs.
• wrap_group_info generates a fresh CSPRNG nonce per call by default (many independent writers encrypt under the same long-lived key, so deterministic nonce schemes would collide across writers); .nonce(...) override for tests.
• unwrap_group_info verifies envelope version, nonce length, digest presence + length, and (when now_ns is supplied) expiry — all before decryption.
• Adds XMTP_EXTERNAL_INVITE_LABEL to xmtp_configuration::common::mls (used by the create-invite path).

Candidate-set selection across the versioned slot (validate-and-select, highest-epoch, deterministic fork order) lands with the join flow (L-11), where GroupInfo parsing lives.

Stack

• Base: tyler/qr-invite-l4b-proto-rebump (xmtp_proto: bump to xmtp/proto XIP-82 revisions (typed invite primitives) + adapt invite::payload #3751 — xmtp_proto bump to feat: XIP-82 review revisions — typed invite primitives, max_uses, refresh_pointers, AAD + effective expiry, admitted_via tag proto#336 + typed invite::payload).

Test plan

• 17 tests: round-trip (default + explicit nonce), version reject, nonce-length reject (short + long), wrong-key fails AEAD, tampered ciphertext / epoch / digest / expiry each fail AEAD, fresh nonces differ, expiry semantics (boundary, zero-means-never, None bypass), digest-length enforcement at wrap and unwrap, effective-expiry math (bounds dropout, min in both orders, saturation).
• cargo check --locked, just lint-rust clean; cargo nextest -p xmtp_mls_common 824 passed.

🤖 Generated with Claude Code

Note

Add invite::encrypted_group_info and AAD support to wrap_payload_symmetric

• Adds a new encrypted_group_info module to xmtp_mls_common with wrap_group_info and unwrap_group_info functions that produce/consume an EncryptedGroupInfoBlob V1 envelope using ChaCha20Poly1305 AEAD, binding epoch, expiry, and group state hash as AAD.
• Adds XMTP_EXTERNAL_INVITE_LABEL constant to xmtp_configuration as an HPKE domain-separation label for external-invite GroupInfo payloads.
• Converts wrap_payload_symmetric and unwrap_payload_symmetric in payload_encryption.rs to a #[bon::builder] API with an optional aad parameter; existing callers in mls_sync.rs and decrypted_welcome.rs are updated to use the new builder style.
• Behavioral Change: wrap_payload_symmetric and unwrap_payload_symmetric now accept AAD; omitting aad preserves prior behavior (empty slice).

^{Macroscope summarized ea93854.}

[claude]

Claude finished @tylerhawkes's task —— View job

---

Code Review Complete

Review Date: June 11, 2026, 05:10 UTC

Summary

This PR adds well-structured encryption/decryption helpers for the QR-invite flow with strong cryptographic foundations. The implementation is thorough with comprehensive test coverage. However, there is one unresolved security issue that should be addressed before merge (already flagged by Macroscope).

---

⚠️ Critical Issue (Already Flagged)

Pre-authentication expiry check in encrypted_group_info.rs:247-255

The expiry validation occurs before AEAD authentication, allowing an attacker to manipulate the expires_at_ns field to cause premature rejection of valid invites. While the AAD binding prevents silent acceptance of tampered expiry values, the early check creates an unauthenticated denial-of-service vector.

Impact: An attacker can intercept a valid encrypted blob and modify expires_at_ns to any past timestamp, causing the joiner to reject it with Expired rather than Unwrap. This defeats the integrity protection of the AAD binding for the expiry field specifically.

Recommendation: Move the expiry check to after successful AEAD decryption (after line 264). This ensures all envelope fields are integrity-verified before any semantic validation.

---

🟢 Strengths

1. Strong cryptographic design: AAD binding of all cleartext metadata (epoch, expires_at_ns, group_state_hash) prevents tampering attacks. The test suite validates this thoroughly with dedicated tamper tests for each field.

2. Excellent test coverage: 17 tests covering round-trips, nonce freshness, version/length validation, wrong-key failures, tampering detection, expiry semantics, and edge cases. Test quality is high.

3. Good separation of concerns: The builder pattern for wrap_group_info/unwrap_group_info makes parameter misuse difficult (all byte slices are named at call sites). The effective_expires_at_ns helper cleanly encapsulates policy merging logic.

4. Clear documentation: Inline comments explain the cryptographic requirements (nonce uniqueness, AAD purpose) and design decisions (why staleness deadline is folded into expires_at_ns).

5. Type safety: GROUP_STATE_HASH_LEN enforcement at both wrap and unwrap sides prevents length confusion. The EncryptedGroupInfoError variants are specific and actionable.

---

💡 Minor Observations

1. payload_encryption.rs changes look good: The conversion to builder-style API with optional AAD is a clean refactoring. All existing callers are correctly updated to the new builder syntax. The tests demonstrate both with-AAD and without-AAD paths work correctly.

2. XMTP_EXTERNAL_INVITE_LABEL is well-documented: The comment explains why it's distinct from WELCOME_HPKE_LABEL (cross-protocol oracle prevention) and notes it's reserved for future HPKE use even though v1 uses symmetric AEAD only.

3. No performance concerns: ChaCha20Poly1305 is appropriate for this use case. Nonce generation via CSPRNG is acceptable given the security model (many writers sharing a long-lived key).

---

✅ Test Coverage Assessment

The test suite is comprehensive and covers all critical paths:

• Nonce handling (default random, explicit override, freshness verification)
• Error conditions (version, lengths, expiry boundary, wrong key, tampering)
• AAD binding (all three fields individually)
• Policy logic (effective_expires_at_ns math including saturation)

No test gaps identified.

---

Recommendation

Request changes to address the pre-authentication expiry check timing issue. Once that's resolved, this is ready to merge.

---

[macroscopeapp]

Approvability

Verdict: Needs human review

New cryptographic encryption/decryption helpers for the QR-invite flow with ~580 lines of new code. Unresolved review comments identify a potential security issue where expiry checks occur before AEAD authentication. New security-relevant features warrant human review.

No code changes detected at ea93854. Prior analysis still applies.

^{You can customize Macroscope's approvability policy. Learn more.}

[codecov]

Codecov Report

❌ Patch coverage is 99.04077% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.54%. Comparing base (bd245bf) to head (d58d4c3).

Files with missing lines	Patch %	Lines
...xmtp_mls_common/src/invite/encrypted_group_info.rs	98.70%	4 Missing ⚠️

Additional details and impacted files

@@                         Coverage Diff                          @@
##           tyler/qr-invite-l4b-proto-rebump    #3671      +/-   ##
====================================================================
+ Coverage                             84.45%   84.54%   +0.09%     
====================================================================
  Files                                   408      409       +1     
  Lines                                 59869    60248     +379     
====================================================================
+ Hits                                  50561    50938     +377     
- Misses                                 9308     9310       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Dismissing prior approval to re-evaluate d8d71d5

Dismissing prior approval to re-evaluate e369a4e

Dismissing prior approval to re-evaluate e369a4e

[macroscopeapp]

🟢 Low invite/encrypted_group_info.rs:155

unwrap_group_info checks v1.expires_at_ns against now_ns at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify expires_at_ns to any nonzero past timestamp and cause the function to return EncryptedGroupInfoError::Expired instead of EncryptedGroupInfoError::Unwrap. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the expires_at_ns value is integrity-protected by the AAD.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @crates/xmtp_mls_common/src/invite/encrypted_group_info.rs around line 155:

`unwrap_group_info` checks `v1.expires_at_ns` against `now_ns` at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify `expires_at_ns` to any nonzero past timestamp and cause the function to return `EncryptedGroupInfoError::Expired` instead of `EncryptedGroupInfoError::Unwrap`. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the `expires_at_ns` value is integrity-protected by the AAD.

[macroscopeapp]

🟢 Low invite/encrypted_group_info.rs:155

unwrap_group_info checks v1.expires_at_ns against now_ns at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify expires_at_ns to any nonzero past timestamp and cause the function to return EncryptedGroupInfoError::Expired instead of EncryptedGroupInfoError::Unwrap. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the expires_at_ns value is integrity-protected by the AAD.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @crates/xmtp_mls_common/src/invite/encrypted_group_info.rs around line 155:

`unwrap_group_info` checks `v1.expires_at_ns` against `now_ns` at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify `expires_at_ns` to any nonzero past timestamp and cause the function to return `EncryptedGroupInfoError::Expired` instead of `EncryptedGroupInfoError::Unwrap`. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the `expires_at_ns` value is integrity-protected by the AAD.

[macroscopeapp]

🟢 Low invite/encrypted_group_info.rs:155

unwrap_group_info checks v1.expires_at_ns against now_ns at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify expires_at_ns to any nonzero past timestamp and cause the function to return EncryptedGroupInfoError::Expired instead of EncryptedGroupInfoError::Unwrap. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the expires_at_ns value is integrity-protected by the AAD.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @crates/xmtp_mls_common/src/invite/encrypted_group_info.rs around line 155:

`unwrap_group_info` checks `v1.expires_at_ns` against `now_ns` at line 167–174 before the AEAD unwrap at line 178–184. Because the envelope fields are attacker-controlled until verified, an attacker can modify `expires_at_ns` to any nonzero past timestamp and cause the function to return `EncryptedGroupInfoError::Expired` instead of `EncryptedGroupInfoError::Unwrap`. This allows unauthenticated expiry invalidation of valid invites. The expiry check should occur after successful AEAD authentication so the `expires_at_ns` value is integrity-protected by the AAD.