extract-zip 2.0.1

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/extract-zip@2.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/extract-zip@2.0.1

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:20ed9a9b2f01a8a74d03c06d27141be99c9fe64f95bac4263ebba752ba4f9bd2","contract":["extract extracts files and nested directory structures from a zip archive into an absolute target directory","extract throws an Error when target directory option dir is not an absolute path","extract invokes onEntry callback with zip entry for each processed entry","extract rejects when an archive entry contains out-of-bound path traversal","extract creates missing target directories and parent directories recursively","extract applies defaultFileMode and defaultDirMode when entry file permissions are unset"],"goal":"verify pkg:npm/extract-zip@2.0.1","kind":"HOW","packages":["pkg:npm/extract-zip@2.0.1"],"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/extract-zip@2.0.1"],"schemaVersion":1,"subject":"pkg:npm/extract-zip@2.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-extract-zip",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-extract-zip",
      "version": "1.0.0",
      "dependencies": {
        "extract-zip": "2.0.1"
      }
    },
    "node_modules/@types/node": {
      "version": "26.2.0",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.2.0.tgz",
      "integrity": "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg==",
      "license": "MIT",
      "optional": true,
      "dependencies": {
        "undici-types": "~8.3.0"
      }
    },
    "node_modules/@types/yauzl": {
      "version": "2.10.3",
      "resolved": "https://registry.npmjs.org/@types/yauzl/-/yauzl-2.10.3.tgz",
      "integrity": "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q==",
      "license": "MIT",
      "optional": true,
      "dependencies": {
        "@types/node": "*"
      }
    },
    "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/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/end-of-stream": {
      "version": "1.4.5",
      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
      "license": "MIT",
      "dependencies": {
        "once": "^1.4.0"
      }
    },
    "node_modules/extract-zip": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-2.0.1.tgz",
      "integrity": "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "debug": "^4.1.1",
        "get-stream": "^5.1.0",
        "yauzl": "^2.10.0"
      },
      "bin": {
        "extract-zip": "cli.js"
      },
      "engines": {
        "node": ">= 10.17.0"
      },
      "optionalDependencies": {
        "@types/yauzl": "^2.9.1"
      }
    },
    "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/get-stream": {
      "version": "5.2.0",
      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
      "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==",
      "license": "MIT",
      "dependencies": {
        "pump": "^3.0.0"
      },
      "engines": {
        "node": ">=8"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/once": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
      "license": "ISC",
      "dependencies": {
        "wrappy": "1"
      }
    },
    "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/pump": {
      "version": "3.0.4",
      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
      "license": "MIT",
      "dependencies": {
        "end-of-stream": "^1.1.0",
        "once": "^1.3.1"
      }
    },
    "node_modules/undici-types": {
      "version": "8.3.0",
      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
      "license": "MIT",
      "optional": true
    },
    "node_modules/wrappy": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    },
    "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-extract-zip",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "extract-zip": "2.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/extract-zip@2.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/extract-zip@2.0.1"
  ]
}

import assert from 'node:assert/strict';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import zlib from 'node:zlib';
import extract from 'extract-zip';

function createZip(entries) {
  const localHeaders = [];
  const centralHeaders = [];
  let offset = 0;

  for (const entry of entries) {
    const isDir = entry.name.endsWith('/');
    const content = isDir ? Buffer.alloc(0) : Buffer.from(entry.content || '');
    const nameBuf = Buffer.from(entry.name, 'utf8');
    const crc = zlib.crc32(content);
    const size = content.length;

    // Local header
    const localHdr = Buffer.alloc(30 + nameBuf.length);
    localHdr.writeUInt32LE(0x04034b50, 0);
    localHdr.writeUInt16LE(20, 4);
    localHdr.writeUInt16LE(0, 6);
    localHdr.writeUInt16LE(0, 8);
    localHdr.writeUInt16LE(0, 10);
    localHdr.writeUInt16LE(0, 12);
    localHdr.writeUInt32LE(crc, 14);
    localHdr.writeUInt32LE(size, 18);
    localHdr.writeUInt32LE(size, 22);
    localHdr.writeUInt16LE(nameBuf.length, 26);
    localHdr.writeUInt16LE(0, 28);
    nameBuf.copy(localHdr, 30);

    const localChunk = Buffer.concat([localHdr, content]);
    localHeaders.push(localChunk);

    // Central dir header
    const mode = entry.mode !== undefined ? entry.mode : (isDir ? 0o040755 : 0o100644);
    const externalAttr = (mode << 16) >>> 0;
    const centralHdr = Buffer.alloc(46 + nameBuf.length);
    centralHdr.writeUInt32LE(0x02014b50, 0);
    centralHdr.writeUInt16LE(0x031e, 4);
    centralHdr.writeUInt16LE(20, 6);
    centralHdr.writeUInt16LE(0, 8);
    centralHdr.writeUInt16LE(0, 10);
    centralHdr.writeUInt16LE(0, 12);
    centralHdr.writeUInt32LE(crc, 16);
    centralHdr.writeUInt32LE(size, 20);
    centralHdr.writeUInt32LE(size, 24);
    centralHdr.writeUInt16LE(nameBuf.length, 28);
    centralHdr.writeUInt16LE(0, 30);
    centralHdr.writeUInt16LE(0, 32);
    centralHdr.writeUInt16LE(0, 34);
    centralHdr.writeUInt16LE(0, 36);
    centralHdr.writeUInt32LE(externalAttr, 38);
    centralHdr.writeUInt32LE(offset, 42);
    nameBuf.copy(centralHdr, 46);

    centralHeaders.push(centralHdr);
    offset += localChunk.length;
  }

  const centralDir = Buffer.concat(centralHeaders);
  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(centralDir.length, 12);
  eocd.writeUInt32LE(offset, 16);
  eocd.writeUInt16LE(0, 20);

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

// 1. extract extracts files and nested directory structures from a zip archive into an absolute target directory
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'archive.zip');
  const targetDir = path.join(tmpBase, 'extracted');

  const zipBuf = createZip([
    { name: 'hello.txt', content: 'hello extract-zip' },
    { name: 'nested/', content: '' },
    { name: 'nested/doc.txt', content: 'nested file content' },
  ]);
  await fs.promises.writeFile(zipPath, zipBuf);

  await extract(zipPath, { dir: targetDir });

  assert.equal(await fs.promises.readFile(path.join(targetDir, 'hello.txt'), 'utf8'), 'hello extract-zip');
  assert.equal(await fs.promises.readFile(path.join(targetDir, 'nested', 'doc.txt'), 'utf8'), 'nested file content');

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}

// 2. extract throws an Error when target directory option dir is not an absolute path
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'archive.zip');
  await fs.promises.writeFile(zipPath, createZip([{ name: 'sample.txt', content: 'data' }]));

  await assert.rejects(
    extract(zipPath, { dir: 'relative/dir/path' }),
    (err) => {
      assert.ok(err instanceof Error);
      assert.match(err.message, /Target directory is expected to be absolute/);
      return true;
    }
  );

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}

// 3. extract invokes onEntry callback with zip entry for each processed entry
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'entries.zip');
  const targetDir = path.join(tmpBase, 'out');

  const zipBuf = createZip([
    { name: 'entry-a.txt', content: 'content A' },
    { name: 'entry-b.txt', content: 'content B' },
  ]);
  await fs.promises.writeFile(zipPath, zipBuf);

  const seen = [];
  await extract(zipPath, {
    dir: targetDir,
    onEntry: (entry, zipfile) => {
      assert.ok(zipfile);
      seen.push(entry.fileName);
    },
  });

  assert.deepEqual(seen, ['entry-a.txt', 'entry-b.txt']);
  assert.equal(await fs.promises.readFile(path.join(targetDir, 'entry-a.txt'), 'utf8'), 'content A');
  assert.equal(await fs.promises.readFile(path.join(targetDir, 'entry-b.txt'), 'utf8'), 'content B');

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}

// 4. extract rejects when an archive entry contains out-of-bound path traversal
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'malicious.zip');
  const targetDir = path.join(tmpBase, 'out');

  const zipBuf = createZip([
    { name: '../outside.txt', content: 'dangerous' },
  ]);
  await fs.promises.writeFile(zipPath, zipBuf);

  await assert.rejects(
    extract(zipPath, { dir: targetDir }),
    (err) => {
      assert.ok(err instanceof Error);
      assert.match(err.message, /invalid relative path|Out of bound path/i);
      return true;
    }
  );

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}

// 5. extract creates missing target directories and parent directories recursively
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'deep.zip');
  const targetDir = path.join(tmpBase, 'deep', 'nested', 'target', 'dir');

  const zipBuf = createZip([
    { name: 'item.txt', content: 'deep item' },
  ]);
  await fs.promises.writeFile(zipPath, zipBuf);

  await extract(zipPath, { dir: targetDir });

  assert.ok(fs.existsSync(targetDir));
  assert.equal(await fs.promises.readFile(path.join(targetDir, 'item.txt'), 'utf8'), 'deep item');

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}

// 6. extract applies defaultFileMode and defaultDirMode when entry file permissions are unset
{
  const tmpBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'csx-contract-'));
  const zipPath = path.join(tmpBase, 'permissions.zip');
  const targetDir = path.join(tmpBase, 'out');

  const zipBuf = createZip([
    { name: 'custom-dir/', content: '', mode: 0 },
    { name: 'custom-file.txt', content: 'permission test', mode: 0 },
  ]);
  await fs.promises.writeFile(zipPath, zipBuf);

  await extract(zipPath, {
    dir: targetDir,
    defaultFileMode: 0o600,
    defaultDirMode: 0o700,
  });

  const fileStat = await fs.promises.stat(path.join(targetDir, 'custom-file.txt'));
  const dirStat = await fs.promises.stat(path.join(targetDir, 'custom-dir'));
  assert.equal(fileStat.mode & 0o777, 0o600);
  assert.equal(dirStat.mode & 0o777, 0o700);

  await fs.promises.rm(tmpBase, { recursive: true, force: true });
}