@indigoai-us/hq-cli 5.33.0 → 5.34.0

package/src/commands/rescue.ts

@@ -0,0 +1,210 @@
+/**
+ * hq rescue — re-sync the local HQ core to an upstream hq-core release (or the
+ * staging branch) WITHOUT destroying local edits ("drift").
+ *
+ * Thin driver over @indigoai-us/hq-cloud's `rescue()`, which execs the bundled
+ * scripts/replace-rescue.sh against the HQ root. This is the CLI sibling of the
+ * HQ Sync menubar app's "Update / Restore" pill — both drive the exact same
+ * rescue script, just resolved from the shared hq-cloud package.
+ *
+ * Prod (default): resolves the latest `indigoai-us/hq-core` release tag and
+ * pins the three-way history floor to the commit of the user's currently
+ * installed version (read from core/core.yaml). Staging (`--staging`): targets
+ * `indigoai-us/hq-core-staging@main` and lets the script read its on-disk
+ * sync stamp for the floor.
+ */
+import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import chalk from 'chalk';
+import { rescue } from '@indigoai-us/hq-cloud';
+import { findHqRoot } from '../utils/manifest.js';
+
+const PROD_SOURCE = 'indigoai-us/hq-core';
+const STAGING_SOURCE = 'indigoai-us/hq-core-staging';
+
+export interface RescueTarget {
+  source: string;
+  /** undefined → let the script apply its own default ref (`main`). */
+  ref?: string;
+}
+
+/**
+ * Resolve the source repo + ref from the user's flags. Pure + exported for
+ * tests. `latestTag` is the resolved latest release tag (prod only); ignored
+ * for staging and when an explicit `--ref` is given.
+ */
+export function resolveRescueTarget(
+  opts: { staging?: boolean; source?: string; ref?: string },
+  latestTag?: string
+): RescueTarget {
+  if (opts.staging) {
+    return { source: opts.source ?? STAGING_SOURCE, ref: opts.ref };
+  }
+  return { source: opts.source ?? PROD_SOURCE, ref: opts.ref ?? latestTag };
+}
+
+/** Resolve a GitHub token: prefer `gh auth token`, fall back to env. */
+function resolveGhToken(): string | undefined {
+  try {
+    const res = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8' });
+    if (res.status === 0) {
+      const tok = res.stdout.trim();
+      if (tok) return tok;
+    }
+  } catch {
+    // gh not installed — fall through to env.
+  }
+  return process.env.GH_TOKEN || process.env.GITHUB_TOKEN || undefined;
+}
+
+function ghHeaders(token?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'User-Agent': 'hq-cli-rescue',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+/** Latest release tag for a repo, e.g. `v12.3.0`. Throws on failure. */
+async function getLatestReleaseTag(repo: string, token?: string): Promise<string> {
+  const res = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
+    headers: ghHeaders(token),
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub releases/latest for ${repo}: HTTP ${res.status}`);
+  }
+  const body = (await res.json()) as { tag_name?: string };
+  if (!body.tag_name) throw new Error(`no tag_name in latest release for ${repo}`);
+  return body.tag_name;
+}
+
+/** Resolve a tag to its commit SHA, dereferencing annotated tags. */
+async function resolveTagSha(repo: string, tag: string, token?: string): Promise<string> {
+  const refRes = await fetch(
+    `https://api.github.com/repos/${repo}/git/ref/tags/${encodeURIComponent(tag)}`,
+    { headers: ghHeaders(token) }
+  );
+  if (!refRes.ok) throw new Error(`git/ref/tags/${tag} for ${repo}: HTTP ${refRes.status}`);
+  const ref = (await refRes.json()) as { object?: { type?: string; sha?: string } };
+  const obj = ref.object;
+  if (!obj?.sha) throw new Error(`no object.sha for tag ${tag} in ${repo}`);
+  if (obj.type !== 'tag') return obj.sha; // lightweight tag → already a commit
+  // Annotated tag → dereference to the commit it points at.
+  const tagRes = await fetch(`https://api.github.com/repos/${repo}/git/tags/${obj.sha}`, {
+    headers: ghHeaders(token),
+  });
+  if (!tagRes.ok) throw new Error(`git/tags/${obj.sha} for ${repo}: HTTP ${tagRes.status}`);
+  const annotated = (await tagRes.json()) as { object?: { sha?: string } };
+  if (!annotated.object?.sha) throw new Error(`annotated tag ${tag} has no target sha`);
+  return annotated.object.sha;
+}
+
+/** Read the installed HQ core version from `{hqRoot}/core/core.yaml`. */
+function readInstalledVersion(hqRoot: string): string | undefined {
+  const file = path.join(hqRoot, 'core', 'core.yaml');
+  if (!fs.existsSync(file)) return undefined;
+  try {
+    const doc = yaml.load(fs.readFileSync(file, 'utf8')) as { hqVersion?: unknown } | null;
+    const v = doc?.hqVersion;
+    return typeof v === 'string' ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function registerRescueCommand(program: Command): void {
+  program
+    .command('rescue')
+    .description(
+      'Re-sync your HQ core to the latest release, preserving your local edits (drift)'
+    )
+    .option('--hq-root <path>', 'HQ root to operate on (defaults to auto-detected root)')
+    .option('--ref <ref>', 'Target tag/branch (default: latest hq-core release)')
+    .option('--source <repo>', 'Source repo (default: indigoai-us/hq-core)')
+    .option('--staging', 'Use the staging channel (indigoai-us/hq-core-staging@main)')
+    .option('--floor-sha <sha>', 'Pin the three-way history floor to a 40-char commit SHA')
+    .option('--paths <list>', 'Comma-separated top-level paths to narrow the rescue to')
+    .option('--check', 'Plan only — classify and report, change nothing on disk (--dry-run)')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .option('--no-backup', 'Skip the pre-op safety snapshot under ~/.hq/backups')
+    .option('--cloud-update', 'Cloud-update mode')
+    .action(
+      async (opts: {
+        hqRoot?: string;
+        ref?: string;
+        source?: string;
+        staging?: boolean;
+        floorSha?: string;
+        paths?: string;
+        check?: boolean;
+        yes?: boolean;
+        backup?: boolean; // --no-backup → false
+        cloudUpdate?: boolean;
+      }) => {
+        try {
+          const hqRoot = opts.hqRoot ?? findHqRoot();
+          const token = resolveGhToken();
+
+          let { source, ref } = resolveRescueTarget(opts);
+          let floorSha = opts.floorSha;
+
+          if (!opts.staging) {
+            // Prod: resolve the latest release tag when no explicit ref, and
+            // pin the floor to the installed version's commit when possible.
+            if (!ref) {
+              ref = await getLatestReleaseTag(source, token);
+            }
+            if (!floorSha) {
+              const installed = readInstalledVersion(hqRoot);
+              if (installed) {
+                try {
+                  floorSha = await resolveTagSha(source, `v${installed}`, token);
+                } catch (err) {
+                  console.warn(
+                    chalk.yellow(
+                      `Warning: couldn't resolve the floor commit for v${installed} ` +
+                        `(${err instanceof Error ? err.message : 'unknown error'}); ` +
+                        `falling back to the on-disk sync stamp.`
+                    )
+                  );
+                }
+              }
+            }
+          }
+
+          console.log(
+            chalk.dim(
+              `Rescuing ${hqRoot} from ${source}${ref ? `@${ref}` : ''}` +
+                `${floorSha ? ` (floor ${floorSha.slice(0, 12)})` : ''}` +
+                `${opts.check ? ' [dry-run]' : ''}`
+            )
+          );
+
+          const { status } = rescue({
+            hqRoot,
+            source,
+            ref,
+            floorSha,
+            paths: opts.paths ? opts.paths.split(',').map((p) => p.trim()).filter(Boolean) : undefined,
+            dryRun: opts.check,
+            assumeYes: opts.yes,
+            noBackup: opts.backup === false,
+            cloudUpdate: opts.cloudUpdate,
+            ghToken: token,
+          });
+          process.exit(status);
+        } catch (error) {
+          console.error(
+            chalk.red('Error:'),
+            error instanceof Error ? error.message : 'Unknown error'
+          );
+          process.exit(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');
+  });
+});