@oh-my-pi/pi-utils 17.4.0 → 17.4.2

package/src/browsers.ts

@@ -4,17 +4,10 @@ import type * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import * as zlib from "node:zlib";
+import { extractArchive } from "./ar";
 
 const CHROME_FOR_TESTING_BASE_URL = "https://storage.googleapis.com/chrome-for-testing-public";
 const CHROME_METADATA_BASE_URL = "https://googlechromelabs.github.io/chrome-for-testing";
-const ZIP_LOCAL_FILE_HEADER = 0x04034b50;
-const ZIP_CENTRAL_DIRECTORY_HEADER = 0x02014b50;
-const ZIP_END_OF_CENTRAL_DIRECTORY = 0x06054b50;
-const ZIP_DIRECTORY_MODE = 0o040000;
-const ZIP_REGULAR_FILE_MODE = 0o100000;
-const ZIP_SYMLINK_MODE = 0o120000;
-const ZIP_FILE_TYPE_MASK = 0o170000;
 
 /** Supported browser products. */
 export enum Browser {
@@ -104,16 +97,6 @@ interface PatchVersions {
 	builds: Record<string, { version: string }>;
 }
 
-interface ZipEntry {
-	name: string;
-	method: number;
-	crc: number;
-	compressedSize: number;
-	uncompressedSize: number;
-	externalAttributes: number;
-	localHeaderOffset: number;
-}
-
 /** Detect the current host's Puppeteer browser platform. */
 export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	const platform = os.platform();
@@ -259,7 +242,7 @@ export async function install(options: InstallOptions): Promise<InstalledBrowser
 			archivePath,
 			options.downloadProgressCallback,
 		);
-		await extractZipArchive(archivePath, stagingPath);
+		await extractArchive(archivePath, stagingPath);
 		await fsp.mkdir(path.dirname(installPath), { recursive: true });
 		await fsp.rm(installPath, { recursive: true, force: true });
 		await fsp.rename(stagingPath, installPath);
@@ -369,133 +352,3 @@ async function downloadArchive(
 		await file.close();
 	}
 }
-
-async function extractZipArchive(archivePath: string, destination: string): Promise<void> {
-	const archive = await fsp.readFile(archivePath);
-	const entries = readCentralDirectory(archive);
-	await fsp.mkdir(destination, { recursive: true });
-	const root = path.resolve(destination);
-	for (const entry of entries) {
-		const outputPath = safeArchivePath(root, entry.name);
-		const mode = entry.externalAttributes >>> 16;
-		const type = mode & ZIP_FILE_TYPE_MASK;
-		if (entry.name.endsWith("/") || type === ZIP_DIRECTORY_MODE) {
-			await fsp.mkdir(outputPath, { recursive: true });
-			if (mode & 0o777) await fsp.chmod(outputPath, mode & 0o777);
-			continue;
-		}
-
-		const contents = readZipEntry(archive, entry);
-		await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-		if (type === ZIP_SYMLINK_MODE) {
-			const target = contents.toString("utf8");
-			validateSymlinkTarget(root, outputPath, target);
-			await fsp.symlink(target, outputPath);
-			continue;
-		}
-		await fsp.writeFile(outputPath, contents, { mode: mode & 0o777 ? mode & 0o777 : 0o644 });
-		if ((mode & ZIP_FILE_TYPE_MASK) === ZIP_REGULAR_FILE_MODE && mode & 0o777)
-			await fsp.chmod(outputPath, mode & 0o777);
-	}
-}
-
-function readCentralDirectory(archive: Buffer): ZipEntry[] {
-	const minimumOffset = Math.max(0, archive.length - 65_557);
-	let endOffset = -1;
-	for (let offset = archive.length - 22; offset >= minimumOffset; offset--) {
-		if (archive.readUInt32LE(offset) === ZIP_END_OF_CENTRAL_DIRECTORY) {
-			endOffset = offset;
-			break;
-		}
-	}
-	if (endOffset < 0) throw new Error("Invalid ZIP archive: central directory was not found");
-	const disk = archive.readUInt16LE(endOffset + 4);
-	const centralDisk = archive.readUInt16LE(endOffset + 6);
-	const entryCount = archive.readUInt16LE(endOffset + 10);
-	const centralSize = archive.readUInt32LE(endOffset + 12);
-	const centralOffset = archive.readUInt32LE(endOffset + 16);
-	if (disk !== 0 || centralDisk !== 0) throw new Error("Multi-disk ZIP archives are not supported");
-	if (entryCount === 0xffff || centralSize === 0xffffffff || centralOffset === 0xffffffff) {
-		throw new Error("ZIP64 archives are not supported");
-	}
-	if (centralOffset + centralSize > endOffset)
-		throw new Error("Invalid ZIP archive: central directory is out of bounds");
-
-	const entries: ZipEntry[] = [];
-	let offset = centralOffset;
-	for (let index = 0; index < entryCount; index++) {
-		if (offset + 46 > archive.length || archive.readUInt32LE(offset) !== ZIP_CENTRAL_DIRECTORY_HEADER) {
-			throw new Error("Invalid ZIP archive: malformed central directory entry");
-		}
-		const flags = archive.readUInt16LE(offset + 8);
-		if (flags & 1) throw new Error("Encrypted ZIP entries are not supported");
-		const nameLength = archive.readUInt16LE(offset + 28);
-		const extraLength = archive.readUInt16LE(offset + 30);
-		const commentLength = archive.readUInt16LE(offset + 32);
-		const end = offset + 46 + nameLength + extraLength + commentLength;
-		if (end > archive.length) throw new Error("Invalid ZIP archive: truncated central directory entry");
-		entries.push({
-			name: archive.subarray(offset + 46, offset + 46 + nameLength).toString("utf8"),
-			method: archive.readUInt16LE(offset + 10),
-			crc: archive.readUInt32LE(offset + 16),
-			compressedSize: archive.readUInt32LE(offset + 20),
-			uncompressedSize: archive.readUInt32LE(offset + 24),
-			externalAttributes: archive.readUInt32LE(offset + 38),
-			localHeaderOffset: archive.readUInt32LE(offset + 42),
-		});
-		offset = end;
-	}
-	return entries;
-}
-
-function readZipEntry(archive: Buffer, entry: ZipEntry): Buffer {
-	const offset = entry.localHeaderOffset;
-	if (offset + 30 > archive.length || archive.readUInt32LE(offset) !== ZIP_LOCAL_FILE_HEADER) {
-		throw new Error(`Invalid ZIP archive: malformed local header for ${entry.name}`);
-	}
-	const nameLength = archive.readUInt16LE(offset + 26);
-	const extraLength = archive.readUInt16LE(offset + 28);
-	const start = offset + 30 + nameLength + extraLength;
-	const end = start + entry.compressedSize;
-	if (end > archive.length) throw new Error(`Invalid ZIP archive: truncated data for ${entry.name}`);
-	const compressed = archive.subarray(start, end);
-	let contents: Buffer;
-	if (entry.method === 0) contents = Buffer.from(compressed);
-	else if (entry.method === 8) contents = zlib.inflateRawSync(compressed);
-	else throw new Error(`Unsupported ZIP compression method ${entry.method} for ${entry.name}`);
-	if (contents.length !== entry.uncompressedSize)
-		throw new Error(`Invalid uncompressed size for ZIP entry ${entry.name}`);
-	if (crc32(contents) !== entry.crc) throw new Error(`CRC mismatch for ZIP entry ${entry.name}`);
-	return contents;
-}
-
-function safeArchivePath(root: string, name: string): string {
-	if (!name || name.includes("\0") || name.startsWith("/") || name.startsWith("\\") || /^[A-Za-z]:/.test(name)) {
-		throw new Error(`Unsafe path in ZIP archive: ${name}`);
-	}
-	const segments = name.replaceAll("\\", "/").split("/");
-	if (segments.some(segment => segment === "..")) throw new Error(`Unsafe path in ZIP archive: ${name}`);
-	const target = path.resolve(root, ...segments.filter(Boolean));
-	if (target !== root && !target.startsWith(`${root}${path.sep}`))
-		throw new Error(`Unsafe path in ZIP archive: ${name}`);
-	return target;
-}
-
-function validateSymlinkTarget(root: string, linkPath: string, target: string): void {
-	if (!target || target.includes("\0") || path.isAbsolute(target) || /^[A-Za-z]:/.test(target)) {
-		throw new Error(`Unsafe symlink target in ZIP archive: ${target}`);
-	}
-	const resolved = path.resolve(path.dirname(linkPath), target);
-	if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
-		throw new Error(`Unsafe symlink target in ZIP archive: ${target}`);
-	}
-}
-
-function crc32(contents: Uint8Array): number {
-	let crc = 0xffffffff;
-	for (const byte of contents) {
-		crc ^= byte;
-		for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
-	}
-	return (crc ^ 0xffffffff) >>> 0;
-}

package/src/docx/converter.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { archiveEntryText, readArchiveEntries } from "../ar";
 import { attribute, childElements, descendants, firstChild, localName, parseXml, type XmlElement } from "./xml";
-import { readZip, readZipText, type ZipEntries } from "./zip";
 
 /** A mammoth-compatible diagnostic emitted while converting a document. */
 export interface DocxMessage {
@@ -119,7 +119,7 @@ interface NumberingLevel {
 }
 
 interface ConversionContext {
-	readonly entries: ZipEntries;
+	readonly entries: ReadonlyMap<string, Uint8Array>;
 	readonly relationships: ReadonlyMap<string, Relationship>;
 	readonly contentTypes: ReadonlyMap<string, string>;
 	readonly styles: ReadonlyMap<string, Style>;
@@ -655,21 +655,21 @@ function defaultImageConverter(): ImageConverter {
 /** Convert a DOCX buffer or path to mammoth-compatible HTML. */
 export async function convertToHtml(input: DocxInput, options: ConvertToHtmlOptions = {}): Promise<DocxResult> {
 	const bytes = "buffer" in input && input.buffer ? input.buffer : await fs.readFile(input.path);
-	const entries = readZip(bytes);
-	const documentXml = readZipText(entries, "word/document.xml");
+	const entries = await readArchiveEntries({ bytes, format: "zip" });
+	const documentXml = archiveEntryText(entries, "word/document.xml");
 	if (!documentXml) throw new Error("Invalid DOCX: missing word/document.xml");
 	const context: ConversionContext = {
 		entries,
-		relationships: parseRelationships(readZipText(entries, "word/_rels/document.xml.rels")),
-		contentTypes: parseContentTypes(readZipText(entries, "[Content_Types].xml")),
-		styles: parseStyles(readZipText(entries, "word/styles.xml")),
-		numbering: parseNumbering(readZipText(entries, "word/numbering.xml")),
+		relationships: parseRelationships(archiveEntryText(entries, "word/_rels/document.xml.rels")),
+		contentTypes: parseContentTypes(archiveEntryText(entries, "[Content_Types].xml")),
+		styles: parseStyles(archiveEntryText(entries, "word/styles.xml")),
+		numbering: parseNumbering(archiveEntryText(entries, "word/numbering.xml")),
 		messages: [],
 		warnedStyles: new Set(),
 		customStyles: parseCustomStyles(options.styleMap),
 		includeDefaultStyleMap: options.includeDefaultStyleMap !== false,
 		convertImage: options.convertImage ?? defaultImageConverter(),
-		footnotes: parseFootnotes(readZipText(entries, "word/footnotes.xml")),
+		footnotes: parseFootnotes(archiveEntryText(entries, "word/footnotes.xml")),
 		usedFootnotes: [],
 		footnoteOrdinals: new Map(),
 	};

package/src/postmortem.ts

@@ -146,6 +146,66 @@ export function isIpcSendEpipe(err: Error): boolean {
 	return classifyBrokenPipe(err) === "ipc-send";
 }
 
+/**
+ * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
+ *
+ * When a worker subprocess spawned with `serialization: "advanced"` sends a
+ * malformed or truncated frame, Bun raises the decode failure as a
+ * process-level `uncaughtException` in the *parent* rather than routing it to
+ * the channel's `ipc()` callback (oven-sh/bun#37287). The error is a bare
+ * `TypeError: Unable to deserialize data.` whose only own property is `message`
+ * — it carries no `code`, no `syscall`, and no `stack`. Matching all four traits
+ * keeps unrelated application `TypeError`s (which always carry a populated
+ * multi-frame stack) on the fatal path, so a genuine bug is never silently
+ * swallowed.
+ *
+ * Every advanced-serialization channel in this process is an optional worker
+ * subsystem (TTS, STT, tiny-title, mnemopi embeddings, JS eval), so one
+ * worker's bad frame must fault only that worker — via its own `onExit`/error
+ * path — never tear down the whole session. Callers log-and-continue instead of
+ * taking the fatal path. Mirrors {@link classifyBrokenPipe} for the send side
+ * (#2997, #9158).
+ */
+export function isWorkerIpcDeserializeError(err: unknown): boolean {
+	return (
+		err instanceof TypeError &&
+		err.message === "Unable to deserialize data." &&
+		!err.stack &&
+		!("code" in err) &&
+		!("syscall" in err)
+	);
+}
+
+/** Recycle callbacks for the active advanced-serialization worker IPC channels. */
+const workerIpcFaultHandlers = new Set<(err: Error) => void>();
+
+/**
+ * Register a fault/recycle callback for an active advanced-serialization worker
+ * IPC channel.
+ *
+ * Bun surfaces a malformed frame as a process-global `uncaughtException`
+ * ({@link isWorkerIpcDeserializeError}) with no way to attribute it to a
+ * specific channel, so when one fires every registered handler is invoked to
+ * conservatively fault its worker — reject in-flight requests and recycle the
+ * subprocess — instead of leaving pending work to await forever. Returns an
+ * unregister function; callers MUST unregister when the worker exits.
+ */
+export function registerWorkerIpcFaultHandler(handler: (err: Error) => void): () => void {
+	workerIpcFaultHandlers.add(handler);
+	return () => workerIpcFaultHandlers.delete(handler);
+}
+
+/** Invoke every registered worker IPC fault handler, isolating handler throws. */
+function faultWorkerIpcChannels(err: Error): void {
+	for (const handler of workerIpcFaultHandlers) {
+		try {
+			handler(err);
+		} catch (handlerErr) {
+			logger.warn("Worker IPC fault handler threw", { err: handlerErr });
+		}
+	}
+}
+
 /**
  * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
  *
@@ -283,6 +343,20 @@ if (isMainThread) {
 				logger.warn("Ignoring expected cleanup exception", { err });
 				return;
 			}
+			// A malformed advanced-serialization frame from a worker subprocess
+			// surfaces here as a process-level uncaughtException (oven-sh/bun#37287)
+			// rather than in the channel's ipc() callback, and Bun gives no way to
+			// tell which channel produced it. Contain it to the worker layer: keep
+			// the session alive and conservatively fault every active advanced-IPC
+			// worker so its owning client rejects in-flight requests and recycles
+			// the subprocess — a worker that sent a bad frame but stays alive would
+			// otherwise never fire onExit and leave callers awaiting forever.
+			// Mirrors the ipc-send EPIPE containment below (#9158, #2997).
+			if (isWorkerIpcDeserializeError(err)) {
+				logger.warn("Malformed worker IPC frame; faulting active worker subsystems", { err });
+				faultWorkerIpcChannels(err);
+				return;
+			}
 			await exitAfterFatal("Uncaught Exception", "Uncaught exception", err, Reason.UNCAUGHT_EXCEPTION);
 		})
 		.on("unhandledRejection", async reason => {

package/dist/types/docx/zip.d.ts

@@ -1,6 +0,0 @@
-/** The decompressed members of a DOCX ZIP package. */
-export type ZipEntries = ReadonlyMap<string, Uint8Array>;
-/** Decode a ZIP package by walking its central directory. */
-export declare function readZip(bytes: Uint8Array): ZipEntries;
-/** Decode a ZIP member as UTF-8 text. */
-export declare function readZipText(entries: ZipEntries, name: string): string | undefined;

package/src/docx/zip.ts

@@ -1,87 +0,0 @@
-import * as zlib from "node:zlib";
-
-const LOCAL_FILE_SIGNATURE = 0x04034b50;
-const CENTRAL_FILE_SIGNATURE = 0x02014b50;
-const END_SIGNATURE = 0x06054b50;
-const MAX_END_SEARCH = 65_557;
-const UTF8 = new TextDecoder();
-
-/** The decompressed members of a DOCX ZIP package. */
-export type ZipEntries = ReadonlyMap<string, Uint8Array>;
-
-function view(bytes: Uint8Array): DataView {
-	return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-}
-
-function findEndRecord(bytes: Uint8Array): number {
-	const data = view(bytes);
-	for (
-		let offset = bytes.byteLength - 22, limit = Math.max(0, bytes.byteLength - MAX_END_SEARCH);
-		offset >= limit;
-		offset--
-	) {
-		if (data.getUint32(offset, true) === END_SIGNATURE) return offset;
-	}
-	throw new Error("Invalid DOCX: missing ZIP end record");
-}
-
-/** Decode a ZIP package by walking its central directory. */
-export function readZip(bytes: Uint8Array): ZipEntries {
-	if (bytes.byteLength < 22) throw new Error("Invalid DOCX: truncated ZIP package");
-	const data = view(bytes);
-	const endOffset = findEndRecord(bytes);
-	const entryCount = data.getUint16(endOffset + 10, true);
-	const centralSize = data.getUint32(endOffset + 12, true);
-	const centralOffset = data.getUint32(endOffset + 16, true);
-	if (entryCount === 0xffff || centralSize === 0xffffffff || centralOffset === 0xffffffff) {
-		throw new Error("Invalid DOCX: ZIP64 packages are not supported");
-	}
-	if (centralOffset + centralSize > bytes.byteLength) throw new Error("Invalid DOCX: truncated ZIP central directory");
-	const entries = new Map<string, Uint8Array>();
-	let offset = centralOffset;
-	for (let index = 0; index < entryCount; index++) {
-		if (offset + 46 > bytes.byteLength || data.getUint32(offset, true) !== CENTRAL_FILE_SIGNATURE) {
-			throw new Error("Invalid DOCX: malformed ZIP central directory");
-		}
-		const flags = data.getUint16(offset + 8, true);
-		const method = data.getUint16(offset + 10, true);
-		const compressedSize = data.getUint32(offset + 20, true);
-		const uncompressedSize = data.getUint32(offset + 24, true);
-		const nameLength = data.getUint16(offset + 28, true);
-		const extraLength = data.getUint16(offset + 30, true);
-		const commentLength = data.getUint16(offset + 32, true);
-		const localOffset = data.getUint32(offset + 42, true);
-		const entryEnd = offset + 46 + nameLength + extraLength + commentLength;
-		if (entryEnd > bytes.byteLength) throw new Error("Invalid DOCX: truncated ZIP entry");
-		const name = UTF8.decode(bytes.subarray(offset + 46, offset + 46 + nameLength)).replaceAll("\\", "/");
-		if ((flags & 1) !== 0) throw new Error(`Invalid DOCX: encrypted ZIP member ${name}`);
-		if (localOffset + 30 > bytes.byteLength || data.getUint32(localOffset, true) !== LOCAL_FILE_SIGNATURE) {
-			throw new Error(`Invalid DOCX: missing local header for ${name}`);
-		}
-		const localNameLength = data.getUint16(localOffset + 26, true);
-		const localExtraLength = data.getUint16(localOffset + 28, true);
-		const payloadOffset = localOffset + 30 + localNameLength + localExtraLength;
-		const payloadEnd = payloadOffset + compressedSize;
-		if (payloadEnd > bytes.byteLength) throw new Error(`Invalid DOCX: truncated ZIP member ${name}`);
-		const compressed = bytes.subarray(payloadOffset, payloadEnd);
-		let decoded: Uint8Array;
-		if (method === 0) {
-			decoded = compressed;
-		} else if (method === 8) {
-			decoded = zlib.inflateRawSync(compressed, { maxOutputLength: Math.max(uncompressedSize, 1) });
-		} else {
-			throw new Error(`Invalid DOCX: unsupported ZIP compression method ${method}`);
-		}
-		if (decoded.byteLength !== uncompressedSize)
-			throw new Error(`Invalid DOCX: size mismatch for ZIP member ${name}`);
-		if (name && !name.endsWith("/")) entries.set(name, decoded);
-		offset = entryEnd;
-	}
-	return entries;
-}
-
-/** Decode a ZIP member as UTF-8 text. */
-export function readZipText(entries: ZipEntries, name: string): string | undefined {
-	const bytes = entries.get(name);
-	return bytes ? UTF8.decode(bytes) : undefined;
-}