feat!: Add new major version for qr-link package (#655)

### Notes
We are planning a new roll-out of the session validation flow:
https://www.notion.so/worldcoin/Proposal-Eliminate-Session-Centric-Verification-Flow-2418614bdf8c802893d9c3fe43ebba81.

This PR prepares a new version of qr codes where the orb knows the
version of the QR code

* A description of the new flow is written in lib
* relies on the new orb relay message types specified in
worldcoin/orb-relay-messages#71

Author: danielle-tfh

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "orb-qr-link"
-version = "0.0.5"
+version = "0.1.0"
 description = "Data link between Worldcoin App and Orb through QR-codes"
 authors = ["Valentyn Valiaiev <[email protected]>"]
 publish = false
@@ -23,6 +23,11 @@ serde = { version = "1.0.188", features = ["derive"] }
 thiserror = "1.0.57"
 uuid = { version = "1.4.1", features = ["v4"] }
 
+[dependencies.orb-relay-messages]
+features = ["client"]
+git = "https://github.com/worldcoin/orb-relay-messages.git"
+rev = "2c2a97f963b6e3baea794a678f0450428876ec02"
+
 [[test]]
 name = "verification"
 required-features = ["encode", "decode"]

qr-link/Cargo.toml

@@ -0,0 +1,59 @@
+use blake3::Hasher;
+use orb_relay_messages::common::v1::AppAuthenticatedData;
+
+// Define the constant needed by the implementation
+const PCP_VERSION_DEFAULT: u32 = 2;
+
+/// Extension trait for [`AppAuthenticatedData`] that provides hashing and verification functionality.
+///
+/// This trait adds methods to hash and verify the authenticity of [`AppAuthenticatedData`]
+/// instances using BLAKE3 cryptographic hashing.
+pub trait AppAuthenticatedDataExt {
+    /// Returns `true` if `hash` is a BLAKE3 hash of this [`AppAuthenticatedData`].
+    ///
+    /// This method calculates its own hash of the same length as the input
+    /// `hash` and checks if both hashes are identical.
+    fn verify(&self, hash: impl AsRef<[u8]>) -> bool;
+
+    /// Calculates a BLAKE3 hash of the length `n`.
+    fn hash(&self, n: usize) -> Vec<u8>;
+
+    /// Updates the provided BLAKE3 hasher with all fields of this [`AppAuthenticatedData`].
+    ///
+    /// This method must hash every field in the struct to ensure complete validation.
+    fn hasher_update(&self, hasher: &mut Hasher);
+}
+
+// Implement the trait for AppAuthenticatedData
+impl AppAuthenticatedDataExt for AppAuthenticatedData {
+    fn verify(&self, hash: impl AsRef<[u8]>) -> bool {
+        let external_hash = hash.as_ref();
+        let internal_hash = self.hash(external_hash.len());
+        external_hash == internal_hash
+    }
+
+    fn hash(&self, n: usize) -> Vec<u8> {
+        let mut hasher = Hasher::new();
+        self.hasher_update(&mut hasher);
+        let mut output = vec![0; n];
+        hasher.finalize_xof().fill(&mut output);
+        output
+    }
+
+    fn hasher_update(&self, hasher: &mut Hasher) {
+        let Self {
+            identity_commitment,
+            self_custody_public_key,
+            pcp_version,
+            os_version,
+            os,
+        } = self;
+        hasher.update(identity_commitment.as_bytes());
+        hasher.update(self_custody_public_key.as_bytes());
+        hasher.update(os_version.as_bytes());
+        hasher.update(os.as_bytes());
+        if *pcp_version != PCP_VERSION_DEFAULT {
+            hasher.update(&pcp_version.to_le_bytes());
+        }
+    }
+}

qr-link/src/app_authenticated_data.rs

@@ -2,7 +2,7 @@ use data_encoding::BASE64_NOPAD;
 use thiserror::Error;
 use uuid::Uuid;
 
-/// QR-code decoding error returned by [`decode_qr`].
+/// QR-code decoding error returned by [`decode_qr_with_version`].
 #[derive(Error, Debug)]
 pub enum DecodeError {
     /// Format version is unsupported.
@@ -16,17 +16,27 @@ pub enum DecodeError {
     Base64,
 }
 
-/// Parses `session_id` and `user_data_hash` from a QR-code string.
-pub fn decode_qr(qr: &str) -> Result<(Uuid, Vec<u8>), DecodeError> {
+/// Parses `user_id` and `user_data_hash` from a QR-code string and return the version
+/// different logic on the orb can be done based on the version returned
+pub fn decode_qr_with_version(qr: &str) -> Result<(u8, Uuid, Vec<u8>), DecodeError> {
     let Some(version) = qr.bytes().next() else {
         return Err(DecodeError::Malformed);
     };
     match version {
-        b'3' => decode_v3(qr),
+        b'3' => {
+            let (session_id, user_data_hash) = decode_v3(qr)?;
+            Ok((3, session_id, user_data_hash))
+        }
+        b'4' => {
+            let (orb_relay_id, app_authenticated_data_hash) = decode_v4(qr)?;
+            Ok((4, orb_relay_id, app_authenticated_data_hash))
+        }
         _ => Err(DecodeError::UnsupportedVersion),
     }
 }
 
+// the `decode_v3` method is specifically to decode user sessions where the id is the `session_id` and the hash is the hash from `UserData`
+// can be deprecated once all apps have moved to V3
 fn decode_v3(qr: &str) -> Result<(Uuid, Vec<u8>), DecodeError> {
     let Ok(payload) = BASE64_NOPAD.decode(&qr.as_bytes()[1..]) else {
         return Err(DecodeError::Base64);
@@ -41,3 +51,19 @@ fn decode_v3(qr: &str) -> Result<(Uuid, Vec<u8>), DecodeError> {
     let session_id = Uuid::from_u128(session_id);
     Ok((session_id, user_data_hash.to_vec()))
 }
+
+// the `decode_v4` method is specifically to decode static sessions where the id is the `orb_relay_id` and the hash is the hash from `AppAuthenticatedData`
+fn decode_v4(qr: &str) -> Result<(Uuid, Vec<u8>), DecodeError> {
+    let Ok(payload) = BASE64_NOPAD.decode(&qr.as_bytes()[1..]) else {
+        return Err(DecodeError::Base64);
+    };
+    let Some(orb_relay_id) = payload.get(0..16) else {
+        return Err(DecodeError::Malformed);
+    };
+    let Some(app_authenticated_data_hash) = payload.get(16..) else {
+        return Err(DecodeError::Malformed);
+    };
+    let orb_relay_id = u128::from_be_bytes(orb_relay_id.try_into().unwrap());
+    let orb_relay_id = Uuid::from_u128(orb_relay_id);
+    Ok((orb_relay_id, app_authenticated_data_hash.to_vec()))
+}

qr-link/src/decode.rs

@@ -1,14 +1,16 @@
 use data_encoding::BASE64_NOPAD;
 use uuid::Uuid;
 
-/// QR-code version prefix.
-pub const QR_VERSION: u8 = b'3';
+pub const QR_VERSION: u8 = b'4';
 
-/// Generates a QR-code string from `session_id` and `user_data_hash`.
-pub fn encode_qr(session_id: &Uuid, user_data_hash: impl AsRef<[u8]>) -> String {
+/// Generates a QR-code (V4) string from `orb relay id` and `app_authenticated_data`
+pub fn encode_static_qr(
+    orb_relay_id: &Uuid,
+    authenticated_data_hash: impl AsRef<[u8]>,
+) -> String {
     let mut payload = Vec::new();
-    payload.extend_from_slice(&session_id.as_u128().to_be_bytes());
-    payload.extend_from_slice(user_data_hash.as_ref());
+    payload.extend_from_slice(&orb_relay_id.as_u128().to_be_bytes());
+    payload.extend_from_slice(authenticated_data_hash.as_ref());
 
     let mut qr = String::new();
     qr.push(QR_VERSION.into());

qr-link/src/encode.rs

@@ -10,83 +10,73 @@
 //! backend for performance, and transfer a hash of the data via a QR-code for
 //! security.
 //!
+//! //! The library is shared between Worldcoin App and Orb Core.
 //! # Usage
-//!
-//! The library is shared between Worldcoin App and Orb Core.
-//!
 //! ## Encode (App)
 //!
-//! Worldcoin App uploads user data and generates a QR-code.
+//! Worldcoin App generates a QR-code using the orb relay ID and includes a hash of the app authenticated data that will be sent in the orb relay message.
 //!
 //! ```rust
-//! use orb_qr_link::{encode_qr, DataPolicy, UserData};
+//! use orb_qr_link::{encode_static_qr, AppAuthenticatedDataExt};
+//! use orb_relay_messages::common::v1::AppAuthenticatedData;
 //! use uuid::Uuid;
 //!
 //! // Generate a new session id and user data.
-//! let session_id = Uuid::new_v4();
-//! let sample_jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-//! let user_data = UserData {
-//!     identity_commitment: String::new(),
-//!     self_custody_public_key: String::new(),
-//!     data_policy: DataPolicy::OptOut,
-//!     pcp_version: 2,
-//!     user_centric_signup: true,
-//!     orb_relay_app_id: Some("123123".to_string()),
-//!     bypass_age_verification_token: Some(sample_jwt_token.to_string()),
+//! let orb_relay_id = Uuid::new_v4();
+//! let app_data = AppAuthenticatedData {
+//!    identity_commitment: identity_commitment.to_string(),
+//!    self_custody_public_key: self_custody_public_key.to_string(),
+//!    pcp_version: 3,
+//!    os: "Android".to_string(),
+//!    os_version: "1.2.3".to_string(),
 //! };
 //!
-//! // Upload `user_data` to the backend by the `session_id` key.
-//! // ...
-//!
-//! // Calculate a variable-length hash of `user_data`.
-//! let user_data_hash = user_data.hash(16);
+//! // Calculate a variable-length hash of `app_data`.
+//! let app_data_hash = app_data.hash(16);
 //! // Encode a new QR-code.
-//! let qr = encode_qr(&session_id, user_data_hash);
+//! let qr = encode_static_qr(&orb_relay_id, app_data_hash);
 //!
 //! // Allow the Orb to scan the generated QR-code.
 //! // ...
 //! ```
 //!
 //! ## Decode (Orb)
 //!
-//! The Orb scans a QR-code and downloads the user data.
+//! The Orb scans a QR-code
 //!
 //! ```rust
-//! use orb_qr_link::{decode_qr, DataPolicy, UserData};
+//! use orb_qr_link::{decode_qr_with_version};
 //!
 //! // Scan QR-code generated by the App.
 //! let qr = "3WVd+tbAtSgyH0Ce9uiKT9i063t/xG2HxTIhuNa+gNnM";
 //!
 //! // Decode the QR-code string.
-//! let (session_id, user_data_hash) = decode_qr(qr).unwrap();
-//!
-//! // Download `user_data` from the backend by the `session_id` key.
-//! let user_data = UserData {
-//!     identity_commitment: String::new(),
-//!     self_custody_public_key: String::new(),
-//!     data_policy: DataPolicy::OptOut,
-//!     pcp_version: 2,
-//!     user_centric_signup: true,
-//!     orb_relay_app_id: Some("123123".to_string()),
-//!     bypass_age_verification_token: None,
-//! };
+//! let (version, orb_relay_id, app_data_hash) = decode_qr_with_version(qr).unwrap();
+//!
+//! // connects to the app via orb relay using the orb_relay_id
+//! // if version is V4 then orb can do the logic for static sessions
+//!
+//! // Retrieves the app data from the AnnounceAppId Orb Relay Message
+//! let app_data = orb_relay_announce_id_message.app_authenticated_data;
 //!
-//! // Verify that the `user_data_hash` from the QR-code matches `user_data`
+//! // Verify that the `app_data_hash` from the QR-code matches `app_data`
 //! // from the backend.
-//! let success = user_data.verify(user_data_hash);
+//! let success = app_data.verify(app_data_hash);
 //! ```
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]
 
+mod app_authenticated_data;
 #[cfg(feature = "decode")]
 mod decode;
 #[cfg(feature = "encode")]
 mod encode;
 mod user_data;
 
+pub use app_authenticated_data::AppAuthenticatedDataExt;
 #[cfg(feature = "decode")]
-pub use decode::{decode_qr, DecodeError};
+pub use decode::{decode_qr_with_version, DecodeError};
 #[cfg(feature = "encode")]
-pub use encode::encode_qr;
+pub use encode::encode_static_qr;
 pub use user_data::{DataPolicy, UserData};