@indigoai-us/hq-cli 5.32.0 → 5.33.1

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

@@ -0,0 +1,459 @@
+/**
+ * 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');
+  });
+});