xmtp_mls_common: add invite::payload module (ExternalInvitePayload helpers)

Author: tylerhawkes

crates/xmtp_mls_common/src/invite/mod.rs

@@ -0,0 +1,10 @@
+//! External-invite primitives for QR-code-based group joining via MLS external
+//! commits.
+//!
+//! The [`payload`] module provides helpers for the
+//! [`ExternalInvitePayload`] proto. The encryption envelope lives in the
+//! sibling `encrypted_group_info` module (added by a separate PR).
+//!
+//! [`ExternalInvitePayload`]: xmtp_proto::xmtp::mls::message_contents::ExternalInvitePayload
+
+pub mod payload;

crates/xmtp_mls_common/src/invite/payload.rs

@@ -0,0 +1,264 @@
+//! Helpers for the [`ExternalInvitePayload`] proto.
+//!
+//! This module centralises the small but easy-to-get-wrong pieces of building
+//! and validating an external-invite payload:
+//!
+//! * fresh symmetric keys / nonces from the workspace CSPRNG
+//! * the canonical `sha256(group_id)` lookup hash
+//! * version gating against [`CURRENT_PAYLOAD_VERSION`]
+//! * expiry checks with the `0 == never` convention
+//! * a [`build_payload`] convenience constructor
+//!
+//! The actual encryption of the [`GroupInfo`] blob is performed by the
+//! sibling `encrypted_group_info` module (added in a follow-up PR).
+//!
+//! [`ExternalInvitePayload`]: xmtp_proto::xmtp::mls::message_contents::ExternalInvitePayload
+//! [`GroupInfo`]: openmls::messages::group_info::GroupInfo
+
+use thiserror::Error;
+use xmtp_proto::xmtp::mls::message_contents::ExternalInvitePayload;
+
+/// Wire-format version implemented by this module. Payloads with any other
+/// `version` field are rejected by [`validate_version`].
+pub const CURRENT_PAYLOAD_VERSION: u32 = 1;
+
+/// Length in bytes of the ChaCha20Poly1305 key used to wrap the encrypted
+/// `GroupInfo` blob referenced by an [`ExternalInvitePayload`].
+pub const SYMMETRIC_KEY_LEN: usize = 32;
+
+/// Length in bytes of the ChaCha20Poly1305 nonce used alongside
+/// [`SYMMETRIC_KEY_LEN`]-byte keys.
+pub const NONCE_LEN: usize = 12;
+
+/// Errors returned when validating the `version` field of an
+/// [`ExternalInvitePayload`].
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum InviteVersionError {
+    /// The payload advertises a version this build does not understand. The
+    /// `found` value is whatever the wire said; `expected` is
+    /// [`CURRENT_PAYLOAD_VERSION`].
+    #[error("unsupported external-invite payload version: found {found}, expected {expected}")]
+    UnsupportedVersion {
+        /// Version advertised by the payload.
+        found: u32,
+        /// Version this build understands.
+        expected: u32,
+    },
+}
+
+/// Generate a fresh 32-byte symmetric key from the workspace CSPRNG.
+///
+/// The key is intended for use with ChaCha20Poly1305 when wrapping the
+/// encrypted GroupInfo blob referenced by the resulting
+/// [`ExternalInvitePayload`].
+pub fn generate_symmetric_key() -> [u8; SYMMETRIC_KEY_LEN] {
+    xmtp_common::rand_array::<SYMMETRIC_KEY_LEN>()
+}
+
+/// Generate a fresh 12-byte nonce from the workspace CSPRNG.
+///
+/// Intended for use with ChaCha20Poly1305 alongside a key produced by
+/// [`generate_symmetric_key`]. The nonce is *not* stored in the payload
+/// itself — it lives next to the ciphertext in the encrypted GroupInfo blob.
+pub fn generate_nonce() -> [u8; NONCE_LEN] {
+    xmtp_common::rand_array::<NONCE_LEN>()
+}
+
+/// Compute the canonical lookup hash `sha256(group_id)` used as the
+/// `group_id_hash` field of an [`ExternalInvitePayload`].
+///
+/// External invite services key the encrypted GroupInfo blob by this hash so
+/// that callers can fetch the blob without revealing the underlying
+/// `group_id`.
+pub fn compute_group_id_hash(group_id: &[u8]) -> [u8; 32] {
+    xmtp_common::sha256_array(group_id)
+}
+
+/// Returns `true` if `payload` carries a non-zero expiry that is at or before
+/// `now_ns`.
+///
+/// `expires_at_ns == 0` is treated as "no expiry" per the proto contract.
+/// The comparison is `>=`, so `now_ns == expires_at_ns` is considered
+/// expired.
+pub fn is_expired(payload: &ExternalInvitePayload, now_ns: u64) -> bool {
+    payload.expires_at_ns != 0 && now_ns >= payload.expires_at_ns
+}
+
+/// Validate that `payload.version` matches [`CURRENT_PAYLOAD_VERSION`].
+///
+/// Returns [`InviteVersionError::UnsupportedVersion`] for every other value
+/// (including `0`).
+pub fn validate_version(payload: &ExternalInvitePayload) -> Result<(), InviteVersionError> {
+    if payload.version == CURRENT_PAYLOAD_VERSION {
+        Ok(())
+    } else {
+        Err(InviteVersionError::UnsupportedVersion {
+            found: payload.version,
+            expected: CURRENT_PAYLOAD_VERSION,
+        })
+    }
+}
+
+/// Build an [`ExternalInvitePayload`] with `version` set to
+/// [`CURRENT_PAYLOAD_VERSION`] and `group_id_hash` derived via
+/// [`compute_group_id_hash`].
+///
+/// * `service_pointer` — application-defined opaque bytes describing where
+///   the encrypted GroupInfo blob can be fetched.
+/// * `group_id` — the raw MLS group id; hashed in place.
+/// * `symmetric_key` — typically the output of [`generate_symmetric_key`].
+/// * `expires_at_ns` — nanoseconds since the UNIX epoch; `0` means no expiry.
+/// * `ciphersuite` — the MLS ciphersuite identifier of the target group.
+pub fn build_payload(
+    service_pointer: Vec<u8>,
+    group_id: &[u8],
+    symmetric_key: [u8; SYMMETRIC_KEY_LEN],
+    expires_at_ns: u64,
+    ciphersuite: u16,
+) -> ExternalInvitePayload {
+    ExternalInvitePayload {
+        version: CURRENT_PAYLOAD_VERSION,
+        service_pointer,
+        group_id_hash: compute_group_id_hash(group_id).to_vec(),
+        symmetric_key: symmetric_key.to_vec(),
+        expires_at_ns,
+        ciphersuite: ciphersuite as u32,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn group_id_hash_is_sha256() {
+        // Known SHA-256 of the empty string.
+        let empty = compute_group_id_hash(b"");
+        let expected_empty: [u8; 32] = [
+            0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f,
+            0xb9, 0x24, 0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b,
+            0x78, 0x52, 0xb8, 0x55,
+        ];
+        assert_eq!(empty, expected_empty);
+
+        // Known SHA-256 of "abc".
+        let abc = compute_group_id_hash(b"abc");
+        let expected_abc: [u8; 32] = [
+            0xba, 0x78, 0x16, 0xbf, 0x8f, 0x01, 0xcf, 0xea, 0x41, 0x41, 0x40, 0xde, 0x5d, 0xae,
+            0x22, 0x23, 0xb0, 0x03, 0x61, 0xa3, 0x96, 0x17, 0x7a, 0x9c, 0xb4, 0x10, 0xff, 0x61,
+            0xf2, 0x00, 0x15, 0xad,
+        ];
+        assert_eq!(abc, expected_abc);
+
+        // Deterministic for identical inputs.
+        assert_eq!(compute_group_id_hash(b"abc"), compute_group_id_hash(b"abc"));
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn key_and_nonce_are_random() {
+        let k1 = generate_symmetric_key();
+        let k2 = generate_symmetric_key();
+        assert_eq!(k1.len(), SYMMETRIC_KEY_LEN);
+        assert_eq!(k2.len(), SYMMETRIC_KEY_LEN);
+        assert_ne!(k1, k2, "two CSPRNG-generated keys must differ");
+        assert_ne!(k1, [0u8; SYMMETRIC_KEY_LEN], "key must not be all-zero");
+
+        let n1 = generate_nonce();
+        let n2 = generate_nonce();
+        assert_eq!(n1.len(), NONCE_LEN);
+        assert_eq!(n2.len(), NONCE_LEN);
+        assert_ne!(n1, n2, "two CSPRNG-generated nonces must differ");
+        assert_ne!(n1, [0u8; NONCE_LEN], "nonce must not be all-zero");
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn validate_version_accepts_current() {
+        let payload = build_payload(b"svc".to_vec(), b"group-id", [7u8; SYMMETRIC_KEY_LEN], 0, 1);
+        assert_eq!(payload.version, CURRENT_PAYLOAD_VERSION);
+        validate_version(&payload)?;
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn validate_version_rejects_zero_and_future() {
+        let mut payload =
+            build_payload(b"svc".to_vec(), b"group-id", [7u8; SYMMETRIC_KEY_LEN], 0, 1);
+
+        payload.version = 0;
+        assert_eq!(
+            validate_version(&payload),
+            Err(InviteVersionError::UnsupportedVersion {
+                found: 0,
+                expected: CURRENT_PAYLOAD_VERSION,
+            })
+        );
+
+        payload.version = CURRENT_PAYLOAD_VERSION + 1;
+        assert_eq!(
+            validate_version(&payload),
+            Err(InviteVersionError::UnsupportedVersion {
+                found: CURRENT_PAYLOAD_VERSION + 1,
+                expected: CURRENT_PAYLOAD_VERSION,
+            })
+        );
+
+        payload.version = u32::MAX;
+        assert_eq!(
+            validate_version(&payload),
+            Err(InviteVersionError::UnsupportedVersion {
+                found: u32::MAX,
+                expected: CURRENT_PAYLOAD_VERSION,
+            })
+        );
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn is_expired_handles_zero_as_no_expiry() {
+        let payload = build_payload(b"svc".to_vec(), b"group-id", [7u8; SYMMETRIC_KEY_LEN], 0, 1);
+        assert!(!is_expired(&payload, 0));
+        assert!(!is_expired(&payload, u64::MAX));
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn is_expired_strict_inequality() {
+        let payload = build_payload(
+            b"svc".to_vec(),
+            b"group-id",
+            [7u8; SYMMETRIC_KEY_LEN],
+            100,
+            1,
+        );
+        // Before expiry.
+        assert!(!is_expired(&payload, 0));
+        assert!(!is_expired(&payload, 99));
+        // At expiry — treated as expired (>=).
+        assert!(is_expired(&payload, 100));
+        // After expiry.
+        assert!(is_expired(&payload, 101));
+        assert!(is_expired(&payload, u64::MAX));
+    }
+
+    #[xmtp_common::test(unwrap_try = true)]
+    fn build_payload_round_trip() {
+        let group_id = b"some-group-id";
+        let service_pointer = b"https://invites.example/abc".to_vec();
+        let key = [0x42u8; SYMMETRIC_KEY_LEN];
+        let expires = 1_700_000_000_000_000_000u64;
+        let ciphersuite: u16 = 0x0001;
+
+        let payload = build_payload(service_pointer.clone(), group_id, key, expires, ciphersuite);
+
+        assert_eq!(payload.version, CURRENT_PAYLOAD_VERSION);
+        assert_eq!(payload.service_pointer, service_pointer);
+        assert_eq!(
+            payload.group_id_hash,
+            compute_group_id_hash(group_id).to_vec()
+        );
+        assert_eq!(payload.symmetric_key, key.to_vec());
+        assert_eq!(payload.expires_at_ns, expires);
+        assert_eq!(payload.ciphersuite, ciphersuite as u32);
+
+        // The round-tripped payload still passes validation.
+        validate_version(&payload)?;
+        assert!(!is_expired(&payload, 0));
+    }
+}

crates/xmtp_mls_common/src/lib.rs

@@ -3,5 +3,6 @@ pub mod group;
 pub mod group_metadata;
 pub mod group_mutable_metadata;
 pub mod inbox_id;
+pub mod invite;
 pub mod tls_map;
 pub mod tls_set;