imprimatur 0.1.0

data/ext/imprimatur_native/core/src/xlsx.rs

@@ -0,0 +1,120 @@
+//! `SpreadsheetML` (`.xlsx`) workbooks, per ECMA-376 Part 1.
+
+mod cell;
+mod comment;
+mod date;
+mod format;
+mod package;
+mod range;
+mod styles;
+#[cfg(test)]
+mod tests;
+pub(crate) mod text;
+mod validation;
+mod worksheet;
+
+use std::fs::File;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+
+pub use crate::style::{Align, Color, TextDirection};
+pub(crate) use cell::push_cell_reference;
+pub use cell::{Cell, cell_reference, column_name};
+pub use comment::Comment;
+pub use date::DateTime;
+pub use format::{Border, Format, VerticalAlign};
+pub use range::{CellRange, parse_cell_reference};
+pub use validation::{Alert, Validation};
+pub use worksheet::{MAX_COLUMNS, MAX_ROWS, Worksheet};
+
+use crate::{Error, Result};
+
+/// The longest sheet name Excel accepts.
+const MAX_SHEET_NAME: usize = 31;
+
+/// A workbook: an ordered list of uniquely named worksheets.
+#[derive(Debug, Default)]
+pub struct Workbook {
+    sheets: Vec<Worksheet>,
+}
+
+impl Workbook {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { sheets: Vec::new() }
+    }
+
+    /// Adds a sheet after the existing ones and returns it for writing.
+    ///
+    /// # Errors
+    /// [`Error::InvalidSheetName`] for a name Excel rejects, and
+    /// [`Error::DuplicateSheetName`] when the name is taken, ignoring case.
+    pub fn add_sheet(&mut self, name: impl Into<String>) -> Result<&mut Worksheet> {
+        let name = name.into();
+        validate_sheet_name(&name)?;
+        let folded = name.to_lowercase();
+        if self.sheets.iter().any(|sheet| sheet.name().to_lowercase() == folded) {
+            return Err(Error::DuplicateSheetName(name));
+        }
+        Ok(self.sheets.push_mut(Worksheet::new(name)))
+    }
+
+    #[must_use]
+    pub fn sheets(&self) -> &[Worksheet] {
+        &self.sheets
+    }
+
+    pub fn sheet_mut(&mut self, index: usize) -> Option<&mut Worksheet> {
+        self.sheets.get_mut(index)
+    }
+
+    /// Writes the `.xlsx` package to `out` and returns it.
+    ///
+    /// # Errors
+    /// [`Error::EmptyWorkbook`] without sheets, [`Error::Io`] when `out` fails.
+    pub fn write_to<W: Write>(&self, out: W) -> Result<W> {
+        package::write(&self.sheets, out)
+    }
+
+    /// The `.xlsx` package as bytes.
+    ///
+    /// # Errors
+    /// As [`write_to`](Self::write_to).
+    pub fn to_bytes(&self) -> Result<Vec<u8>> {
+        self.write_to(Vec::new())
+    }
+
+    /// Writes the `.xlsx` package to a file, replacing it if it exists.
+    ///
+    /// # Errors
+    /// As [`write_to`](Self::write_to).
+    pub fn save(&self, path: impl AsRef<Path>) -> Result<()> {
+        let file = File::create(path)?;
+        self.write_to(BufWriter::new(file))?;
+        Ok(())
+    }
+}
+
+fn validate_sheet_name(name: &str) -> Result<()> {
+    let invalid = |reason| Err(Error::InvalidSheetName { name: name.to_owned(), reason });
+    if name.is_empty() {
+        return invalid("it is empty");
+    }
+    // Excel counts UTF-16 code units.
+    if name.encode_utf16().count() > MAX_SHEET_NAME {
+        return invalid("it is longer than 31 characters");
+    }
+    if name.contains(['[', ']', ':', '*', '?', '/', '\\']) {
+        return invalid("it contains one of [ ] : * ? / \\");
+    }
+    if name.chars().any(crate::xml::is_forbidden) {
+        return invalid("it contains a control character");
+    }
+    if name.starts_with('\'') || name.ends_with('\'') {
+        return invalid("it starts or ends with an apostrophe");
+    }
+    if name.eq_ignore_ascii_case("history") {
+        return invalid("Excel reserves the name History");
+    }
+    Ok(())
+}

data/ext/imprimatur_native/core/src/xml/reader.rs

@@ -0,0 +1,238 @@
+//! A pull parser for the XML parts of OOXML packages. It reads untrusted
+//! input, so it is deliberately small: no DTDs (refused outright, which rules
+//! out entity expansion attacks), only the five predefined entities and
+//! character references, and a nesting limit. Names, attributes and text
+//! borrow from the input; only text with an entity in it is copied.
+//!
+//! Element and attribute names are matched by their local part: `w:p` is
+//! `p`. OOXML parts use one namespace per prefix in practice.
+
+#[cfg(test)]
+mod tests;
+
+use std::borrow::Cow;
+
+use crate::{Error, Result};
+
+/// One step through the document. A self-closing element is a `Start`
+/// followed by its `End`, so readers need not tell the two forms apart.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Event<'a> {
+    Start(Tag<'a>),
+    End(&'a str),
+    Text(Cow<'a, str>),
+}
+
+/// An opening tag: its local name and its raw, still escaped, attributes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Tag<'a> {
+    name: &'a str,
+    attrs: &'a str,
+}
+
+impl<'a> Tag<'a> {
+    /// A tag of this name with these raw attributes, as they sit between
+    /// the name and the closing `>`.
+    pub const fn new(name: &'a str, attrs: &'a str) -> Self {
+        Self { name, attrs }
+    }
+
+    pub const fn name(&self) -> &'a str {
+        self.name
+    }
+
+    /// The attribute with this local name, unescaped.
+    pub fn attr(&self, local: &str) -> Option<Cow<'a, str>> {
+        let mut rest = self.attrs;
+        loop {
+            rest = rest.trim_start();
+            let (name, after) = rest.split_once('=')?;
+            let after = after.trim_start();
+            let quote = after.chars().next().filter(|&quote| quote == '"' || quote == '\'')?;
+            let (value, tail) = after[1..].split_once(quote)?;
+            if local_name(name.trim_end()) == local {
+                return unescape(value).ok();
+            }
+            rest = tail;
+        }
+    }
+
+    /// `w:val`-style booleans: present without a value, `1`, `true` or
+    /// `on` are true; Word writes `w:val="0"` to switch a property off.
+    pub fn flag(&self, local: &str) -> bool {
+        self.attr(local).is_none_or(|value| matches!(&*value, "1" | "true" | "on"))
+    }
+}
+
+pub struct XmlReader<'a> {
+    text: &'a str,
+    pos: usize,
+    depth: usize,
+    max_depth: usize,
+    /// The `End` a self-closing element still owes.
+    pending_end: Option<&'a str>,
+}
+
+impl<'a> XmlReader<'a> {
+    pub const fn new(text: &'a str, max_depth: usize) -> Self {
+        Self { text, pos: 0, depth: 0, max_depth, pending_end: None }
+    }
+
+    /// The next event, or `None` at the end of the input.
+    ///
+    /// # Errors
+    /// [`Error::Malformed`] for broken markup or a DTD, and
+    /// [`Error::LimitExceeded`] beyond the nesting limit.
+    pub fn next(&mut self) -> Result<Option<Event<'a>>> {
+        if let Some(name) = self.pending_end.take() {
+            self.depth -= 1;
+            return Ok(Some(Event::End(name)));
+        }
+        loop {
+            let rest = &self.text[self.pos..];
+            if rest.is_empty() {
+                return Ok(None);
+            }
+            if !rest.starts_with('<') {
+                let end = rest.find('<').unwrap_or(rest.len());
+                self.pos += end;
+                return Ok(Some(Event::Text(unescape(&rest[..end])?)));
+            }
+            if let Some(body) = rest.strip_prefix("<?") {
+                self.pos += 2 + find(body, "?>")? + 2;
+            } else if let Some(body) = rest.strip_prefix("<!--") {
+                self.pos += 4 + find(body, "-->")? + 3;
+            } else if let Some(body) = rest.strip_prefix("<![CDATA[") {
+                let end = find(body, "]]>")?;
+                self.pos += 9 + end + 3;
+                return Ok(Some(Event::Text(Cow::Borrowed(&body[..end]))));
+            } else if rest.starts_with("<!") {
+                return Err(malformed("a DTD or declaration, which is not allowed"));
+            } else if let Some(body) = rest.strip_prefix("</") {
+                let end = find(body, ">")?;
+                self.pos += 2 + end + 1;
+                self.depth =
+                    self.depth.checked_sub(1).ok_or_else(|| malformed("an extra end tag"))?;
+                return Ok(Some(Event::End(local_name(body[..end].trim_end()))));
+            } else {
+                return self.start(&rest[1..]).map(Some);
+            }
+        }
+    }
+
+    /// Skips to the end of the element whose `Start` was just read.
+    pub fn skip(&mut self) -> Result<()> {
+        let mut open = 1_usize;
+        while open > 0 {
+            match self.next()? {
+                Some(Event::Start(_)) => open += 1,
+                Some(Event::End(_)) => open -= 1,
+                Some(Event::Text(_)) => {}
+                None => return Err(malformed("an element that never ends")),
+            }
+        }
+        Ok(())
+    }
+
+    fn start(&mut self, body: &'a str) -> Result<Event<'a>> {
+        let end = tag_end(body)?;
+        let (inner, empty) =
+            body[..end].strip_suffix('/').map_or((&body[..end], false), |inner| (inner, true));
+        let name_end = inner.find(|ch: char| ch.is_ascii_whitespace()).unwrap_or(inner.len());
+        let name = &inner[..name_end];
+        if name.is_empty() {
+            return Err(malformed("a tag without a name"));
+        }
+        self.pos += 1 + end + 1;
+        self.depth += 1;
+        if self.depth > self.max_depth {
+            return Err(Error::LimitExceeded("XML nesting depth"));
+        }
+        let name = local_name(name);
+        if empty {
+            self.pending_end = Some(name);
+        }
+        Ok(Event::Start(Tag { name, attrs: &inner[name_end..] }))
+    }
+}
+
+/// A part's text: UTF-8, with or without a byte order mark, or UTF-16
+/// with one. UTF-8 takes over the bytes' allocation.
+pub fn into_text(mut bytes: Vec<u8>) -> Result<String> {
+    let utf16 = |bytes: &[u8], from: fn([u8; 2]) -> u16| {
+        let units = bytes.as_chunks::<2>().0.iter().map(|pair| from([pair[0], pair[1]]));
+        char::decode_utf16(units)
+            .collect::<Result<String, _>>()
+            .map_err(|_| malformed("invalid UTF-16"))
+    };
+    match bytes.as_slice() {
+        [0xFF, 0xFE, rest @ ..] => return utf16(rest, u16::from_le_bytes),
+        [0xFE, 0xFF, rest @ ..] => return utf16(rest, u16::from_be_bytes),
+        [0xEF, 0xBB, 0xBF, ..] => {
+            bytes.drain(..3);
+        }
+        _ => {}
+    }
+    String::from_utf8(bytes).map_err(|_| malformed("invalid UTF-8"))
+}
+
+/// Replaces the predefined entities and character references.
+pub fn unescape(text: &str) -> Result<Cow<'_, str>> {
+    let Some(first) = text.find('&') else {
+        return Ok(Cow::Borrowed(text));
+    };
+    let mut out = String::with_capacity(text.len());
+    out.push_str(&text[..first]);
+    let mut rest = &text[first..];
+    while let Some(at) = rest.find('&') {
+        out.push_str(&rest[..at]);
+        let entity = &rest[at + 1..];
+        let end = entity.find(';').filter(|&end| end <= 10).ok_or_else(|| malformed("a bare &"))?;
+        out.push(match &entity[..end] {
+            "lt" => '<',
+            "gt" => '>',
+            "amp" => '&',
+            "quot" => '"',
+            "apos" => '\'',
+            reference => character_reference(reference)?,
+        });
+        rest = &entity[end + 1..];
+    }
+    out.push_str(rest);
+    Ok(Cow::Owned(out))
+}
+
+fn character_reference(reference: &str) -> Result<char> {
+    let code = match reference.strip_prefix('#') {
+        Some(hex) if hex.starts_with(['x', 'X']) => u32::from_str_radix(&hex[1..], 16).ok(),
+        Some(decimal) => decimal.parse().ok(),
+        None => None,
+    };
+    code.and_then(char::from_u32).ok_or_else(|| malformed("an unknown entity"))
+}
+
+/// The end of a start tag: its `>`, outside quoted attribute values.
+fn tag_end(body: &str) -> Result<usize> {
+    let mut quote = None;
+    for (at, byte) in body.bytes().enumerate() {
+        match (quote, byte) {
+            (None, b'>') => return Ok(at),
+            (None, b'"' | b'\'') => quote = Some(byte),
+            (Some(open), _) if open == byte => quote = None,
+            _ => {}
+        }
+    }
+    Err(malformed("an unterminated tag"))
+}
+
+fn find(haystack: &str, needle: &str) -> Result<usize> {
+    haystack.find(needle).ok_or_else(|| malformed("unterminated markup"))
+}
+
+pub fn local_name(name: &str) -> &str {
+    name.rsplit_once(':').map_or(name, |(_, local)| local)
+}
+
+fn malformed(reason: &str) -> Error {
+    Error::malformed("XML", reason)
+}

data/ext/imprimatur_native/core/src/xml.rs

@@ -0,0 +1,95 @@
+//! The XML emitter every written part goes through: all it has to get right
+//! is escaping and well-formedness. [`reader`] parses the parts of the
+//! documents being read.
+
+pub mod reader;
+#[cfg(test)]
+mod tests;
+
+/// Builds one XML part in memory.
+pub struct XmlWriter {
+    buf: String,
+}
+
+impl XmlWriter {
+    /// Starts a part with the standalone XML declaration Office writes.
+    pub fn new() -> Self {
+        Self {
+            buf: String::from("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n"),
+        }
+    }
+
+    /// Starts a part without the declaration, as legacy VML is written.
+    pub const fn bare() -> Self {
+        Self { buf: String::new() }
+    }
+
+    /// Writes `<name a="v" ...>`. Attribute values are escaped.
+    pub fn open(&mut self, name: &str, attrs: &[(&str, &str)]) {
+        self.tag(name, attrs);
+        self.buf.push('>');
+    }
+
+    /// Writes `<name a="v" .../>`.
+    pub fn empty(&mut self, name: &str, attrs: &[(&str, &str)]) {
+        self.tag(name, attrs);
+        self.buf.push_str("/>");
+    }
+
+    pub fn close(&mut self, name: &str) {
+        self.buf.push_str("</");
+        self.buf.push_str(name);
+        self.buf.push('>');
+    }
+
+    /// Writes escaped character data.
+    pub fn text(&mut self, text: &str) {
+        escape_into(&mut self.buf, text, false);
+    }
+
+    /// `<name attrs>text</name>`.
+    pub fn element(&mut self, name: &str, attrs: &[(&str, &str)], text: &str) {
+        self.open(name, attrs);
+        self.text(text);
+        self.close(name);
+    }
+
+    pub fn finish(self) -> String {
+        self.buf
+    }
+
+    fn tag(&mut self, name: &str, attrs: &[(&str, &str)]) {
+        self.buf.push('<');
+        self.buf.push_str(name);
+        for (key, value) in attrs {
+            self.buf.push(' ');
+            self.buf.push_str(key);
+            self.buf.push_str("=\"");
+            escape_into(&mut self.buf, value, true);
+            self.buf.push('"');
+        }
+    }
+}
+
+/// Escapes markup characters. In attributes, whitespace other than a space is
+/// written as a character reference too, or attribute normalization would turn
+/// it into a space on read.
+fn escape_into(buf: &mut String, text: &str, attribute: bool) {
+    for ch in text.chars() {
+        match ch {
+            '&' => buf.push_str("&amp;"),
+            '<' => buf.push_str("&lt;"),
+            '>' => buf.push_str("&gt;"),
+            '"' if attribute => buf.push_str("&quot;"),
+            '\t' if attribute => buf.push_str("&#9;"),
+            '\n' if attribute => buf.push_str("&#10;"),
+            '\r' => buf.push_str("&#13;"),
+            ch => buf.push(ch),
+        }
+    }
+}
+
+/// True for characters XML 1.0 cannot carry at all, not even escaped.
+pub const fn is_forbidden(ch: char) -> bool {
+    matches!(ch, '\0'..='\u{8}' | '\u{b}' | '\u{c}' | '\u{e}'..='\u{1f}' | '\u{fffe}' | '\u{ffff}')
+}

data/ext/imprimatur_native/core/src/zip/reader.rs

@@ -0,0 +1,144 @@
+//! Reads the zip container of an OOXML package. Entries are inflated on
+//! demand, each against the read's decompression budget and checked against
+//! its CRC, so a zip bomb fails before it fills memory.
+
+#[cfg(test)]
+mod tests;
+
+use super::{
+    CENTRAL_HEADER, END_OF_CENTRAL_DIRECTORY, LOCAL_HEADER, METHOD_DEFLATED, METHOD_STORED,
+};
+use crate::read::Budget;
+use crate::{Error, Result};
+
+/// The end of central directory record without its trailing comment.
+const END_RECORD: usize = 22;
+const MAX_COMMENT: usize = u16::MAX as usize;
+
+struct Entry<'a> {
+    name: &'a str,
+    method: u16,
+    crc: u32,
+    compressed: usize,
+    size: usize,
+    offset: usize,
+}
+
+pub struct ZipReader<'a> {
+    data: &'a [u8],
+    entries: Vec<Entry<'a>>,
+}
+
+impl<'a> ZipReader<'a> {
+    /// Reads the central directory.
+    ///
+    /// # Errors
+    /// [`Error::Malformed`] when `data` is not a zip archive this reader can
+    /// handle (zip64 and encrypted entries are not).
+    pub fn new(data: &'a [u8]) -> Result<Self> {
+        let search = data.len().saturating_sub(END_RECORD + MAX_COMMENT);
+        let end = (search..=data.len().saturating_sub(END_RECORD))
+            .rev()
+            .find(|&at| u32_at(data, at) == Some(END_OF_CENTRAL_DIRECTORY))
+            .ok_or_else(|| malformed("no end of central directory"))?;
+        let count = usize::from(u16_at(data, end + 10).ok_or_else(|| malformed("truncated"))?);
+        let mut at = u32_at(data, end + 16).ok_or_else(|| malformed("truncated"))? as usize;
+        if at == u32::MAX as usize {
+            return Err(Error::UnsupportedDocument("zip64 archives".to_owned()));
+        }
+        let mut entries = Vec::with_capacity(count);
+        for _ in 0..count {
+            (u32_at(data, at) == Some(CENTRAL_HEADER))
+                .ok_or_else(|| malformed("bad central directory"))?;
+            let field = |offset: usize| u16_at(data, at + offset).map(usize::from);
+            let word = |offset: usize| u32_at(data, at + offset);
+            let (Some(flags), Some(method), Some(crc), Some(compressed), Some(size)) =
+                (field(8), field(10), word(16), word(20), word(24))
+            else {
+                return Err(malformed("truncated central directory"));
+            };
+            let (Some(name_len), Some(extra_len), Some(comment_len), Some(offset)) =
+                (field(28), field(30), field(32), word(42))
+            else {
+                return Err(malformed("truncated central directory"));
+            };
+            if flags & 1 != 0 {
+                return Err(Error::UnsupportedDocument("encrypted zip entries".to_owned()));
+            }
+            let name = data
+                .get(at + 46..at + 46 + name_len)
+                .and_then(|name| std::str::from_utf8(name).ok())
+                .ok_or_else(|| malformed("bad entry name"))?;
+            entries.push(Entry {
+                name: name.trim_start_matches('/'),
+                method: u16::try_from(method).unwrap_or(u16::MAX),
+                crc,
+                compressed: compressed as usize,
+                size: size as usize,
+                offset: offset as usize,
+            });
+            at += 46 + name_len + extra_len + comment_len;
+        }
+        Ok(Self { data, entries })
+    }
+
+    /// The entries' names, in the archive's order.
+    pub fn names(&self) -> impl Iterator<Item = &'a str> + '_ {
+        self.entries.iter().map(|entry| entry.name)
+    }
+
+    /// The entry named `name` (OPC part names ignore ASCII case), inflated,
+    /// or `None` when the archive has none.
+    ///
+    /// # Errors
+    /// [`Error::LimitExceeded`] past the decompression budget, and
+    /// [`Error::Malformed`] for a corrupt entry.
+    pub fn read(&self, name: &str, budget: &Budget<'_>) -> Result<Option<Vec<u8>>> {
+        let name = name.trim_start_matches('/');
+        let Some(entry) = self.entries.iter().find(|entry| entry.name.eq_ignore_ascii_case(name))
+        else {
+            return Ok(None);
+        };
+        let header = entry.offset;
+        (u32_at(self.data, header) == Some(LOCAL_HEADER))
+            .ok_or_else(|| malformed("bad local header"))?;
+        let (Some(name_len), Some(extra_len)) =
+            (u16_at(self.data, header + 26), u16_at(self.data, header + 28))
+        else {
+            return Err(malformed("truncated local header"));
+        };
+        let start = header + 30 + usize::from(name_len) + usize::from(extra_len);
+        let stored = self
+            .data
+            .get(start..start + entry.compressed)
+            .ok_or_else(|| malformed("entry data past the end"))?;
+        (entry.size <= budget.inflatable()).ok_or(Error::LimitExceeded("decompressed size"))?;
+        let data = match entry.method {
+            METHOD_STORED => stored.to_vec(),
+            METHOD_DEFLATED => {
+                match crate::read::inflate::inflate(stored, false, entry.size, entry.size) {
+                    Ok((data, true)) => data,
+                    Ok((_, false)) | Err(_) => return Err(malformed("an entry does not inflate")),
+                }
+            }
+            _ => return Err(Error::UnsupportedDocument("a zip compression method".to_owned())),
+        };
+        budget.inflate(data.len())?;
+        budget.check()?;
+        (data.len() == entry.size && crc32fast::hash(&data) == entry.crc)
+            .ok_or_else(|| malformed("an entry fails its CRC"))?;
+        Ok(Some(data))
+    }
+}
+
+fn u16_at(data: &[u8], at: usize) -> Option<u16> {
+    Some(u16::from_le_bytes(data.get(at..at + 2)?.try_into().ok()?))
+}
+
+fn u32_at(data: &[u8], at: usize) -> Option<u32> {
+    Some(u32::from_le_bytes(data.get(at..at + 4)?.try_into().ok()?))
+}
+
+fn malformed(reason: &str) -> Error {
+    Error::malformed("zip", reason)
+}