@happyvertical/files 0.78.2 → 0.79.0

package/README.md

@@ -77,6 +77,80 @@ const buf = await fetchBuffer('https://example.com/image.png');
 await fetchToFile('https://example.com/file.zip', './downloads/file.zip');
 ```
 
+### Secure ZIP Manifest Inspection
+
+Inspect untrusted ZIP metadata before deciding whether to accept an upload:
+
+```typescript
+import {
+  inspectZipManifest,
+  ZipManifestError,
+  ZipManifestLimitError,
+} from '@happyvertical/files';
+
+try {
+  const manifest = inspectZipManifest(zipBytes, {
+    maxEntries: 2_000,
+    maxEntryUncompressedBytes: 50 * 1024 * 1024,
+    maxTotalUncompressedBytes: 500 * 1024 * 1024,
+  });
+
+  const files = manifest.entries
+    .filter((entry) => entry.type === 'file')
+    .map(({ path, size }) => ({ path, size }));
+} catch (error) {
+  if (error instanceof ZipManifestLimitError) {
+    console.error(error.limit, error.actual, error.maximum);
+  } else if (error instanceof ZipManifestError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+`inspectZipManifest()` reads and cross-checks central-directory and local-header
+metadata only. It does not decompress or materialize file bodies. Paths are
+returned with `/` separators and `.`/empty segments removed; names containing
+ordinary spaces remain valid. The whole archive is rejected for parent
+traversal, absolute/drive-qualified paths, NTFS alternate data stream paths
+containing colons, NUL bytes, Unix symlinks and special files, Windows reparse
+points and reserved device names, path segments ending in dots or spaces,
+case-insensitive or Unicode-normalization path collisions, file/descendant path
+conflicts, overlapping local entry ranges, or unreferenced data before the
+central directory.
+
+Default limits are 10,000 entries, 200 MiB per entry, 2 GiB aggregate declared
+uncompressed size, and 1,024 encoded path bytes. Entry count includes directory
+entries, and aggregate size includes every entry. All limits are configurable
+with non-negative safe integers. The entry limit also bounds cumulative
+central-directory work while disambiguating end records in hostile comments.
+
+Policy is deliberately strict: ZIP64, encrypted, multi-disk, malformed,
+truncated, ambiguous-end-record, and non-UTF-8-name archives are rejected with
+typed errors. Stored entries must also declare identical compressed and
+uncompressed sizes, and each local header and compressed payload must occupy a
+distinct range. Those referenced ranges must collectively cover every byte
+before the central directory, so archive preambles, padding gaps, and local
+entries omitted from the central directory are rejected. Data descriptors are
+rejected for both stored and compressed entries because their payload boundary
+cannot be verified without decompression or extractor-specific scanning. Entry
+names use strict UTF-8 decoding whether or not the UTF-8 flag is set. Leading
+UTF-8 BOMs are rejected because filename decoders disagree on whether the BOM
+is part of the extracted path; common macOS ZIPs with valid UTF-8 names remain
+compatible.
+PKWARE alternate-encoding, Info-ZIP, and Xceed path extra fields are rejected
+so an extractor cannot select a different path or character encoding from the
+one inspected. PKWARE and ASi Unix extra fields are likewise rejected because
+they can supply link targets;
+libarchive's `xl` field is rejected because it can override the inspected file
+type. Unix file-type bits are honored only for Unix- or Darwin-origin central
+headers; file-type bits claimed by DOS, NTFS, or other creator systems are
+rejected. These alternate-metadata cases, along with contradictory Unix file
+and directory attributes, use
+`UnsupportedZipFeatureError` with the `ambiguous-metadata` feature. This API is
+a metadata preflight, not an extraction API; consumers that later extract an
+accepted archive must still use an extraction destination and library with
+equivalent path and symlink protections.
+
 ### Error Handling
 
 ```typescript
@@ -126,6 +200,8 @@ const files = await listFiles('/path/to/dir', { match: /\.json$/ });
 
 **Fetch**: `fetchText`, `fetchJSON`, `fetchBuffer`, `fetchToFile`, `addRateLimit`, `getRateLimit`
 
+**Archive inspection**: `inspectZipManifest`, `DEFAULT_ZIP_MANIFEST_LIMITS`, `ZipManifestError`, `InvalidZipArchiveError`, `UnsafeZipEntryError`, `ZipManifestLimitError`, `UnsupportedZipFeatureError`
+
 **Errors**: `FilesystemError`, `FileNotFoundError`, `PermissionError`, `DirectoryNotEmptyError`, `InvalidPathError`
 
 **Legacy**: `isFile`, `isDirectory`, `ensureDirectoryExists`, `download`, `upload`, `downloadFileWithCache`, `listFiles`, `getCached`, `setCached`, `getMimeType`

package/dist/archive.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Bounded, zero-decompression ZIP manifest inspection.
+ *
+ * The inspector reads ZIP metadata only. It never inflates or materializes an
+ * entry body, and it rejects archive features that would make the classic ZIP
+ * metadata ambiguous (ZIP64, encryption, and multi-disk archives).
+ */
+/** Limits applied while inspecting ZIP metadata. */
+export interface ZipManifestLimits {
+    /** Maximum number of central-directory entries, including directories. */
+    maxEntries?: number;
+    /** Maximum declared uncompressed size of one entry. */
+    maxEntryUncompressedBytes?: number;
+    /** Maximum aggregate declared uncompressed size across all entries. */
+    maxTotalUncompressedBytes?: number;
+    /** Maximum encoded byte length of one entry path. */
+    maxPathBytes?: number;
+}
+/** Conservative defaults suitable for rejecting untrusted uploads. */
+export declare const DEFAULT_ZIP_MANIFEST_LIMITS: Readonly<Required<ZipManifestLimits>>;
+/** One normalized entry from a ZIP archive. */
+export interface ZipManifestEntry {
+    /** Normalized relative path using `/` separators and no `.` segments. */
+    path: string;
+    /** Whether the entry represents a file or directory. */
+    type: 'file' | 'directory';
+    /** Declared uncompressed size in bytes. */
+    size: number;
+    /** Declared compressed size in bytes. */
+    compressedSize: number;
+    /** ZIP compression method identifier. Entry bodies are not decompressed. */
+    compressionMethod: number;
+}
+/** A bounded metadata-only view of a ZIP archive. */
+export interface ZipManifest {
+    entries: ZipManifestEntry[];
+    entryCount: number;
+    fileCount: number;
+    directoryCount: number;
+    totalUncompressedBytes: number;
+}
+export type ZipManifestErrorCode = 'ZIP_INVALID' | 'ZIP_LIMIT_EXCEEDED' | 'ZIP_UNSAFE_ENTRY' | 'ZIP_UNSUPPORTED_FEATURE';
+/** Base class for failures caused by untrusted ZIP input. */
+export declare class ZipManifestError extends Error {
+    readonly code: ZipManifestErrorCode;
+    readonly entryPath?: string | undefined;
+    constructor(message: string, code: ZipManifestErrorCode, entryPath?: string | undefined);
+}
+/** The archive metadata is malformed, truncated, or internally inconsistent. */
+export declare class InvalidZipArchiveError extends ZipManifestError {
+    constructor(message: string);
+}
+export type ZipUnsafeEntryReason = 'absolute-path' | 'alternate-data-stream' | 'drive-qualified-path' | 'duplicate-path' | 'empty-path' | 'nul-byte' | 'path-conflict' | 'path-traversal' | 'portable-path-collision' | 'reparse-point' | 'special-file' | 'symlink' | 'windows-reserved-path';
+/** An entry is unsafe to expose to an extraction workflow. */
+export declare class UnsafeZipEntryError extends ZipManifestError {
+    readonly reason: ZipUnsafeEntryReason;
+    constructor(reason: ZipUnsafeEntryReason, entryPath: string, message: string);
+}
+export type ZipLimitName = 'entry-count' | 'entry-uncompressed-size' | 'path-bytes' | 'total-uncompressed-size';
+/** A configured inspection limit was exceeded. */
+export declare class ZipManifestLimitError extends ZipManifestError {
+    readonly limit: ZipLimitName;
+    readonly actual: number;
+    readonly maximum: number;
+    constructor(limit: ZipLimitName, actual: number, maximum: number, message: string, entryPath?: string);
+}
+export type UnsupportedZipFeature = 'ambiguous-metadata' | 'encryption' | 'multi-disk' | 'zip64';
+/** The archive uses a feature deliberately outside this inspector's policy. */
+export declare class UnsupportedZipFeatureError extends ZipManifestError {
+    readonly feature: UnsupportedZipFeature;
+    constructor(feature: UnsupportedZipFeature, message: string, entryPath?: string);
+}
+/**
+ * Inspect a ZIP archive without decompressing entry bodies.
+ *
+ * ZIP64, encrypted, and multi-disk archives are rejected. Entry paths are
+ * normalized and checked for traversal, absolute/drive-qualified forms, NTFS
+ * alternate data streams, NUL bytes, Unix symlinks and special files, Windows
+ * reparse points and reserved names, and portable case/normalization
+ * collisions. Local entry ranges, declared entry sizes, and end-record
+ * validation work are bounded and cross-checked before a manifest is returned.
+ */
+export declare function inspectZipManifest(data: Uint8Array, limits?: ZipManifestLimits): ZipManifest;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4CH,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,uEAAuE;IACvE,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,sEAAsE;AACtE,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAChD,QAAQ,CAAC,iBAAiB,CAAC,CAM3B,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,oBAAoB,GACpB,kBAAkB,GAClB,yBAAyB,CAAC;AAE9B,6DAA6D;AAC7D,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,oBAAoB;aAC1B,SAAS,CAAC,EAAE,MAAM;gBAFlC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,oBAAoB,EAC1B,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED,gFAAgF;AAChF,qBAAa,sBAAuB,SAAQ,gBAAgB;gBAC9C,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf,uBAAuB,GACvB,sBAAsB,GACtB,gBAAgB,GAChB,YAAY,GACZ,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,yBAAyB,GACzB,eAAe,GACf,cAAc,GACd,SAAS,GACT,uBAAuB,CAAC;AAE5B,8DAA8D;AAC9D,qBAAa,mBAAoB,SAAQ,gBAAgB;aAErC,MAAM,EAAE,oBAAoB;gBAA5B,MAAM,EAAE,oBAAoB,EAC5C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,yBAAyB,GACzB,YAAY,GACZ,yBAAyB,CAAC;AAE9B,kDAAkD;AAClD,qBAAa,qBAAsB,SAAQ,gBAAgB;aAEvC,KAAK,EAAE,YAAY;aACnB,MAAM,EAAE,MAAM;aACd,OAAO,EAAE,MAAM;gBAFf,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAC/B,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM;CAKrB;AAED,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,YAAY,GACZ,YAAY,GACZ,OAAO,CAAC;AAEZ,+EAA+E;AAC/E,qBAAa,0BAA2B,SAAQ,gBAAgB;aAE5C,OAAO,EAAE,qBAAqB;gBAA9B,OAAO,EAAE,qBAAqB,EAC9C,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM;CAKrB;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,MAAM,GAAE,iBAAsB,GAC7B,WAAW,CAoRb"}

package/dist/index.d.ts

@@ -23,6 +23,7 @@
  *
  * @packageDocumentation
  */
+export * from './archive';
 export type { FetchToFileOptions, WriteResponseToFileOptions, } from './fetch';
 export { addRateLimit, fetchBuffer, fetchJSON, fetchText, fetchToFile, getRateLimit, writeResponseToFile, } from './fetch';
 export * from './filesystem';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EACV,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAEjB,cAAc,cAAc,CAAC;AAE7B,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,WAAW,EACX,MAAM,EACN,SAAS,EACT,SAAS,EACT,MAAM,GACP,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAY/B,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAE5C;;;GAGG;AACH,eAAe,OAAO,CAAC;AAEvB,gBAAgB;AAChB,eAAO,MAAM,2BAA2B,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,WAAW,CAAC;AAC1B,YAAY,EACV,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAEjB,cAAc,cAAc,CAAC;AAE7B,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,WAAW,EACX,MAAM,EACN,SAAS,EACT,SAAS,EACT,MAAM,GACP,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAY/B,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAE5C;;;GAGG;AACH,eAAe,OAAO,CAAC;AAEvB,gBAAgB;AAChB,eAAO,MAAM,2BAA2B,OAAO,CAAC"}