Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
// SPDX-License-Identifier: MPL-2.0
//! The pairing ceremony (protocol §9) over the `nectarlink-pair/0` ALPN.
//!
//! Two flows:
//! - **QR**: the host (PC) shows a pairing link with a one-time secret; the
//! joiner (phone) proves knowledge of it.
//! - **Nearby**: numeric comparison. Both screens show a 6-digit code derived
//! from both identities and committed nonces; both users confirm.
//!
//! Both flows end the same way, so a pairing is never stored on only one
//! side in normal operation: the host sends the last protocol message, the
//! initiator acknowledges it with `pair.done`, the host stores the pairing
//! and closes with [`CLOSE_PAIRED`], and the initiator stores it when it sees
//! that close. Failures close with [`CLOSE_FAILED`] and nobody stores.
use std::{
net::{IpAddr, SocketAddr},
sync::{Arc, Mutex},
time::{Duration, Instant},
};
use iroh::{
EndpointAddr,
endpoint::{Connection, ConnectionError, RecvStream, SendStream, VarInt},
};
use nectarlink_protocol::{
ALPN_PAIR, DeviceId, Envelope, ErrorCode,
messages::*,
pairing::{self as proto, NONCE_LEN, PairingUri, SECRET_LEN},
read_frame, write_frame,
};
use tokio::sync::oneshot;
use crate::{
Error, Result,
events::{NodeEvent, PairingEvent, PairingFailure},
node::Shared,
};
/// How long the host stays in pairing mode.
pub(crate) const PAIRING_TTL: Duration = Duration::from_secs(5 * 60);
/// How long to wait for the users to compare the 6-digit codes.
const SAS_DECISION_TIMEOUT: Duration = Duration::from_secs(120);
/// How long each pairing message may take to arrive.
const STEP_TIMEOUT: Duration = Duration::from_secs(20);
/// Wrong proofs tolerated before pairing mode ends.
const MAX_FAILED_ATTEMPTS: u32 = 5;
const DIAL_TIMEOUT: Duration = Duration::from_secs(15);
/// How long the initiator waits for the host to store the pairing and close.
const FINISH_TIMEOUT: Duration = Duration::from_secs(10);
/// How long a host that failed waits for the initiator to read its error.
const LINGER_TIMEOUT: Duration = Duration::from_secs(2);
/// Close code: the host stored the pairing.
const CLOSE_PAIRED: u32 = 0;
/// Close code: the ceremony failed; nothing was stored.
const CLOSE_FAILED: u32 = 1;
/// Host-side pairing mode, active while a QR code is shown.
struct HostMode {
secret: [u8; SECRET_LEN],
expires_at: Instant,
failures: u32,
}
/// Pairing state shared by both flows. Only one ceremony runs at a time.
#[derive(Default)]
pub(crate) struct PairingState {
host: Mutex<Option<HostMode>>,
/// Waiting for the local user to confirm or reject the 6-digit code.
sas_decision: Mutex<Option<(DeviceId, oneshot::Sender<bool>)>>,
/// True while a nearby ceremony is in flight, so a second one cannot
/// overwrite `sas_decision`.
nearby_active: std::sync::atomic::AtomicBool,
}
pub(crate) struct NearbyGuard<'a>(&'a PairingState);
impl Drop for NearbyGuard<'_> {
fn drop(&mut self) {
self.0.clear_decision();
self.0.nearby_active.store(false, std::sync::atomic::Ordering::Release);
}
}
impl std::fmt::Debug for PairingState {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PairingState").finish_non_exhaustive()
}
}
fn lock<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
m.lock().unwrap_or_else(|e| e.into_inner())
}
impl PairingState {
fn host_secret(&self) -> Option<[u8; SECRET_LEN]> {
let mut host = lock(&self.host);
match host.as_ref() {
Some(mode) if mode.expires_at > Instant::now() => Some(mode.secret),
Some(_) => {
*host = None;
None
}
None => None,
}
}
pub(crate) fn is_hosting(&self) -> bool {
self.host_secret().is_some()
}
fn end_host(&self) {
*lock(&self.host) = None;
}
/// Records a failed attempt; returns true if pairing mode just ended.
fn record_failure(&self) -> bool {
let mut host = lock(&self.host);
if let Some(mode) = host.as_mut() {
mode.failures += 1;
if mode.failures >= MAX_FAILED_ATTEMPTS {
*host = None;
return true;
}
}
false
}
fn begin_nearby(&self) -> Option<NearbyGuard<'_>> {
self.nearby_active
.compare_exchange(
false,
true,
std::sync::atomic::Ordering::AcqRel,
std::sync::atomic::Ordering::Acquire,
)
.ok()
.map(|_| NearbyGuard(self))
}
/// Delivers the local user's decision about the 6-digit code.
pub(crate) fn decide(&self, matches: bool) -> Result<()> {
match lock(&self.sas_decision).take() {
Some((_, tx)) => {
let _ = tx.send(matches);
Ok(())
}
None => Err(Error::NotPairing),
}
}
fn await_decision(&self, peer: DeviceId) -> Result<oneshot::Receiver<bool>> {
let mut slot = lock(&self.sas_decision);
if slot.is_some() {
return Err(Error::Denied);
}
let (tx, rx) = oneshot::channel();
*slot = Some((peer, tx));
Ok(rx)
}
fn clear_decision(&self) {
*lock(&self.sas_decision) = None;
}
}
/// Starts host pairing mode and returns the link to show as a QR code.
pub(crate) async fn start_host(shared: &Arc<Shared>) -> Result<PairingUri> {
let secret: [u8; SECRET_LEN] = rand::random();
*lock(&shared.pairing.host) =
Some(HostMode { secret, expires_at: Instant::now() + PAIRING_TTL, failures: 0 });
// Expire quietly; tell the UI if nobody paired in time.
let weak = Arc::downgrade(shared);
tokio::spawn(async move {
tokio::time::sleep(PAIRING_TTL).await;
if let Some(shared) = weak.upgrade() {
let still_ours = lock(&shared.pairing.host).as_ref().is_some_and(|m| m.secret == secret);
if still_ours {
shared.pairing.end_host();
shared.emit(NodeEvent::Pairing(PairingEvent::Failed(PairingFailure::Expired)));
}
}
});
let name = local_device(shared).name;
Ok(PairingUri { id: shared.id, secret, name, addrs: link_addrs(shared.direct_addrs().await) })
}
/// Most addresses a pairing link carries; more only make the QR code denser.
const MAX_LINK_ADDRS: usize = 3;
/// Picks the addresses worth putting in a pairing link: private IPv4 first
/// (what a phone on the same network almost always uses), then other IPv4,
/// then at most one IPv6. Link-local IPv6 is useless without a scope ID.
/// Discovery on the network finds the device even if none of these work.
fn link_addrs(mut addrs: Vec<SocketAddr>) -> Vec<SocketAddr> {
let rank = |a: &SocketAddr| match a.ip() {
IpAddr::V4(v4) if v4.is_private() => 0,
IpAddr::V4(v4) if v4.is_loopback() || v4.is_link_local() => 3,
IpAddr::V4(_) => 1,
IpAddr::V6(_) => 2,
};
let has_non_loopback = addrs.iter().any(|a| match a.ip() {
IpAddr::V6(v6) => !v6.is_loopback() && !v6.is_unicast_link_local(),
IpAddr::V4(v4) => !v4.is_loopback(),
});
addrs.retain(|a| match a.ip() {
IpAddr::V6(v6) => !v6.is_loopback() && !v6.is_unicast_link_local(),
IpAddr::V4(v4) => !has_non_loopback || !v4.is_loopback(),
});
addrs.sort_by_key(rank);
let mut picked = Vec::new();
let mut has_v6 = false;
for addr in addrs {
if addr.is_ipv6() {
if has_v6 {
continue;
}
has_v6 = true;
}
picked.push(addr);
if picked.len() == MAX_LINK_ADDRS {
break;
}
}
picked
}
pub(crate) fn cancel(shared: &Shared) {
shared.pairing.end_host();
shared.pairing.clear_decision();
}
// ---- Initiator side ----
/// Joins a host by scanning its pairing link (the phone side of the QR flow).
pub(crate) async fn join_qr(shared: &Arc<Shared>, uri: &PairingUri) -> Result<()> {
shared.remember_addrs(&uri.id, &uri.addrs);
let conn = dial(shared, &uri.id).await?;
let result = async {
let (mut send, mut recv) = conn.open_bi().await.map_err(crate::error::net)?;
let device = local_device(shared);
let proof = proto::pair_proof(&uri.secret, &shared.id, &uri.id).to_vec();
send_env(&mut send, Envelope::new(types::PAIR_REQUEST, &PairRequest { device, proof })?).await?;
let accept: PairAccept = recv_env(&mut recv, STEP_TIMEOUT).await?.expect_body(types::PAIR_ACCEPT)?;
finish_initiator(&conn, send).await?;
Ok(accept.device.sanitized())
}
.await;
settle_initiator(shared, &conn, uri.id, result).await
}
/// Starts the nearby (numeric comparison) flow with a device in pairing
/// mode. The 6-digit code arrives as [`PairingEvent::SasCode`]; answer with
/// [`crate::Node::pairing_confirm`].
pub(crate) async fn start_nearby(shared: &Arc<Shared>, peer: DeviceId) -> Result<()> {
let nearby = shared.pairing.begin_nearby().ok_or(Error::Denied)?;
let conn = match dial(shared, &peer).await {
Ok(conn) => conn,
Err(e) => {
drop(nearby);
return Err(e);
}
};
let result = async {
let (mut send, mut recv) = conn.open_bi().await.map_err(crate::error::net)?;
let n_a: [u8; NONCE_LEN] = rand::random();
let commit = PairCommit { device: local_device(shared), c: proto::commitment(&n_a).to_vec() };
send_env(&mut send, Envelope::new(types::PAIR_COMMIT, &commit)?).await?;
let nonce: PairNonce = recv_env(&mut recv, STEP_TIMEOUT).await?.expect_body(types::PAIR_NONCE)?;
send_env(&mut send, Envelope::new(types::PAIR_REVEAL, &PairReveal { n_a: n_a.to_vec() })?).await?;
// We are A (initiator), the host is B.
let code = proto::sas_code(&n_a, &nonce.n_b, &shared.id, &peer);
exchange_decisions(shared, peer, code, &mut send, &mut recv, Role::Initiator).await?;
finish_initiator(&conn, send).await?;
Ok(nonce.device.sanitized())
}
.await;
drop(nearby);
settle_initiator(shared, &conn, peer, result).await
}
/// Sends `pair.done` and waits for the host to store the pairing and close
/// with [`CLOSE_PAIRED`]. Any other outcome means the host didn't store it.
async fn finish_initiator(conn: &Connection, mut send: SendStream) -> Result<()> {
send_env(&mut send, Envelope::empty(types::PAIR_DONE)).await?;
let _ = send.finish();
match tokio::time::timeout(FINISH_TIMEOUT, conn.closed()).await {
Ok(ConnectionError::ApplicationClosed(close))
if close.error_code == VarInt::from_u32(CLOSE_PAIRED) =>
{
Ok(())
}
Ok(other) => Err(Error::Network(format!("pairing ended unexpectedly: {other}"))),
Err(_) => Err(Error::Timeout),
}
}
async fn settle_initiator(
shared: &Arc<Shared>,
conn: &Connection,
peer: DeviceId,
result: Result<DeviceInfo>,
) -> Result<()> {
match result {
Ok(device) => shared.complete_pairing(peer, device).await,
Err(err) => {
conn.close(VarInt::from_u32(CLOSE_FAILED), b"failed");
Err(fail(shared, err))
}
}
}
// ---- Host side ----
/// Handles an incoming pairing connection (host side of both flows).
pub(crate) async fn accept(shared: Arc<Shared>, conn: Connection) {
let peer = crate::device_id(&conn.remote_id());
let is_usb = shared.is_usb_connection(&conn);
if !shared.pairing.is_hosting() && !is_usb {
tracing::debug!(peer = %peer.short(), "refusing pairing connection: not in pairing mode");
conn.close(VarInt::from_u32(ErrorCode::Denied.close_code()), b"not pairing");
return;
}
let (mut send, mut recv) = match conn.accept_bi().await {
Ok(streams) => streams,
Err(e) => {
tracing::debug!(peer = %peer.short(), error = %e, "pairing connection dropped");
return;
}
};
let result = async {
let first = recv_env(&mut recv, STEP_TIMEOUT).await?;
let device = match first.t.as_str() {
types::PAIR_REQUEST => accept_qr(&shared, peer, first, &mut send).await?,
types::PAIR_COMMIT => {
match accept_nearby(&shared, peer, first, &mut send, &mut recv, is_usb).await {
Ok(Some(device)) => device,
Ok(None) => return Err(Error::Denied),
Err(e) => {
let ended = shared.pairing.record_failure();
let err = fail(&shared, e);
if ended && !matches!(err, Error::Denied) {
shared.emit(NodeEvent::Pairing(PairingEvent::Failed(PairingFailure::Rejected)));
}
return Err(err);
}
}
}
other => {
let reply = Envelope::error(ErrorCode::Unsupported, format!("unexpected {other}"));
send_env(&mut send, reply).await?;
return Err(Error::Protocol(format!("unexpected pairing message {other}")));
}
};
// Store only once the initiator acknowledged our last message.
recv_env(&mut recv, STEP_TIMEOUT).await?.expect(types::PAIR_DONE)?;
Ok(device)
}
.await;
match result {
Ok(device) => match shared.complete_pairing(peer, device).await {
Ok(()) => conn.close(VarInt::from_u32(CLOSE_PAIRED), b"paired"),
Err(e) => {
tracing::warn!(error = %e, "failed to store pairing");
conn.close(VarInt::from_u32(CLOSE_FAILED), b"storage");
}
},
Err(err) => {
tracing::info!(peer = %peer.short(), error = %err, "pairing attempt failed");
// Let the initiator read our error before the connection goes away.
let _ = send.finish();
let _ = tokio::time::timeout(LINGER_TIMEOUT, conn.closed()).await;
conn.close(VarInt::from_u32(CLOSE_FAILED), b"failed");
}
}
}
async fn accept_qr(
shared: &Arc<Shared>,
peer: DeviceId,
env: Envelope,
send: &mut SendStream,
) -> Result<DeviceInfo> {
let request: PairRequest = env.body()?;
let Some(secret) = shared.pairing.host_secret() else {
send_env(send, Envelope::error(ErrorCode::Denied, "pairing mode ended")).await?;
return Err(Error::NotPairing);
};
if !proto::verify_pair_proof(&secret, &peer, &shared.id, &request.proof) {
send_env(send, Envelope::error(ErrorCode::Denied, "pairing code mismatch")).await?;
if shared.pairing.record_failure() {
shared.emit(NodeEvent::Pairing(PairingEvent::Failed(PairingFailure::Rejected)));
}
return Err(Error::Denied);
}
shared.pairing.end_host();
send_env(send, Envelope::new(types::PAIR_ACCEPT, &PairAccept { device: local_device(shared) })?).await?;
Ok(request.device.sanitized())
}
async fn accept_nearby(
shared: &Arc<Shared>,
peer: DeviceId,
env: Envelope,
send: &mut SendStream,
recv: &mut RecvStream,
is_usb: bool,
) -> Result<Option<DeviceInfo>> {
if !shared.pairing.is_hosting() && !is_usb {
send_env(send, Envelope::error(ErrorCode::Denied, "pairing mode ended")).await?;
return Ok(None);
}
let Some(_nearby) = shared.pairing.begin_nearby() else {
send_env(send, Envelope::error(ErrorCode::Busy, "another pairing is in progress")).await?;
return Ok(None);
};
let commit: PairCommit = env.body()?;
let peer_device = commit.device.sanitized();
shared.note_discovered(peer, Some(peer_device.name.clone()));
let n_b: [u8; NONCE_LEN] = rand::random();
let nonce = PairNonce { device: local_device(shared), n_b: n_b.to_vec() };
send_env(send, Envelope::new(types::PAIR_NONCE, &nonce)?).await?;
let reveal: PairReveal = recv_env(recv, STEP_TIMEOUT).await?.expect_body(types::PAIR_REVEAL)?;
if !proto::verify_commitment(&commit.c, &reveal.n_a) {
send_env(send, Envelope::error(ErrorCode::Denied, "commitment mismatch")).await?;
return Err(Error::Denied);
}
// The initiator is A, we are B.
let code = proto::sas_code(&reveal.n_a, &n_b, &peer, &shared.id);
exchange_decisions(shared, peer, code, send, recv, Role::Host).await?;
shared.pairing.end_host();
Ok(Some(peer_device))
}
// ---- Code comparison ----
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Role {
/// Sends its confirmation as soon as the local user confirms.
Initiator,
/// Replies last: only after both the local user and the initiator confirmed.
Host,
}
/// Shows the 6-digit code and exchanges both users' decisions. Watches the
/// peer while waiting for the local user, so a decline on the other device
/// ends the comparison right away.
async fn exchange_decisions(
shared: &Arc<Shared>,
peer: DeviceId,
code: String,
send: &mut SendStream,
recv: &mut RecvStream,
role: Role,
) -> Result<()> {
let decision = shared.pairing.await_decision(peer)?;
shared.emit(NodeEvent::Pairing(PairingEvent::SasCode { peer, code }));
let mut decision = Box::pin(tokio::time::timeout(SAS_DECISION_TIMEOUT, decision));
// Created once: reading a frame isn't cancel-safe, so it must not be
// restarted when the other branch wins.
let mut remote = Box::pin(recv_env(recv, SAS_DECISION_TIMEOUT));
let (mut local_ok, mut remote_ok) = (false, false);
while !(local_ok && remote_ok) {
tokio::select! {
outcome = &mut decision, if !local_ok => {
if !matches!(outcome, Ok(Ok(true))) {
shared.pairing.clear_decision();
send_env(send, Envelope::error(ErrorCode::Denied, "codes did not match")).await?;
return Err(Error::Declined);
}
local_ok = true;
if role == Role::Initiator {
send_env(send, Envelope::empty(types::PAIR_CONFIRM)).await?;
}
}
reply = &mut remote, if !remote_ok => {
let outcome = reply.and_then(|env| Ok(env.expect(types::PAIR_CONFIRM)?));
if let Err(err) = outcome {
shared.pairing.clear_decision();
return Err(err);
}
remote_ok = true;
}
}
}
if role == Role::Host {
send_env(send, Envelope::empty(types::PAIR_CONFIRM)).await?;
}
Ok(())
}
// ---- Helpers ----
fn local_device(shared: &Shared) -> DeviceInfo {
shared.local.read().unwrap_or_else(|e| e.into_inner()).device.clone()
}
async fn dial(shared: &Arc<Shared>, peer: &DeviceId) -> Result<Connection> {
let mut addr = EndpointAddr::new(crate::public_key(peer)?);
if let Some(usb_addr) = shared.usb_peer_addr(peer) {
addr = addr.with_ip_addr(usb_addr);
}
let err = match tokio::time::timeout(DIAL_TIMEOUT, shared.endpoint.connect(addr, ALPN_PAIR)).await {
Ok(Ok(conn)) => return Ok(conn),
Ok(Err(e)) => crate::error::net(e),
Err(_) => Error::Timeout,
};
shared.emit(NodeEvent::Pairing(PairingEvent::Failed(PairingFailure::Unreachable)));
Err(err)
}
async fn send_env(send: &mut SendStream, env: Envelope) -> Result<()> {
write_frame(send, &env.to_cbor()).await?;
Ok(())
}
async fn recv_env(recv: &mut RecvStream, timeout: Duration) -> Result<Envelope> {
let frame = tokio::time::timeout(timeout, read_frame(recv)).await.map_err(|_| Error::Timeout)??;
Ok(Envelope::from_cbor(&frame.ok_or(Error::Offline)?)?)
}
/// Reports a failed ceremony to the UI and passes the error through.
fn fail(shared: &Shared, err: Error) -> Error {
let failure = match &err {
Error::Denied => PairingFailure::Rejected,
Error::Declined => PairingFailure::Declined,
Error::Timeout | Error::Offline | Error::Network(_) => PairingFailure::Unreachable,
other => PairingFailure::Other(other.to_string()),
};
shared.emit(NodeEvent::Pairing(PairingEvent::Failed(failure)));
err
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn pairing_links_carry_the_useful_addresses() {
let addrs: Vec<SocketAddr> = [
"[2001:db8:1::1]:5000",
"[fe80::1]:5000",
"100.64.0.1:5000",
"[2001:db8:1::2]:5000",
"192.168.1.20:5000",
"127.0.0.1:5000",
]
.iter()
.map(|a| a.parse().unwrap())
.collect();
let picked: Vec<String> = link_addrs(addrs).iter().map(ToString::to_string).collect();
assert_eq!(picked, ["192.168.1.20:5000", "100.64.0.1:5000", "[2001:db8:1::1]:5000"]);
let loopback_only: Vec<SocketAddr> = ["127.0.0.1:5000".parse().unwrap()].into();
let fallback: Vec<String> = link_addrs(loopback_only).iter().map(ToString::to_string).collect();
assert_eq!(fallback, ["127.0.0.1:5000"]);
assert!(link_addrs(Vec::new()).is_empty());
}
#[test]
fn second_nearby_ceremony_is_refused_without_clobbering_decision() {
let state = PairingState::default();
let guard = state.begin_nearby().expect("first nearby starts");
assert!(state.begin_nearby().is_none(), "concurrent nearby is refused");
let peer_a = DeviceId([1; 32]);
let peer_b = DeviceId([2; 32]);
let mut rx = state.await_decision(peer_a).expect("first decision registered");
assert!(matches!(state.await_decision(peer_b), Err(Error::Denied)));
state.decide(true).expect("decision delivered to first ceremony");
assert_eq!(rx.try_recv(), Ok(true));
drop(guard);
assert!(state.begin_nearby().is_some(), "slot released after guard drops");
}
}