Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.
Rust apple-notesapple-reminderscloudkitcrdtdesktop-appicloudicloud-calendaricloud-driveicloud-notesicloud-photosiphonelinuxlinux-desktoplocal-firstoffline-firstprivacyrusttauritauri-appwindows
Calendar client: read Apple's dates without trusting them
Yashwanth Kamireddi2819117f0ba5
diff --git a/Cargo.lock b/Cargo.lockindex b28ef18..1163675 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1804,9 +1804,9 @@ dependencies = [[[package]]name = "jiff"-version = "0.2.36"+version = "0.2.37"source = "registry+https://github.com/rust-lang/crates.io-index"-checksum = "ab029497d95f294d364e77e36012a8842255163805c469a9c07451509bf5f847"+checksum = "0ab1baf72f08796de0260609515130699b890ac25f30e610ad894bc5856cafdb"dependencies = ["defmt","jiff-core",@@ -1831,9 +1831,9 @@ dependencies = [[[package]]name = "jiff-static"-version = "0.2.36"+version = "0.2.37"source = "registry+https://github.com/rust-lang/crates.io-index"-checksum = "9fbc18d65120b0ebdcf39368e770879849b1255e0118788018d4154a6c0be528"+checksum = "378268a1116ad67ae6228701118ac9f491d78fda38a40a1f1a9e1348de6f7212"dependencies = ["jiff-core","proc-macro2",@@ -2812,6 +2812,20 @@ dependencies = ["thiserror 2.0.20",]+[[package]]+name = "quince-icloud"+version = "0.1.0"+dependencies = [+ "jiff",+ "quince-core",+ "reqwest 0.12.28",+ "serde",+ "serde_json",+ "thiserror 2.0.20",+ "tokio",+ "wiremock",+]+[[package]]name = "quince-probe"version = "0.0.0"diff --git a/Cargo.toml b/Cargo.tomlindex 5a6088c..7641132 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -1,6 +1,6 @@[workspace]resolver = "2"-members = ["probe", "crates/quince-auth", "crates/quince-core", "src-tauri"]+members = ["probe", "crates/quince-auth", "crates/quince-core", "crates/quince-icloud", "src-tauri"][workspace.package]edition = "2021"diff --git a/crates/quince-icloud/Cargo.toml b/crates/quince-icloud/Cargo.tomlnew file mode 100644index 0000000..eb1c14d--- /dev/null+++ b/crates/quince-icloud/Cargo.toml@@ -0,0 +1,18 @@+[package]+name = "quince-icloud"+version = "0.1.0"+edition.workspace = true+rust-version.workspace = true+license.workspace = true++[dependencies]+quince-core = { path = "../quince-core" }+reqwest.workspace = true+serde.workspace = true+serde_json.workspace = true+thiserror = "2"+jiff = "0.2.37"++[dev-dependencies]+tokio = { workspace = true }+wiremock = "0.6"diff --git a/crates/quince-icloud/src/calendar.rs b/crates/quince-icloud/src/calendar.rsnew file mode 100644index 0000000..8ff301b--- /dev/null+++ b/crates/quince-icloud/src/calendar.rs@@ -0,0 +1,361 @@+//! Apple's calendar web service.+//!+//! `/ca/startup` returns the collections plus the events in a window; `/ca/events` returns+//! events alone. Both are shaped for the icloud.com web client rather than for us.++use crate::{Error, Result};+use jiff::{civil, tz::TimeZone};+use quince_core::calendar::{Calendar, Event};+use serde_json::Value;++/// Apple encodes an instant as `[YYYYMMDD, year, month, day, hour, minute, minsSinceMidnight]`+/// alongside a separate named timezone — not as a timestamp.+///+/// Converting needs the zone, because the same wall-clock reading means different instants in+/// different places. A missing or unknown zone falls back to UTC rather than failing the whole+/// sync over one event.+fn parse_apple_date(raw: &Value, timezone: Option<&str>) -> Result<i64> {+ let parts = raw+ .as_array()+ .ok_or_else(|| Error::Protocol("a date was not an array".into()))?;+ // Index 0 is a packed YYYYMMDD that duplicates the fields after it; the components are+ // what we read. Anything shorter than six entries is unusable.+ if parts.len() < 6 {+ return Err(Error::Protocol(format!(+ "a date had {} components, expected at least 6",+ parts.len()+ )));+ }+ let at = |i: usize| -> Result<i64> {+ parts[i]+ .as_i64()+ .ok_or_else(|| Error::Protocol(format!("date component {i} was not a number")))+ };++ let (year, month, day, hour, minute) = (at(1)?, at(2)?, at(3)?, at(4)?, at(5)?);++ // `civil::date` PANICS on an out-of-range component, and these numbers come off the+ // network. The checked constructor is the only safe way to build one from untrusted input.+ let narrow = |v: i64, what: &str| -> Result<i8> {+ i8::try_from(v).map_err(|_| Error::Protocol(format!("implausible {what} {v}")))+ };+ let civil_dt = civil::DateTime::new(+ i16::try_from(year).map_err(|_| Error::Protocol(format!("implausible year {year}")))?,+ narrow(month, "month")?,+ narrow(day, "day")?,+ narrow(hour, "hour")?,+ narrow(minute, "minute")?,+ 0,+ 0,+ )+ .map_err(|e| {+ Error::Protocol(format!(+ "{year}-{month}-{day} {hour}:{minute} is not a date: {e}"+ ))+ })?;++ // An unknown zone is not worth failing a sync over; UTC keeps the event visible.+ let zone = timezone+ .and_then(|name| TimeZone::get(name).ok())+ .unwrap_or(TimeZone::UTC);++ let zoned = civil_dt+ .to_zoned(zone)+ .map_err(|e| Error::Protocol(format!("couldn't place {civil_dt} in its timezone: {e}")))?;+ Ok(zoned.timestamp().as_second())+}++fn string(v: &Value, key: &str) -> Option<String> {+ v.get(key)+ .and_then(Value::as_str)+ .filter(|s| !s.is_empty())+ .map(ToString::to_string)+}++/// Turn one entry of Apple's `Collection` array into a calendar.+fn collection_from(v: &Value) -> Option<Calendar> {+ Some(Calendar {+ guid: string(v, "guid")?,+ title: string(v, "title").unwrap_or_else(|| "Untitled".into()),+ colour: string(v, "color"),+ ctag: string(v, "ctag"),+ sort_order: v.get("order").and_then(Value::as_i64).unwrap_or(0),+ // Apple omits `enabled` for calendars that are on.+ enabled: v.get("enabled").and_then(Value::as_bool).unwrap_or(true),+ })+}++/// Turn one entry of Apple's `Event` array into an event.+///+/// Returns `Ok(None)` for entries that carry no usable identity, so one odd row cannot fail+/// an otherwise good sync.+fn event_from(v: &Value) -> Result<Option<Event>> {+ let (Some(guid), Some(calendar_guid)) = (string(v, "guid"), string(v, "pGuid")) else {+ return Ok(None);+ };+ let timezone = string(v, "tz");+ let Some(start_raw) = v.get("startDate") else {+ return Ok(None);+ };++ let starts_at = parse_apple_date(start_raw, timezone.as_deref())?;+ let ends_at = match v.get("endDate") {+ Some(raw) => parse_apple_date(raw, timezone.as_deref())?,+ // Apple omits endDate on some entries; a duration in minutes is the fallback.+ None => {+ let minutes = v.get("duration").and_then(Value::as_i64).unwrap_or(0);+ starts_at + minutes * 60+ }+ };++ Ok(Some(Event {+ guid,+ calendar_guid,+ title: string(v, "title").unwrap_or_else(|| "Untitled".into()),+ location: string(v, "location"),+ starts_at,+ // A zero-length event still needs to be selectable, and an end before its start is+ // nonsense we should not store.+ ends_at: ends_at.max(starts_at),+ all_day: v.get("allDay").and_then(Value::as_bool).unwrap_or(false),+ timezone,+ url: string(v, "url"),+ notes: string(v, "description"),+ etag: string(v, "etag"),+ }))+}++/// Everything one calendar refresh yields.+#[derive(Debug, Default)]+pub struct Snapshot {+ pub calendars: Vec<Calendar>,+ pub events: Vec<Event>,+}++/// Read a `/ca/startup` or `/ca/events` body.+///+/// Malformed individual events are skipped rather than failing the batch: Apple's calendar is+/// long-lived data and one unparseable row from years ago should not block today's sync.+pub fn parse_snapshot(body: &Value) -> Snapshot {+ let calendars = body+ .get("Collection")+ .and_then(Value::as_array)+ .map(|arr| arr.iter().filter_map(collection_from).collect())+ .unwrap_or_default();++ let events = body+ .get("Event")+ .and_then(Value::as_array)+ .map(|arr| {+ arr.iter()+ .filter_map(|v| event_from(v).ok().flatten())+ .collect()+ })+ .unwrap_or_default();++ Snapshot { calendars, events }+}++/// Apple's calendar service.+pub struct CalendarClient<'a> {+ http: &'a reqwest::Client,+ root: String,+ params: Vec<(String, String)>,+}++impl<'a> CalendarClient<'a> {+ pub fn new(http: &'a reqwest::Client, root: &str, params: Vec<(String, String)>) -> Self {+ Self {+ http,+ root: root.trim_end_matches('/').to_string(),+ params,+ }+ }++ /// Collections plus the events between two dates, formatted `YYYY-MM-DD`.+ pub async fn startup(&self, from: &str, to: &str, tz: &str) -> Result<Snapshot> {+ let body = self.get("/ca/startup", from, to, tz).await?;+ Ok(parse_snapshot(&body))+ }++ /// Events alone, for refreshing a window without refetching the collections.+ pub async fn events(&self, from: &str, to: &str, tz: &str) -> Result<Snapshot> {+ let body = self.get("/ca/events", from, to, tz).await?;+ Ok(parse_snapshot(&body))+ }++ async fn get(&self, path: &str, from: &str, to: &str, tz: &str) -> Result<Value> {+ let mut query = self.params.clone();+ query.push(("startDate".into(), from.into()));+ query.push(("endDate".into(), to.into()));+ query.push(("lang".into(), "en-us".into()));+ query.push(("usertz".into(), tz.into()));++ let response = self+ .http+ .get(format!("{}{path}", self.root))+ .query(&query)+ .send()+ .await?;+ let status = response.status();+ let text = response.text().await.unwrap_or_default();++ if status.as_u16() == 450 {+ return Err(Error::ReauthRequired);+ }+ if !status.is_success() {+ return Err(Error::Protocol(format!(+ "{path} returned {status}: {}",+ text.chars().take(160).collect::<String>()+ )));+ }+ serde_json::from_str(&text)+ .map_err(|e| Error::Protocol(format!("{path} returned invalid JSON: {e}")))+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ #[test]+ fn a_date_is_read_in_its_own_timezone() {+ // 14:30 in Kolkata is 09:00 UTC — the zone is what makes this unambiguous.+ let raw = json!([20260912, 2026, 9, 12, 14, 30, 870]);+ let seconds = parse_apple_date(&raw, Some("Asia/Kolkata")).unwrap();+ let utc = jiff::Timestamp::from_second(seconds).unwrap();+ assert_eq!(utc.to_string(), "2026-09-12T09:00:00Z");+ }++ #[test]+ fn the_same_reading_in_another_zone_is_another_instant() {+ let raw = json!([20260912, 2026, 9, 12, 14, 30, 870]);+ let kolkata = parse_apple_date(&raw, Some("Asia/Kolkata")).unwrap();+ let new_york = parse_apple_date(&raw, Some("America/New_York")).unwrap();+ assert_ne!(+ kolkata, new_york,+ "wall-clock time alone does not identify an instant"+ );+ // New York is behind, so the same reading happens later in absolute terms.+ assert!(new_york > kolkata);+ }++ /// The hour that does not exist on a spring-forward day must not fail a sync.+ #[test]+ fn a_daylight_saving_gap_resolves_rather_than_erroring() {+ // 02:30 on 8 March 2026 never happens in New York.+ let raw = json!([20260308, 2026, 3, 8, 2, 30, 150]);+ let seconds = parse_apple_date(&raw, Some("America/New_York")).unwrap();+ assert!(+ seconds > 0,+ "a nonexistent local time should shift, not blow up"+ );+ }++ #[test]+ fn an_unknown_timezone_falls_back_to_utc() {+ let raw = json!([20260912, 2026, 9, 12, 14, 30, 870]);+ let unknown = parse_apple_date(&raw, Some("Mars/Olympus_Mons")).unwrap();+ let utc = parse_apple_date(&raw, None).unwrap();+ assert_eq!(unknown, utc, "one bad zone must not lose the event");+ }++ /// Network input must never panic, however malformed.+ #[test]+ fn malformed_dates_are_errors_not_panics() {+ for bad in [+ json!("2026-09-12"),+ json!([]),+ json!([20260912, 2026, 9]),+ json!([20260912, 2026, 99, 12, 14, 30]), // month out of range+ json!([20260912, 2026, 2, 31, 14, 30]), // a day that does not exist+ json!([20260912, 2026, 9, 12, 99, 30]), // hour out of range+ json!([20260912, 2026, 9, 12, 14, 999]), // minute out of range+ json!([20260912, 2026, 0, 12, 14, 30]), // zero month+ json!([20260912, 2026, 9, 12, "two", 30]),+ json!([20260912, 999_999, 9, 12, 14, 30]),+ ] {+ assert!(parse_apple_date(&bad, None).is_err(), "should reject {bad}");+ }+ }++ #[test]+ fn a_snapshot_reads_collections_and_events() {+ let body = json!({+ "Collection": [+ { "guid": "cal-1", "title": "Work", "color": "#C8912A", "ctag": "c1", "order": 1 },+ { "guid": "cal-2", "title": "Home", "enabled": false }+ ],+ "Event": [+ {+ "guid": "ev-1", "pGuid": "cal-1", "title": "Standup",+ "location": "Room 2", "tz": "Asia/Kolkata",+ "startDate": [20260912, 2026, 9, 12, 9, 30, 570],+ "endDate": [20260912, 2026, 9, 12, 9, 45, 585],+ "etag": "e1"+ }+ ]+ });+ let snap = parse_snapshot(&body);++ assert_eq!(snap.calendars.len(), 2);+ assert_eq!(snap.calendars[0].colour.as_deref(), Some("#C8912A"));+ assert!(+ snap.calendars[0].enabled,+ "a calendar with no `enabled` flag is on"+ );+ assert!(!snap.calendars[1].enabled);++ assert_eq!(snap.events.len(), 1);+ let event = &snap.events[0];+ assert_eq!(event.title, "Standup");+ assert_eq!(event.calendar_guid, "cal-1");+ assert_eq!(event.ends_at - event.starts_at, 15 * 60);+ }++ #[test]+ fn an_event_without_an_end_uses_its_duration() {+ let body = json!({ "Event": [{+ "guid": "ev-1", "pGuid": "cal-1", "title": "Focus",+ "startDate": [20260912, 2026, 9, 12, 9, 0, 540],+ "duration": 90+ }]});+ let snap = parse_snapshot(&body);+ assert_eq!(snap.events[0].ends_at - snap.events[0].starts_at, 90 * 60);+ }++ #[test]+ fn an_end_before_its_start_is_clamped() {+ let body = json!({ "Event": [{+ "guid": "ev-1", "pGuid": "cal-1", "title": "Backwards",+ "startDate": [20260912, 2026, 9, 12, 10, 0, 600],+ "endDate": [20260912, 2026, 9, 12, 9, 0, 540]+ }]});+ let event = &parse_snapshot(&body).events[0];+ assert_eq!(+ event.ends_at, event.starts_at,+ "a negative duration is not storable"+ );+ }++ /// One unparseable row from years ago must not block today's sync.+ #[test]+ fn one_bad_event_does_not_lose_the_good_ones() {+ let body = json!({ "Event": [+ { "guid": "bad", "pGuid": "cal-1", "startDate": "not-an-array" },+ { "guid": "no-identity", "title": "orphan" },+ { "guid": "good", "pGuid": "cal-1", "title": "Fine",+ "startDate": [20260912, 2026, 9, 12, 9, 0, 540], "duration": 30 }+ ]});+ let snap = parse_snapshot(&body);+ assert_eq!(snap.events.len(), 1);+ assert_eq!(snap.events[0].guid, "good");+ }++ #[test]+ fn an_empty_body_is_an_empty_snapshot() {+ let snap = parse_snapshot(&json!({}));+ assert!(snap.calendars.is_empty() && snap.events.is_empty());+ }+}diff --git a/crates/quince-icloud/src/lib.rs b/crates/quince-icloud/src/lib.rsnew file mode 100644index 0000000..7db8092--- /dev/null+++ b/crates/quince-icloud/src/lib.rs@@ -0,0 +1,20 @@+//! Clients for Apple's private iCloud web services, riding an authenticated session.+//!+//! These are reverse-engineered endpoints, not a published API. Every response is treated as+//! untrusted: a missing field or a malformed date returns an error, never a panic.++pub mod calendar;++#[derive(Debug, thiserror::Error)]+pub enum Error {+ #[error("couldn't reach iCloud: {0}")]+ Network(#[from] reqwest::Error),+ #[error("iCloud sent back something unexpected: {0}")]+ Protocol(String),+ #[error("this needs a fresh sign-in")]+ ReauthRequired,+ #[error(transparent)]+ Storage(#[from] quince_core::Error),+}++pub type Result<T> = std::result::Result<T, Error>;