@gyng/remote-zip 1.0.0 → 1.0.1

package/lib/types/crypto.d.mts

@@ -0,0 +1,39 @@
+/** Incremental CRC-32, for verifying decompressed output (including streaming). */
+export declare class Crc32 {
+    private state;
+    update(bytes: Uint8Array): void;
+    digest(): number;
+}
+/** Compute the CRC-32 of `bytes` (the ZIP/IEEE variant). */
+export declare const crc32: (bytes: Uint8Array) => number;
+/** Test seam: raw AES block encryption (FIPS-197), used to validate the core. */
+export declare const aesEncryptBlockRaw: (key: Uint8Array, block: Uint8Array) => Uint8Array;
+/**
+ * Decrypt traditional-ZipCrypto bytes (the 12-byte encryption header is consumed
+ * and stripped). Returns the compressed plaintext and the header's check byte.
+ */
+export declare const decryptZipCrypto: (data: Uint8Array, password: Uint8Array) => {
+    plaintext: Uint8Array;
+    checkByte: number;
+};
+/** Encrypt for ZipCrypto (used by tests to build fixtures). */
+export declare const encryptZipCrypto: (plaintext: Uint8Array, password: Uint8Array, header: Uint8Array) => Uint8Array;
+/** Parse the WinZip AES extra field (id 0x9901): strength + actual method. */
+export declare const parseAesExtra: (extra: ArrayBuffer) => {
+    strength: number;
+    actualMethod: number;
+} | null;
+/** Reasons a WinZip AES decryption can fail (mapped to RemoteZipError codes). */
+export type AesDecryptError = "WRONG_PASSWORD" | "BAD_MAC" | "UNSUPPORTED";
+export declare class CryptoError extends Error {
+    reason: AesDecryptError;
+    constructor(reason: AesDecryptError);
+}
+/**
+ * Decrypt a WinZip AES entry payload (salt || pwVerify || ciphertext || mac).
+ * Verifies the password-check bytes and the authentication code, then returns
+ * the still-compressed plaintext.
+ */
+export declare const decryptWinzipAes: (data: Uint8Array, password: Uint8Array, strength: number) => Promise<Uint8Array>;
+/** Encrypt a WinZip AES payload (used by tests to build fixtures). */
+export declare const encryptWinzipAes: (plaintext: Uint8Array, password: Uint8Array, strength: number, salt: Uint8Array) => Promise<Uint8Array>;

package/lib/types/zip.d.mts

@@ -1,6 +1,6 @@
-export { crc32 } from "./crypto";
+export { crc32 } from "./crypto.mjs";
 /** Machine-readable discriminant for {@link RemoteZipError}. */
-export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "HTTP_ERROR" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
+export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "INVALID_CONTENT_LENGTH" | "HTTP_ERROR" | "RANGE_NOT_SUPPORTED" | "RANGE_RESPONSE_MISMATCH" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "INVALID_ARCHIVE" | "TRUNCATED_ENTRY" | "UNSUPPORTED_COMPRESSION" | "UNSUPPORTED_MULTI_DISK" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
 export declare class RemoteZipError extends Error {
     /** Machine-readable error code, for programmatic handling without matching on `message`. */
     code: RemoteZipErrorCode;
@@ -273,7 +273,7 @@ export declare class RemoteZip {
         /** Passed to fetch when performing a HTTP GET request for the file */
         method: string;
         /** Passed to fetch when performing a HTTP GET request for the file. */
-        credentials: "include" | "omit" | "same-origin";
+        credentials?: "include" | "omit" | "same-origin";
     } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
     /** Build a fetch RequestInit from this instance's network options. */
     private requestInitFor;
@@ -305,7 +305,7 @@ export declare class RemoteZip {
      * @param options.verifyCrc If set, verify the decompressed output against the
      *   entry's CRC-32 and throw a {@link RemoteZipError} (`CRC_MISMATCH`) on mismatch.
      * @returns Inflated (uncompressed) bytes of the requested file
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse, fetch, or exceeds limits
+     * @throws {@link RemoteZipError} if it fails to parse, fetch, or exceeds limits
      */
     fetch(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<Uint8Array>;
     /**
@@ -333,6 +333,7 @@ export declare class RemoteZip {
      * {@link fetchStream}.
      */
     private fetchEntryResponse;
+    private fetchRange;
 }
 /**
  * Network options shared by every request a {@link RemoteZip} / {@link RemoteZipPointer}
@@ -403,8 +404,8 @@ export declare class RemoteZipPointer {
     /**
      * Gets metadata about the ZIP file and constructs an initialised `RemoteZip`.
      *
-     * @returns An initialised [RemoteZip](RemoteZip)
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     * @returns An initialised {@link RemoteZip}
+     * @throws {@link RemoteZipError} if it fails to parse or fetch
      */
     populate(): Promise<RemoteZip>;
     private fetchEndOfCentralDirectory;
@@ -428,13 +429,18 @@ export declare const parseZipDatetime: (zipDate: number, zipTime: number) => str
 export declare const isZip64: (eocd: EndOfCentralDirectory) => boolean;
 /** Effective central-directory location from a ZIP64 End Of Central Directory record. */
 export interface Zip64EndOfCentralDirectory {
+    diskNumber: number;
+    cdDisk: number;
+    centralDirectoryDiskRecordCount: number;
     centralDirectoryRecordCount: number;
     centralDirectoryByteSize: number;
     centralDirectoryByteOffset: number;
 }
 /** Locate the ZIP64 EOCD locator in a tail buffer and return the ZIP64 EOCD offset. */
 export declare const parseZip64EOCDLocator: (buffer: ArrayBuffer) => {
+    diskWithZip64EOCD: number;
     zip64EOCDOffset: number;
+    totalDisks: number;
 } | null;
 /** Parse a ZIP64 End Of Central Directory record (the real CD offset/size/count). */
 export declare const parseZip64EOCD: (buffer: ArrayBuffer) => Zip64EndOfCentralDirectory | null;

package/lib/types/zip.d.ts

@@ -1,6 +1,6 @@
 export { crc32 } from "./crypto";
 /** Machine-readable discriminant for {@link RemoteZipError}. */
-export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "HTTP_ERROR" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
+export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "INVALID_CONTENT_LENGTH" | "HTTP_ERROR" | "RANGE_NOT_SUPPORTED" | "RANGE_RESPONSE_MISMATCH" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "INVALID_ARCHIVE" | "TRUNCATED_ENTRY" | "UNSUPPORTED_COMPRESSION" | "UNSUPPORTED_MULTI_DISK" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
 export declare class RemoteZipError extends Error {
     /** Machine-readable error code, for programmatic handling without matching on `message`. */
     code: RemoteZipErrorCode;
@@ -273,7 +273,7 @@ export declare class RemoteZip {
         /** Passed to fetch when performing a HTTP GET request for the file */
         method: string;
         /** Passed to fetch when performing a HTTP GET request for the file. */
-        credentials: "include" | "omit" | "same-origin";
+        credentials?: "include" | "omit" | "same-origin";
     } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
     /** Build a fetch RequestInit from this instance's network options. */
     private requestInitFor;
@@ -305,7 +305,7 @@ export declare class RemoteZip {
      * @param options.verifyCrc If set, verify the decompressed output against the
      *   entry's CRC-32 and throw a {@link RemoteZipError} (`CRC_MISMATCH`) on mismatch.
      * @returns Inflated (uncompressed) bytes of the requested file
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse, fetch, or exceeds limits
+     * @throws {@link RemoteZipError} if it fails to parse, fetch, or exceeds limits
      */
     fetch(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<Uint8Array>;
     /**
@@ -333,6 +333,7 @@ export declare class RemoteZip {
      * {@link fetchStream}.
      */
     private fetchEntryResponse;
+    private fetchRange;
 }
 /**
  * Network options shared by every request a {@link RemoteZip} / {@link RemoteZipPointer}
@@ -403,8 +404,8 @@ export declare class RemoteZipPointer {
     /**
      * Gets metadata about the ZIP file and constructs an initialised `RemoteZip`.
      *
-     * @returns An initialised [RemoteZip](RemoteZip)
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     * @returns An initialised {@link RemoteZip}
+     * @throws {@link RemoteZipError} if it fails to parse or fetch
      */
     populate(): Promise<RemoteZip>;
     private fetchEndOfCentralDirectory;
@@ -428,13 +429,18 @@ export declare const parseZipDatetime: (zipDate: number, zipTime: number) => str
 export declare const isZip64: (eocd: EndOfCentralDirectory) => boolean;
 /** Effective central-directory location from a ZIP64 End Of Central Directory record. */
 export interface Zip64EndOfCentralDirectory {
+    diskNumber: number;
+    cdDisk: number;
+    centralDirectoryDiskRecordCount: number;
     centralDirectoryRecordCount: number;
     centralDirectoryByteSize: number;
     centralDirectoryByteOffset: number;
 }
 /** Locate the ZIP64 EOCD locator in a tail buffer and return the ZIP64 EOCD offset. */
 export declare const parseZip64EOCDLocator: (buffer: ArrayBuffer) => {
+    diskWithZip64EOCD: number;
     zip64EOCDOffset: number;
+    totalDisks: number;
 } | null;
 /** Parse a ZIP64 End Of Central Directory record (the real CD offset/size/count). */
 export declare const parseZip64EOCD: (buffer: ArrayBuffer) => Zip64EndOfCentralDirectory | null;

package/package.json

@@ -1,45 +1,27 @@
 {
   "name": "@gyng/remote-zip",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Fetch file listings and individual files from a remote ZIP archive over HTTP Range requests, without downloading the whole archive.",
-  "type": "commonjs",
-  "main": "lib/cjs/index.js",
-  "module": "lib/esm/index.mjs",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./lib/types/index.d.mts",
-        "default": "./lib/esm/index.mjs"
-      },
-      "require": {
-        "types": "./lib/types/index.d.ts",
-        "default": "./lib/cjs/index.js"
-      }
-    },
-    "./package.json": "./package.json"
-  },
-  "sideEffects": false,
-  "author": "Ng Guoyou <gyng@users.noreply.github.com>",
-  "license": "(MIT OR Apache-2.0)",
   "keywords": [
-    "zip",
-    "remote",
+    "browser",
+    "central-directory",
+    "fetch",
     "http",
     "range",
-    "fetch",
+    "remote",
     "stream",
-    "central-directory",
-    "browser"
+    "zip"
   ],
   "homepage": "https://github.com/gyng/remote-zip#readme",
   "bugs": {
     "url": "https://github.com/gyng/remote-zip/issues"
   },
-  "engines": {
-    "node": ">=22"
+  "license": "(MIT OR Apache-2.0)",
+  "author": "Ng Guoyou <gyng@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gyng/remote-zip.git"
   },
-  "packageManager": "npm@11.11.0",
   "files": [
     "LICENSE-MIT",
     "LICENSE-APACHE",
@@ -47,45 +29,55 @@
     "package.json",
     "lib/**"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gyng/remote-zip.git"
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.mjs",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/types/index.d.mts",
+        "default": "./lib/esm/index.mjs"
+      },
+      "require": {
+        "types": "./lib/types/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "rm -rf lib/* && npm run ts-types && node ./esbuild.mjs",
     "d": "WATCH=1 npm run build",
-    "doc:gen": "typedoc src/index.ts --excludePrivate --cleanOutputDir --logLevel Verbose --out ./docs/api",
+    "doc:gen": "npm --prefix tools/typedoc run generate",
     "doc:site": "npm run build && npm run doc:gen && node ./scripts/build-site.mjs",
-    "lint:eslint:fix": "npm run lint:eslint -- --fix",
-    "lint:eslint": "eslint .",
-    "lint:fix": "npm run lint:prettier:fix && npm run lint:eslint:fix",
-    "lint:prettier:fix": "prettier --write .",
-    "lint:prettier": "prettier --check .",
-    "lint": "npm run lint:prettier && npm run lint:eslint",
+    "lint:fix": "oxfmt . && oxlint --type-aware --import-plugin --vitest-plugin --fix .",
+    "lint": "oxfmt --check . && oxlint --type-aware --import-plugin --vitest-plugin .",
     "t:watch": "vitest",
     "t": "npm test",
     "test:coverage": "vitest run --coverage",
+    "test:package": "npm run build && node ./scripts/test-package.mjs",
     "test": "vitest run",
     "ts-types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "pako": "^3.0.1"
+  },
   "devDependencies": {
-    "@eslint/js": "^10.0.0",
-    "@types/node": "^22.19.20",
-    "@types/pako": "^2.0.4",
-    "@vitest/coverage-v8": "^4.1.0",
-    "esbuild": "^0.28.0",
-    "eslint": "^10.0.0",
-    "eslint-config-prettier": "^10.1.8",
-    "globals": "^17.6.0",
-    "prettier": "^3.8.3",
-    "typedoc": "^0.28.19",
-    "typescript": "~6.0",
-    "typescript-eslint": "^8.61.0",
-    "vitest": "^4.1.0"
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "esbuild": "^0.28.1",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "oxlint-tsgolint": "^0.24.0",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.10"
   },
-  "dependencies": {
-    "pako": "^2.1.0"
-  }
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@11.11.0"
 }