Files
craft-libs/crates/epub/src/read.rs
T
Dylan M. Taylorandskylar taylor-barrick c88555e4a5 craft-epub: table of contents reading, EPUB 2 NCX writing, encryption.xml (#962)
* craft-zip: ZIP preflight, bounded entry read and Budget (from craft-archive, #129)

The ZIP half of the craft-archive proposal (#126, #129): an allocation-free check of the end
records and central directory that runs before a ZIP reader indexes the archive, a bounded
entry read that distrusts the declared size, and the named Budget both charge. The XML half
of #129 is not carried: craft-xml bounds XML now.

* craft-zip: Archive (entry-count guard, duplicate names, budgeted reads) and Writer

check_entry_count is craft-opc's guard: the declared entry count, ZIP64 included, checked on
the raw bytes before zip parses the central directory. Archive reads entries within a per-entry
limit and a total Budget through read_entry. Duplicate names are found by counting the central
directory headers against the entries zip kept. Writer is craft-opc's ZipOut: stored or deflated
entries, ZIP64 for large ones, one fixed timestamp.

* craft-idml, craft-epub: read and write through craft-zip

Both crates drop their own bounded ZIP reads and zip writers. They gain the entry-count check
before the archive is indexed (ZIP64 included) and archives whose bytes depend only on their
content (one fixed timestamp).

* craft-epub: table of contents (navigation document, NCX), EPUB 2 NCX writing, encryption.xml

Epub::toc reads the EPUB 3 navigation document's toc, else the EPUB 2 NCX, as entries with a
label, target and level, walked without recursion and capped. Book::ncx also writes toc.ncx for
older reading systems. Epub::encryption lists what META-INF/encryption.xml says is encrypted and
tells font obfuscation from DRM.

---------

Co-authored-by: skylar taylor-barrick <hi@skylar.cc>
2026-11-11 20:07:35 -05:00

326 lines
14 KiB
Rust

//! An EPUB 2 or 3 package, read: container, package document, and bounded entry reads.
use std::collections::HashMap;
use craft_xml::{El, Local, Options};
use crate::Error;
/// What the reader refuses to exceed.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Limits {
/// Most entries the archive may hold. Default 100,000.
pub max_entries: usize,
/// Most bytes one entry may expand to. Default 64 MiB.
pub max_entry_bytes: u64,
/// Most bytes all the entries read from one package may expand to together (many entries
/// with small declared sizes can't add up past this). Default 256 MiB.
pub max_total_bytes: u64,
/// Most manifest items kept; further ones are ignored. Default 10,000.
pub max_manifest: usize,
/// Most spine items kept; further ones are ignored. Default 10,000.
pub max_spine: usize,
}
impl Limits {
pub const DEFAULT: Limits =
Limits { max_entries: 100_000, max_entry_bytes: 64 << 20, max_total_bytes: 256 << 20, max_manifest: 10_000, max_spine: 10_000 };
}
impl Default for Limits {
fn default() -> Limits {
Limits::DEFAULT
}
}
/// A manifest item.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Item {
pub id: String,
/// The `href` as written.
pub href: String,
/// The archive entry the `href` names: resolved against the package document, decoded,
/// fragment removed.
pub path: String,
pub media_type: String,
/// EPUB 3 `properties` (`nav`, `cover-image`, `mathml`, …), space separated.
pub properties: String,
}
impl Item {
pub fn has_property(&self, property: &str) -> bool {
self.properties.split_ascii_whitespace().any(|p| p == property)
}
}
/// A spine entry.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SpineItem {
pub idref: String,
/// `linear="no"`: auxiliary content, outside the main reading order.
pub linear: bool,
/// The archive entry of the manifest item it refers to; `None` when no item has that id.
pub path: Option<String>,
}
/// The package document (OPF).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Package {
/// The `version` attribute (`2.0`, `3.0`).
pub version: String,
/// The first `dc:title`.
pub title: String,
/// Every `dc:creator`, in order.
pub creators: Vec<String>,
/// The first `dc:language` that is not blank.
pub language: Option<String>,
/// The `dc:identifier` the package's `unique-identifier` names, else the first.
pub identifier: Option<String>,
/// `dcterms:modified` (EPUB 3).
pub modified: Option<String>,
/// `rendition:layout` is `pre-paginated`: a fixed-layout book.
pub pre_paginated: bool,
pub manifest: Vec<Item>,
pub spine: Vec<SpineItem>,
/// The archive entry of the EPUB 2 NCX the spine's `toc` attribute names.
pub ncx: Option<String>,
/// The id of the EPUB 2 cover image (`<meta name="cover">`).
cover_id: Option<String>,
}
impl Package {
/// The archive entries of the spine, in reading order, for the items the manifest has.
pub fn spine_paths(&self) -> impl Iterator<Item = &str> {
self.spine.iter().filter_map(|s| s.path.as_deref())
}
/// The EPUB 3 navigation document.
pub fn nav(&self) -> Option<&Item> {
self.manifest.iter().find(|i| i.has_property("nav"))
}
/// The cover image: the item with the `cover-image` property, else the one an EPUB 2
/// `<meta name="cover">` names.
pub fn cover_image(&self) -> Option<&Item> {
let by_id = || self.cover_id.as_ref().and_then(|id| self.manifest.iter().find(|i| &i.id == id));
self.manifest.iter().find(|i| i.has_property("cover-image")).or_else(by_id)
}
}
/// The directory of an archive path (`a/b/c.xhtml` → `a/b`; `c.xhtml` → `""`).
pub fn dir_of(path: &str) -> &str {
path.rsplit_once('/').map_or("", |(dir, _)| dir)
}
/// The archive entry a relative `href` names from a file in `base_dir`: `.` and `..` segments
/// applied, percent escapes decoded, fragment and query removed.
///
/// A hostile `../../../etc/passwd` cannot leave the archive: the result only ever names an
/// archive entry, never a file system path, and `..` stops at the archive's root.
pub fn resolve(base_dir: &str, href: &str) -> String {
let href = href.split(['#', '?']).next().unwrap_or("");
let href = percent_decode(href);
let mut parts: Vec<&str> = if href.starts_with('/') { Vec::new() } else { base_dir.split('/').filter(|s| !s.is_empty()).collect() };
for seg in href.split('/') {
match seg {
"" | "." => {}
".." => {
parts.pop();
}
s => parts.push(s),
}
}
parts.join("/")
}
/// Decode `%XX` escapes; an invalid escape, or a result that is not UTF-8, is kept as written.
fn percent_decode(s: &str) -> String {
let b = s.as_bytes();
let hex = |i: usize| b.get(i).and_then(|c| char::from(*c).to_digit(16));
let mut out = Vec::with_capacity(b.len());
let mut i = 0;
while let Some(&c) = b.get(i) {
if c == b'%'
&& let (Some(h), Some(l)) = (hex(i + 1), hex(i + 2))
{
out.push((h * 16 + l) as u8);
i += 3;
} else {
out.push(c);
i += 1;
}
}
String::from_utf8(out).unwrap_or_else(|_| s.to_string())
}
/// Both required documents must be well formed: a lenient read would take a container or package
/// document cut off after its useful content for a complete one, and give half a book.
pub(crate) fn parse_xml(part: &str, xml: &[u8], limits: &Limits) -> Result<El, Error> {
let xml_limits = craft_xml::Limits { max_input: usize::try_from(limits.max_entry_bytes).unwrap_or(usize::MAX), ..craft_xml::Limits::DEFAULT };
Options::local().strict().with_limits(xml_limits).parse(xml).map_err(|e| Error::Part { part: part.to_string(), msg: e.to_string() })
}
/// The package document's path from `META-INF/container.xml` (the first `rootfile`'s
/// `full-path`). `Ok(None)`: well formed, but it names none.
pub fn parse_container(xml: &[u8]) -> Result<Option<String>, Error> {
let root = parse_xml("META-INF/container.xml", xml, &Limits::DEFAULT)?;
Ok(root.find(Local("rootfile")).and_then(|r| r.attr("full-path")).filter(|p| !p.is_empty()).map(str::to_string))
}
/// The package document `xml`, its hrefs resolved against `opf_dir` (the directory of the
/// package document in the archive).
pub fn parse_package(xml: &[u8], opf_dir: &str, limits: &Limits) -> Result<Package, Error> {
let root = parse_xml("package document", xml, limits)?;
let mut pkg = Package { version: root.attr("version").unwrap_or_default().to_string(), ..Package::default() };
let unique = root.attr("unique-identifier");
if let Some(meta) = root.child("metadata") {
// EPUB 2 packages may wrap the Dublin Core elements in `dc-metadata`.
let all = || meta.elements().flat_map(|e| if e.is("dc-metadata") { e.elements().collect::<Vec<_>>() } else { vec![e] });
let texts = |name: &'static str| all().filter(move |e| e.is(name)).map(|e| e.deep_text().trim().to_string());
pkg.title = texts("title").next().unwrap_or_default();
pkg.creators = texts("creator").filter(|c| !c.is_empty()).take(limits.max_manifest).collect();
pkg.language = texts("language").find(|l| !l.is_empty());
let ids = || all().filter(|e| e.is("identifier"));
let chosen = ids().find(|e| unique.is_some() && e.attr("id") == unique).or_else(|| ids().next());
pkg.identifier = chosen.map(|e| e.deep_text().trim().to_string()).filter(|i| !i.is_empty());
for m in all().filter(|e| e.is("meta")) {
let text = || m.deep_text().trim().to_string();
match (m.attr("property"), m.attr("name")) {
(Some("dcterms:modified"), _) if pkg.modified.is_none() => pkg.modified = Some(text()),
(Some("rendition:layout"), _) => pkg.pre_paginated = text() == "pre-paginated",
(_, Some("cover")) if pkg.cover_id.is_none() => pkg.cover_id = m.attr("content").map(str::to_string),
_ => {}
}
}
}
let attr = |e: &El, name: &str| e.attr(name).unwrap_or_default().to_string();
for item in root.child("manifest").into_iter().flat_map(|m| m.children("item")).take(limits.max_manifest) {
let (Some(id), Some(href)) = (item.attr("id"), item.attr("href")) else { continue };
pkg.manifest.push(Item {
id: id.to_string(),
href: href.to_string(),
path: resolve(opf_dir, href),
media_type: attr(item, "media-type"),
properties: attr(item, "properties"),
});
}
// The first item with an id wins, as it does when the id is looked up in the document.
let mut by_id: HashMap<&str, &str> = HashMap::new();
for item in &pkg.manifest {
by_id.entry(&item.id).or_insert(&item.path);
}
if let Some(spine) = root.child("spine") {
pkg.ncx = spine.attr("toc").and_then(|id| by_id.get(id)).map(ToString::to_string);
for itemref in spine.children("itemref").take(limits.max_spine) {
let Some(idref) = itemref.attr("idref") else { continue };
let path = by_id.get(idref).map(ToString::to_string);
pkg.spine.push(SpineItem { idref: idref.to_string(), linear: itemref.attr("linear") != Some("no"), path });
}
}
Ok(pkg)
}
/// An open EPUB package. Entries are decompressed only when asked for, within the byte budgets
/// of its [`Limits`].
pub struct Epub<'a> {
zip: craft_zip::Archive<'a>,
limits: Limits,
/// The archive path of the package document.
pub opf_path: String,
pub package: Package,
}
impl<'a> Epub<'a> {
/// Opens `bytes` with [`Limits::DEFAULT`].
pub fn open(bytes: &'a [u8]) -> Result<Self, Error> {
Self::open_with(bytes, Limits::DEFAULT)
}
/// Reads the container and the package document. The `mimetype` entry is not required:
/// packages without one, or with it compressed, are common.
pub fn open_with(bytes: &'a [u8], limits: Limits) -> Result<Self, Error> {
let zip =
craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries as u64, max_total_bytes: limits.max_total_bytes })
.map_err(|e| match e {
craft_zip::Error::TooManyEntries { declared, limit } => Error::TooManyEntries {
found: usize::try_from(declared).unwrap_or(usize::MAX),
limit: usize::try_from(limit).unwrap_or(usize::MAX),
},
e => Error::NotEpub(e.to_string()),
})?;
let mut epub = Epub { zip, limits, opf_path: String::new(), package: Package::default() };
let container = epub.read("META-INF/container.xml")?.ok_or_else(|| Error::NotEpub("META-INF/container.xml is missing".into()))?;
let opf_path = parse_container(&container)?.ok_or_else(|| Error::NotEpub("container.xml names no package document".into()))?;
// The container gives a path from the archive's root; resolving it also drops a leading `/`.
let opf_path = resolve("", &opf_path);
let opf = epub.read(&opf_path)?.ok_or_else(|| Error::NotEpub(format!("package document {opf_path} is missing")))?;
epub.package = parse_package(&opf, dir_of(&opf_path), &limits).map_err(|e| match e {
Error::Part { msg, .. } => Error::Part { part: opf_path.clone(), msg },
e => e,
})?;
epub.opf_path = opf_path;
Ok(epub)
}
/// Does the archive have an entry `path`?
pub fn contains(&self, path: &str) -> bool {
self.zip.contains(path)
}
/// The bytes of archive entry `path`, or `None` when the archive has no such entry. An entry
/// past the limits is an error, and so is one that expands to more than it declared.
pub fn read(&mut self, path: &str) -> Result<Option<Vec<u8>>, Error> {
if path.ends_with('/') {
return Ok(None);
}
let limit = self.limits.max_entry_bytes.min(self.zip.budget().remaining());
self.zip.read(path, self.limits.max_entry_bytes).map_err(|e| match e {
craft_zip::Error::EntryTooLarge { .. } | craft_zip::Error::BudgetSpent { .. } => Error::TooLarge { part: path.to_string(), limit },
e => Error::Part { part: path.to_string(), msg: e.to_string() },
})
}
/// [`Epub::read`] for what a file of the package refers to: `href` as written in the file at
/// archive path `from` (an image's `src` in a content document).
pub fn read_href(&mut self, from: &str, href: &str) -> Result<Option<Vec<u8>>, Error> {
let path = resolve(dir_of(from), href);
if path.is_empty() { Ok(None) } else { self.read(&path) }
}
/// The table of contents: the EPUB 3 navigation document's `toc`, else the EPUB 2 NCX.
/// Empty when the package has neither, or the one it names is missing.
pub fn toc(&mut self) -> Result<Vec<crate::TocEntry>, Error> {
let nav = self.package.nav().map(|i| i.path.clone());
if let Some(path) = nav
&& let Some(xml) = self.read(&path)?
{
let toc = crate::parse_nav(&xml, &path)?;
if !toc.is_empty() {
return Ok(toc);
}
}
match self.package.ncx.clone() {
Some(path) => match self.read(&path)? {
Some(xml) => crate::parse_ncx(&xml, &path),
None => Ok(Vec::new()),
},
None => Ok(Vec::new()),
}
}
/// What `META-INF/encryption.xml` says is encrypted; empty when the package has none. A
/// resource listed here cannot be used as it is read: fonts are usually only obfuscated
/// ([`crate::Encrypted::is_font_obfuscation`]), anything else is DRM.
pub fn encryption(&mut self) -> Result<Vec<crate::Encrypted>, Error> {
match self.read("META-INF/encryption.xml")? {
Some(xml) => crate::parse_encryption(&xml),
None => Ok(Vec::new()),
}
}
/// Bytes the entries still to be read may expand to.
pub fn budget_left(&self) -> u64 {
self.zip.budget().remaining()
}
}