xmtp_mls_common: add invite::encrypted_group_info + XMTP_EXTERNAL_INVITE_LABEL

[tylerhawkes]

Summary

Adds the encryption envelope for the QR-invite flow.

• xmtp_mls_common::invite::encrypted_group_info — wraps/unwraps a TLS-serialized GroupInfo into an EncryptedGroupInfoBlob proto using ChaCha20Poly1305 (via the payload_encryption helpers from PR-L2).
• wrap_group_info generates a fresh nonce per call; wrap_group_info_with_nonce for tests / explicit nonce management.
• unwrap_group_info verifies envelope version + nonce length before decryption.
• Adds XMTP_EXTERNAL_INVITE_LABEL constant to xmtp_configuration::common::mls (passed to wrap_payload_hpke by the create-invite path, not used here directly).

The blob's epoch and group_state_hash fields are populated by the L-10/L-11 callers where the MlsGroup is available — the pure-codec helpers in this PR leave them zero.

Stack

• Base: tyler/qr-invite-l4-invite-payload (xmtp_mls_common: add invite::payload module (ExternalInvitePayload helpers) #3670).
• Also depends on PR-L2 (xmtp_mls_common: relocate + rename welcome_wrapper -> payload_encryption #3669) for mls_ext::payload_encryption. The merge commit in this PR brings L-2 in; once L-2 lands the diff cleans up.

Test plan

• 7 tests: round-trip (default + explicit nonce), version-mismatch reject, nonce-length reject, wrong-key fails AEAD, tampered ciphertext fails AEAD, fresh nonces differ across calls.

Note

Add invite::encrypted_group_info module with wrap_group_info/unwrap_group_info and XMTP_EXTERNAL_INVITE_LABEL

• Adds encrypted_group_info.rs implementing ChaCha20Poly1305 symmetric encryption/decryption for EncryptedGroupInfoBlob::V1, with AAD binding epoch, expiry, and group state hash to authenticate envelope metadata.
• Adds XMTP_EXTERNAL_INVITE_LABEL in mls.rs as a distinct HPKE domain-separation label reserved for external-invite flows.
• Converts wrap_payload_symmetric and unwrap_payload_symmetric in payload_encryption.rs from positional-argument functions to #[bon::builder]-style, adding an optional aad parameter that defaults to empty bytes.
• Behavioral Change: existing callers of wrap_payload_symmetric/unwrap_payload_symmetric must be updated to use builder syntax; AAD defaults to empty preserving prior decryption behavior.

^{Macroscope summarized 54721d0.}

[claude]

Claude finished @tylerhawkes's task —— View job

---

Code Review — June 6, 2026 05:09 UTC

I've reviewed the encryption helpers for the QR-invite flow. The implementation is solid overall, with one outstanding security concern that should be addressed:

Security: Expiry Check Ordering (High Priority)

The existing review comment about expiry-check ordering at encrypted_group_info.rs:165 is valid and should be fixed:

Issue: unwrap_group_info checks expires_at_ns against now_ns (lines 177-184) before AEAD unwrap (lines 187-194). Since expires_at_ns is attacker-controlled until the AEAD verifies it, an attacker can modify this field to cause spurious Expired errors on valid invites.

Impact: Denial-of-service vector — attackers can make valid, non-expired invites appear expired by tampering with expires_at_ns in transit.

Fix: Move the expiry check after line 195 (after successful AEAD unwrap), when v1.expires_at_ns is integrity-protected by the AAD. The check will still prevent using genuinely expired invites, but tampering will correctly surface as Unwrap errors instead of Expired.

Example:

// After line 194, before Ok((plaintext, v1)):
if let Some(now) = now_ns
    && v1.expires_at_ns != 0
    && now >= v1.expires_at_ns
{
    return Err(EncryptedGroupInfoError::Expired {
        expires_at_ns: v1.expires_at_ns,
        now_ns: now,
    });
}

Test gap: The existing expired_blob_rejected_when_now_supplied test doesn't catch this because it only tests legitimate expiry (matching AAD). Add a test that tampers with expires_at_ns on a valid blob and verifies it returns Unwrap (not Expired).

---

Other Observations

Code Quality: ✅ Excellent

• Builder pattern for wrap_group_info is clean and type-safe
• AAD construction (blob_aad) is unambiguous with length-prefixing
• Error types are well-structured and informative
• Comprehensive doc comments with examples

Test Coverage: ✅ Strong (98.76%)

• 7 tests cover: round-trips, version mismatch, nonce validation, wrong keys, ciphertext tampering, AAD tampering (epoch, state hash, expiry)
• Nonce-uniqueness property verified (fresh_nonces_differ)
• Missing: test for the expiry-ordering DoS described above

Performance: ✅ No concerns

• ChaCha20Poly1305 is appropriate for this use case
• Single-pass AAD construction is efficient

Best Practices: ✅ Followed

• AEAD nonce management is correct (fresh per call, overridable for tests)
• Domain separation via AAD (not just ciphertext)
• Zero-copy where practical (&[u8] arguments)

---

Summary

This is high-quality cryptographic code. The only blocker is the expiry-check ordering issue, which is a real security concern (DoS vector) but straightforward to fix. Once that's addressed, this is ready to merge.

Tasks

• Analyze code structure and implementation
• Review security concerns
• Check test coverage and edge cases
• Provide final feedback

---

[macroscopeapp]

Approvability

Verdict: Needs human review

Introduces new cryptographic functionality for encrypted group info with AEAD encryption. Unresolved review comments identify a potential security issue where expiry is checked before AEAD authentication, which warrants human attention.

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

[codecov]

Codecov Report

❌ Patch coverage is 98.81657% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.36%. Comparing base (360a2e8) to head (54721d0).
⚠️ Report is 13 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3671      +/-   ##
==========================================
+ Coverage   84.23%   84.36%   +0.12%     
==========================================
  Files         407      409       +2     
  Lines       59350    59519     +169     
==========================================
+ Hits        49994    50213     +219     
+ Misses       9356     9306      -50     

☔ 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.