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.

Reminders writes are signed the way the phone signs them, and join the list's order

Yashwanth Kamireddi989c8713b653
diff --git a/crates/quince-icloud/src/cloudkit.rs b/crates/quince-icloud/src/cloudkit.rs
index 82b887e..71fc26c 100644
--- a/crates/quince-icloud/src/cloudkit.rs
+++ b/crates/quince-icloud/src/cloudkit.rs
@@ -282,6 +282,106 @@ pub mod field {
}
}
+/// Seconds between the Unix epoch and Apple's, the first moment of 2001 UTC.
+const APPLE_EPOCH: f64 = 978_307_200.0;
+
+/// The token key Apple uses for a field: its name with the first letter lowered, except where
+/// Apple named it something else.
+fn token_key(field: &str) -> String {
+ match field {
+ "ReminderIDs" => "reminderIDsMergeableOrdering".into(),
+ _ => {
+ let mut chars = field.chars();
+ chars.next().map_or_else(String::new, |first| {
+ first.to_lowercase().chain(chars).collect()
+ })
+ }
+ }
+}
+
+/// Add a `ResolutionTokenMap` to `fields` advancing the token of every field in it.
+fn stamp_tokens(fields: &mut Value, current: Option<&Value>) {
+ let Some(written) = fields.as_object() else {
+ return;
+ };
+ let mut map: Value = current
+ .and_then(|c| c.pointer("/fields/ResolutionTokenMap/value"))
+ .and_then(Value::as_str)
+ .and_then(|s| serde_json::from_str(s).ok())
+ .filter(|v: &Value| v.get("map").is_some_and(Value::is_object))
+ .unwrap_or_else(|| json!({ "map": {} }));
+ let now = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0.0, |d| d.as_secs_f64())
+ - APPLE_EPOCH;
+ let writer = crate::topotext::writer_id();
+ let names: Vec<String> = written
+ .keys()
+ .filter(|k| k.as_str() != "ResolutionTokenMap")
+ .cloned()
+ .collect();
+ for name in names {
+ let key = token_key(&name);
+ let counter = map["map"][&key]["counter"].as_u64().unwrap_or(0) + 1;
+ map["map"][key] =
+ json!({ "counter": counter, "modificationTime": now, "replicaID": writer });
+ }
+ fields["ResolutionTokenMap"] = json!({ "type": "STRING", "value": map.to_string() });
+}
+
+#[cfg(test)]
+mod token_tests {
+ use super::*;
+
+ fn tokens(fields: &Value) -> Value {
+ serde_json::from_str(fields["ResolutionTokenMap"]["value"].as_str().unwrap()).unwrap()
+ }
+
+ /// The shape measured on the phone's own records.
+ #[test]
+ fn each_field_written_gets_its_token_advanced() {
+ let current = json!({ "fields": { "ResolutionTokenMap": { "type": "STRING", "value":
+ r#"{"map":{"titleDocument":{"counter":1,"modificationTime":803701265.4,"replicaID":"A"},
+ "priority":{"counter":4,"modificationTime":803701265.4,"replicaID":"B"},
+ "reminderIDsMergeableOrdering":{"counter":123,"modificationTime":1.0,"replicaID":"C"}}}"# } } });
+ let mut fields = json!({
+ "TitleDocument": { "type": "ENCRYPTED_BYTES", "value": "x" },
+ "ReminderIDs": { "type": "STRING", "value": "[]" },
+ "LastModifiedDate": { "type": "TIMESTAMP", "value": 1 },
+ });
+ stamp_tokens(&mut fields, Some(&current));
+ let map = &tokens(&fields)["map"];
+ assert_eq!(map["titleDocument"]["counter"], 2);
+ assert_eq!(map["reminderIDsMergeableOrdering"]["counter"], 124);
+ assert_eq!(map["lastModifiedDate"]["counter"], 1);
+ // What was not written is left exactly as it was.
+ assert_eq!(map["priority"]["counter"], 4);
+ assert_eq!(map["priority"]["replicaID"], "B");
+ // Now, in Apple's seconds, by this installation.
+ let t = map["titleDocument"]["modificationTime"].as_f64().unwrap();
+ assert!(t > 812_000_000.0, "{t}");
+ assert_eq!(
+ map["titleDocument"]["replicaID"],
+ crate::topotext::writer_id()
+ );
+ }
+
+ #[test]
+ fn a_new_record_starts_every_token_at_one() {
+ let mut fields = json!({ "Name": { "type": "STRING", "value": "GYM" } });
+ stamp_tokens(&mut fields, None);
+ assert_eq!(tokens(&fields)["map"]["name"]["counter"], 1);
+ }
+
+ #[test]
+ fn a_broken_map_is_started_again_rather_than_kept() {
+ let current = json!({ "fields": { "ResolutionTokenMap": { "type": "STRING", "value": "not json" } } });
+ let mut fields = json!({ "Flagged": { "type": "NUMBER_INT64", "value": 1 } });
+ stamp_tokens(&mut fields, Some(&current));
+ assert_eq!(tokens(&fields)["map"]["flagged"]["counter"], 1);
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -520,6 +620,49 @@ impl ZoneClient<'_> {
///
/// The caller supplies the record name so the same identifier can be stored locally
/// without waiting for a round trip.
+ /// [`Self::update_record`], with each changed field's resolution token advanced.
+ ///
+ /// Reminders and lists carry `ResolutionTokenMap`, a JSON map from each field to
+ /// `{counter, modificationTime, replicaID}`, and a phone merges field by field on those
+ /// tokens. A write that leaves them alone gives a phone no reason to prefer it — measured on
+ /// the account, a reminder created here had every token at counter 0, and the phone's own
+ /// edits carry counters of 1 and up. So each field written gets its counter raised, the
+ /// time set to now, and this installation as the writer. Only for record types that carry
+ /// the map: CloudKit refuses a field its schema does not already have.
+ pub async fn update_record_signed(
+ &self,
+ zone: &str,
+ record_name: &str,
+ record_type: &str,
+ change_tag: Option<&str>,
+ mut changes: Value,
+ ) -> Result<Value> {
+ let current = self.lookup_record(zone, record_name).await?;
+ stamp_tokens(&mut changes, current.as_ref());
+ let tag = change_tag.map(ToString::to_string).or_else(|| {
+ current
+ .as_ref()
+ .and_then(|c| c.get("recordChangeTag"))
+ .and_then(Value::as_str)
+ .map(ToString::to_string)
+ });
+ self.update_record(zone, record_name, record_type, tag.as_deref(), changes)
+ .await
+ }
+
+ /// [`Self::create_record`], with a first token for every field, as the phone makes one.
+ pub async fn create_record_signed(
+ &self,
+ zone: &str,
+ record_name: &str,
+ record_type: &str,
+ mut fields: Value,
+ ) -> Result<Value> {
+ stamp_tokens(&mut fields, None);
+ self.create_record(zone, record_name, record_type, fields)
+ .await
+ }
+
pub async fn create_record(
&self,
zone: &str,
diff --git a/crates/quince-icloud/src/reminders.rs b/crates/quince-icloud/src/reminders.rs
index 0e2d1cd..bbf6de8 100644
--- a/crates/quince-icloud/src/reminders.rs
+++ b/crates/quince-icloud/src/reminders.rs
@@ -1130,7 +1130,7 @@ pub async fn create_cloudkit(
let stamp = now_millis();
client
- .create_record(
+ .create_record_signed(
ZONE,
&record_name,
"Reminder",
@@ -1148,9 +1148,61 @@ pub async fn create_cloudkit(
)
.await?;
+ // The phone adds a new reminder to the end of its list's own order. Without that, a list
+ // sorted by hand has nowhere to put it — measured: a list of 126 reminders held 125 ids,
+ // the missing one the reminder made here. The reminder itself is made either way, so a
+ // failure here costs its place in the order, never the reminder.
+ let _ = place_in_list(&client, list_guid, &record_name, None).await;
+
Ok(record_name)
}
+/// Add a reminder to the end of a list's `ReminderIDs`, and take it out of the list it left.
+async fn place_in_list(
+ client: &ZoneClient<'_>,
+ list_guid: &str,
+ reminder_guid: &str,
+ left: Option<&str>,
+) -> Result<()> {
+ let id = reminder_guid
+ .rsplit('/')
+ .next()
+ .unwrap_or(reminder_guid)
+ .to_string();
+ let edit = |list: Value, add: bool| {
+ let mut ids: Vec<String> = list
+ .pointer("/fields/ReminderIDs/value")
+ .and_then(Value::as_str)
+ .and_then(|s| serde_json::from_str(s).ok())
+ .unwrap_or_default();
+ let had = ids.iter().any(|x| x.eq_ignore_ascii_case(&id));
+ if add && !had {
+ ids.push(id.clone());
+ } else if !add && had {
+ ids.retain(|x| !x.eq_ignore_ascii_case(&id));
+ } else {
+ return None;
+ }
+ Some(serde_json::json!({
+ "ReminderIDs": { "type": "STRING", "value": serde_json::to_string(&ids).unwrap_or_default() }
+ }))
+ };
+ for (guid, add) in [Some((list_guid, true)), left.map(|l| (l, false))]
+ .into_iter()
+ .flatten()
+ {
+ let Some(list) = client.lookup_record(ZONE, guid).await? else {
+ continue;
+ };
+ if let Some(fields) = edit(list, add) {
+ client
+ .update_record_signed(ZONE, guid, "List", None, fields)
+ .await?;
+ }
+ }
+ Ok(())
+}
+
/// How often a reminder comes back.
///
/// Apple's frequency is 0 daily, 1 weekly, 2 monthly, 3 yearly — the same numbering the
@@ -1236,7 +1288,7 @@ pub async fn set_recurrence_cloudkit(
.or(reminder.etag.as_deref());
client
- .update_record(
+ .update_record_signed(
ZONE,
&reminder.guid,
"Reminder",
@@ -1270,7 +1322,7 @@ pub async fn delete_cloudkit(
) -> Result<()> {
let client = ZoneClient::new(http, ckdatabasews_root, CONTAINER, params);
client
- .update_record(
+ .update_record_signed(
ZONE,
&reminder.guid,
"Reminder",
@@ -1457,8 +1509,23 @@ pub async fn edit_cloudkit(
.or(reminder.etag.as_deref());
client
- .update_record(ZONE, &reminder.guid, "Reminder", tag, Value::Object(fields))
+ .update_record_signed(ZONE, &reminder.guid, "Reminder", tag, Value::Object(fields))
.await?;
+ // Moved to another list: it joins the end of that list's order and leaves the old one's,
+ // as on the phone. The move itself has happened either way.
+ if let Some(list_guid) = edit
+ .list_guid
+ .as_deref()
+ .filter(|l| *l != reminder.list_guid)
+ {
+ let _ = place_in_list(
+ &client,
+ list_guid,
+ &reminder.guid,
+ Some(&reminder.list_guid),
+ )
+ .await;
+ }
Ok(())
}
@@ -1481,7 +1548,7 @@ pub async fn create_list_cloudkit(
let record_name = format!("List/{}", uuid::Uuid::new_v4().to_string().to_uppercase());
client
- .create_record(
+ .create_record_signed(
ZONE,
&record_name,
"List",
@@ -1511,7 +1578,7 @@ pub async fn rename_list_cloudkit(
}
let client = ZoneClient::new(http, ckdatabasews_root, CONTAINER, params);
client
- .update_record(
+ .update_record_signed(
ZONE,
list_guid,
"List",
@@ -1534,7 +1601,7 @@ pub async fn delete_list_cloudkit(
) -> Result<()> {
let client = ZoneClient::new(http, ckdatabasews_root, CONTAINER, params);
client
- .update_record(
+ .update_record_signed(
ZONE,
list_guid,
"List",
@@ -1582,7 +1649,7 @@ pub async fn set_completed_cloudkit(
};
client
- .update_record(
+ .update_record_signed(
ZONE,
&reminder.guid,
"Reminder",
@@ -1953,13 +2020,25 @@ mod write_tests {
.await
.unwrap();
- let sent: Value =
- serde_json::from_slice(&server.received_requests().await.unwrap()[0].body).unwrap();
+ let requests = server.received_requests().await.unwrap();
+ let modify = requests
+ .iter()
+ .find(|r| r.url.path().ends_with("/records/modify"))
+ .expect("a write was sent");
+ let sent: Value = serde_json::from_slice(&modify.body).unwrap();
assert_eq!(sent["operations"][0]["operationType"], "update");
assert_eq!(
sent["operations"][0]["record"]["fields"]["Deleted"]["value"],
1
);
+ // Signed, so a phone merging field by field has a reason to take it.
+ let tokens: Value = serde_json::from_str(
+ sent["operations"][0]["record"]["fields"]["ResolutionTokenMap"]["value"]
+ .as_str()
+ .expect("the write carries resolution tokens"),
+ )
+ .unwrap();
+ assert!(tokens["map"]["deleted"]["counter"].as_u64() >= Some(1));
assert_eq!(
sent["operations"][0]["record"]["recordChangeTag"], "tag-3",
"the change tag guards against clobbering a newer edit"
@@ -3832,3 +3911,74 @@ mod account_order_tests {
assert_eq!(before, after);
}
}
+
+/// A reminder made here takes its place in its list's own order, as one made on the phone does.
+#[cfg(test)]
+mod list_order_write_tests {
+ use super::*;
+ use serde_json::json;
+ use wiremock::matchers::{method, path_regex};
+ use wiremock::{Mock, MockServer, ResponseTemplate};
+
+ #[tokio::test]
+ async fn a_new_reminder_joins_the_end_of_its_list() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path_regex(r".*/records/lookup$"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "records": [{
+ "recordName": "List/L", "recordType": "List", "recordChangeTag": "t1",
+ "fields": {
+ "ReminderIDs": { "type": "STRING", "value": "[\"AAA\",\"BBB\"]" },
+ "ResolutionTokenMap": { "type": "STRING", "value":
+ "{\"map\":{\"reminderIDsMergeableOrdering\":{\"counter\":123,\"modificationTime\":1,\"replicaID\":\"P\"}}}" }
+ }
+ }]})))
+ .mount(&server)
+ .await;
+ Mock::given(method("POST"))
+ .and(path_regex(r".*/records/modify$"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_json(json!({ "records": [{ "recordName": "x" }] })),
+ )
+ .mount(&server)
+ .await;
+
+ let made = create_cloudkit(
+ &reqwest::Client::new(),
+ &server.uri(),
+ vec![],
+ "List/L",
+ "Buy milk",
+ )
+ .await
+ .unwrap();
+ let uuid = made.trim_start_matches("Reminder/").to_string();
+
+ let lists: Vec<Value> = server
+ .received_requests()
+ .await
+ .unwrap()
+ .iter()
+ .filter(|r| r.url.path().ends_with("/records/modify"))
+ .filter_map(|r| serde_json::from_slice::<Value>(&r.body).ok())
+ .map(|b| b["operations"][0]["record"].clone())
+ .filter(|r| r["recordType"] == "List")
+ .collect();
+ assert_eq!(lists.len(), 1, "the list's order is written once");
+ let ids: Vec<String> =
+ serde_json::from_str(lists[0]["fields"]["ReminderIDs"]["value"].as_str().unwrap())
+ .unwrap();
+ assert_eq!(ids, vec!["AAA".to_string(), "BBB".into(), uuid]);
+ let tokens: Value = serde_json::from_str(
+ lists[0]["fields"]["ResolutionTokenMap"]["value"]
+ .as_str()
+ .unwrap(),
+ )
+ .unwrap();
+ assert_eq!(
+ tokens["map"]["reminderIDsMergeableOrdering"]["counter"],
+ 124
+ );
+ }
+}
diff --git a/crates/quince-icloud/src/topotext.rs b/crates/quince-icloud/src/topotext.rs
index e16f169..00e655b 100644
--- a/crates/quince-icloud/src/topotext.rs
+++ b/crates/quince-icloud/src/topotext.rs
@@ -36,6 +36,12 @@ pub fn set_writer(id: [u8; 16]) {
let _ = WRITER.set(id);
}
+/// This installation's writer id, as Apple writes a replica id: an uppercase UUID.
+#[must_use]
+pub fn writer_id() -> String {
+ uuid::Uuid::from_bytes(writer()).to_string().to_uppercase()
+}
+
fn writer() -> [u8; 16] {
*WRITER.get_or_init(|| *uuid::Uuid::new_v4().as_bytes())
}