From 30d7ddcf1abe940dc50c3beb0e5fb08cd971c594 Mon Sep 17 00:00:00 2001 From: Omar Oughriss Date: Thu, 31 Oct 2024 14:58:30 +0100 Subject: [PATCH] pairing.rs documentation --- tests/pairing.rs | 60 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/tests/pairing.rs b/tests/pairing.rs index 1622b51..e45ebf8 100644 --- a/tests/pairing.rs +++ b/tests/pairing.rs @@ -23,6 +23,66 @@ use utils::*; wasm_bindgen_test_configure!(run_in_browser); +/// # Pairing Process Documentation between Alice and Bob +/// +/// This test describes the secure pairing process between two devices, Alice and Bob, +/// across several steps, utilizing `process_cache` to store and exchange the process state +/// while mutually validating their commitments. Each stage is designed to establish a strong +/// validation between the two devices via secure exchanges of `prd` messages (updates and confirmations). +/// +/// ## Step 1 - Pairing Preparation by Alice +/// 1. **Establishing a Shared Secret**: A shared secret is established via `connect.rs` to secure +/// communication between Alice and Bob. +/// 2. **Pairing Status Check**: Alice verifies that the pairing is not already active. +/// 3. **Adding Bob's Address**: Alice adds Bob’s address to her own, setting the base for creating +/// a new `Member` object. +/// 4. **Initiating Pairing**: Alice initializes pairing using the transaction’s `commitment` and +/// the created member, which contains the list of devices. +/// 5. **Updating `prd`**: Alice creates an update `prd`, stores this new state in +/// `alice_process_cache`, and sends the `prd` to Bob. +/// +/// ## Step 2 - Receiving and Confirming the `prd` by Bob +/// 1. **Receiving and Verifying**: Bob receives and decrypts the update `prd` message sent by Alice. +/// 2. **Updating Process State**: Bob updates his process state using the `prd` data and stores +/// this new state in `bob_process_cache`. +/// 3. **Creating and Sending `Prd Confirm`**: Bob creates a confirmation `prd`, which he then +/// sends to Alice to proceed with the pairing. +/// +/// ## Step 3 - Confirmation of `Prd Confirm` by Alice +/// 1. **Receiving and Verifying**: Alice receives the `Prd Confirm` sent by Bob. +/// 2. **Creating Commitment**: Alice uses the received `prd` to generate a commitment based on the +/// recorded process state. +/// 3. **Proof Generation**: Alice creates a proof using her private spend key and response to the +/// commitment, which is then added to the `prd`. +/// 4. **Updating `process_cache`**: Alice stores the new state in `alice_process_cache`. +/// 5. **Sending `Prd Response`**: Alice creates and sends a `Prd Response` to Bob, including +/// the commitment of the `pcd` which will validate the pairing. +/// +/// ## Step 4 - Finalizing Pairing by Bob +/// 1. **Receiving and Verifying `Prd Response` and `pcd`**: Bob receives Alice’s `Prd Response` +/// and updates `bob_process_cache` with the new state. +/// 2. **Validating Pairing State**: Bob retrieves the latest process state and the state change +/// request, in this case, the pairing. +/// - He validates the current process state. +/// - He decrypts the `pcd` to retrieve the request. +/// 3. **Verifying Roles and Addresses**: Bob extracts the roles associated with the state change, +/// retrieves the addresses of involved members, and displays them to the user to confirm pairing. +/// 4. **Adding Final Proof**: Upon user confirmation, Bob generates and adds his proof to the `prd`, +/// then records the final state in `bob_process_cache`. +/// +/// ## Creation of Pairing Transaction +/// 1. **Creating the `commit_msg`**: A validation message (`commit_msg`) containing proofs from +/// both Alice and Bob is generated. +/// 2. **Creating the Transaction**: A transaction containing the final commitment is created and +/// shared between Alice and Bob. +/// 3. **Device Pairing**: Using the transaction `txid` and the list of member addresses, the +/// pairing is officially initiated, validated by a new `Member` object grouping Alice and Bob’s +/// addresses along with the transaction. +/// +/// ## Final Outcome +/// The pairing is now active between Alice and Bob, ensuring the mutual validation of their +/// respective identities and shared commitment to the validated `prd`. + #[wasm_bindgen_test] fn test_pairing() { setup();