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.

A note written here is shaped like one Apple wrote, so a phone will show it

Yashwanth Kamireddi65b16de0cb8c
diff --git a/crates/quince-core/src/lib.rs b/crates/quince-core/src/lib.rs
index d9ba00a..ba3b101 100644
--- a/crates/quince-core/src/lib.rs
+++ b/crates/quince-core/src/lib.rs
@@ -85,6 +85,30 @@ impl Library {
}
}
+impl Library {
+ /// Remember something learned from the account, by name.
+ pub fn set_state(&mut self, key: &str, value: &str) -> Result<()> {
+ self.conn.execute(
+ "INSERT INTO app_state (key, value) VALUES (?1, ?2)
+ ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+ rusqlite::params![key, value],
+ )?;
+ Ok(())
+ }
+
+ /// What was remembered under that name, if anything.
+ pub fn state(&self, key: &str) -> Result<Option<String>> {
+ let mut stmt = self
+ .conn
+ .prepare("SELECT value FROM app_state WHERE key = ?1")?;
+ let mut rows = stmt.query(rusqlite::params![key])?;
+ match rows.next()? {
+ Some(row) => Ok(Some(row.get(0)?)),
+ None => Ok(None),
+ }
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
diff --git a/crates/quince-core/src/schema.rs b/crates/quince-core/src/schema.rs
index c919f7c..c37ee98 100644
--- a/crates/quince-core/src/schema.rs
+++ b/crates/quince-core/src/schema.rs
@@ -265,4 +265,17 @@ pub const MIGRATIONS: &[&str] = &[
r#"
ALTER TABLE reminders ADD COLUMN timezone TEXT;
"#,
+ // 18 — somewhere to keep a thing learned from the account.
+ //
+ // The first of these is a note document Apple wrote, kept so a new note can be given the
+ // same shape. It cannot be fetched on demand: notes sit far enough into the zone walk that
+ // the first page of a hundred and thirty-nine records held none of them, and walking the
+ // whole zone to write one note is not a trade worth making. Sync already reads every note,
+ // so sync is where it is noticed.
+ r#"
+ CREATE TABLE app_state (
+ key TEXT PRIMARY KEY,
+ value TEXT NOT NULL
+ );
+ "#,
];
diff --git a/crates/quince-icloud/src/ckdocument.rs b/crates/quince-icloud/src/ckdocument.rs
index 68ae016..c376402 100644
--- a/crates/quince-icloud/src/ckdocument.rs
+++ b/crates/quince-icloud/src/ckdocument.rs
@@ -657,6 +657,56 @@ pub fn repair_runs_in_base64(original: &str) -> Option<String> {
Some(B64.encode(gzip(&repair_runs(&raw)?)))
}
+/// Give a document the merge records Apple's notes carry, for tests that need one to copy.
+#[doc(hidden)]
+#[must_use]
+pub fn add_merge_records_for_test(original: &str) -> 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 mut with = note.to_vec();
+ with.extend(length_delimited(3, &varint_field(5, 1)));
+ with.extend(length_delimited(4, &varint_field(1, 1)));
+ let rebuilt = rewrite(&plain, &TEXT_PATH[..2], &with).unwrap_or(plain);
+ B64.encode(gzip(&rebuilt))
+}
+
+/// Whether a document carries the merge records Apple's own reader needs.
+///
+/// Inside the note message Apple keeps records saying which writer produced which stretch of
+/// text — fields 3 and 4. A document without them reads back here perfectly and shows on a
+/// phone as an empty note, so this is what tells a document worth copying from one that is
+/// not.
+#[must_use]
+pub fn has_merge_records(original: &str) -> bool {
+ let Ok(raw) = B64.decode(original.trim()) else {
+ return false;
+ };
+ let Some(plain) = inflate(&raw) else {
+ return false;
+ };
+ let Some(note) = field_at(&plain, &TEXT_PATH[..2]) else {
+ return false;
+ };
+
+ let mut reader = Reader::new(note);
+ let mut provenance = false;
+ let mut writer = false;
+ while !reader.done() {
+ let Some(key) = reader.varint() else { break };
+ match key >> 3 {
+ 3 => provenance = true,
+ 4 => writer = true,
+ _ => {}
+ }
+ if reader.skip(key & 7).is_none() {
+ break;
+ }
+ }
+ provenance && writer
+}
+
/// Whether [`replace_text`] would accept this document, without building the result.
///
/// Answers "can this note be edited?" at sync time, so the interface can say so before
@@ -1535,3 +1585,89 @@ mod version_tests {
assert_eq!(out, store, "nothing was missing, so nothing changed");
}
}
+
+/// Telling a document Apple's reader will show from one it will not.
+#[cfg(test)]
+mod merge_record_tests {
+ use super::*;
+
+ /// What this app builds from nothing: text, a run, the versions. It reads back here
+ /// perfectly and a phone shows it as an empty note.
+ #[test]
+ fn a_document_built_from_nothing_has_no_merge_records() {
+ let built = text_to_base64("Buy milk");
+ assert_eq!(text_from_base64(&built).as_deref(), Some("Buy milk"));
+ assert!(
+ !has_merge_records(&built),
+ "which is exactly why a phone showed nothing"
+ );
+ }
+
+ /// The shape Apple writes: records saying which writer produced which stretch of text.
+ #[test]
+ fn a_document_shaped_like_apples_is_recognised() {
+ let mut note = length_delimited(TEXT_PATH[2], b"Buy milk");
+ // One provenance record and one writer, which is the least Apple ever writes.
+ note.extend(length_delimited(3, &varint_field(5, 1)));
+ note.extend(length_delimited(4, &varint_field(1, 1)));
+ note.extend(length_delimited(ATTRIBUTE_RUN, &varint_field(1, 8)));
+
+ let mut document = varint_field(1, 0);
+ document.extend(varint_field(2, 0));
+ document.extend(length_delimited(TEXT_PATH[1], &note));
+ let mut store = varint_field(1, 0);
+ store.extend(length_delimited(TEXT_PATH[0], &document));
+
+ assert!(has_merge_records(&B64.encode(gzip(&store))));
+ }
+
+ /// Both halves are needed — provenance without a writer is not the shape.
+ #[test]
+ fn half_the_shape_is_not_the_shape() {
+ for tag in [3, 4] {
+ let mut note = length_delimited(TEXT_PATH[2], b"Buy milk");
+ note.extend(length_delimited(tag, &varint_field(5, 1)));
+ note.extend(length_delimited(ATTRIBUTE_RUN, &varint_field(1, 8)));
+ let mut document = varint_field(1, 0);
+ document.extend(varint_field(2, 0));
+ document.extend(length_delimited(TEXT_PATH[1], &note));
+ let mut store = varint_field(1, 0);
+ store.extend(length_delimited(TEXT_PATH[0], &document));
+ assert!(
+ !has_merge_records(&B64.encode(gzip(&store))),
+ "field {tag} alone"
+ );
+ }
+ }
+
+ /// Nonsense is not a document worth copying from.
+ #[test]
+ fn rubbish_is_not_mistaken_for_a_document() {
+ assert!(!has_merge_records("not base64 at all !!"));
+ assert!(!has_merge_records(""));
+ assert!(!has_merge_records(&B64.encode(b"hello")));
+ }
+
+ /// The whole point: swapping the text of a document that has them keeps them, which is
+ /// what makes a note written here one a phone will show.
+ #[test]
+ fn swapping_the_text_keeps_what_makes_it_readable() {
+ let mut note = length_delimited(TEXT_PATH[2], b"Old words");
+ note.extend(length_delimited(3, &varint_field(5, 1)));
+ note.extend(length_delimited(4, &varint_field(1, 1)));
+ note.extend(length_delimited(ATTRIBUTE_RUN, &varint_field(1, 9)));
+ let mut document = varint_field(1, 0);
+ document.extend(varint_field(2, 0));
+ document.extend(length_delimited(TEXT_PATH[1], &note));
+ let mut store = varint_field(1, 0);
+ store.extend(length_delimited(TEXT_PATH[0], &document));
+ let apples = B64.encode(gzip(&store));
+
+ let swapped = replace_text_in_base64(&apples, "Entirely new words").unwrap();
+ assert_eq!(
+ text_from_base64(&swapped).as_deref(),
+ Some("Entirely new words")
+ );
+ assert!(has_merge_records(&swapped));
+ }
+}
diff --git a/crates/quince-icloud/src/notes.rs b/crates/quince-icloud/src/notes.rs
index 91090f5..e4205d4 100644
--- a/crates/quince-icloud/src/notes.rs
+++ b/crates/quince-icloud/src/notes.rs
@@ -122,6 +122,9 @@ pub async fn fetch_cloudkit(
}
/// Store a fetched pass. Touches no network.
+/// Where the document a new note is shaped from is kept.
+pub const TEMPLATE_KEY: &str = "notes.document_template";
+
pub fn apply_cloudkit(
library: &mut quince_core::Library,
fetched: NotesFetch,
@@ -133,6 +136,7 @@ pub fn apply_cloudkit(
} = fetched;
let mut folders: Vec<NoteFolder> = Vec::new();
+ let mut template: Option<String> = None;
let mut notes: Vec<Note> = Vec::new();
let mut gone: Vec<String> = Vec::new();
// Deletion and pinning live on the per-user record, keyed by a reference to the note.
@@ -168,6 +172,18 @@ pub fn apply_cloudkit(
if removed {
gone.push(name);
} else {
+ // A document Apple wrote is worth keeping the shape of. A note created
+ // here is built from it, because one built from nothing shows on a phone
+ // as an empty note. Noticed during sync rather than fetched on demand:
+ // notes sit far enough into the zone walk that the first page of a hundred
+ // and thirty-nine records held none of them.
+ if template.is_none() {
+ template = record
+ .pointer("/fields/TextDataEncrypted/value")
+ .and_then(Value::as_str)
+ .filter(|d| crate::ckdocument::has_merge_records(d))
+ .map(ToString::to_string);
+ }
notes.extend(note_from_record(record));
}
}
@@ -225,6 +241,9 @@ pub fn apply_cloudkit(
let keep: Vec<String> = notes.iter().map(|n| n.guid.clone()).collect();
library.retain_notes(&keep)?;
}
+ if let Some(document) = template {
+ library.set_state(TEMPLATE_KEY, &document)?;
+ }
library.mark_synced("notes", token.as_deref())?;
Ok((folders.len(), notes.len(), token))
}
@@ -321,6 +340,7 @@ pub async fn create_cloudkit(
params: Vec<(String, String)>,
folder_guid: Option<&str>,
body: &str,
+ template: Option<&str>,
) -> Result<String> {
if body.trim().is_empty() {
return Err(Error::Protocol("a note needs something in it".into()));
@@ -340,10 +360,13 @@ pub async fn create_cloudkit(
let stamp = now_millis();
let (title, snippet) = title_and_snippet(body);
+ // A document Apple's own reader will show. See `document_like_apples`.
+ let document = document_like_apples(template, body);
+
let mut fields = serde_json::json!({
"TextDataEncrypted": {
"type": "ENCRYPTED_BYTES",
- "value": crate::ckdocument::text_to_base64(body),
+ "value": document,
},
"TitleEncrypted": {
"type": "ENCRYPTED_BYTES",
@@ -374,10 +397,42 @@ pub async fn create_cloudkit(
Ok(record_name)
}
-// Tried and rejected: copying `ReplicaIDToUserIDEncrypted` and
-// `ReplicaIDToNotesVersionDataEncrypted` from an existing note. They are identical on every
-// note on an account, so they looked like a registry worth stamping onto a new one — but Apple
-// drops them silently on a write. They are the server's to keep, not a client's to set.
+/// A note's text in a document Apple's own reader will show.
+///
+/// A document built from nothing — text, one attribute run, the version fields — is read back
+/// here perfectly and shows on a phone as an empty note. Laying one beside a note Apple wrote
+/// says why: inside the note message Apple keeps a handful of merge records, and ours had none.
+///
+/// ```text
+/// Apple's note [ text, 3,3,3,3,3,3,3, 4, 5 ]
+/// ours note [ text, 5 ]
+/// ```
+///
+/// Those records say which writer produced which stretch of text, and field 4 names the writer
+/// with a UUID. Synthesising a plausible-looking set was tried and the phone still showed
+/// nothing; what works is taking a document Apple already wrote and swapping only the text —
+/// the same operation an edit performs, which has always worked.
+///
+/// Copying them is not the sleight of hand it first looks like. Field 4 identifies the writer,
+/// and a phone stamps every note it makes with the same one, so notes sharing a writer is the
+/// normal case rather than a collision. Each note's records are its own and reference nothing
+/// outside it.
+///
+/// An account with no note to learn from — a new one — gets a document built from scratch.
+/// That is the shape that does not render, and there is nothing better to be had until the
+/// account has one note on it; the alternative is refusing to create a note at all.
+///
+/// Tried and rejected along the way: copying `ReplicaIDToUserIDEncrypted` and
+/// `ReplicaIDToNotesVersionDataEncrypted`, which are identical on every note on an account and
+/// so looked like a registry worth stamping onto a new one. Apple drops them silently on a
+/// write. They are the server's to keep, not a client's to set — and notes that lack them
+/// render perfectly, so they were never the reason.
+fn document_like_apples(template: Option<&str>, body: &str) -> String {
+ template
+ .filter(|document| crate::ckdocument::has_merge_records(document))
+ .and_then(|document| crate::ckdocument::replace_text_in_base64(document, body))
+ .unwrap_or_else(|| crate::ckdocument::text_to_base64(body))
+}
/// Move a note into a folder, or out of every folder.
pub async fn move_cloudkit(
@@ -816,6 +871,7 @@ mod write_tests {
vec![],
None,
" \n ",
+ None,
)
.await;
assert!(outcome.is_err());
@@ -834,6 +890,7 @@ mod write_tests {
vec![],
Some("Folder/a"),
"Packing\npassport",
+ None,
)
.await
.unwrap();
@@ -973,3 +1030,67 @@ mod folder_shape_tests {
assert_eq!(orphan.parent_guid.as_deref(), Some("GONE"));
}
}
+
+/// Shaping a new note like one Apple wrote.
+#[cfg(test)]
+mod template_tests {
+ use super::*;
+
+ /// A document with the merge records a phone needs, to stand in for one Apple wrote.
+ fn apples_shape(text: &str) -> String {
+ let built = crate::ckdocument::text_to_base64(text);
+ // Built documents have no merge records, so this checks the fixture is honest about
+ // what it is rather than quietly testing nothing.
+ assert!(!crate::ckdocument::has_merge_records(&built));
+ crate::ckdocument::add_merge_records_for_test(&built)
+ }
+
+ #[test]
+ fn a_new_note_takes_the_shape_of_one_apple_wrote() {
+ let template = apples_shape("Something Apple wrote");
+ let made = document_like_apples(Some(&template), "Something written here");
+ assert_eq!(
+ crate::ckdocument::text_from_base64(&made).as_deref(),
+ Some("Something written here")
+ );
+ assert!(
+ crate::ckdocument::has_merge_records(&made),
+ "which is what makes a phone show it"
+ );
+ }
+
+ /// A new account has no note to learn from. Building from nothing is the only option, and
+ /// refusing to create a note at all would be worse.
+ #[test]
+ fn with_nothing_to_learn_from_it_still_makes_a_note() {
+ let made = document_like_apples(None, "The first note on this account");
+ assert_eq!(
+ crate::ckdocument::text_from_base64(&made).as_deref(),
+ Some("The first note on this account")
+ );
+ }
+
+ /// A template that is itself the shape that does not render is no use as a template.
+ #[test]
+ fn a_template_without_the_records_is_not_used_as_one() {
+ let useless = crate::ckdocument::text_to_base64("no merge records here");
+ let made = document_like_apples(Some(&useless), "New text");
+ assert_eq!(
+ crate::ckdocument::text_from_base64(&made).as_deref(),
+ Some("New text"),
+ "the note is still made"
+ );
+ }
+
+ /// Rubbish stored as a template must not take a note down with it.
+ #[test]
+ fn rubbish_stored_as_a_template_is_ignored() {
+ for bad in ["", "not base64 !!", "aGVsbG8="] {
+ let made = document_like_apples(Some(bad), "Still fine");
+ assert_eq!(
+ crate::ckdocument::text_from_base64(&made).as_deref(),
+ Some("Still fine")
+ );
+ }
+ }
+}
diff --git a/probe/src/main.rs b/probe/src/main.rs
index a16fd83..98c4c0b 100644
--- a/probe/src/main.rs
+++ b/probe/src/main.rs
@@ -1183,8 +1183,15 @@ async fn main() -> Result<()> {
);
let body = "Quince write test\nsafe to delete";
- match quince_icloud::notes::create_cloudkit(&http, &ck, params.clone(), None, body)
- .await
+ match quince_icloud::notes::create_cloudkit(
+ &http,
+ &ck,
+ params.clone(),
+ None,
+ body,
+ None,
+ )
+ .await
{
Err(e) => println!(" \x1b[31mFAIL\x1b[0m create: {e}"),
Ok(guid) => {
diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs
index 0f73372..590fcca 100644
--- a/src-tauri/src/main.rs
+++ b/src-tauri/src/main.rs
@@ -736,12 +736,21 @@ async fn note_create(
data: State<'_, Data>,
) -> UiResult<String> {
let (http, root, params) = cloudkit_context(&auth).await?;
+ // The shape of a document Apple wrote, noticed during a sync. A note built without it
+ // reads back here perfectly and shows on a phone as an empty note.
+ let template = {
+ let library = data.0.lock().await;
+ library
+ .state(quince_icloud::notes::TEMPLATE_KEY)
+ .map_err(|e| e.to_string())?
+ };
let guid = quince_icloud::notes::create_cloudkit(
&http,
&root,
params.clone(),
folder_guid.as_deref(),
&body,
+ template.as_deref(),
)
.await
.map_err(|e| e.to_string())?;