yauzl 2.10.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/yauzl@2.10.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/yauzl@2.10.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:398f624aed8dcb343ad9767c75b36c89880f24b918ac93ec8873fee4d9d9ea2d","contract":["assert yauzl.fromBuffer opens a zip archive from a buffer and reads entries","assert yauzl opens a readable stream for an entry and extracts uncompressed contents","assert yauzl.validateFileName returns null for valid relative paths and error string for unsafe paths","assert yauzl.dosDateTimeToDate converts MS-DOS date and time integers into a JavaScript Date","assert yauzl.fromBuffer reports an error callback when given an invalid zip buffer"],"goal":"verify pkg:npm/yauzl@2.10.0","kind":"HOW","packages":["pkg:npm/yauzl@2.10.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/yauzl@2.10.0"],"schemaVersion":1,"subject":"pkg:npm/yauzl@2.10.0","verifierAdapter":"node-typescript@1"}

import yauzl from 'yauzl';

/**
 * Promisified wrapper around yauzl.fromBuffer to open a ZipFile instance.
 * @param {Buffer} buffer - Raw zip archive buffer.
 * @param {object} [options] - yauzl options.
 * @returns {Promise<import('yauzl').ZipFile>}
 */
export function openZipFromBuffer(buffer, options = {}) {
  return new Promise((resolve, reject) => {
    yauzl.fromBuffer(buffer, options, (err, zipfile) => {
      if (err) return reject(err);
      resolve(zipfile);
    });
  });
}

/**
 * Reads the uncompressed content of a zip entry as a Buffer.
 * @param {import('yauzl').ZipFile} zipfile
 * @param {import('yauzl').Entry} entry
 * @returns {Promise<Buffer>}
 */
export function readEntryStream(zipfile, entry) {
  return new Promise((resolve, reject) => {
    zipfile.openReadStream(entry, (err, stream) => {
      if (err) return reject(err);
      const chunks = [];
      stream.on('data', (chunk) => chunks.push(chunk));
      stream.on('end', () => resolve(Buffer.concat(chunks)));
      stream.on('error', reject);
    });
  });
}

/**
 * Validates a zip entry file name for safe extraction.
 * @param {string} fileName
 * @returns {string|null} null if valid, or an error string if invalid
 */
export function validateEntryPath(fileName) {
  return yauzl.validateFileName(fileName);
}

/**
 * Converts MS-DOS date and time integers into a JavaScript Date.
 * @param {number} date
 * @param {number} time
 * @returns {Date}
 */
export function parseDosDateTime(date, time) {
  return yauzl.dosDateTimeToDate(date, time);
}

export default yauzl;

{
  "name": "sample-yauzl-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-yauzl-verify",
      "version": "1.0.0",
      "dependencies": {
        "yauzl": "2.10.0"
      }
    },
    "node_modules/buffer-crc32": {
      "version": "0.2.13",
      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
      "license": "MIT",
      "engines": {
        "node": "*"
      }
    },
    "node_modules/fd-slicer": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
      "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
      "license": "MIT",
      "dependencies": {
        "pend": "~1.2.0"
      }
    },
    "node_modules/pend": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
      "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
      "license": "MIT"
    },
    "node_modules/yauzl": {
      "version": "2.10.0",
      "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
      "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==",
      "license": "MIT",
      "dependencies": {
        "buffer-crc32": "~0.2.3",
        "fd-slicer": "~1.1.0"
      }
    }
  }
}

{
  "name": "sample-yauzl-verify",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "yauzl": "2.10.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/yauzl@2.10.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/yauzl@2.10.0"
  ]
}

import assert from 'node:assert/strict';
import zlib from 'node:zlib';
import yauzl, { openZipFromBuffer, readEntryStream, validateEntryPath, parseDosDateTime } from '../index.mjs';

/**
 * Creates a minimal valid uncompressed ZIP archive Buffer for testing.
 * @param {Array<{name: string, content: string|Buffer}>} entries
 * @returns {Buffer}
 */
function createTestZip(entries = []) {
  const localHeaders = [];
  const centralHeaders = [];
  let offset = 0;

  for (const entry of entries) {
    const filenameBuf = Buffer.from(entry.name, 'utf8');
    const contentBuf = Buffer.isBuffer(entry.content)
      ? entry.content
      : Buffer.from(entry.content, 'utf8');
    const crc = zlib.crc32(contentBuf);
    const size = contentBuf.length;

    // Local file header (30 bytes + filename)
    const localHeader = Buffer.alloc(30 + filenameBuf.length);
    localHeader.writeUInt32LE(0x04034b50, 0);
    localHeader.writeUInt16LE(10, 4);
    localHeader.writeUInt16LE(0x0800, 6);
    localHeader.writeUInt16LE(0, 8);
    localHeader.writeUInt16LE(0, 10);
    localHeader.writeUInt16LE(0x21, 12);
    localHeader.writeUInt32LE(crc, 14);
    localHeader.writeUInt32LE(size, 18);
    localHeader.writeUInt32LE(size, 22);
    localHeader.writeUInt16LE(filenameBuf.length, 26);
    localHeader.writeUInt16LE(0, 28);
    filenameBuf.copy(localHeader, 30);

    // Central directory header (46 bytes + filename)
    const centralHeader = Buffer.alloc(46 + filenameBuf.length);
    centralHeader.writeUInt32LE(0x02014b50, 0);
    centralHeader.writeUInt16LE(20, 4);
    centralHeader.writeUInt16LE(10, 6);
    centralHeader.writeUInt16LE(0x0800, 8);
    centralHeader.writeUInt16LE(0, 10);
    centralHeader.writeUInt16LE(0, 12);
    centralHeader.writeUInt16LE(0x21, 14);
    centralHeader.writeUInt32LE(crc, 16);
    centralHeader.writeUInt32LE(size, 20);
    centralHeader.writeUInt32LE(size, 24);
    centralHeader.writeUInt16LE(filenameBuf.length, 28);
    centralHeader.writeUInt16LE(0, 30);
    centralHeader.writeUInt16LE(0, 32);
    centralHeader.writeUInt16LE(0, 34);
    centralHeader.writeUInt16LE(0, 36);
    centralHeader.writeUInt32LE(0, 38);
    centralHeader.writeUInt32LE(offset, 42);
    filenameBuf.copy(centralHeader, 46);

    localHeaders.push(localHeader, contentBuf);
    centralHeaders.push(centralHeader);
    offset += localHeader.length + contentBuf.length;
  }

  const centralDirOffset = offset;
  const centralDirSize = centralHeaders.reduce((acc, b) => acc + b.length, 0);

  const eocd = Buffer.alloc(22);
  eocd.writeUInt32LE(0x06054b50, 0);
  eocd.writeUInt16LE(0, 4);
  eocd.writeUInt16LE(0, 6);
  eocd.writeUInt16LE(entries.length, 8);
  eocd.writeUInt16LE(entries.length, 10);
  eocd.writeUInt32LE(centralDirSize, 12);
  eocd.writeUInt32LE(centralDirOffset, 16);
  eocd.writeUInt16LE(0, 20);

  return Buffer.concat([...localHeaders, ...centralHeaders, eocd]);
}

// 1. assert yauzl.fromBuffer opens a zip archive from a buffer and reads entries
{
  const zipBuffer = createTestZip([
    { name: 'sample.txt', content: 'test content' },
    { name: 'docs/guide.md', content: 'documentation' }
  ]);

  const zipfile = await openZipFromBuffer(zipBuffer, { lazyEntries: true });
  assert.strictEqual(zipfile.entryCount, 2, 'Should contain 2 entries');

  const entryNames = [];
  await new Promise((resolve, reject) => {
    zipfile.on('entry', (entry) => {
      entryNames.push(entry.fileName);
      zipfile.readEntry();
    });
    zipfile.on('end', resolve);
    zipfile.on('error', reject);
    zipfile.readEntry();
  });

  assert.deepStrictEqual(entryNames, ['sample.txt', 'docs/guide.md']);
}

// 2. assert yauzl opens a readable stream for an entry and extracts uncompressed contents
{
  const expectedContent = 'Hello from yauzl!';
  const zipBuffer = createTestZip([
    { name: 'hello.txt', content: expectedContent }
  ]);

  const zipfile = await openZipFromBuffer(zipBuffer, { lazyEntries: true });
  const entry = await new Promise((resolve, reject) => {
    zipfile.once('entry', resolve);
    zipfile.once('error', reject);
    zipfile.readEntry();
  });

  assert.strictEqual(entry.fileName, 'hello.txt');
  assert.strictEqual(entry.uncompressedSize, expectedContent.length);

  const contentBuffer = await readEntryStream(zipfile, entry);
  assert.strictEqual(contentBuffer.toString('utf8'), expectedContent);
}

// 3. assert yauzl.validateFileName returns null for valid relative paths and error string for unsafe paths
{
  assert.strictEqual(validateEntryPath('file.txt'), null);
  assert.strictEqual(validateEntryPath('nested/dir/file.txt'), null);

  const relativeError = validateEntryPath('../traversal.txt');
  assert.ok(typeof relativeError === 'string' && relativeError.includes('relative path'));

  const absoluteError = validateEntryPath('/etc/passwd');
  assert.ok(typeof absoluteError === 'string' && absoluteError.includes('absolute path'));

  const backslashError = validateEntryPath('invalid\\slash.txt');
  assert.ok(typeof backslashError === 'string' && backslashError.includes('invalid characters'));
}

// 4. assert yauzl.dosDateTimeToDate converts MS-DOS date and time integers into a JavaScript Date
{
  // DOS date 0x21 is 1980-01-01, time 0x0 is 00:00:00
  const date = parseDosDateTime(0x21, 0x0);
  assert.ok(date instanceof Date, 'Should return a Date instance');
  assert.strictEqual(date.getFullYear(), 1980);
  assert.strictEqual(date.getMonth(), 0); // January (0-indexed)
  assert.strictEqual(date.getDate(), 1);
}

// 5. assert yauzl.fromBuffer reports an error callback when given an invalid zip buffer
{
  const invalidBuffer = Buffer.from('this is not a valid zip archive');
  let caughtError = null;

  try {
    await openZipFromBuffer(invalidBuffer);
  } catch (err) {
    caughtError = err;
  }

  assert.ok(caughtError !== null, 'Should fail to open invalid zip buffer');
  assert.ok(caughtError.message.includes('end of central directory record signature not found'));
}

console.log('All contracts passed successfully.');