Authentication

// src/pair.rs
// Auto-derives the client type from `device_props`.
pub fn make_qr_data(store: &Device, ref_str: &str) -> String {
    let client_type = companion_web_client_type_for_props(&store.device_props);
    make_qr_data_with_client_type(store, ref_str, client_type)
}

// Use this to override the trailing client-type field explicitly.
pub fn make_qr_data_with_client_type(
    store: &Device,
    ref_str: &str,
    client_type: CompanionWebClientType,
) -> String { /* ... */ }

use std::sync::Arc;
use whatsapp_rust::bot::Bot;
use whatsapp_rust::TokioRuntime;
use whatsapp_rust::store::SqliteStore;
use whatsapp_rust_tokio_transport::TokioWebSocketTransportFactory;
use whatsapp_rust_ureq_http_client::UreqHttpClient;
use wacore::types::events::{Event, PairingQrCode};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = Arc::new(SqliteStore::new("whatsapp.db").await?);

    let mut bot = Bot::builder()
        .with_backend(backend)
        .with_transport_factory(TokioWebSocketTransportFactory::new())
        .with_http_client(UreqHttpClient::new())
        .with_runtime(TokioRuntime)
        .on_event(|event, _client| async move {
            match &*event {
                Event::PairingQrCode(PairingQrCode { code, timeout, .. }) => {
                    println!("Scan this QR code (valid for {}s):", timeout.as_secs());
                    println!("{}", code);
                }
                Event::PairSuccess(info) => {
                    println!("Paired as {}", info.id);
                }
                _ => {}
            }
        })
        .build()
        .await?;

    bot.run().await?.await?;
    Ok(())
}

// wacore/src/types/events.rs
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingQrCode {
    pub code: String,               // ASCII art QR or data string
    pub timeout: std::time::Duration, // Validity duration (60s first, 20s subsequent)
}

for code in codes_clone {
    // Safety guard: pairing may complete before this task gets polled
    if client_clone.is_logged_in() {
        info!("Already logged in, stopping QR rotation.");
        return;
    }

    let timeout = if is_first {
        is_first = false;
        Duration::from_secs(60)
    } else {
        Duration::from_secs(20)
    };

    client.core.event_bus.dispatch(Event::PairingQrCode(
        PairingQrCode::builder().code(code).timeout(timeout).build(),
    ));

    let sleep = client_clone.runtime.sleep(timeout);
    let stop = stop_rx.recv();
    futures::pin_mut!(sleep);
    futures::pin_mut!(stop);
    match futures::future::select(sleep, stop).await {
        futures::future::Either::Left(_) => {
            // Timeout elapsed — check again in case login happened during sleep
            if client_clone.is_logged_in() {
                info!("Logged in during QR timeout, stopping rotation.");
                return;
            }
        }
        futures::future::Either::Right(_) => {
            info!("Pairing complete. Stopping QR code rotation.");
            return;
        }
    }
}

// src/pair.rs
let pair_code_outstanding = client_clone
    .pair_code_state
    .lock()
    .await
    .is_outstanding(wacore::time::Instant::now());

client_clone.core.event_bus.dispatch(Event::PairingQrCodesExhausted(
    PairingQrCodesExhausted::builder()
        .disconnected(!pair_code_outstanding)
        .build(),
));
if !pair_code_outstanding {
    client_clone.disconnect().await;
}

// wacore/src/companion_reg.rs (re-exported from whatsapp_rust::pair)
pub const NATIVE_CAMERA_DEEP_LINK_PREFIX: &str = "https://wa.me/settings/linked_devices#";

use whatsapp_rust::pair::NATIVE_CAMERA_DEEP_LINK_PREFIX;
use wacore::types::events::{Event, PairingQrCode};

// Depends on the `qrcode` crate:  qrcode = "0.14"
fn render_qr(payload: &str) {
    use qrcode::{QrCode, render::unicode};
    let code = QrCode::new(payload).expect("valid QR payload");
    let art = code
        .render::<unicode::Dense1x2>()
        .quiet_zone(true)
        .build();
    println!("{art}");
}

// ...inside your event handler:
.on_event(|event, _client| async move {
    if let Event::PairingQrCode(PairingQrCode { code, timeout, .. }) = &*event {
        // Prepend the prefix so iOS's native Camera opens WhatsApp directly.
        let deep_link = format!("{NATIVE_CAMERA_DEEP_LINK_PREFIX}{code}");

        println!("Scan with your iOS Camera app (valid {}s):", timeout.as_secs());
        render_qr(&deep_link);

        // Tip: `deep_link` is also a working https:// URL you can share as a
        // clickable link on the device itself.
    }
})

123456789ABCDEFGHJKLMNPQRSTVWXYZ

use whatsapp_rust::pair_code::PairCodeOptions;

let options = PairCodeOptions {
    phone_number: "15551234567".to_string(),
    show_push_notification: true,
    ..Default::default()
};

let code = client.pair_with_code(options).await?;
println!("Enter this code on your phone: {}", code);

let options = PairCodeOptions {
    phone_number: "15551234567".to_string(),
    custom_code: Some("MYCODE12".to_string()),
    ..Default::default()
};

let code = client.pair_with_code(options).await?;
assert_eq!(code, "MYCODE12");

use wacore::pair_code::PairCodeError;
use whatsapp_rust::pair_code::PairError;

match client.pair_with_code(options).await {
    Ok(code) => println!("Enter this code on your phone: {code}"),
    Err(PairError::PairCode(PairCodeError::CodeAlreadyOutstanding { remaining })) => {
        // `remaining` is the code's validity window, not a countdown on the
        // overall block: it reads `0` while a pair-success is pending on an
        // already-entered code, not "no time left before you may retry".
        eprintln!("A code is already outstanding ({remaining:?} left in its validity window) — cancel it first");
        client.cancel_pair_code().await;
    }
    Err(e) => eprintln!("Pair code request failed: {e}"),
}

// src/pair_code.rs
pub async fn cancel_pair_code(self: &Arc<Self>);

// wacore/src/pair_code.rs
pub struct PairCodeOptions {
    /// Phone number in international format (e.g., "15551234567").
    /// Non-digit characters are automatically stripped.
    pub phone_number: String,

    /// Whether to show a push notification on the phone (default: `true`).
    pub show_push_notification: bool,

    /// Custom 8-character code (must be valid Crockford Base32).
    /// If `None`, a random code is generated.
    pub custom_code: Option<String>,

    /// Override for `companion_platform_id`. When `None`, the value is
    /// derived from `Device.device_props.platform_type`.
    pub platform_id: Option<CompanionWebClientType>,

    /// Advanced OS override for `companion_platform_display`. `None`
    /// (default) canonicalizes `DeviceProps::os` to a small server-safe set
    /// (an unrecognized/branding value coerces to `Linux`). `Some(os)` sends
    /// `os` **verbatim**, bypassing that coercion — use it to keep a real OS
    /// name the server accepts but the canonical set drops (e.g. `"Ubuntu"`,
    /// `"Fedora"`). At your own risk: the server rejects a non-OS string with
    /// `bad-request`. An all-whitespace value is ignored (falls back to the
    /// safe coercion).
    pub display_os: Option<String>,
}

// wacore/src/companion_reg.rs
pub enum CompanionWebClientType {
    // Web (digit codes from WAWebCompanionRegClientUtils.DEVICE_PLATFORM)
    Chrome,            // b'1'
    Edge,              // b'2'
    Firefox,           // b'3'
    Ie,                // b'4'
    Opera,             // b'5'
    Safari,            // b'6'
    Electron,          // b'7'
    Uwp,               // b'8'
    OtherWebClient,    // b'9' — default fallback
    // Mobile (letter codes from the official WhatsApp Android client).
    // Reachable only via an explicit `PairCodeOptions::platform_id` override
    // because the server requires attestation that this crate cannot fake.
    AndroidTablet,     // b'd'
    AndroidPhone,      // b'e'
    AndroidAmbiguous,  // b'f'
}

// wacore/src/types/events.rs
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCode {
    pub code: String,               // The 8-character pairing code
    pub timeout: std::time::Duration, // Validity (~180 seconds), remaining at time of emission
}

let requested_at = wacore::time::Instant::now();
let code_expires_at = requested_at + PairCodeUtils::code_validity();
// ...stage 1 companion_hello round-trip...
let remaining = code_expires_at.saturating_duration_since(wacore::time::Instant::now());

self.core.event_bus.dispatch(Event::PairingCode(
    PairingCode::builder()
        .code(code.clone())
        .timeout(remaining)
        .build(),
));

// wacore/src/types/events.rs
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCodeRefresh {
    pub force_manual: bool,  // true when the server requires an explicit re-request
}

// wacore/src/types/events.rs
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCodeError {
    pub rejection: Option<PairCodeRejection>,   // The server's refusal, when it answered with one
    pub backoff: Option<std::time::Duration>,   // The server's requested retry delay, when it named one
    pub error: String,                          // The failure rendered for logs — do not branch on it
}

// wacore/src/pair_code.rs
pub enum PairCodeRejection {
    BadRequest,          // 400 — malformed, or throttled per phone number (server reuses this code)
    Forbidden,           // 403
    RateOverlimit,       // 429 — requesting codes too fast; the only correct response is to slow down
    FeatureNotAvailable, // 452 — phone-number linking disabled for this account; retrying will not help
    InternalServerError, // 500
    Unknown(i32),        // a code outside WA Web's own accepted set
}

impl PairError {
    pub fn rejection(&self) -> Option<PairCodeRejection>;
    pub fn backoff(&self) -> Option<std::time::Duration>;
    pub fn lost_the_flow_to_another_request(&self) -> bool;
}

// src/pair_code.rs:165-174
let iq_content = PairCodeUtils::build_companion_hello_iq(
    &phone_number,
    &noise_static_pub,
    &wrapped_ephemeral,
    options.platform_id,
    &options.platform_display,
    options.show_push_notification,
    req_id.clone(),
);

let pairing_ref = PairCodeUtils::parse_companion_hello_response(&response)
    .ok_or(PairCodeError::MissingPairingRef)?;

match reg_node.get_attr("stage").map(|v| v.as_str()).as_deref() {
    Some("primary_hello") => handle_primary_hello(client, reg_node).await,
    Some("refresh_code") => handle_refresh_code(client, reg_node).await,
    _ => { /* ignored */ false }
}

#[async_trait]
pub trait PasskeyAuthenticator: MaybeSendSync {
    async fn get_assertion(&self, request: &AssertionRequest) -> Result<Assertion, PasskeyError>;
}

pub struct AssertionRequest {
    pub challenge: Vec<u8>,               // already base64url-decoded
    pub rp_id: Option<String>,
    pub allow_credentials: Vec<Vec<u8>>,  // empty = discoverable credential
    pub user_verification: UserVerification, // Required | Preferred | Discouraged
    pub timeout_ms: Option<u64>,
    pub raw_options_json: String,         // verbatim server JSON, e.g. for Android Credential Manager
}

pub struct Assertion {
    pub assertion_json: Vec<u8>,   // WA's `<webauthn_assertion>` JSON shape
    pub credential_id: Vec<u8>,
}

// Parses the server's PublicKeyCredentialRequestOptions JSON into an AssertionRequest
pub fn parse_request_options(json: &str) -> Result<AssertionRequest, PasskeyError>;

// Assemble WA Web's exact `<webauthn_assertion>` JSON from raw WebAuthn assertion components
// (for authenticator backends that return raw bytes instead of WA-shaped JSON).
pub fn build_webauthn_assertion_json(
    credential_id: &[u8],
    client_data_json: &[u8],
    authenticator_data: &[u8],
    signature: &[u8],
    user_handle: Option<&[u8]>,
) -> Vec<u8>;

use std::sync::Arc;
use whatsapp_rust::passkey::{Assertion, AssertionRequest, CallbackAuthenticator, PasskeyError};

let authenticator = CallbackAuthenticator::new(|request: AssertionRequest| {
    Box::pin(async move {
        // e.g. hand `request.raw_options_json` to Android Credential Manager's
        // GetPublicKeyCredentialOption(requestJson = ...) and map the result:
        Ok(Assertion {
            assertion_json: get_webauthn_assertion_json(&request).await?,
            credential_id: get_credential_id(&request).await?,
        })
    })
});

client.set_passkey_authenticator(Arc::new(authenticator)).await;

use std::sync::Arc;
use wacore::types::events::Event;
use whatsapp_rust::passkey::CallbackAuthenticator;

// Automatic: register an authenticator once. Re-links finish on their own; a fresh
// link still needs you to show the code from PairPasskeyConfirmation and call
// send_passkey_confirmation() once the user approves it (see the Manual example below).
client.set_passkey_authenticator(Arc::new(CallbackAuthenticator::new(my_get_assertion))).await;

// Manual: drive each step from the events yourself.
.on_event(|event, client| async move {
    match &*event {
        Event::PairPasskeyRequest(req) => {
            let assertion = my_get_assertion_from_json(&req.request_options_json).await?;
            client.send_passkey_response(assertion).await?;
        }
        Event::PairPasskeyConfirmation(conf) => {
            if conf.skip_handoff_ux {
                client.send_passkey_confirmation().await?;
            } else {
                println!("Confirm {} matches on your phone, then continue", conf.code);
                // ...await user confirmation, then:
                client.send_passkey_confirmation().await?;
            }
        }
        Event::PairPasskeyError(err) => {
            eprintln!("Passkey link failed (continuation={}): {}", err.continuation, err.error);
        }
        Event::PairSuccess(info) => println!("Paired as {}", info.id),
        _ => {}
    }
})

// wacore/src/types/events.rs
Event::PairPasskeyRequest(PairPasskeyRequest {
    request_options_json: String, // verbatim PublicKeyCredentialRequestOptions JSON
})

Event::PairPasskeyConfirmation(PairPasskeyConfirmation {
    code: String,            // 8-char "XXXX-XXXX" verification code
    skip_handoff_ux: bool,   // true on a proven re-link: no need to show the code
})

Event::PairPasskeyError(PairPasskeyError {
    error: String,
    continuation: bool,     // false = failed during the initial request, true = during continuation
})

// wacore/noise/src/handshake.rs
pub struct XxHandshakeState         { /* ... */ }  // Noise_XX_25519_AESGCM_SHA256
pub struct IkHandshakeState         { /* ... */ }  // Noise_IK_25519_AESGCM_SHA256
pub struct XxFallbackHandshakeState { /* ... */ }  // Resumes the IK transcript as XX

pub enum IkServerHelloOutcome {
    Continue(Box<IkHandshakeOutcome>),  // Cached static accepted
    Fallback(Box<IkFallbackInputs>),    // Pivot into XXfallback
}

// wacore/src/client_profile.rs
pub struct ClientProfile {
    pub user_agent_platform: wa::client_payload::user_agent::Platform,
    pub device: String,
    pub os_version: String,
    pub manufacturer: String,
    pub include_web_info: bool,
    pub passive_login: bool,       // ClientPayload.passive
    pub phone_id: Option<String>,  // UserAgent.phone_id (anti-abuse UUID)
    pub locale_language: String,   // UserAgent.locale_language_iso6391, e.g. "pt"
    pub locale_country: String,    // UserAgent.locale_country_iso31661_alpha2, e.g. "BR"
}

use whatsapp_rust::ClientProfile;

client.set_client_profile(ClientProfile::android("13")).await;
client.connect().await?.read_until_disconnected().await;

// Direct key exchange - keys in QR code

// wacore/src/pair_code.rs
// Expensive PBKDF2 operation (wrapped in spawn_blocking)
let wrapped_ephemeral = tokio::task::spawn_blocking(move || {
    PairCodeUtils::encrypt_ephemeral_pub(&ephemeral_pub, &code_clone)
}).await?;

// src/pair.rs:188-209
let result = PairUtils::do_pair_crypto(&device_state, &device_identity_bytes);

match result {
    Ok((self_signed_identity_bytes, key_index)) => {
        // Store device JID, LID, account info
        client.persistence_manager
            .process_command(DeviceCommand::SetId(Some(jid.clone())))
            .await;
        client.persistence_manager
            .process_command(DeviceCommand::SetAccount(Some(signed_identity)))
            .await;
    }
    Err(e) => {
        // Send error to server
    }
}

// wacore/src/pair.rs — pair-time write decision
pub fn lid_migrated_update(props_migrated: bool, account_changed: bool) -> Option<bool> {
    if props_migrated {
        Some(true)
    } else if account_changed {
        // A different account must not inherit the previous account's state.
        Some(false)
    } else {
        // Same-account relink whose pair-success omitted client-props:
        // preserve whatever is already stored.
        None
    }
}

// Start QR code (automatic on connection)
bot.run().await?;

// Also start pair code in parallel
let code = client.pair_with_code(options).await?;

// src/client.rs
pub(crate) pairing_cancellation_tx: Mutex<Option<async_channel::Sender<()>>>,
pub(crate) pair_code_state: Mutex<PairCodeState>,

// src/pair.rs:140-149
async fn handle_pair_success(...) {
    // Cancel QR code rotation if active
    if let Some(tx) = client.pairing_cancellation_tx.lock().await.take() {
        let _ = tx.try_send(());
        debug!("Sent QR rotation stop signal");
    } else {
        // is_logged_in guard will stop the task even without the channel
        debug!("QR rotation channel not yet stored — is_logged_in guard will stop the task");
    }

    // Clear pair code state if active
    *client.pair_code_state.lock().await = PairCodeState::Completed;
}

// wacore/src/types/events.rs
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairSuccess {
    pub id: Jid,                // Device JID (e.g., "15551234567.0:1@s.whatsapp.net")
    pub lid: Jid,               // LID JID (e.g., "100000012345678.0:1@lid")
    pub business_name: String,  // Push name / business name
    pub platform: String,       // Platform identifier
}

Event::PairSuccess(
    PairSuccess::builder()
        .id(id)
        .lid(lid)
        .business_name(business_name)
        .platform(platform)
        .build(),
)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairError {
    pub id: Jid,
    pub lid: Jid,
    pub business_name: String,
    pub platform: String,
    pub error: String,          // Error description
}

Event::PairError(PairError::builder() /* .id(..).lid(..)… */ .build())

use whatsapp_rust::pair_code::PairError;
use wacore::pair_code::PairCodeError;

match client.pair_with_code(options).await {
    Ok(code) => println!("Code: {}", code),
    Err(PairError::PairCode(PairCodeError::PhoneNumberRequired)) => {
        eprintln!("Phone number is required");
    }
    Err(PairError::PairCode(PairCodeError::PhoneNumberTooShort)) => {
        eprintln!("Phone number must be at least 7 digits");
    }
    Err(PairError::PairCode(PairCodeError::PhoneNumberNotInternational)) => {
        eprintln!("Phone number must not start with 0 (use international format)");
    }
    Err(PairError::PairCode(PairCodeError::InvalidCustomCode)) => {
        eprintln!("Custom code must be 8 valid Crockford Base32 characters");
    }
    Err(PairError::PairCode(PairCodeError::CodeAlreadyOutstanding { remaining })) => {
        // `remaining` reads `0` while a pair-success is pending on an
        // already-entered code, not "no time left before you may retry".
        eprintln!("A code is already outstanding ({remaining:?} left in its validity window)");
    }
    Err(PairError::PairCode(PairCodeError::Cancelled)) => {
        eprintln!("cancel_pair_code() was called while companion_hello was in flight");
    }
    Err(PairError::PairCode(PairCodeError::MissingPairingRef)) => {
        eprintln!("Server did not return a pairing reference");
    }
    Err(PairError::PairCode(PairCodeError::NotWaiting)) => {
        eprintln!("No pending pair code request");
    }
    Err(PairError::PairCode(PairCodeError::InvalidWrappedData { expected, got })) => {
        eprintln!("Invalid wrapped data: expected {} bytes, got {}", expected, got);
    }
    // Typed crypto failures preserve their `CurveError`/`CryptoProviderError` source
    Err(PairError::PairCode(PairCodeError::InvalidPrimaryEphemeralKey(e))) => {
        eprintln!("Primary device sent an invalid ephemeral key: {e}");
    }
    Err(PairError::PairCode(PairCodeError::InvalidPrimaryIdentityKey(e))) => {
        eprintln!("Primary device sent an invalid identity key: {e}");
    }
    Err(PairError::PairCode(PairCodeError::EphemeralKeyAgreement(e))) => {
        eprintln!("Ephemeral DH failed: {e}");
    }
    Err(PairError::PairCode(PairCodeError::IdentityKeyAgreement(e))) => {
        eprintln!("Identity DH failed: {e}");
    }
    Err(PairError::PairCode(PairCodeError::AdvSecretKeyDerivation)) => {
        eprintln!("HKDF expand for adv_secret failed");
    }
    Err(PairError::PairCode(PairCodeError::BundleKeyDerivation)) => {
        eprintln!("HKDF expand for bundle encryption key failed");
    }
    Err(PairError::PairCode(PairCodeError::BundleAead(e))) => {
        eprintln!("AES-GCM encryption of key bundle failed: {e}");
    }
    Err(PairError::RequestFailed(iq)) => {
        eprintln!("Pair-code IQ request failed: {iq}");
    }
    // Both `PairError` and `PairCodeError` are `#[non_exhaustive]`, so a
    // wildcard arm is required from outside the crate — `PairCodeError`
    // joined the other 3 that were missing the attribute in PR #1100.
    _ => {}
}

// No pairing needed - automatic reconnection
let bot = Bot::builder()
    .with_backend(backend)
    .with_transport_factory(TokioWebSocketTransportFactory::new())
    .with_http_client(UreqHttpClient::new())
    .with_runtime(TokioRuntime)
    .build()
    .await?;

bot.run().await?; // Uses saved session

// Clear session data. Infallible as of PR #1090 — the deregistration IQ is
// best-effort and the local teardown runs either way.
client.logout().await;

// Event emitted:
Event::LoggedOut(
    LoggedOut::builder()
        .on_connect(false)
        .reason(ConnectFailureReason::LoggedOut)
        .build(),
)

.on_event(|event, client| async move {
    match &*event {
        Event::PairingQrCode(PairingQrCode { code, timeout, .. }) => {
            // Display QR to user
            println!("Valid for: {}s", timeout.as_secs());
        }
        Event::PairingCode(PairingCode { code, timeout, .. }) => {
            // Display code to user
            println!("Enter {} on your phone", code);
        }
        Event::PairingCodeRefresh(PairingCodeRefresh { force_manual, .. }) => {
            // Previous code is no longer guaranteed valid — request a new one
            println!("Refresh requested (force_manual={})", force_manual);
        }
        Event::PairSuccess(info) => {
            // Save success notification
            println!("Paired: {}", info.id);
        }
        Event::PairError(err) => {
            // Handle error
            eprintln!("Pairing failed: {}", err.error);
        }
        _ => {}
    }
})

// Both methods active - whichever completes first wins
tokio::spawn(async move {
    if let Ok(code) = client.pair_with_code(options).await {
        println!("Pair code: {}", code);
    }
});

// QR codes automatically generated and rotated
bot.run().await?;