archive-codec 1.5.0 → 1.6.0

package/README.md

@@ -10,9 +10,11 @@ Created for [documents.js#564](https://github.com/ExaDev/documents.js/issues/564
 
 [documents.js#815](https://github.com/ExaDev/documents.js/issues/815), [#816](https://github.com/ExaDev/documents.js/issues/816), and [#817](https://github.com/ExaDev/documents.js/issues/817) then needed the other direction. `xls-codec`, `doc-codec`, `ppt-codec`, and `wpd-codec` each read a legacy Office binary format out of an [MS-CFB] container, and none of them can write one back, because there was no container to put their streams into: a `.xls` writer producing a `Workbook` stream, or a `.doc` writer producing `WordDocument` and `1Table`, needs a conformant compound file to hold them. That container is structural knowledge exactly as the reader's is, so `writeCompoundFile` is the mirror of `readCompoundFile` here rather than four hand-rolled emitters in four codecs.
 
+[documents.js#974](https://github.com/ExaDev/documents.js/issues/974) added the other half of the OLE Package stream: `writeOlePackage`, the mirror of `readOlePackage`, for `rtf-codec`'s own OLE embedding -- an RTF `\object`'s `\objdata` is the hex bytes of a real [MS-CFB] compound file wrapping a `Package` stream, so writing one needed both halves this package already had separately (`writeCompoundFile` for the container, `readOlePackage` for the stream inside it) plus the write side of the stream itself.
+
 [documents.js#815](https://github.com/ExaDev/documents.js/issues/815), [#816](https://github.com/ExaDev/documents.js/issues/816), and [#817](https://github.com/ExaDev/documents.js/issues/817) also each named the same remaining gap: `doc-codec`, `xls-codec`, and `ppt-codec` all hard-coded document metadata (title, author, dates) to an empty object, because that metadata lives in a genuinely different structure from the one each format's own reader already parses -- a [MS-OLEPS] Property Set Stream, conventionally stored as a "\x05SummaryInformation" stream beside `WordDocument`/`Workbook`/`PowerPoint Document` in the identical [MS-CFB] container all three already read through this package. `oleps/read` and `oleps/write` are the generic property-set codec (the stream header, the PropertySet packet's dictionary, and VT_I2/VT_I4/VT_LPSTR/VT_LPWSTR/VT_FILETIME typed values), and `oleps/summary-information` is the SummaryInformation-specific mapping on top of it -- the same two-layer split `cfb/read.ts` and `cfb/ole-package.ts` already establish for the OLE Package stream, container structure below, one named stream's own field layout above.
 
-Scope: **ZIP containers** (read and write over [`fflate`](https://github.com/101arrowz/fflate), recursive walking of ZIP-in-ZIP entries), **classic OLE compound files** (bounded [MS-CFB] reading and conformant [MS-CFB] writing, plus the OLE Package stream unwrapping), and **[MS-OLEPS] Property Set Streams** (generic read/write of a single-property-set stream, plus SummaryInformation's own title/subject/author/keywords/comments/created/last-saved/last-printed fields). **tar and gzip, DocumentSummaryInformation's extended and user-defined property sets, and writing VT_LPSTR (ANSI-codepage) string properties are explicitly out of scope.**
+Scope: **ZIP containers** (read and write over [`fflate`](https://github.com/101arrowz/fflate), recursive walking of ZIP-in-ZIP entries), **classic OLE compound files** (bounded [MS-CFB] reading and conformant [MS-CFB] writing, plus OLE Package stream reading and writing), and **[MS-OLEPS] Property Set Streams** (generic read/write of a single-property-set stream, plus SummaryInformation's own title/subject/author/keywords/comments/created/last-saved/last-printed fields). **tar and gzip, DocumentSummaryInformation's extended and user-defined property sets, and writing VT_LPSTR (ANSI-codepage) string properties are explicitly out of scope.**
 
 ## Getting started
 
@@ -50,7 +52,7 @@ The smoke suite (`test/smoke.test.mjs`) is the guard on that advertisement: it l
 | `cfb/detect`                | `isCompoundFile` (the `D0 CF 11 E0 …` magic-byte check)                                                                                                                                                                                                                                 |
 | `cfb/read`                  | `readCompoundFile` (bounded [MS-CFB] stream extraction), `CompoundFileStream`, `CompoundFileFormatError`, `MAX_CFB_TOTAL_STREAM_BYTES`, `ReadCompoundFileOptions`                                                                                                                       |
 | `cfb/write`                 | `writeCompoundFile` ([MS-CFB] container generation), `CompoundFileWriteError`, `WriteCompoundFileOptions` — takes the `CompoundFileStream` array `cfb/read` returns                                                                                                                     |
-| `cfb/ole-package`           | `readOlePackage` (OLE Package stream unwrapping), `OlePackage`, `OlePackageFormatError`                                                                                                                                                                                                 |
+| `cfb/ole-package`           | `readOlePackage` (OLE Package stream unwrapping), `writeOlePackage` (the mirror), `OlePackage`, `OlePackageFormatError`, `OlePackageWriteError`                                                                                                                                         |
 | `oleps/read`                | `readPropertySetStream` (generic [MS-OLEPS] property-set decoding), `PropertySetFormatError`                                                                                                                                                                                            |
 | `oleps/write`               | `writePropertySetStream` (generic [MS-OLEPS] property-set encoding), `PropertySetWriteError` — takes the `PropertySet` shape `oleps/read` returns                                                                                                                                       |
 | `oleps/summary-information` | `readSummaryInformation`, `writeSummaryInformationStream`, `SummaryInformationProperties`, `FMTID_SUMMARY_INFORMATION`                                                                                                                                                                  |
@@ -76,7 +78,12 @@ Both guards throw rather than truncate: an input outside the contract must fail
 ### Compound files
 
 ```ts
-import { readCompoundFile, readOlePackage } from "archive-codec";
+import {
+  readCompoundFile,
+  readOlePackage,
+  writeCompoundFile,
+  writeOlePackage,
+} from "archive-codec";
 
 // Every stream of a classic OLE compound file, with its storage path.
 // Throws CompoundFileFormatError on any structural nonconformance.
@@ -93,6 +100,19 @@ const packageStream = readCompoundFile(oleBinBytes).find(
 if (packageStream !== undefined) {
   readOlePackage(packageStream.bytes).fileBytes; // often a ZIP for a modern embed
 }
+
+// The mirror image: builds a 'Package' stream's bytes from the same shape
+// readOlePackage returns, to wrap alongside writeCompoundFile -- this is how
+// rtf-codec builds the real [MS-CFB] container an RTF \object's \objdata carries.
+const packageBytes = writeOlePackage({
+  label: "embedded.docx",
+  sourcePath: "",
+  tempPath: "",
+  fileBytes: embeddedFileBytes,
+});
+const embedBytes = writeCompoundFile([
+  { path: "Package", bytes: packageBytes },
+]);
 ```
 
 Reading is bounded the same way walking is: chain cycles and out-of-range sectors fail against bounds derived from the file's own sector count, and one cumulative extracted-bytes budget (`MAX_CFB_TOTAL_STREAM_BYTES`, 512 MiB — the same figure the family grants one decompressed stream) bounds the multiplication a hostile FAT gains by aliasing one sector into many streams. Every structural failure throws rather than truncating — a malformed compound file fails whole, never a partial stream listing that looks complete. Version 3 (512-byte sectors) and version 4 (4096-byte) files both read; the mini-FAT path every stream shorter than the header's cutoff takes is first-class, because a small real-world embed genuinely lands there.

package/dist/cfb/ole-package.cjs

@@ -37,6 +37,46 @@ function readOlePackage(bytes) {
 		fileBytes: bytes.slice(offset, offset + fileByteCount)
 	};
 }
+var OlePackageWriteError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageWriteError";
+	}
+};
+function asciiZeroTerminated(value, fieldName) {
+	const bytes = new Uint8Array(value.length + 1);
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 0) throw new OlePackageWriteError(`Package stream's ${fieldName} contains an embedded NUL byte, which this field's own null-terminated encoding cannot carry: it would silently truncate the field and mis-frame every field written after it`);
+		if (code > 127) throw new OlePackageWriteError(`Package stream's ${fieldName} contains a character (U+${code.toString(16).padStart(4, "0")}) outside ASCII; encoding it to an arbitrary windows-1252 byte would need a full codepage table this package does not carry`);
+		bytes[index] = code;
+	}
+	return bytes;
+}
+function writeOlePackage(pkg) {
+	const labelBytes = asciiZeroTerminated(pkg.label, "label");
+	const sourcePathBytes = asciiZeroTerminated(pkg.sourcePath, "source path");
+	const tempPathBytes = asciiZeroTerminated(pkg.tempPath, "temp path");
+	const totalLength = 2 + labelBytes.length + sourcePathBytes.length + 8 + tempPathBytes.length + 4 + pkg.fileBytes.length;
+	const out = new Uint8Array(totalLength);
+	const view = new DataView(out.buffer);
+	let offset = 0;
+	view.setUint16(offset, 2, true);
+	offset += 2;
+	out.set(labelBytes, offset);
+	offset += labelBytes.length;
+	out.set(sourcePathBytes, offset);
+	offset += sourcePathBytes.length;
+	offset += 8;
+	out.set(tempPathBytes, offset);
+	offset += tempPathBytes.length;
+	view.setUint32(offset, pkg.fileBytes.length, true);
+	offset += 4;
+	out.set(pkg.fileBytes, offset);
+	return out;
+}
 //#endregion
 exports.OlePackageFormatError = OlePackageFormatError;
+exports.OlePackageWriteError = OlePackageWriteError;
 exports.readOlePackage = readOlePackage;
+exports.writeOlePackage = writeOlePackage;

package/dist/cfb/ole-package.d.cts

@@ -9,5 +9,9 @@ interface OlePackage {
   readonly fileBytes: Uint8Array<ArrayBuffer>;
 }
 declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+declare class OlePackageWriteError extends Error {
+  constructor(message: string);
+}
+declare function writeOlePackage(pkg: OlePackage): Uint8Array<ArrayBuffer>;
 //#endregion
-export { OlePackage, OlePackageFormatError, readOlePackage };
+export { OlePackage, OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage };

package/dist/cfb/ole-package.d.ts

@@ -9,5 +9,9 @@ interface OlePackage {
   readonly fileBytes: Uint8Array<ArrayBuffer>;
 }
 declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+declare class OlePackageWriteError extends Error {
+  constructor(message: string);
+}
+declare function writeOlePackage(pkg: OlePackage): Uint8Array<ArrayBuffer>;
 //#endregion
-export { OlePackage, OlePackageFormatError, readOlePackage };
+export { OlePackage, OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage };

package/dist/cfb/ole-package.js

@@ -36,5 +36,43 @@ function readOlePackage(bytes) {
 		fileBytes: bytes.slice(offset, offset + fileByteCount)
 	};
 }
+var OlePackageWriteError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageWriteError";
+	}
+};
+function asciiZeroTerminated(value, fieldName) {
+	const bytes = new Uint8Array(value.length + 1);
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 0) throw new OlePackageWriteError(`Package stream's ${fieldName} contains an embedded NUL byte, which this field's own null-terminated encoding cannot carry: it would silently truncate the field and mis-frame every field written after it`);
+		if (code > 127) throw new OlePackageWriteError(`Package stream's ${fieldName} contains a character (U+${code.toString(16).padStart(4, "0")}) outside ASCII; encoding it to an arbitrary windows-1252 byte would need a full codepage table this package does not carry`);
+		bytes[index] = code;
+	}
+	return bytes;
+}
+function writeOlePackage(pkg) {
+	const labelBytes = asciiZeroTerminated(pkg.label, "label");
+	const sourcePathBytes = asciiZeroTerminated(pkg.sourcePath, "source path");
+	const tempPathBytes = asciiZeroTerminated(pkg.tempPath, "temp path");
+	const totalLength = 2 + labelBytes.length + sourcePathBytes.length + 8 + tempPathBytes.length + 4 + pkg.fileBytes.length;
+	const out = new Uint8Array(totalLength);
+	const view = new DataView(out.buffer);
+	let offset = 0;
+	view.setUint16(offset, 2, true);
+	offset += 2;
+	out.set(labelBytes, offset);
+	offset += labelBytes.length;
+	out.set(sourcePathBytes, offset);
+	offset += sourcePathBytes.length;
+	offset += 8;
+	out.set(tempPathBytes, offset);
+	offset += tempPathBytes.length;
+	view.setUint32(offset, pkg.fileBytes.length, true);
+	offset += 4;
+	out.set(pkg.fileBytes, offset);
+	return out;
+}
 //#endregion
-export { OlePackageFormatError, readOlePackage };
+export { OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage };

package/dist/index.cjs

@@ -18,6 +18,7 @@ exports.MAX_CFB_TOTAL_STREAM_BYTES = require_cfb_read.MAX_CFB_TOTAL_STREAM_BYTES
 exports.MAX_WALK_DEPTH = require_zip_walk.MAX_WALK_DEPTH;
 exports.MAX_WALK_TOTAL_BYTES = require_zip_walk.MAX_WALK_TOTAL_BYTES;
 exports.OlePackageFormatError = require_cfb_ole_package.OlePackageFormatError;
+exports.OlePackageWriteError = require_cfb_ole_package.OlePackageWriteError;
 exports.PropertySetFormatError = require_oleps_read.PropertySetFormatError;
 exports.PropertySetWriteError = require_oleps_write.PropertySetWriteError;
 exports.detectArchiveFormat = require_zip_detect.detectArchiveFormat;
@@ -33,6 +34,7 @@ exports.summaryInformationToLayoutMetadata = require_oleps_layout_metadata.summa
 exports.unzipPackage = require_zip_container.unzipPackage;
 exports.walkArchive = require_zip_walk.walkArchive;
 exports.writeCompoundFile = require_cfb_write.writeCompoundFile;
+exports.writeOlePackage = require_cfb_ole_package.writeOlePackage;
 exports.writePropertySetStream = require_oleps_write.writePropertySetStream;
 exports.writeSummaryInformationStream = require_oleps_summary_information.writeSummaryInformationStream;
 exports.zipPackage = require_zip_container.zipPackage;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { isCompoundFile } from "./cfb/detect.cjs";
-import { OlePackage, OlePackageFormatError, readOlePackage } from "./cfb/ole-package.cjs";
+import { OlePackage, OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage } from "./cfb/ole-package.cjs";
 import { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile } from "./cfb/read.cjs";
 import { CompoundFileWriteError, WriteCompoundFileOptions, writeCompoundFile } from "./cfb/write.cjs";
 import { FMTID_SUMMARY_INFORMATION, SummaryInformationProperties, readSummaryInformation, writeSummaryInformationStream } from "./oleps/summary-information.cjs";
@@ -10,4 +10,4 @@ import { PropertySetWriteError, writePropertySetStream } from "./oleps/write.cjs
 import { ZipEntry, unzipPackage, zipPackage } from "./zip/container.cjs";
 import { ArchiveFormat, detectArchiveFormat, isZipArchive } from "./zip/detect.cjs";
 import { ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, WalkArchiveOptions, walkArchive } from "./zip/walk.cjs";
-export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileStream, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackage, OlePackageFormatError, type PropertySet, PropertySetFormatError, PropertySetWriteError, type PropertyValue, ReadCompoundFileOptions, SummaryInformationProperties, WalkArchiveOptions, WriteCompoundFileOptions, ZipEntry, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writePropertySetStream, writeSummaryInformationStream, zipPackage };
+export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileStream, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackage, OlePackageFormatError, OlePackageWriteError, type PropertySet, PropertySetFormatError, PropertySetWriteError, type PropertyValue, ReadCompoundFileOptions, SummaryInformationProperties, WalkArchiveOptions, WriteCompoundFileOptions, ZipEntry, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writeOlePackage, writePropertySetStream, writeSummaryInformationStream, zipPackage };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { isCompoundFile } from "./cfb/detect.js";
-import { OlePackage, OlePackageFormatError, readOlePackage } from "./cfb/ole-package.js";
+import { OlePackage, OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage } from "./cfb/ole-package.js";
 import { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile } from "./cfb/read.js";
 import { CompoundFileWriteError, WriteCompoundFileOptions, writeCompoundFile } from "./cfb/write.js";
 import { FMTID_SUMMARY_INFORMATION, SummaryInformationProperties, readSummaryInformation, writeSummaryInformationStream } from "./oleps/summary-information.js";
@@ -10,4 +10,4 @@ import { PropertySetWriteError, writePropertySetStream } from "./oleps/write.js"
 import { ZipEntry, unzipPackage, zipPackage } from "./zip/container.js";
 import { ArchiveFormat, detectArchiveFormat, isZipArchive } from "./zip/detect.js";
 import { ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, WalkArchiveOptions, walkArchive } from "./zip/walk.js";
-export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileStream, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackage, OlePackageFormatError, type PropertySet, PropertySetFormatError, PropertySetWriteError, type PropertyValue, ReadCompoundFileOptions, SummaryInformationProperties, WalkArchiveOptions, WriteCompoundFileOptions, ZipEntry, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writePropertySetStream, writeSummaryInformationStream, zipPackage };
+export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileStream, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackage, OlePackageFormatError, OlePackageWriteError, type PropertySet, PropertySetFormatError, PropertySetWriteError, type PropertyValue, ReadCompoundFileOptions, SummaryInformationProperties, WalkArchiveOptions, WriteCompoundFileOptions, ZipEntry, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writeOlePackage, writePropertySetStream, writeSummaryInformationStream, zipPackage };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { isCompoundFile } from "./cfb/detect.js";
-import { OlePackageFormatError, readOlePackage } from "./cfb/ole-package.js";
+import { OlePackageFormatError, OlePackageWriteError, readOlePackage, writeOlePackage } from "./cfb/ole-package.js";
 import { CompoundFileFormatError, MAX_CFB_TOTAL_STREAM_BYTES, readCompoundFile } from "./cfb/read.js";
 import { CompoundFileWriteError, writeCompoundFile } from "./cfb/write.js";
 import { hasSummaryInformationFields, layoutMetadataToSummaryInformation, summaryInformationToLayoutMetadata } from "./oleps/layout-metadata.js";
@@ -9,4 +9,4 @@ import { FMTID_SUMMARY_INFORMATION, readSummaryInformation, writeSummaryInformat
 import { unzipPackage, zipPackage } from "./zip/container.js";
 import { detectArchiveFormat, isZipArchive } from "./zip/detect.js";
 import { ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, walkArchive } from "./zip/walk.js";
-export { ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackageFormatError, PropertySetFormatError, PropertySetWriteError, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writePropertySetStream, writeSummaryInformationStream, zipPackage };
+export { ArchiveWalkLimitError, CompoundFileFormatError, CompoundFileWriteError, FMTID_SUMMARY_INFORMATION, MAX_CFB_TOTAL_STREAM_BYTES, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, OlePackageFormatError, OlePackageWriteError, PropertySetFormatError, PropertySetWriteError, detectArchiveFormat, hasSummaryInformationFields, isCompoundFile, isZipArchive, layoutMetadataToSummaryInformation, readCompoundFile, readOlePackage, readPropertySetStream, readSummaryInformation, summaryInformationToLayoutMetadata, unzipPackage, walkArchive, writeCompoundFile, writeOlePackage, writePropertySetStream, writeSummaryInformationStream, zipPackage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archive-codec",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "ZIP-in-ZIP recursive walking with depth and cumulative decompressed-size guards, bounded classic OLE compound-file ([MS-CFB]) reading and writing, and [MS-OLEPS] Property Set Stream reading and writing - zero document-format knowledge, the archive and container utility package for the documents.js family.",
   "type": "module",
   "repository": {