epub-tools/docs/ARCHITECTURE.md

Architecture

The app is a relocatable static React application using the Toolbox shell and contract. EPUB work is divided into small TypeScript modules under src/epub/:

• archive.ts applies ZIP/path/entry/ratio limits and opens the container with zip.js.
• xml.ts, package.ts, and paths.ts decode bounded XML, reject DTD/entity input, parse OPF/navigation/NCX, and resolve package-relative references without traversal.
• validation.ts performs bounded package and cross-document diagnostics and reports skipped scope.
• reader.ts sanitizes content with DOMPurify, neutralizes navigation and CSS URLs, resolves bounded local images, injects a restrictive iframe CSP, and returns object URLs with an explicit revocation lifecycle.
• export.ts patches Dublin Core metadata and streams entries into a fresh normalized EPUB. It also produces JSON, cover, chapter, and reading-order text exports.

zip.js receives a lazy browser BlobReader, performs CRC checks when entry data is read, and can use web workers. React retains one open reader and closes the previous reader when a new book replaces it. The original File is immutable; all changes exist only in staged React state or a newly downloaded Blob.

The safe reader uses both sanitization and an iframe without sandbox permissions. Its srcdoc adds default-src 'none' and permits only inline styles plus local data/blob image/font/media URLs. Publisher stylesheet links are intentionally removed in v0.1.