Merge pull request #46 from auths-dev/feature/fn-43-sas-verification

feat: verification via SAS and transport encryption for device pairing

Author: bordumb

.github/workflows/docs.yml

@@ -23,11 +23,13 @@ permissions:
   contents: write
 
 jobs:
-  check-cli-docs:
-    name: CLI docs up to date
+  deploy:
+    name: Deploy docs
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for git-revision-date
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
@@ -42,17 +44,8 @@ jobs:
           key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: ${{ runner.os }}-cargo-
 
-      - name: Check CLI docs are up to date
-        run: cargo run -p xtask -- gen-docs --check
-
-  deploy:
-    name: Deploy docs
-    needs: check-cli-docs
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # full history for git-revision-date
+      - name: Regenerate CLI docs
+        run: cargo run -p xtask -- gen-docs
 
       - uses: actions/setup-python@v5
         with:

Cargo.lock

@@ -38,6 +38,7 @@ auths-policy.workspace = true
 auths-index.workspace = true
 auths-crypto.workspace = true
 auths-sdk.workspace = true
+auths-pairing-protocol.workspace = true
 auths-telemetry.workspace = true
 auths-verifier = { workspace = true, features = ["native"] }
 auths-infra-git.workspace = true

crates/auths-cli/Cargo.toml

@@ -72,6 +72,58 @@ pub(crate) fn print_completion(device_name: Option<&str>, device_did: &str) {
     println!();
 }
 
+/// Display SAS and prompt for explicit Y/N confirmation (no default).
+///
+/// Returns `true` if the user confirms the SAS matches, `false` on rejection.
+pub(crate) fn prompt_sas_confirmation(sas_bytes: &[u8; 8]) -> Result<bool> {
+    use auths_pairing_protocol::sas;
+
+    println!();
+    println!("{}", style(format!("━━━ {LOCK}Verify Pairing ━━━")).bold());
+    println!();
+    println!("  Confirm this code matches your other device:");
+    println!();
+    println!("    {}", style(sas::format_sas_emoji(sas_bytes)).bold());
+    println!(
+        "    {}",
+        style(format!("({})", sas::format_sas_numeric(sas_bytes))).dim()
+    );
+    println!();
+    println!(
+        "  {}",
+        style("If the codes don't match, someone may be intercepting this connection.").dim()
+    );
+    println!();
+
+    let confirmed = dialoguer::Confirm::new()
+        .with_prompt("Do the codes match? [y/N]")
+        .default(false)
+        .interact()
+        .context("Failed to read confirmation")?;
+
+    Ok(confirmed)
+}
+
+/// Display a warning when SAS verification fails.
+pub(crate) fn display_sas_mismatch_warning() {
+    println!();
+    println!(
+        "  {}{}",
+        WARN,
+        style("PAIRING ABORTED — possible interception detected")
+            .red()
+            .bold()
+    );
+    println!();
+    println!("  The verification codes did not match. This could mean:");
+    println!("    • An attacker is intercepting the connection (MITM)");
+    println!("    • A network issue corrupted the key exchange");
+    println!();
+    println!("  Retry on a trusted network. If this persists, do not pair these devices.");
+    println!("  No keys or attestations were created.");
+    println!();
+}
+
 /// Handle a successful pairing response — verify signature, complete ECDH, create attestation.
 pub(crate) fn handle_pairing_response(
     session: &mut PairingSession,
@@ -137,11 +189,37 @@ pub(crate) fn handle_pairing_response(
 
     // Complete ECDH key exchange
     let exchange_spinner = create_wait_spinner(&format!("{GEAR}Completing key exchange..."));
-    let _shared_secret = session
+    let initiator_x25519_pub = session
+        .ephemeral_pubkey_bytes()
+        .context("Failed to get initiator pubkey")?;
+    let shared_secret = session
         .complete_exchange(&device_x25519_bytes)
         .context("ECDH key exchange failed")?;
     exchange_spinner.finish_with_message(format!("{CHECK}Key exchange complete"));
 
+    // Derive SAS with transcript binding
+    let short_code = &session.token.short_code;
+    let sas_bytes = auths_pairing_protocol::sas::derive_sas(
+        &shared_secret,
+        &initiator_x25519_pub,
+        &device_x25519_bytes,
+        short_code,
+    );
+    let transport_key = auths_pairing_protocol::sas::derive_transport_key(
+        &shared_secret,
+        &initiator_x25519_pub,
+        &device_x25519_bytes,
+        short_code,
+    );
+
+    // SAS verification ceremony
+    let confirmed = prompt_sas_confirmation(&sas_bytes)?;
+    if !confirmed {
+        display_sas_mismatch_warning();
+        drop(transport_key);
+        anyhow::bail!("SAS verification failed — pairing aborted");
+    }
+
     if !auths_dir.exists() {
         println!();
         println!(

crates/auths-cli/src/commands/device/pair/common.rs

@@ -2,10 +2,12 @@
 
 use anyhow::{Context, Result};
 use auths_core::config::EnvironmentConfig;
+use auths_core::pairing::types::Base64UrlEncoded;
+use auths_core::pairing::{PairingResponse, PairingToken};
+use auths_core::ports::pairing::PairingRelayClient;
 use auths_infra_http::HttpPairingRelayClient;
-use auths_sdk::pairing::{
-    PairingCompletionResult, join_pairing_session, load_device_signing_material,
-};
+use auths_pairing_protocol::sas;
+use auths_sdk::pairing::{load_device_signing_material, validate_short_code};
 use chrono::Utc;
 use console::style;
 
@@ -20,8 +22,7 @@ pub(crate) async fn handle_join(
     registry: &str,
     env_config: &EnvironmentConfig,
 ) -> Result<()> {
-    let normalized =
-        auths_sdk::pairing::validate_short_code(code).map_err(|e| anyhow::anyhow!("{}", e))?;
+    let normalized = validate_short_code(code).map_err(|e| anyhow::anyhow!("{}", e))?;
 
     let formatted = format!("{}-{}", &normalized[..3], &normalized[3..]);
 
@@ -67,42 +68,148 @@ pub(crate) async fn handle_join(
     );
     println!();
 
-    let create_spinner = create_wait_spinner(&format!("{GEAR}Creating and submitting response..."));
+    // Look up the session by short code
+    let session_data = relay
+        .lookup_by_code(registry, &normalized)
+        .await
+        .map_err(|e| anyhow::anyhow!("Failed to look up session: {}", e))?;
+
+    let token_data = session_data
+        .token
+        .ok_or_else(|| anyhow::anyhow!("session has no token data"))?;
+
+    let token = PairingToken {
+        controller_did: token_data.controller_did.clone(),
+        endpoint: registry.to_string(),
+        short_code: normalized.clone(),
+        ephemeral_pubkey: token_data.ephemeral_pubkey.to_string(),
+        expires_at: chrono::DateTime::from_timestamp(token_data.expires_at, 0)
+            .unwrap_or_else(Utc::now),
+        capabilities: token_data.capabilities.clone(),
+    };
+
+    if token.is_expired(Utc::now()) {
+        anyhow::bail!("Session expired");
+    }
+
+    let create_spinner = create_wait_spinner(&format!("{GEAR}Creating pairing response..."));
 
-    match join_pairing_session(
-        code,
-        registry,
-        &relay,
+    // Create the response + ECDH
+    let (pairing_response, shared_secret) = PairingResponse::create(
         Utc::now(),
-        &material,
+        &token,
+        &material.seed,
+        &material.public_key,
+        material.device_did.to_string(),
         Some(hostname()),
     )
-    .await
-    .map_err(|e| anyhow::anyhow!("{}", e))?
-    {
-        PairingCompletionResult::Success { .. } => {
-            create_spinner.finish_with_message(format!("{CHECK}Response submitted"));
-        }
-        PairingCompletionResult::Fallback { error, .. } => {
-            create_spinner.finish_and_clear();
-            anyhow::bail!("Failed to submit pairing response: {}", error);
-        }
+    .map_err(|e| anyhow::anyhow!("Failed to create pairing response: {}", e))?;
+
+    // Derive SAS from shared secret with transcript binding
+    let initiator_x25519_pub = token
+        .ephemeral_pubkey_bytes()
+        .map_err(|e| anyhow::anyhow!("Invalid initiator pubkey: {}", e))?;
+    let responder_x25519_pub = pairing_response
+        .device_x25519_pubkey_bytes()
+        .map_err(|e| anyhow::anyhow!("Invalid responder pubkey: {}", e))?;
+
+    let sas_bytes = sas::derive_sas(
+        &shared_secret,
+        &initiator_x25519_pub,
+        &responder_x25519_pub,
+        &normalized,
+    );
+    let transport_key = sas::derive_transport_key(
+        &shared_secret,
+        &initiator_x25519_pub,
+        &responder_x25519_pub,
+        &normalized,
+    );
+
+    // Submit the response to the relay
+    let submit_req = auths_core::pairing::types::SubmitResponseRequest {
+        device_x25519_pubkey: Base64UrlEncoded::from_raw(
+            pairing_response.device_x25519_pubkey.clone(),
+        ),
+        device_signing_pubkey: Base64UrlEncoded::from_raw(
+            pairing_response.device_signing_pubkey.clone(),
+        ),
+        device_did: pairing_response.device_did.clone(),
+        signature: Base64UrlEncoded::from_raw(pairing_response.signature.clone()),
+        device_name: pairing_response.device_name.clone(),
+    };
+
+    relay
+        .submit_response(registry, &session_data.session_id, &submit_req)
+        .await
+        .map_err(|e| anyhow::anyhow!("Failed to submit response: {}", e))?;
+
+    create_spinner.finish_with_message(format!("{CHECK}Response submitted"));
+
+    // SAS verification ceremony
+    let confirmed = prompt_sas_confirmation(&sas_bytes)?;
+    if !confirmed {
+        display_sas_mismatch_warning();
+        drop(transport_key);
+        anyhow::bail!("SAS verification failed — pairing aborted");
+    }
+
+    // Wait for encrypted attestation from initiator
+    let wait_spinner = create_wait_spinner(&format!(
+        "{GEAR}Waiting for initiator to confirm and send attestation..."
+    ));
+
+    let confirmation = relay
+        .get_confirmation(registry, &session_data.session_id)
+        .await
+        .map_err(|e| anyhow::anyhow!("Failed to get confirmation: {}", e))?;
+
+    if confirmation.aborted {
+        wait_spinner.finish_and_clear();
+        println!();
+        println!(
+            "  {}{}",
+            WARN,
+            style("The other device rejected the pairing.").red().bold()
+        );
+        println!("  {}", style("No attestation was created.").dim());
+        println!();
+        drop(transport_key);
+        anyhow::bail!("Initiator rejected SAS — pairing aborted");
+    }
+
+    if let Some(encrypted) = confirmation.encrypted_attestation {
+        let ciphertext = base64::Engine::decode(
+            &base64::engine::general_purpose::URL_SAFE_NO_PAD,
+            &encrypted,
+        )
+        .context("Invalid base64 in encrypted attestation")?;
+
+        let _attestation_json = sas::decrypt_from_transport(&ciphertext, transport_key.as_bytes())
+            .map_err(|e| anyhow::anyhow!("Failed to decrypt attestation: {}", e))?;
+
+        wait_spinner.finish_with_message(format!("{CHECK}Attestation received and decrypted"));
+
+        // TODO(fn-43.6): verify and store attestation locally
+    } else {
+        wait_spinner.finish_and_clear();
+        println!();
+        println!(
+            "  {}{}",
+            WARN,
+            style("No attestation received from initiator.").yellow()
+        );
+        println!();
     }
 
     println!();
     println!(
         "{}",
-        style(format!("━━━ {CHECK}Response Submitted ━━━"))
+        style(format!("━━━ {CHECK}Pairing Complete ━━━"))
             .green()
             .bold()
     );
     println!();
-    println!(
-        "  {}",
-        style("The initiating device will verify the response and create").dim()
-    );
-    println!("  {}", style("a device attestation for this device.").dim());
-    println!();
 
     Ok(())
 }