wolfy-reader 0.1.0

package/src/zip/eocd.ts

@@ -0,0 +1,97 @@
+import { ZipFormatError } from './errors.ts';
+import { readExact, view, type ByteSource } from './source.ts';
+
+const EOCD_SIG = 0x06054b50;
+const EOCD_MIN = 22;
+const MAX_COMMENT = 0xffff;
+const LOCATOR_SIG = 0x07064b50;
+const LOCATOR_SIZE = 20;
+const ZIP64_EOCD_SIG = 0x06064b50;
+const ZIP64_EOCD_MIN = 56;
+const INITIAL_PROBE = 1024;
+
+export interface CentralDirectoryLocation {
+  offset: number;
+  size: number;
+  entryCount: number;
+}
+
+export async function locateCentralDirectory(src: ByteSource): Promise<CentralDirectoryLocation> {
+  if (src.size < EOCD_MIN) throw new ZipFormatError('too small to be a zip archive');
+
+  let probe = Math.min(src.size, INITIAL_PROBE);
+  let tail = await readExact(src, src.size - probe, probe);
+  let idx = findEocd(tail);
+  const maxProbe = Math.min(src.size, EOCD_MIN + MAX_COMMENT);
+  if (idx < 0 && probe < maxProbe) {
+    probe = maxProbe;
+    tail = await readExact(src, src.size - probe, probe);
+    idx = findEocd(tail);
+  }
+  if (idx < 0) throw new ZipFormatError('end of central directory record not found');
+
+  const eocdFileOffset = src.size - probe + idx;
+  const zip64 = await readZip64(src, tail, idx, eocdFileOffset);
+  if (zip64) return zip64;
+
+  const dv = view(tail);
+  const diskNumber = dv.getUint16(idx + 4, true);
+  const cdDisk = dv.getUint16(idx + 6, true);
+  if (diskNumber !== 0 || cdDisk !== 0) {
+    throw new ZipFormatError('multi-disk archives are not supported');
+  }
+  const entryCount = dv.getUint16(idx + 10, true);
+  const size = dv.getUint32(idx + 12, true);
+  const offset = dv.getUint32(idx + 16, true);
+  if (entryCount === 0xffff || size === 0xffffffff || offset === 0xffffffff) {
+    throw new ZipFormatError('zip64 markers present but the zip64 locator is missing');
+  }
+  return { offset, size, entryCount };
+}
+
+function findEocd(tail: Uint8Array): number {
+  const dv = view(tail);
+  for (let i = tail.byteLength - EOCD_MIN; i >= 0; i--) {
+    if (dv.getUint32(i, true) !== EOCD_SIG) continue;
+    const commentLen = dv.getUint16(i + 20, true);
+    if (i + EOCD_MIN + commentLen === tail.byteLength) return i;
+  }
+  return -1;
+}
+
+async function readZip64(
+  src: ByteSource,
+  tail: Uint8Array,
+  eocdIdx: number,
+  eocdFileOffset: number,
+): Promise<CentralDirectoryLocation | null> {
+  if (eocdFileOffset < LOCATOR_SIZE) return null;
+  const locator =
+    eocdIdx >= LOCATOR_SIZE
+      ? tail.subarray(eocdIdx - LOCATOR_SIZE, eocdIdx)
+      : await readExact(src, eocdFileOffset - LOCATOR_SIZE, LOCATOR_SIZE);
+  const ldv = view(locator);
+  if (ldv.getUint32(0, true) !== LOCATOR_SIG) return null;
+  if (ldv.getUint32(16, true) > 1) {
+    throw new ZipFormatError('multi-disk archives are not supported');
+  }
+  const recordOffset = toSafeNumber(ldv.getBigUint64(8, true), 'zip64 EOCD offset');
+
+  const record = await readExact(src, recordOffset, ZIP64_EOCD_MIN);
+  const rdv = view(record);
+  if (rdv.getUint32(0, true) !== ZIP64_EOCD_SIG) {
+    throw new ZipFormatError('zip64 locator points at a missing zip64 EOCD record');
+  }
+  return {
+    entryCount: toSafeNumber(rdv.getBigUint64(32, true), 'zip64 entry count'),
+    size: toSafeNumber(rdv.getBigUint64(40, true), 'zip64 central directory size'),
+    offset: toSafeNumber(rdv.getBigUint64(48, true), 'zip64 central directory offset'),
+  };
+}
+
+export function toSafeNumber(value: bigint, what: string): number {
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new ZipFormatError(`${what} exceeds the safe integer range`);
+  }
+  return Number(value);
+}

package/src/zip/errors.ts

@@ -0,0 +1,41 @@
+export class ZipError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipError';
+  }
+}
+
+export class ZipFormatError extends ZipError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipFormatError';
+  }
+}
+
+export class ZipCrcMismatchError extends ZipFormatError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipCrcMismatchError';
+  }
+}
+
+export class ZipEncryptedEntryError extends ZipError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipEncryptedEntryError';
+  }
+}
+
+export class ZipUnsupportedMethodError extends ZipError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipUnsupportedMethodError';
+  }
+}
+
+export class ZipEntryNotFoundError extends ZipError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ZipEntryNotFoundError';
+  }
+}

package/src/zip/index.ts

@@ -0,0 +1,114 @@
+import { parseCentralDirectory, type CentralRecord } from './central.ts';
+import { crc32 } from './crc32.ts';
+import { locateCentralDirectory } from './eocd.ts';
+import {
+  ZipCrcMismatchError,
+  ZipEncryptedEntryError,
+  ZipEntryNotFoundError,
+  ZipError,
+  ZipFormatError,
+  ZipUnsupportedMethodError,
+} from './errors.ts';
+import { decompress } from './inflate.ts';
+import { readExact, toByteSource, view, type ByteSource, type ZipSource } from './source.ts';
+
+export {
+  ZipCrcMismatchError,
+  ZipEncryptedEntryError,
+  ZipEntryNotFoundError,
+  ZipError,
+  ZipFormatError,
+  ZipUnsupportedMethodError,
+};
+export type { RangeReader, RangeReaderSource, ZipSource } from './source.ts';
+
+const LOCAL_SIG = 0x04034b50;
+const LOCAL_HEADER_SIZE = 30;
+
+function hex32(value: number): string {
+  return `0x${value.toString(16).padStart(8, '0')}`;
+}
+
+export interface ZipEntry {
+  readonly name: string;
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly encrypted: boolean;
+}
+
+export interface ZipArchive {
+  readonly entries: readonly ZipEntry[];
+  entry(name: string): ZipEntry | undefined;
+  read(name: string): Promise<Uint8Array>;
+}
+
+export async function openZip(source: ZipSource): Promise<ZipArchive> {
+  const src = toByteSource(source);
+  const location = await locateCentralDirectory(src);
+  const directory = await readExact(src, location.offset, location.size);
+  const records = parseCentralDirectory(directory, location.entryCount);
+  const byName = new Map<string, CentralRecord>();
+  for (const record of records) byName.set(record.name, record);
+
+  const entries: readonly ZipEntry[] = records.map((record) => ({
+    name: record.name,
+    method: record.method,
+    compressedSize: record.compressedSize,
+    uncompressedSize: record.uncompressedSize,
+    encrypted: record.encrypted,
+  }));
+  // First entry wins on a duplicate name, preserving the Array.find semantics
+  // this Map lookup replaced.
+  const entryByName = new Map<string, ZipEntry>();
+  for (const entry of entries) {
+    if (!entryByName.has(entry.name)) entryByName.set(entry.name, entry);
+  }
+
+  return {
+    entries,
+    entry: (name) => entryByName.get(name),
+    read: async (name) => {
+      const record = byName.get(name);
+      if (!record) throw new ZipEntryNotFoundError(`no entry named ${name}`);
+      return readEntry(src, record);
+    },
+  };
+}
+
+async function readEntry(src: ByteSource, record: CentralRecord): Promise<Uint8Array> {
+  if (record.encrypted) {
+    throw new ZipEncryptedEntryError(`entry ${record.name} is encrypted; encrypted archives are not supported`);
+  }
+  const header = await readExact(src, record.localHeaderOffset, LOCAL_HEADER_SIZE);
+  const dv = view(header);
+  if (dv.getUint32(0, true) !== LOCAL_SIG) {
+    throw new ZipFormatError(`entry ${record.name}: no local file header at offset ${record.localHeaderOffset}`);
+  }
+  // The local header's own name/extra lengths can differ from the central
+  // directory's (bsdtar pads local extras); sizes with data descriptors (flag
+  // bit 3) are zero here — the central directory values are authoritative.
+  const nameLen = dv.getUint16(26, true);
+  const extraLen = dv.getUint16(28, true);
+  const dataOffset = record.localHeaderOffset + LOCAL_HEADER_SIZE + nameLen + extraLen;
+  const data = await readExact(src, dataOffset, record.compressedSize);
+  const out = await decompress(data, record.method, record.name);
+  if (out.byteLength !== record.uncompressedSize) {
+    throw new ZipFormatError(
+      `entry ${record.name}: expected ${record.uncompressedSize} bytes, decompressed to ${out.byteLength}`,
+    );
+  }
+  // Verify against the central directory's CRC-32, unconditionally. The
+  // data-descriptor exemption (APPNOTE 4.4.7) zeroes the CRC only in the
+  // *local* header of a flag-bit-3 entry — "the correct value is put in the
+  // data descriptor and in the central directory" — so the central copy is
+  // always the real checksum and there is no CRC==0 skip: 0 is simply the
+  // legitimate CRC of an empty payload, which trivially matches.
+  const actual = crc32(out);
+  if (actual !== record.crc32) {
+    throw new ZipCrcMismatchError(
+      `entry ${record.name}: CRC-32 mismatch (expected ${hex32(record.crc32)}, computed ${hex32(actual)})`,
+    );
+  }
+  return out;
+}

package/src/zip/inflate.ts

@@ -0,0 +1,41 @@
+import { ZipFormatError, ZipUnsupportedMethodError } from './errors.ts';
+
+const STORED = 0;
+const DEFLATED = 8;
+
+export async function decompress(data: Uint8Array, method: number, name: string): Promise<Uint8Array> {
+  if (method === STORED) return data.slice();
+  if (method === DEFLATED) return inflateRaw(data, name);
+  throw new ZipUnsupportedMethodError(`entry ${name} uses unsupported compression method ${method}`);
+}
+
+async function inflateRaw(data: Uint8Array, name: string): Promise<Uint8Array> {
+  const input = new ReadableStream<BufferSource>({
+    start(controller) {
+      // slice() re-backs the view with a plain ArrayBuffer — a range reader may
+      // hand back a SharedArrayBuffer-backed view, which BufferSource excludes.
+      controller.enqueue(data.slice());
+      controller.close();
+    },
+  });
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    const reader = input.pipeThrough(new DecompressionStream('deflate-raw')).getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  } catch (cause) {
+    throw new ZipFormatError(`entry ${name}: corrupt deflate stream`, { cause });
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}

package/src/zip/source.ts

@@ -0,0 +1,51 @@
+import { ZipFormatError } from './errors.ts';
+
+export type RangeReader = (offset: number, length: number) => Promise<Uint8Array>;
+
+/** Streaming input: `size` is required because locating a zip's central directory starts from the file tail. */
+export interface RangeReaderSource {
+  read: RangeReader;
+  size: number;
+}
+
+export type ZipSource = ArrayBuffer | Uint8Array | Blob | RangeReaderSource;
+
+export interface ByteSource {
+  size: number;
+  read: RangeReader;
+}
+
+export function toByteSource(source: ZipSource): ByteSource {
+  if (source instanceof Uint8Array) return bufferSource(source);
+  if (source instanceof ArrayBuffer) return bufferSource(new Uint8Array(source));
+  if (source instanceof Blob) {
+    return {
+      size: source.size,
+      read: async (offset, length) =>
+        new Uint8Array(await source.slice(offset, offset + length).arrayBuffer()),
+    };
+  }
+  return { size: source.size, read: (offset, length) => source.read(offset, length) };
+}
+
+function bufferSource(bytes: Uint8Array): ByteSource {
+  return {
+    size: bytes.byteLength,
+    read: (offset, length) => Promise.resolve(bytes.subarray(offset, offset + length)),
+  };
+}
+
+export async function readExact(src: ByteSource, offset: number, length: number): Promise<Uint8Array> {
+  if (offset < 0 || length < 0 || offset + length > src.size) {
+    throw new ZipFormatError(`range ${offset}..${offset + length} is outside the ${src.size}-byte source`);
+  }
+  const bytes = await src.read(offset, length);
+  if (bytes.byteLength !== length) {
+    throw new ZipFormatError(`short read at ${offset}: wanted ${length} bytes, got ${bytes.byteLength}`);
+  }
+  return bytes;
+}
+
+export function view(bytes: Uint8Array): DataView {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}