apple-crates

@@ -1 +1 @@

-/target

+target/

@@ -3475,6 +3475,21 @@ dependencies = [

  "cc",

 ]

+[[package]]

+name = "icloud"

+version = "0.1.0"

+dependencies = [

+ "adi",

+ "grandslam",

+ "plist",

+ "plist-macros",

+ "reqwest",

+ "serde",

+ "serde_json",

+ "thiserror 2.0.18",

+ "uuid",

+]

+

 [[package]]

 name = "icu_collections"

 version = "2.2.0"

@@ -6111,6 +6126,27 @@ dependencies = [

  "zeroize",

 ]

+[[package]]

+name = "rust-adi"

+version = "0.1.0"

+dependencies = [

+ "adi",

+ "aes 0.9.1",

+ "base64",

+ "cbc 0.2.1",

+ "getrandom 0.4.3",

+ "grandslam",

+ "hex",

+ "md-5",

+ "plist",

+ "reqwest",

+ "serde_json",

+ "sha1 0.11.0",

+ "sha2 0.10.9",

+ "tempfile",

+ "tokio",

+]

+

 [[package]]

 name = "rust-embed"

 version = "8.11.0"

@@ -7113,7 +7149,6 @@ dependencies = [

  "crc32fast",

  "der",

  "directories",

- "dlopen2",

  "env_logger",

  "flate2",

  "futures",

@@ -7128,12 +7163,12 @@ dependencies = [

  "libc",

  "library-coreadi",

  "log",

- "ouroboros",

  "pem-rfc7468",

  "plist",

  "rand 0.10.2",

  "reqwest",

  "rsa",

+ "rust-adi",

  "serde",

  "sha1 0.11.0",

  "sha2 0.10.9",

@@ -1,6 +1,6 @@

 [workspace]

 resolver = "2"

-members = ["adi", "adid-proxy", "android-coreadi", "aps", "grandslam", "apple-codesign-quick", "elf-loader", "fairplay", "itunes", "library-coreadi", "plist-macros", "purple-builder", "super-sideloader", "xcode"]

+members = ["adi", "adid-proxy", "android-coreadi", "aps", "grandslam", "apple-codesign-quick", "elf-loader", "fairplay", "icloud", "itunes", "library-coreadi", "plist-macros", "purple-builder", "super-sideloader", "xcode"]

 [workspace.dependencies]

 adi = { path = "adi" }

@@ -9,6 +9,7 @@ android-coreadi = { path = "android-coreadi" }

 aps = { path = "aps" }

 elf-loader = { path = "elf-loader" }

 grandslam = { path = "grandslam" }

+icloud = { path = "icloud" }

 itunes = { path = "itunes" }

 library-coreadi = { path = "library-coreadi" }

 plist-macros = { path = "plist-macros" }

@@ -11,7 +11,7 @@ Here is a breakdown of every crate here:

 ### adi

-Abstracts an ADI connection, allows direct communication with ADI code.

+Abstracts an ADI connection, allows communication with ADI code.

 ### adid-proxy

@@ -401,7 +401,7 @@ impl<T: CoreADIADIProxy> ADIProxy for T {

     fn get_all_provisioned_accounts(&self) -> ADIResult<Vec<ADIAccount>> {

         let coreadi_accounts = <Self as CoreADIADIProxy>::get_all_provisioned_accounts(self)?;

         let accounts: Vec<ADIAccount> = unsafe {

-            (&*coreadi_accounts).iter().map(

+            coreadi_accounts.iter().map(

                 |&CoreADIAccount {

                      ds_id,

                      mid_len,

@@ -465,7 +465,7 @@ impl<T: CoreADIADIProxy> ADIProxy for T {

         let (mid_buf, otp_buf) = <Self as CoreADIADIProxy>::request_otp(self, ds_id)?;

         let (mid, otp) = (mid_buf.to_vec(), otp_buf.to_vec());

         self.dispose(mid_buf).and_then(|()| self.dispose(otp_buf))?;

-        Ok((mid.into(), otp.into()))

+        Ok((mid, otp))

     }

     fn set_provisioning_path(&self, path: &CStr) -> ADIResult<()> {

@@ -31,7 +31,7 @@ impl Serialize for EncryptionType {

 }

 #[repr(i32)]

-#[derive(Debug)]

+#[derive(Debug, PartialEq, Eq)]

 pub enum ADIError {

     // -45001 - Invalid parameters, have all the library fields been properly initialized?

     InvalidParameters = -45001,

@@ -19,10 +19,16 @@ let device_data = grandslam::DeviceData {

 connection.set_topics(&["com.apple.idmsauth"]).await?;

 loop {

-    let notification = connection.receive().await?;

+    match connection.receive().await? {

+        aps::Event::Notification(notification) => {

             // Accept or store notification.payload according to its topic.

             connection.acknowledge(&notification).await?;

         }

+        aps::Event::Acknowledgement { id, status } => {

+            // Match id to an outgoing send; status is Accepted or Rejected(code).

+        }

+    }

+}

 ```

 `ActivationDevice` contains the actual device fields sent in the activation

@@ -33,7 +39,7 @@ and CSR. A returned `PushIdentity` always contains the matching device key and

 certificate, and a returned `PushConnection` always has a token.

 Errors follow those boundaries: `IdentityError`, `ActivationError<S::Error>`,

-`ConnectError`, and `CourierError`. Signer errors keep their concrete type.

+`ConnectError`, `SendError`, and `CourierError`. Signer errors keep their concrete type.

 Connecting moves the identity into the connection; reconnecting reuses it

 without cloning the private key.

@@ -43,8 +49,9 @@ signer uses embedded constants and Rust cryptography.

 ## Connection lifetime and persistence

-`receive` returns notifications and handles ping/pong traffic. Call `acknowledge`

-after accepting or storing each notification; it borrows the notification, so

+`receive` returns notifications or outgoing-send acknowledgements and handles

+ping/pong traffic. Call `acknowledge` after accepting or storing each notification;

+it borrows the notification, so

 an acknowledgement error leaves it available to the caller. Keep calling

 `receive` while expecting pushes. There are no hidden background tasks or retry

 loops. Call `reconnect` after transport failure; it reuses the identity/token

@@ -53,6 +60,28 @@ token's existence does not mean a connection is currently reachable.

 If cancelling `acknowledge` during its write, or `receive` during a keepalive

 write, reconnect before continuing.

+`send(id, topic, payload)` writes unchanged payload bytes. Only one send can await

+acknowledgement at a time; attempting another returns

+`SendError::PendingAcknowledgement`. Use a new ID for each send. Continue calling

+`receive`, processing notifications as usual, until `Event::Acknowledgement`

+reports that ID. The courier can omit the ID on the wire, in which case it is

+associated with the one outstanding send, as in macOS. An explicit nonmatching

+ID is ignored. `SendStatus::Accepted` means courier acceptance, not delivery to a

+recipient. Nonzero response codes are preserved as `SendStatus::Rejected(code)`.

+

+`max_payload_size()` exposes the courier's advertised limit; larger payloads are

+rejected before writing or occupying the pending slot. If the courier omits the

+limit, the two-byte TLV length is the local ceiling, not a promise of acceptance.

+

+`receive` reports `CourierError::AcknowledgementTimeout(id)` after 30 seconds

+without a matching acknowledgement. This is the crate's existing operation

+timeout policy; callers can impose shorter deadlines. The caller owns retry

+policy. After a timeout, transport failure, or cancelled send, reconnect before

+sending again. Reconnect

+clears the outstanding send without replaying it: its outcome is unknown, and

+retrying could duplicate delivery. Payload encoding and IDS service registration

+remain the caller's responsibility.

+

 Persist the device certificate, private key, and latest token together.

 `PushIdentity::certificate` returns DER bytes; `private_key` exposes the RSA key

 for PKCS#8 export or a future adapter. `PushIdentity::new` validates imported

@@ -83,6 +112,9 @@ once. No DLL or extraction step is needed. Signing errors use `rsa::Error`.

 cargo run -p aps --example push_token -- /path/to/push-state.plist

 ```

+Add `--check-connection` to drive receive/keepalive for 95 seconds, reconnect,

+and report whether the token was preserved. It does not print tokens or payloads.

+

 The example activates on its first run, subscribes to `com.apple.idmsauth`,

 saves the identity/token, and closes the connection. Subsequent runs restore

 that state. The state file contains a private key; the example requests mode

@@ -94,7 +126,10 @@ wrapper is at `0x180005250`. The APS protocol was cross-checked against Apple's

 Windows client and rustpush's public protocol implementation. This crate does

 not depend on rustpush or its account APIs.

-See [the signing format notes](docs/windows-signing.md) for the decoded wrapping

+Outgoing messages and acknowledgement handling were also checked against

+macOS 27's `apsd`; see [the comparison notes](../research/aps/docs/macos-protocol.md).

+

+See [the signing format notes](../research/aps/docs/windows-signing.md) for the decoded wrapping

 format and its provenance.

 All ten embedded identities passed independent RSA signature verification.

@@ -1,4 +1,4 @@

-//! cargo run -p aps --example push_token -- STATE.plist

+//! cargo run -p aps --example push_token -- STATE.plist [--check-connection]

 use aps::{ActivationDevice, PushConnection, PushIdentity, PushToken, WindowsActivationSigner};

 use plist::Data;

 use rsa::{

@@ -11,7 +11,7 @@ use thiserror::Error;

 #[derive(Debug, Error)]

 enum ExampleError {

-    #[error("usage: push_token STATE.plist")]

+    #[error("usage: push_token STATE.plist [--check-connection]")]

     Usage,

     #[error(transparent)]

     Io(#[from] io::Error),

@@ -41,7 +41,7 @@ struct SavedState {

 #[tokio::main]

 async fn main() -> Result<(), ExampleError> {

     let args: Vec<_> = std::env::args_os().skip(1).collect();

-    if args.len() != 1 {

+    if args.is_empty() || args.len() > 2 || (args.len() == 2 && args[1] != "--check-connection") {

         return Err(ExampleError::Usage);

     }

     let state_path = PathBuf::from(&args[0]);

@@ -109,6 +109,38 @@ async fn main() -> Result<(), ExampleError> {

         connection.push_token().as_bytes().len(),

         state_path.display()

     );

+    println!(

+        "Courier payload limit: {} bytes",

+        connection.max_payload_size()

+    );

+    if args.len() == 2 {

+        // Drive the first keepalive (60s) and its response deadline (30s).

+        // Do not print received payloads or credential values.

+        let until = tokio::time::Instant::now() + Duration::from_secs(95);

+        loop {

+            match tokio::time::timeout_at(until, connection.receive()).await {

+                Ok(Ok(aps::Event::Notification(notification))) => {

+                    connection.acknowledge(&notification).await?;

+                }

+                Ok(Ok(aps::Event::Acknowledgement { .. })) => {}

+                Ok(Err(error)) => return Err(error.into()),

+                Err(_) => break,

+            }

+        }

+        println!("95-second receive/keepalive check passed");

+        let token = connection.push_token().clone();

+        connection.reconnect(&client).await?;

+        println!(

+            "Reconnected; token unchanged: {}",

+            connection.push_token() == &token

+        );

+        // Persist again because reconnect may replace the token.

+        let state = SavedState {

+            token: connection.push_token().clone(),

+            ..state

+        };

+        plist::to_writer_xml(options.open(&state_path)?, &state)?;

+    }

     connection.close().await?;

     Ok(())

 }

@@ -92,6 +92,28 @@ pub struct Notification {

     pub payload: Bytes,

 }

+/// The courier's response to an outgoing message, not a recipient delivery receipt.

+#[derive(Clone, Copy, Debug, PartialEq, Eq)]

+pub enum SendStatus {

+    Accepted,

+    Rejected(u8),

+}

+

+#[derive(Debug, Error)]

+pub enum SendError {

+    #[error("APS message {0} is still awaiting acknowledgement")]

+    PendingAcknowledgement(u32),

+    #[error("APS payload is {size} bytes, exceeding the courier limit of {maximum}")]

+    PayloadTooLarge { size: usize, maximum: u16 },

+    #[error("Sending the APS message failed: {0}")]

+    Courier(#[from] CourierError),

+}

+

+pub enum Event {

+    Notification(Notification),

+    Acknowledgement { id: u32, status: SendStatus },

+}

+

 /// A completed APS handshake and its live courier transport.

 /// Call `receive` to drive notifications and keepalive. No tasks are spawned.

 pub struct PushConnection {

@@ -102,6 +124,8 @@ pub struct PushConnection {

     topics: Vec<[u8; 20]>,

     next_ping: Instant,

     pong_deadline: Option<Instant>,

+    pending_send: Option<(u32, Instant)>,

+    max_payload_size: u16,

 }

 impl PushConnection {

@@ -125,7 +149,8 @@ impl PushConnection {

         identity: PushIdentity,

         previous: Option<&PushToken>,

     ) -> Result<Self, ConnectError> {

-        let (stream, reader, token) = timeout(TIMEOUT, handshake(client, &identity, previous))

+        let (stream, reader, token, max_payload_size) =

+            timeout(TIMEOUT, handshake(client, &identity, previous))

                 .await

                 .map_err(|_| ConnectError::Timeout)??;

         Ok(Self {

@@ -136,6 +161,8 @@ impl PushConnection {

             topics: Vec::new(),

             next_ping: Instant::now() + KEEPALIVE,

             pong_deadline: None,

+            pending_send: None,

+            max_payload_size,

         })

     }

@@ -147,10 +174,16 @@ impl PushConnection {

         &self.identity

     }

+    /// The courier's advertised payload limit, or the TLV limit if omitted.

+    pub fn max_payload_size(&self) -> u16 {

+        self.max_payload_size

+    }

+

     /// Reuses the current identity/token and restores topics. Failed attempts

     /// leave the existing identity and token available for another attempt.

+    /// An unacknowledged send has an unknown outcome and is not retried.

     pub async fn reconnect(&mut self, client: &Client) -> Result<(), ConnectError> {

-        let (mut stream, reader, token) = timeout(

+        let (mut stream, reader, token, max_payload_size) = timeout(

             TIMEOUT,

             handshake(client, &self.identity, Some(&self.token)),

         )

@@ -167,6 +200,8 @@ impl PushConnection {

         self.token = token;

         self.next_ping = Instant::now() + KEEPALIVE;

         self.pong_deadline = None;

+        self.pending_send = None;

+        self.max_payload_size = max_payload_size;

         Ok(())

     }

@@ -186,15 +221,60 @@ impl PushConnection {

         Ok(())

     }

-    /// Receives the next notification, driving keepalive while waiting.

-    /// Call `acknowledge` once the notification is accepted or stored.

+    /// Writes an outgoing message without waiting for its acknowledgement.

+    /// Only one send may await acknowledgement at a time: the courier can omit

+    /// its message ID. `receive` returns the supplied `id` in the acknowledgement.

+    /// Use a new ID for each send. Payload bytes are sent unchanged.

+    /// A successful write does not imply courier acceptance or recipient delivery.

+    /// Reconnect after I/O errors, timeouts, or cancellation during the write.

+    pub async fn send(&mut self, id: u32, topic: &str, payload: &[u8]) -> Result<(), SendError> {

+        if let Some((id, _)) = self.pending_send {

+            return Err(SendError::PendingAcknowledgement(id));

+        }

+        // Validate before marking the send in flight. The remaining fields

+        // have fixed sizes and fit within the frame limit.

+        if payload.len() > usize::from(self.max_payload_size) {

+            return Err(SendError::PayloadTooLarge {

+                size: payload.len(),

+                maximum: self.max_payload_size,

+            });

+        }

+        // Set before the write so cancellation cannot permit a second send.

+        self.pending_send = Some((id, Instant::now() + TIMEOUT));

+        Message::Send {

+            token: &self.token,

+            topic: &Sha1::digest(topic.as_bytes()).into(),

+            id,

+            payload,

+        }

+        .write(&mut self.stream)

+        .await?;

+        Ok(())

+    }

+

+    /// Receives the next notification or send acknowledgement, driving keepalive.

+    /// Call `acknowledge` once a notification is accepted or stored.

+    /// Send acknowledgements do not themselves require acknowledgement.

+    /// An outgoing send times out after 30 seconds. Reconnect afterward; its

+    /// outcome is unknown and it is not replayed.

     /// Reconnect after errors or cancellation during a keepalive write.

-    pub async fn receive(&mut self) -> Result<Notification, CourierError> {

+    pub async fn receive(&mut self) -> Result<Event, CourierError> {

         loop {

-            let deadline = self.pong_deadline.unwrap_or(self.next_ping);

+            let mut deadline = self.pong_deadline.unwrap_or(self.next_ping);

+            if let Some((id, expires)) = self.pending_send {

+                // Check before reading so incoming traffic cannot starve the timeout.

+                if Instant::now() >= expires {

+                    return Err(CourierError::AcknowledgementTimeout(id));

+                }

+                deadline = deadline.min(expires);

+            }

             let frame = tokio::select! {

                 frame = self.reader.read(&mut self.stream) => frame?,

                 _ = sleep_until(deadline) => {

+                    if let Some((id, expires)) = self.pending_send

+                        && Instant::now() >= expires {

+                        return Err(CourierError::AcknowledgementTimeout(id));

+                    }

                     if self.pong_deadline.is_some() { return Err(CourierError::Timeout); }

                     Message::Ping.write(&mut self.stream).await?;

                     self.pong_deadline = Some(Instant::now() + TIMEOUT);

@@ -209,18 +289,48 @@ impl PushConnection {

                             .try_into()

                             .map_err(|_| CourierError::InvalidField(4))?,

                     );

+                    let token = frame.get(1).unwrap_or(self.token.as_bytes());

+                    if token != self.token.as_bytes() {

+                        return Err(CourierError::TokenMismatch);

+                    }

                     let topic = frame

                         .required(2)?

                         .try_into()

                         .map_err(|_| CourierError::InvalidField(2))?;

+                    return Ok(Event::Notification(Notification {

+                        id,

+                        topic,

+                        payload: frame.into_field(3)?,

+                    }));

+                }

+                Command::Ack => {

+                    let Some((id, _)) = self.pending_send else {

+                        continue;

+                    };

                     let token = frame.get(1).unwrap_or(self.token.as_bytes());

                     if token != self.token.as_bytes() {

                         return Err(CourierError::TokenMismatch);

                     }

-                    return Ok(Notification {

+                    if let Some(received_id) = frame.get(4) {

+                        let received_id = u32::from_be_bytes(

+                            received_id

+                                .try_into()

+                                .map_err(|_| CourierError::InvalidField(4))?,

+                        );

+                        if received_id != id {

+                            continue;

+                        }

+                    }

+                    let [status] = frame.required(8)? else {

+                        return Err(CourierError::InvalidField(8));

+                    };

+                    self.pending_send = None;

+                    return Ok(Event::Acknowledgement {

                         id,

-                        topic,

-                        payload: frame.into_field(3)?,

+                        status: match status {

+                            0 => SendStatus::Accepted,

+                            status => SendStatus::Rejected(*status),

+                        },

                     });

                 }

                 Command::Ping => Message::Pong.write(&mut self.stream).await?,

@@ -255,7 +365,7 @@ async fn handshake(

     client: &Client,

     identity: &PushIdentity,

     previous: Option<&PushToken>,

-) -> Result<(TlsStream<TcpStream>, FrameReader, PushToken), ConnectError> {

+) -> Result<(TlsStream<TcpStream>, FrameReader, PushToken, u16), ConnectError> {

     let body = client

         .get("https://init.push.apple.com/bag")

         .send()

@@ -332,6 +442,14 @@ async fn handshake(

         ),

         None => previous.cloned().ok_or(CourierError::MissingField(3))?,

     };

+    let max_payload_size = match reply.get(4) {

+        Some(bytes) => u16::from_be_bytes(

+            bytes

+                .try_into()

+                .map_err(|_| CourierError::InvalidField(4))?,

+        ),

+        None => u16::MAX,

+    };

     Message::SetActive.write(&mut stream).await?;

-    Ok((stream, reader, token))

+    Ok((stream, reader, token, max_payload_size))

 }

@@ -12,7 +12,9 @@ pub use activation::{

     ActivationDevice, ActivationError, ActivationSignature, ActivationSigner, IdentityError,

     PushIdentity, activate,

 };

-pub use connection::{ConnectError, Notification, PushConnection, PushToken};

+pub use connection::{

+    ConnectError, Event, Notification, PushConnection, PushToken, SendError, SendStatus,

+};

 pub use protocol::CourierError;

 pub use windows_signer::WindowsActivationSigner;

@@ -49,6 +49,12 @@ pub(crate) enum Message<'a> {

         token: &'a PushToken,

         topics: &'a [[u8; 20]],

     },

+    Send {

+        token: &'a PushToken,

+        topic: &'a [u8; 20],

+        id: u32,

+        payload: &'a [u8],

+    },

     Ack {

         token: &'a PushToken,

         id: u32,

@@ -78,8 +84,8 @@ impl Message<'_> {

                 frame.push(12, certificate)?;

                 frame.push(13, nonce)?;

                 frame.push(14, signature)?;

-                // Version-like field used by rustpush; this Windows build sends 5.

-                // Its precise semantics are not established.

+                // Protocol version used by rustpush. Windows sends 5; macOS 27

+                // sends 12 with additional capabilities we do not implement.

                 frame.push(16, 9u16.to_be_bytes())?;

                 frame

             }

@@ -91,6 +97,20 @@ impl Message<'_> {

                 }

                 frame

             }

+            Self::Send {

+                token,

+                topic,

+                id,

+                payload,

+            } => {

+                let mut frame = Frame::new(Command::Notification);

+                frame.push(4, id.to_be_bytes())?;

+                // Outgoing messages reverse the incoming token/topic fields.

+                frame.push(1, topic)?;

+                frame.push(2, token.as_bytes())?;

+                frame.push(3, payload)?;

+                frame

+            }

             Self::Ack { token, id } => {

                 let mut frame = Frame::new(Command::Ack);

                 frame.push(1, token.as_bytes())?;

@@ -128,10 +148,12 @@ pub enum CourierError {

     InvalidField(u8),

     #[error("Unexpected APS command {0}")]

     UnexpectedCommand(u8),

-    #[error("The notification belongs to another push token")]

+    #[error("The message belongs to another push token")]

     TokenMismatch,

     #[error("Courier operation timed out")]

     Timeout,

+    #[error("APS message {0} was not acknowledged before the deadline; reconnect before retrying")]

+    AcknowledgementTimeout(u32),

 }

 // command:u8, length:u32, then (id:u8, length:u16, value), all big endian.

@@ -51,14 +51,20 @@ const ROOT_CA: &[u8] = include_bytes!("grandslam/root-ca.pem");

 ///

 /// # Examples

 ///

-/// ```

+/// ```no_run

+/// use grandslam::bundle_information::AUTH_KIT_BUNDLE_INFORMATION;

+/// use grandslam::device::Device;

+///

+/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {

 /// let device = Device {

 ///     device_model: "MacBookPro13,2".to_string(),

 ///     operating_system_information: "macOS;15.6.1;24G90".to_string(),

 ///     device_uuid: "A8B31C86-359B-4D95-8950-BA5DD8FFC46F".to_string(),

 /// };

 ///

-/// let grandslam_http_session = grandslam::http_session(device, XCODE_BUNDLE_INFORMATION).await?;

+/// let grandslam_http_session = grandslam::http_session(device, AUTH_KIT_BUNDLE_INFORMATION).await?;

+/// # Ok(())

+/// # }

 /// ```

 pub async fn http_session(

     device: Device,

@@ -410,8 +416,7 @@ async fn login_with_credential(

         buf

     };

-    let verifier =

-        srp_client.process_reply(&a, user.as_bytes(), &processed_password, salt, b)?;

+    let verifier = srp_client.process_reply(&a, user.as_bytes(), &processed_password, salt, b)?;

     let request_plist = dict! {

         "Header": dict!{

@@ -1,4 +1,4 @@

-use super::app::{AppToken, Token, TokenBag};

+use super::app::{AppToken, RawToken, Token, TokenBag};

 use crate::grandslam::{ContinuationToken, build_client_provided_data};

 use crate::http_session::{AnisetteHTTPSession, AppleError, parse_status};

 use adi::proxy::{ADIError, ADIResult};

@@ -64,6 +64,63 @@ pub struct SessionKey(Vec<u8>);

 #[serde(transparent)]

 pub struct AuthCookie(Vec<u8>);

+/// Credentials used together by GrandSlam's `apptokens` operation.

+/// Kept separate from service tokens and the continuation token; never logged.

+#[derive(Clone, Serialize, Deserialize)]

+pub struct MasterToken {

+    idms_token: IdmsToken,

+    session_key: SessionKey,

+    cookie: AuthCookie,

+}

+

+impl MasterToken {

+    pub fn new(idms_token: IdmsToken, session_key: SessionKey, cookie: AuthCookie) -> Self {

+        Self {

+            idms_token,

+            session_key,

+            cookie,

+        }

+    }

+

+    /// Web authentication replaces all three credentials together.

+    pub fn from_response_headers(

+        headers: &reqwest::header::HeaderMap,

+    ) -> Result<Self, ResponseTokenError> {

+        use base64::{Engine, prelude::BASE64_STANDARD};

+        let name = "x-apple-identity-token";

+        let mut values = headers.get_all(name).iter();

+        let value = values

+            .next()

+            .ok_or(ResponseTokenError::InvalidHeader(name))?;

+        if values.next().is_some() {

+            return Err(ResponseTokenError::InvalidHeader(name));

+        }

+        let (_, token) = header_token(value, name)?;

+        let decode = |name| {

+            let value =

+                header_text(headers, name)?.ok_or(ResponseTokenError::InvalidHeader(name))?;

+            BASE64_STANDARD

+                .decode(value)

+                .map_err(|_| ResponseTokenError::InvalidHeader(name))

+        };

+        let session_key = decode("x-apple-session-key")?;

+        let cookie = decode("x-apple-encrypted-session-key")?;

+        if session_key.len() != 32 {

+            return Err(ResponseTokenError::InvalidHeader("x-apple-session-key"));

+        }

+        if cookie.is_empty() {

+            return Err(ResponseTokenError::InvalidHeader(

+                "x-apple-encrypted-session-key",

+            ));

+        }

+        Ok(Self {

+            idms_token: IdmsToken(token.token),

+            session_key: SessionKey(session_key),

+            cookie: AuthCookie(cookie),

+        })

+    }

+}

+

 #[derive(Debug, Clone, Deserialize)]

 #[serde(transparent)]

 pub struct ServerProvidedData(pub(super) Dictionary);

@@ -87,6 +144,21 @@ impl ServerProvidedData {

         Some(AuthCookie(self.0.get("c")?.as_data()?.to_vec()))

     }

+    pub fn master_token(&self) -> Option<MasterToken> {

+        let token = MasterToken {

+            idms_token: self.idms_token()?,

+            session_key: self.session_key()?,

+            cookie: self.cookie()?,

+        };

+        if token.idms_token.0.is_empty()

+            || token.session_key.0.len() != 32

+            || token.cookie.0.is_empty()

+        {

+            return None;

+        }

+        Some(token)

+    }

+

     pub fn continuation_token(&self) -> Option<ContinuationToken> {

         Some(ContinuationToken(self.0.get("ck")?.as_string()?.to_owned()))

     }

@@ -148,28 +220,25 @@ impl<'lt, 'adi> AccountHTTPSession<'lt, 'adi> {

     pub async fn get_app_token<T: AppToken>(

         &self,

-        idms_token: &IdmsToken,

-        session_key: &SessionKey,

-        cookie: &AuthCookie,

+        master: &MasterToken,

     ) -> Result<Token<T>, AppTokenRequestError> {

-        let token = self

-            .get_app_token_for_service(T::APP_TOKEN_IDENTIFIER, idms_token, session_key, cookie)

-            .await?;

-        Ok(Token {

-            duration: token.duration,

-            expiry_epoch_millis: token.expiry_epoch_millis,

-            token: T::from(token.token),

-        })

+        Ok(self

+            .get_app_token_for_service(T::APP_TOKEN_IDENTIFIER, master)

+            .await?

+            .into())

     }

     /// Request a token for a service identifier supplied at runtime.

     pub async fn get_app_token_for_service(

         &self,

         app_token_identifier: &str,

-        idms_token: &IdmsToken,

-        session_key: &SessionKey,

-        cookie: &AuthCookie,

-    ) -> Result<Token, AppTokenRequestError> {

+        master: &MasterToken,

+    ) -> Result<RawToken, AppTokenRequestError> {

+        let MasterToken {

+            idms_token,

+            session_key,

+            cookie,

+        } = master;

         let alt_dsid = self.alt_dsid.0.as_str();

         let gs_service_url = self

@@ -308,7 +377,7 @@ pub(super) fn header_text(

 pub(super) fn header_token(

     value: &reqwest::header::HeaderValue,

     name: &'static str,

-) -> Result<(String, Token), ResponseTokenError> {

+) -> Result<(String, RawToken), ResponseTokenError> {

     use base64::{Engine, prelude::BASE64_STANDARD};

     let bytes = BASE64_STANDARD

         .decode(value.as_bytes())

@@ -330,7 +399,7 @@ pub(super) fn header_token(

         .ok_or(ResponseTokenError::InvalidHeader(name))?;

     Ok((

         fields[0].to_owned(),

-        Token {

+        RawToken {

             token: fields[1].to_owned(),

             duration,

             expiry_epoch_millis,

@@ -1,5 +1,5 @@

 use crate::http_session::{AnisetteHTTPSession, AppleError, parse_status};

-use adi::proxy::ADIError;

+use adi::proxy::{ADIError, ADIProvisioningSession, ADIProxy, ADIResult};

 use base64::Engine;

 use base64::prelude::BASE64_STANDARD;

 use plist::{Dictionary, Value};

@@ -306,6 +306,7 @@ pub async fn sync_machine(

         .ok_or_else(|| SyncError::ResponseStructure(sync_machine_response_plist.clone()))?;

     if code != 0 {

         return Err(SyncError::Apple(AppleError {

+            subcode: status.get("sec").and_then(Value::as_signed_integer),

             code,

             message: status

                 .get("em")

@@ -5,7 +5,7 @@ use reqwest::{Method, RequestBuilder};

 use serde::{Deserialize, Serialize};

 #[derive(Debug, Deserialize, Serialize, Clone)]

-pub struct Token<T = String> {

+pub struct Token<T: AppToken> {

     pub duration: u64,

     // #[serde(rename = "cts")]

     // pub start_epoch_millis: u64,

@@ -14,6 +14,25 @@ pub struct Token<T = String> {

     pub token: T,

 }

+/// An app token for a service identifier supplied at runtime.

+#[derive(Debug, Deserialize, Serialize, Clone)]

+pub struct RawToken {

+    pub duration: u64,

+    #[serde(rename = "expiry")]

+    pub expiry_epoch_millis: u64,

+    pub token: String,

+}

+

+impl<T: AppToken> From<RawToken> for Token<T> {

+    fn from(token: RawToken) -> Self {

+        Self {

+            duration: token.duration,

+            expiry_epoch_millis: token.expiry_epoch_millis,

+            token: T::from(token.token),

+        }

+    }

+}

+

 pub trait AppToken: From<String> + AsRef<str> {

     const APP_TOKEN_IDENTIFIER: &'static str;

 }

@@ -43,7 +62,7 @@ impl TokenBag {

         Ok(Self(tokens))

     }

-    pub fn entries(&self) -> Result<std::collections::BTreeMap<String, Token>, plist::Error> {

+    pub fn entries(&self) -> Result<std::collections::BTreeMap<String, RawToken>, plist::Error> {

         self.0

             .iter()

             .map(|(service, value)| Ok((service.clone(), plist::from_value(value)?)))

@@ -51,12 +70,8 @@ impl TokenBag {

     }

     pub fn get<T: AppToken>(&self) -> Option<Token<T>> {

-        let token: Token = plist::from_value(self.0.get(T::APP_TOKEN_IDENTIFIER)?).ok()?;

-        Some(Token {

-            duration: token.duration,

-            expiry_epoch_millis: token.expiry_epoch_millis,

-            token: T::from(token.token),

-        })

+        let token: RawToken = plist::from_value(self.0.get(T::APP_TOKEN_IDENTIFIER)?).ok()?;

+        Some(token.into())

     }

 }

@@ -97,6 +97,7 @@ impl<'lt, 'adi> IdentityHTTPSession<'lt, 'adi> {

             0 => Ok(()),

             -21669 => Err(ValidateCodeError::InvalidCode),

             code => Err(AppleError {

+                subcode: response_plist.get("sec").and_then(Value::as_signed_integer),

                 code,

                 message: response_plist

                     .get("em")

@@ -18,6 +18,7 @@ const SIMULATED_AUTHENTICATION_FRAMEWORK_INFORMATION: BundleInformation =

 pub struct AppleError {

     // description: String,

     pub code: i64,

+    pub subcode: Option<i64>,

     pub message: String,

 }

@@ -64,6 +65,9 @@ pub fn parse_status(status_dict: &Dictionary) -> Result<(), AppleError> {

             Err(AppleError {

                 // description: ed.to_string(),

                 code: ec,

+                subcode: status_dict

+                    .get("sec")

+                    .and_then(plist::Value::as_signed_integer),

                 message: em.to_string(),

             })

         }

@@ -0,0 +1,15 @@

+[package]

+name = "icloud"

+version = "0.1.0"

+edition = "2024"

+

+[dependencies]

+adi.workspace = true

+grandslam.workspace = true

+plist.workspace = true

+plist-macros.workspace = true

+reqwest.workspace = true

+thiserror.workspace = true

+serde = { version = "1", features = ["derive"] }

+serde_json = "1"

+uuid = { version = "1.19", features = ["v4"] }

@@ -0,0 +1,44 @@

+# Native iCloud

+

+Experimental native authentication and CloudKit container setup, built on

+`grandslam`. This crate does **not yet list or download iCloud Drive files**.

+It does not use the iCloud website's session cookies or Drive JSON endpoints.

+

+The implemented authentication steps are:

+

+1. Obtain `PasswordEquivalentToken` from a GrandSlam SRP authentication result.

+   Antarctic may return a still-valid cached PET or renew one using CK; it does

+   not submit this identifier to the master-token `apptokens` exchange.

+2. Build a MobileMe delegate request with `account::login_request_builder` and

+   submit it with `account::login`. The result wraps the returned service data.

+3. Extract the numeric DSID, `MmeAuthToken`, and `CloudKitToken` as needed.

+4. Call `cloudkit::CLOUD_DOCS.initialize` with the DSID and MobileMe token to

+   resolve the container-scoped user ID.

+5. Construct `CloudKitSession` with that ID and the CloudKit token. Its request

+   builder is a low-level header builder; protobuf operations are not implemented.

+

+`ICloudSession::account_settings` implements the native account-settings refresh.

+`AccountSettings::service` exposes the server's dataclass configuration, including

+`com.apple.Dataclass.CKDatabaseService` and its `url`. Future operations should use

+these URLs instead of assuming an account's server shard.

+

+PETs are used for login; MobileMe tokens authenticate setup/account requests;

+CloudKit tokens authenticate database requests. None are implicitly forwarded to

+asset download servers. Secret-bearing types deliberately omit `Debug`.

+

+## Validation status

+

+Compiled locally; synthetic parser checks covered success, rejected top-level

+and delegate statuses, missing fields, malformed plists and both settings layouts.

+Native MobileMe login and container initialization have not yet been validated

+with an account. PET acquisition has been: password-based SRP returned a fresh

+PET, while requesting the PET identifier through the same fresh master-token

+exchange returned `-22413`; an Xcode token request before and after it succeeded.

+

+The login builder permits a caller to add `X-Mme-Nas-Qualify` if validation data is

+available. Acceptance without that header is **unverified**. The Windows and

+macOS login paths must not be assumed interchangeable. No automatic terms

+acceptance, IDS enrollment, or account-key recovery is performed.

+

+See [native protocol notes](../research/icloud-windows/docs/native-drive.md) for the verified binary anchors

+and the remaining work needed for actual file access.

@@ -0,0 +1,279 @@

+use adi::proxy::{ADIError, ADIResult};

+use grandslam::plist_request::dict_to_body;

+use grandslam::{AccountHTTPSession, AppToken};

+use plist::{Dictionary, Value};

+use plist_macros::dict;

+use reqwest::{Method, RequestBuilder};

+use serde::{Deserialize, Serialize};

+use thiserror::Error;

+

+/// GrandSlam's password-equivalent token. Only used to establish iCloud credentials.

+#[derive(Clone, Serialize, Deserialize)]

+#[serde(transparent)]

+pub struct PasswordEquivalentToken(String);

+

+impl From<String> for PasswordEquivalentToken {

+    fn from(value: String) -> Self {

+        Self(value)

+    }

+}

+

+impl AsRef<str> for PasswordEquivalentToken {

+    fn as_ref(&self) -> &str {

+        &self.0

+    }

+}

+

+impl AppToken for PasswordEquivalentToken {

+    const APP_TOKEN_IDENTIFIER: &'static str = "com.apple.gs.idms.pet";

+}

+

+/// Numeric account ID returned by iCloud, distinct from GrandSlam's alternate ID.

+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

+#[serde(transparent)]

+pub struct Dsid(String);

+

+impl AsRef<str> for Dsid {

+    fn as_ref(&self) -> &str {

+        &self.0

+    }

+}

+

+#[derive(Clone, Serialize, Deserialize)]

+#[serde(transparent)]

+pub struct MmeAuthToken(String);

+

+#[derive(Clone, Serialize, Deserialize)]

+#[serde(transparent)]

+pub struct CloudKitToken(String);

+

+impl AsRef<str> for MmeAuthToken {

+    fn as_ref(&self) -> &str {

+        &self.0

+    }

+}

+

+impl AsRef<str> for CloudKitToken {

+    fn as_ref(&self) -> &str {

+        &self.0

+    }

+}

+

+/// iCloud's service data. Extract only the credentials needed by each service.

+/// Deliberately has no Debug implementation: the dictionary contains credentials.

+#[derive(Clone, Deserialize, Serialize)]

+#[serde(transparent)]

+pub struct AccountSettings(Dictionary);

+

+impl AccountSettings {

+    pub fn dsid(&self) -> Option<Dsid> {

+        let value = self.account_info()?.get("dsPrsID")?;

+        let dsid = match value {

+            Value::String(value)

+                if !value.is_empty() && value.bytes().all(|b| b.is_ascii_digit()) =>

+            {

+                value.clone()

+            }

+            Value::Integer(value) => value.as_unsigned()?.to_string(),

+            _ => return None,

+        };

+        Some(Dsid(dsid))

+    }

+

+    pub fn account_info(&self) -> Option<&Dictionary> {