Files
craft-libs/crates/ora/src/lib.rs
T
Dylan M. Taylor c86ea6802a craft-ora, craft-kra: charge every entry to one document-wide total (#1339)
An archive could hold many individually allowed members whose combined
decompression was unbounded, because both readers passed
max_total_bytes: u64::MAX to craft-zip. Each now passes MAX_TOTAL (4 GiB)
and every entry read is charged to it.

craft-fig's declared-entry cap drops from 1,000,000 to 100,000 to match the
other ZIP readers; its images were already bounded by Limits::max_image_total.
2026-11-14 13:45:31 -05:00

463 lines
18 KiB
Rust

#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! OpenRaster (`.ora`) read and write. Layout from the public OpenRaster specification
//! (<https://www.openraster.org/>, `stack.xml` 0.0.x): a ZIP whose first, stored entry is
//! `mimetype` = `image/openraster`, a `stack.xml` layer tree, one PNG per layer, and a
//! `mergedimage.png` / `Thumbnails/thumbnail.png` rendering.
//!
//! - [`Archive::open`] checks the mimetype and reads `stack.xml` into an [`Image`]: the tree of
//! [`Node`]s with the attributes the file has. [`Archive::entry`] reads a layer's image.
//! - [`Writer`] builds an archive: the mimetype first, then the entries it is given and the
//! `stack.xml` of an [`Image`].
//!
//! Layer images are PNG files; decoding and encoding them is the caller's. So is what a
//! composite operation means: `composite-op` is kept as written ([`SVG_COMPOSITE_OPS`] lists the
//! specification's names).
#[cfg(test)]
mod tests;
use craft_xml::El;
/// Why an OpenRaster document was not read or written.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The file is not an OpenRaster archive, is damaged, or exceeds a limit.
#[error("invalid OpenRaster document: {0}")]
Invalid(String),
/// The archive could not be written.
#[error("OpenRaster archive not written: {0}")]
Write(String),
}
pub type Result<T> = std::result::Result<T, Error>;
fn invalid(message: impl Into<String>) -> Error {
Error::Invalid(message.into())
}
/// The `mimetype` entry of an OpenRaster archive.
pub const MIMETYPE: &[u8] = b"image/openraster";
/// The `stack.xml` version [`Image::to_xml`] writes when the image names none.
pub const VERSION: &str = "0.0.6";
/// Canvas side limit; layer offsets may be up to four times this.
pub const MAX_SIDE: u32 = 300_000;
/// The canvas may hold at most this many bytes at 8 bytes per pixel (16-bit RGBA).
pub const MAX_PIXEL_BYTES: usize = 1 << 30;
/// Elements under the root stack: layers, stacks and unknown ones.
pub const MAX_NODES: usize = 8192;
/// Largest `stack.xml`.
pub const MAX_STACK_XML: usize = 16 << 20;
/// Largest layer image file a reader should ask [`Archive::entry`] for.
pub const MAX_ENTRY: usize = 512 << 20;
/// Most entries the archive may declare; checked before the archive is indexed.
pub const MAX_ENTRIES: u64 = 100_000;
/// Most bytes all the entries read from one archive may expand to together. Each layer image may
/// be [`MAX_ENTRY`] on its own, so without a total a document of many layers could spend far more
/// than one open should.
pub const MAX_TOTAL: u64 = 4 << 30;
/// Deepest element nesting of `stack.xml`.
pub const MAX_XML_DEPTH: usize = 512;
/// The compositing operations the specification names for `composite-op`. Applications also
/// write `svg:plus`, `svg:exclusion` and their own (`krita:<id>`).
pub const SVG_COMPOSITE_OPS: [&str; 15] = [
"svg:src-over",
"svg:multiply",
"svg:screen",
"svg:overlay",
"svg:darken",
"svg:lighten",
"svg:color-dodge",
"svg:color-burn",
"svg:hard-light",
"svg:soft-light",
"svg:difference",
"svg:color",
"svg:luminosity",
"svg:hue",
"svg:saturation",
];
/// The payload of a ZIP's first entry when it is a stored file named `mimetype` of at most 256
/// bytes, which is how OpenRaster (and Krita, OpenDocument, EPUB) mark their archives so the
/// type is readable without unzipping.
pub fn zip_mimetype(bytes: &[u8]) -> Option<&[u8]> {
craft_zip::stored_mimetype(bytes)
}
/// `true` for an OpenRaster archive (by its `mimetype` entry).
pub fn is_ora(bytes: &[u8]) -> bool {
zip_mimetype(bytes) == Some(MIMETYPE)
}
/// The attributes a `<layer>` and a `<stack>` share.
#[derive(Clone, Debug, PartialEq)]
pub struct Props {
/// `name`, exactly as written (surrounding whitespace kept).
pub name: Option<String>,
/// `visibility`: everything but `hidden` is visible.
pub visible: bool,
/// `opacity`, as stored (not clamped). 1 when missing.
pub opacity: f32,
/// `composite-op`, trimmed. Missing means `svg:src-over`.
pub composite_op: Option<String>,
/// `edit-locked`.
pub edit_locked: bool,
/// `alpha-preserve`.
pub alpha_preserve: bool,
}
impl Default for Props {
fn default() -> Props {
Props { name: None, visible: true, opacity: 1.0, composite_op: None, edit_locked: false, alpha_preserve: false }
}
}
/// A `<layer>`: one image at a position.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Layer {
pub props: Props,
/// `x`, `y`: where the image's top-left pixel sits (fractions are rounded).
pub x: i32,
pub y: i32,
/// `src`: the archive entry of the layer's image, trimmed.
pub src: Option<String>,
}
/// A `<stack>`: a group.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Stack {
pub props: Props,
/// `isolation`, trimmed: `isolate` or `auto`. See [`Image::explicit_group_isolation`].
pub isolation: Option<String>,
/// The children, topmost first as the file lists them.
pub children: Vec<Node>,
}
/// An element of a stack.
#[derive(Clone, Debug, PartialEq)]
pub enum Node {
Layer(Layer),
Stack(Stack),
/// An element that is neither (`<text>`, ...): its tag and `name` attribute. Not written.
Other {
tag: String,
name: Option<String>,
},
}
/// The `<image>` root of `stack.xml`.
#[derive(Clone, Debug, PartialEq)]
pub struct Image {
/// `version`, as written.
pub version: Option<String>,
/// Canvas size in pixels (`w`, `h`), 1 to [`MAX_SIDE`].
pub width: u32,
pub height: u32,
/// `xres`, `yres` in pixels per inch: 72 when `xres` is missing, `yres` defaults to `xres`.
pub xres: f64,
pub yres: f64,
/// The children of the root `<stack>`, topmost first. The root stack's own attributes are
/// not read.
pub stack: Vec<Node>,
}
/// A number attribute; a missing one is `default`, an unparsable one an error.
fn num(el: &El, name: &str, default: f64) -> Result<f64> {
match el.attr(name) {
None => Ok(default),
Some(v) => v.trim().parse::<f64>().ok().filter(|v| v.is_finite()).ok_or_else(|| invalid(format!("invalid {name} attribute `{v}`"))),
}
}
fn int(el: &El, name: &str) -> Result<i32> {
let v = num(el, name, 0.0)?.round();
if v.abs() > f64::from(MAX_SIDE) * 4.0 {
return Err(invalid(format!("{name} offset {v} is out of range")));
}
Ok(v as i32)
}
fn flag(el: &El, name: &str) -> bool {
el.attr(name).is_some_and(|v| matches!(v.trim(), "true" | "1"))
}
fn props(el: &El) -> Result<Props> {
Ok(Props {
name: el.attr("name").map(str::to_string),
visible: el.attr("visibility").is_none_or(|v| v.trim() != "hidden"),
opacity: num(el, "opacity", 1.0)? as f32,
composite_op: el.attr("composite-op").map(|v| v.trim().to_string()),
edit_locked: flag(el, "edit-locked"),
alpha_preserve: flag(el, "alpha-preserve"),
})
}
/// The elements of `stack`, walked with an explicit stack: a stack can nest up to
/// [`MAX_XML_DEPTH`] deep, more than a small thread stack can recurse.
fn stack(el: &El, count: &mut usize) -> Result<Vec<Node>> {
struct Frame<'a> {
props: Props,
isolation: Option<String>,
children: Vec<Node>,
rest: std::vec::IntoIter<&'a El>,
}
let mut root = el.elements().collect::<Vec<_>>().into_iter();
let mut frames: Vec<Frame> = Vec::new();
let mut out = Vec::new();
loop {
let next = match frames.last_mut() {
Some(frame) => frame.rest.next(),
None => root.next(),
};
let Some(child) = next else {
let Some(frame) = frames.pop() else { break };
let node = Node::Stack(Stack { props: frame.props, isolation: frame.isolation, children: frame.children });
match frames.last_mut() {
Some(parent) => parent.children.push(node),
None => out.push(node),
}
continue;
};
*count += 1;
if *count > MAX_NODES {
return Err(invalid(format!("more than {MAX_NODES} layers")));
}
match child.name.as_str() {
"layer" => {
let node = Node::Layer(Layer {
props: props(child)?,
x: int(child, "x")?,
y: int(child, "y")?,
src: child.attr("src").map(|s| s.trim().to_string()),
});
match frames.last_mut() {
Some(parent) => parent.children.push(node),
None => out.push(node),
}
}
"stack" => frames.push(Frame {
props: props(child)?,
isolation: child.attr("isolation").map(|s| s.trim().to_string()),
children: Vec::new(),
rest: child.elements().collect::<Vec<_>>().into_iter(),
}),
other => {
let node = Node::Other { tag: other.to_string(), name: child.attr("name").map(str::to_string) };
match frames.last_mut() {
Some(parent) => parent.children.push(node),
None => out.push(node),
}
}
}
}
Ok(out)
}
impl Image {
/// Reads `stack.xml`.
pub fn parse(xml: &[u8]) -> Result<Image> {
if std::str::from_utf8(xml).is_err() {
return Err(invalid("stack.xml is not UTF-8"));
}
let options = craft_xml::Options {
doctype: craft_xml::Doctype::Reject,
limits: craft_xml::Limits { max_input: MAX_STACK_XML, max_depth: MAX_XML_DEPTH, ..craft_xml::Limits::DEFAULT },
..craft_xml::Options::local().strict()
};
let image = options.parse(xml).map_err(|e| invalid(format!("stack.xml: {e}")))?;
if image.name != "image" {
return Err(invalid("stack.xml has no <image> root"));
}
let side = |attr: &str| -> Result<u32> {
let v = num(&image, attr, 0.0)?;
if !(1.0..=f64::from(MAX_SIDE)).contains(&v) || v.fract() != 0.0 {
return Err(invalid(format!("image {attr} {v} must be a whole number of pixels from 1 to {MAX_SIDE}")));
}
Ok(v as u32)
};
let (width, height) = (side("w")?, side("h")?);
if (width as usize).saturating_mul(height as usize).saturating_mul(8) > MAX_PIXEL_BYTES {
return Err(invalid("the canvas exceeds the 1 GiB pixel limit"));
}
let root = image.child("stack").ok_or_else(|| invalid("stack.xml has no root <stack>"))?;
let nodes = stack(root, &mut 0)?;
let xres = num(&image, "xres", 72.0)?;
let yres = num(&image, "yres", xres)?;
Ok(Image { version: image.attr("version").map(str::to_string), width, height, xres, yres, stack: nodes })
}
/// Does the file's version make group isolation explicit? OpenRaster 0.0.6 defaults to
/// isolated groups and makes `isolation="auto"` pass-through whatever the group's
/// `composite-op`. Older files (and ones with no or an unrecognised version) leave it to the
/// reader, by convention: a group passes through unless it says `isolate` or has a
/// composite operation other than `svg:src-over`. The numeric core is compared, not the
/// version string.
pub fn explicit_group_isolation(&self) -> bool {
let Some(core) = self.version.as_deref().and_then(|v| v.trim().split(['-', '+']).next()) else { return false };
let mut parts = core.split('.');
let number = |part: Option<&str>| part.and_then(|s| s.parse::<u32>().ok());
match (number(parts.next()), number(parts.next()), number(parts.next()), parts.next()) {
(Some(major), Some(minor), Some(patch), None) => [major, minor, patch] >= [0, 0, 6],
_ => false,
}
}
/// `stack.xml` for this image: `version` (or [`VERSION`]), the canvas, the resolution, and
/// the layers and stacks with every attribute of [`Props`]. A stack with no `isolation`
/// is written `isolate`; [`Node::Other`] is left out.
pub fn to_xml(&self) -> String {
let mut xml = format!(
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<image version=\"{}\" w=\"{}\" h=\"{}\" xres=\"{}\" yres=\"{}\"><stack>",
craft_xml::esc_attr(self.version.as_deref().unwrap_or(VERSION)),
self.width,
self.height,
self.xres,
self.yres
);
// Iterative, so a tree built by hand may be as deep as its builder made it.
let mut open: Vec<std::slice::Iter<'_, Node>> = vec![self.stack.iter()];
while let Some(level) = open.last_mut() {
match level.next() {
Some(Node::Layer(l)) => {
xml.push_str("<layer");
push_props(&mut xml, &l.props);
if let Some(src) = &l.src {
xml.push_str(&format!(" src=\"{}\"", craft_xml::esc_attr(src)));
}
xml.push_str(&format!(" x=\"{}\" y=\"{}\"/>", l.x, l.y));
}
Some(Node::Stack(s)) => {
xml.push_str("<stack");
push_props(&mut xml, &s.props);
xml.push_str(&format!(" isolation=\"{}\">", craft_xml::esc_attr(s.isolation.as_deref().unwrap_or("isolate"))));
open.push(s.children.iter());
}
Some(Node::Other { .. }) => {}
None => {
open.pop();
xml.push_str(if open.is_empty() { "</stack></image>\n" } else { "</stack>" });
}
}
}
xml
}
}
fn push_props(xml: &mut String, p: &Props) {
if let Some(name) = &p.name {
xml.push_str(&format!(" name=\"{}\"", craft_xml::esc_attr(name)));
}
xml.push_str(&format!(" visibility=\"{}\" opacity=\"{}\"", if p.visible { "visible" } else { "hidden" }, p.opacity));
xml.push_str(&format!(" composite-op=\"{}\"", craft_xml::esc_attr(p.composite_op.as_deref().unwrap_or("svg:src-over"))));
if p.edit_locked {
xml.push_str(" edit-locked=\"true\"");
}
if p.alpha_preserve {
xml.push_str(" alpha-preserve=\"true\"");
}
}
/// An open OpenRaster archive: the parsed `stack.xml` and access to the archive's entries.
pub struct Archive<'a> {
zip: craft_zip::Archive<'a>,
image: Image,
}
impl<'a> Archive<'a> {
/// Opens the archive, checks its `mimetype` and reads `stack.xml`.
pub fn open(bytes: &'a [u8]) -> Result<Archive<'a>> {
Self::open_with_total(bytes, MAX_TOTAL)
}
/// [`Archive::open`], allowing the entries read from the archive to expand to
/// `max_total_bytes` together ([`MAX_TOTAL`] is the default).
pub(crate) fn open_with_total(bytes: &'a [u8], max_total_bytes: u64) -> Result<Archive<'a>> {
let mut zip = craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes }).map_err(zip_error)?;
// `zip` keeps one entry of a repeated name; which one the writer meant is not known.
if zip.has_duplicate_names() {
return Err(invalid("two entries of the archive share a name"));
}
let mime = read(&mut zip, "mimetype", 256)?.ok_or_else(|| invalid("the archive has no mimetype"))?;
if mime.trim_ascii() != MIMETYPE {
return Err(invalid("the archive's mimetype is not image/openraster"));
}
let xml = read(&mut zip, "stack.xml", MAX_STACK_XML)?.ok_or_else(|| invalid("the archive has no stack.xml"))?;
Ok(Archive { zip, image: Image::parse(&xml)? })
}
/// The document's `<image>`.
pub fn image(&self) -> &Image {
&self.image
}
/// An entry by name (a layer's `src`, `mergedimage.png`, `Thumbnails/thumbnail.png`),
/// refusing one that inflates past `max` bytes ([`MAX_ENTRY`] for a layer image). `None`
/// when the archive has no such entry.
pub fn entry(&mut self, name: &str, max: usize) -> Result<Option<Vec<u8>>> {
read(&mut self.zip, name, max)
}
}
fn read(zip: &mut craft_zip::Archive<'_>, name: &str, max: usize) -> Result<Option<Vec<u8>>> {
zip.read(name, max as u64).map_err(zip_error)
}
fn write_error(e: craft_zip::Error) -> Error {
match e {
craft_zip::Error::Write(m) => Error::Write(m),
e => Error::Write(e.to_string()),
}
}
fn zip_error(e: craft_zip::Error) -> Error {
match e {
craft_zip::Error::NotZip(m) => invalid(m),
craft_zip::Error::EntryTooLarge { name, limit } => invalid(format!("{name}: larger than {limit} bytes")),
e => invalid(e.to_string()),
}
}
/// Writes an OpenRaster archive. Entries are stored (PNG is already compressed), in the order
/// they are added, after the `mimetype`.
pub struct Writer {
zip: craft_zip::Writer,
failed: Option<Error>,
}
impl Default for Writer {
fn default() -> Writer {
Writer::new()
}
}
impl Writer {
/// An archive holding the `mimetype`: it must be the first entry, stored, so the type is
/// readable at a fixed offset.
pub fn new() -> Writer {
let mut w = Writer { zip: craft_zip::Writer::new(), failed: None };
w.failed = w.add("mimetype", MIMETYPE).err();
w
}
/// Adds an entry: a layer image under the name its [`Layer::src`] gives, `mergedimage.png`
/// (the whole image, which the specification requires) or `Thumbnails/thumbnail.png` (at
/// most 256 pixels a side, also required).
pub fn add(&mut self, name: &str, data: &[u8]) -> Result<()> {
self.zip.add(name, data, craft_zip::Compression::Stored).map_err(write_error)
}
/// Adds `stack.xml` for `image`.
pub fn add_stack(&mut self, image: &Image) -> Result<()> {
self.add("stack.xml", image.to_xml().as_bytes())
}
/// The finished archive.
pub fn finish(self) -> Result<Vec<u8>> {
if let Some(e) = self.failed {
return Err(e);
}
self.zip.finish().map_err(write_error)
}
}