Device Pairing

brave lion sunset river eagle mountain forest ocean thunder crystal diamond phoenix

{
  "version": 2,
  "words": "brave lion sunset river eagle mountain forest ocean thunder crystal diamond phoenix",
  "node_id": "6jn4e7l3pzx2kqhv..."
}

pub enum PairingMessage {
    // Joiner → Initiator: "I want to pair"
    PairingRequest {
        session_id: Uuid,
        device_info: DeviceInfo,
        public_key: Vec<u8>,
    },

    // Initiator → Joiner: "Prove you have the code"
    Challenge {
        session_id: Uuid,
        challenge: Vec<u8>,  // 32 random bytes
        device_info: DeviceInfo,
    },

    // Joiner → Initiator: "Here's my signature"
    Response {
        session_id: Uuid,
        response: Vec<u8>,   // 64-byte Ed25519 signature
        device_info: DeviceInfo,
    },

    // Initiator → Joiner: "Pairing complete"
    Complete {
        session_id: Uuid,
        success: bool,
        reason: Option<String>,
    },
}

pub enum PairingState {
    // Initiator states
    WaitingForConnection,    // Code generated, waiting
    ChallengeIssued,        // Sent challenge to joiner

    // Joiner states
    Connecting,             // Looking for initiator
    ChallengeReceived,      // Got challenge, signing

    // Terminal states
    Completed,              // Success!
    Failed(String),         // Something went wrong
}

pub struct PairingSession {
    session_id: Uuid,           // Derived from code
    state: PairingState,        // Current state
    remote_device: Option<DeviceInfo>,
    created_at: SystemTime,
    expires_at: SystemTime,     // 5 minutes later
}

// Initiator broadcasts session_id via user_data
endpoint.set_user_data_for_discovery(Some(session_id));

// Joiner listens for matching session_id
discovery_stream.filter(|item| {
    item.node_info().data.user_data() == session_id
});

// Automatic pkarr publishing (done by Iroh)
.add_discovery(PkarrPublisher::n0_dns())  // Publish to dns.iroh.link
.add_discovery(DnsDiscovery::n0_dns())    // Resolve from dns.iroh.link

// Joiner queries by node_id
let node_addr = NodeAddr::new(node_id);  // Pkarr resolves in background
endpoint.connect(node_addr, PAIRING_ALPN).await?;

tokio::select! {
    result = try_mdns_discovery(session_id) => {
        // Fast path: local network
    }
    result = try_relay_discovery(node_id) => {
        // Reliable path: internet via pkarr
    }
}
// First to succeed wins, other is canceled

// Relay mode configured at startup
.relay_mode(RelayMode::Default)  // Uses n0's production relays

// Automatic relay fallback during connection
endpoint.connect(node_addr, PAIRING_ALPN).await?;  // Tries direct, then relay

// Initiator generates challenge
let challenge = rand::thread_rng().gen::<[u8; 32]>();

// Joiner signs challenge
let signature = signing_key.sign(&challenge);

// Initiator verifies signature
let valid = verifying_key.verify(&challenge, &signature).is_ok();

// Derive shared secret from pairing code
let shared_secret = hkdf::extract(
    &pairing_code.secret,
    &[initiator_id, joiner_id].concat()
);

// Generate session keys
let (tx_key, rx_key) = hkdf::expand(
    &shared_secret,
    b"spacedrive-session-keys",
    64
);

// Automatic publishing (initiator)
let endpoint = Endpoint::builder()
    .add_discovery(PkarrPublisher::n0_dns())  // Publishes to dns.iroh.link
    .bind().await?;

// Automatic resolution (joiner)
let endpoint = Endpoint::builder()
    .add_discovery(DnsDiscovery::n0_dns())    // Resolves from dns.iroh.link
    .bind().await?;

// Discovery happens automatically during connection
endpoint.connect(NodeAddr::new(node_id), PAIRING_ALPN).await?;

pub enum PairingError {
    // User errors
    InvalidCode,            // Wrong or malformed code
    CodeExpired,           // Took too long

    // Network errors
    DeviceNotFound,        // Can't find initiator
    ConnectionFailed,      // Network issues

    // Security errors
    InvalidSignature,      // Challenge verification failed
    UntrustedDevice,       // Device key mismatch

    // State errors
    SessionNotFound,       // Unknown session ID
    InvalidState,          // Wrong state transition
}

// High-level API
pub async fn start_pairing_as_initiator(
    &self
) -> Result<PairingCode> {
    // Generate secure code
    let code = PairingCode::generate();
    let session_id = code.derive_session_id();

    // Create session
    let session = PairingSession::new_initiator(session_id);
    self.sessions.insert(session_id, session);

    // Advertise on network
    self.advertise_pairing(session_id).await?;

    Ok(code)
}

// High-level API
pub async fn start_pairing_as_joiner(
    &self,
    code: &str
) -> Result<()> {
    // Parse and validate code
    let pairing_code = PairingCode::from_str(code)?;
    let session_id = pairing_code.derive_session_id();

    // Create session
    let session = PairingSession::new_joiner(session_id);
    self.sessions.insert(session_id, session);

    // Find and connect to initiator
    let initiator = self.discover_initiator(session_id).await?;
    self.connect_and_pair(initiator, session_id).await?;

    Ok(())
}

impl PairingProtocolHandler {
    async fn handle_message(
        &mut self,
        msg: PairingMessage,
        peer_id: PeerId,
    ) -> Result<()> {
        match msg {
            PairingMessage::PairingRequest { .. } => {
                self.handle_pairing_request(..);
            }
            PairingMessage::Challenge { .. } => {
                self.handle_challenge(..);
            }
            PairingMessage::Response { .. } => {
                self.handle_response(..);
            }
            PairingMessage::Complete { .. } => {
                self.handle_complete(..);
            }
        }
    }
}

#[test]
fn test_pairing_code_generation() {
    let code = PairingCode::generate();
    assert_eq!(code.words.len(), 12);
    assert!(code.is_valid());
}

#[test]
fn test_challenge_response() {
    let (signing_key, verifying_key) = generate_keypair();
    let challenge = generate_challenge();

    let signature = signing_key.sign(&challenge);
    assert!(verifying_key.verify(&challenge, &signature).is_ok());
}

#[tokio::test]
async fn test_full_pairing_flow() {
    // Start initiator
    let code = initiator.start_pairing_as_initiator().await?;

    // Join with code
    joiner.start_pairing_as_joiner(&code.to_string()).await?;

    // Verify both paired
    assert!(initiator.is_paired_with(joiner.device_id()));
    assert!(joiner.is_paired_with(initiator.device_id()));
}