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.

Contacts show the pictures they have, cropped where their owner chose

Yashwanth Kamireddi5f6d413698f4
diff --git a/Cargo.lock b/Cargo.lock
index e6fddc1..a1b5b1c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -380,6 +380,12 @@ version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
[[package]]
name = "bytes"
version = "1.12.1"
@@ -2000,6 +2006,21 @@ dependencies = [
"icu_properties",
]
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png 0.18.1",
+ "zune-core",
+ "zune-jpeg",
+]
+
[[package]]
name = "indexmap"
version = "1.9.3"
@@ -2408,6 +2429,16 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
[[package]]
name = "muda"
version = "0.19.3"
@@ -3120,6 +3151,12 @@ dependencies = [
"psl-types",
]
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
[[package]]
name = "quick-xml"
version = "0.42.0"
@@ -3138,6 +3175,7 @@ dependencies = [
"quince-auth",
"quince-core",
"quince-icloud",
+ "quince-media",
"reqwest 0.12.28",
"serde",
"serde_json",
@@ -3200,6 +3238,13 @@ dependencies = [
"wiremock",
]
+[[package]]
+name = "quince-media"
+version = "0.1.0"
+dependencies = [
+ "image",
+]
+
[[package]]
name = "quince-probe"
version = "0.0.0"
@@ -3210,6 +3255,7 @@ dependencies = [
"quince-auth",
"quince-core",
"quince-icloud",
+ "quince-media",
"rpassword",
"serde_json",
"tokio",
@@ -5949,6 +5995,21 @@ version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
+
[[package]]
name = "zvariant"
version = "4.2.0"
diff --git a/Cargo.toml b/Cargo.toml
index 6290612..ba870be 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[workspace]
resolver = "2"
-members = ["probe", "crates/quince-auth", "crates/quince-core", "crates/quince-icloud", "src-tauri"]
+members = ["probe", "crates/quince-auth", "crates/quince-core", "crates/quince-icloud", "crates/quince-media", "src-tauri"]
[workspace.package]
edition = "2021"
@@ -14,3 +14,4 @@ serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
uuid = { version = "1", features = ["v4"] }
+quince-media = { path = "crates/quince-media" }
diff --git a/crates/quince-core/src/contacts.rs b/crates/quince-core/src/contacts.rs
index f7ce16b..8bf8f95 100644
--- a/crates/quince-core/src/contacts.rs
+++ b/crates/quince-core/src/contacts.rs
@@ -13,6 +13,17 @@ pub struct ContactMethod {
pub value: String,
}
+/// Everything needed to put one person's picture on screen.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ContactPhoto {
+ pub url: String,
+ /// Changes when the picture does, so a cached copy knows it has gone stale. Absent on a
+ /// picture shared by the person it belongs to, which is then never cached to disk.
+ pub signature: Option<String>,
+ /// `x,y,width,height` in the stored picture's own pixels.
+ pub crop: Option<String>,
+}
+
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct Contact {
@@ -21,6 +32,15 @@ pub struct Contact {
/// Apple keeps one, and four people in a real address book have one.
#[serde(default)]
pub middle_name: Option<String>,
+ /// Where Apple keeps this person's picture, and the signature that changes when the
+ /// picture does. `None` for the great majority of an address book.
+ #[serde(default)]
+ pub photo_url: Option<String>,
+ #[serde(default)]
+ pub photo_signature: Option<String>,
+ /// The square its owner chose, as `x,y,width,height` in the stored picture's own pixels.
+ #[serde(default)]
+ pub photo_crop: Option<String>,
pub last_name: Option<String>,
pub company: Option<String>,
pub is_company: bool,
@@ -87,11 +107,15 @@ impl Library {
{
let mut upsert = tx.prepare(
"INSERT INTO contacts (guid, first_name, middle_name, last_name, company, is_company,
- sort_name, birthday, notes, etag, updated_at)
- VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)
+ sort_name, birthday, notes, photo_url, photo_signature,
+ photo_crop, etag, updated_at)
+ VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)
ON CONFLICT(guid) DO UPDATE SET
first_name = excluded.first_name, middle_name = excluded.middle_name,
last_name = excluded.last_name,
+ photo_url = excluded.photo_url,
+ photo_signature = excluded.photo_signature,
+ photo_crop = excluded.photo_crop,
company = excluded.company, is_company = excluded.is_company,
sort_name = excluded.sort_name, birthday = excluded.birthday,
notes = excluded.notes, etag = excluded.etag,
@@ -115,6 +139,9 @@ impl Library {
c.sort_key(),
c.birthday,
c.notes,
+ c.photo_url,
+ c.photo_signature,
+ c.photo_crop,
c.etag,
stamp
])?;
@@ -147,6 +174,31 @@ impl Library {
Ok(())
}
+ /// Where one person's picture lives, without reading the rest of the address book.
+ ///
+ /// The picture is served per row as a list scrolls, so this stays a single-row lookup
+ /// rather than loading everyone and their phone numbers to answer it.
+ pub fn contact_photo_source(&self, guid: &str) -> Result<Option<ContactPhoto>> {
+ let mut stmt = self.conn.prepare(
+ "SELECT photo_url, photo_signature, photo_crop FROM contacts WHERE guid = ?1",
+ )?;
+ let mut rows = stmt.query(params![guid])?;
+ let Some(row) = rows.next()? else {
+ return Ok(None);
+ };
+ // The signature and the crop are each absent on real contacts — a picture shared by
+ // the person it belongs to arrives with neither. Only the URL decides whether there
+ // is anything to fetch.
+ let Some(url) = row.get::<_, Option<String>>(0)? else {
+ return Ok(None);
+ };
+ Ok(Some(ContactPhoto {
+ url,
+ signature: row.get(1)?,
+ crop: row.get(2)?,
+ }))
+ }
+
/// The address book in display order, optionally filtered.
///
/// The filter matches names and any stored method, so searching a phone number finds the
@@ -159,7 +211,7 @@ impl Library {
let mut stmt = self.conn.prepare(
"SELECT c.guid, c.first_name, c.middle_name, c.last_name, c.company, c.is_company,
- c.birthday, c.notes, c.etag
+ c.birthday, c.notes, c.photo_url, c.photo_signature, c.photo_crop, c.etag
FROM contacts c
WHERE ?1 IS NULL
OR lower(coalesce(c.first_name, '') || ' ' || coalesce(c.middle_name, '')
@@ -179,7 +231,10 @@ impl Library {
is_company: row.get::<_, i64>(5)? != 0,
birthday: row.get(6)?,
notes: row.get(7)?,
- etag: row.get(8)?,
+ photo_url: row.get(8)?,
+ photo_signature: row.get(9)?,
+ photo_crop: row.get(10)?,
+ etag: row.get(11)?,
methods: Vec::new(),
})
})?;
@@ -212,6 +267,9 @@ mod tests {
guid: guid.into(),
first_name: first.map(ToString::to_string),
middle_name: None,
+ photo_url: None,
+ photo_signature: None,
+ photo_crop: None,
last_name: last.map(ToString::to_string),
company: None,
is_company: false,
diff --git a/crates/quince-core/src/schema.rs b/crates/quince-core/src/schema.rs
index cd8bb1e..f47d5c4 100644
--- a/crates/quince-core/src/schema.rs
+++ b/crates/quince-core/src/schema.rs
@@ -213,4 +213,23 @@ pub const MIGRATIONS: &[&str] = &[
r#"
ALTER TABLE contacts ADD COLUMN middle_name TEXT;
"#,
+ // 13 — where a contact's photo lives.
+ //
+ // The URL is Apple's; the signature changes when the picture does, which is what tells
+ // a cached copy it has gone stale. The bytes themselves are not kept here: an image
+ // belongs on disk where the webview can load it directly, not in a row that has to
+ // cross an IPC boundary every time a list scrolls.
+ r#"
+ ALTER TABLE contacts ADD COLUMN photo_url TEXT;
+ ALTER TABLE contacts ADD COLUMN photo_signature TEXT;
+ "#,
+ // 14 — the square of a picture its owner chose to show.
+ //
+ // Apple stores the photo whole and records the crop beside it. One picture on a real
+ // account is 1696x2528 with a crop of 1279x1279 at 251,1249 — a portrait whose face sits
+ // near the bottom. Centring it, which is what any viewer does without this, shows a chest.
+ // Kept as `x,y,width,height` because it is only ever read and written together.
+ r#"
+ ALTER TABLE contacts ADD COLUMN photo_crop TEXT;
+ "#,
];
diff --git a/crates/quince-icloud/src/contacts.rs b/crates/quince-icloud/src/contacts.rs
index c6edaf0..cd9cfb9 100644
--- a/crates/quince-icloud/src/contacts.rs
+++ b/crates/quince-icloud/src/contacts.rs
@@ -117,6 +117,17 @@ fn contact_from(v: &Value) -> Option<Contact> {
guid,
first_name: string(v, "firstName"),
middle_name: string(v, "middleName"),
+ // Apple hands out a URL for the picture, a signature that changes with it, and the
+ // square its owner chose. Only the URL is always there.
+ photo_url: v
+ .pointer("/photo/url")
+ .and_then(Value::as_str)
+ .map(photo_url),
+ photo_signature: v
+ .pointer("/photo/signature")
+ .and_then(Value::as_str)
+ .map(ToString::to_string),
+ photo_crop: v.pointer("/photo/crop").and_then(crop),
last_name: string(v, "lastName"),
company: string(v, "companyName"),
is_company: v.get("isCompany").and_then(Value::as_bool).unwrap_or(false),
@@ -128,6 +139,29 @@ fn contact_from(v: &Value) -> Option<Contact> {
}
#[must_use]
+/// Apple's own address book service appends a vCard property to some picture URLs, leaving
+/// `.../card/<32 hex>X-SHARED-PHOTO-DISPLAY-PREF:ALWAYS_ASK`. That URL answers 404. Four of
+/// seventeen pictures on a real account arrive this way, so the leak is trimmed back to the
+/// card id — which does answer — rather than those people silently having no picture.
+fn photo_url(url: &str) -> String {
+ let Some((base, last)) = url.rsplit_once('/') else {
+ return url.to_string();
+ };
+ let id: String = last.chars().take_while(char::is_ascii_hexdigit).collect();
+ if id.len() == 32 && id.len() < last.len() {
+ format!("{base}/{id}")
+ } else {
+ url.to_string()
+ }
+}
+
+/// The chosen square, flattened to the `x,y,width,height` the library keeps.
+fn crop(value: &Value) -> Option<String> {
+ let at = |key: &str| value.get(key).and_then(Value::as_i64);
+ let (x, y, width, height) = (at("x")?, at("y")?, at("width")?, at("height")?);
+ (width > 0 && height > 0).then(|| format!("{x},{y},{width},{height}"))
+}
+
pub fn parse(body: &Value) -> Vec<Contact> {
body.get("contacts")
.and_then(Value::as_array)
@@ -501,6 +535,9 @@ mod write_tests {
guid: "C1".into(),
first_name: Some("Ada".into()),
middle_name: None,
+ photo_url: None,
+ photo_signature: None,
+ photo_crop: None,
last_name: Some("Lovelace".into()),
company: None,
is_company: false,
@@ -832,3 +869,72 @@ mod shape_tests {
assert!(contacts[0].methods.is_empty());
}
}
+
+#[cfg(test)]
+mod photo_tests {
+ use super::*;
+
+ /// Apple's own service sends these; four of seventeen pictures on a real account arrive
+ /// with a vCard property welded onto the card id, and that URL answers 404.
+ #[test]
+ fn a_url_apple_mangled_is_trimmed_back_to_the_card_it_names() {
+ let base = "https://gateway.icloud.com/contacts/1148/ck/card";
+ assert_eq!(
+ photo_url(&format!(
+ "{base}/095356b02d69e2fbebb51c11fee2459dX-SHARED-PHOTO-DISPLAY-PREF:ALWAYS_ASK"
+ )),
+ format!("{base}/095356b02d69e2fbebb51c11fee2459d")
+ );
+ assert_eq!(
+ photo_url(&format!(
+ "{base}/396d3dd0fc24ceeb66305190d44840edX-SHARED-PHOTO-DISPLAY-PREF:AUTOUPDATE"
+ )),
+ format!("{base}/396d3dd0fc24ceeb66305190d44840ed")
+ );
+ }
+
+ /// A URL that is already right must come back untouched, whatever shape it is.
+ #[test]
+ fn a_sound_url_is_left_exactly_as_it_came() {
+ for url in [
+ "https://gateway.icloud.com/contacts/1148/ck/card/5dcf9896c11839d3119214c8a000fe0f",
+ "https://example.invalid/ada.jpg",
+ "https://example.invalid/deadbeef",
+ "no-slash-at-all",
+ ] {
+ assert_eq!(photo_url(url), url, "{url}");
+ }
+ }
+
+ #[test]
+ fn a_crop_is_flattened_and_a_useless_one_is_dropped() {
+ let value = serde_json::json!({"x": 251, "y": 1249, "width": 1279, "height": 1279});
+ assert_eq!(crop(&value).as_deref(), Some("251,1249,1279,1279"));
+ assert_eq!(
+ crop(&serde_json::json!({"x": 0, "y": 0, "width": 0, "height": 9})),
+ None
+ );
+ assert_eq!(crop(&serde_json::json!({"x": 0, "y": 0})), None);
+ assert_eq!(crop(&Value::Null), None);
+ }
+
+ /// The picture fields come off a real payload, not an invented one.
+ #[test]
+ fn a_shared_picture_parses_with_a_usable_url_and_nothing_else() {
+ let body = serde_json::json!({"contacts": [{
+ "contactId": "abc",
+ "firstName": "Atta",
+ "photo": { "url":
+ "https://gateway.icloud.com/contacts/1148/ck/card/095356b02d69e2fbebb51c11fee2459dX-SHARED-PHOTO-DISPLAY-PREF:ALWAYS_ASK" }
+ }]});
+ let parsed = parse(&body);
+ assert_eq!(
+ parsed[0].photo_url.as_deref(),
+ Some(
+ "https://gateway.icloud.com/contacts/1148/ck/card/095356b02d69e2fbebb51c11fee2459d"
+ )
+ );
+ assert_eq!(parsed[0].photo_signature, None);
+ assert_eq!(parsed[0].photo_crop, None);
+ }
+}
diff --git a/crates/quince-media/Cargo.toml b/crates/quince-media/Cargo.toml
new file mode 100644
index 0000000..4803a44
--- /dev/null
+++ b/crates/quince-media/Cargo.toml
@@ -0,0 +1,10 @@
+[package]
+name = "quince-media"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+# Only the formats Apple has been observed to serve. Every extra decoder is compile time and
+# attack surface for no gain.
+image = { version = "0.25", default-features = false, features = ["png", "jpeg"] }
diff --git a/crates/quince-media/src/lib.rs b/crates/quince-media/src/lib.rs
new file mode 100644
index 0000000..9275581
--- /dev/null
+++ b/crates/quince-media/src/lib.rs
@@ -0,0 +1,230 @@
+//! Turning what Apple stores into what the interface draws.
+//!
+//! Apple keeps a contact's picture at full size and records, separately, the square its owner
+//! chose to show. Contacts on a phone draws that square; anything that ignores it shows the
+//! middle of the original instead — which for a portrait photo is a chest, not a face. So the
+//! square is cut here, in Rust, and the interface is handed a small image that is already
+//! right.
+
+/// The square of a picture its owner chose to show, in the stored image's own pixels.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Crop {
+ pub x: i64,
+ pub y: i64,
+ pub width: i64,
+ pub height: i64,
+}
+
+impl Crop {
+ /// Reads the compact form kept in the library: `x,y,width,height`.
+ #[must_use]
+ pub fn parse(text: &str) -> Option<Self> {
+ let mut parts = text.split(',').map(|p| p.trim().parse::<i64>().ok());
+ let (x, y, width, height) = (
+ parts.next()??,
+ parts.next()??,
+ parts.next()??,
+ parts.next()??,
+ );
+ if parts.next().is_some() || width <= 0 || height <= 0 {
+ return None;
+ }
+ Some(Self {
+ x,
+ y,
+ width,
+ height,
+ })
+ }
+
+ #[must_use]
+ pub fn to_text(self) -> String {
+ format!("{},{},{},{}", self.x, self.y, self.width, self.height)
+ }
+}
+
+/// A picture cut to its chosen square and sized for display.
+///
+/// `size` is the edge of the result. Serving 256 rather than the stored 1696×2528 is most of
+/// why a list of faces scrolls: the webview decodes a few kilobytes per row instead of a few
+/// hundred.
+///
+/// # Errors
+/// When the bytes are not an image this can decode.
+pub fn avatar(bytes: &[u8], crop: Option<Crop>, size: u32) -> Result<Vec<u8>, image::ImageError> {
+ let image = image::load_from_memory(bytes)?;
+ let square = cut(image, crop);
+ // Lanczos: these are faces, and a cheaper filter shows on skin.
+ let scaled = square.resize_to_fill(size, size, image::imageops::FilterType::Lanczos3);
+ encode(&scaled)
+}
+
+/// Cuts out the chosen square, ignoring a rectangle that does not fit the picture it came with.
+///
+/// A crop is only trusted where it actually lands inside the image. Apple's own API has been
+/// seen to send fields that do not match what it serves, and a bad rectangle should cost a
+/// centred picture, never a panic or a blank one.
+fn cut(image: image::DynamicImage, crop: Option<Crop>) -> image::DynamicImage {
+ use image::GenericImageView;
+ let (w, h) = image.dimensions();
+ let Some(c) = crop else { return image };
+ let (Ok(x), Ok(y), Ok(cw), Ok(ch)) = (
+ u32::try_from(c.x),
+ u32::try_from(c.y),
+ u32::try_from(c.width),
+ u32::try_from(c.height),
+ ) else {
+ return image;
+ };
+ if cw == 0 || ch == 0 || x.saturating_add(cw) > w || y.saturating_add(ch) > h {
+ return image;
+ }
+ image.crop_imm(x, y, cw, ch)
+}
+
+/// PNG where the picture needs transparency, JPEG where it does not.
+///
+/// A photograph re-encoded as PNG is several times the size for no visible gain, and these are
+/// read back on every scroll.
+fn encode(image: &image::DynamicImage) -> Result<Vec<u8>, image::ImageError> {
+ let mut out = std::io::Cursor::new(Vec::new());
+ if transparent(image) {
+ image.write_to(&mut out, image::ImageFormat::Png)?;
+ } else {
+ let rgb = image.to_rgb8();
+ let mut encoder = image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, 88);
+ encoder.encode_image(&rgb)?;
+ }
+ Ok(out.into_inner())
+}
+
+fn transparent(image: &image::DynamicImage) -> bool {
+ image.color().has_alpha() && image.to_rgba8().pixels().any(|p| p.0[3] != 255)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use image::{DynamicImage, GenericImageView, Rgba, RgbaImage};
+
+ /// A tall picture with a red square in the lower half — where a face would be in a portrait.
+ fn portrait() -> Vec<u8> {
+ let mut img = RgbaImage::from_pixel(100, 200, Rgba([0, 0, 255, 255]));
+ for y in 150..200 {
+ for x in 50..100 {
+ img.put_pixel(x, y, Rgba([255, 0, 0, 255]));
+ }
+ }
+ let mut out = std::io::Cursor::new(Vec::new());
+ DynamicImage::ImageRgba8(img)
+ .write_to(&mut out, image::ImageFormat::Png)
+ .unwrap();
+ out.into_inner()
+ }
+
+ fn middle_pixel(bytes: &[u8]) -> [u8; 3] {
+ let img = image::load_from_memory(bytes).unwrap();
+ let p = img.get_pixel(img.width() / 2, img.height() / 2);
+ [p.0[0], p.0[1], p.0[2]]
+ }
+
+ /// The whole point: a portrait photo cropped where its owner said, not through the middle.
+ #[test]
+ fn the_chosen_square_is_what_gets_drawn() {
+ let source = portrait();
+ let chosen = Crop {
+ x: 50,
+ y: 150,
+ width: 50,
+ height: 50,
+ };
+
+ let cropped = avatar(&source, Some(chosen), 64).unwrap();
+ assert!(
+ middle_pixel(&cropped)[0] > 200,
+ "the chosen square is the red one"
+ );
+
+ let centred = avatar(&source, None, 64).unwrap();
+ assert!(
+ middle_pixel(&centred)[2] > 200,
+ "with no crop it centres, which is why the crop matters"
+ );
+ }
+
+ #[test]
+ fn the_result_is_the_size_that_was_asked_for() {
+ let out = avatar(&portrait(), None, 48).unwrap();
+ let img = image::load_from_memory(&out).unwrap();
+ assert_eq!(img.dimensions(), (48, 48));
+ }
+
+ /// Apple's own API sends fields that do not match what it serves. A rectangle falling off
+ /// the picture must cost a centred face, not a crash or an empty frame.
+ #[test]
+ fn a_rectangle_that_does_not_fit_is_ignored_rather_than_obeyed() {
+ for bad in [
+ Crop {
+ x: 0,
+ y: 0,
+ width: 500,
+ height: 500,
+ },
+ Crop {
+ x: 90,
+ y: 190,
+ width: 50,
+ height: 50,
+ },
+ Crop {
+ x: -10,
+ y: 0,
+ width: 20,
+ height: 20,
+ },
+ ] {
+ let out = avatar(&portrait(), Some(bad), 32).unwrap();
+ assert_eq!(
+ image::load_from_memory(&out).unwrap().dimensions(),
+ (32, 32)
+ );
+ }
+ }
+
+ #[test]
+ fn a_crop_survives_the_round_trip_through_the_library() {
+ let c = Crop {
+ x: 251,
+ y: 1249,
+ width: 1279,
+ height: 1279,
+ };
+ assert_eq!(Crop::parse(&c.to_text()), Some(c));
+ assert_eq!(Crop::parse("1,2,3"), None);
+ assert_eq!(Crop::parse("1,2,3,4,5"), None);
+ assert_eq!(Crop::parse("1,2,0,4"), None, "an empty square is no square");
+ assert_eq!(Crop::parse("a,b,c,d"), None);
+ }
+
+ /// A photograph should not be shipped as a PNG; a picture with holes in it must be.
+ #[test]
+ fn the_format_follows_what_the_picture_needs() {
+ let opaque = avatar(&portrait(), None, 64).unwrap();
+ assert_eq!(&opaque[..3], b"\xff\xd8\xff", "opaque becomes a JPEG");
+
+ let mut img = RgbaImage::from_pixel(20, 20, Rgba([0, 0, 0, 0]));
+ img.put_pixel(10, 10, Rgba([255, 255, 255, 255]));
+ let mut src = std::io::Cursor::new(Vec::new());
+ DynamicImage::ImageRgba8(img)
+ .write_to(&mut src, image::ImageFormat::Png)
+ .unwrap();
+ let holes = avatar(&src.into_inner(), None, 64).unwrap();
+ assert_eq!(&holes[..4], b"\x89PNG", "transparency stays a PNG");
+ }
+
+ #[test]
+ fn bytes_that_are_not_a_picture_are_an_error_not_a_panic() {
+ assert!(avatar(b"404 Not Found", None, 64).is_err());
+ assert!(avatar(b"", None, 64).is_err());
+ }
+}
diff --git a/probe/Cargo.toml b/probe/Cargo.toml
index 6441358..48f9c6b 100644
--- a/probe/Cargo.toml
+++ b/probe/Cargo.toml
@@ -16,3 +16,4 @@ uuid.workspace = true
quince-auth = { path = "../crates/quince-auth" }
quince-core = { path = "../crates/quince-core" }
quince-icloud = { path = "../crates/quince-icloud" }
+quince-media = { workspace = true }
diff --git a/probe/examples/photos_check.rs b/probe/examples/photos_check.rs
new file mode 100644
index 0000000..70ee1b4
--- /dev/null
+++ b/probe/examples/photos_check.rs
@@ -0,0 +1,112 @@
+//! Throwaway: the whole contact-picture chain against the real account.
+use anyhow::{anyhow, Result};
+
+fn kind(b: &[u8]) -> &'static str {
+ match b {
+ [0x89, b'P', b'N', b'G', ..] => "png",
+ [0xff, 0xd8, 0xff, ..] => "jpeg",
+ _ => "UNDRAWABLE",
+ }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ let probe_dir =
+ std::path::PathBuf::from(std::env::var("HOME")?).join(".local/share/quince-probe");
+ let lib_dir = std::path::PathBuf::from(
+ std::env::args()
+ .nth(1)
+ .ok_or_else(|| anyhow!("pass a library dir"))?,
+ );
+
+ let mut client = quince_auth::Client::new(&probe_dir)?;
+ if !client.resume().await? {
+ return Err(anyhow!("the probe session is gone"));
+ }
+ let root = client
+ .session()
+ .service_url("contacts")
+ .ok_or_else(|| anyhow!("no contacts service"))?;
+ let http = client.http().clone();
+ let params = client.service_params();
+
+ let mut library = quince_core::Library::open(&lib_dir)?;
+ println!(
+ "synced {} contacts",
+ quince_icloud::contacts::sync(&http, &root, params.clone(), &mut library).await?
+ );
+
+ let people = library.contacts(None)?;
+ let want = people.iter().filter(|c| c.photo_url.is_some()).count();
+ println!("with a picture: {want} of {}\n", people.len());
+
+ let (mut ok, mut before, mut after) = (0usize, 0usize, 0usize);
+ for person in people.iter().filter(|c| c.photo_url.is_some()) {
+ let photo = library.contact_photo_source(&person.guid)?.ok_or_else(|| {
+ anyhow!(
+ "the handler's own lookup found nothing for {}",
+ person.display_name()
+ )
+ })?;
+ let r = http.get(&photo.url).query(&params).send().await?;
+ let status = r.status();
+ let raw = r.bytes().await?.to_vec();
+ let crop = photo.crop.as_deref().and_then(quince_media::Crop::parse);
+ let drawn = quince_media::avatar(&raw, crop, 256)
+ .map_err(|e| anyhow!("{}: {e}", person.display_name()))?;
+ let square = image_dims(&drawn);
+ println!(
+ " {status} {:>6}b -> {:>6}b {:<5} {square} crop {:<20} {}",
+ raw.len(),
+ drawn.len(),
+ kind(&drawn),
+ photo.crop.clone().unwrap_or_else(|| "none".into()),
+ person.display_name()
+ );
+ before += raw.len();
+ after += drawn.len();
+ if status.is_success() && kind(&drawn) != "UNDRAWABLE" && square == "256x256" {
+ ok += 1;
+ }
+ }
+ println!(
+ "\n{ok} of {want} drawable. {} KB from Apple -> {} KB served.",
+ before / 1024,
+ after / 1024
+ );
+ if ok != want {
+ return Err(anyhow!("some pictures did not survive the chain"));
+ }
+ println!("OK — every picture on the account came through.");
+ Ok(())
+}
+
+fn image_dims(b: &[u8]) -> String {
+ image_size(b).map_or_else(|| "?".into(), |(w, h)| format!("{w}x{h}"))
+}
+fn image_size(b: &[u8]) -> Option<(u32, u32)> {
+ if b.starts_with(b"\x89PNG") && b.len() > 24 {
+ return Some((
+ u32::from_be_bytes(b[16..20].try_into().ok()?),
+ u32::from_be_bytes(b[20..24].try_into().ok()?),
+ ));
+ }
+ // JPEG: walk the segments to the frame header.
+ let mut i = 2;
+ while i + 9 < b.len() {
+ if b[i] != 0xff {
+ i += 1;
+ continue;
+ }
+ let marker = b[i + 1];
+ let len = u16::from_be_bytes([b[i + 2], b[i + 3]]) as usize;
+ if (0xc0..=0xcf).contains(&marker) && marker != 0xc4 && marker != 0xc8 && marker != 0xcc {
+ return Some((
+ u16::from_be_bytes([b[i + 7], b[i + 8]]) as u32,
+ u16::from_be_bytes([b[i + 5], b[i + 6]]) as u32,
+ ));
+ }
+ i += 2 + len;
+ }
+ None
+}
diff --git a/probe/src/main.rs b/probe/src/main.rs
index dfed185..6134bab 100644
--- a/probe/src/main.rs
+++ b/probe/src/main.rs
@@ -1755,6 +1755,9 @@ async fn main() -> Result<()> {
guid: String::new(),
first_name: Some("Quince".into()),
middle_name: None,
+ photo_url: None,
+ photo_signature: None,
+ photo_crop: None,
last_name: Some("Write Test".into()),
company: None,
is_company: false,
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 46b14c1..4e09c7b 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -12,6 +12,7 @@ tauri-build = { version = "2", features = [] }
tauri = { version = "2", features = [] }
quince-auth = { path = "../crates/quince-auth" }
quince-core = { path = "../crates/quince-core" }
+quince-media = { workspace = true }
quince-icloud = { path = "../crates/quince-icloud" }
reqwest.workspace = true
serde.workspace = true
diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs
index 3239221..2d1b097 100644
--- a/src-tauri/src/main.rs
+++ b/src-tauri/src/main.rs
@@ -78,6 +78,25 @@ async fn cloudkit_context(
Ok((client.http().clone(), root, client.service_params()))
}
+/// Undo percent-encoding in a path segment. Enough for the ids this scheme carries.
+fn percent_decode(text: &str) -> String {
+ let bytes = text.as_bytes();
+ let mut out = Vec::with_capacity(bytes.len());
+ let mut i = 0;
+ while i < bytes.len() {
+ if bytes[i] == b'%' && i + 2 < bytes.len() {
+ if let Ok(byte) = u8::from_str_radix(&text[i + 1..i + 3], 16) {
+ out.push(byte);
+ i += 3;
+ continue;
+ }
+ }
+ out.push(bytes[i]);
+ i += 1;
+ }
+ String::from_utf8_lossy(&out).into_owned()
+}
+
fn state_dir(app: &tauri::AppHandle) -> PathBuf {
app.path()
.app_data_dir()
@@ -1109,8 +1128,169 @@ fn spawn_auto_sync(app: tauri::AppHandle, client: Arc<Mutex<Client>>) {
});
}
+/// Where a contact's picture is cached on disk, named by the signature Apple gives it so a
+/// changed picture lands at a new path rather than behind a stale one.
+/// The edge of a served avatar.
+///
+/// Drawn at 26px in a list and 68px on a card, so 256 covers both on a display of any density
+/// while staying a few kilobytes rather than the few hundred Apple stores.
+const AVATAR_PX: u32 = 256;
+
+/// What a picture actually is, read from its own first bytes.
+///
+/// Apple serves contact pictures as PNG today and said nothing about keeping to it, and a
+/// cached copy on disk carries no header to consult — so the bytes are asked directly rather
+/// than a type being assumed. An unrecognised one is still handed over: the webview sniffs
+/// too, and the interface already falls back to initials if it cannot draw it.
+fn image_type(bytes: &[u8]) -> &'static str {
+ match bytes {
+ [0x89, b'P', b'N', b'G', ..] => "image/png",
+ [0xff, 0xd8, 0xff, ..] => "image/jpeg",
+ [b'G', b'I', b'F', b'8', ..] => "image/gif",
+ [b'R', b'I', b'F', b'F', _, _, _, _, b'W', b'E', b'B', b'P', ..] => "image/webp",
+ [_, _, _, _, b'f', b't', b'y', b'p', ..] => "image/heic",
+ _ => "application/octet-stream",
+ }
+}
+
+fn photo_path(dir: &std::path::Path, guid: &str, signature: &str) -> PathBuf {
+ // The signature is base64 and can hold characters a filename cannot.
+ let safe: String = signature
+ .chars()
+ .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+ .collect();
+ let guid_safe: String = guid
+ .chars()
+ .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+ .collect();
+ // No extension: the format is Apple's to choose, and is read back from the bytes.
+ dir.join("photos").join(format!("{guid_safe}-{safe}"))
+}
+
+/// Serve a contact's picture to the interface.
+///
+/// Through a scheme of our own rather than over IPC: the webview loads it the way it loads
+/// any image, into its own cache, so a list of a hundred people does not push a hundred
+/// images through a message channel on every scroll. Fetched from Apple once and kept on
+/// disk after that.
+/// A picture ready to serve, and whether it is safe to let the webview keep it.
+struct Photo {
+ bytes: Vec<u8>,
+ durable: bool,
+}
+
+async fn contact_photo(
+ app: &tauri::AppHandle,
+ guid: &str,
+) -> Result<Photo, Box<dyn std::error::Error + Send + Sync>> {
+ let photo = {
+ let data = app.state::<Data>();
+ let library = data.0.lock().await;
+ library
+ .contact_photo_source(guid)?
+ .ok_or("that contact has no picture")?
+ };
+
+ // A picture shared by the person it belongs to arrives with no signature, and Apple's
+ // own preference on those is that they update themselves. With nothing to tell a cached
+ // copy it has gone stale, none is kept: a stale face is worse than a second fetch.
+ let dir = state_dir(app);
+ let cached = photo
+ .signature
+ .as_deref()
+ .map(|signature| photo_path(&dir, guid, signature));
+ let durable = cached.is_some();
+ if let Some(path) = &cached {
+ if let Ok(bytes) = tokio::fs::read(path).await {
+ return Ok(Photo { bytes, durable });
+ }
+ }
+
+ let (http, params) = {
+ let auth = app.state::<Auth>();
+ let client = auth.client.lock().await;
+ (client.http().clone(), client.service_params())
+ };
+ let response = http.get(&photo.url).query(&params).send().await?;
+ if !response.status().is_success() {
+ return Err(format!("Apple returned {}", response.status()).into());
+ }
+ let bytes = response.bytes().await?.to_vec();
+
+ // Cut to the square its owner chose and sized for a face, off the interface's thread.
+ // Apple stores these whole — one of them is 1696x2528 — and a list of them has to scroll.
+ let crop = photo.crop.as_deref().and_then(quince_media::Crop::parse);
+ let drawn = tokio::task::spawn_blocking(move || quince_media::avatar(&bytes, crop, AVATAR_PX))
+ .await?
+ .map_err(|e| format!("that picture could not be read: {e}"))?;
+
+ if let Some(path) = &cached {
+ if let Some(parent) = path.parent() {
+ tokio::fs::create_dir_all(parent).await.ok();
+ }
+ tokio::fs::write(path, &drawn).await.ok();
+ }
+ Ok(Photo {
+ bytes: drawn,
+ durable,
+ })
+}
+
fn main() {
tauri::Builder::default()
+ // Images are served, not messaged. `quince://photo/<contact id>` is loaded by the
+ // webview itself, which is what keeps a scrolling list cheap.
+ .register_asynchronous_uri_scheme_protocol("quince", |ctx, request, responder| {
+ let app = ctx.app_handle().clone();
+ // WebKitGTK reads `quince://photo/<id>` with "photo" as the host, while Tauri's
+ // own helper produces `quince://localhost/photo/<id>`. Accept either, rather than
+ // depending on which one the caller happened to build.
+ let uri = request.uri();
+ let mut path = uri.path().trim_start_matches('/').to_string();
+ if uri.host() == Some("photo") {
+ path = format!("photo/{path}");
+ }
+ tauri::async_runtime::spawn(async move {
+ let Some(guid) = path.strip_prefix("photo/") else {
+ responder.respond(
+ tauri::http::Response::builder()
+ .status(404)
+ .body(Vec::new())
+ .unwrap_or_default(),
+ );
+ return;
+ };
+ // Percent-encoding: a contact id is a plain UUID, but the scheme should not
+ // assume what a future caller puts here.
+ let guid = percent_decode(guid);
+ match contact_photo(&app, &guid).await {
+ Ok(Photo { bytes, durable }) => responder.respond(
+ tauri::http::Response::builder()
+ .status(200)
+ .header("Content-Type", image_type(&bytes))
+ // A picture with a signature cannot change without the signature
+ // changing too, so the webview may hold it. One without can change
+ // under us, so it is only held long enough to scroll a list.
+ .header(
+ "Cache-Control",
+ if durable {
+ "private, max-age=604800"
+ } else {
+ "private, max-age=300"
+ },
+ )
+ .body(bytes)
+ .unwrap_or_default(),
+ ),
+ Err(_) => responder.respond(
+ tauri::http::Response::builder()
+ .status(404)
+ .body(Vec::new())
+ .unwrap_or_default(),
+ ),
+ }
+ });
+ })
.setup(|app| {
let dir = state_dir(app.handle());
let client = Arc::new(Mutex::new(Client::new(&dir)?));
@@ -1177,3 +1357,44 @@ fn main() {
.run(tauri::generate_context!())
.expect("Quince failed to start");
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// Apple serves contact pictures as PNG, which is not what the first version of this
+ /// assumed. The type is read from the bytes so a change of format is not a broken image.
+ #[test]
+ fn an_image_is_recognised_by_its_own_first_bytes() {
+ assert_eq!(image_type(b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR"), "image/png");
+ assert_eq!(image_type(b"\xff\xd8\xff\xe0JFIF"), "image/jpeg");
+ assert_eq!(image_type(b"GIF89a"), "image/gif");
+ assert_eq!(image_type(b"RIFF\0\0\0\0WEBPVP8 "), "image/webp");
+ assert_eq!(image_type(b"\0\0\0\x18ftypheic"), "image/heic");
+ assert_eq!(image_type(b"not a picture"), "application/octet-stream");
+ assert_eq!(image_type(b""), "application/octet-stream", "and no panic");
+ }
+
+ /// A signature is base64 and holds `/` and `+`; a filename cannot. Two different pictures
+ /// must still land on two different files.
+ #[test]
+ fn a_cached_picture_is_named_safely_and_uniquely() {
+ let dir = std::path::Path::new("/tmp/quince");
+ let one = photo_path(dir, "A-B/C", "FAhjvQxoOa/G338LIq+u7A==");
+ let two = photo_path(dir, "A-B/C", "ZZhjvQxoOa/G338LIq+u7A==");
+ let name = one.file_name().unwrap().to_string_lossy().to_string();
+ assert!(
+ name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-'),
+ "a filename Apple's base64 cannot break: {name}"
+ );
+ assert_ne!(one, two, "a new picture must not read the old one's cache");
+ }
+
+ /// The address bar of the interface is not a path: a contact id arrives encoded.
+ #[test]
+ fn a_percent_encoded_id_comes_back_as_itself() {
+ assert_eq!(percent_decode("a%2Fb"), "a/b");
+ assert_eq!(percent_decode("plain-uuid"), "plain-uuid");
+ assert_eq!(percent_decode("%zz"), "%zz", "malformed stays as it was");
+ }
+}
diff --git a/src/lib/ipc.ts b/src/lib/ipc.ts
index 8df8fd8..e451201 100644
--- a/src/lib/ipc.ts
+++ b/src/lib/ipc.ts
@@ -1,4 +1,4 @@
-import { invoke } from "@tauri-apps/api/core";
+import { convertFileSrc, invoke } from "@tauri-apps/api/core";
export type Status = { hasStoredSession: boolean; signedIn: boolean };
export type SignInResult = "complete" | "needs_two_factor";
@@ -235,6 +235,8 @@ export type Contact = {
firstName: string | null;
middleName: string | null;
lastName: string | null;
+ photoUrl: string | null;
+ photoSignature: string | null;
company: string | null;
isCompany: boolean;
birthday: string | null;
@@ -244,6 +246,17 @@ export type Contact = {
};
/** What to show, whichever name fields a contact happens to have. */
+/**
+ * Where the interface loads a contact's picture from.
+ *
+ * Its own scheme rather than a data URI over IPC: the webview fetches and caches it the way
+ * it does any image, so a list of a hundred people does not push a hundred pictures through
+ * a message channel every time it scrolls.
+ */
+export function photoSrc(c: Contact): string | null {
+ return c.photoUrl ? convertFileSrc(`photo/${c.guid}`, "quince") : null;
+}
+
export function displayName(c: Contact): string {
const full = [c.firstName, c.middleName, c.lastName].filter(Boolean).join(" ").trim();
if (full) return full;
diff --git a/src/screens/ContactsView.tsx b/src/screens/ContactsView.tsx
index 96d9886..fac027c 100644
--- a/src/screens/ContactsView.tsx
+++ b/src/screens/ContactsView.tsx
@@ -3,6 +3,7 @@ import {
api,
displayName,
messageOf,
+ photoSrc,
type Contact,
type ContactMethod,
} from "../lib/ipc";
@@ -16,10 +17,32 @@ const KINDS = [
{ value: "url", label: "link" },
] as const;
+/**
+ * A contact's picture where there is one, initials where there is not.
+ *
+ * The image is allowed to fail — a photo Apple has moved, or no network yet — and when it
+ * does the initials underneath are what shows, rather than a broken frame.
+ */
+function Avatar({ contact, large }: { contact: Contact; large?: boolean }) {
+ const [failed, setFailed] = useState(false);
+ const src = failed ? null : photoSrc(contact);
+ return (
+ <span className={`avatar${large ? " large" : ""}`} aria-hidden="true">
+ {src ? (
+ <img src={src} alt="" onError={() => setFailed(true)} />
+ ) : (
+ initials(contact)
+ )}
+ </span>
+ );
+}
+
const blank = (): Contact => ({
guid: "",
firstName: null,
middleName: null,
+ photoUrl: null,
+ photoSignature: null,
lastName: null,
company: null,
isCompany: false,
@@ -185,7 +208,7 @@ export function ContactsView() {
aria-current={openGuid === contact.guid}
onClick={() => setOpenGuid(contact.guid)}
>
- <span className="avatar" aria-hidden="true">{initials(contact)}</span>
+ <Avatar contact={contact} />
<span className="contact-row-name">{displayName(contact)}</span>
</button>
</li>
@@ -327,7 +350,7 @@ export function ContactsView() {
The avatar used to be pinned to the pane's left edge while the name was
centred somewhere else entirely, so they read as two unrelated things. */}
<div className="contact-head">
- <span className="avatar large" aria-hidden="true">{initials(open)}</span>
+ <Avatar contact={open} large />
<div className="contact-head-names">
<h2>{displayName(open)}</h2>
{open.company && !open.isCompany && (
diff --git a/src/styles/app.css b/src/styles/app.css
index 9fb8870..a0b928a 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -1210,6 +1210,15 @@ textarea.note-text:disabled {
display: grid;
place-items: center;
flex: none;
+ overflow: hidden;
+}
+
+/* Cropped to the circle and filling it, the way a picture sits in Contacts. */
+.avatar img {
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ display: block;
}
.avatar.large {