@bendyline/squisq-formats 1.4.2 → 2.0.1

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,24 @@
 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 interface ContainerToZipOptions {
+  /** STORE avoids producing archives that violate strict import compression-ratio policies. */
+  compression?: 'STORE' | 'DEFLATE';
+  /** JSZip DEFLATE level; ignored for STORE. */
+  compressionLevel?: number;
+}
+export { ZipSafetyError };
+export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
 
 /**
  * Serialize a ContentContainer to a ZIP blob.
@@ -24,21 +42,30 @@ import { MemoryContentContainer } from '@bendyline/squisq/storage';
  * @param container — The container to serialize
  * @returns A Blob containing the ZIP archive
  */
-export async function containerToZip(container: ContentContainer): Promise<Blob> {
+export async function containerToZip(
+  container: ContentContainer,
+  options: ContainerToZipOptions = {},
+): Promise<Blob> {
   const zip = new JSZip();
   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));
     }
   }
 
+  const compression = options.compression ?? 'DEFLATE';
+  const compressionLevel = options.compressionLevel ?? 6;
+  if (!Number.isSafeInteger(compressionLevel) || compressionLevel < 1 || compressionLevel > 9) {
+    throw new Error('ZIP compression level must be an integer between 1 and 9');
+  }
   return zip.generateAsync({
     type: 'blob',
-    compression: 'DEFLATE',
-    compressionOptions: { level: 6 },
+    compression,
+    ...(compression === 'DEFLATE' ? { compressionOptions: { level: compressionLevel } } : {}),
   });
 }
 
@@ -54,36 +81,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');