Skip to content

Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.

114 KB
Raw Blame
//! Apple ID sign-in, and the session that survives a restart.
//!
//! Two things make this different from every Electron iCloud wrapper:
//!
//! 1. **Auth is native.** Chromium splits WebAuthn across its render engine and its browser
//!    layer, and Electron ships only the former — so "Sign in with iPhone" hangs forever on
//!    Linux (electron/electron#24573, open since 2020). Doing SRP ourselves sidesteps that
//!    entirely; no webview is involved in authentication.
//! 2. **We keep the durable credential.** Apple hands back a trust token from `/2sv/trust`.
//!    A webview never asks for one, so it has nothing to persist and signs you out. We store
//!    it in the OS keyring.

/// What went wrong, said on the terminal in a development build only, and never with anything
/// of the person's in it — no names, record ids, addresses or Apple's answers. A release build
/// says nothing at all: Quince keeps no diagnostics and sends none anywhere.
macro_rules! quiet {
    ($($t:tt)*) => {
        if cfg!(debug_assertions) {
            eprintln!($($t)*);
        }
    };
}

pub mod diag;
pub mod pcs;
pub mod releases;
mod sealed;
pub mod session;
pub mod srp;
pub mod state;

use base64::{engine::general_purpose::STANDARD as B64, Engine};
use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
use reqwest::{Client as HttpClient, Response, StatusCode};
use reqwest_cookie_store::CookieStoreMutex;
use serde_json::{json, Value};
pub use session::Store;
use session::{backoff_seconds, unix_now, Session, CAPTURED_HEADERS};
use std::path::Path;
use std::sync::Arc;

/// Base URLs for Apple's auth and setup services.
///
/// Injectable so the sign-in flow can be exercised against a mock server.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Endpoints {
    /// Origin for the SRP sign-in calls.
    pub auth_root: String,
    /// `{auth_root}/appleauth/auth`
    pub auth: String,
    /// `.../setup/ws/1`
    pub setup: String,
    /// Origin for everything that is not SRP sign-in.
    pub home: String,
}

impl Default for Endpoints {
    fn default() -> Self {
        Self {
            auth_root: "https://idmsa.apple.com".into(),
            auth: "https://idmsa.apple.com/appleauth/auth".into(),
            setup: "https://setup.icloud.com/setup/ws/1".into(),
            home: "https://www.icloud.com".into(),
        }
    }
}

/// The domain Apple names for the accounts it keeps on its own servers apart from iCloud.com
/// (`domainToUse` in its answer to `accountLogin`), as it writes it.
pub const REGIONAL_DOMAIN: &str = "icloud.com.cn";

/// iCloud.com's own domain, as Apple names it in `domainToUse`.
const HOME_DOMAIN: &str = "icloud.com";

/// Where Apple's answer says this account is kept, when it says (`domainToUse`).
fn domain_to_use(text: &str) -> Option<String> {
    serde_json::from_str::<Value>(text)
        .ok()?
        .get("domainToUse")?
        .as_str()
        .map(|d| d.trim().to_ascii_lowercase())
        .filter(|d| !d.is_empty())
}

impl Endpoints {
    /// Apple's servers for an account Apple keeps at `domain` (its `domainToUse`, kept in the
    /// session): iCloud.com's for every account, unless Apple named its regional domain. The
    /// same services and protocols, at Apple's own hosts there (icloudpd's `--domain cn`).
    #[must_use]
    pub fn for_domain(domain: Option<&str>) -> Self {
        if domain.is_some_and(|d| d.eq_ignore_ascii_case(REGIONAL_DOMAIN)) {
            Self {
                auth_root: "https://idmsa.apple.com.cn".into(),
                auth: "https://idmsa.apple.com.cn/appleauth/auth".into(),
                setup: "https://setup.icloud.com.cn/setup/ws/1".into(),
                home: "https://www.icloud.com.cn".into(),
            }
        } else {
            Self::default()
        }
    }

    /// Point every service at one base URL. Test seam.
    pub fn at(base: &str) -> Self {
        let base = base.trim_end_matches('/');
        Self {
            auth_root: base.into(),
            auth: format!("{base}/appleauth/auth"),
            setup: format!("{base}/setup/ws/1"),
            home: base.into(),
        }
    }
}

/// iCloud web's first-party OAuth widget key. Not a secret — it is public in the web client.
const WIDGET_KEY: &str = "d39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d";
/// Bounds on Apple's PBKDF2 iteration count. Apple sends each account's own: most see about
/// 20,000, but older accounts far fewer (806 for one, issue #8), and every other client takes
/// whatever comes. So any count is taken but none, which is no derivation at all; only the
/// ceiling guards something, a response that would have us burn the CPU. Apple chose the count
/// over TLS, so a low one is not something an attacker in the middle can ask for.
const MIN_PBKDF2_ITERATIONS: u32 = 1;
const MAX_PBKDF2_ITERATIONS: u32 = 1_000_000;

/// Version strings the iCloud web client sends. Cosmetic to Apple in practice, but sending
/// something plausible keeps our requests looking like the client they are imitating.
const CLIENT_BUILD: &str = "2523Project28";
const CLIENT_MASTERING: &str = "2523B28";

const UA: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 \
                  (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36";

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("Apple didn't accept that Apple Account or password. Use your Apple Account password itself: an app-specific password can't sign in here.")]
    BadCredentials,
    #[error("Apple has locked this Apple Account for security. Unlock it at iforgot.apple.com, then sign in here again.")]
    AccountLocked,
    #[error("That code didn't match. Check your iPhone and try again.")]
    BadCode,
    #[error("Apple didn't return a trust token, so this session wouldn't survive a restart")]
    NoTrustToken,
    #[error("this account signs in a way Skykeep can't handle yet ({0})")]
    UnsupportedAccount(String),
    /// Apple wants something finished on the account before it signs in anywhere new.
    #[error("Apple needs one more step on your Apple Account first. Sign in at account.apple.com, finish what it asks, then sign in here again.")]
    RepairNeeded,
    /// Said without the address, which carries account and client ids.
    #[error("couldn't reach Apple: {}", if .0.is_timeout() { "it took too long to answer" } else if .0.is_connect() { "check your connection" } else { "the connection dropped" })]
    Network(#[from] reqwest::Error),
    #[error("Apple sent back something unexpected: {0}")]
    Protocol(String),
    /// Apple's servers answered but could not serve now — an outage, maintenance, too many
    /// requests (5xx, 429). Like being offline: try again later, never "signed out".
    #[error("Apple’s servers are busy right now. Try again in a few minutes.")]
    Unavailable(u16),
    #[error("Too many attempts. Try again in {seconds} seconds.")]
    CoolingDown { seconds: u64 },
    #[error("this needs a fresh sign-in — Apple won't accept a resumed session for it")]
    ReauthRequired,
    /// Apple keeps this account on its regional servers and this session has moved there, but
    /// Apple wants a sign-in made there: whoever holds the password signs in again (issue #10).
    #[error("Apple keeps this Apple Account on your region's iCloud servers. Sign in again to continue there.")]
    Moved,
    /// [`Error::Moved`] met after a code: signed in again there, and Apple sent a new code.
    #[error("Apple keeps this Apple Account on your region's iCloud servers, and has sent a new code for them. Enter the new code.")]
    CodeAgain,
    // Apple's 429 and its 503 on sign-in both mean "not now", whether from too many tries or
    // its own load: say what to do, not which of the two it was.
    #[error(
        "Apple asked to wait before signing in again. Try again in a few minutes: trying \
             again right away can make Apple lock the account for a while."
    )]
    RateLimited,
    /// Said as what to do: the keyring's own words (a D-Bus error name, a Win32 code) are for
    /// the log, and stay in the value.
    #[error("{}", keyring_words())]
    Keyring(String),
    #[error(transparent)]
    Io(#[from] std::io::Error),
    #[error(transparent)]
    Json(#[from] serde_json::Error),
}

type Result<T> = std::result::Result<T, Error>;

/// What a keyring that would not answer means to the person in front of it.
#[cfg(windows)]
pub const KEYRING_WORDS: &str = "Windows Credential Manager didn’t answer. Try again in a moment.";
#[cfg(not(windows))]
pub const KEYRING_WORDS: &str =
    "Your system keyring is locked or not running. Unlock or start GNOME Keyring or KWallet, then try again.";

/// In the Snap, the keyring is reached through the password-manager-service interface, which
/// snapd never connects by itself (its base declaration denies auto-connection). Unconnected,
/// every keyring call is refused whatever state the keyring is in, so "locked" would send the
/// person to the wrong fix.
#[cfg(not(windows))]
pub const SNAP_KEYRING_WORDS: &str = "Skykeep needs your permission to use the system keyring. In a terminal, run: sudo snap connect skykeep:password-manager-service — then try again.";

/// What a keyring that would not answer means here: [`KEYRING_WORDS`], or inside the Snap
/// [`SNAP_KEYRING_WORDS`].
pub fn keyring_words() -> &'static str {
    #[cfg(not(windows))]
    if std::env::var_os("SNAP_NAME").is_some_and(|n| n == "skykeep") {
        return SNAP_KEYRING_WORDS;
    }
    KEYRING_WORDS
}

/// A reply that says "not now" rather than "no": Apple's servers failing or overloaded.
fn transient(status: reqwest::StatusCode) -> Option<Error> {
    (status.is_server_error() || status.as_u16() == 429)
        .then(|| Error::Unavailable(status.as_u16()))
}

/// Apple returns `{"serviceErrors":[{"code":"-21669","message":"..."}]}` on failures.
/// Surface its own words; a bare status code explains nothing.
fn apple_error(context: &str, status: StatusCode, body: &str) -> Error {
    if status == StatusCode::TOO_MANY_REQUESTS || status == StatusCode::SERVICE_UNAVAILABLE {
        return Error::RateLimited;
    }
    // 450 is Apple's "re-authenticate for this service": a resumed session is not enough.
    if status.as_u16() == 450 {
        return Error::ReauthRequired;
    }
    // An outage or maintenance: its body is a web page, never words for the person signing in.
    if status.is_server_error() {
        return Error::Unavailable(status.as_u16());
    }
    let parsed: Option<Value> = serde_json::from_str(body).ok();
    if let Some(v) = &parsed {
        if let Some(errs) = v["serviceErrors"].as_array().filter(|a| !a.is_empty()) {
            let code = errs[0]["code"].as_str().unwrap_or("");
            let message = errs[0]["message"].as_str().unwrap_or("").trim();
            // -21669 is Apple's "incorrect verification code".
            if code == "-21669" {
                return Error::BadCode;
            }
            // -20209 is Apple's "locked for security reasons", most often after many tries.
            if code == "-20209" {
                return Error::AccountLocked;
            }
            if message.to_ascii_lowercase().contains("too many") {
                return Error::RateLimited;
            }
            if !message.is_empty() {
                return Error::Protocol(format!(
                    "{context}: {message} (Apple code {code}, HTTP {status})"
                ));
            }
        }
    }
    let snippet: String = body
        .chars()
        .take(220)
        .collect::<String>()
        .replace('\n', " ");
    Error::Protocol(format!("{context}: HTTP {status} {snippet}"))
}

/// Apple turning the password down (a 401, or a 403 before the password was even tried) —
/// unless its own code in the reply says why it really refused.
///
/// A locked account is a 403 or 401 with code -20209 (timlaing/pyicloud#368,
/// icloud_photos_downloader#1010). Read as a wrong password, a lapsed session signing itself
/// back in threw away the password it keeps, so the account was locked *and* signed out, and
/// the person was told to check a password that was right.
fn refused_password(context: &str, status: StatusCode, body: &str) -> Error {
    match apple_error(context, status, body) {
        e @ (Error::AccountLocked | Error::RateLimited) => e,
        _ => Error::BadCredentials,
    }
}

/// A phone Apple will send a code to, when no trusted device responds.
#[derive(Debug, Clone, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TrustedPhone {
    pub id: u64,
    /// Already masked by Apple, e.g. "+91 ••••• ••123".
    pub masked_number: String,
    /// How Apple reaches this number: `sms`, or `voice` for a number it calls (a landline).
    /// Sent back as it came (timlaing/pyicloud#210): Apple takes a code for a number the way
    /// it sends one there.
    pub mode: String,
    /// Apple's `nonFTEU` flag on the number, sent back with it when Apple gave one.
    #[serde(skip)]
    pub non_fteu: Option<bool>,
}

impl TrustedPhone {
    /// The `phoneNumber` Apple's phone endpoints take for this number.
    fn as_payload(&self) -> Value {
        let mut phone = json!({ "id": self.id });
        if let Some(flag) = self.non_fteu {
            phone["nonFTEU"] = Value::Bool(flag);
        }
        phone
    }
}

/// What Apple's `GET /appleauth/auth` answered, as JSON: the reply itself, or — when Apple
/// sends its sign-in page instead — the JSON that page carries in its `boot_args` script
/// (timlaing/pyicloud#322).
fn auth_options_of(text: &str) -> Value {
    if let Ok(v) = serde_json::from_str::<Value>(text) {
        return v;
    }
    let Some(at) = text.find("boot_args") else {
        return Value::Null;
    };
    let rest = &text[at..];
    rest.find('>')
        .map(|open| &rest[open + 1..])
        .and_then(|body| body.find("</script").map(|end| &body[..end]))
        .and_then(|json| serde_json::from_str(json.trim()).ok())
        .unwrap_or(Value::Null)
}

/// Every place Apple has kept the two-factor details in that reply: at the top, and — since
/// its 2026 sign-in — under `phoneNumberVerification`, `direct.twoSV`, and
/// `direct.twoSV.bridgeInitiateData.phoneNumberVerification` (icloud_photos_downloader#1335,
/// timlaing/pyicloud#322).
fn two_factor_places(v: &Value) -> Vec<&Value> {
    let two_sv = v.pointer("/direct/twoSV");
    [
        Some(v),
        v.get("phoneNumberVerification"),
        v.get("direct"),
        two_sv,
        two_sv.and_then(|t| t.get("phoneNumberVerification")),
        two_sv.and_then(|t| t.pointer("/bridgeInitiateData/phoneNumberVerification")),
    ]
    .into_iter()
    .flatten()
    .filter(|p| p.is_object())
    .collect()
}

/// The trusted phones in Apple's two-factor reply, wherever it kept them, each once.
///
/// Read only at the top, an account whose numbers Apple had moved inward showed "Apple has
/// nowhere to send a code" — for someone with no other device, no way to sign in at all.
fn trusted_phones(v: &Value) -> Vec<TrustedPhone> {
    let mut phones: Vec<TrustedPhone> = Vec::new();
    for place in two_factor_places(v) {
        let listed = place
            .get("trustedPhoneNumbers")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
            .chain(place.get("trustedPhoneNumber").filter(|p| p.is_object()));
        for p in listed {
            let id = p["id"]
                .as_u64()
                .or_else(|| p["id"].as_str().and_then(|s| s.trim().parse().ok()));
            let Some(id) = id else { continue };
            if phones.iter().any(|known| known.id == id) {
                continue;
            }
            phones.push(TrustedPhone {
                id,
                masked_number: p["numberWithDialCode"]
                    .as_str()
                    .or_else(|| p["obfuscatedNumber"].as_str())
                    .unwrap_or("(hidden)")
                    .to_string(),
                mode: p["pushMode"]
                    .as_str()
                    .map(str::trim)
                    .filter(|m| !m.is_empty())
                    .unwrap_or("sms")
                    .to_string(),
                non_fteu: p["nonFTEU"].as_bool(),
            });
        }
    }
    phones
}

/// Where Apple is willing to send a code. Read after a `NeedsTwoFactor` outcome.
#[derive(Debug, Clone, Default, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TwoFactorOptions {
    /// Devices Apple pushed the code to. Zero means nothing will arrive on its own.
    pub trusted_device_count: u64,
    pub phones: Vec<TrustedPhone>,
    /// Apple refuses further sends for a while.
    pub too_many_codes_sent: bool,
    /// The account signs in with security keys (FIDO): Apple offers a WebAuthn challenge
    /// (`fsaChallenge`) in place of a code (icloudpd#583, #1423). Skykeep cannot answer one yet,
    /// so the code screen says so rather than waiting for a code that will not come.
    pub security_key: bool,
}

/// Whether Apple's two-factor answer offers a security-key challenge: `fsaChallenge` with its
/// `challenge`, `keyHandles` and `rpId`, as icloudpd reads it.
fn offers_security_key(v: &Value) -> bool {
    let c = &v["fsaChallenge"];
    c.is_object()
        && ["challenge", "keyHandles", "rpId"].iter().all(|k| {
            let x = &c[*k];
            !x.is_null() && x.as_str() != Some("") && x.as_array().is_none_or(|a| !a.is_empty())
        })
}

/// What `sign_in` decided.
#[derive(Debug, PartialEq, Eq)]
pub enum SignInOutcome {
    /// Signed in. Apple already trusted this install.
    Complete,
    /// Apple wants a six-digit code. Call [`Client::submit_two_factor`] next.
    NeedsTwoFactor,
}

/// Apple's SRP challenge, from `/signin/init` or `/escrow/init`.
struct Challenge {
    salt: Vec<u8>,
    b_pub: Vec<u8>,
    c: String,
    iterations: u32,
    protocol: srp::Protocol,
}

impl Challenge {
    fn of(init: &Value) -> Result<Self> {
        let decode = |key: &str| -> Result<Vec<u8>> {
            let raw = init[key]
                .as_str()
                .ok_or_else(|| Error::Protocol(format!("sign-in response had no `{key}`")))?;
            B64.decode(raw)
                .map_err(|_| Error::Protocol(format!("`{key}` wasn't valid base64")))
        };
        let salt = decode("salt")?;
        let b_pub = decode("b")?;
        let c = init["c"]
            .as_str()
            .ok_or_else(|| Error::Protocol("sign-in response had no `c`".into()))?
            .to_string();
        let iterations = {
            let raw = init["iteration"]
                .as_u64()
                .ok_or_else(|| Error::Protocol("sign-in response had no `iteration`".into()))?;
            u32::try_from(raw)
                .ok()
                .filter(|n| (MIN_PBKDF2_ITERATIONS..=MAX_PBKDF2_ITERATIONS).contains(n))
                .ok_or_else(|| {
                    Error::Protocol(format!(
                        "Apple asked for an implausible {raw} key-derivation rounds"
                    ))
                })?
        };
        let protocol_name = init["protocol"].as_str().unwrap_or("s2k");
        let protocol = srp::Protocol::parse(protocol_name)
            .ok_or_else(|| Error::UnsupportedAccount(format!("SRP protocol {protocol_name}")))?;
        Ok(Self {
            salt,
            b_pub,
            c,
            iterations,
            protocol,
        })
    }
}

/// Whether Apple wants its escrow step: `X-Apple-EDP` or `X-Apple-PDP` on a 409 (icloud-photos-
/// sync#1124, rclone#10048). Since iOS 26.4 Apple asks for it after an accepted code, and when
/// a sign-in presents a trust token it accepts — and until it is done it does not honour the
/// trust token, so every later sign-in looks as if it needs a code again.
fn wants_escrow(response: &Response) -> bool {
    let h = response.headers();
    h.contains_key("x-apple-edp") || h.contains_key("x-apple-pdp")
}

/// Whether a sign-in that Apple wants a code for asks Apple to send it now.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Code {
    /// The person just typed their password and the code screen is next: ask.
    Send,
    /// Nobody is watching (a lapse mended in the background): leave it to the code screen.
    Wait,
}

/// OAuth headers every idmsa call carries. Deliberately sets no Origin: the HTTP client
/// defaults to the icloud.com origin, which is what the verify, trust and phone endpoints
/// expect. Only SRP overrides it — see [`with_srp_origin`].
/// Two secrets compared without the time taken saying how much of one matched.
fn same_secret(a: &[u8], b: &[u8]) -> bool {
    a.len() == b.len() && a.iter().zip(b).fold(0u8, |d, (x, y)| d | (x ^ y)) == 0
}

fn base_oauth_headers(
    client_id: &str,
    home: &str,
    scnt: Option<&str>,
    session_id: Option<&str>,
) -> HeaderMap {
    let mut h = HeaderMap::new();
    let mut put = |k: &'static str, v: &str| {
        if let Ok(val) = HeaderValue::from_str(v) {
            h.insert(HeaderName::from_static(k), val);
        }
    };
    put("accept", "application/json, text/javascript, */*; q=0.01");
    put("content-type", "application/json");
    put("x-apple-oauth-client-id", WIDGET_KEY);
    put("x-apple-oauth-client-type", "firstPartyAuth");
    put("x-apple-oauth-redirect-uri", home);
    put("x-apple-oauth-require-grant-code", "true");
    put("x-apple-oauth-response-mode", "web_message");
    put("x-apple-oauth-response-type", "code");
    put("x-apple-oauth-state", client_id);
    put("x-apple-widget-key", WIDGET_KEY);
    if let Some(v) = scnt {
        put("scnt", v);
    }
    if let Some(v) = session_id {
        put("x-apple-id-session-id", v);
    }
    h
}

/// `/signin/init` and `/signin/complete` are served from idmsa and reject the icloud.com
/// origin. Applying this anywhere else earns a 409.
fn with_srp_origin(mut h: HeaderMap, auth_root: &str) -> HeaderMap {
    if let Ok(v) = HeaderValue::from_str(auth_root) {
        h.insert("origin", v);
    }
    if let Ok(v) = HeaderValue::from_str(&format!("{auth_root}/")) {
        h.insert("referer", v);
    }
    h
}

pub struct Client {
    http: HttpClient,
    jar: Arc<CookieStoreMutex>,
    store: Store,
    session: Session,
    endpoints: Endpoints,
    /// iCloud.com's servers, and Apple's regional ones: where [`Client::switch_servers`] goes.
    home_endpoints: Endpoints,
    regional_endpoints: Endpoints,
    /// A sign-in in flight: its password, kept only once the sign-in completes, and the code
    /// Apple wants for it (see [`state::SignIn`]).
    sign: state::SignIn,
    /// The keyring would not answer when this started — locked, or not up yet. Not the same
    /// as nothing stored: it is asked again before anything else happens.
    keyring_error: Option<String>,
    /// The session signed in, or taken up, but the keyring would not keep it (none running:
    /// a window manager without one, a session over SSH): held in memory for as long as
    /// Skykeep runs, and written again at every heartbeat until a keyring takes it.
    unsaved: Option<String>,
    /// What was last written, as a hash of the session and one of the cookies: a heartbeat that
    /// changed neither writes neither (see [`Client::persist`]).
    persisted: std::sync::Mutex<Persisted>,
    /// The cookies on disk, as this start found them (see [`read_jar`]).
    cookies: Cookies,
    /// The trusted phones Apple last listed, so a code is sent to and checked for each number
    /// the way that number takes one.
    phones: Vec<TrustedPhone>,
    /// What this run knows of Advanced Data Protection approvals (see [`pcs`]).
    pcs: pcs::Pcs,
}

/// What became of the cookies kept on disk when the client started.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Cookies {
    /// Read, or there were none.
    Read,
    /// Sealed, and the keyring would not answer for their key — locked, or not up yet. The file
    /// is left as it is and read again once the keyring answers.
    Unread,
    /// Sealed, and could not be opened: the keyring no longer holds their key (it was reset),
    /// or the file was changed. Set aside; the session carries on from its tokens.
    SetAside,
}

/// The cookie jar kept on disk, opened, and what became of the file.
///
/// A sealed file is opened with its key from the keyring. One that cannot be — no key, a key
/// that does not fit, a version this build does not know, a changed byte — is deleted, never
/// a reason to fail: the cookies only save a round trip, and the tokens the keyring holds open
/// a new set (see [`Client::resume`]).
///
/// A jar from before sealing (plain JSON) is read once and sealed in its place, or, with no
/// keyring to keep a key, deleted — its cookies held in memory for as long as Skykeep runs and
/// sealed by the first write a keyring takes. Either way no plaintext is left behind: the sealed
/// file is renamed over it, so the plain one is never there beside it.
fn read_jar(store: &Store) -> (cookie_store::CookieStore, Cookies) {
    let path = store.cookie_path();
    let parse = |json: &[u8]| cookie_store::serde::json::load(json).ok();
    let Ok(bytes) = std::fs::read(path) else {
        return (cookie_store::CookieStore::default(), Cookies::Read);
    };
    let set_aside = |why: &str| {
        quiet!("quince: the saved cookies were set aside: {why}");
        let _ = std::fs::remove_file(path);
        (cookie_store::CookieStore::default(), Cookies::SetAside)
    };
    if sealed::is_sealed(&bytes) {
        return match store.cookie_key() {
            Ok(Some(key)) => match sealed::open(&key, &bytes) {
                Ok(json) => match parse(&json) {
                    Some(jar) => (jar, Cookies::Read),
                    None => set_aside("they were not a cookie jar"),
                },
                Err(sealed::Unopened::Version(v)) => set_aside(&format!("unknown version {v}")),
                Err(sealed::Unopened::Damaged) => set_aside("they did not open with their key"),
            },
            Ok(None) => set_aside("the keyring no longer holds their key"),
            Err(e) => {
                quiet!("quince: the saved cookies wait for the keyring: {e}");
                (cookie_store::CookieStore::default(), Cookies::Unread)
            }
        };
    }
    // From before sealing: read once, then sealed in place or gone.
    let Some(jar) = parse(&bytes) else {
        let _ = std::fs::remove_file(path);
        return (cookie_store::CookieStore::default(), Cookies::Read);
    };
    let sealed_in_place = (|| -> Result<()> {
        let key = store.cookie_key_or_new()?;
        let json = jar_bytes(&jar)?;
        Ok(session::write_whole(
            path,
            &sealed::seal(&key, &json)?,
            true,
        )?)
    })();
    if let Err(e) = sealed_in_place {
        quiet!("quince: the cookies are kept in memory only: {e}");
        let _ = std::fs::remove_file(path);
    }
    (jar, Cookies::Read)
}

/// The jar as it is written to disk: every cookie that has not run out, Apple's session
/// cookies among them.
///
/// `cookie_store`'s own `save` keeps only cookies with an expiry, and Apple sets several of the
/// ones its sign-in leans on without one — idmsa's own, and some of icloud.com's. Each start
/// came back without them, so the next sign-in was a stranger's and Apple asked for a code
/// again, about every day. pyicloud and icloudpd keep them the same way (`LWPCookieJar.save(
/// ignore_discard=True)`), as a browser that restores its session does. They are a credential
/// like the rest of the jar, and sealed with it (see [`sealed`]).
fn jar_bytes(jar: &cookie_store::CookieStore) -> Result<Vec<u8>> {
    let cookies: Vec<&cookie_store::Cookie<'static>> = jar.iter_unexpired().collect();
    let mut out = serde_json::to_vec_pretty(&cookies)
        .map_err(|e| Error::Protocol(format!("couldn't save cookies: {e}")))?;
    out.push(b'\n');
    Ok(out)
}

/// Hashes of the session and the cookie jar as last written; `None` for not written yet.
#[derive(Default)]
struct Persisted {
    session: Option<u64>,
    cookies: Option<u64>,
}

fn hash_of(bytes: &[u8]) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut h = std::collections::hash_map::DefaultHasher::new();
    bytes.hash(&mut h);
    h.finish()
}

/// Apple's client for an account at `endpoints`: their web origin on every request (what
/// setup.icloud.com and the service endpoints expect; the idmsa sign-in calls name their own),
/// the cookie jar the session keeps, and the rest every connection to Apple gets.
fn apple_client(endpoints: &Endpoints, jar: &Arc<CookieStoreMutex>) -> Result<HttpClient> {
    // The account's web origin — what setup and the service endpoints expect. The idmsa SRP
    // endpoints want their own origin and override it per request.
    let mut defaults = HeaderMap::new();
    if let Ok(v) = HeaderValue::from_str(&endpoints.home) {
        defaults.insert("origin", v);
    }
    if let Ok(v) = HeaderValue::from_str(&format!("{}/", endpoints.home)) {
        defaults.insert("referer", v);
    }
    defaults.insert(
        "accept-language",
        HeaderValue::from_static("en-US,en;q=0.9"),
    );

    // Never waits for ever. After a sleep or a change of network a pooled connection can
    // be dead without saying so, and a request on it hung until the kernel gave up — a
    // quarter of an hour or more — holding the sign-in lock, so every screen waited too.
    // A read that brings nothing for a minute is given up (a long download keeps going as
    // long as bytes arrive); idle connections are let go of before they can go stale; and
    // keep-alives notice a dead one.
    apple_only()
        // The jar itself, telling diagnostics (when the person turned them on) which
        // cookies go out and come back, by name.
        .cookie_provider(Arc::new(diag::Told(Arc::clone(jar))))
        .user_agent(UA)
        .default_headers(defaults)
        .connect_timeout(std::time::Duration::from_secs(15))
        .read_timeout(std::time::Duration::from_secs(60))
        .pool_idle_timeout(std::time::Duration::from_secs(50))
        .tcp_keepalive(std::time::Duration::from_secs(30))
        .build()
        .map_err(Error::from)
}

impl Client {
    pub fn new(state_dir: &Path) -> Result<Self> {
        Self::with(state_dir, Endpoints::default(), Store::keyring(state_dir)?)
    }

    /// Build a client against specific endpoints and a specific secret store.
    pub fn with(state_dir: &Path, endpoints: Endpoints, store: Store) -> Result<Self> {
        std::fs::create_dir_all(state_dir)?;
        let (session, keyring_error) = match store.try_load() {
            Ok(session) => (session, None),
            Err(e) => (session::Session::default(), Some(e.to_string())),
        };

        let (jar, cookies) = read_jar(&store);
        let jar = Arc::new(CookieStoreMutex::new(jar));

        // The account's own servers: iCloud.com's, or Apple's regional ones for an account
        // Apple keeps there (issue #10), unless a test pointed the client somewhere itself.
        let endpoints = if endpoints == Endpoints::default() {
            Endpoints::for_domain(session.domain.as_deref())
        } else {
            endpoints
        };
        open_regional(endpoints == Endpoints::for_domain(Some(REGIONAL_DOMAIN)));
        let http = apple_client(&endpoints, &jar)?;

        // Where switch_servers goes: a test's mock for both, unless it names another for the
        // regional servers; Apple's own otherwise.
        let home_endpoints = if endpoints == Endpoints::for_domain(Some(REGIONAL_DOMAIN)) {
            Endpoints::default()
        } else {
            endpoints.clone()
        };
        let regional_endpoints = if home_endpoints == Endpoints::default() {
            Endpoints::for_domain(Some(REGIONAL_DOMAIN))
        } else {
            home_endpoints.clone()
        };
        Ok(Self {
            http,
            jar,
            store,
            session,
            endpoints,
            home_endpoints,
            regional_endpoints,
            sign: state::SignIn::Idle,
            keyring_error,
            unsaved: None,
            persisted: std::sync::Mutex::new(Persisted::default()),
            cookies,
            phones: Vec::new(),
            pcs: pcs::Pcs::default(),
        })
    }

    /// Said when the cookies kept on disk could not be opened and were set aside — the keyring
    /// was reset, or the file changed. Nothing else is lost: Skykeep carries on from the
    /// session the keyring holds, and asks for a sign-in only if that is gone too.
    #[must_use]
    pub fn cookies_set_aside(&self) -> Option<&'static str> {
        (self.cookies == Cookies::SetAside).then_some(
            "Skykeep couldn't open its saved connection to iCloud, so it set it aside. \
             If you're asked to sign in again, that's all it takes — your library is untouched.",
        )
    }

    /// Cookies left unread at the start because the keyring would not answer, read now that it
    /// may — into a jar nothing has filled since, never over cookies newer than the file.
    fn read_cookies_again(&mut self) {
        if self.cookies != Cookies::Unread {
            return;
        }
        let (jar, cookies) = read_jar(&self.store);
        if cookies == Cookies::Unread {
            return;
        }
        self.cookies = cookies;
        let mut held = self
            .jar
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if held.iter_any().next().is_none() {
            *held = jar;
        }
    }

    /// A lapsed session tried to sign itself back in, and Apple wants a code before it will
    /// trust this computer again. The code screen is the next thing to show.
    #[must_use]
    pub fn awaiting_code(&self) -> bool {
        self.sign.awaiting_code()
    }

    pub fn session(&self) -> &Session {
        &self.session
    }

    /// True when a stored session exists and is worth trying.
    ///
    /// A keyring that would not answer at the start (locked, or not up yet at login) may well
    /// hold one: sealed cookies on disk say a keyring kept a session here before. Then it is
    /// worth a resume, which asks the keyring again — and where it is locked, that is what
    /// brings up its unlock prompt — rather than a sign-in screen that would replace it.
    pub fn has_stored_session(&self) -> bool {
        self.session.is_resumable()
            || (self.keyring_error.is_some() && self.store.cookie_path().exists())
    }

    // ---- persistence ----------------------------------------------------------------

    fn capture(&mut self, response: &Response) {
        diag::answer(response.url(), response.status());
        for (header, field) in CAPTURED_HEADERS {
            if let Some(v) = response
                .headers()
                .get(*header)
                .and_then(|v| v.to_str().ok())
            {
                self.session.set(*field, v.to_string());
            }
        }
    }

    /// Keep the session and its cookies where the next start finds them — each only when it
    /// differs from what was last written.
    ///
    /// Every heartbeat, so every sync and every return to the window, wrote the session to the
    /// keyring: several D-Bus writes, deletes of old names and a read-back, all while holding
    /// the sign-in lock, for a session that had not changed. Only a write that went through is
    /// remembered, so one that failed is made again next time.
    fn persist(&self) -> Result<()> {
        let session = serde_json::to_vec(&self.session)
            .map_err(|e| Error::Protocol(format!("couldn't save the session: {e}")))?;
        let cookies = {
            let jar = self
                .jar
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            jar_bytes(&jar)?
        };
        let (session, cookies) = (hash_of(&session), (hash_of(&cookies), cookies));
        let mut last = self
            .persisted
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if last.session != Some(session) {
            self.store.save(&self.session)?;
            last.session = Some(session);
        }
        if last.cookies != Some(cookies.0) {
            self.write_cookies(&cookies.1)?;
            last.cookies = Some(cookies.0);
        }
        Ok(())
    }

    /// [`Self::persist`] once Apple has accepted the session: a keyring that will not take it
    /// never undoes that.
    ///
    /// With no Secret Service at all, the password went through, then the write failed and
    /// the sign-in failed with it — before the code was even asked for — so a machine without
    /// a keyring could never sign in, not just never stay signed in. The session is kept in
    /// memory instead, said so ([`Self::unsaved`]), and written again on the next heartbeat.
    /// A live session in memory is newer than anything the keyring holds, so a keyring that
    /// would not answer at the start is not asked to replace it either.
    fn keep(&mut self) {
        self.keyring_error = None;
        // Never an empty jar written over cookies the keyring could not open at the start.
        self.read_cookies_again();
        match self.persist() {
            Ok(()) => self.unsaved = None,
            Err(e) => {
                quiet!("quince: the session is kept in memory only: {e:?}");
                self.unsaved = Some(e.to_string());
            }
        }
    }

    /// Why the session is held in memory only, when a keyring would not keep it: Skykeep
    /// stays signed in while it runs, but not after it closes.
    #[must_use]
    pub fn unsaved(&self) -> Option<&str> {
        self.unsaved.as_deref()
    }

    /// The cookie jar, as `cookie_store` wrote it, sealed to its file (see [`sealed`]).
    ///
    /// With no keyring to keep the key nothing is written: the cookies stay in memory, as the
    /// session does, and are sealed by the first write a keyring takes. Never in the clear.
    fn write_cookies(&self, cookies: &[u8]) -> Result<()> {
        let key = self.store.cookie_key_or_new()?;
        // The session's cookies are a credential: readable by this user alone as well, whatever
        // folder they end up in (a backup, a copy), not only by the private data folder.
        Ok(session::write_whole(
            self.store.cookie_path(),
            &sealed::seal(&key, cookies)?,
            true,
        )?)
    }

    /// Forget this account entirely.
    pub fn sign_out(&mut self) -> Result<()> {
        self.session = Session::default();
        // The next account starts at iCloud.com, and the regional domains close again.
        self.switch_servers(None)?;
        self.data_access_forget();
        if let Ok(mut jar) = self.jar.lock() {
            jar.clear();
        }
        // Nothing is stored any more: the next session is written whatever it is.
        *self
            .persisted
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner) = Persisted::default();
        self.store.clear()
    }

    // ---- headers --------------------------------------------------------------------

    fn auth_headers(&mut self) -> HeaderMap {
        let client_id = self.session.client_id();
        base_oauth_headers(
            &client_id,
            &self.endpoints.home,
            self.session.scnt.as_deref(),
            self.session.session_id.as_deref(),
        )
    }

    /// Headers for `/signin/init` and `/signin/complete` only.
    ///
    /// Those two are served from idmsa and reject the icloud.com origin. Every other auth
    /// endpoint — verify, trust, phone — wants the icloud.com origin the client defaults to.
    fn srp_headers(&mut self) -> HeaderMap {
        let h = self.auth_headers();
        with_srp_origin(h, &self.endpoints.auth_root)
    }

    /// Headers for `/signin/init` specifically.
    ///
    /// Deliberately omits `scnt` and the session id: the flow has not issued them yet, and
    /// sending leftovers from an abandoned challenge is a conflict.
    fn srp_init_headers(&mut self) -> HeaderMap {
        let client_id = self.session.client_id();
        let h = base_oauth_headers(&client_id, &self.endpoints.home, None, None);
        with_srp_origin(h, &self.endpoints.auth_root)
    }

    /// Drop transient challenge state, keeping what identifies this install.
    ///
    /// `trust_token` and `client_id` survive — they are what lets Apple skip 2FA next time.
    /// Everything else belongs to a single sign-in attempt and must not leak into the next.
    fn clear_challenge_state(&mut self) {
        self.session.scnt = None;
        self.session.session_id = None;
        self.session.session_token = None;
    }

    // ---- the restart test -----------------------------------------------------------

    /// Try to resume a stored session without a password.
    ///
    /// Returns `Ok(true)` when the stored session still works — the behaviour the whole
    /// product promises. `Ok(false)` means Apple rejected it and a full sign-in is needed;
    /// that is an expected outcome (roughly every 60 days), not a failure.
    pub async fn resume(&mut self) -> Result<bool> {
        // A keyring that would not answer at startup is asked again; still locked, that is
        // what is said — never "signed out", which led to a sign-in replacing what it holds.
        if self.keyring_error.is_some() {
            match self.store.try_load() {
                Ok(session) => {
                    self.session = session;
                    self.keyring_error = None;
                }
                Err(e) => {
                    quiet!("quince: keyring: still not answering: {e:?}");
                    return Err(e);
                }
            }
        }
        self.read_cookies_again();
        if !self.session.is_resumable() {
            return Ok(false);
        }
        // Cheap path: the cookies are still good, so nothing needs re-establishing.
        let validated = match self.validate().await {
            Ok(data) => {
                self.absorb(&data);
                self.keep();
                return Ok(true);
            }
            Err(e) => e,
        };

        // The cookies are missing or stale but the tokens are not. Apple's service endpoints
        // authenticate by cookie — without X-APPLE-WEBAUTH-USER they answer 421 — so trade
        // the stored tokens for a fresh set. No password, no code.
        //
        // This is what makes staying signed in survive a lost cookie file, a copied install,
        // or cookies expiring before the trust token does.
        let logged_in = match self.account_login().await {
            Ok(data) => {
                self.absorb(&data);
                self.keep();
                return Ok(true);
            }
            // New iCloud terms waiting are not a lapse: `absorb` keeps Apple's flag and the
            // session stays, so nothing signs in again with the password into the same terms.
            Err(e) => e,
        };
        // Unreachable is not rejected. Offline — no network yet after login, or a resume
        // from sleep mid-reconnect — the session is left exactly as it is and the caller
        // told so; signing in again here cleared the session token, failed on the network,
        // and saved the cleared state, so every launch after showed the sign-in screen.
        // Offline, or Apple down for a while: the session is not dead, only unreachable — it
        // is kept and tried again, rather than a sign-in that ends in "Apple signed you out".
        let away = |e: &Error| matches!(e, Error::Network(_) | Error::Unavailable(_));
        if away(&validated) && away(&logged_in) {
            return Err(logged_in);
        }

        // The session token has lapsed too — Apple keeps one for days, not months. With the
        // password kept, sign in again: this computer is still trusted, so Apple asks for no
        // code, and nobody sees a sign-in screen. Only when the trust itself has run out
        // (about two months) does Apple want a code, and then the code screen is what shows.
        if let (Some(apple_id), Some(password)) =
            (self.session.apple_id.clone(), self.session.password.clone())
        {
            let before = self.session.clone();
            // Quietly: a code is asked for only once the person is at the code screen. Asked
            // for here, every lapse — the heartbeat's, a sync's, a launch at login — put an
            // "Allow sign-in?" and a code on their phone while they were nowhere near Skykeep.
            match self.sign_in_as(&apple_id, &password, Code::Wait).await {
                Ok(SignInOutcome::Complete) => return Ok(true),
                // Lost the network part way, or Apple busy, down or asking to wait: not a
                // refusal. What was kept is put back as it was and the next try is left to
                // later — read as signed out, an outage told the person "Apple signed you
                // out" and dropped the session token.
                Err(
                    e @ (Error::Network(_)
                    | Error::Unavailable(_)
                    | Error::RateLimited
                    | Error::CoolingDown { .. }),
                ) => {
                    self.session = before;
                    let _ = self.persist();
                    return Err(e);
                }
                Ok(SignInOutcome::NeedsTwoFactor) => {
                    self.sign.wants_code(true);
                    return Ok(false);
                }
                // The password was changed elsewhere: the kept one is worthless now.
                Err(Error::BadCredentials) => {
                    self.session.password = None;
                    self.keep();
                }
                Err(_) => {}
            }
        }

        // Genuinely dead. Drop the challenge state so it cannot contaminate the sign-in that
        // follows.
        self.clear_challenge_state();
        Ok(false)
    }

    /// `POST /validate` — cheap liveness check. Doubles as the session heartbeat.
    async fn validate(&mut self) -> Result<Value> {
        let r = self
            .http
            .post(format!("{}/validate", self.endpoints.setup))
            .header("content-type", "application/json")
            .body("null")
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let body = r.text().await.unwrap_or_default();
        if !status.is_success() {
            return Err(transient(status)
                .unwrap_or_else(|| Error::Protocol(format!("validate returned {status}"))));
        }
        let data = serde_json::from_str(&body).unwrap_or(Value::Null);
        diag::account("validate", &data);
        Ok(data)
    }

    /// Keep the session warm.
    ///
    /// Apple resets auth cookies on long idle gaps; icloudpd's field experience is that
    /// roughly hourly contact keeps them alive. Cheap enough to run on a timer.
    pub async fn heartbeat(&mut self) -> Result<bool> {
        match self.validate().await {
            Ok(_) => {
                self.keep();
                Ok(true)
            }
            // Cookies lapse after an idle spell long before the session does. Giving up here
            // left a running window signed out for good — every refresh failing quietly —
            // when the stored tokens, or the kept password, would have carried on.
            Err(_) => self.resume().await,
        }
    }

    // ---- sign-in --------------------------------------------------------------------

    /// Sign in with an Apple ID and password, over SRP.
    ///
    /// The password is never sent to Apple — SRP proves knowledge of it without transmitting
    /// it. Apple retired the old cleartext endpoint; it now answers 503.
    pub async fn sign_in(&mut self, apple_id: &str, password: &str) -> Result<SignInOutcome> {
        self.sign_in_as(apple_id, password, Code::Send).await
    }

    /// [`Self::sign_in`], saying whether a code Apple wants is asked for now.
    async fn sign_in_as(
        &mut self,
        apple_id: &str,
        password: &str,
        code: Code,
    ) -> Result<SignInOutcome> {
        // What this account already owes, from beside the cookies rather than from the
        // keyring — so a machine with no keyring still remembers, which is where forgetting
        // would matter most. Per account, so signing in as somebody else inherits nothing.
        let owed = self.store.cooldown_for(apple_id);
        self.session.consecutive_failures = owed.consecutive_failures;
        self.session.retry_after = owed.retry_after;

        // Kept only once Apple has accepted it all the way: see `absorb`.
        self.sign.start(apple_id, password);
        let mut outcome = self.sign_in_inner(apple_id, password, code).await;
        // Apple keeps the account on its regional servers and wants the sign-in made there:
        // made again there, once — this session now starts at Apple's servers for it.
        if matches!(outcome, Err(Error::Moved)) {
            self.sign.start(apple_id, password);
            outcome = self.sign_in_inner(apple_id, password, code).await;
        }
        if outcome.is_err() {
            self.sign.fail();
        }
        match &outcome {
            // Reaching the two-factor step means the password was accepted: not a failure.
            Ok(_) => {
                self.session.consecutive_failures = 0;
                self.session.retry_after = None;
            }
            // Only Apple turning the attempt down counts. Not reaching Apple, or this computer
            // failing afterwards (a keyring that would not take the session), is no wrong
            // password: counted, it held a person back from trying again once it was fixed.
            Err(
                Error::CoolingDown { .. }
                | Error::Network(_)
                | Error::Keyring(_)
                | Error::Io(_)
                | Error::Json(_)
                | Error::RepairNeeded
                | Error::Moved
                | Error::CodeAgain,
            ) => {}
            Err(e) => {
                self.session.consecutive_failures =
                    self.session.consecutive_failures.saturating_add(1);
                // Apple saying "slow down" outranks our own schedule.
                let wait = if matches!(e, Error::RateLimited) {
                    backoff_seconds(u32::MAX)
                } else {
                    backoff_seconds(self.session.consecutive_failures)
                };
                self.session.retry_after = (wait > 0).then(|| unix_now() + wait);
            }
        }
        // Written on its own and first. `persist` needs the keyring and is allowed to fail;
        // the wait must be remembered either way, or a machine without a keyring forgets it
        // every time the window closes and somebody can go on hammering Apple until the
        // account they are trying to reach is locked.
        let _ = self.store.save_cooldown(&crate::session::Cooldown {
            account: Some(crate::session::account_fingerprint(apple_id)),
            consecutive_failures: self.session.consecutive_failures,
            retry_after: self.session.retry_after,
        });
        let _ = self.persist();
        outcome
    }

    async fn sign_in_inner(
        &mut self,
        apple_id: &str,
        password: &str,
        code: Code,
    ) -> Result<SignInOutcome> {
        // Refuse before touching Apple. Hammering sign-in is what gets an account
        // temporarily locked, and an impatient user clicking twice should not risk that.
        if let Some(seconds) = session::wait_left(self.session.retry_after, unix_now()) {
            return Err(Error::CoolingDown { seconds });
        }

        // Start clean. An interrupted previous attempt would otherwise announce a
        // half-finished session and Apple would reject this one as a conflict.
        self.clear_challenge_state();
        // A new web session: its encrypted services' keys are its own to ask for.
        self.data_access_forget();

        let client = srp::Client::new(apple_id);

        // --- /signin/init: send A, receive salt, B, protocol, iteration count ---
        let headers = self.srp_init_headers();
        let r = self
            .http
            .post(format!("{}/signin/init", self.endpoints.auth))
            .headers(headers)
            .body(
                json!({
                    "a": B64.encode(client.a_public_bytes()),
                    "accountName": apple_id,
                    "protocols": ["s2k", "s2k_fo"],
                })
                .to_string(),
            )
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let text = r.text().await.unwrap_or_default();
        if status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN {
            return Err(refused_password("starting sign-in", status, &text));
        }
        if !status.is_success() {
            return Err(apple_error("starting sign-in", status, &text));
        }
        let init: Value = serde_json::from_str(&text)?;
        let Challenge {
            salt,
            b_pub,
            c,
            iterations,
            protocol,
        } = Challenge::of(&init)?;

        // --- /signin/complete: submit the proof ---
        let proof = client
            .process_challenge(password, protocol, &salt, &b_pub, iterations)
            .ok_or_else(|| {
                Error::Protocol("Apple's sign-in challenge failed its safety check".into())
            })?;

        let mut body = json!({
            "accountName": apple_id,
            "c": c,
            "m1": B64.encode(proof.m1),
            "m2": B64.encode(proof.m2),
            "rememberMe": true,
            "trustTokens": [],
        });
        if let Some(t) = &self.session.trust_token {
            body["trustTokens"] = json!([t]);
        }

        let headers = self.srp_headers();
        let r = self
            .http
            .post(format!("{}/signin/complete", self.endpoints.auth))
            .query(&[("isRememberMeEnabled", "true")])
            .headers(headers)
            .body(body.to_string())
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let escrow = wants_escrow(&r);
        // This step's own reply: its serviceErrors say why Apple refused (a locked account,
        // a wrong password). The challenge from /signin/init is not the reason and is never shown.
        let text = if status.is_success() || status == StatusCode::CONFLICT {
            String::new()
        } else {
            r.text().await.unwrap_or_default()
        };

        match status {
            // Apple accepted this computer's trust token and wants its escrow step, not a code:
            // read as "a code", every lapse asked for one — about daily.
            StatusCode::CONFLICT if escrow && self.session.trust_token.is_some() => {
                self.complete_escrow(password).await?;
                let data = self.account_login().await?;
                self.absorb(&data);
                self.keep();
                Ok(SignInOutcome::Complete)
            }
            StatusCode::CONFLICT => {
                self.keep();
                // Ask for the code — when the person has just typed their password. Apple used
                // to push it to trusted devices on this 409 by itself; since iOS 26.4 it waits
                // to be asked (PUT verify/trusteddevice/securitycode), and until asked no
                // "Allow sign-in?" ever reaches a phone — which is why the only way a code ever
                // arrived here was Airplane Mode and Settings, or pressing "Send again". Not
                // fatal if it fails: the code screen still offers sending it again, and a text.
                //
                // A sign-in nobody is watching (a lapse mended in the background) asks for
                // nothing: the code screen asks once the person opens it ([`Self::request_code`]).
                self.sign.wants_code(false);
                if code == Code::Send {
                    if let Err(e) = self.resend_to_devices().await {
                        quiet!("asking Apple to send the code: {e}");
                    }
                }
                Ok(SignInOutcome::NeedsTwoFactor)
            }
            s if s.is_success() => {
                let data = self.account_login().await?;
                self.absorb(&data);
                self.keep();
                Ok(SignInOutcome::Complete)
            }
            StatusCode::UNAUTHORIZED => Err(refused_password("finishing sign-in", status, &text)),
            // "Precondition failed": Apple wants a step on the account finished first (seen right
            // after new iCloud terms, and on accounts without two-factor). icloudpd answers it
            // with an empty `POST repair/complete` and carries on; so does this.
            StatusCode::PRECONDITION_FAILED => {
                self.repair_complete().await?;
                let data = self.account_login().await?;
                self.absorb(&data);
                self.keep();
                Ok(SignInOutcome::Complete)
            }
            s => Err(apple_error("finishing sign-in", s, &text)),
        }
    }

    /// Where Apple can send a code, and whether it already pushed one.
    ///
    /// Worth reading whenever a code doesn't arrive: a `trusted_device_count` of zero means
    /// no push was ever sent and SMS is the only route.
    pub async fn two_factor_options(&mut self) -> Result<TwoFactorOptions> {
        let mut headers = self.auth_headers();
        headers.insert("accept", HeaderValue::from_static("application/json"));
        let r = self
            .http
            .get(&self.endpoints.auth)
            .headers(headers)
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let text = r.text().await.unwrap_or_default();
        // A reply Apple refused, or one that names no devices and no numbers at all, says
        // nothing about where a code can go. Read as "0 devices, no numbers" it told someone
        // with an iPhone and a number that their account had nowhere to send a code (reported
        // on X, 5 Nov 2026, after airplane-mode codes had failed): it is an error, and the code
        // screen falls back to its plain wording.
        if !status.is_success() {
            return Err(apple_error(
                "reading where Apple can send a code",
                status,
                &text,
            ));
        }
        let v = auth_options_of(&text);
        let places = two_factor_places(&v);
        let says_where = places.iter().any(|p| {
            [
                "trustedDeviceCount",
                "hasTrustedDevices",
                "trustedPhoneNumbers",
                "trustedPhoneNumber",
            ]
            .iter()
            .any(|k| p.get(*k).is_some())
        });
        if !says_where {
            return Err(Error::Protocol(
                "Apple didn't say where it can send a code".into(),
            ));
        }

        let phones = trusted_phones(&v);
        self.phones.clone_from(&phones);
        // A count where Apple gives one; where it says only that there are trusted devices
        // (`direct.hasTrustedDevices`), at least one.
        let counted = places
            .iter()
            .find_map(|p| p.get("trustedDeviceCount").and_then(Value::as_u64));
        let has_devices = places
            .iter()
            .any(|p| p.get("hasTrustedDevices").and_then(Value::as_bool) == Some(true));
        let too_many = places.iter().any(|p| {
            p.pointer("/securityCode/tooManyCodesSent")
                .and_then(Value::as_bool)
                == Some(true)
        });

        Ok(TwoFactorOptions {
            trusted_device_count: counted.unwrap_or(u64::from(has_devices)),
            phones,
            too_many_codes_sent: too_many,
            security_key: places.iter().any(|p| offers_security_key(p)),
        })
    }

    /// The `phoneNumber` and `mode` for `phone_id`, as Apple last described the number.
    fn phone_payload(&self, phone_id: u64) -> (Value, String) {
        self.phones.iter().find(|p| p.id == phone_id).map_or_else(
            || (json!({ "id": phone_id }), "sms".to_string()),
            |p| (p.as_payload(), p.mode.clone()),
        )
    }

    /// The code screen is open: ask Apple to send the code, unless it was already asked for
    /// this sign-in (the person typed their password a moment ago, or had it texted). A lapse
    /// mended in the background left it unasked on purpose — see [`Self::resume`].
    pub async fn request_code(&mut self) -> Result<()> {
        if self.sign.code_sent() {
            return Ok(());
        }
        self.resend_to_devices().await
    }

    /// Ask Apple to push the code to trusted devices again.
    pub async fn resend_to_devices(&mut self) -> Result<()> {
        let mut headers = self.auth_headers();
        headers.insert("accept", HeaderValue::from_static("application/json"));
        let r = self
            .http
            .put(format!(
                "{}/verify/trusteddevice/securitycode",
                self.endpoints.auth
            ))
            .headers(headers)
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        if !status.is_success() && status != StatusCode::NO_CONTENT {
            let body = r.text().await.unwrap_or_default();
            return Err(apple_error("sending the code again", status, &body));
        }
        self.sign.sent();
        Ok(())
    }

    /// Text the code to one of the trusted phone numbers.
    pub async fn send_sms(&mut self, phone_id: u64) -> Result<()> {
        let mut headers = self.auth_headers();
        headers.insert("accept", HeaderValue::from_static("application/json"));
        let r = self
            .http
            .put(format!("{}/verify/phone", self.endpoints.auth))
            .headers(headers)
            .body({
                let (phone, mode) = self.phone_payload(phone_id);
                json!({ "phoneNumber": phone, "mode": mode }).to_string()
            })
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        if !status.is_success() && status != StatusCode::NO_CONTENT {
            let body = r.text().await.unwrap_or_default();
            return Err(apple_error("texting the code", status, &body));
        }
        self.sign.sent();
        Ok(())
    }

    /// Submit a code that arrived by SMS. Trusted-device codes use `submit_two_factor`.
    pub async fn submit_sms_code(&mut self, phone_id: u64, code: &str) -> Result<()> {
        let mut headers = self.auth_headers();
        headers.insert("accept", HeaderValue::from_static("application/json"));
        let (phone, mode) = self.phone_payload(phone_id);
        let r = self
            .http
            .post(format!("{}/verify/phone/securitycode", self.endpoints.auth))
            .headers(headers)
            .body(
                json!({
                    "phoneNumber": phone,
                    "securityCode": { "code": code },
                    "mode": mode,
                })
                .to_string(),
            )
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let escrow = wants_escrow(&r);
        // A correct code on an account with steps waiting (right after new iCloud terms, say)
        // is answered 412 with a repair session token, not 200 (pyicloud#466): accepted.
        let repair = status == StatusCode::PRECONDITION_FAILED
            && r.headers().contains_key("x-apple-repair-session-token");
        let body = r.text().await.unwrap_or_default();
        if !status.is_success() && status != StatusCode::NO_CONTENT && !repair {
            let err = apple_error("checking that texted code", status, &body);
            if matches!(err, Error::BadCode) {
                return Err(err);
            }
            if self.trust().await.is_ok() {
                return self.open_after_code().await;
            }
            return Err(err);
        }
        self.escrow_if_asked(escrow).await?;
        self.trust().await?;
        self.open_after_code().await
    }

    /// Submit the six-digit code, then ask Apple to trust this install.
    pub async fn submit_two_factor(&mut self, code: &str) -> Result<()> {
        let mut headers = self.auth_headers();
        headers.insert("accept", HeaderValue::from_static("application/json"));
        let r = self
            .http
            .post(format!(
                "{}/verify/trusteddevice/securitycode",
                self.endpoints.auth
            ))
            .headers(headers)
            .body(json!({ "securityCode": { "code": code } }).to_string())
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let escrow = wants_escrow(&r);
        let body = r.text().await.unwrap_or_default();
        // Since iOS 26.4 a correct code is answered 409 with `securityCode.valid: true`.
        let accepted = status == StatusCode::CONFLICT
            && serde_json::from_str::<Value>(&body)
                .ok()
                .and_then(|v| v.pointer("/securityCode/valid").and_then(Value::as_bool))
                == Some(true);
        if !status.is_success() && status != StatusCode::NO_CONTENT && !accepted {
            let err = apple_error("checking that code", status, &body);
            // A genuinely wrong code is final; don't burn an attempt probing further.
            if matches!(err, Error::BadCode) {
                return Err(err);
            }
            // Apple answers 409 on this endpoint in some flows even though the code WAS
            // accepted. The status alone is not evidence, so ask whether the session became
            // usable before reporting a failure.
            if self.trust().await.is_ok() {
                return self.open_after_code().await;
            }
            return Err(err);
        }

        self.escrow_if_asked(escrow).await?;
        self.trust().await?;
        self.open_after_code().await
    }

    /// Whether `password` is this account's Apple ID password: what the Hidden album asks for,
    /// as icloud.com asks for it before showing Hidden. The password this computer already
    /// keeps (in the keyring, for signing back in) answers it here when it matches — offline,
    /// with no sign-in for Apple to note. Otherwise (none kept, or the kept one out of date) it
    /// is proved to Apple as sign-in proves it (SRP: the password itself is never sent) on a client
    /// of its own with no cookies: the live session is never touched, nothing Apple answers is
    /// kept, and no code is ever asked for — Apple waits to be asked before it sends one.
    pub async fn check_password(&mut self, password: &str) -> Result<bool> {
        // The kept copy is right nearly every time. One that doesn't match may be the old one —
        // the password changed on the phone since — so Apple is asked before "wrong" is said.
        if self
            .session
            .password
            .as_deref()
            .is_some_and(|kept| same_secret(kept.as_bytes(), password.as_bytes()))
        {
            return Ok(true);
        }
        let apple_id = self.session.apple_id.clone().ok_or(Error::Protocol(
            "no Apple ID to check the password against".into(),
        ))?;
        let http = apple_only()
            .timeout(std::time::Duration::from_secs(30))
            .build()
            .map_err(Error::Network)?;
        let headers = with_srp_origin(
            base_oauth_headers(&self.session.client_id(), &self.endpoints.home, None, None),
            &self.endpoints.auth_root,
        );
        let client = srp::Client::new(&apple_id);
        let r = http
            .post(format!("{}/signin/init", self.endpoints.auth))
            .headers(headers.clone())
            .body(
                json!({
                    "a": B64.encode(client.a_public_bytes()),
                    "accountName": apple_id,
                    "protocols": ["s2k", "s2k_fo"],
                })
                .to_string(),
            )
            .send()
            .await?;
        let status = r.status();
        let text = r.text().await.unwrap_or_default();
        if status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN {
            return Ok(false);
        }
        if !status.is_success() {
            return Err(apple_error("checking your password", status, &text));
        }
        let challenge = Challenge::of(&serde_json::from_str(&text)?)?;
        let proof = client
            .process_challenge(
                password,
                challenge.protocol,
                &challenge.salt,
                &challenge.b_pub,
                challenge.iterations,
            )
            .ok_or_else(|| {
                Error::Protocol("Apple's sign-in challenge failed its safety check".into())
            })?;
        let mut body = json!({
            "accountName": apple_id,
            "c": challenge.c,
            "m1": B64.encode(proof.m1),
            "m2": B64.encode(proof.m2),
            "rememberMe": false,
            "trustTokens": [],
        });
        if let Some(t) = &self.session.trust_token {
            body["trustTokens"] = json!([t]);
        }
        let r = http
            .post(format!("{}/signin/complete", self.endpoints.auth))
            .headers(headers)
            .body(body.to_string())
            .send()
            .await?;
        match r.status() {
            // Accepted — whether Apple would want a code next, its escrow step, or nothing: the
            // password was right, and nothing further is asked.
            s if s.is_success()
                || s == StatusCode::CONFLICT
                || s == StatusCode::PRECONDITION_FAILED =>
            {
                Ok(true)
            }
            StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Ok(false),
            s => {
                let text = r.text().await.unwrap_or_default();
                Err(apple_error("checking your password", s, &text))
            }
        }
    }

    /// Apple's escrow step: the SRP password proof again, with an empty account name, sending
    /// the session key with it — `POST escrow/init` `{a, accountName: "", protocols}`, then
    /// `POST escrow/complete` `{m1, m2, c, k}` (icloud-photos-sync#1124, rclone#10048). Apple
    /// issues a new session token for it, taken with the other headers.
    async fn complete_escrow(&mut self, password: &str) -> Result<()> {
        let client = srp::Client::new("");
        let r = self
            .http
            .post(format!("{}/escrow/init", self.endpoints.auth))
            .headers(self.srp_headers())
            .body(
                json!({
                    "a": B64.encode(client.a_public_bytes()),
                    "accountName": "",
                    "protocols": ["s2k", "s2k_fo"],
                })
                .to_string(),
            )
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let text = r.text().await.unwrap_or_default();
        if !status.is_success() {
            return Err(apple_error(
                "confirming your password with Apple",
                status,
                &text,
            ));
        }
        let challenge = Challenge::of(&serde_json::from_str(&text)?)?;
        let proof = client
            .process_challenge(
                password,
                challenge.protocol,
                &challenge.salt,
                &challenge.b_pub,
                challenge.iterations,
            )
            .ok_or_else(|| {
                Error::Protocol("Apple's sign-in challenge failed its safety check".into())
            })?;
        let r = self
            .http
            .post(format!("{}/escrow/complete", self.endpoints.auth))
            .headers(self.srp_headers())
            .body(
                json!({
                    "m1": B64.encode(proof.m1),
                    "m2": B64.encode(proof.m2),
                    "c": challenge.c,
                    "k": B64.encode(proof.key),
                })
                .to_string(),
            )
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        if !status.is_success() && status != StatusCode::NO_CONTENT {
            let text = r.text().await.unwrap_or_default();
            return Err(apple_error(
                "confirming your password with Apple",
                status,
                &text,
            ));
        }
        quiet!("quince: Apple's escrow step is done");
        Ok(())
    }

    /// `POST repair/complete` with `{}`, as icloudpd sends it when `/signin/complete` answers
    /// 412. Refused, the account needs the person at account.apple.com.
    async fn repair_complete(&mut self) -> Result<()> {
        let r = self
            .http
            .post(format!("{}/repair/complete", self.endpoints.auth))
            .headers(self.auth_headers())
            .body("{}")
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        if status.is_success() || status == StatusCode::NO_CONTENT {
            return Ok(());
        }
        if let Some(e) = transient(status) {
            return Err(e);
        }
        Err(Error::RepairNeeded)
    }

    /// The password for the escrow step after a code: the one just typed, or the one kept.
    fn password_for_escrow(&self) -> Option<String> {
        self.sign
            .password()
            .map(str::to_string)
            .or_else(|| self.session.password.clone())
    }

    /// After an accepted code: Apple's escrow step when the answer asks for it, before the
    /// trust token is asked for — without it Apple does not honour that token next time.
    async fn escrow_if_asked(&mut self, asked: bool) -> Result<()> {
        if !asked {
            return Ok(());
        }
        let password = self.password_for_escrow().ok_or(Error::ReauthRequired)?;
        self.complete_escrow(&password).await
    }

    /// `GET /2sv/trust` — yields the trust token. Without it, sign-in wouldn't outlive the process.
    async fn trust(&mut self) -> Result<()> {
        let headers = self.auth_headers();
        let r = self
            .http
            .get(format!("{}/2sv/trust", self.endpoints.auth))
            .headers(headers)
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let body = r.text().await.unwrap_or_default();
        if !status.is_success() && status != StatusCode::NO_CONTENT {
            return Err(apple_error("trusting this device", status, &body));
        }
        if self.session.trust_token.is_none() {
            return Err(Error::NoTrustToken);
        }
        Ok(())
    }

    /// Exchange the session token for Apple's per-account service URL map.
    async fn account_login(&mut self) -> Result<Value> {
        let body = json!({
            "accountCountryCode": self.session.account_country.clone().unwrap_or_default(),
            "dsWebAuthToken": self.session.session_token.clone().unwrap_or_default(),
            "extended_login": true,
            "trustToken": self.session.trust_token.clone().unwrap_or_default(),
        });
        let r = self
            .http
            .post(format!("{}/accountLogin", self.endpoints.setup))
            .header("content-type", "application/json")
            .body(body.to_string())
            .send()
            .await?;
        self.capture(&r);
        let status = r.status();
        let text = r.text().await.unwrap_or_default();
        // An account Apple keeps on its regional servers: answered `302` with only
        // `{"domainToUse": "iCloud.com.cn"}` (issue #10; rclone#8257). Asked again there, with
        // the sign-in this session has; an answer naming where it already is goes on below.
        if let Some(to) = domain_to_use(&text) {
            let here = self.session.domain.as_deref().unwrap_or(HOME_DOMAIN);
            if !to.eq_ignore_ascii_case(here) {
                if !to.eq_ignore_ascii_case(REGIONAL_DOMAIN)
                    && !to.eq_ignore_ascii_case(HOME_DOMAIN)
                {
                    return Err(Error::Protocol(format!(
                        "Apple keeps this Apple Account at {to}, which Skykeep can't open yet"
                    )));
                }
                quiet!("quince: Apple keeps this account at {to}; asking there");
                self.switch_servers(Some(&to))?;
                return match Box::pin(self.account_login()).await {
                    Ok(data) => Ok(data),
                    // Not there to ask: said as it is, and asked again later.
                    Err(e @ (Error::Network(_) | Error::Unavailable(_) | Error::RateLimited)) => {
                        Err(e)
                    }
                    // A sign-in made at iCloud.com that Apple won't take there: made again.
                    Err(_) => Err(Error::Moved),
                };
            }
        }
        if !status.is_success() {
            return Err(transient(status).unwrap_or_else(|| {
                Error::Protocol(format!("couldn't open the account ({status})"))
            }));
        }
        let data: Value = serde_json::from_str(&text)?;
        diag::account("accountLogin", &data);
        // New iCloud terms not yet accepted: Apple answers 200 but opens the session only
        // part-way, without the web cookies every service needs (rclone/rclone#9919). Not an
        // error: a sign-in that met them is complete — the password proved itself, and is no
        // failed attempt — and `absorb` keeps `termsUpdateNeeded`, which the window says and
        // every pass asks again until the person has agreed at icloud.com.
        Ok(data)
    }

    /// This account's servers, from now on: Apple's at `domain` (its `domainToUse`) — iCloud.com's
    /// for `None` — with a client of their own (their web origin on every request), the lock
    /// opened to Apple's regional domains only for an account kept there, and the choice kept
    /// in the session so every later launch starts there. The cookies stay: each belongs to
    /// the host that set it.
    fn switch_servers(&mut self, domain: Option<&str>) -> Result<()> {
        let regional = domain.is_some_and(|d| d.eq_ignore_ascii_case(REGIONAL_DOMAIN));
        let endpoints = if regional {
            self.regional_endpoints.clone()
        } else {
            self.home_endpoints.clone()
        };
        if endpoints != self.endpoints {
            self.http = apple_client(&endpoints, &self.jar)?;
            self.endpoints = endpoints;
        }
        open_regional(regional);
        self.session.domain = regional.then(|| REGIONAL_DOMAIN.to_string());
        let _ = self.persist();
        Ok(())
    }

    /// Where a test's regional servers are (its mock), instead of Apple's. Test seam.
    pub fn regional_endpoints_at(&mut self, endpoints: Endpoints) {
        self.regional_endpoints = endpoints;
    }

    /// The account opened after a code was taken. An account Apple then names as kept on its
    /// regional servers, where this sign-in isn't taken, is signed in again there with the
    /// password still in flight: Apple sends a new code for them, and the code screen, where
    /// the person is, says to enter it (issue #10).
    async fn open_after_code(&mut self) -> Result<()> {
        match self.account_login().await {
            Ok(data) => {
                self.absorb(&data);
                self.keep();
                Ok(())
            }
            Err(Error::Moved) => {
                let Some((apple_id, password)) = self.sign.credentials() else {
                    return Err(Error::Moved);
                };
                match Box::pin(self.sign_in_as(&apple_id, &password, Code::Send)).await? {
                    SignInOutcome::Complete => Ok(()),
                    SignInOutcome::NeedsTwoFactor => Err(Error::CodeAgain),
                }
            }
            Err(e) => Err(e),
        }
    }

    fn absorb(&mut self, data: &Value) {
        // A completed sign-in — with or without a code — is when a password has proved
        // itself, so that is when it is kept.
        if let Some((apple_id, password)) = self.sign.finish() {
            self.session.apple_id = Some(apple_id);
            self.session.password = Some(password);
        }
        if let Some(ws) = data.get("webservices") {
            self.session.webservices = Some(ws.clone());
        }
        if let Some(d) = data.pointer("/dsInfo/dsid").and_then(|v| v.as_str()) {
            self.session.dsid = Some(d.to_string());
        }
        let text = |path: &str| {
            data.pointer(path)
                .and_then(|v| v.as_str())
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
        };
        if let Some(name) = text("/dsInfo/fullName").or_else(|| {
            let first = text("/dsInfo/firstName")?;
            Some(match text("/dsInfo/lastName") {
                Some(last) => format!("{first} {last}"),
                None => first,
            })
        }) {
            self.session.account_name = Some(name);
        }
        if let Some(email) = text("/dsInfo/primaryEmail").or_else(|| text("/dsInfo/appleId")) {
            self.session.account_email = Some(email);
        }
        if let Some(on) = data
            .get("iCDPEnabled")
            .or_else(|| data.pointer("/dsInfo/iCDPEnabled"))
            .and_then(Value::as_bool)
        {
            self.session.data_protection = Some(on);
        }
        // Web access, new terms and the account to finish, from every answer that carries
        // them, so agreeing at icloud.com clears them at the next `accountLogin` — the
        // heartbeat's, or Try Again's.
        self.session.gate.absorb(data);
        if self.session.gate.standing() == state::Standing::Terms {
            quiet!("quince: Apple has iCloud terms waiting to be agreed to");
        }
    }

    /// Ask Apple for the account again — after the person agreed to new iCloud terms at
    /// icloud.com, say: a fresh `accountLogin` opens the whole web session they were waiting on.
    pub async fn refresh_account(&mut self) -> Result<()> {
        let data = self.account_login().await?;
        self.absorb(&data);
        self.keep();
        Ok(())
    }

    /// Apple is keeping this session from the account's data until something is done at
    /// icloud.com: new terms agreed to, or the account finished. Nothing else can be read
    /// meanwhile, so nothing else is asked.
    #[must_use]
    pub fn waits_on_icloud_com(&self) -> bool {
        self.standing().at_icloud_com()
    }

    /// What, if anything, Apple has said holds the account's data back from this session.
    #[must_use]
    pub fn standing(&self) -> state::Standing {
        self.session.gate.standing()
    }

    /// Query parameters every iCloud service endpoint expects alongside the session cookies.
    #[must_use]
    pub fn service_params(&self) -> Vec<(String, String)> {
        let mut params = vec![
            ("clientBuildNumber".to_string(), CLIENT_BUILD.to_string()),
            (
                "clientMasteringNumber".to_string(),
                CLIENT_MASTERING.to_string(),
            ),
            (
                "clientId".to_string(),
                self.session.client_id.clone().unwrap_or_default(),
            ),
        ];
        if let Some(dsid) = &self.session.dsid {
            params.push(("dsid".to_string(), dsid.clone()));
        }
        params
    }

    /// The account service's root (`…/setup/ws/1`), where storage use is asked for.
    #[must_use]
    pub fn setup_url(&self) -> &str {
        &self.endpoints.setup
    }

    /// Shared HTTP client, for the service crates that ride this session.
    pub fn http(&self) -> &HttpClient {
        &self.http
    }
}

/// The domains Apple's client can reach, each with every host under it: Apple's sign-in,
/// iCloud's services and their files, and push. What Settings
/// lists as what Skykeep talks to, read from here so the list is the lock itself.
pub const APPLE_DOMAINS: [&str; 3] = ["apple.com", "icloud.com", "icloud-content.com"];

/// Apple's own domains for the accounts it keeps at [`REGIONAL_DOMAIN`]: its sign-in, iCloud's
/// services and their files there, each served under Apple's certificate. Reachable only once
/// this computer's account is one of them ([`open_regional`]), so every other account's
/// client reaches exactly [`APPLE_DOMAINS`], and Settings lists exactly what can be reached.
pub const REGIONAL_DOMAINS: [&str; 3] = ["apple.com.cn", "icloud.com.cn", "icloud-content.com.cn"];

/// Whether [`REGIONAL_DOMAINS`] are open: set when the signed-in account is kept there.
static REGIONAL: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Open (or close) Apple's regional domains, for an account Apple keeps there (or no longer).
pub fn open_regional(open: bool) {
    REGIONAL.store(open, std::sync::atomic::Ordering::SeqCst);
}

/// Every domain Apple's client can reach right now: [`APPLE_DOMAINS`], and [`REGIONAL_DOMAINS`]
/// while the account is kept there. What Settings lists, read from the lock itself.
#[must_use]
pub fn reachable_domains() -> Vec<&'static str> {
    let mut all = APPLE_DOMAINS.to_vec();
    if REGIONAL.load(std::sync::atomic::Ordering::SeqCst) {
        all.extend(REGIONAL_DOMAINS);
    }
    all
}

/// The web origin Apple's services expect from this account: iCloud.com's, or its regional
/// site's while the account is kept there. For requests that name it themselves (push, Drive).
#[must_use]
pub fn web_origin() -> &'static str {
    if REGIONAL.load(std::sync::atomic::Ordering::SeqCst) {
        "https://www.icloud.com.cn"
    } else {
        "https://www.icloud.com"
    }
}

/// Whether this computer counts as Apple's: in this crate's tests, and in a build made with the
/// `loopback` feature (the other crates' tests, whose mock servers run here) — never in the
/// app. A shipped client that reached `localhost` could be pointed, by an address in Apple's
/// data (a contact's photo), at whatever else runs on the person's computer.
const LOOPBACK: bool = cfg!(any(test, feature = "loopback"));

/// Whether `host` is Apple's: under one of [`APPLE_DOMAINS`] — every host Skykeep has any
/// reason to reach. Loopback too, which is this computer, only in tests (see `LOOPBACK`).
#[must_use]
pub fn is_apple_host(host: &str) -> bool {
    apple_host(
        host,
        LOOPBACK,
        REGIONAL.load(std::sync::atomic::Ordering::SeqCst),
    )
}

fn apple_host(host: &str, loopback: bool, regional: bool) -> bool {
    let host = host.trim_end_matches('.').to_ascii_lowercase();
    let under = |d: &&str| host == *d || host.ends_with(&format!(".{d}"));
    (loopback && host == "localhost")
        || APPLE_DOMAINS.iter().any(under)
        || (regional && REGIONAL_DOMAINS.iter().any(under))
}

/// Every HTTP client Skykeep makes for iCloud starts here: Apple's servers, and nothing else,
/// can be reached at all (see [`AppleOnly`]). The two other clients are just as narrow:
/// [`listed_only`] for subscribed calendars and [`releases::releases_only`] for updates.
pub fn apple_only() -> reqwest::ClientBuilder {
    let builder = HttpClient::builder()
        .dns_resolver(Arc::new(AppleOnly))
        // The resolver alone is not enough: a URL with an address in it (`https://1.2.3.4/`)
        // is never looked up, and through a proxy the proxy looks the name up, not us. So
        // every request's own URL is checked first, a redirect's included; one that is not
        // Apple's is sent to a "proxy" that cannot be found — by the resolver above, so the
        // refusal reads the same — and never leaves the machine.
        .proxy(reqwest::Proxy::custom(|url| {
            (!url_is_apples(url)).then(|| REFUSED.to_string())
        }));
    // Setting a proxy turns off the system's own (`HTTPS_PROXY` and the rest), which Apple's
    // hosts still go through when one is set, as they did before.
    with_system_proxies(builder)
}

/// The proxy the system names for `scheme` ("https" or "http"), from `HTTPS_PROXY` and the
/// rest, if any.
pub(crate) fn env_proxy(scheme: &str) -> Option<String> {
    let names = if scheme == "https" {
        ["HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy"]
    } else {
        ["HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"]
    };
    names
        .iter()
        .find_map(|n| std::env::var(n).ok().filter(|v| !v.trim().is_empty()))
}

/// The system's own proxies (`HTTPS_PROXY` and the rest), put back after a refusing proxy has
/// turned them off.
fn with_system_proxies(mut builder: reqwest::ClientBuilder) -> reqwest::ClientBuilder {
    for scheme in ["https", "http"] {
        let Some(via) = env_proxy(scheme) else {
            continue;
        };
        let proxy =
            reqwest::Proxy::custom(move |url| (url.scheme() == scheme).then(|| via.clone()))
                .no_proxy(reqwest::NoProxy::from_env());
        builder = builder.proxy(proxy);
    }
    builder
}

/// The client for calendars the person subscribed to by address — and for nothing else. It
/// reaches exactly the hosts in `hosts` (the ones those addresses name), by the same two locks
/// as [`apple_only`]: a resolver that looks up no other name, and a check of every request's
/// own URL, a redirect's included, so an address or a proxy cannot carry it anywhere else.
/// Apple's own client is not widened by it; nothing else in Skykeep uses this one.
pub fn listed_only(hosts: &[String]) -> reqwest::ClientBuilder {
    let listed: Arc<Vec<String>> = Arc::new(hosts.iter().map(|h| normal_host(h)).collect());
    let check = Arc::clone(&listed);
    let builder = HttpClient::builder()
        .dns_resolver(Arc::new(ListedOnly(Arc::clone(&listed))))
        .redirect(reqwest::redirect::Policy::limited(5))
        .proxy(reqwest::Proxy::custom(move |url| {
            (!url_is_listed(url, &check)).then(|| REFUSED.to_string())
        }));
    with_system_proxies(builder)
}

fn normal_host(host: &str) -> String {
    host.trim_end_matches('.')
        .trim_start_matches('[')
        .trim_end_matches(']')
        .to_ascii_lowercase()
}

/// Whether a request's URL names one of the listed hosts exactly — and, where it names an
/// address, one out on the internet.
fn url_is_listed(url: &reqwest::Url, listed: &[String]) -> bool {
    url.host_str().is_some_and(|h| {
        let h = normal_host(h);
        listed.contains(&h) && h.parse::<std::net::IpAddr>().ok().is_none_or(is_public_ip)
    })
}

/// Whether an address is out on the internet: not this computer, not the local network (a
/// router's page, a printer, `192.168.…`, `10.…`, `fd…`), not link-local (where cloud machines
/// keep their secrets, `169.254.169.254`), nor any other range no public calendar is on. A
/// subscription is an address anyone can hand the person — and its name can be pointed at any
/// address its owner likes — so one that leads inside is never fetched.
#[must_use]
pub fn is_public_ip(ip: std::net::IpAddr) -> bool {
    use std::net::IpAddr;
    match ip {
        IpAddr::V4(v4) => {
            let [a, b, ..] = v4.octets();
            !(v4.is_private()
                || v4.is_loopback()
                || v4.is_link_local()
                || v4.is_unspecified()
                || v4.is_broadcast()
                || v4.is_multicast()
                || v4.is_documentation()
                || a == 0
                || a >= 240
                // Shared address space (carrier NAT, tailnets) and benchmarking.
                || (a == 100 && (64..128).contains(&b))
                || (a == 198 && (18..20).contains(&b))
                // IETF protocol assignments.
                || (a == 192 && b == 0 && v4.octets()[2] == 0))
        }
        IpAddr::V6(v6) => {
            if let Some(v4) = v6.to_ipv4_mapped() {
                return is_public_ip(IpAddr::V4(v4));
            }
            let first = v6.segments()[0];
            // NAT64 (`64:ff9b::/96`) carries an IPv4 address inside.
            if v6.segments()[..6] == [0x64, 0xff9b, 0, 0, 0, 0] {
                let [.., a, b, c, d] = v6.octets();
                return is_public_ip(IpAddr::V4(std::net::Ipv4Addr::new(a, b, c, d)));
            }
            !(v6.is_loopback()
                || v6.is_unspecified()
                || v6.is_multicast()
                || (first & 0xfe00) == 0xfc00
                || (first & 0xffc0) == 0xfe80
                || (first & 0xffc0) == 0xfec0
                || first == 0x2001 && v6.segments()[1] == 0x0db8)
        }
    }
}

/// The subscribed-calendar client's resolver: a listed host is looked up as the system looks
/// up any name; any other is never looked up at all.
struct ListedOnly(Arc<Vec<String>>);

impl reqwest::dns::Resolve for ListedOnly {
    fn resolve(&self, name: reqwest::dns::Name) -> reqwest::dns::Resolving {
        let host = normal_host(name.as_str());
        let allowed = self.0.contains(&host);
        Box::pin(async move {
            if !allowed {
                let refused: Box<dyn std::error::Error + Send + Sync> =
                    format!("{host} is not a calendar you subscribed to").into();
                return Err(refused);
            }
            // Whatever the name says, only addresses out on the internet are dialled: a feed
            // whose name leads to this computer or the local network reaches neither.
            let found: Vec<_> = tokio::net::lookup_host((host.as_str(), 0))
                .await?
                .filter(|a| is_public_ip(a.ip()))
                .collect();
            if found.is_empty() {
                let refused: Box<dyn std::error::Error + Send + Sync> =
                    format!("{host} is not on the internet").into();
                return Err(refused);
            }
            let addrs: reqwest::dns::Addrs = Box::new(found.into_iter());
            Ok(addrs)
        })
    }
}

/// Where a request that is not Apple's is pointed: a name the resolver refuses.
const REFUSED: &str = "http://refused.skykeep.invalid";

/// Whether a request's URL may be sent: an Apple host by name, or this computer in tests.
fn url_is_apples(url: &reqwest::Url) -> bool {
    url_apples(url, LOOPBACK)
}

fn url_apples(url: &reqwest::Url, loopback: bool) -> bool {
    let Some(host) = url.host_str() else {
        return false;
    };
    match host
        .trim_start_matches('[')
        .trim_end_matches(']')
        .parse::<std::net::IpAddr>()
    {
        Ok(ip) => loopback && ip.is_loopback(),
        // Apple's hosts over TLS only. Plain HTTP to one — an address in Apple's data, or a
        // redirect down to it — would carry the session's cookies where anyone on the network
        // can read them (pyicloud#356, #401). This computer, in tests, is the one exception.
        Err(_) => {
            let secure = matches!(url.scheme(), "https" | "wss");
            (secure || (loopback && host == "localhost"))
                && apple_host(
                    host,
                    loopback,
                    REGIONAL.load(std::sync::atomic::Ordering::SeqCst),
                )
        }
    }
}

/// The one way Apple's client finds a server: a host that is not Apple's is never looked up,
/// so no request of Apple's client can reach one — how the code works, not a promise about it.
/// Apple's are looked up as the system looks up any name.
struct AppleOnly;

impl reqwest::dns::Resolve for AppleOnly {
    fn resolve(&self, name: reqwest::dns::Name) -> reqwest::dns::Resolving {
        let host = name.as_str().to_string();
        Box::pin(async move {
            if !is_apple_host(&host) {
                let refused: Box<dyn std::error::Error + Send + Sync> =
                    format!("{host} is not Apple's, and Apple's client reaches only Apple").into();
                return Err(refused);
            }
            let found = tokio::net::lookup_host((host.as_str(), 0)).await?;
            let addrs: reqwest::dns::Addrs = Box::new(found.collect::<Vec<_>>().into_iter());
            Ok(addrs)
        })
    }
}

#[cfg(test)]
mod release_tests {
    use super::*;

    /// What the shipped client allows: Apple's hosts, and never this computer — by name or
    /// by address.
    #[test]
    fn a_release_client_never_reaches_this_computer() {
        for host in ["localhost", "LOCALHOST.", "127.0.0.1", "[::1]"] {
            assert!(!apple_host(host, false, false), "{host}");
            assert!(!apple_host(host, false, true), "{host}");
        }
        for url in [
            "http://localhost:8080/",
            "http://127.0.0.1:631/",
            "http://127.1.2.3/",
            "http://[::1]:9/",
            "https://localhost./",
        ] {
            let u = reqwest::Url::parse(url).unwrap();
            assert!(!url_apples(&u, false), "{url}");
            assert!(url_apples(&u, true), "{url}");
        }
        assert!(url_apples(
            &reqwest::Url::parse("https://p01-contacts.icloud.com/x").unwrap(),
            false
        ));
    }
}

#[cfg(test)]
mod listed_tests {
    use super::*;

    /// A subscribed calendar's client reaches its own hosts and refuses every other — by
    /// name, by address, and Apple's too — before anything leaves the machine.
    #[tokio::test]
    async fn the_subscription_client_refuses_a_host_nobody_subscribed_to() {
        let http = listed_only(&["calendar.example.org".into()])
            .build()
            .unwrap();
        for url in [
            "https://elsewhere.example.net/feed.ics",
            "https://93.184.216.34/feed.ics",
            "https://www.icloud.com/",
        ] {
            let err = http.get(url).send().await.expect_err(url);
            let text = format!("{err:?}");
            assert!(
                text.contains("not a calendar you subscribed to"),
                "{url} was not refused by the list: {text}"
            );
        }
    }

    #[test]
    fn a_listed_host_is_matched_exactly_and_without_case() {
        let listed = vec![normal_host("Calendar.Example.org.")];
        let ok = |u: &str| url_is_listed(&reqwest::Url::parse(u).unwrap(), &listed);
        assert!(ok("https://calendar.example.org/a.ics"));
        assert!(ok("http://CALENDAR.example.org:8080/a.ics"));
        assert!(!ok("https://evil.calendar.example.org/a.ics"));
        assert!(!ok("https://example.org/a.ics"));
        assert!(!ok("https://calendar.example.org.evil.net/a.ics"));
    }

    /// A subscription never reaches this computer or the local network: not by an address in
    /// it, not by a name that leads there.
    #[tokio::test]
    async fn a_subscription_never_reaches_inside() {
        use std::net::IpAddr;
        for inside in [
            "127.0.0.1",
            "10.0.0.1",
            "172.16.5.4",
            "192.168.1.1",
            "169.254.169.254",
            "100.100.100.100",
            "0.0.0.0",
            "255.255.255.255",
            "::1",
            "::",
            "fe80::1",
            "fd00::1",
            "::ffff:127.0.0.1",
            "::ffff:192.168.0.1",
            "64:ff9b::a9fe:a9fe",
        ] {
            assert!(!is_public_ip(inside.parse::<IpAddr>().unwrap()), "{inside}");
        }
        for out in ["93.184.215.14", "1.1.1.1", "2606:4700:4700::1111"] {
            assert!(is_public_ip(out.parse::<IpAddr>().unwrap()), "{out}");
        }
        // Listed, and still refused: an address inside, or a name that leads inside.
        let by_address = vec![normal_host("192.168.1.1"), normal_host("[::1]")];
        for u in ["http://192.168.1.1/a.ics", "http://[::1]:8080/a.ics"] {
            assert!(
                !url_is_listed(&reqwest::Url::parse(u).unwrap(), &by_address),
                "{u}"
            );
        }
        let http = listed_only(&["localhost".into()]).build().unwrap();
        let err = http
            .get("http://localhost:9/feed.ics")
            .send()
            .await
            .expect_err("a name that leads to this computer");
        assert!(
            format!("{err:?}").contains("not on the internet"),
            "{err:?}"
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const HOME_T: &str = "https://www.icloud.com";
    const ROOT_T: &str = "https://idmsa.apple.com";

    /// Apple answers 409 when the idmsa origin is sent to an endpoint that expects the
    /// icloud.com one. Only the two SRP calls may carry it.
    #[test]
    fn srp_origin_is_scoped_to_sign_in() {
        let base = base_oauth_headers("auth-test", HOME_T, None, None);
        assert!(
            base.get("origin").is_none(),
            "base headers must not pin an Origin; the client default (icloud.com) applies"
        );

        let srp = with_srp_origin(base_oauth_headers("auth-test", HOME_T, None, None), ROOT_T);
        assert_eq!(srp.get("origin").unwrap(), ROOT_T);
        assert_eq!(srp.get("referer").unwrap(), &format!("{ROOT_T}/")[..]);
    }

    #[test]
    fn session_headers_are_forwarded_when_present() {
        let h = base_oauth_headers(
            "auth-test",
            HOME_T,
            Some("scnt-value"),
            Some("session-value"),
        );
        assert_eq!(h.get("scnt").unwrap(), "scnt-value");
        assert_eq!(h.get("x-apple-id-session-id").unwrap(), "session-value");
    }

    /// Sign-in must not advertise a session that does not exist yet.
    #[test]
    fn init_headers_omit_challenge_state() {
        let stale = base_oauth_headers(
            "auth-test",
            HOME_T,
            Some("stale-scnt"),
            Some("stale-session"),
        );
        assert!(
            stale.get("scnt").is_some(),
            "sanity: the helper does forward them"
        );

        let init = with_srp_origin(base_oauth_headers("auth-test", HOME_T, None, None), ROOT_T);
        assert!(
            init.get("scnt").is_none(),
            "/signin/init must not send scnt"
        );
        assert!(
            init.get("x-apple-id-session-id").is_none(),
            "/signin/init must not send a session id"
        );
        assert_eq!(init.get("origin").unwrap(), ROOT_T);
    }

    /// The first retry should be nearly free; repeated failures must back off hard, because
    /// the penalty for hammering Apple is a temporary account lock.
    #[test]
    fn backoff_grows_and_is_capped() {
        use crate::session::backoff_seconds;
        assert_eq!(backoff_seconds(0), 0, "a first attempt must not be delayed");
        let steps: Vec<u64> = (1..=6).map(backoff_seconds).collect();
        for pair in steps.windows(2) {
            assert!(pair[1] >= pair[0], "backoff must never shrink: {steps:?}");
        }
        assert_eq!(
            backoff_seconds(u32::MAX),
            backoff_seconds(5),
            "and it must be bounded"
        );
    }

    #[test]
    fn a_locked_account_and_a_wrong_password_read_as_what_they_are() {
        let words = Error::BadCredentials.to_string();
        assert!(words.contains("app-specific"), "{words}");
        let locked = r#"{"serviceErrors":[{"code":"-20209","message":"This Apple Account has been locked for security reasons."}]}"#;
        assert!(matches!(
            apple_error("finishing sign-in", StatusCode::FORBIDDEN, locked),
            Error::AccountLocked
        ));
        assert!(Error::AccountLocked
            .to_string()
            .contains("iforgot.apple.com"));
    }

    #[test]
    fn apple_errors_are_classified() {
        let wrong =
            r#"{"serviceErrors":[{"code":"-21669","message":"Incorrect verification code."}]}"#;
        assert!(matches!(
            apple_error("x", StatusCode::CONFLICT, wrong),
            Error::BadCode
        ));

        let throttled = r#"{"serviceErrors":[{"code":"-22222","message":"Too many codes sent."}]}"#;
        assert!(matches!(
            apple_error("x", StatusCode::CONFLICT, throttled),
            Error::RateLimited
        ));

        assert!(matches!(
            apple_error("x", StatusCode::TOO_MANY_REQUESTS, ""),
            Error::RateLimited
        ));

        // An outage at sign-in is said as one, not as Apple's error page.
        let page = "<html><head><title>502 Bad Gateway</title></head><body>nginx</body></html>";
        let said = apple_error("starting sign-in", StatusCode::BAD_GATEWAY, page);
        assert!(matches!(said, Error::Unavailable(502)), "got {said:?}");
        assert!(!said.to_string().contains('<'), "no markup: {said}");
        assert!(
            !said.to_string().contains("Skykeep will"),
            "nothing it won't do"
        );

        // Find My answers 450 on a resumed session; that is "sign in again", not a failure.
        assert!(matches!(
            apple_error("x", StatusCode::from_u16(450).unwrap(), ""),
            Error::ReauthRequired
        ));

        // Anything unrecognised must keep Apple's own words rather than flatten to a status.
        let other = r#"{"serviceErrors":[{"code":"-20101","message":"Account locked."}]}"#;
        match apple_error("signing in", StatusCode::CONFLICT, other) {
            Error::Protocol(m) => {
                assert!(m.contains("Account locked."), "got: {m}");
                assert!(m.contains("-20101"), "got: {m}");
            }
            e => panic!("expected Protocol, got {e:?}"),
        }
    }
}

/// The cookie jar on disk: sealed with a key the keyring keeps, and never in the clear.
#[cfg(test)]
mod sealed_jar_tests {
    use super::*;

    const VALUE: &str = "cookie-value-that-must-not-show";

    fn client(dir: &Path) -> Client {
        Client::with(dir, Endpoints::default(), Store::file(dir).unwrap()).unwrap()
    }

    fn holding_a_cookie(dir: &Path) -> Client {
        let c = client(dir);
        let url = reqwest::Url::parse("https://www.icloud.com/").unwrap();
        let cookie = cookie_store::RawCookie::parse(format!(
            "X-APPLE-WEBAUTH-USER={VALUE}; Domain=icloud.com; Path=/; Max-Age=3600; Secure"
        ))
        .unwrap();
        c.jar.lock().unwrap().insert_raw(&cookie, &url).unwrap();
        c
    }

    fn has_the_cookie(c: &Client) -> bool {
        c.jar.lock().unwrap().iter_any().any(|k| k.value() == VALUE)
    }

    fn cookies_file(dir: &Path) -> std::path::PathBuf {
        dir.join("cookies.json")
    }

    /// The jar as it was written before sealing: plain JSON.
    fn plain_jar(dir: &Path) -> Vec<u8> {
        let c = holding_a_cookie(dir);
        let mut json = Vec::new();
        cookie_store::serde::json::save(&c.jar.lock().unwrap(), &mut json).unwrap();
        assert!(String::from_utf8_lossy(&json).contains(VALUE));
        json
    }

    /// No keyring to keep a key: where the key would be is a folder, so nothing can be kept.
    fn no_keyring(dir: &Path) {
        std::fs::create_dir(dir.join("cookie-key")).unwrap();
    }

    fn nothing_but(dir: &Path, names: &[&str]) {
        let mut found: Vec<String> = std::fs::read_dir(dir)
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .collect();
        found.sort();
        let mut want: Vec<String> = names.iter().map(|n| (*n).to_string()).collect();
        want.sort();
        assert_eq!(found, want);
    }

    #[test]
    fn cookies_are_sealed_on_disk_and_read_back_by_the_next_start() {
        let dir = tempfile::tempdir().unwrap();
        holding_a_cookie(dir.path()).persist().unwrap();

        let on_disk = std::fs::read(cookies_file(dir.path())).unwrap();
        assert!(
            on_disk.starts_with(sealed::MAGIC),
            "sealed, with its header"
        );
        assert!(
            !String::from_utf8_lossy(&on_disk).contains(VALUE),
            "the cookie is not in the file"
        );
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = std::fs::metadata(cookies_file(dir.path()))
                .unwrap()
                .permissions()
                .mode();
            assert_eq!(mode & 0o777, 0o600);
        }

        let next = client(dir.path());
        assert!(has_the_cookie(&next));
        assert!(next.cookies_set_aside().is_none());
    }

    /// A changed byte: set aside cleanly, the file gone, said calmly — never a crash.
    #[test]
    fn a_changed_file_is_set_aside() {
        let dir = tempfile::tempdir().unwrap();
        holding_a_cookie(dir.path()).persist().unwrap();
        let path = cookies_file(dir.path());
        let mut bytes = std::fs::read(&path).unwrap();
        let last = bytes.len() - 1;
        bytes[last] ^= 0x40;
        std::fs::write(&path, bytes).unwrap();

        let next = client(dir.path());
        assert!(!has_the_cookie(&next));
        assert!(!path.exists(), "nothing left that cannot be opened");
        assert!(next.cookies_set_aside().is_some(), "and it says so");
        // The next write seals afresh, and that opens.
        holding_a_cookie(dir.path()).persist().unwrap();
        assert!(has_the_cookie(&client(dir.path())));
    }

    #[test]
    fn a_version_this_build_does_not_know_is_set_aside() {
        let dir = tempfile::tempdir().unwrap();
        holding_a_cookie(dir.path()).persist().unwrap();
        let path = cookies_file(dir.path());
        let mut bytes = std::fs::read(&path).unwrap();
        bytes[sealed::MAGIC.len()] = sealed::VERSION + 1;
        std::fs::write(&path, bytes).unwrap();

        let next = client(dir.path());
        assert!(!has_the_cookie(&next));
        assert!(!path.exists());
        assert!(next.cookies_set_aside().is_some());
    }

    /// The keyring was reset: the file is there and its key is not.
    #[test]
    fn a_file_whose_key_is_gone_is_set_aside() {
        let dir = tempfile::tempdir().unwrap();
        holding_a_cookie(dir.path()).persist().unwrap();
        std::fs::remove_file(dir.path().join("cookie-key")).unwrap();

        let next = client(dir.path());
        assert!(!has_the_cookie(&next));
        assert!(!cookies_file(dir.path()).exists());
        assert!(next.cookies_set_aside().is_some());
    }

    /// A jar from before sealing is read once and sealed in its place; the plain one is gone,
    /// with nothing beside it.
    #[test]
    fn a_plain_jar_from_before_is_sealed_in_its_place() {
        let dir = tempfile::tempdir().unwrap();
        let json = plain_jar(dir.path());
        std::fs::write(cookies_file(dir.path()), &json).unwrap();

        let c = client(dir.path());
        assert!(has_the_cookie(&c), "nothing lost on the way");
        let on_disk = std::fs::read(cookies_file(dir.path())).unwrap();
        assert!(on_disk.starts_with(sealed::MAGIC));
        assert!(!String::from_utf8_lossy(&on_disk).contains(VALUE));
        nothing_but(dir.path(), &["cookies.json", "cookie-key"]);
        assert!(
            has_the_cookie(&client(dir.path())),
            "and it opens next time"
        );
    }

    /// No keyring, and a plain jar from before: read into memory, and the plain file deleted —
    /// it is not left there, and nothing is written in its place.
    #[test]
    fn a_plain_jar_with_no_keyring_is_kept_in_memory_and_deleted() {
        let dir = tempfile::tempdir().unwrap();
        let json = plain_jar(dir.path());
        no_keyring(dir.path());
        std::fs::write(cookies_file(dir.path()), &json).unwrap();

        let c = client(dir.path());
        assert!(has_the_cookie(&c), "held for as long as Skykeep runs");
        assert!(
            !cookies_file(dir.path()).exists(),
            "no plaintext left behind"
        );
        nothing_but(dir.path(), &["cookie-key"]);
    }

    /// No keyring: the cookies are not written at all — never in the clear — and saying so is
    /// what `keep` does with the error.
    #[test]
    fn with_no_keyring_nothing_is_written() {
        let dir = tempfile::tempdir().unwrap();
        no_keyring(dir.path());
        let mut c = holding_a_cookie(dir.path());
        assert!(matches!(c.persist(), Err(Error::Keyring(_))));
        assert!(!cookies_file(dir.path()).exists());
        nothing_but(dir.path(), &["cookie-key", "session.json"]);
        c.keep();
        assert!(c.unsaved().is_some(), "said: kept in memory only");
        assert!(has_the_cookie(&c));

        // A keyring comes up: the next write seals them.
        std::fs::remove_dir(dir.path().join("cookie-key")).unwrap();
        c.keep();
        assert!(c.unsaved().is_none());
        assert!(has_the_cookie(&client(dir.path())));
    }

    /// A keyring that will not answer yet is not a reset one: the sealed file is left as it is,
    /// and read once it answers.
    #[test]
    fn a_keyring_that_does_not_answer_leaves_the_file_for_later() {
        let dir = tempfile::tempdir().unwrap();
        holding_a_cookie(dir.path()).persist().unwrap();
        let key = dir.path().join("cookie-key");
        let kept = std::fs::read(&key).unwrap();
        std::fs::remove_file(&key).unwrap();
        no_keyring(dir.path());

        let mut c = client(dir.path());
        assert!(!has_the_cookie(&c));
        assert!(cookies_file(dir.path()).exists(), "untouched");
        assert!(c.cookies_set_aside().is_none());

        std::fs::remove_dir(&key).unwrap();
        std::fs::write(&key, kept).unwrap();
        c.read_cookies_again();
        assert!(has_the_cookie(&c));
    }

    /// A keyring locked at login, or not up yet when Skykeep starts with the desktop: the
    /// session it holds is still there. Read as nothing stored, the launch went to the sign-in
    /// screen — never asking the keyring again, so its unlock prompt never came — and signing
    /// in replaced the session and its trust token, with a code to type.
    #[tokio::test]
    async fn a_keyring_that_does_not_answer_is_asked_again_not_read_as_signed_out() {
        let dir = tempfile::tempdir().unwrap();
        let mut c = holding_a_cookie(dir.path());
        c.session.session_token = Some("token".into());
        c.persist().unwrap();
        assert!(cookies_file(dir.path()).exists());
        // Where the session is kept will not answer.
        let session = dir.path().join("session.json");
        std::fs::remove_file(&session).unwrap();
        std::fs::create_dir(&session).unwrap();

        let mut c = client(dir.path());
        assert!(c.has_stored_session(), "worth a resume, which asks again");
        let said = c.resume().await.unwrap_err();
        assert!(matches!(said, Error::Keyring(_)), "got {said:?}");
        let words = said.to_string();
        assert!(words.contains("keyring") || words.contains("Credential Manager"));
        assert!(
            !words.contains("Is a directory"),
            "no raw OS words: {words}"
        );

        // A first run with no keyring kept nothing: the sign-in screen is right then.
        let fresh = tempfile::tempdir().unwrap();
        std::fs::create_dir(fresh.path().join("session.json")).unwrap();
        assert!(!client(fresh.path()).has_stored_session());
    }

    /// Signing out takes the key with the cookies.
    #[test]
    fn signing_out_forgets_the_key_too() {
        let dir = tempfile::tempdir().unwrap();
        let mut c = holding_a_cookie(dir.path());
        c.persist().unwrap();
        c.sign_out().unwrap();
        assert!(!cookies_file(dir.path()).exists());
        assert!(!dir.path().join("cookie-key").exists());
    }
}