@bendyline/squisq-formats 1.4.2 → 2.0.1

package/src/shared/zipEntryCount.ts

@@ -0,0 +1,151 @@
+/** Narrow EOCD preflight for rejecting record-count bombs before JSZip allocation. */
+
+import { throwIfZipAborted } from './zipLimits.js';
+
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+const ZIP64_END_OF_CENTRAL_DIRECTORY = 0x06064b50;
+const ZIP64_END_LOCATOR = 0x07064b50;
+const UINT16_MAX = 0xffff;
+const MIN_EOCD_BYTES = 22;
+const MAX_ZIP_COMMENT_BYTES = 0xffff;
+
+export type ZipInput = ArrayBuffer | Uint8Array | Blob;
+
+/** Materialize Blob input once when possible so preflight bytes feed JSZip too. */
+export async function prepareZipInput(
+  data: ZipInput,
+  signal?: AbortSignal,
+): Promise<{ input: ZipInput; bytes?: Uint8Array }> {
+  throwIfZipAborted(signal);
+  if (ArrayBuffer.isView(data)) {
+    const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return { input: bytes, bytes };
+  }
+  if (!isBlobLike(data)) {
+    const bytes = new Uint8Array(data);
+    return { input: bytes, bytes };
+  }
+
+  const bytes = await readBlobBytes(data, signal);
+  throwIfZipAborted(signal);
+  return bytes ? { input: bytes, bytes } : { input: data };
+}
+
+/**
+ * Read the declared total central-directory record count when unambiguous.
+ * Returns undefined for absent, trailing, malformed, or unsupported metadata;
+ * JSZip remains authoritative in those cases.
+ */
+export function declaredZipEntryCount(bytes: Uint8Array): number | undefined {
+  const eocdOffset = findEocd(bytes);
+  if (eocdOffset === undefined) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const count = view.getUint16(eocdOffset + 10, true);
+  if (count !== UINT16_MAX) return count;
+  return readZip64EntryCount(view, eocdOffset);
+}
+
+function findEocd(bytes: Uint8Array): number | undefined {
+  if (bytes.byteLength < MIN_EOCD_BYTES) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const earliest = Math.max(0, bytes.byteLength - MIN_EOCD_BYTES - MAX_ZIP_COMMENT_BYTES);
+  for (let offset = bytes.byteLength - MIN_EOCD_BYTES; offset >= earliest; offset--) {
+    if (view.getUint32(offset, true) !== END_OF_CENTRAL_DIRECTORY) continue;
+    const commentLength = view.getUint16(offset + 20, true);
+    if (offset + MIN_EOCD_BYTES + commentLength === bytes.byteLength) return offset;
+  }
+  return undefined;
+}
+
+function readZip64EntryCount(view: DataView, eocdOffset: number): number | undefined {
+  const locatorOffset = eocdOffset - 20;
+  if (locatorOffset < 0 || view.getUint32(locatorOffset, true) !== ZIP64_END_LOCATOR) {
+    return undefined;
+  }
+  const recordOffset = readSafeUint64(view, locatorOffset + 8);
+  if (
+    recordOffset === undefined ||
+    recordOffset < 0 ||
+    recordOffset + 40 > view.byteLength ||
+    view.getUint32(recordOffset, true) !== ZIP64_END_OF_CENTRAL_DIRECTORY
+  ) {
+    return undefined;
+  }
+  return readSafeUint64(view, recordOffset + 32);
+}
+
+function readSafeUint64(view: DataView, offset: number): number | undefined {
+  if (offset < 0 || offset + 8 > view.byteLength) return undefined;
+  const low = view.getUint32(offset, true);
+  const high = view.getUint32(offset + 4, true);
+  const value = high * 0x1_0000_0000 + low;
+  return Number.isSafeInteger(value) ? value : undefined;
+}
+
+function isBlobLike(data: ZipInput): data is Blob {
+  const candidate = data as Blob;
+  return typeof candidate.size === 'number' && typeof candidate.slice === 'function';
+}
+
+async function readBlobBytes(blob: Blob, signal?: AbortSignal): Promise<Uint8Array | undefined> {
+  const arrayBuffer = (blob as Blob & { arrayBuffer?: () => Promise<ArrayBuffer> }).arrayBuffer;
+  if (typeof arrayBuffer === 'function') {
+    return new Uint8Array(await raceWithAbort(arrayBuffer.call(blob), signal));
+  }
+  if (typeof FileReader === 'undefined') return undefined;
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    let settled = false;
+    const cleanup = (): void => signal?.removeEventListener('abort', handleAbort);
+    const finish = (work: () => void): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      work();
+    };
+    const handleAbort = (): void => {
+      if (settled) return;
+      const reason = signal?.reason ?? new Error('ZIP operation was cancelled');
+      // Mark the promise settled before FileReader.abort(): browsers are
+      // allowed to dispatch `abort` synchronously and re-enter this handler.
+      finish(() => reject(reason));
+      try {
+        reader.abort();
+      } catch {
+        // Preserve the caller's reason if a platform reader is already done.
+      }
+    };
+    reader.onload = () => finish(() => resolve(new Uint8Array(reader.result as ArrayBuffer)));
+    reader.onerror = () =>
+      finish(() => reject(reader.error ?? new Error('Could not read ZIP blob.')));
+    reader.onabort = handleAbort;
+    signal?.addEventListener('abort', handleAbort, { once: true });
+    if (signal?.aborted) {
+      handleAbort();
+      return;
+    }
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+function raceWithAbort<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  throwIfZipAborted(signal);
+  if (!signal) return work;
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (complete: () => void): void => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', handleAbort);
+      complete();
+    };
+    const handleAbort = (): void =>
+      finish(() => reject(signal.reason ?? new Error('ZIP operation was cancelled')));
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    work.then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}

package/src/shared/zipLimits.ts

@@ -0,0 +1,296 @@
+/** ZIP safety policy, structured errors, path checks, and metadata validation. */
+
+import type JSZip from 'jszip';
+
+export interface ZipSafetyLimits {
+  /** Cooperatively cancel archive opening, validation, and member traversal. */
+  signal?: AbortSignal;
+  /** Maximum number of archive records, including directories. Default: 10,000. */
+  maxEntries?: number;
+  /** Maximum uncompressed bytes for one member. Defaults to maxUncompressedBytes. */
+  maxEntryUncompressedBytes?: number;
+  /** Maximum total uncompressed bytes across the archive. Default: 512 MiB. */
+  maxUncompressedBytes?: number;
+  /** Maximum uncompressed/compressed ratio for a member. Default: 1,000. */
+  maxCompressionRatio?: number;
+}
+
+export type ZipSafetyErrorCode =
+  | 'invalid-limit'
+  | 'invalid-archive'
+  | 'unsafe-path'
+  | 'invalid-entry-metadata'
+  | 'too-many-entries'
+  | 'entry-too-large'
+  | 'archive-too-large'
+  | 'compression-ratio-exceeded'
+  | 'size-mismatch'
+  | 'crc-mismatch'
+  | 'decompression-failed';
+
+export interface ZipSafetyErrorOptions {
+  path?: string;
+  limit?: number;
+  actual?: number;
+  cause?: unknown;
+}
+
+/** A stable, machine-readable error raised while validating or reading a ZIP. */
+export class ZipSafetyError extends Error {
+  readonly code: ZipSafetyErrorCode;
+  readonly path?: string;
+  readonly limit?: number;
+  readonly actual?: number;
+
+  constructor(code: ZipSafetyErrorCode, message: string, options: ZipSafetyErrorOptions = {}) {
+    super(message);
+    this.name = 'ZipSafetyError';
+    this.code = code;
+    this.path = options.path;
+    this.limit = options.limit;
+    this.actual = options.actual;
+    if (options.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+export interface ValidatedZipEntry {
+  path: string;
+  entry: JSZip.JSZipObject;
+  declaredSize?: number;
+  compressedSize?: number;
+  crc32?: number;
+}
+
+export interface ResolvedZipSafetyLimits {
+  maxEntries: number;
+  maxEntryUncompressedBytes: number;
+  maxUncompressedBytes: number;
+  maxCompressionRatio: number;
+}
+
+export const DEFAULT_MAX_ZIP_ENTRIES = 10_000;
+export const DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+export const DEFAULT_MAX_ZIP_COMPRESSION_RATIO = 1_000;
+
+/**
+ * Validate central-directory metadata before any member is decompressed.
+ * JSZip normalizes traversal names, so inspect `unsafeOriginalName` too.
+ */
+export function validateZipArchive(zip: JSZip, limits: ZipSafetyLimits = {}): ValidatedZipEntry[] {
+  throwIfZipAborted(limits.signal);
+  const resolved = resolveZipSafetyLimits(limits);
+  const files: ValidatedZipEntry[] = [];
+  let memberCount = 0;
+  let declaredTotal = 0;
+  let oversizedEntry: { path: string; actual: number; limit: number } | undefined;
+
+  zip.forEach((relativePath, entry) => {
+    throwIfZipAborted(limits.signal);
+    memberCount++;
+    if (entry.dir) return;
+    const originalPath = originalEntryPath(entry, relativePath);
+    if (!isSafeArchivePath(originalPath)) {
+      throw new ZipSafetyError(
+        'unsafe-path',
+        `ZIP import: archive contains an unsafe path: ${originalPath}.`,
+        { path: originalPath },
+      );
+    }
+
+    const metadata = compressedMetadata(entry, originalPath);
+    if (
+      metadata.uncompressedSize !== undefined &&
+      metadata.uncompressedSize > resolved.maxEntryUncompressedBytes
+    ) {
+      oversizedEntry ??= {
+        path: originalPath,
+        actual: metadata.uncompressedSize,
+        limit: resolved.maxEntryUncompressedBytes,
+      };
+    }
+
+    const ratio =
+      metadata.uncompressedSize === undefined || metadata.compressedSize === undefined
+        ? undefined
+        : compressionRatio(metadata.uncompressedSize, metadata.compressedSize);
+    if (ratio !== undefined && ratio > resolved.maxCompressionRatio) {
+      throw compressionRatioError(originalPath, ratio, resolved.maxCompressionRatio);
+    }
+
+    declaredTotal += metadata.uncompressedSize ?? 0;
+    if (!Number.isSafeInteger(declaredTotal)) throw invalidMetadataError(originalPath);
+    files.push({
+      path: relativePath,
+      entry,
+      ...(metadata.uncompressedSize !== undefined
+        ? { declaredSize: metadata.uncompressedSize }
+        : {}),
+      ...(metadata.compressedSize !== undefined ? { compressedSize: metadata.compressedSize } : {}),
+      ...(metadata.crc32 !== undefined ? { crc32: metadata.crc32 } : {}),
+    });
+  });
+
+  if (memberCount > resolved.maxEntries) {
+    throw tooManyEntriesError(memberCount, resolved.maxEntries);
+  }
+  if (declaredTotal > resolved.maxUncompressedBytes) {
+    throw archiveTooLargeError(declaredTotal, resolved.maxUncompressedBytes);
+  }
+  if (oversizedEntry) {
+    throw entryTooLargeError(oversizedEntry.path, oversizedEntry.actual, oversizedEntry.limit);
+  }
+  return files;
+}
+
+/** Preserve the caller's exact cancellation reason across ZIP/OOXML layers. */
+export function throwIfZipAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason ?? new Error('ZIP operation was cancelled');
+}
+
+/** Reject a path that could be interpreted outside an archive's logical root. */
+export function assertSafeZipPath(path: string): void {
+  if (!isSafeArchivePath(path)) {
+    throw new ZipSafetyError('unsafe-path', `ZIP archive path is unsafe: ${path}.`, { path });
+  }
+}
+
+export function resolveZipSafetyLimits(limits: ZipSafetyLimits): ResolvedZipSafetyLimits {
+  const maxEntries = limits.maxEntries ?? DEFAULT_MAX_ZIP_ENTRIES;
+  const maxUncompressedBytes = limits.maxUncompressedBytes ?? DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES;
+  const maxEntryUncompressedBytes = limits.maxEntryUncompressedBytes ?? maxUncompressedBytes;
+  const maxCompressionRatio = limits.maxCompressionRatio ?? DEFAULT_MAX_ZIP_COMPRESSION_RATIO;
+
+  assertNonNegativeInteger('maxEntries', maxEntries);
+  assertNonNegativeFinite('maxUncompressedBytes', maxUncompressedBytes);
+  assertNonNegativeFinite('maxEntryUncompressedBytes', maxEntryUncompressedBytes);
+  if (!Number.isFinite(maxCompressionRatio) || maxCompressionRatio < 1) {
+    throw invalidLimitError(
+      'maxCompressionRatio must be a finite number greater than or equal to 1',
+    );
+  }
+  return {
+    maxEntries,
+    maxEntryUncompressedBytes,
+    maxUncompressedBytes,
+    maxCompressionRatio,
+  };
+}
+
+export function assertNonNegativeFinite(name: string, value: number): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw invalidLimitError(`${name} must be a non-negative finite number`);
+  }
+}
+
+export function entryTooLargeError(path: string, actual: number, limit: number): ZipSafetyError {
+  return new ZipSafetyError(
+    'entry-too-large',
+    `ZIP import: archive member ${path} exceeds ${limit} byte per-entry limit.`,
+    { path, limit, actual },
+  );
+}
+
+export function tooManyEntriesError(actual: number, limit: number): ZipSafetyError {
+  return new ZipSafetyError(
+    'too-many-entries',
+    `ZIP import: archive has ${actual} files; limit is ${limit}.`,
+    { limit, actual },
+  );
+}
+
+export function archiveTooLargeError(actual: number, limit: number): ZipSafetyError {
+  return new ZipSafetyError(
+    'archive-too-large',
+    `ZIP import: uncompressed content exceeds ${limit} byte limit.`,
+    { limit, actual },
+  );
+}
+
+export function compressionRatioError(path: string, actual: number, limit: number): ZipSafetyError {
+  return new ZipSafetyError(
+    'compression-ratio-exceeded',
+    `ZIP import: archive member ${path} exceeds ${limit}:1 compression-ratio limit.`,
+    { path, limit, actual },
+  );
+}
+
+export function compressionRatio(uncompressedBytes: number, compressedBytes: number): number {
+  if (uncompressedBytes === 0) return 0;
+  if (compressedBytes === 0) return Number.POSITIVE_INFINITY;
+  return uncompressedBytes / compressedBytes;
+}
+
+function assertNonNegativeInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw invalidLimitError(`${name} must be a non-negative integer`);
+  }
+}
+
+function invalidLimitError(detail: string): ZipSafetyError {
+  return new ZipSafetyError('invalid-limit', `ZIP import: ${detail}.`);
+}
+
+function originalEntryPath(entry: JSZip.JSZipObject, relativePath: string): string {
+  return (
+    (
+      entry as JSZip.JSZipObject & {
+        unsafeOriginalName?: string;
+      }
+    ).unsafeOriginalName ?? relativePath
+  );
+}
+
+function compressedMetadata(
+  entry: JSZip.JSZipObject,
+  path: string,
+): { uncompressedSize?: number; compressedSize?: number; crc32?: number } {
+  const data = (
+    entry as unknown as {
+      _data?: { uncompressedSize?: number; compressedSize?: number; crc32?: number };
+    }
+  )._data;
+  const uncompressedSize = data?.uncompressedSize;
+  const compressedSize = data?.compressedSize;
+  const crc32 = data?.crc32;
+  if (
+    (uncompressedSize !== undefined && !isValidMetadataInteger(uncompressedSize)) ||
+    (compressedSize !== undefined && !isValidMetadataInteger(compressedSize)) ||
+    (crc32 !== undefined && !Number.isInteger(crc32))
+  ) {
+    throw invalidMetadataError(path);
+  }
+  return {
+    ...(uncompressedSize !== undefined ? { uncompressedSize } : {}),
+    ...(compressedSize !== undefined ? { compressedSize } : {}),
+    ...(crc32 !== undefined ? { crc32 } : {}),
+  };
+}
+
+function isValidMetadataInteger(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function invalidMetadataError(path: string): ZipSafetyError {
+  return new ZipSafetyError(
+    'invalid-entry-metadata',
+    `ZIP import: archive member has invalid size or checksum metadata: ${path}.`,
+    { path },
+  );
+}
+
+function isSafeArchivePath(path: string): boolean {
+  const segments = path.split('/');
+  return !(
+    path.startsWith('/') ||
+    /^[a-zA-Z]:[\\/]/.test(path) ||
+    path.includes('\\') ||
+    Array.from(path).some((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint < 0x20 || codePoint === 0x7f;
+    }) ||
+    segments.some((segment) => segment === '' || segment === '.' || segment === '..')
+  );
+}

package/src/shared/zipSafety.ts

@@ -0,0 +1,19 @@
+/** Stable facade for ZIP validation and bounded JSZip member reads. */
+
+export {
+  ZipSafetyError,
+  DEFAULT_MAX_ZIP_ENTRIES,
+  DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES,
+  DEFAULT_MAX_ZIP_COMPRESSION_RATIO,
+  assertSafeZipPath,
+  validateZipArchive,
+} from './zipLimits.js';
+export type {
+  ZipSafetyLimits,
+  ZipSafetyErrorCode,
+  ZipSafetyErrorOptions,
+  ValidatedZipEntry,
+} from './zipLimits.js';
+
+export { createBoundedZipArchive, openBoundedZipArchive } from './boundedZipArchive.js';
+export type { BoundedZipArchive } from './boundedZipArchive.js';

package/src/xlsx/import.ts

@@ -16,10 +16,11 @@ import type {
   MarkdownTableRow,
 } from '@bendyline/squisq/markdown';
 import { getPartXml, getPartRelationships, openPackage } from '../ooxml/reader.js';
+import type { OoxmlOpenOptions } from '../ooxml/reader.js';
 import type { OoxmlPackage } from '../ooxml/types.js';
 import { NS_R, NS_SML } from '../ooxml/namespaces.js';
 
-export interface XlsxImportOptions {
+export interface XlsxImportOptions extends OoxmlOpenOptions {
   /** Which sheet to import (0-based index or sheet name). Default: all sheets. */
   sheet?: number | string;
 }
@@ -133,7 +134,7 @@ export async function xlsxToMarkdownDoc(
   data: ArrayBuffer | Blob,
   options: XlsxImportOptions = {},
 ): Promise<MarkdownDocument> {
-  const pkg = await openPackage(data);
+  const pkg = await openPackage(data, options);
   const sheets = await readSheets(pkg);
   const shared = await readSharedStrings(pkg);