diff --git a/tests/pairing.rs b/tests/pairing.rs index e45ebf8..3eab488 100644 --- a/tests/pairing.rs +++ b/tests/pairing.rs @@ -25,63 +25,71 @@ 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). -/// +/// This test describes the secure pairing process between two devices, Alice and Bob. +/// +/// ## What's pairing? +/// Pairing is a process, and abide by the same rules than any other process. The goal of pairing +/// is to define an identity on the network as a set of devices (defined by their sp_address). +/// Being a process it is public and can be audited by anyone, and be used as one's proof of identity. +/// It also contains a session keypair that is updated as necessary. Since all devices are needed to +/// update the key in the process it can then be used to sign a proof that someone was indeed in control +/// of all the devices for some amount of time in a MFA setup. +/// It contains the following mandatory fields: +/// * `roles`: multiple devices represented as sp adresses linked together in the same member. It is recommended +/// to have one `owner` role with one member which is the actual identity and whose signatures are all +/// needed to modify anything in the process. +/// * `session_privkey`: a private key visible by all devices of the member defined in the process, but +/// not by other members. It *must* be changed at every update of the process. This key will be used +/// to sign documents and validate actions for other processes. It's valid as soon as the commitment +/// transaction for the process udpate is seen and it stays valid for _n_ blocks after the update being mined. +/// * `session_pubkey`: the x-only public key derived from the session private key. It's visible by everyone and +/// used for validation by any third party. Obviously it changes with the private key at any update. +/// * `parity`: the parity of the session_pubkey. We could use 33 bytes compressed public key format +/// but using 32 bytes publick key + parity allows for more standard serialization. +/// +/// ## Detailed protocol +/// (Here Alice and Bob are used as a convention, but keep in mind they're not 2 different users, but +/// 2 devices belonging to the same user) +/// ## Step 0 - Preliminary step +/// 1. **Establishing a Shared Secret**: A shared secret is established to secure +/// communication between Alice and Bob (see `connect.rs`). /// ## 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 +/// 1. **Pairing Status Check**: Alice verifies that it's not already paired. +/// 2. **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. +/// 3. **Creation of the pairing process**: Alice initializes pairing by creating a prd update that contains +/// both its address and Bob's, and send it 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`. +/// 2. **Updating Process State**: Bob identifies the new process and store it, but it doesn't have access +/// to the actual data for now. /// 3. **Creating and Sending `Prd Confirm`**: Bob creates a confirmation `prd`, which he then -/// sends to Alice to proceed with the pairing. +/// sends to Alice to get the pcd containing the state for this new process. /// -/// ## Step 3 - Confirmation of `Prd Confirm` by Alice +/// ## Step 3 - Alice gets confirmation and answers with a pcd /// 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. -/// +/// 2. **Sending PCD**: Alice having confirmation that Bob got the update proposal, +/// it now sends the actual data in a pcd. +/// 3. **User confirmation**: At this step we must get the approval of the user. If user confirms +/// the pairing we create a prd response with a valid signature from Alice spend key and send +/// it to Bob. +/// /// ## 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. +/// 1. **Receiving and Verifying `pcd`**: Bob received the `pcd` and only now can tell what's the +/// process was about. /// 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`. +/// request, in this case, the pairing. User is prompted for validation, and if confirmed a prd response +/// is created and sent(see the **User confirmation** step for Alice). /// -/// ## 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`. +/// ## Commiting the process state +/// 1. **Creating the `commit_msg`**: The first device that got both validations creates the commit_msg that +/// contains a transaction paying a relay to generate the first outpoint to commit the state of the process, +/// the hash of the encrypted state of the process (relay must have access to roles though, either it is clear +/// all along or it was provided with the encryption keys) and the proofs that all devices validated this state. +/// 2. **Actual commitment**: As soon as the relay validated the proofs it spends the outpoint and puts the hash of +/// the whole prd response (including pcd hash and all the proofs) in an OP_RETURN output. The process is now +/// public and can be used to prove identity for other processes. #[wasm_bindgen_test] fn test_pairing() {