@bendyline/squisq-formats 1.4.2 → 2.0.0

package/src/__tests__/zipSafety.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it, vi } from 'vitest';
+import JSZip from 'jszip';
+import { getPartXml, openPackage } from '../ooxml/reader';
+import type { OoxmlPackage } from '../ooxml/types';
+import { openBoundedZipArchive, validateZipArchive, ZipSafetyError } from '../shared/zipSafety';
+import { declaredZipEntryCount } from '../shared/zipEntryCount';
+
+interface InstrumentedStream {
+  pause(): InstrumentedStream;
+}
+
+interface StreamableEntry {
+  internalStream(type: 'uint8array'): InstrumentedStream;
+}
+
+async function makeZip(
+  files: Record<string, string | Uint8Array>,
+  compression: 'STORE' | 'DEFLATE' = 'DEFLATE',
+): Promise<Uint8Array> {
+  const zip = new JSZip();
+  for (const [path, data] of Object.entries(files)) zip.file(path, data);
+  return zip.generateAsync({ type: 'uint8array', compression });
+}
+
+function patchMemberMetadata(
+  source: Uint8Array,
+  path: string,
+  patch: { uncompressedSize?: number; crc32?: number },
+): Uint8Array {
+  const bytes = source.slice();
+  const view = new DataView(bytes.buffer);
+  let patchedCentral = false;
+
+  for (let offset = 0; offset <= bytes.byteLength - 4; offset++) {
+    const signature = view.getUint32(offset, true);
+    let nameOffset: number;
+    let nameLengthOffset: number;
+    let uncompressedSizeOffset: number;
+    let crcOffset: number;
+    if (signature === 0x02014b50) {
+      nameOffset = offset + 46;
+      nameLengthOffset = offset + 28;
+      uncompressedSizeOffset = offset + 24;
+      crcOffset = offset + 16;
+    } else if (signature === 0x04034b50) {
+      nameOffset = offset + 30;
+      nameLengthOffset = offset + 26;
+      uncompressedSizeOffset = offset + 22;
+      crcOffset = offset + 14;
+    } else {
+      continue;
+    }
+
+    const nameLength = view.getUint16(nameLengthOffset, true);
+    const name = new TextDecoder().decode(bytes.subarray(nameOffset, nameOffset + nameLength));
+    if (name !== path) continue;
+    if (patch.uncompressedSize !== undefined) {
+      view.setUint32(uncompressedSizeOffset, patch.uncompressedSize, true);
+    }
+    if (patch.crc32 !== undefined) view.setUint32(crcOffset, patch.crc32, true);
+    if (signature === 0x02014b50) patchedCentral = true;
+  }
+
+  expect(patchedCentral).toBe(true);
+  return bytes;
+}
+
+function renameZipMember(source: Uint8Array, from: string, to: string): Uint8Array {
+  expect(to.length).toBe(from.length);
+  const bytes = source.slice();
+  const view = new DataView(bytes.buffer);
+  const replacement = new TextEncoder().encode(to);
+  let renamedCentral = false;
+  for (let offset = 0; offset <= bytes.byteLength - 4; offset++) {
+    const signature = view.getUint32(offset, true);
+    const isCentral = signature === 0x02014b50;
+    const isLocal = signature === 0x04034b50;
+    if (!isCentral && !isLocal) continue;
+    const nameLengthOffset = offset + (isCentral ? 28 : 26);
+    const nameOffset = offset + (isCentral ? 46 : 30);
+    const nameLength = view.getUint16(nameLengthOffset, true);
+    const name = new TextDecoder().decode(bytes.subarray(nameOffset, nameOffset + nameLength));
+    if (name !== from) continue;
+    bytes.set(replacement, nameOffset);
+    if (isCentral) renamedCentral = true;
+  }
+  expect(renamedCentral).toBe(true);
+  return bytes;
+}
+
+describe('bounded JSZip reads', () => {
+  it('preflights duplicate central records before JSZip collapses their names', async () => {
+    const valid = await makeZip({ 'one.txt': '1', 'two.txt': '2' }, 'STORE');
+    const duplicate = renameZipMember(valid, 'two.txt', 'one.txt');
+    const parsed = await JSZip.loadAsync(duplicate);
+    expect(Object.values(parsed.files).filter((entry) => !entry.dir)).toHaveLength(1);
+
+    const blob = new Blob([duplicate.slice().buffer]);
+    await expect(openBoundedZipArchive(blob, { maxEntries: 1 })).rejects.toMatchObject({
+      code: 'too-many-entries',
+      limit: 1,
+      actual: 2,
+    });
+  });
+
+  it('counts directory-only central records toward the entry limit', async () => {
+    const zip = new JSZip();
+    zip.folder('one');
+    zip.folder('two');
+    const data = await zip.generateAsync({ type: 'uint8array' });
+    await expect(openBoundedZipArchive(data, { maxEntries: 1 })).rejects.toMatchObject({
+      code: 'too-many-entries',
+      actual: 2,
+    });
+  });
+
+  it('finds the EOCD record with a comment containing signature-like bytes', async () => {
+    const zip = new JSZip();
+    zip.file('one.txt', '1');
+    zip.file('two.txt', '2');
+    const data = await zip.generateAsync({
+      type: 'uint8array',
+      comment: 'looks like PK\u0005\u0006 but is only a comment',
+    });
+    expect(declaredZipEntryCount(data)).toBe(2);
+  });
+
+  it('reads ZIP64 record counts and falls back when ZIP64 metadata is ambiguous', () => {
+    const zip64 = new Uint8Array(98);
+    const view = new DataView(zip64.buffer);
+    view.setUint32(0, 0x06064b50, true);
+    view.setUint32(32, 3, true);
+    view.setUint32(56, 0x07064b50, true);
+    view.setUint32(64, 0, true);
+    view.setUint32(76, 0x06054b50, true);
+    view.setUint16(86, 0xffff, true);
+    expect(declaredZipEntryCount(zip64)).toBe(3);
+
+    zip64.fill(0, 56, 76);
+    expect(declaredZipEntryCount(zip64)).toBeUndefined();
+  });
+
+  it('maps Blob read failures to a structured invalid-archive error', async () => {
+    const unreadable = {
+      size: 10,
+      slice: () => unreadable,
+      arrayBuffer: () => Promise.reject(new Error('read failed')),
+    } as unknown as Blob;
+    await expect(openBoundedZipArchive(unreadable)).rejects.toMatchObject({
+      code: 'invalid-archive',
+    });
+  });
+
+  it('returns structured errors while preserving established messages', async () => {
+    const data = await makeZip({ 'large.txt': '12345' }, 'STORE');
+    let error: unknown;
+    try {
+      await openBoundedZipArchive(data, { maxEntryUncompressedBytes: 4 });
+    } catch (caught: unknown) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(ZipSafetyError);
+    expect(error).toMatchObject({
+      name: 'ZipSafetyError',
+      code: 'entry-too-large',
+      path: 'large.txt',
+      limit: 4,
+      actual: 5,
+    });
+    expect((error as Error).message).toMatch(/exceeds 4 byte per-entry limit/);
+  });
+
+  it('rejects a high-ratio member from central-directory metadata', async () => {
+    const data = await makeZip({ 'repeated.bin': new Uint8Array(128 * 1024) });
+    await expect(openBoundedZipArchive(data, { maxCompressionRatio: 2 })).rejects.toMatchObject({
+      code: 'compression-ratio-exceeded',
+      path: 'repeated.bin',
+      limit: 2,
+    });
+  });
+
+  it('enforces the default compression-ratio ceiling against a single-member bomb', async () => {
+    const data = await makeZip({ 'zeros.bin': new Uint8Array(2 * 1024 * 1024) });
+    await expect(openBoundedZipArchive(data)).rejects.toMatchObject({
+      code: 'compression-ratio-exceeded',
+      path: 'zeros.bin',
+      limit: 1000,
+    });
+  });
+
+  it('halts an underdeclared member on its first emitted chunk without retaining it', async () => {
+    const valid = await makeZip({ 'bomb.txt': new Uint8Array(1024 * 1024) });
+    const forged = patchMemberMetadata(valid, 'bomb.txt', { uncompressedSize: 1 });
+    const archive = await openBoundedZipArchive(forged);
+
+    await expect(archive.read('bomb.txt')).rejects.toMatchObject({
+      code: 'size-mismatch',
+      path: 'bomb.txt',
+    });
+    expect(archive.emittedUncompressedBytes).toBe(0);
+  });
+
+  it('pauses every concurrent JSZip stream when one read breaches its bound', async () => {
+    const data = await makeZip(
+      {
+        'one.bin': new Uint8Array(64 * 1024),
+        'two.bin': new Uint8Array(64 * 1024),
+      },
+      'STORE',
+    );
+    const archive = await openBoundedZipArchive(data);
+    const pauseSpies: Array<ReturnType<typeof vi.fn>> = [];
+
+    for (const metadata of archive.entries) {
+      const entry = metadata.entry as unknown as StreamableEntry;
+      const original = entry.internalStream.bind(entry);
+      entry.internalStream = ((type: 'uint8array') => {
+        const stream = original(type);
+        const pause = vi.fn(stream.pause.bind(stream));
+        stream.pause = pause;
+        pauseSpies.push(pause);
+        return stream;
+      }) as StreamableEntry['internalStream'];
+    }
+
+    const results = await Promise.allSettled([
+      archive.read('one.bin', 1),
+      archive.read('two.bin', 1),
+    ]);
+    expect(results.every((result) => result.status === 'rejected')).toBe(true);
+    expect(pauseSpies).toHaveLength(2);
+    expect(pauseSpies.every((pause) => pause.mock.calls.length > 0)).toBe(true);
+    expect(archive.emittedUncompressedBytes).toBe(0);
+  });
+
+  it('caches successful part reads without charging the aggregate budget twice', async () => {
+    const data = await makeZip({ 'part.xml': '<part />' }, 'STORE');
+    const archive = await openBoundedZipArchive(data);
+    const first = await archive.read('part.xml');
+    const emittedAfterFirstRead = archive.emittedUncompressedBytes;
+    const second = await archive.read('part.xml');
+
+    expect(second).toBe(first);
+    expect(archive.emittedUncompressedBytes).toBe(emittedAfterFirstRead);
+    expect(emittedAfterFirstRead).toBe(new TextEncoder().encode('<part />').byteLength);
+  });
+
+  it('checks CRC32 while streaming instead of eagerly inflating during load', async () => {
+    const valid = await makeZip({ 'content.txt': 'integrity' }, 'STORE');
+    const forged = patchMemberMetadata(valid, 'content.txt', { crc32: 0 });
+    const archive = await openBoundedZipArchive(forged);
+
+    await expect(archive.read('content.txt')).rejects.toMatchObject({
+      code: 'crc-mismatch',
+      path: 'content.txt',
+    });
+  });
+
+  it('does not reject an otherwise valid JSZip object solely for unavailable internals', async () => {
+    const data = await makeZip({ 'content.txt': 'okay' }, 'STORE');
+    const zip = await JSZip.loadAsync(data);
+    const entry = zip.file('content.txt') as unknown as {
+      _data: { uncompressedSize?: number; compressedSize?: number; crc32?: number };
+    };
+    delete entry._data.uncompressedSize;
+    delete entry._data.compressedSize;
+    delete entry._data.crc32;
+
+    expect(() => validateZipArchive(zip)).not.toThrow();
+  });
+
+  it('rejects manually constructed OOXML packages that bypass bounded archive opening', async () => {
+    const forged = {
+      contentTypes: { overrides: new Map(), defaults: new Map() },
+      rootRelationships: [],
+    } as unknown as OoxmlPackage;
+
+    await expect(getPartXml(forged, 'custom.xml')).rejects.toThrow(
+      'Invalid OoxmlPackage: create packages with openPackage().',
+    );
+  });
+
+  it('bounds mandatory OOXML metadata independently of large media allowances', async () => {
+    const oversizedContentTypes = `<Types>${' '.repeat(1024 * 1024)}</Types>`;
+    const data = await makeZip(
+      {
+        '[Content_Types].xml': oversizedContentTypes,
+        'word/media/large.bin': new Uint8Array(2 * 1024 * 1024),
+      },
+      'STORE',
+    );
+
+    await expect(openPackage(data.slice().buffer)).rejects.toMatchObject({
+      code: 'entry-too-large',
+      path: '[Content_Types].xml',
+      limit: 1024 * 1024,
+    });
+  });
+
+  it('bounds OOXML relationship metadata before DOM parsing', async () => {
+    const oversizedRelationships = `<Relationships>${' '.repeat(4 * 1024 * 1024)}</Relationships>`;
+    const data = await makeZip(
+      {
+        '[Content_Types].xml': '<Types />',
+        '_rels/.rels': oversizedRelationships,
+      },
+      'STORE',
+    );
+
+    await expect(openPackage(data.slice().buffer)).rejects.toMatchObject({
+      code: 'entry-too-large',
+      path: '_rels/.rels',
+      limit: 4 * 1024 * 1024,
+    });
+  });
+});

package/src/container/index.ts

@@ -14,6 +14,18 @@
 import JSZip from 'jszip';
 import type { ContentContainer } from '@bendyline/squisq/storage';
 import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import {
+  assertSafeZipPath,
+  openBoundedZipArchive,
+  ZipSafetyError,
+  type ZipSafetyLimits,
+  type ZipSafetyErrorCode,
+  type ZipSafetyErrorOptions,
+} from '../shared/zipSafety.js';
+
+export type ZipToContainerOptions = ZipSafetyLimits;
+export { ZipSafetyError };
+export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
 
 /**
  * Serialize a ContentContainer to a ZIP blob.
@@ -29,6 +41,7 @@ export async function containerToZip(container: ContentContainer): Promise<Blob>
   const entries = await container.listFiles();
 
   for (const entry of entries) {
+    assertSafeZipPath(entry.path);
     const data = await container.readFile(entry.path);
     if (data) {
       zip.file(entry.path, new Uint8Array(data));
@@ -54,36 +67,14 @@ export async function containerToZip(container: ContentContainer): Promise<Blob>
  */
 export async function zipToContainer(
   zipData: ArrayBuffer | Uint8Array | Blob,
+  options: ZipToContainerOptions = {},
 ): Promise<MemoryContentContainer> {
-  const zip = await JSZip.loadAsync(zipData);
+  const archive = await openBoundedZipArchive(zipData, options);
   const container = new MemoryContentContainer();
-
-  const filePromises: Promise<void>[] = [];
-
-  zip.forEach((relativePath, zipEntry) => {
-    // Skip directories
-    if (zipEntry.dir) return;
-
-    // Strip leading slash if present
-    const entryPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
-    if (!entryPath) return;
-
-    // Path-traversal protection: reject absolute paths, backslashes, and .. segments
-    if (
-      entryPath.startsWith('/') ||
-      entryPath.includes('\\') ||
-      entryPath.split('/').some((seg) => seg === '..')
-    ) {
-      return;
-    }
-
-    filePromises.push(
-      zipEntry.async('arraybuffer').then((data) => {
-        return container.writeFile(entryPath, data);
-      }),
-    );
-  });
-
-  await Promise.all(filePromises);
+  for (const { path } of archive.entries) {
+    const data = await archive.read(path);
+    if (data) await container.writeFile(path, data);
+    archive.release(path);
+  }
   return container;
 }

package/src/docx/export.ts

@@ -17,7 +17,7 @@
  * ```
  */
 
-import type { Doc, Theme } from '@bendyline/squisq/schemas';
+import type { Doc, Theme, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { resolveFontFamily } from '@bendyline/squisq/schemas';
 import { docToMarkdown, resolveThemeForDoc } from '@bendyline/squisq/doc';
 import type {
@@ -105,6 +105,8 @@ export interface DocxExportOptions {
    * the theme's primary color to headings.
    */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
   /**
    * Pre-resolved image data keyed by image URL/path as it appears in the
    * markdown source. When provided, images are embedded in the .docx file
@@ -221,7 +223,7 @@ class ExportContext {
     let themeBackgroundColor: string | undefined;
 
     if (options.themeId) {
-      const theme: Theme = resolveThemeForDoc(doc, options.themeId);
+      const theme: Theme = resolveThemeForDoc(doc, options.themeId, options.themeRegistry);
       // Theme fonts arrive as CSS stacks (e.g. `"Oswald", Impact,
       // "Arial Black", sans-serif`). Word's `w:ascii` attribute is a
       // single font name — passing the whole stack is treated as a

package/src/docx/import.ts

@@ -48,6 +48,7 @@ import type {
 } from '@bendyline/squisq/markdown';
 
 import { openPackage, getPartXml, getPartBinary, getPartRelationships } from '../ooxml/reader.js';
+import type { OoxmlOpenOptions } from '../ooxml/reader.js';
 import type { OoxmlPackage, Relationship } from '../ooxml/types.js';
 import { NS_WML, NS_R } from '../ooxml/namespaces.js';
 import type { ContentContainer } from '@bendyline/squisq/storage';
@@ -68,7 +69,7 @@ import {
 /**
  * Options for DOCX import.
  */
-export interface DocxImportOptions {
+export interface DocxImportOptions extends OoxmlOpenOptions {
   /**
    * Whether to extract embedded images as base64 data URIs.
    * When false, images are represented as `[Image]` placeholders.
@@ -88,7 +89,7 @@ export async function docxToMarkdownDoc(
   data: ArrayBuffer | Blob,
   options: DocxImportOptions = {},
 ): Promise<MarkdownDocument> {
-  const pkg = await openPackage(data);
+  const pkg = await openPackage(data, options);
   const ctx = await buildImportContext(pkg, options);
 
   const documentXml = await getPartXml(pkg, 'word/document.xml');
@@ -138,7 +139,7 @@ export async function docxToContainer(
   data: ArrayBuffer | Blob,
   options: DocxImportOptions = {},
 ): Promise<ContentContainer> {
-  const pkg = await openPackage(data);
+  const pkg = await openPackage(data, options);
   const ctx = await buildImportContext(pkg, { ...options, extractImages: true });
 
   const documentXml = await getPartXml(pkg, 'word/document.xml');

package/src/epub/export.ts

@@ -22,7 +22,7 @@
  */
 
 import JSZip from 'jszip';
-import type { Doc, AudioSegment } from '@bendyline/squisq/schemas';
+import type { Doc, AudioSegment, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { resolveFontFamily } from '@bendyline/squisq/schemas';
 import { resolveThemeForDoc } from '@bendyline/squisq/doc';
 import type {
@@ -36,7 +36,7 @@ import type {
   MarkdownTableRow,
   MarkdownTableCell,
 } from '@bendyline/squisq/markdown';
-import { readFrontmatterThemeId } from '@bendyline/squisq/markdown';
+import { readFrontmatterThemeId, sanitizeUrl } from '@bendyline/squisq/markdown';
 import { escapeXml } from '../ooxml/xmlUtils.js';
 import { inferMimeType, extractFilename } from '../html/imageUtils.js';
 import { extractPlainText } from '../shared/text.js';
@@ -56,6 +56,8 @@ export interface EpubExportOptions {
   publisher?: string;
   /** Squisq theme ID for CSS styling */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
   /** Pre-resolved image data keyed by relative path as it appears in the markdown */
   images?: Map<string, ArrayBuffer>;
   /** Cover image data (JPEG or PNG) */
@@ -93,7 +95,7 @@ export async function markdownDocToEpub(
   const language = options.language ?? 'en';
   const description = options.description ?? '';
   const publisher = options.publisher ?? '';
-  const uuid = crypto.randomUUID();
+  const uuid = createEpubUuid();
 
   // Split document into chapters
   const chapters = splitIntoChapters(doc.children);
@@ -101,22 +103,13 @@ export async function markdownDocToEpub(
   // Collect images referenced in the document, deduplicating filenames
   const imageEntries = collectDocImages(doc.children);
   const resolvedImages = new Map<string, { data: ArrayBuffer; mime: string; filename: string }>();
+  const usedImageNames = new Set<string>();
   if (options.images) {
-    const usedNames = new Set<string>();
     for (const src of imageEntries) {
       const data = options.images.get(src);
       if (data) {
-        let filename = extractFilename(src);
-        // Deduplicate: if two paths share a basename (e.g. a/hero.png and b/hero.png)
-        if (usedNames.has(filename)) {
-          const dot = filename.lastIndexOf('.');
-          const base = dot > 0 ? filename.slice(0, dot) : filename;
-          const ext = dot > 0 ? filename.slice(dot) : '';
-          let counter = 2;
-          while (usedNames.has(`${base}-${counter}${ext}`)) counter++;
-          filename = `${base}-${counter}${ext}`;
-        }
-        usedNames.add(filename);
+        const filename = uniqueFilename(safeArchiveBasename(src, 'image'), usedImageNames);
+        usedImageNames.add(filename);
         resolvedImages.set(src, { data, mime: inferMimeType(filename), filename });
       }
     }
@@ -124,7 +117,11 @@ export async function markdownDocToEpub(
 
   // Generate theme CSS — honor an explicit themeId, else the doc's frontmatter
   // theme (`squisq-theme` / legacy), mirroring the other export formats.
-  const css = generateStylesheet(options.themeId ?? readFrontmatterThemeId(doc.frontmatter), doc);
+  const css = generateStylesheet(
+    options.themeId ?? readFrontmatterThemeId(doc.frontmatter),
+    doc,
+    options.themeRegistry,
+  );
 
   // Build the ZIP
   const zip = new JSZip();
@@ -155,7 +152,8 @@ export async function markdownDocToEpub(
       bytes[1] === 0x50 &&
       bytes[2] === 0x4e &&
       bytes[3] === 0x47;
-    coverFilename = isPng ? 'cover.png' : 'cover.jpg';
+    coverFilename = uniqueFilename(isPng ? 'cover.png' : 'cover.jpg', usedImageNames);
+    usedImageNames.add(coverFilename);
     zip.file(`OEBPS/images/${coverFilename}`, options.coverImage);
 
     // Generate cover XHTML page — full-bleed image, no margins
@@ -184,17 +182,28 @@ export async function markdownDocToEpub(
   // Per-segment audio file info, indexed by segment index (null if data missing)
   const segmentAudioFiles: ({ filename: string; mime: string } | null)[] = [];
   const allAudioFiles: { filename: string; mime: string }[] = [];
+  const audioFilenameBySource = new Map<string, string>();
+  const usedAudioFilenames = new Set<string>();
 
   if (hasAudio) {
     for (const seg of audioSegments) {
       const data = audioMap.get(seg.src) ?? audioMap.get(seg.name);
       if (data) {
-        const filename = extractFilename(seg.src);
-        const finalName = filename.includes('.') ? filename : `${filename}.mp3`;
-        zip.file(`OEBPS/audio/${finalName}`, data);
+        const sourceKey = seg.src || seg.name;
+        let finalName = audioFilenameBySource.get(sourceKey);
+        let isNewFile = false;
+        if (!finalName) {
+          const basename = safeArchiveBasename(sourceKey || 'narration', 'narration');
+          const withExtension = basename.includes('.') ? basename : `${basename}.mp3`;
+          finalName = uniqueFilename(withExtension, usedAudioFilenames);
+          audioFilenameBySource.set(sourceKey, finalName);
+          usedAudioFilenames.add(finalName);
+          zip.file(`OEBPS/audio/${finalName}`, data);
+          isNewFile = true;
+        }
         const info = { filename: finalName, mime: inferMimeType(finalName) };
         segmentAudioFiles.push(info);
-        allAudioFiles.push(info);
+        if (isNewFile) allAudioFiles.push(info);
       } else {
         segmentAudioFiles.push(null);
       }
@@ -535,14 +544,18 @@ function inlineToXhtml(node: MarkdownInlineNode, images: ImageMap): string {
       return `<code>${escapeXml(node.value)}</code>`;
 
     case 'link': {
+      const href = sanitizeUrl(node.url, 'link');
+      if (!href) return inlinesToXhtml(node.children, images);
       const titleAttr = node.title ? ` title="${escapeXml(node.title)}"` : '';
-      return `<a href="${escapeXml(node.url)}"${titleAttr}>${inlinesToXhtml(node.children, images)}</a>`;
+      return `<a href="${escapeXml(href)}"${titleAttr}>${inlinesToXhtml(node.children, images)}</a>`;
     }
 
     case 'image': {
       const alt = escapeXml(node.alt ?? '');
       const resolved = images.get(node.url);
-      const src = resolved ? `../images/${resolved.filename}` : escapeXml(node.url);
+      const safeSrc = resolved ? `../images/${resolved.filename}` : sanitizeUrl(node.url, 'media');
+      if (!safeSrc) return alt;
+      const src = escapeXml(safeSrc);
       return `<img src="${src}" alt="${alt}"/>`;
     }
 
@@ -561,6 +574,58 @@ function inlineToXhtml(node: MarkdownInlineNode, images: ImageMap): string {
   }
 }
 
+/**
+ * Produce an EPUB identifier without assuming `crypto.randomUUID()` exists.
+ * `randomUUID` is unavailable in older/non-secure browser contexts; use
+ * `getRandomValues` when possible and retain a non-cryptographic last resort
+ * because this UUID is an identifier, not a security token.
+ */
+function createEpubUuid(): string {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === 'function') return webCrypto.randomUUID();
+
+  const bytes = new Uint8Array(16);
+  if (typeof webCrypto?.getRandomValues === 'function') {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    let seed = Date.now() ^ Math.floor(Math.random() * 0x7fffffff);
+    for (let i = 0; i < bytes.length; i++) {
+      seed = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+      bytes[i] = seed & 0xff;
+    }
+  }
+  // RFC 4122 version 4 / variant 1 bits.
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** Flatten an external path to a safe archive basename. */
+function safeArchiveBasename(path: string, fallback: string): string {
+  const filename = extractFilename(path.replace(/\\/g, '/'));
+  const safe = Array.from(filename, (character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return character === '\\' || character === '/' || codePoint < 0x20 || codePoint === 0x7f
+      ? '_'
+      : character;
+  })
+    .join('')
+    .trim();
+  return !safe || safe === '.' || safe === '..' ? fallback : safe;
+}
+
+/** Return a basename that does not collide with a prior archive member. */
+function uniqueFilename(filename: string, used: ReadonlySet<string>): string {
+  if (!used.has(filename)) return filename;
+  const dot = filename.lastIndexOf('.');
+  const base = dot > 0 ? filename.slice(0, dot) : filename;
+  const ext = dot > 0 ? filename.slice(dot) : '';
+  let suffix = 2;
+  while (used.has(`${base}-${suffix}${ext}`)) suffix++;
+  return `${base}-${suffix}${ext}`;
+}
+
 // ── SMIL Media Overlays ───────────────────────────────────────────
 
 /**
@@ -778,10 +843,14 @@ ${navItems}
 
 // ── Stylesheet ────────────────────────────────────────────────────
 
-function generateStylesheet(themeId: string | undefined, doc?: MarkdownDocument): string {
+function generateStylesheet(
+  themeId: string | undefined,
+  doc?: MarkdownDocument,
+  registry?: ThemeRegistry,
+): string {
   let themeVars = '';
   if (themeId) {
-    const theme = resolveThemeForDoc(doc, themeId);
+    const theme = resolveThemeForDoc(doc, themeId, registry);
     themeVars = `
   --epub-bg: ${theme.colors.background};
   --epub-text: ${theme.colors.text};