@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/safe-extract.test.ts

@@ -1,459 +0,0 @@
-/**
- * safe-extract adversarial suite (US-020).
- *
- * These tests assert the hardened extractor refuses hostile archives — zip-slip
- * / `..` traversal, absolute-path entries, symlink/hardlink escape,
- * decompression-bomb caps, and mid-extract failure rollback. This is the seam
- * US-024's adversarial suite also hits; these are the first line.
- *
- * MALICIOUS FIXTURES ARE BUILT DETERMINISTICALLY (writeMaliciousTarGz), NOT by
- * shelling to the system `tar`. GNU tar (Linux / CI / prod) STRIPS the leading
- * `../` and absolute `/` when CREATING an archive, so a "malicious" fixture
- * built via `tar -c` is benign on Linux and the guard has nothing to reject —
- * the test passes on macOS bsdtar (preserves them) but fails on Linux. By
- * emitting the tar bytes ourselves the hostile entry names are recorded
- * verbatim and identically on every platform; the READING side (`tar -tvf`,
- * which the pre-flight uses) never strips, so the guard sees the real attack
- * everywhere. BENIGN fixtures (in-tree names that no tar strips) still use the
- * system `tar` for fidelity to the real extraction path.
- *
- * Everything is contained to per-test tmp dirs — nothing is ever written
- * outside an os.tmpdir() scratch tree.
- */
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { execFileSync } from 'child_process';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { writeMaliciousTarGz } from './__fixtures__/make-tar.js';
-import {
-  DEFAULT_CAPS,
-  UnsafeArchiveError,
-  isContained,
-  resolveContainedPath,
-  assertLinkTargetContained,
-  parseTarListing,
-  validateEntries,
-  safeExtractTarball,
-  type ExtractCaps,
-  type TarEntry,
-} from './safe-extract.js';
-
-// ---------------------------------------------------------------------------
-// Helpers — build tarballs from a scratch source tree.
-// ---------------------------------------------------------------------------
-
-let scratch: string;
-
-beforeEach(() => {
-  scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'safe-extract-test-'));
-});
-afterEach(() => {
-  fs.rmSync(scratch, { recursive: true, force: true });
-});
-
-/** Make a gzip tarball from explicit member paths inside `srcRoot`. */
-function tarball(name: string, srcRoot: string, members: string[]): string {
-  const out = path.join(scratch, name);
-  execFileSync('tar', ['-czf', out, '-C', srcRoot, ...members]);
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// Unit: containment primitives
-// ---------------------------------------------------------------------------
-
-describe('containment primitives', () => {
-  it('isContained: nested true, sibling-prefix false, self true', () => {
-    expect(isContained('/a/base', '/a/base/x/y')).toBe(true);
-    expect(isContained('/a/base', '/a/base')).toBe(true);
-    expect(isContained('/a/base', '/a/baseEVIL')).toBe(false); // trailing-sep guard
-    expect(isContained('/a/base', '/a/other')).toBe(false);
-  });
-
-  it('resolveContainedPath: rejects `..` traversal', () => {
-    expect(() => resolveContainedPath('/tmp/target', '../escape')).toThrow(
-      UnsafeArchiveError,
-    );
-    expect(() => resolveContainedPath('/tmp/target', 'a/../../escape')).toThrow(
-      UnsafeArchiveError,
-    );
-  });
-
-  it('resolveContainedPath: rejects absolute entry names', () => {
-    expect(() => resolveContainedPath('/tmp/target', '/etc/passwd')).toThrow(
-      UnsafeArchiveError,
-    );
-  });
-
-  it('resolveContainedPath: accepts an in-tree relative name', () => {
-    const r = resolveContainedPath('/tmp/target', 'sub/dir/file');
-    expect(r).toBe(path.resolve('/tmp/target', 'sub/dir/file'));
-  });
-
-  it('assertLinkTargetContained: rejects absolute escape and `..` escape', () => {
-    const entryAbs = '/tmp/pack/link';
-    expect(() => assertLinkTargetContained('/tmp/pack', entryAbs, '/etc')).toThrow(
-      UnsafeArchiveError,
-    );
-    expect(() =>
-      assertLinkTargetContained('/tmp/pack', entryAbs, '../../etc'),
-    ).toThrow(UnsafeArchiveError);
-    // In-tree relative target is fine.
-    expect(() =>
-      assertLinkTargetContained('/tmp/pack', entryAbs, './sibling'),
-    ).not.toThrow();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Unit: tar listing parser
-// ---------------------------------------------------------------------------
-
-describe('parseTarListing', () => {
-  it('parses files, dirs, and symlinks (bsdtar verbose form)', () => {
-    const sample = [
-      'drwxr-xr-x  0 user group        0 Jan  1 00:00 package/',
-      '-rw-r--r--  0 user group     1234 Jan  1 00:00 package/file.txt',
-      'lrwxr-xr-x  0 user group        0 Jan  1 00:00 package/link -> ../../etc/passwd',
-    ].join('\n');
-    const entries = parseTarListing(sample);
-    expect(entries).toEqual<TarEntry[]>([
-      { type: 'dir', name: 'package', size: 0, linkTarget: undefined },
-      { type: 'file', name: 'package/file.txt', size: 1234, linkTarget: undefined },
-      {
-        type: 'symlink',
-        name: 'package/link',
-        size: 0,
-        linkTarget: '../../etc/passwd',
-      },
-    ]);
-  });
-
-  // SECURITY-CRITICAL CROSS-PLATFORM REGRESSION. GNU tar (Linux / prod
-  // Lambdas) renders `tar -tvf` with a slash-joined owner/group, NO link-count
-  // column, and an ISO date (`YYYY-MM-DD HH:MM`) — unlike bsdtar's
-  // `Mon DD HH:MM`. A parser that anchors on the month abbreviation matches
-  // NOTHING under GNU tar and returns [], so the pre-flight containment scan
-  // sees zero entries and every malicious archive sails through. This guards
-  // that the parser stays format-agnostic across both tar implementations.
-  it('parses GNU tar verbose form (ISO date, slash owner, no link-count col)', () => {
-    const gnu = [
-      'drwxr-xr-x user/group        0 2026-01-01 00:00 package/',
-      '-rw-r--r-- user/group     1234 2026-01-01 00:00 package/file.txt',
-      'lrwxrwxrwx user/group        0 2026-01-01 00:00 package/link -> ../../etc/passwd',
-      'hrw-r--r-- user/group        0 2026-01-01 00:00 package/hard link to package/file.txt',
-      '-rw-r--r-- user/group       11 2026-06-05 09:20:33 with-seconds.txt',
-    ].join('\n');
-    const entries = parseTarListing(gnu);
-    expect(entries).toEqual<TarEntry[]>([
-      { type: 'dir', name: 'package', size: 0, linkTarget: undefined },
-      { type: 'file', name: 'package/file.txt', size: 1234, linkTarget: undefined },
-      {
-        type: 'symlink',
-        name: 'package/link',
-        size: 0,
-        linkTarget: '../../etc/passwd',
-      },
-      {
-        type: 'hardlink',
-        name: 'package/hard',
-        size: 0,
-        linkTarget: 'package/file.txt',
-      },
-      { type: 'file', name: 'with-seconds.txt', size: 11, linkTarget: undefined },
-    ]);
-  });
-
-  // SECURITY-CRITICAL: the GNU `h... name link to target` hardlink form must be
-  // parsed into a hardlink entry whose extracted target is then FLAGGED AS
-  // ESCAPING by the containment check — proving the end-to-end guard rejects an
-  // escaping hardlink under GNU tar even though CI only runs GNU and we can only
-  // emit a synthetic GNU listing locally (bsdtar). We feed a hand-written
-  // GNU-format listing line straight to parseTarListing, then push the parsed
-  // entry through validateEntries (the same code path safeExtractTarball uses)
-  // and assert it throws. This is the platform-variance backstop: even though
-  // the fixture bytes are identical everywhere, this proves the GNU LISTING
-  // string parses + rejects.
-  it('extracts an escaping target from a synthetic GNU hardlink listing line and flags it as escaping', () => {
-    const gnuHardlink =
-      'hrw-r--r-- 0/0               0 1970-01-01 00:00 escape-hard link to ../../../../etc/passwd';
-    const parsed = parseTarListing(gnuHardlink);
-    expect(parsed).toEqual<TarEntry[]>([
-      {
-        type: 'hardlink',
-        name: 'escape-hard',
-        size: 0,
-        linkTarget: '../../../../etc/passwd',
-      },
-    ]);
-    // The extracted target is fed through the SAME containment check the
-    // pre-flight uses, and it must reject (escaping hardlink → UnsafeArchiveError).
-    expect(() => validateEntries(parsed, '/tmp/pack-target')).toThrow(
-      UnsafeArchiveError,
-    );
-    // And it is specifically the LINK-ESCAPE check that fires (not name traversal).
-    expect(() => validateEntries(parsed, '/tmp/pack-target')).toThrow(
-      /Link escape blocked/,
-    );
-  });
-
-  it('returns [] only for genuinely empty input — never silently on a real listing', () => {
-    // A non-empty listing in EITHER format must yield entries; an all-noise or
-    // empty string yields []. This catches a regression where one tar dialect
-    // parses to zero entries (the cross-platform hole).
-    expect(parseTarListing('')).toEqual([]);
-    expect(parseTarListing('\n  \n')).toEqual([]);
-    expect(
-      parseTarListing('-rw-r--r-- user/group 5 2026-01-01 00:00 a').length,
-    ).toBe(1);
-    expect(
-      parseTarListing('-rw-r--r--  0 u g 5 Jan  1 00:00 a').length,
-    ).toBe(1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Guard 1: zip-slip / path traversal — END TO END through a real tarball
-// ---------------------------------------------------------------------------
-
-describe('GUARD 1: zip-slip / traversal (end-to-end)', () => {
-  it('rejects a tarball with a `../` escaping entry; nothing written outside', () => {
-    // Build a tarball whose recorded member name genuinely escapes by emitting
-    // the tar bytes directly — the stored entry name is literally
-    // `../evil-escape` on EVERY platform (GNU tar would have stripped the `../`
-    // had we used `tar -c`, defeating the test on Linux).
-    const tb = writeMaliciousTarGz(path.join(scratch, 'slip.tgz'), [
-      { name: '../evil-escape', content: 'pwned' },
-    ]);
-
-    // Sanity: the recorded entry name does escape with `..` (the READING side
-    // never strips, so this holds on bsdtar and GNU tar alike).
-    const listing = execFileSync('tar', ['-tf', tb], { encoding: 'utf-8' });
-    expect(listing).toMatch(/\.\.\//);
-
-    const finalDir = path.join(scratch, 'out');
-    const canary = path.join(scratch, 'evil-escape'); // sibling of finalDir
-    expect(() => safeExtractTarball(tb, finalDir)).toThrow(UnsafeArchiveError);
-    // Nothing written outside the (never-created) target.
-    expect(fs.existsSync(finalDir)).toBe(false);
-    expect(fs.existsSync(canary)).toBe(false);
-    // No leftover staging dirs.
-    expect(fs.readdirSync(scratch).filter((n) => n.includes('.out.staging-'))).toHaveLength(0);
-  });
-
-  it('rejects an absolute-path entry via validateEntries', () => {
-    const entries: TarEntry[] = [
-      { type: 'file', name: '/etc/cron.d/evil', size: 10 },
-    ];
-    expect(() => validateEntries(entries, '/tmp/target')).toThrow(
-      /Path traversal blocked/,
-    );
-  });
-
-  it('rejects a tarball with an absolute-path entry END TO END; nothing written', () => {
-    // Deterministic absolute-path fixture: GNU tar strips the leading `/` on
-    // create, so this must be written byte-for-byte to genuinely carry an
-    // absolute entry name on Linux too.
-    const tb = writeMaliciousTarGz(path.join(scratch, 'abs.tgz'), [
-      { name: '/tmp/hq-evil-absolute', content: 'pwned' },
-    ]);
-
-    // Sanity: the recorded entry name is absolute (READING never strips).
-    const listing = execFileSync('tar', ['-tf', tb], { encoding: 'utf-8' });
-    expect(listing).toMatch(/^\/tmp\/hq-evil-absolute/m);
-
-    const finalDir = path.join(scratch, 'out-abs');
-    expect(() => safeExtractTarball(tb, finalDir)).toThrow(UnsafeArchiveError);
-    expect(fs.existsSync(finalDir)).toBe(false);
-    // The absolute target was never created (pre-flight rejected before extract).
-    expect(fs.existsSync('/tmp/hq-evil-absolute')).toBe(false);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Guard 1b: symlink / hardlink escape
-// ---------------------------------------------------------------------------
-
-describe('GUARD 1b: symlink / hardlink escape (end-to-end)', () => {
-  it('rejects a tarball containing a symlink whose target escapes the pack dir', () => {
-    // Deterministic symlink-escape fixture (typeflag '2', linkname escapes).
-    // Built byte-for-byte so the escaping linkname is preserved on every
-    // platform; the pre-flight link-target containment check rejects it.
-    const tb = writeMaliciousTarGz(path.join(scratch, 'symlink.tgz'), [
-      { name: 'escape-link', type: 'symlink', linkname: '../../../../etc/passwd' },
-      { name: 'ok.txt', content: 'fine' },
-    ]);
-
-    // Sanity: the listing records the escaping link target verbatim.
-    const listing = execFileSync('tar', ['-tvf', tb], { encoding: 'utf-8' });
-    expect(listing).toMatch(/escape-link -> \.\.\/\.\.\/\.\.\/\.\.\/etc\/passwd/);
-
-    const finalDir = path.join(scratch, 'out');
-    expect(() => safeExtractTarball(tb, finalDir)).toThrow(UnsafeArchiveError);
-    expect(fs.existsSync(finalDir)).toBe(false);
-  });
-
-  it('rejects a tarball containing a hardlink whose target escapes the pack dir', () => {
-    // Deterministic hardlink-escape fixture (typeflag '1', linkname escapes).
-    // The bytes are identical on every platform, but the two `tar` dialects
-    // REJECT the escape via DIFFERENT mechanisms, so we assert the SECURITY
-    // OUTCOME (throws + nothing escapes + nothing wired), not a specific error
-    // type:
-    //   - bsdtar (macOS) preserves the `../` hardlink target in `-tvf`, so the
-    //     pre-flight link-target containment check throws UnsafeArchiveError
-    //     BEFORE extraction.
-    //   - GNU tar (Linux/prod) STRIPS the leading `../` from hardlink targets
-    //     on both read and extract, so the listing looks contained and the
-    //     pre-flight can't flag it — but GNU tar then refuses the link at
-    //     extract time ("Cannot hard link to 'etc/passwd'") and exits non-zero,
-    //     so safeExtractTarball throws an extraction error and the atomic
-    //     staging is rolled back. Either way the escape is neutralized.
-    const tb = writeMaliciousTarGz(path.join(scratch, 'hardlink.tgz'), [
-      { name: 'escape-hard', type: 'hardlink', linkname: '../../../../etc/passwd' },
-      { name: 'ok.txt', content: 'fine' },
-    ]);
-
-    const finalDir = path.join(scratch, 'out-hard');
-    const canary = '/etc/passwd-hq-hardlink-canary'; // never created by the guard
-    // The escaping hardlink MUST be rejected (strict — it MUST throw); the
-    // error TYPE differs by tar dialect (guard UnsafeArchiveError vs tar
-    // extraction error), so accept any throw and prove the escape outcome below.
-    expect(() => safeExtractTarball(tb, finalDir)).toThrow();
-    // Anti-vacuity: nothing wired (no final dir), no staging leftover, and the
-    // escaping target was never reachable for a write.
-    expect(fs.existsSync(finalDir)).toBe(false);
-    expect(fs.existsSync(canary)).toBe(false);
-    expect(
-      fs.readdirSync(scratch).filter((n) => n.includes('.out-hard.staging-')),
-    ).toHaveLength(0);
-  });
-
-  it('accepts a symlink whose target stays inside the pack dir', () => {
-    const src = path.join(scratch, 'src-ok');
-    fs.mkdirSync(src, { recursive: true });
-    fs.writeFileSync(path.join(src, 'real.txt'), 'data');
-    fs.symlinkSync('real.txt', path.join(src, 'alias.txt')); // in-tree relative
-    const tb = tarball('symlink-ok.tgz', src, ['real.txt', 'alias.txt']);
-
-    const finalDir = path.join(scratch, 'out-ok');
-    expect(() => safeExtractTarball(tb, finalDir)).not.toThrow();
-    expect(fs.existsSync(path.join(finalDir, 'real.txt'))).toBe(true);
-    expect(fs.lstatSync(path.join(finalDir, 'alias.txt')).isSymbolicLink()).toBe(true);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Guard 2: decompression-bomb caps
-// ---------------------------------------------------------------------------
-
-describe('GUARD 2: decompression-bomb caps', () => {
-  const tinyCaps: ExtractCaps = {
-    maxUncompressedBytes: 1024,
-    maxFileCount: 5,
-    maxSingleFileBytes: 512,
-  };
-
-  it('aborts on file-count cap (many entries) before extracting', () => {
-    const src = path.join(scratch, 'many');
-    fs.mkdirSync(src, { recursive: true });
-    const members: string[] = [];
-    for (let i = 0; i < 20; i++) {
-      const n = `f${i}.txt`;
-      fs.writeFileSync(path.join(src, n), 'x');
-      members.push(n);
-    }
-    const tb = tarball('many.tgz', src, members);
-
-    const finalDir = path.join(scratch, 'out-many');
-    expect(() => safeExtractTarball(tb, finalDir, { caps: tinyCaps })).toThrow(
-      /Decompression-bomb guard.*entries/,
-    );
-    expect(fs.existsSync(finalDir)).toBe(false);
-  });
-
-  it('aborts on per-file size cap', () => {
-    const src = path.join(scratch, 'big');
-    fs.mkdirSync(src, { recursive: true });
-    fs.writeFileSync(path.join(src, 'big.bin'), Buffer.alloc(2048, 0)); // > 512
-    const tb = tarball('big.tgz', src, ['big.bin']);
-
-    const finalDir = path.join(scratch, 'out-big');
-    expect(() => safeExtractTarball(tb, finalDir, { caps: tinyCaps })).toThrow(
-      /per-file limit/,
-    );
-    expect(fs.existsSync(finalDir)).toBe(false);
-  });
-
-  it('aborts on cumulative uncompressed size cap', () => {
-    const src = path.join(scratch, 'cum');
-    fs.mkdirSync(src, { recursive: true });
-    // Each 400 bytes (< per-file 512) but together > 1024 total.
-    for (const n of ['a', 'b', 'c']) {
-      fs.writeFileSync(path.join(src, n), Buffer.alloc(400, 0));
-    }
-    const tb = tarball('cum.tgz', src, ['a', 'b', 'c']);
-
-    const finalDir = path.join(scratch, 'out-cum');
-    expect(() => safeExtractTarball(tb, finalDir, { caps: tinyCaps })).toThrow(
-      /cumulative uncompressed size exceeded/,
-    );
-    expect(fs.existsSync(finalDir)).toBe(false);
-  });
-
-  it('default caps are sane (documented constants present)', () => {
-    expect(DEFAULT_CAPS.maxUncompressedBytes).toBe(256 * 1024 * 1024);
-    expect(DEFAULT_CAPS.maxFileCount).toBe(20_000);
-    expect(DEFAULT_CAPS.maxSingleFileBytes).toBe(64 * 1024 * 1024);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Guard 3: staged + atomic — mid-extract failure rolls back fully
-// ---------------------------------------------------------------------------
-
-describe('GUARD 3: atomic staging + rollback', () => {
-  function benignTarball(): string {
-    const src = path.join(scratch, 'benign');
-    fs.mkdirSync(path.join(src, 'package'), { recursive: true });
-    fs.writeFileSync(path.join(src, 'package', 'package.yaml'), 'name: hq-pack-x\n');
-    fs.writeFileSync(path.join(src, 'package', 'README.md'), '# x\n');
-    return tarball('benign.tgz', src, ['package']);
-  }
-
-  it('commits atomically on success — final dir appears, no staging left', () => {
-    const tb = benignTarball();
-    const finalDir = path.join(scratch, 'committed');
-    safeExtractTarball(tb, finalDir);
-    expect(fs.existsSync(path.join(finalDir, 'package', 'package.yaml'))).toBe(true);
-    expect(fs.readdirSync(scratch).filter((n) => n.includes('.committed.staging-'))).toHaveLength(0);
-  });
-
-  it('mid-extract failure aborts: NO final dir, NO staging dir remains', () => {
-    const tb = benignTarball();
-    const finalDir = path.join(scratch, 'failed');
-    expect(() =>
-      safeExtractTarball(tb, finalDir, {
-        afterExtractHook: () => {
-          throw new Error('injected mid-extract failure');
-        },
-      }),
-    ).toThrow(/injected mid-extract failure/);
-
-    // Full rollback: nothing wired, nothing staged.
-    expect(fs.existsSync(finalDir)).toBe(false);
-    const leftovers = fs.readdirSync(scratch).filter((n) => n.includes('.failed.staging-'));
-    expect(leftovers).toHaveLength(0);
-  });
-
-  it('refuses to extract over an existing final dir (no clobber)', () => {
-    const tb = benignTarball();
-    const finalDir = path.join(scratch, 'exists');
-    fs.mkdirSync(finalDir, { recursive: true });
-    fs.writeFileSync(path.join(finalDir, 'keep.txt'), 'precious');
-    expect(() => safeExtractTarball(tb, finalDir)).toThrow(/refusing to extract over/);
-    // Pre-existing content untouched.
-    expect(fs.readFileSync(path.join(finalDir, 'keep.txt'), 'utf-8')).toBe('precious');
-  });
-});