From 1ec7ab92b5a316d41642c388561fc5c2a2ad8492 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 07:57:29 -0500 Subject: [PATCH] Expose bounded cross-platform binary plist reader with explicit limits --- ATTRIBUTION.md | 4 + Cargo.lock | 7 ++ Cargo.toml | 1 + crates/plist/Cargo.toml | 14 ++++ crates/plist/README.md | 11 +++ crates/plist/src/binary.rs | 90 +++++++++++++++-------- crates/plist/src/bytes.rs | 45 ------------ crates/plist/src/lib.rs | 33 +++++++++ crates/plist/tests/limits.rs | 57 ++++++++++++++ crates/plist/tests/plist_object_bounds.rs | 3 - 10 files changed, 188 insertions(+), 77 deletions(-) create mode 100644 crates/plist/Cargo.toml create mode 100644 crates/plist/README.md create mode 100644 crates/plist/src/lib.rs create mode 100644 crates/plist/tests/limits.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 77d3578cb..c087ecda1 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -95,3 +95,7 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso | `crates/raw/docs/raf-corpus.sha256` (hashes only; the files are not bundled) | The photographers who contributed each file to raw.pixls.us | [raw.pixls.us](https://raw.pixls.us/) | CC0-1.0 | | `crates/drawingml/src/preset_text.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_guides.py` from the guide formulas of ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) | | `crates/drawingml/tests/fixtures/preset_table.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_table.py` from ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) | + +## Binary Apple property lists + +`crates/plist` is extracted from `storytold/craft-anything` (`crates/formats/src/plist.rs` and checked byte reads), at source main `88d1d9cac852aec1c7fd97886db451e005e49d2a`. MIT OR Apache-2.0; source license texts are retained in the crate. Primary import Git authors preserve Brandon Thomas, BFlat, RRFZ and Afloat. Regression imports preserve BFlat. XML, JSON projection, calendar formatting and app policy were not imported into the public API. diff --git a/Cargo.lock b/Cargo.lock index 4936ffe2b..529e1a2e0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2357,6 +2357,13 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-plist" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + [[package]] name = "craft-platform" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 77b20da79..c5a585d7b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,6 +17,7 @@ craft-proto = { path = "crates/proto" } acadrust = "=0.6.6" log = "0.4" # internal: add each crate here as `craft- = { path = "crates/" }` +craft-plist = { path = "crates/plist" } craft-platform = { path = "crates/platform" } craft-aep = { path = "crates/aep" } craft-affinity = { path = "crates/affinity" } diff --git a/crates/plist/Cargo.toml b/crates/plist/Cargo.toml new file mode 100644 index 000000000..7ae95aae0 --- /dev/null +++ b/crates/plist/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "craft-plist" +description = "Bounded cross-platform binary Apple property-list reader" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +thiserror.workspace = true diff --git a/crates/plist/README.md b/crates/plist/README.md new file mode 100644 index 000000000..dc5c52007 --- /dev/null +++ b/crates/plist/README.md @@ -0,0 +1,11 @@ +# craft-plist + +A cross-platform bounded binary (`bplist00`) reader, extracted from Craft Anything's existing implementation and hardening history. Typed dictionaries retain order and duplicate keys; `get` returns the first match. Strings retain the source reader's lossy decoding policy. Shared references expand under node and decoded-byte budgets, and cycles are rejected. + +`parse_binary_with_limits` accepts explicit input, object, expanded-node, nesting and decoded-byte limits. Recursion always has a hard ceiling of 256 even if a caller supplies a larger depth. Counts are checked before container reservation; allocations can return a resource error. Limits are per parse, not a promise of a precise process RSS cap. + +This first PR contains reading only. XML parsing/writing and keyed-archive interpretation are not implemented. JSON projection, date formatting, OS file access and preference/locale selection are not part of this crate. Existing updater/Photo streaming `plist` users remain unchanged. + +Initial consumers: PhotoCraft's AppleLanguages binary-reader path; later Craft Anything binary parsing and LightCraft XML presets (after XML support/parity). Photo must retain its 4 MiB input policy and first-language selection. + +Source: `storytold/craft-anything` at `88d1d9cac852aec1c7fd97886db451e005e49d2a`, `crates/formats/src/plist.rs` and checked byte reader. Source license files retained. Imported changes retain Brandon Thomas, BFlat, RRFZ and Afloat as primary Git authors; imported regression tests are BFlat's. No external specification implementation copied. diff --git a/crates/plist/src/binary.rs b/crates/plist/src/binary.rs index 26129ad83..3e65f1a9e 100644 --- a/crates/plist/src/binary.rs +++ b/crates/plist/src/binary.rs @@ -1,8 +1,4 @@ -use crate::{FormatError, bytes::Reader}; - -pub const MAX_DEPTH: usize = 256; -pub const MAX_NODES: usize = 2_000_000; -pub const MAX_EXPANDED_BYTES: usize = 64 << 20; +use crate::{FormatError, Limits, bytes::Reader}; #[derive(Debug, Clone, PartialEq)] pub enum Value { @@ -61,7 +57,6 @@ impl Value { _ => None, } } - } struct Bin<'a> { r: Reader<'a>, @@ -70,19 +65,23 @@ struct Bin<'a> { nodes: usize, /// Data and text bytes still allowed to be copied out. bytes_left: usize, + limits: Limits, } /// Parse a `bplist00` binary property list. pub fn parse_binary(data: &[u8]) -> Result { - parse_binary_within(data, MAX_EXPANDED_BYTES.max(data.len().saturating_mul(3))) + parse_binary_with_limits(data, Limits::default()) } -/// Parse a binary property list, producing at most `byte_budget` bytes of data and decoded text. -fn parse_binary_within(data: &[u8], byte_budget: usize) -> Result { +/// Parse a binary property list, with caller-selected input, object, expansion and nesting limits. +pub fn parse_binary_with_limits(data: &[u8], limits: Limits) -> Result { + if data.len() > limits.max_input_bytes { + return Err(FormatError::TooLarge("input bytes".into())); + } if !data.starts_with(b"bplist") { return Err(FormatError::Malformed("not a binary plist".into())); } - if !data.starts_with(b"bplist0") { + if !data.starts_with(b"bplist00") { return Err(FormatError::Unsupported("unknown binary plist version".into())); } let len = data.len(); @@ -104,11 +103,14 @@ fn parse_binary_within(data: &[u8], byte_budget: usize) -> Result len { return Err(FormatError::Malformed(format!("{num} objects in a {len}-byte file"))); } + if num > limits.max_objects { + return Err(FormatError::TooLarge("object count".into())); + } let need = num.checked_mul(off_size).and_then(|n| n.checked_add(table)).ok_or_else(|| FormatError::Malformed("offset table".into()))?; if need > t || table < 8 { return Err(FormatError::Truncated("offset table runs past the trailer".into())); } - let mut offsets = Vec::with_capacity(num); + let mut offsets = reserved(num)?; for i in 0..num { let o = read_be(&r, table + i * off_size, off_size).ok_or_else(|| FormatError::Truncated("offset table".into()))?; let o = usize::try_from(o).map_err(|_| FormatError::Malformed("object offset".into()))?; @@ -120,8 +122,8 @@ fn parse_binary_within(data: &[u8], byte_budget: usize) -> Result { usize::try_from(v).map_err(|_| FormatError::Malformed("reference".into())) } - /// Refuse a container whose `children` would pass MAX_NODES, before space is reserved for them. + /// Refuse a container whose `children` would pass the node limit, before space is reserved for them. fn room_for_nodes(&self, children: usize) -> Result<(), FormatError> { - if children > MAX_NODES.saturating_sub(self.nodes) { - return Err(FormatError::TooLarge(format!("more than {MAX_NODES} plist nodes"))); + if children > self.limits.max_nodes.saturating_sub(self.nodes) { + return Err(FormatError::TooLarge("expanded node count".into())); } Ok(()) } @@ -187,10 +189,10 @@ impl Bin<'_> { /// Read object `idx`. `stack` holds the containers on the current path, so a cycle is refused. fn object(&mut self, idx: usize, stack: &mut Vec) -> Result { self.nodes += 1; - if self.nodes > MAX_NODES { - return Err(FormatError::TooLarge(format!("more than {MAX_NODES} plist nodes"))); + if self.nodes > self.limits.max_nodes { + return Err(FormatError::TooLarge("expanded node count".into())); } - if stack.len() >= MAX_DEPTH { + if stack.len() >= self.limits.max_depth.min(256) { return Err(FormatError::Malformed("nesting too deep".into())); } if stack.contains(&idx) { @@ -227,18 +229,32 @@ impl Bin<'_> { }; Value::Real(v.ok_or_else(|| FormatError::Truncated("real".into()))?) } - 0x3 if lo == 3 => Value::Date(DateValue::Seconds(self.r.u64_be(at + 1).map(f64::from_bits).ok_or_else(|| FormatError::Truncated("date".into()))?)), + 0x3 if lo == 3 => { + Value::Date(DateValue::Seconds(self.r.u64_be(at + 1).map(f64::from_bits).ok_or_else(|| FormatError::Truncated("date".into()))?)) + } 0x4 => { let (n, s) = self.count(at, lo)?; let bytes = self.r.slice(s, n).ok_or_else(|| FormatError::Truncated("data".into()))?; self.spend(bytes.len())?; - Value::Data(bytes.to_vec()) + { + let mut out = reserved(bytes.len())?; + out.extend_from_slice(bytes); + Value::Data(out) + } } 0x5 => { let (n, s) = self.count(at, lo)?; let bytes = self.r.slice(s, n).ok_or_else(|| FormatError::Truncated("string".into()))?; - self.spend(lossy_utf8_len(bytes))?; - Value::String(String::from_utf8_lossy(bytes).into_owned()) + let size = lossy_utf8_len(bytes); + self.spend(size)?; + let mut out = reserved_string(size)?; + for chunk in bytes.utf8_chunks() { + out.push_str(chunk.valid()); + if !chunk.invalid().is_empty() { + out.push(char::REPLACEMENT_CHARACTER); + } + } + Value::String(out) } 0x6 => { let (n, s) = self.count(at, lo)?; @@ -246,9 +262,14 @@ impl Bin<'_> { .r .slice(s, n.checked_mul(2).ok_or_else(|| FormatError::Malformed("string".into()))?) .ok_or_else(|| FormatError::Truncated("string".into()))?; - self.spend(lossy_utf16_len(bytes))?; - let units: Vec = bytes.as_chunks::<2>().0.iter().map(|c| u16::from_be_bytes(*c)).collect(); - Value::String(String::from_utf16_lossy(&units)) + let size = lossy_utf16_len(bytes); + self.spend(size)?; + let mut out = reserved_string(size)?; + let units = bytes.as_chunks::<2>().0.iter().map(|c| u16::from_be_bytes(*c)); + for ch in char::decode_utf16(units) { + out.push(ch.unwrap_or(char::REPLACEMENT_CHARACTER)); + } + Value::String(out) } 0x8 => { if lo > 7 { @@ -260,14 +281,14 @@ impl Bin<'_> { 0xa | 0xc => { let (n, s) = self.count(at, lo)?; // Writers store equal values once, so an array may name one object many times: - // only its references have to fit in the file. MAX_NODES and the byte budget bound + // only its references have to fit in the file. the node limit and the byte budget bound // the expansion. if s.saturating_add(n.saturating_mul(self.ref_size)) > self.r.len() { return Err(FormatError::Malformed("array larger than the file".into())); } self.room_for_nodes(n)?; stack.push(idx); - let mut out = Vec::with_capacity(n); + let mut out = reserved(n)?; for i in 0..n { let child = self.reference(s, i)?; out.push(self.object(child, stack)?); @@ -282,7 +303,7 @@ impl Bin<'_> { } self.room_for_nodes(n.saturating_mul(2))?; stack.push(idx); - let mut out = Vec::with_capacity(n); + let mut out = reserved(n)?; for i in 0..n { let k = self.reference(s, i)?; let v = self.reference(s, i + n)?; @@ -301,3 +322,14 @@ impl Bin<'_> { } } +fn reserved(n: usize) -> Result, FormatError> { + let mut v = Vec::new(); + v.try_reserve_exact(n).map_err(|_| FormatError::TooLarge("allocation".into()))?; + Ok(v) +} + +fn reserved_string(n: usize) -> Result { + let mut s = String::new(); + s.try_reserve_exact(n).map_err(|_| FormatError::TooLarge("string allocation".into()))?; + Ok(s) +} diff --git a/crates/plist/src/bytes.rs b/crates/plist/src/bytes.rs index b9de989c3..bdfecc668 100644 --- a/crates/plist/src/bytes.rs +++ b/crates/plist/src/bytes.rs @@ -14,14 +14,6 @@ impl<'a> Reader<'a> { self.data.len() } - pub fn is_empty(&self) -> bool { - self.data.is_empty() - } - - pub fn data(&self) -> &'a [u8] { - self.data - } - pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> { let end = off.checked_add(len)?; self.data.get(off..end) @@ -35,22 +27,6 @@ impl<'a> Reader<'a> { self.slice(off, N)?.try_into().ok() } - pub fn u16_le(&self, off: usize) -> Option { - self.arr(off).map(u16::from_le_bytes) - } - - pub fn u32_le(&self, off: usize) -> Option { - self.arr(off).map(u32::from_le_bytes) - } - - pub fn u64_le(&self, off: usize) -> Option { - self.arr(off).map(u64::from_le_bytes) - } - - pub fn u16_be(&self, off: usize) -> Option { - self.arr(off).map(u16::from_be_bytes) - } - pub fn u32_be(&self, off: usize) -> Option { self.arr(off).map(u32::from_be_bytes) } @@ -58,25 +34,4 @@ impl<'a> Reader<'a> { pub fn u64_be(&self, off: usize) -> Option { self.arr(off).map(u64::from_be_bytes) } - - /// A NUL-terminated string starting at `off`, at most `max` bytes, lossily decoded. - pub fn cstr(&self, off: usize, max: usize) -> Option { - let rest = self.data.get(off..)?; - let rest = rest.get(..max.min(rest.len()))?; - let end = rest.iter().position(|&b| b == 0).unwrap_or(rest.len()); - Some(String::from_utf8_lossy(rest.get(..end)?).into_owned()) - } - - /// Unsigned LEB128 at `off`: (value, bytes consumed). At most 10 bytes. - pub fn uleb128(&self, off: usize) -> Option<(u64, usize)> { - let mut result = 0u64; - for i in 0..10usize { - let b = self.u8(off.checked_add(i)?)?; - result |= u64::from(b & 0x7f).checked_shl(7 * i as u32)?; - if b & 0x80 == 0 { - return Some((result, i + 1)); - } - } - None - } } diff --git a/crates/plist/src/lib.rs b/crates/plist/src/lib.rs new file mode 100644 index 000000000..3e4c6cd85 --- /dev/null +++ b/crates/plist/src/lib.rs @@ -0,0 +1,33 @@ +//! Bounded binary Apple property lists, independent of operating-system preferences. +//! XML and writing are intentionally not implemented in this first extraction. +//! File discovery, locale selection, bundle validation and application policy stay in callers. +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +mod binary; +mod bytes; +pub use binary::{DateValue, Value, parse_binary, parse_binary_with_limits}; + +/// Caller-selected resource limits. Zero values refuse the corresponding resource. +#[derive(Clone, Copy, Debug)] +pub struct Limits { + pub max_input_bytes: usize, + pub max_objects: usize, + pub max_nodes: usize, + pub max_depth: usize, + pub max_expanded_bytes: usize, +} +impl Default for Limits { + fn default() -> Self { + Self { max_input_bytes: 16 << 20, max_objects: 100_000, max_nodes: 100_000, max_depth: 64, max_expanded_bytes: 64 << 20 } + } +} +#[derive(Debug, thiserror::Error)] +pub enum FormatError { + #[error("malformed property list: {0}")] + Malformed(String), + #[error("truncated property list: {0}")] + Truncated(String), + #[error("unsupported property list: {0}")] + Unsupported(String), + #[error("property list resource limit: {0}")] + TooLarge(String), +} diff --git a/crates/plist/tests/limits.rs b/crates/plist/tests/limits.rs new file mode 100644 index 000000000..0c4fefd7c --- /dev/null +++ b/crates/plist/tests/limits.rs @@ -0,0 +1,57 @@ +use craft_plist::{Limits, Value, parse_binary, parse_binary_with_limits}; +fn plist(objects: &[&[u8]]) -> Vec { + let mut b = b"bplist00".to_vec(); + let mut offsets = Vec::new(); + for obj in objects { + offsets.push(b.len() as u8); + b.extend_from_slice(obj); + } + let table = b.len() as u64; + b.extend_from_slice(&offsets); + b.extend_from_slice(&[0, 0, 0, 0, 0, 0, 1, 1]); + b.extend_from_slice(&(objects.len() as u64).to_be_bytes()); + b.extend_from_slice(&0u64.to_be_bytes()); + b.extend_from_slice(&table.to_be_bytes()); + b +} +#[test] +fn languages_and_every_truncation() { + let b = plist(&[&[0xd1, 1, 2], b"\x5eAppleLanguages", &[0xa1, 3], b"\x55ja-JP"]); + let p = parse_binary(&b).unwrap(); + assert_eq!(p.get("AppleLanguages").unwrap().as_array().unwrap()[0].as_str(), Some("ja-JP")); + for n in 0..b.len() { + assert!(parse_binary(&b[..n]).is_err(), "prefix {n}"); + } +} +#[test] +fn cycles_and_repeated_references() { + assert!(parse_binary(&plist(&[&[0xa1, 0]])).is_err()); + let b = plist(&[&[0xa3, 1, 1, 1], b"\x51x"]); + assert_eq!(parse_binary(&b).unwrap(), Value::Array(vec![Value::String("x".into()); 3])); + assert!(parse_binary_with_limits(&b, Limits { max_nodes: 3, ..Limits::default() }).is_err()); + assert!(parse_binary_with_limits(&b, Limits { max_expanded_bytes: 2, ..Limits::default() }).is_err()); +} +#[test] +fn explicit_limits_and_version() { + let b = plist(&[&[0xa1, 1], b"\x51x"]); + for l in [ + Limits { max_input_bytes: b.len() - 1, ..Limits::default() }, + Limits { max_objects: 1, ..Limits::default() }, + Limits { max_depth: 1, ..Limits::default() }, + Limits { max_nodes: 0, ..Limits::default() }, + ] { + assert!(parse_binary_with_limits(&b, l).is_err()); + } + let mut future = b; + future[7] = b'1'; + assert!(parse_binary(&future).is_err()); +} +#[test] +fn utf16_and_lossy_expansion_spend_budget() { + let b = plist(&[&[0x62, 0xd8, 0x3d, 0xde, 0x00]]); + assert_eq!(parse_binary(&b).unwrap().as_str(), Some("😀")); + assert!(parse_binary_with_limits(&b, Limits { max_expanded_bytes: 3, ..Limits::default() }).is_err()); + let bad = plist(&[&[0x51, 0xff]]); + assert_eq!(parse_binary(&bad).unwrap().as_str(), Some("�")); + assert!(parse_binary_with_limits(&bad, Limits { max_expanded_bytes: 2, ..Limits::default() }).is_err()); +} diff --git a/crates/plist/tests/plist_object_bounds.rs b/crates/plist/tests/plist_object_bounds.rs index 52d30cb80..d35fd91b1 100644 --- a/crates/plist/tests/plist_object_bounds.rs +++ b/crates/plist/tests/plist_object_bounds.rs @@ -1,5 +1,4 @@ use craft_plist::{Value, parse_binary}; -use craft_anything_testkit::apple as fx; fn single_object(object: &[u8], offset: u8) -> Vec { let mut data = b"bplist00".to_vec(); @@ -29,6 +28,4 @@ fn binary_offsets_cannot_point_inside_the_file_header() { #[test] fn objects_ending_at_the_table_boundary_are_valid() { assert!(matches!(parse_binary(&single_object(&[0x51, b'x'], 8)), Ok(Value::String(s)) if s == "x")); - let sample = fx::sample_plist(); - assert_eq!(parse_binary(&fx::to_bplist(&sample)).unwrap().get("Count").and_then(Value::as_int), Some(-42)); }