diff --git a/crates/psd/src/annotations.rs b/crates/psd/src/annotations.rs new file mode 100644 index 000000000..57b466843 --- /dev/null +++ b/crates/psd/src/annotations.rs @@ -0,0 +1,230 @@ +//! Bounded, borrowed views and serialization of PSD global `Anno` records. +//! +//! Framing follows PhotoCraft's annotation reader (Brandon Thomas, aa87012a), with +//! David Mann's minimum-length guard and the per-entry span fix from PhotoCraft +//! #11138. Coordinates, colour conversion, text decoding and popup defaults are +//! deliberately caller policy. Unknown records can be carried through byte-exact. + +use crate::{PsdError, Result}; + +/// Explicit limits shared by readers and writers. +#[derive(Clone, Copy, Debug)] +pub struct Limits { + /// Maximum complete block size. + pub bytes: usize, + /// Maximum annotation count. + pub records: usize, +} +impl Default for Limits { + fn default() -> Self { + Self { bytes: 16 * 1024 * 1024, records: 4096 } + } +} + +struct Reader<'a> { + d: &'a [u8], + p: usize, +} +impl<'a> Reader<'a> { + fn take(&mut self, n: usize) -> Result<&'a [u8]> { + let end = self.p.checked_add(n).ok_or(PsdError::LimitExceeded("annotation offset"))?; + let s = self.d.get(self.p..end).ok_or(PsdError::UnexpectedEof { offset: self.p, needed: n })?; + self.p = end; + Ok(s) + } + fn u8(&mut self) -> Result { + Ok(self.take(1)?.first().copied().unwrap_or_default()) + } + fn u16(&mut self) -> Result { + Ok(u16::from_be_bytes(self.take(2)?.try_into().map_err(|_| PsdError::invalid("annotation u16"))?)) + } + fn u32(&mut self) -> Result { + Ok(u32::from_be_bytes(self.take(4)?.try_into().map_err(|_| PsdError::invalid("annotation u32"))?)) + } + fn key(&mut self) -> Result<[u8; 4]> { + self.take(4)?.try_into().map_err(|_| PsdError::invalid("annotation key")) + } + fn rect(&mut self) -> Result<[i32; 4]> { + Ok([self.u32()? as i32, self.u32()? as i32, self.u32()? as i32, self.u32()? as i32]) + } + fn pascal(&mut self) -> Result<&'a [u8]> { + let n = usize::from(self.u8()?); + let bytes = self.take(n)?; + if (n + 1) % 2 == 1 { + self.take(1)?; + } + Ok(bytes) + } +} + +/// A borrowed record, including its original length, padding and unknown fields. +#[derive(Clone, Copy, Debug)] +pub struct Record<'a> { + raw: &'a [u8], +} +impl<'a> Record<'a> { + /// Complete self-counting record, suitable for lossless passthrough. + pub fn raw(&self) -> &'a [u8] { + self.raw + } + /// Parse text records; other record kinds remain opaque. + pub fn text(&self) -> Result>> { + let mut r = Reader { d: self.raw, p: 4 }; + if r.key()? != *b"txtA" { + return Ok(None); + } + // Never read beyond this record, even if a text length points into its neighbour. + let open = r.u8()?; + let flags = r.u8()?; + let optional_blocks = r.u16()?; + let icon = r.rect()?; + let popup = r.rect()?; + let color_space = r.u16()?; + let color = [r.u16()?, r.u16()?, r.u16()?, r.u16()?]; + let author = r.pascal()?; + let name = r.pascal()?; + let modified = r.pascal()?; + let data_length = r.u32()?; + let data_key = r.key()?; + let size = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation text"))?; + let data = r.take(size)?; + Ok(Some(Text { open, flags, optional_blocks, icon, popup, color_space, color, author, name, modified, data_length, data_key, data })) + } +} + +/// Wire-level text annotation. Text payload and Pascal strings remain bytes. +/// No text normalisation or application colour/coordinate policy is applied. +#[derive(Clone, Copy, Debug)] +pub struct Text<'a> { + /// Open state byte. + pub open: u8, + /// Flags byte. + pub flags: u8, + /// Optional block flags. + pub optional_blocks: u16, + /// Icon rectangle, top/left/bottom/right. + pub icon: [i32; 4], + /// Popup rectangle, top/left/bottom/right. + pub popup: [i32; 4], + /// PSD colour space. + pub color_space: u16, + /// Raw colour components. + pub color: [u16; 4], + /// Pascal author bytes, maximum 255. + pub author: &'a [u8], + /// Pascal name bytes, maximum 255. + pub name: &'a [u8], + /// Pascal modification-date bytes, maximum 255. + pub modified: &'a [u8], + /// Original self-counting data length, exposed for diagnostics. + /// The writer recomputes this field. + pub data_length: u32, + /// Usually `txtC`; retained without imposing application policy. + pub data_key: [u8; 4], + /// Payload, including any text byte-order mark. + pub data: &'a [u8], +} + +/// Parse complete framing before exposing records. Borrowed payloads do not allocate. +/// Trailing block bytes are accepted as in the existing PhotoCraft reader. +pub fn read(data: &[u8], limits: Limits) -> Result>> { + if data.len() > limits.bytes { + return Err(PsdError::LimitExceeded("annotation bytes")); + } + let mut r = Reader { d: data, p: 0 }; + r.u16()?; + r.u16()?; + let count = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation count"))?; + if count > limits.records || count > data.len().saturating_sub(8) / 8 { + return Err(PsdError::LimitExceeded("annotation count")); + } + let mut out = Vec::new(); + out.try_reserve_exact(count).map_err(|_| PsdError::OutOfMemory("annotation records"))?; + for _ in 0..count { + let start = r.p; + let len = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation length"))?; + // David Mann's zero-length guard: a self-counting record must advance. + if len < 8 { + return Err(PsdError::invalid("annotation record shorter than its header")); + } + r.p = start; + let record = Record { raw: r.take(len)? }; + record.text()?; // validate text spans, including data borrowed by later consumers + out.push(record); + } + Ok(out) +} + +fn append(out: &mut Vec, bytes: &[u8], limit: usize) -> Result<()> { + let len = out.len().checked_add(bytes.len()).ok_or(PsdError::LimitExceeded("annotation bytes"))?; + if len > limit { + return Err(PsdError::LimitExceeded("annotation bytes")); + } + out.try_reserve(bytes.len()).map_err(|_| PsdError::OutOfMemory("annotation bytes"))?; + out.extend_from_slice(bytes); + Ok(()) +} + +fn pascal(out: &mut Vec, bytes: &[u8], limit: usize) -> Result<()> { + let n = u8::try_from(bytes.len()).map_err(|_| PsdError::LimitExceeded("annotation Pascal string"))?; + append(out, &[n], limit)?; + append(out, bytes, limit)?; + if (bytes.len() + 1) % 2 == 1 { + append(out, &[0], limit)?; + } + Ok(()) +} + +/// Serialize one text record, computing both length fields. Caller supplies raw +/// text bytes and already-mapped colour/coordinates; nothing is truncated. +pub fn write_text(text: &Text<'_>, limits: Limits) -> Result> { + let mut out = Vec::new(); + append(&mut out, &[0; 4], limits.bytes)?; + append(&mut out, b"txtA", limits.bytes)?; + append(&mut out, &[text.open, text.flags], limits.bytes)?; + append(&mut out, &text.optional_blocks.to_be_bytes(), limits.bytes)?; + for value in text.icon.into_iter().chain(text.popup) { + append(&mut out, &value.to_be_bytes(), limits.bytes)?; + } + append(&mut out, &text.color_space.to_be_bytes(), limits.bytes)?; + for value in text.color { + append(&mut out, &value.to_be_bytes(), limits.bytes)?; + } + for value in [text.author, text.name, text.modified] { + pascal(&mut out, value, limits.bytes)?; + } + let n = u32::try_from(text.data.len()).map_err(|_| PsdError::LimitExceeded("annotation text"))?; + let data_length = n.checked_add(12).ok_or(PsdError::LimitExceeded("annotation data length"))?; + append(&mut out, &data_length.to_be_bytes(), limits.bytes)?; + append(&mut out, &text.data_key, limits.bytes)?; + append(&mut out, &n.to_be_bytes(), limits.bytes)?; + append(&mut out, text.data, limits.bytes)?; + let len = u32::try_from(out.len()).map_err(|_| PsdError::LimitExceeded("annotation record length"))?; + out.get_mut(..4).ok_or_else(|| PsdError::invalid("annotation header"))?.copy_from_slice(&len.to_be_bytes()); + Ok(out) +} + +/// Combine already-framed records into a version 2.1 block. Unknown record types +/// are preserved byte-exact; malformed text records are refused. +pub fn write(records: &[&[u8]], limits: Limits) -> Result> { + if records.len() > limits.records { + return Err(PsdError::LimitExceeded("annotation count")); + } + let count = u32::try_from(records.len()).map_err(|_| PsdError::LimitExceeded("annotation count"))?; + let mut out = Vec::new(); + append(&mut out, &[0, 2, 0, 1], limits.bytes)?; + append(&mut out, &count.to_be_bytes(), limits.bytes)?; + for raw in records { + let mut r = Reader { d: raw, p: 0 }; + let declared = usize::try_from(r.u32()?).map_err(|_| PsdError::LimitExceeded("annotation record length"))?; + if raw.len() < 8 || declared != raw.len() { + return Err(PsdError::invalid("annotation record length mismatch")); + } + Record { raw }.text()?; + append(&mut out, raw, limits.bytes)?; + } + Ok(out) +} + +#[cfg(test)] +mod tests; diff --git a/crates/psd/src/annotations/tests.rs b/crates/psd/src/annotations/tests.rs new file mode 100644 index 000000000..e207852d4 --- /dev/null +++ b/crates/psd/src/annotations/tests.rs @@ -0,0 +1,117 @@ +use super::*; + +fn note() -> Text<'static> { + Text { + open: 1, + flags: 0x1c, + optional_blocks: 1, + icon: [10, 20, 30, 36], + popup: [30, 40, 190, 280], + color_space: 0, + color: [65535, 1000, 3000, 0], + author: b"Writer", + name: b"", + modified: b"2026", + data_length: 0, + data_key: *b"txtC", + data: &[0xfe, 0xff, 0, 65, 0, 13, 0, 66], + } +} + +#[test] +fn text_and_unknown_sound_round_trip_without_copying_payloads() { + let limits = Limits::default(); + let text = write_text(¬e(), limits).unwrap(); + let sound = [0, 0, 0, 11, b's', b'n', b'd', b'A', 42, 3, 9]; + let block = write(&[&text, &sound], limits).unwrap(); + let parsed = read(&block, limits).unwrap(); + assert_eq!(parsed.len(), 2); + let view = parsed[0].text().unwrap().unwrap(); + assert_eq!(view.author, note().author); + assert_eq!(view.data, note().data); + assert_eq!(view.icon, note().icon); + assert_eq!(view.color, note().color); + assert_eq!(view.data_length, 20); + assert!(parsed[1].text().unwrap().is_none()); + assert_eq!(parsed[1].raw(), sound); + let slices: Vec<_> = parsed.iter().map(Record::raw).collect(); + assert_eq!(write(&slices, limits).unwrap(), block); + assert!(view.data.as_ptr() >= block.as_ptr()); + assert!(view.data.as_ptr() < block.as_ptr().wrapping_add(block.len())); +} + +#[test] +fn text_cannot_read_past_the_declared_entry_into_its_neighbour() { + // Regression from PhotoCraft #11138, without its app Note/Color policy. + let mut record = write_text(¬e(), Limits::default()).unwrap(); + let shortened = record.len() - note().data.len(); + record[..4].copy_from_slice(&(shortened as u32).to_be_bytes()); + let mut block = vec![0, 2, 0, 1, 0, 0, 0, 1]; + block.extend_from_slice(&record); + assert!(read(&block, Limits::default()).is_err()); + assert!(write(&[&record], Limits::default()).is_err()); +} + +#[test] +fn truncation_and_hostile_counts_lengths_fail_closed() { + let record = write_text(¬e(), Limits::default()).unwrap(); + let block = write(&[&record], Limits::default()).unwrap(); + for end in 0..block.len() { + assert!(read(&block[..end], Limits::default()).is_err(), "{end}"); + } + for len in [0u32, 1, 7, u32::MAX] { + let mut bad = block.clone(); + bad[8..12].copy_from_slice(&len.to_be_bytes()); + assert!(read(&bad, Limits::default()).is_err()); + } + let mut bad = block; + bad[4..8].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(read(&bad, Limits::default()).is_err()); +} + +#[test] +fn explicit_limits_and_pascal_length_are_not_silently_truncated() { + let record = write_text(¬e(), Limits::default()).unwrap(); + let block = write(&[&record], Limits::default()).unwrap(); + assert!(read(&block, Limits { records: 0, ..Limits::default() }).is_err()); + assert!(read(&block, Limits { bytes: block.len() - 1, ..Limits::default() }).is_err()); + assert!(write(&[&record], Limits { records: 0, ..Limits::default() }).is_err()); + assert!(write_text(¬e(), Limits { bytes: record.len() - 1, ..Limits::default() }).is_err()); + let long = [0; 256]; + let mut text = note(); + text.author = &long; + assert!(write_text(&text, Limits::default()).is_err()); +} + +#[test] +fn preserves_legacy_version_and_unused_data_header_acceptance() { + let record = write_text(¬e(), Limits::default()).unwrap(); + let mut block = write(&[&record], Limits::default()).unwrap(); + block[..4].copy_from_slice(&[0, 9, 0, 8]); + block.extend_from_slice(b"trailing"); + assert_eq!(read(&block, Limits::default()).unwrap()[0].raw(), record); +} + +#[test] +fn canonical_layout_matches_the_existing_photocraft_writer() { + // PhotoCraft annotations_map::write_note layout (Brandon Thomas, aa87012a). + // App RGB/position/text conversion happens before this shared wire writer. + let n = note(); + let mut expected = vec![0, 0, 0, 0]; + expected.extend_from_slice(b"txtA"); + expected.extend_from_slice(&[1, 0x1c, 0, 1]); + for value in [10i32, 20, 30, 36, 30, 40, 190, 280] { + expected.extend_from_slice(&value.to_be_bytes()); + } + for value in [0u16, 65535, 1000, 3000, 0] { + expected.extend_from_slice(&value.to_be_bytes()); + } + expected.extend_from_slice(b"\x06Writer\x00\x00\x00\x042026\x00"); + expected.extend_from_slice(&20u32.to_be_bytes()); + expected.extend_from_slice(b"txtC"); + expected.extend_from_slice(&8u32.to_be_bytes()); + expected.extend_from_slice(n.data); + let len = expected.len() as u32; + expected[..4].copy_from_slice(&len.to_be_bytes()); + assert_eq!(write_text(&n, Limits::default()).unwrap(), expected); +} diff --git a/crates/psd/src/lib.rs b/crates/psd/src/lib.rs index 93acd5f39..8126437ff 100644 --- a/crates/psd/src/lib.rs +++ b/crates/psd/src/lib.rs @@ -54,6 +54,7 @@ pub mod aco; pub mod act; pub mod adjust; pub mod animation; +pub mod annotations; pub mod ase; pub mod asl; pub mod atn;