Module pairing 

Pairing protocol for cross-device identity linking.

This module implements a secure pairing protocol that allows users to link multiple devices to the same identity. The protocol uses X25519 ECDH key exchange with Ed25519 signature binding to ensure secure device authentication and forward secrecy.

Protocol Flow

1. Initiating device generates a PairingToken with:

   • Controller DID (identity of the initiator)
   • X25519 ephemeral public key
   • Alphanumeric short code (6-char, no ambiguous chars)
   • Capabilities to grant
   • 5-minute expiry

2. Initiating device displays the token as:

   • QR code (preferred)
   • Alphanumeric short code (fallback)

3. Responding device scans/enters the token and creates a PairingResponse:

   • Generates its own X25519 ephemeral key
   • Performs ECDH with initiator’s key → shared secret
   • Signs binding message (short_code || initiator_x25519 || device_x25519)
   • Includes its Ed25519 public key and DID

4. Initiating device verifies the response and completes ECDH:

   • Verifies Ed25519 signature binding
   • Performs ECDH with responder’s X25519 key → same shared secret
   • Creates device attestation

Example

use auths_core::pairing::{PairingToken, PairingResponse, format_pairing_qr};
use chrono::{DateTime, Utc};

// `now` is injected by the caller (e.g., clock.now() at presentation boundary)
fn initiate_pairing(now: DateTime<Utc>) {
    let mut session = PairingToken::generate(
        now,
        "did:keri:controller123".to_string(),
        "http://localhost:3000".to_string(),
        vec!["sign_commit".to_string()],
    ).unwrap();
    let display = format_pairing_qr(&session.token).unwrap();
    print!("{}", display);

    // Get the URI for QR code
    let uri = session.token.to_uri();
}

Re-exports

pub use types::*;

Modules

types

Shared API types for pairing sessions.

Structs

PairingResponse

A response to a pairing request from the responding device.

PairingSession

Ephemeral keypair for a pairing session.

PairingToken

A pairing token for initiating cross-device identity linking.

QrOptions

QR code rendering options.

Enums

PairingError

Errors that can occur during the pairing protocol.

Functions

format_pairing_qr

Format a pairing QR code with header text for terminal display.

normalize_short_code

Normalize a short code: uppercase, strip spaces/dashes.

render_qr

Render a pairing token as a QR code string for terminal display.

render_qr_from_data

Render arbitrary data as a QR code string for terminal display.