Public: anyone can read this; the crew can change it.

An .epub file opens as its title, author and chapter list #13220

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/13210-an-epub-file-opens-as-its-title-author-a → main 13 commits fork 3 threads · 3 unresolved

  • Merged. torque/13210-an-epub-file-opens-as-its-title-author-a was merged into main as 3a8bdf2.

Review

Sign in to review this change.
12 files changed +463 −5
docs/features/README.md +1
@@ -305,6 +305,7 @@ Read with the guide page [Your apps](../guide-your-apps.md).
305305 - [A `.env.example` opens as the variables an app needs](file-env.md)
306306 - [A `.sql` file opens as its schema](file-sql.md)
307307 - [A `Dockerfile` opens as its stages](file-dockerfile.md)
308 - [An .epub opens as its title, author and chapters](file-epub.md)
308309 - [A `Makefile` opens as its targets](file-makefile.md)
309310 - [A `package.json` opens as its manifest](file-package-json.md)
310311 - [A compose file opens as its services](file-compose.md)
docs/features/file-epub.md added +11
@@ -0,0 +1,11 @@
1 # An .epub opens as its title, author and chapters
2
3 An `.epub` opens on the blob page as facts instead of a binary. Source and Raw stay one tap away.
4
5 - **Facts:** title, author(s) and language from the OPF; the chapters in reading order (`META-INF/container.xml` names the OPF, its spine gives the order, the nav document or NCX gives the titles; a chapter with no title shows its file name); and the first chapter's text as a plain excerpt of at most 2,000 characters.
6 - **Never rendered:** chapter XHTML is stripped to text (tags, scripts, styles and comments dropped) and escaped; nothing from the book runs or loads.
7 - **Caps:** read through the same zip floor as `.docx`: at most 1,000 parts, 64 MB unpacked, 2 MB per XML part; at most 1,000 chapters listed. Files over 20 MB keep Source.
8 - **Hostile files:** a path that climbs out of the zip is never read; a book with no readable OPF shows a note and what the zip allows; a zip bomb or a file that is not a zip shows its source. Nothing throws.
9 - No script, no new CSS, no dependency. The terminal workspace opens it the same way (`src/tui/screens/workspace_office.ts`, through `readBook` and the page's gate): title, author, language, chapters and the excerpt as rows.
10
11 Code: `src/web/render/epub.ts`, `src/web/render/kinds.ts`. Test: `test/render-epub.test.ts`, `test/tui-office.test.ts`, `test/fuzz-renderers.test.ts`.
docs/features/file-kinds.md +1
@@ -19,6 +19,7 @@ The forge draws a file on its page when its kind is below and it is within the s
1919 - **Word document**, drawn up to 10 MB: `.docx`
2020 - **Slides**, drawn up to 10 MB: `.pptx`
2121 - **Layered image**, drawn up to 20 MB: `.ora`
22 - **EPUB book**, drawn up to 20 MB: `.epub`
2223 - **Font**, drawn up to 20 MB: `.ttf`, `.otf`, `.woff`, `.woff2`
2324 - **Photoshop**, drawn up to 4 GB: `.psd`
2425 - **Config**, drawn up to 1 MB: `.json`, `.jsonc`, `.yaml`, `.yml`, `.toml`, `.conf`
scripts/kinds-guide.ts +1 −1
@@ -18,7 +18,7 @@ export const NAMES: Readonly<Record<FileKind, string>> = {
1818 excalidraw: "Excalidraw", step: "STEP model", sarif: "SARIF report", lcov: "Coverage (lcov)", junit: "JUnit report",
1919 opml: "OPML", feed: "RSS or Atom feed", env: "Env example", openapi: "OpenAPI", package: "package.json", makefile: "Makefile",
2020 dockerfile: "Dockerfile", workflow: "GitHub workflow", compose: "Compose file", sql: "SQL", graphql: "GraphQL",
21 mbox: "Mailbox", proto: "Protocol Buffers", ini: "INI or properties", rtf: "Rich text", xml: "XML", text: "Other text", binary: "Other binary",
21 epub: "EPUB book", mbox: "Mailbox", proto: "Protocol Buffers", ini: "INI or properties", rtf: "Rich text", xml: "XML", text: "Other text", binary: "Other binary",
2222 };
2323
2424 /** 1_000_000 as `1 MB`; 4_000_000_000 as `4 GB`; no cap as `none: download only`. */
src/tui/screens/workspace_office.ts +17 −4
@@ -1,18 +1,19 @@
11 /**
2 * A .docx, .pptx or .ora in the terminal workspace, read the way the page
3 * reads it: the same `readDocument`, `readSlides` and `readStack`, drawn as a
2 * A .docx, .pptx, .ora or .epub in the terminal workspace, read the way the page
3 * reads it: the same `readDocument`, `readSlides`, `readStack` and `readBook`, drawn as a
44 * table of plain text. The same gate too: the name and the bytes must say so
55 * (`fileKind`), and a file that cannot be read answers its reason.
66 *
77 * `officeView(path, body)` answers a table, a sentence saying why not (the
88 * workspace shows that as its note), or `null` for a file that is not one of
9 * the three: the workspace keeps its binary note.
9 * the four: the workspace keeps its binary note.
1010 */
1111
1212 import { fileKind, HEAD_BYTES, RENDER_CAP } from "../../web/render/kinds.ts";
1313 import { readDocument } from "../../web/render/docx.ts";
1414 import { readSlides } from "../../web/render/pptx.ts";
1515 import { readStack } from "../../web/render/ora.ts";
16 import { readBook } from "../../web/render/epub.ts";
1617 import type { Table } from "../../text/csv.ts";
1718
1819 const table = (header: string[], rows: string[][]): Table => ({
@@ -25,7 +26,7 @@ const table = (header: string[], rows: string[][]): Table => ({
2526
2627 export function officeView(path: string, body: Uint8Array): Table | string | null {
2728 const kind = fileKind(path, body.subarray(0, HEAD_BYTES));
28 if (kind !== "document" && kind !== "slides" && kind !== "layers") return null;
29 if (kind !== "document" && kind !== "slides" && kind !== "layers" && kind !== "epub") return null;
2930 // The page's cap: past it the page keeps the source view, and so does this.
3031 if (body.length > RENDER_CAP[kind])
3132 return `This file is over ${RENDER_CAP[kind] / 1_000_000} MB, too large to open here. Download it instead.`;
@@ -40,6 +41,18 @@ export function officeView(path: string, body: Uint8Array): Table | string | nul
4041 if ("error" in deck) return deck.error;
4142 return table(["Slide", "Title"], deck.slides.map((s) => [String(s.number), s.title === "" ? "(no title)" : s.title]));
4243 }
44 if (kind === "epub") {
45 const book = readBook(body);
46 if ("error" in book) return book.error;
47 const rows: string[][] = [];
48 if (book.title !== "") rows.push(["Title", book.title]);
49 if (book.authors.length > 0) rows.push(["Author", book.authors.join(", ")]);
50 if (book.language !== "") rows.push(["Language", book.language]);
51 book.chapters.forEach((c, i) => rows.push([`Chapter ${i + 1}`, c.title]));
52 if (book.note !== "") rows.push(["Note", book.note]);
53 for (const line of book.excerpt.split("\n")) if (line !== "") rows.push(["Excerpt", line]);
54 return table(["Item", "Text"], rows);
55 }
4356 if (kind === "layers") {
4457 const stack = readStack(body);
4558 if ("error" in stack) return stack.error;
src/web/render/epub.ts added +228
@@ -0,0 +1,228 @@
1 /**
2 * An .epub as facts: title, author, language, the chapters in reading order
3 * and a plain-text excerpt of the first one. Read through the shared zip
4 * floor (`office-zip.ts`): `META-INF/container.xml` names the OPF, the OPF's
5 * spine gives the order, and the nav document (EPUB 3) or the NCX (EPUB 2)
6 * gives the titles. XHTML is never rendered: it is stripped to text and
7 * escaped. Damage or hostility shows the facts that could be read; a file
8 * that is not a zip at all is `{ error }`: the source view. Never throws.
9 */
10
11 import { escapeHtml, html, raw } from "../html.ts";
12 import { fileSize } from "../ui.ts";
13 import { elements, openPackage, tags, tidy, unescapeXml, xmlAttr } from "./office-zip.ts";
14 import type { Rendered, RenderInput } from "./renderers.ts";
15
16 /** The most characters of the first chapter shown. */
17 export const EXCERPT = 2_000;
18 /** The most chapters listed. */
19 export const CHAPTERS = 1_000;
20 /** The most of any one XML part read (the OPF, the nav, a chapter). */
21 const PART = 2 * 1024 * 1024;
22
23 export interface Chapter {
24 readonly href: string;
25 readonly title: string;
26 }
27
28 export interface Book {
29 readonly title: string;
30 readonly authors: readonly string[];
31 readonly language: string;
32 readonly chapters: readonly Chapter[];
33 /** Chapters in the spine, shown or not. */
34 readonly total: number;
35 readonly excerpt: string;
36 /** Why some facts are missing, or "". */
37 readonly note: string;
38 }
39
40 const NAMED: Record<string, string> = { nbsp: " ", mdash: "—", ndash: "–", hellip: "…", rsquo: "’", lsquo: "‘", rdquo: "”", ldquo: "“" };
41 const text = (s: string): string => unescapeXml(s.replace(/&([a-z]+);/g, (m, n: string) => NAMED[n] ?? m));
42 const BLOCK = new Set(["p", "div", "br", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6", "section", "blockquote", "hr"]);
43

toLowerCase() can change string length, so indices from lower do not match src after such a character. Fix as in the review body.

44 /**
45 * Markup as plain text, in one forward pass (`indexOf`, never back): tags
46 * dropped, block tags as line breaks, `<script>`, `<style>` and `<head>`
47 * dropped with their content, an unclosed `<` ends the text.
48 */
49 export function stripMarkup(xhtml: string, max = EXCERPT): string {
50 const src = xhtml.slice(0, PART);
51 let out = "";
52 let i = 0;
53 while (i < src.length && out.length < max * 2) {
54 const lt = src.indexOf("<", i);
55 if (lt < 0) {
56 out += src.slice(i);
57 break;
58 }
59 out += src.slice(i, lt);
60 const gt = src.indexOf(">", lt);
61 if (gt < 0) break;
62 const name = /^<\/?([a-z][a-z0-9]*)/.exec(src.slice(lt, lt + 20).toLowerCase())?.[1] ?? "";
63 i = gt + 1;
64 if (src.startsWith("<!--", lt)) {
65 const end = src.indexOf("-->", lt + 4);
66 if (end < 0) break;
67 i = end + 3;
68 } else if ((name === "script" || name === "style" || name === "head") && src[lt + 1] !== "/") {
69 // Case-insensitive search on `src` itself: lowercasing a copy can change its length.
70 const closer = new RegExp(`</${name}`, "gi");
71 closer.lastIndex = i;
72 const end = closer.exec(src)?.index ?? -1;
73 if (end < 0) break;
74 const close = src.indexOf(">", end);
75 if (close < 0) break;
76 i = close + 1;
77 } else if (BLOCK.has(name)) out += "\n";
78 }
79 return tidy(
80 text(out)
81 .replace(/[ \t\r\f\v]+/g, " ")
82 .replace(/ ?\n ?/g, "\n")
83 .replace(/\n{3,}/g, "\n\n")
84 .trim(),
85 max,
86 );
87 }
88
89 /**
90 * A path inside the zip from a base directory and an href: no fragment, query or escapes; null when
91 * it climbs out.
92 */
93 function resolve(dir: string, href: string): string | null {
94 let h = href.split("#")[0]!.split("?")[0]!;
95 try {
96 h = decodeURIComponent(h);
97 } catch {
98 return null;
99 }
100 if (h === "" || h.startsWith("/") || h.includes("\\") || h.includes("\0")) return null;
101 const parts = (dir + h).split("/");
102 const out: string[] = [];
103 for (const p of parts) {
104 if (p === "" || p === ".") continue;
105 if (p === "..") return null;
106 out.push(p);
107 }
108 return out.join("/");
109 }
110
111 const flat = (s: string): string => tidy(text(s.replace(/<[^>]{0,2000}>/g, " ")).replace(/\s+/g, " ").trim(), 300);
112
113 /** Titles by resolved path, from an EPUB 3 nav document's toc, or an EPUB 2 NCX. */
114 function titles(xml: string, dir: string, ncx: boolean): Map<string, string> {
115 const out = new Map<string, string>();
116 if (ncx) {
117 for (const p of elements(xml, "navPoint")) {
118 let label = "";
119 for (const l of elements(p.body, "navLabel", 1)) label = flat(l.body);
120 for (const c of tags(p.body, "content", 1)) {
121 const path = resolve(dir, xmlAttr(c, "src") ?? "");
122 if (path !== null && label !== "" && !out.has(path)) out.set(path, label);
123 }
124 }
125 return out;
126 }
127 let scope = xml;
128 for (const n of elements(xml, "nav")) {
129 if (/epub:type="[^"]*\btoc\b/.test(n.attrs) || scope === xml) scope = n.body;
130 if (/epub:type="[^"]*\btoc\b/.test(n.attrs)) break;
131 }
132 for (const a of elements(scope, "a")) {
133 const path = resolve(dir, xmlAttr(a.attrs, "href") ?? "");
134 const label = flat(a.body);
135 if (path !== null && label !== "" && !out.has(path)) out.set(path, label);
136 }
137 return out;
138 }
139
140 const NONE: Book = { title: "", authors: [], language: "", chapters: [], total: 0, excerpt: "", note: "" };
141
142 export function readBook(zip: Uint8Array): Book | { readonly error: string } {
143 const pkg = openPackage(zip);
144 if ("error" in pkg) return pkg;
145 const container = pkg.text("META-INF/container.xml", PART);
146 let opfPath: string | null = null;
147 if (container !== null)
148 for (const r of tags(container, "rootfile", 1)) opfPath = resolve("", xmlAttr(r, "full-path") ?? "");
149 const opf = opfPath === null ? null : pkg.text(opfPath, PART);
150 if (opfPath === null || opf === null)
151 return { ...NONE, note: "This file has no readable package document (OPF), so only what the zip itself says is known." };
152 const dir = opfPath.includes("/") ? opfPath.slice(0, opfPath.lastIndexOf("/") + 1) : "";
153
154 const field = (tag: string): string[] => {
155 const out: string[] = [];
156 for (const e of elements(opf, tag, 20)) {
157 const v = flat(e.body);
158 if (v !== "") out.push(v);
159 }
160 return out;
161 };
162 const items = new Map<string, { href: string; props: string }>();
163 for (const a of tags(opf, "item", 20_000)) {
164 const id = xmlAttr(a, "id");
165 const href = xmlAttr(a, "href");
166 if (id !== undefined && href !== undefined && !items.has(id)) items.set(id, { href, props: xmlAttr(a, "properties") ?? "" });
167 }
168 const spine: string[] = [];
169 let tocId: string | undefined;
170 for (const s of tags(opf, "spine", 1)) tocId = xmlAttr(s, "toc");
171 for (const a of tags(opf, "itemref", 20_000)) {
172 const item = items.get(xmlAttr(a, "idref") ?? "");
173 const path = item === undefined ? null : resolve(dir, item.href);
174 if (path !== null) spine.push(path);
175 }
176
177 let names = new Map<string, string>();
178 const nav = [...items.values()].find((i) => /(^|\s)nav(\s|$)/.test(i.props));
179 const ncx = tocId === undefined ? undefined : items.get(tocId);
180 for (const [source, isNcx] of [[nav, false], [ncx, true]] as const) {
181 if (source === undefined || names.size > 0) continue;
182 const at = resolve(dir, source.href);
183 const xml = at === null ? null : pkg.text(at, PART);
184 if (xml !== null) names = titles(xml, at!.includes("/") ? at!.slice(0, at!.lastIndexOf("/") + 1) : "", isNcx);
185 }
186
187 const chapters = spine.slice(0, CHAPTERS).map((path) => ({
188 href: path,
189 title: names.get(path) ?? tidy(path.slice(path.lastIndexOf("/") + 1), 200),
190 }));
191 const first = spine[0];
192 const body = first === undefined ? null : pkg.text(first, PART);
193 return {
194 title: field("dc:title")[0] ?? "",
195 authors: field("dc:creator"),
196 language: field("dc:language")[0] ?? "",
197 chapters,
198 total: spine.length,
199 excerpt: body === null ? "" : stripMarkup(body),
200 note: spine.length === 0 ? "This book's package document lists no chapters." : "",
201 };
202 }
203
204 export function epub(input: RenderInput): Rendered {
205 const book = readBook(input.body);
206 if ("error" in book) return { content: html``, lines: 0, fallback: book.error };
outdated

Both doors: this is a new render module with no screen under src/tui/screens/. Add it, with its palette entry.

207 const fact = (k: string, v: string): string =>
208 v === "" ? "" : `<tr><th scope="row">${k}</th><td>${escapeHtml(v)}</td></tr>`;
209 const facts = fact("Title", book.title) + fact("Author", book.authors.join(", ")) + fact("Language", book.language);
210 const rows = book.chapters
211 .map((c, i) => `<tr><td class="num">${i + 1}</td><td>${escapeHtml(c.title)}</td></tr>`)
212 .join("");
213 const cut =
214 book.total > book.chapters.length
215 ? `<p class="muted small">The first ${CHAPTERS.toLocaleString("en-US")} of ${book.total.toLocaleString("en-US")} chapters are listed.</p>`
216 : "";
217 const content = html`${raw(book.note === "" ? "" : `<p class="muted small">${escapeHtml(book.note)}</p>`)}
218 ${raw(facts === "" ? "" : `<table class="table" data-dense aria-label="About this book"><tbody>${facts}</tbody></table>`)}
219 ${raw(rows === "" ? "" : `<table class="table" data-dense aria-label="Chapters in reading order"><thead><tr><th scope="col">#</th><th scope="col">Chapter</th></tr></thead><tbody>${rows}</tbody></table>`)}
220 ${raw(cut)}
221 ${raw(book.excerpt === "" ? "" : `<h3>Opening of the first chapter</h3><div class="prose" data-text="message"><pre>${escapeHtml(book.excerpt)}</pre></div>`)}`;
222 const n = book.total;
223 return {
224 content,
225 lines: 0,
226 summary: `${n.toLocaleString("en-US")} ${n === 1 ? "chapter" : "chapters"} · ${fileSize(input.size)}`,
227 };
228 }
src/web/render/kinds.ts +3
@@ -29,6 +29,7 @@ export type FileKind =
2929 | "document"
3030 | "slides"
3131 | "layers"
32 | "epub"
3233 | "font"
3334 | "psd"
3435 | "config"
@@ -109,6 +110,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = {
109110 document: 10 * MB,
110111 slides: 10 * MB,
111112 layers: 20 * MB,
113 epub: 20 * MB,
112114 font: 20 * MB,
113115 // Read whole up to 5 MB; above that the header alone gives the facts.
114116 psd: 4_000 * MB,
@@ -372,6 +374,7 @@ const OFFICE: Readonly<Record<string, FileKind>> = {
372374 docx: "document",
373375 pptx: "slides",
374376 ora: "layers",
377 epub: "epub",
375378 };
376379 const isOffice = (path: string, head: Uint8Array): FileKind | undefined => {
377380 const kind = OFFICE[extension(path)];
src/web/render/renderers.ts +2
@@ -56,6 +56,7 @@ import { lcov } from "./lcov.ts";
5656 import { sarif } from "./sarif.ts";
5757 import { sheet } from "./xlsx.ts";
5858 import { docx } from "./docx.ts";
59 import { epub } from "./epub.ts";
5960 import { pptx } from "./pptx.ts";
6061 import { ora } from "./ora.ts";
6162 import { sqlite } from "./sqlite.ts";
@@ -177,6 +178,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = {
177178 document: docx,
178179 slides: pptx,
179180 layers: ora,
181 epub,
180182 font,
181183 psd,
182184 };
test/fuzz-renderers.test.ts +44
@@ -294,6 +294,16 @@ export const SAMPLES: Readonly<Record<string, { path: string; files: readonly st
294294 path: "cube.obj",
295295 files: ["# <b>cube</b>\no Cube\nv 0 0 0\nv 1 0 0\nv 0 1 0\nvn 0 0 1\nf 1 2 3\n"],
296296 },
297 epub: {
298 path: "book.epub",
299 files: [
300 storedZip({
301 "META-INF/container.xml": '<container><rootfile full-path="c.opf"/></container>',
302 "c.opf": '<package><metadata><dc:title>T</dc:title><dc:creator>A</dc:creator><dc:language>en</dc:language></metadata><manifest><item id="a" href="a.xhtml"/></manifest><spine><itemref idref="a"/></spine></package>',
303 "a.xhtml": "<html><body><p>Hello</p></body></html>",
304 }),
305 ],
306 },
297307 };
298308
299309 /**
@@ -319,6 +329,40 @@ export const EXCLUDED: Readonly<Record<string, string>> = {
319329 psd: "binary Photoshop layers; needs a fixture to splice into",
320330 };
321331
332 /**
333 * A stored (uncompressed) zip of ASCII parts, in which every length and
334 * offset has both bytes below 0x80 (parts are padded with trailing spaces
335 * until they do), so it survives the text round trip the fuzzer puts
336 * samples through.
337 */
338 function storedZip(parts: Record<string, string>): string {
339 const u16 = (n: number) => String.fromCharCode(n & 0xff, n >> 8);
340 const u32 = (n: number) => u16(n & 0xffff) + u16(n >>> 16);
341 const clean = (n: number) => (n & 0x80) === 0 && (n & 0x8000) === 0;
342 let body = "";
343 const records: { name: string; at: number; size: number }[] = [];
344 for (const [name, text] of Object.entries(parts)) {
345 let data = text;
346 while (!clean(data.length) || !clean(body.length + 30 + name.length + data.length)) data += " ";
347 records.push({ name, at: body.length, size: data.length });
348 body += "PK\x03\x04" + u16(20) + u16(0) + u16(0) + u32(0) + u32(0) + u32(data.length) + u32(data.length) + u16(name.length) + u16(0) + name + data;
349 }
350 let central = "";
351 let pad = 0;
352 for (;;) {
353 central = records
354 .map((r, i) => {
355 const comment = i === records.length - 1 ? " ".repeat(pad) : "";
356 return "PK\x01\x02" + u16(20) + u16(20) + u16(0) + u16(0) + u32(0) + u32(0) + u32(r.size) + u32(r.size) + u16(r.name.length) + u16(0) + u16(comment.length) + u16(0) + u16(0) + u32(0) + u32(r.at) + r.name + comment;
357 })
358 .join("");
359 if (clean(central.length)) break;
360 pad++;
361 }
362 const n = records.length;
363 return body + central + "PK\x05\x06" + u16(0) + u16(0) + u16(n) + u16(n) + u32(central.length) + u32(body.length) + u16(0);
364 }
365
322366 /** The kind a sample is: what the blob page reads from its path and first file. */
323367 export const sampleKind = (sample: { path: string; files: readonly string[] }): string =>
324368 fileKind(sample.path, encoder.encode(sample.files[0] ?? "").subarray(0, HEAD_BYTES));
test/render-epub.test.ts added +129
@@ -0,0 +1,129 @@
1 /** .epub as facts: registry, reader, page, and the hostile cases. */
2 import { describe, expect, test } from "bun:test";
3 import { zip } from "./helpers/zip.ts";
4 import { fileKind, mediaType } from "../src/web/render/kinds.ts";
5 import { RENDERERS, rendererFor } from "../src/web/render/renderers.ts";
6 import { CHAPTERS, EXCERPT, epub, readBook, stripMarkup } from "../src/web/render/epub.ts";
7
8 const draw = (body: Uint8Array) => epub({ path: "b.epub", size: body.length, body, media: "/m", download: "/d" });
9
10 const CONTAINER = `<?xml version="1.0"?><container><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`;
11 const opf = (spine: string[], extra = "") => `<package><metadata>
12 <dc:title>Tides &amp; &lt;Time&gt;</dc:title><dc:creator>Ada Lovelace</dc:creator><dc:creator>B. Babbage</dc:creator><dc:language>en-GB</dc:language></metadata>
13 <manifest><item id="nav" href="nav.xhtml" properties="nav"/>${spine.map((s) => `<item id="${s}" href="${s}.xhtml"/>`).join("")}${extra}</manifest>
14 <spine>${spine.map((s) => `<itemref idref="${s}"/>`).join("")}</spine></package>`;
15 const NAV = `<html><body><nav epub:type="toc"><ol><li><a href="c2.xhtml">Second <i>chapter</i></a></li><li><a href="c1.xhtml#top">&lt;script&gt;First</a></li></ol></nav></body></html>`;
16 const book = (parts: Record<string, string> = {}) =>
17 zip({
18 mimetype: "application/epub+zip",
19 "META-INF/container.xml": CONTAINER,
20 "OEBPS/content.opf": opf(["c2", "c1"]),
21 "OEBPS/nav.xhtml": NAV,
22 "OEBPS/c2.xhtml": "<html><head><title>no</title><style>p{}</style></head><body><h1>Start</h1><p>Hello <b>there</b> &amp; welcome</p><script>alert(1)</script><p>Next</p></body></html>",
23 "OEBPS/c1.xhtml": "<p>one</p>",
24 ...parts,
25 });
26
27 describe("epub", () => {
28 test("is its own kind, needs zip bytes, and is registered", () => {
29 const pk = new Uint8Array([0x50, 0x4b, 3, 4, 0]);
30 expect(fileKind("a.epub", pk)).toBe("epub");
31 expect(mediaType("a.epub", pk)).toBe("application/octet-stream");
32 expect(fileKind("a.epub", new TextEncoder().encode("plain"))).toBe("text");
33 expect(RENDERERS.epub).toBe(epub);
34 const body = book();
35 expect(rendererFor("a.epub", { kind: "binary", body, size: body.length })?.render).toBe(epub);
36 });
37
38 test("title, authors, language and chapters in spine order with nav titles", () => {
39 const b = readBook(book());
40 if ("error" in b) throw new Error(b.error);
41 expect(b.title).toBe("Tides & <Time>");
42 expect(b.authors).toEqual(["Ada Lovelace", "B. Babbage"]);
43 expect(b.language).toBe("en-GB");
44 expect(b.chapters.map((c) => c.title)).toEqual(["Second chapter", "<script>First"]);
45 expect(b.chapters.map((c) => c.href)).toEqual(["OEBPS/c2.xhtml", "OEBPS/c1.xhtml"]);
46 expect(b.excerpt).toBe("Start\n\nHello there & welcome\n\nNext");
47 });
48
49 test("the page escapes every title and shows no markup from the book", () => {
50 const text = String(draw(book()).content);
51 expect(text).toContain("Tides &amp; &lt;Time&gt;");
52 expect(text).toContain("&lt;script&gt;First");
53 expect(text).not.toContain("<script");
54 expect(text).not.toContain("alert(1)");
55 expect(text).not.toContain("<b>there");
56 expect(draw(book()).summary).toContain("2 chapters");
57 });
58
59 test("an EPUB 2 book takes its titles from the NCX", () => {
60 const ncx = `<ncx><navMap><navPoint><navLabel><text>Alpha</text></navLabel><content src="c1.xhtml"/></navPoint></navMap></ncx>`;
61 const b = readBook(
62 zip({
63 "META-INF/container.xml": CONTAINER,
64 "OEBPS/content.opf": `<package><metadata><dc:title>T</dc:title></metadata><manifest><item id="ncx" href="toc.ncx"/><item id="c1" href="c1.xhtml"/></manifest><spine toc="ncx"><itemref idref="c1"/></spine></package>`,
65 "OEBPS/toc.ncx": ncx,
66 "OEBPS/c1.xhtml": "<p>x</p>",
67 }),
68 );
69 if ("error" in b) throw new Error(b.error);
70 expect(b.chapters[0]!.title).toBe("Alpha");
71 });
72
73 test("the excerpt is at most 2,000 characters", () => {
74 const b = readBook(book({ "OEBPS/c2.xhtml": `<p>${"word ".repeat(5000)}</p>` }));
75 if ("error" in b) throw new Error(b.error);
76 expect(b.excerpt.length).toBeLessThanOrEqual(EXCERPT);
77 expect(b.excerpt.length).toBeGreaterThan(1900);
78 });
79
80 test("stripMarkup is linear on an unclosed tag flood and drops script", () => {
81 const t = performance.now();
82 expect(stripMarkup("<".repeat(500_000))).toBe("");
83 expect(performance.now() - t).toBeLessThan(500);
84 expect(stripMarkup("a<script>b</script>c<!-- d -->e")).toBe("ace");
85 });
86
87 test("a missing OPF shows a note, not an error", () => {
88 const b = readBook(zip({ "META-INF/container.xml": "<container/>" }));
89 if ("error" in b) throw new Error(b.error);
90 expect(b.note).toContain("no readable package document");
91 const out = draw(zip({ "a.txt": "x" }));
92 expect(out.fallback).toBeUndefined();
93 expect(String(out.content)).toContain("no readable package document");
94 });
95
96 test("path traversal in the container or the spine reads nothing", () => {
97 const evil = zip({
98 "META-INF/container.xml": `<container><rootfile full-path="../../etc/passwd"/></container>`,
99 });
100 const b = readBook(evil);
101 if ("error" in b) throw new Error(b.error);
102 expect(b.chapters).toEqual([]);
103 const b2 = readBook(
104 book({ "OEBPS/content.opf": `<package><metadata><dc:title>T</dc:title></metadata><manifest><item id="x" href="../../secret.xhtml"/><item id="y" href="%2e%2e/z.xhtml"/></manifest><spine><itemref idref="x"/><itemref idref="y"/></spine></package>` }),
105 );
106 if ("error" in b2) throw new Error(b2.error);
107 expect(b2.total).toBe(0);
108 });
109

This assertion passes for any value but undefined; it tests nothing. Remove it or assert the outcome.

110 test("a character whose lowercase is longer does not move the script cut", () => {
111 // "İ".toLowerCase() is two UTF-16 units: indices from a lowered copy would drift by one each.
112 const text = stripMarkup("<p>" + "İ".repeat(40) + "</p><SCRIPT>secret()</SCRIPT><p>after</p>");
113 expect(text).toContain("after");
114 expect(text).not.toContain("secret");
115 expect(text).not.toContain("SCRIPT");
116 expect(text).not.toContain("<");
117 });
118 test("a zip bomb and a non-zip are refused, a long spine is capped", () => {
119 const bomb = readBook(zip({ "META-INF/container.xml": "x", a: "y" }, 70 * 1024 * 1024));
120 expect("error" in bomb).toBe(true);
121 expect("error" in readBook(new TextEncoder().encode("not a zip"))).toBe(true);
122 expect(draw(new TextEncoder().encode("not a zip")).fallback).toBeTruthy();
123 const many = Array.from({ length: CHAPTERS + 5 }, (_, i) => `c${i}`);
124 const b = readBook(zip({ "META-INF/container.xml": CONTAINER, "OEBPS/content.opf": opf(many) }));
125 if ("error" in b) throw new Error(b.error);
126 expect(b.chapters.length).toBe(CHAPTERS);
127 expect(b.total).toBe(CHAPTERS + 5);
128 });
129 });
test/render-kinds.test.ts +1
@@ -70,6 +70,7 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = {
7070 docx: [of(0x50, 0x4b, 3, 4, 0), "document", "application/octet-stream"],
7171 pptx: [of(0x50, 0x4b, 3, 4, 0), "slides", "application/octet-stream"],
7272 ora: [of(0x50, 0x4b, 3, 4, 0), "layers", "application/octet-stream"],
73 epub: [of(0x50, 0x4b, 3, 4, 0), "epub", "application/octet-stream"],
7374 ipynb: [enc("{}"), "notebook", "application/octet-stream"],
7475 md: [enc("# a\n"), "markdown", "application/octet-stream"],
7576 markdown: [enc("# a\n"), "markdown", "application/octet-stream"],
test/tui-office.test.ts +25
@@ -57,6 +57,31 @@ describe("the terminal's office view", () => {
5757 });
5858 });
5959
60 describe("the terminal's epub view", () => {
61 const book = zip({
62 mimetype: "application/epub+zip",
63 "META-INF/container.xml": `<container><rootfiles><rootfile full-path="c.opf"/></rootfiles></container>`,
64 "c.opf": `<package><metadata><dc:title>Tides</dc:title><dc:creator>Ada</dc:creator><dc:language>en</dc:language></metadata><manifest><item id="a" href="a.xhtml"/></manifest><spine><itemref idref="a"/></spine></package>`,
65 "a.xhtml": "<p>Hello <b>there</b></p><script>x()</script>",
66 });
67 test("title, author, language, chapters and the excerpt, as the page reads them", () => {
68 const t = officeView("a.epub", book);
69 if (typeof t === "string" || t === null) throw new Error("no table");
70 expect(t.rows).toEqual([["Title", "Tides"], ["Author", "Ada"], ["Language", "en"], ["Chapter 1", "a.xhtml"], ["Excerpt", "Hello there"]]);
71 });
72 test("the page's gate: text bytes, another name, or past the cap are not read", () => {
73 expect(officeView("a.epub", new TextEncoder().encode("plain"))).toBeNull();
74 expect(officeView("a.zip", book)).toBeNull();
75 const big = new Uint8Array(RENDER_CAP.epub + 1);
76 big.set(book);
77 expect(String(officeView("a.epub", big))).toContain("too large");
78 });
79 test("a file that is not a zip answers its reason", () => {
80 const bad = new Uint8Array([0x50, 0x4b, 0x03, 0x04, 1, 2, 3]);
81 expect(typeof officeView("a.epub", bad)).toBe("string");
82 });
83 });
84
6085 describe("the pages are rows, not a box", () => {
6186 const draw = (f: typeof docx, path: string, body: Uint8Array) =>
6287 f({ path, size: body.length, body, media: "/m", download: "/d" }).content.toString();

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs