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.

Edits keep what Skykeep does not model: round-trip proofs, and a tick that reordered fields

Yashwanth Kamireddi1916ccbffaca
diff --git a/crates/quince-icloud/src/calendar.rs b/crates/quince-icloud/src/calendar.rs
index 80dd390..915418a 100644
--- a/crates/quince-icloud/src/calendar.rs
+++ b/crates/quince-icloud/src/calendar.rs
@@ -2841,4 +2841,55 @@ mod odd_event_tests {
assert_eq!(body["title"], "Standup", "{odd} still produces the event");
}
}
+
+ /// A title edited here, on an event made on a Mac with everything this app does not show:
+ /// its alerts, guests, attachments, the repeat and its exceptions, a private comment, an
+ /// organiser, and fields Apple adds that nobody here knows. Every one goes back to Apple
+ /// exactly as Apple sent it; only the title — and the fields this app writes, with the
+ /// same values — differ.
+ #[test]
+ fn an_edit_keeps_everything_this_app_does_not_show() {
+ let http = reqwest::Client::new();
+ let client = CalendarClient::new(&http, "http://127.0.0.1:1", vec![]);
+ let existing = serde_json::json!({
+ "guid": "E1", "pGuid": "C1", "title": "Planning", "location": "Room 4",
+ "description": "Agenda", "url": null, "tz": "Europe/Berlin", "allDay": false,
+ "startDate": [20261105, 2026, 11, 5, 10, 0, 600],
+ "endDate": [20261105, 2026, 11, 5, 11, 0, 660],
+ "localStartDate": [20261105, 2026, 11, 5, 10, 0, 600],
+ "localEndDate": [20261105, 2026, 11, 5, 11, 0, 660],
+ "duration": 60, "etag": "C=9@U=x",
+ "alarms": ["E1:A1", "E1:A2"],
+ "invitees": ["E1:[email protected]", "E1:[email protected]"],
+ "organizer": "[email protected]",
+ "hasAttachments": true, "attachments": ["E1:ATT1"],
+ "recurrence": "E1*MME-RID",
+ "recurrenceMaster": true,
+ "recurrenceException": ["20261112T090000Z"],
+ "privateComments": "bring the numbers",
+ "changeRecurring": null,
+ "birthdayIsYearlessBday": false,
+ "X-APPLE-TRAVEL-ADVISORY-BEHAVIOR": "AUTOMATIC",
+ "someFieldAppleAddsLater": { "nested": [1, 2, 3] },
+ });
+ let event = event_from(&existing).unwrap().unwrap();
+ let mut renamed = event.clone();
+ renamed.title = "Planning, round 2".into();
+ let body = client.event_body(&renamed, Some(&existing));
+ let (Some(body), Some(was)) = (body.as_object(), existing.as_object()) else {
+ panic!("an event is an object");
+ };
+ for (key, value) in was {
+ if key == "title" {
+ continue;
+ }
+ assert_eq!(body.get(key), Some(value), "{key} changed or went missing");
+ }
+ assert_eq!(body["title"], "Planning, round 2");
+ assert_eq!(
+ body.len(),
+ was.len(),
+ "nothing added beyond what Apple holds"
+ );
+ }
}
diff --git a/crates/quince-icloud/src/ckdocument.rs b/crates/quince-icloud/src/ckdocument.rs
index 6cffed1..faecbb6 100644
--- a/crates/quince-icloud/src/ckdocument.rs
+++ b/crates/quince-icloud/src/ckdocument.rs
@@ -932,14 +932,21 @@ fn restyle(run: &[u8], change: ParagraphChange) -> Option<Vec<u8>> {
ParagraphChange::Checked(done) => {
let item = bytes_field(&paragraph, 5)?; // only a checklist item has a tick
let item = set_varint_field(&item, 2, u64::from(done))?;
- let mut p = without_field(&paragraph, 5)?;
- p.extend(length_delimited(5, &item));
- p
+ // In its place: every other field of the paragraph as it was, where it was.
+ rewrite(&paragraph, &[5], &item)?
}
};
- let mut out = without_field(run, 2)?;
- out.extend(length_delimited(2, &next));
- Some(out)
+ // In its place too, so whatever else the run holds — fields this app does not know, a
+ // newer phone's — stays as it was, in the order it was written; appended only where the
+ // run had no paragraph yet.
+ match rewrite(run, &[2], &next) {
+ Some(out) => Some(out),
+ None => {
+ let mut out = run.to_vec();
+ out.extend(length_delimited(2, &next));
+ Some(out)
+ }
+ }
}
/// Set a note's formatting from `runs` — what an editor shows — over a document whose text
@@ -1713,6 +1720,19 @@ pub fn repair_runs_in_base64(original: &str) -> Option<String> {
Some(B64.encode(gzip(&repair_runs(&raw)?)))
}
+/// A document's note message with its runs set to `runs`, raw: for a test to put in fields
+/// this app does not model, as a newer phone writes them.
+#[cfg(test)]
+pub(crate) fn with_raw_runs_for_test(original: &str, runs: &[Vec<u8>]) -> String {
+ let raw = B64.decode(original.trim()).unwrap_or_default();
+ let plain = inflate(&raw).unwrap_or_default();
+ let note = field_at(&plain, &TEXT_PATH[..2]).unwrap_or_default();
+ let rebuilt = with_runs(note, runs).unwrap_or_default();
+ B64.encode(gzip(
+ &rewrite(&plain, &TEXT_PATH[..2], &rebuilt).unwrap_or_default(),
+ ))
+}
+
/// A document as a phone would have written it: its records replaced by ones from a writer
/// that is not this app.
#[cfg(test)]
diff --git a/crates/quince-icloud/src/contacts.rs b/crates/quince-icloud/src/contacts.rs
index c38aabe..0b3e2bf 100644
--- a/crates/quince-icloud/src/contacts.rs
+++ b/crates/quince-icloud/src/contacts.rs
@@ -2719,6 +2719,66 @@ mod write_tests {
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, Request, ResponseTemplate};
+ /// A card as an iPhone keeps it, full of what this app does not show: instant messaging
+ /// (IMPP), social profiles, related names, custom labels, dates, a picture with its crop,
+ /// and fields of Apple's own. A first name changed here, and only that, goes back; every
+ /// other field is Apple's, byte for byte — the whole card too, through `card_written`.
+ #[test]
+ fn an_edit_keeps_every_field_this_app_does_not_show() {
+ let existing = json!({
+ "contactId": "C1", "etag": "e7", "isCompany": false,
+ "firstName": "Ada", "lastName": "Lovelace", "companyName": "Analytical",
+ "jobTitle": "Mathematician", "nickName": "Countess",
+ "phones": [
+ { "label": "MOBILE", "field": "+44 20 7946 0000" },
+ { "label": "_$!<Pager>!$_", "field": "555-0100" },
+ { "label": "Lab bench", "field": "555-0199" }
+ ],
+ "emailAddresses": [{ "label": "WORK", "field": "[email protected]" }],
+ "IMs": [{ "label": "SKYPE", "field": { "userName": "ada.l", "IMService": "Skype" } }],
+ "profiles": [{ "label": "TWITTER", "field": "https://x.com/ada", "user": "ada" }],
+ "relatedNames": [{ "label": "_$!<Mother>!$_", "field": "Anne Isabella Milbanke" }],
+ "dates": [{ "label": "_$!<Anniversary>!$_", "field": "1835-07-08" }],
+ "urls": [{ "label": "HOMEPAGE", "field": "https://example.com/ada" }],
+ "streetAddresses": [{ "label": "HOME", "field": { "street": "12 St James's Sq", "city": "London" } }],
+ "photo": { "url": "https://p.example/ada.jpg", "crop": { "x": 1, "y": 2, "width": 300, "height": 300 }, "signature": "sig" },
+ "X-ABShowAs": "PERSON",
+ "X-SOCIALPROFILE": "x-apple:ada",
+ "someFieldAppleAddsLater": { "nested": true }
+ });
+ let base = contact_from(&existing).expect("a person");
+ let mut mine = base.clone();
+ mine.first_name = Some("Augusta Ada".into());
+ for written in [card_merged(&mine, Some(&existing), Some(&base)), {
+ let card = parse_cards(&json!({ "contacts": [existing.clone()] }))
+ .pop()
+ .unwrap();
+ card_written(
+ &mine,
+ Some(&card.details),
+ Some(&existing),
+ Some(&base),
+ Some(&card.details),
+ )
+ }] {
+ let (Some(written), Some(was)) = (written.as_object(), existing.as_object()) else {
+ panic!("a card is an object");
+ };
+ for (key, value) in was {
+ if key == "firstName" {
+ continue;
+ }
+ assert_eq!(
+ written.get(key),
+ Some(value),
+ "{key} changed or went missing"
+ );
+ }
+ assert_eq!(written["firstName"], "Augusta Ada");
+ assert_eq!(written.len(), was.len(), "nothing added: {written:?}");
+ }
+ }
+
fn person() -> Contact {
Contact {
guid: "C1".into(),
diff --git a/crates/quince-icloud/src/notes.rs b/crates/quince-icloud/src/notes.rs
index 453765b..aa3ffe4 100644
--- a/crates/quince-icloud/src/notes.rs
+++ b/crates/quince-icloud/src/notes.rs
@@ -1900,6 +1900,224 @@ mod tests {
assert_eq!(rewritable(&written), "ok");
}
+ /// A note as a phone keeps one, with everything Notes can hold: a drawing, a scanned
+ /// document, a picture, a PDF, a contact card, an audio recording, a table, a #tag and an
+ /// @mention, a link, a checklist ticked and not, a title and a heading — and in every run
+ /// a field this app does not know (a collapsed section, or whatever a newer phone adds),
+ /// in a document with its merge records. One word typed here: that run alone changes, and
+ /// only in its length; every other run, every attachment's reference and every unknown
+ /// field goes back byte for byte; the merge records still describe the text; and the
+ /// attachments stay sound for the phone.
+ #[test]
+ fn a_one_word_edit_keeps_everything_else_byte_for_byte() {
+ let text = "Trip\nPacking\nTickets booked\nPassport\nSee the guide\n";
+ let units = |s: &str| s.encode_utf16().count() as u64;
+ let mut doc =
+ crate::ckdocument::add_merge_records_for_test(&crate::ckdocument::text_to_base64(text));
+ let styled = vec![
+ Run {
+ length: units("Trip\n"),
+ style: Some(0),
+ ..Run::default()
+ },
+ Run {
+ length: units("Packing\n"),
+ style: Some(1),
+ ..Run::default()
+ },
+ Run {
+ length: units("Tickets booked\n"),
+ style: Some(103),
+ checked: Some(true),
+ ..Run::default()
+ },
+ Run {
+ length: units("Passport\n"),
+ style: Some(103),
+ checked: Some(false),
+ ..Run::default()
+ },
+ plain(units("See the ")),
+ Run {
+ length: units("guide"),
+ link: Some("https://example.com/guide".into()),
+ ..Run::default()
+ },
+ plain(units("\n")),
+ ];
+ doc = crate::ckdocument::replace_rich_in_base64(&doc, text, &styled).expect("styled");
+ // Every kind of attachment, each on a line of its own, as a phone places them.
+ for (i, uti) in [
+ "com.apple.paper",
+ "com.apple.notes.gallery",
+ "public.jpeg",
+ "com.adobe.pdf",
+ "public.vcard",
+ "com.apple.m4a-audio",
+ "com.apple.notes.table",
+ "com.apple.notes.inlinetextattachment.hashtag",
+ "com.apple.notes.inlinetextattachment.mention",
+ ]
+ .into_iter()
+ .enumerate()
+ {
+ let shown = crate::ckdocument::stored_text_from_base64(&doc).unwrap();
+ let at = units(&shown);
+ doc = crate::ckdocument::insert_attachment_in_base64(
+ &doc,
+ at,
+ &format!("00000000-0000-4000-8000-00000000001{i}"),
+ uti,
+ 100 + i as u64,
+ )
+ .expect("placed")
+ .0;
+ }
+ // A field this app does not model in every run (field 30, a varint), as a newer phone
+ // may write one.
+ let raw = |d: &str| {
+ use base64::Engine;
+ crate::ckdocument::debug_attribute_runs(
+ &base64::engine::general_purpose::STANDARD.decode(d).unwrap(),
+ )
+ };
+ let unknown = [0xF0_u8, 0x01, 0x07];
+ let marked: Vec<Vec<u8>> = raw(&doc)
+ .into_iter()
+ .map(|mut r| {
+ r.extend_from_slice(&unknown);
+ r
+ })
+ .collect();
+ let doc = crate::ckdocument::with_raw_runs_for_test(&doc, &marked);
+ assert_eq!(rewritable(&doc), "ok", "a sound document to begin with");
+
+ // One word typed, through the save the window makes.
+ let theirs = crate::ckdocument::stored_text_from_base64(&doc).unwrap();
+ let apple = crate::ckdocument::runs_from_base64(&doc);
+ let editor = canonical_runs(&theirs, &apple).unwrap();
+ let at = theirs.find("booked").unwrap();
+ let typed = format!("{}all {}", &theirs[..at], &theirs[at..]);
+ let mine = crate::ckdocument::carry_runs(&theirs, &editor, &typed);
+ let (kept, written) = rewrite_for_save(
+ &doc,
+ &theirs,
+ Some(&theirs),
+ &typed,
+ Some(&mine),
+ Some(&apple),
+ )
+ .unwrap()
+ .expect("an edit is written");
+ assert_eq!(kept, typed);
+
+ let (before, after) = (raw(&doc), raw(&written));
+ assert_eq!(before.len(), after.len(), "no run re-cut, added or lost");
+ let changed: Vec<usize> = (0..before.len())
+ .filter(|&i| before[i] != after[i])
+ .collect();
+ assert_eq!(changed.len(), 1, "only the run typed into: {changed:?}");
+ let i = changed[0];
+ assert_eq!(
+ crate::ckdocument::debug_run_length(&after[i]),
+ crate::ckdocument::debug_run_length(&before[i]) + units("all ")
+ );
+ assert!(
+ after.iter().all(|r| r.ends_with(&unknown)),
+ "every unknown field kept"
+ );
+ // Every attachment where it was, by the same reference.
+ let ids = |d: &str| -> Vec<String> {
+ crate::ckdocument::runs_from_base64(d)
+ .into_iter()
+ .filter_map(|r| r.attachment)
+ .collect()
+ };
+ assert_eq!(ids(&written), ids(&doc));
+ assert_eq!(ids(&doc).len(), 9);
+ assert!(crate::ckdocument::attachments_sound_in_base64(
+ &doc, &written
+ ));
+ assert_eq!(
+ rewritable(&written),
+ "ok",
+ "merge records still describe the text"
+ );
+ // Read back: the same note, one word longer, set as it was.
+ let read = crate::ckdocument::runs_from_base64(&written);
+ assert!(same_formatting(&typed, &read, &mine));
+
+ // A tick here (the other write a note takes): the passport line ticked, every unknown
+ // field and attachment still there.
+ let line = typed.find("Passport").unwrap();
+ let start = typed[..line].encode_utf16().count() as u64;
+ let ticked = crate::ckdocument::set_paragraph_in_base64(
+ &written,
+ start,
+ crate::ckdocument::ParagraphChange::Checked(true),
+ Some("Passport"),
+ )
+ .expect("ticked");
+ assert!(
+ raw(&ticked).iter().all(|r| r.ends_with(&unknown)),
+ "unknown fields kept by a tick"
+ );
+ assert_eq!(ids(&ticked), ids(&doc));
+ assert!(crate::ckdocument::attachments_sound_in_base64(
+ &written, &ticked
+ ));
+ assert_eq!(rewritable(&ticked), "ok");
+
+ // A restyle from the editor (the heading made body text): the runs are written from
+ // the editor's, and every one still carries what this app does not know.
+ let shown = crate::ckdocument::stored_text_from_base64(&ticked).unwrap();
+ let theirs_runs = crate::ckdocument::runs_from_base64(&ticked);
+ let mut restyled = canonical_runs(&shown, &theirs_runs).unwrap();
+ for r in &mut restyled {
+ if r.style == Some(1) {
+ r.style = None;
+ }
+ }
+ let (_, rewritten) = rewrite_for_save(
+ &ticked,
+ &shown,
+ Some(&shown),
+ &shown,
+ Some(&restyled),
+ Some(&theirs_runs),
+ )
+ .unwrap()
+ .expect("a restyle is written");
+ let holds = |r: &Vec<u8>| r.windows(unknown.len()).any(|w| w == unknown);
+ assert!(
+ raw(&rewritten).iter().all(holds),
+ "unknown fields kept by a restyle"
+ );
+ assert_eq!(ids(&rewritten), ids(&doc));
+ assert!(crate::ckdocument::attachments_sound_in_base64(
+ &ticked, &rewritten
+ ));
+ assert_eq!(rewritable(&rewritten), "ok");
+ }
+
+ /// A locked note is never offered for editing: its text is sealed, and nothing here
+ /// could write it back as the phone keeps it.
+ #[test]
+ fn a_locked_note_is_never_editable() {
+ let sealed = json!({
+ "recordName": "L", "recordType": "Note",
+ "fields": {
+ "TitleEncrypted": { "type": "ENCRYPTED_BYTES", "value": bare("Bank") },
+ "TextDataEncrypted": { "type": "ENCRYPTED_BYTES", "value": "AAECAwQFBgcICQ==" },
+ "CryptoInitializationVector": { "type": "BYTES", "value": "AAAAAAAAAAAAAAAA" },
+ "CryptoTag": { "type": "BYTES", "value": "AAAAAAAAAAAAAAAAAAAAAA==" },
+ }
+ });
+ let note = note_from_record(&sealed).unwrap();
+ assert!(!note.editable);
+ assert!(note.body.is_none());
+ }
+
/// A restyle is written — and the lines it did not touch still read as Apple set them.
#[test]
fn a_restyle_is_written() {
diff --git a/crates/quince-icloud/src/reminders.rs b/crates/quince-icloud/src/reminders.rs
index cd3b7b3..689f507 100644
--- a/crates/quince-icloud/src/reminders.rs
+++ b/crates/quince-icloud/src/reminders.rs
@@ -2993,6 +2993,108 @@ mod edit_tests {
.count()
}
+ /// A reminder an iPhone made with everything on it: a location alarm and an early one, a
+ /// picture, a link, subtasks, a section, a flag, a repeat, hashtags, and the token map its
+ /// devices merge by. Its title edited here sends the title alone (CloudKit's `update`
+ /// changes only the fields named): no other field is sent, the title's merge records are
+ /// rewritten in place, and every other field's merge token goes back as it was.
+ #[tokio::test]
+ async fn a_title_edit_sends_the_title_alone() {
+ let tokens = json!({ "map": {
+ "titleDocument": { "counter": 3, "modificationTime": 7.5e8, "replicaID": "PHONE" },
+ "alarmIDs": { "counter": 2, "modificationTime": 7.4e8, "replicaID": "PHONE" },
+ "flagged": { "counter": 1, "modificationTime": 7.3e8, "replicaID": "MAC" },
+ } })
+ .to_string();
+ let title = crate::ckdocument::add_merge_records_for_test(
+ &crate::ckdocument::text_to_base64("Pick up the frame"),
+ );
+ let record = json!({
+ "recordName": "Reminder/1", "recordType": "Reminder", "recordChangeTag": "fresh",
+ "fields": {
+ "TitleDocument": { "type": "ENCRYPTED_BYTES", "value": title },
+ "NotesDocument": { "type": "ENCRYPTED_BYTES", "value": crate::ckdocument::text_to_base64("At the shop on Main St") },
+ "AlarmIDs": { "type": "STRING_LIST", "value": ["Alarm/LOC-1", "Alarm/EARLY-2"] },
+ "AttachmentIDs": { "type": "STRING_LIST", "value": ["Attachment/IMG-1", "Attachment/URL-1"] },
+ "HashtagIDs": { "type": "STRING_LIST", "value": ["Hashtag/errands"] },
+ "RecurrenceRuleIDs": { "type": "STRING_LIST", "value": ["RecurrenceRule/W1"] },
+ "ParentReminder": { "type": "REFERENCE", "value": { "recordName": "Reminder/0", "action": "VALIDATE" } },
+ "List": { "type": "REFERENCE", "value": { "recordName": "List/a", "action": "VALIDATE" } },
+ "Flagged": { "type": "NUMBER_INT64", "value": 1 },
+ "Priority": { "type": "NUMBER_INT64", "value": 5 },
+ "DueDate": { "type": "TIMESTAMP", "value": 1_789_000_000_000_i64 },
+ "ResolutionTokenMap": { "type": "STRING", "value": tokens },
+ }
+ });
+ 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": [record.clone()] })),
+ )
+ .mount(&server)
+ .await;
+ Mock::given(method("POST"))
+ .and(path_regex(r".*/records/modify$"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_json(json!({ "records": [{ "recordName": "Reminder/1" }] })),
+ )
+ .mount(&server)
+ .await;
+ edit_cloudkit(
+ &reqwest::Client::new(),
+ &server.uri(),
+ vec![],
+ &reminder(),
+ &ReminderEdit {
+ title: Some("Pick up the big frame".into()),
+ ..Default::default()
+ },
+ )
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ let modify = requests
+ .iter()
+ .find(|r| r.url.path().ends_with("/records/modify"))
+ .unwrap();
+ let body: Value = serde_json::from_slice(&modify.body).unwrap();
+ assert_eq!(
+ body["operations"][0]["operationType"], "update",
+ "field by field"
+ );
+ let fields = body["operations"][0]["record"]["fields"]
+ .as_object()
+ .unwrap();
+ let mut sent: Vec<&str> = fields.keys().map(String::as_str).collect();
+ sent.sort_unstable();
+ assert_eq!(
+ sent,
+ ["LastModifiedDate", "ResolutionTokenMap", "TitleDocument"]
+ );
+ // The title's document rewritten in place: its merge records still describe it.
+ let written = fields["TitleDocument"]["value"].as_str().unwrap();
+ assert_eq!(
+ crate::ckdocument::stored_text_from_base64(written).as_deref(),
+ Some("Pick up the big frame")
+ );
+ let raw =
+ base64::Engine::decode(&base64::engine::general_purpose::STANDARD, written).unwrap();
+ assert_eq!(crate::ckdocument::debug_rewritable(&raw), "ok");
+ // Every other field's merge token as Apple had it.
+ let map: Value =
+ serde_json::from_str(fields["ResolutionTokenMap"]["value"].as_str().unwrap()).unwrap();
+ let was: Value = serde_json::from_str(&tokens).unwrap();
+ assert_eq!(map["map"]["alarmIDs"], was["map"]["alarmIDs"]);
+ assert_eq!(map["map"]["flagged"], was["map"]["flagged"]);
+ assert_eq!(
+ map["map"]["titleDocument"]["counter"], 4,
+ "the title's raised"
+ );
+ }
+
#[tokio::test]
async fn a_new_title_is_written_so_it_reads_back() {
let server = accepting().await;