@indigoai-us/hq-cli 5.33.0 → 5.34.0

package/dist/commands/rescue.js

@@ -0,0 +1,161 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e0da62c9-7fd5-5514-b2d0-1b5b76ebcd21")}catch(e){}}();
+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';
+/**
+ * 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, latestTag) {
+    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() {
+    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) {
+    const headers = {
+        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, token) {
+    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());
+    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, tag, token) {
+    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());
+    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());
+    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) {
+    const file = path.join(hqRoot, 'core', 'core.yaml');
+    if (!fs.existsSync(file))
+        return undefined;
+    try {
+        const doc = yaml.load(fs.readFileSync(file, 'utf8'));
+        const v = doc?.hqVersion;
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registerRescueCommand(program) {
+    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) => {
+        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);
+        }
+    });
+}
+//# sourceMappingURL=rescue.js.map
+//# debugId=e0da62c9-7fd5-5514-b2d0-1b5b76ebcd21

package/dist/commands/safe-extract.d.ts

@@ -0,0 +1,154 @@
+/**
+ * safe-extract — hardened tarball extraction for the content-pack installer.
+ *
+ * THREAT MODEL (US-020). A pack tarball is UNTRUSTED input fetched from npm,
+ * a git remote, or a local path the user merely pointed at. Naively shelling
+ * out to `tar -xzf <tarball> -C <dir>` trusts the archive to behave; a hostile
+ * archive can:
+ *
+ *   1. Path traversal / "zip slip": an entry named `../../etc/cron.d/evil` or
+ *      an absolute `/etc/passwd` escapes the intended target dir and clobbers
+ *      arbitrary files (RCE if it lands a hook / cron / shell-rc).
+ *   2. Symlink/hardlink escape: an entry that is a symlink whose target points
+ *      OUTSIDE the pack dir (e.g. `link -> /etc`), optionally followed by a
+ *      second entry that writes "through" the link — the classic two-step
+ *      tar symlink attack.
+ *   3. Decompression bomb: a tiny `.tgz` that inflates to terabytes (many
+ *      files, or one enormous sparse/zero file), exhausting disk or memory.
+ *
+ * DEFENSE (defense-in-depth, default-deny):
+ *   - PRE-FLIGHT: enumerate every entry's header (type, size, name, link
+ *     target) via `tar -tv` WITHOUT extracting. Reject the whole archive if
+ *     ANY entry fails a containment or cap check. Containment uses normalized
+ *     path-prefix logic on the *resolved* path, never naive string matching.
+ *   - CAPS: enforced against the header-reported uncompressed sizes during the
+ *     pre-flight scan, so we abort BEFORE writing a single byte of a bomb.
+ *   - STAGED + ATOMIC: extraction lands in a sibling staging dir on the SAME
+ *     filesystem as the final destination; only after a successful, fully
+ *     validated extract do we `fs.rename` it into place (atomic). Any failure
+ *     mid-extract rolls the staging dir back entirely (`rm -rf` in finally) —
+ *     no partial/half-wired pack is ever left behind.
+ *   - POST-EXTRACT: an independent realpath containment sweep over everything
+ *     actually written (we do NOT rely solely on the pre-flight scan or on the
+ *     tar binary's own protections).
+ */
+export interface ExtractCaps {
+    /** Max total uncompressed bytes across all entries. Default 256 MiB. */
+    maxUncompressedBytes: number;
+    /** Max number of entries in the archive. Default 20,000. */
+    maxFileCount: number;
+    /** Max uncompressed bytes of any single entry. Default 64 MiB. */
+    maxSingleFileBytes: number;
+}
+export declare const DEFAULT_CAPS: ExtractCaps;
+export declare class UnsafeArchiveError extends Error {
+    constructor(message: string);
+}
+export type EntryType = 'file' | 'dir' | 'symlink' | 'hardlink' | 'other';
+export interface TarEntry {
+    type: EntryType;
+    /** Entry path as recorded in the archive (may contain `..`, be absolute…). */
+    name: string;
+    /** Uncompressed size in bytes from the header (0 for dirs/links). */
+    size: number;
+    /** For sym/hardlinks: the link target as recorded in the archive. */
+    linkTarget?: string;
+}
+/**
+ * Parse the verbose listing produced by `tar -tv`. We use the verbose form so
+ * we get the type flag, size, and (for links) the `name -> target` /
+ * `name link to target` suffix without extracting anything.
+ *
+ * SECURITY-CRITICAL CROSS-PLATFORM NOTE. bsdtar (macOS/BSD) and GNU tar
+ * (Linux / prod Lambdas) format the verbose listing DIFFERENTLY, and an
+ * implementation that only understands one of them silently parses ZERO
+ * entries against the other — which means the pre-flight containment scan
+ * sees nothing to reject and every malicious archive sails through. The two
+ * shapes we must both handle:
+ *
+ *   bsdtar:  <mode> <links> <owner> <group> <size> <Mon> <DD> <HH:MM|YYYY> <name...>
+ *     -rw-r--r--  0 user group     1234 Jan  1 00:00 path/file
+ *     lrwxr-xr-x  0 user group        0 Jan  1 00:00 link -> target
+ *
+ *   GNU:     <mode> <owner>/<group> <size> <YYYY-MM-DD> <HH:MM[:SS]> <name...>
+ *     -rw-r--r-- user/group     1234 2026-01-01 00:00 path/file
+ *     lrwxrwxrwx user/group        0 2026-01-01 00:00 link -> target
+ *     hrw-r--r-- user/group        0 2026-01-01 00:00 hard link to target
+ *
+ * GNU has NO link-count column, joins owner/group with `/`, and renders the
+ * date ISO-style (`YYYY-MM-DD HH:MM`) instead of `Mon DD HH:MM`. The previous
+ * parser anchored on a `[A-Za-z]{3}` month token, so it matched NOTHING under
+ * GNU tar and returned [] — the cross-platform hole this fix closes.
+ *
+ * Robust strategy: do NOT anchor on the (format-divergent) date column. Anchor
+ * on the leading mode string (always present, position 0, stable type char),
+ * then take the SIZE as the last integer that appears before the date/time
+ * column, accepting BOTH date formats. The leading mode char is the type flag:
+ *   '-' file, 'd' dir, 'l' symlink, 'h' hardlink (GNU prints 'h'); bsdtar
+ *   prints hardlinks as files with a "link to" suffix, which we also detect.
+ */
+export declare function parseTarListing(verbose: string): TarEntry[];
+/**
+ * True iff `candidate` is `base` itself or strictly nested under it, judged on
+ * normalized absolute paths with a trailing-separator guard so that a sibling
+ * like `/a/baseEVIL` is NOT considered "under" `/a/base`.
+ */
+export declare function isContained(base: string, candidate: string): boolean;
+/**
+ * Resolve where an entry NAME would land under `targetDir` and assert it stays
+ * inside. Rejects absolute names and any `..` that escapes. Returns the
+ * resolved absolute path on success.
+ */
+export declare function resolveContainedPath(targetDir: string, entryName: string): string;
+/**
+ * Validate a sym/hardlink's target stays inside `packDir`. The link is created
+ * AT `entryAbs` (already known-contained), so a relative target is resolved
+ * against the link's parent dir; an absolute target is checked as-is. Either
+ * way the final location must be contained in the pack dir.
+ */
+export declare function assertLinkTargetContained(packDir: string, entryAbs: string, linkTarget: string): void;
+/**
+ * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
+ * argv form — never a shell string — so a hostile filename can't break out.
+ */
+export declare function listTarball(tarballPath: string): TarEntry[];
+/**
+ * Pre-flight validation against the entry headers. Enforces (a) containment of
+ * every entry name under `targetDir`, (b) containment of every link target
+ * under `targetDir`, and (c) the three decompression-bomb caps. Throws
+ * UnsafeArchiveError on the first violation — default-deny.
+ */
+export declare function validateEntries(entries: TarEntry[], targetDir: string, caps?: ExtractCaps): void;
+/**
+ * Walk everything actually written under `stagingDir` and assert that no entry
+ * — and, for symlinks, no link target — escapes. This is the defense-in-depth
+ * backstop: it does not trust the pre-flight scan OR the tar binary. Uses
+ * realpath on the link's PARENT (which exists) plus lstat to inspect links
+ * without following them off-tree.
+ */
+export declare function assertExtractContained(stagingDir: string): void;
+export interface SafeExtractOptions {
+    caps?: ExtractCaps;
+    /**
+     * Test seam: invoked AFTER `tar` extracts into the staging dir but BEFORE
+     * the post-extract sweep / atomic rename. Throwing here simulates a failure
+     * "mid-extract" and must leave NO staging or final dir behind.
+     */
+    afterExtractHook?: (stagingDir: string) => void;
+}
+/**
+ * Safely extract `tarballPath` so its contents land atomically at `finalDir`.
+ *
+ * Sequence:
+ *   1. Pre-flight list + validate (containment + caps) — abort before writing.
+ *   2. Extract into a sibling `*.staging-<rand>` dir on the SAME filesystem.
+ *   3. Post-extract realpath containment sweep (independent backstop).
+ *   4. `afterExtractHook` (test failure-injection seam).
+ *   5. Atomic `fs.rename(staging -> finalDir)`.
+ *   6. finally: `rm -rf` the staging dir if it still exists (rollback).
+ *
+ * On ANY failure the staging dir is removed and `finalDir` is never created,
+ * so a half-extracted pack can never be wired.
+ */
+export declare function safeExtractTarball(tarballPath: string, finalDir: string, opts?: SafeExtractOptions): void;
+//# sourceMappingURL=safe-extract.d.ts.map

package/dist/commands/safe-extract.js

@@ -0,0 +1,347 @@
+/**
+ * safe-extract — hardened tarball extraction for the content-pack installer.
+ *
+ * THREAT MODEL (US-020). A pack tarball is UNTRUSTED input fetched from npm,
+ * a git remote, or a local path the user merely pointed at. Naively shelling
+ * out to `tar -xzf <tarball> -C <dir>` trusts the archive to behave; a hostile
+ * archive can:
+ *
+ *   1. Path traversal / "zip slip": an entry named `../../etc/cron.d/evil` or
+ *      an absolute `/etc/passwd` escapes the intended target dir and clobbers
+ *      arbitrary files (RCE if it lands a hook / cron / shell-rc).
+ *   2. Symlink/hardlink escape: an entry that is a symlink whose target points
+ *      OUTSIDE the pack dir (e.g. `link -> /etc`), optionally followed by a
+ *      second entry that writes "through" the link — the classic two-step
+ *      tar symlink attack.
+ *   3. Decompression bomb: a tiny `.tgz` that inflates to terabytes (many
+ *      files, or one enormous sparse/zero file), exhausting disk or memory.
+ *
+ * DEFENSE (defense-in-depth, default-deny):
+ *   - PRE-FLIGHT: enumerate every entry's header (type, size, name, link
+ *     target) via `tar -tv` WITHOUT extracting. Reject the whole archive if
+ *     ANY entry fails a containment or cap check. Containment uses normalized
+ *     path-prefix logic on the *resolved* path, never naive string matching.
+ *   - CAPS: enforced against the header-reported uncompressed sizes during the
+ *     pre-flight scan, so we abort BEFORE writing a single byte of a bomb.
+ *   - STAGED + ATOMIC: extraction lands in a sibling staging dir on the SAME
+ *     filesystem as the final destination; only after a successful, fully
+ *     validated extract do we `fs.rename` it into place (atomic). Any failure
+ *     mid-extract rolls the staging dir back entirely (`rm -rf` in finally) —
+ *     no partial/half-wired pack is ever left behind.
+ *   - POST-EXTRACT: an independent realpath containment sweep over everything
+ *     actually written (we do NOT rely solely on the pre-flight scan or on the
+ *     tar binary's own protections).
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="372e4f76-03b2-5287-ac66-249543f88937")}catch(e){}}();
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+export const DEFAULT_CAPS = {
+    // A content pack is docs/skills/policies/small scripts. 256 MiB is already
+    // generous; anything larger is almost certainly a bomb or a mistake.
+    maxUncompressedBytes: 256 * 1024 * 1024,
+    maxFileCount: 20_000,
+    maxSingleFileBytes: 64 * 1024 * 1024,
+};
+export class UnsafeArchiveError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsafeArchiveError';
+    }
+}
+/**
+ * Parse the verbose listing produced by `tar -tv`. We use the verbose form so
+ * we get the type flag, size, and (for links) the `name -> target` /
+ * `name link to target` suffix without extracting anything.
+ *
+ * SECURITY-CRITICAL CROSS-PLATFORM NOTE. bsdtar (macOS/BSD) and GNU tar
+ * (Linux / prod Lambdas) format the verbose listing DIFFERENTLY, and an
+ * implementation that only understands one of them silently parses ZERO
+ * entries against the other — which means the pre-flight containment scan
+ * sees nothing to reject and every malicious archive sails through. The two
+ * shapes we must both handle:
+ *
+ *   bsdtar:  <mode> <links> <owner> <group> <size> <Mon> <DD> <HH:MM|YYYY> <name...>
+ *     -rw-r--r--  0 user group     1234 Jan  1 00:00 path/file
+ *     lrwxr-xr-x  0 user group        0 Jan  1 00:00 link -> target
+ *
+ *   GNU:     <mode> <owner>/<group> <size> <YYYY-MM-DD> <HH:MM[:SS]> <name...>
+ *     -rw-r--r-- user/group     1234 2026-01-01 00:00 path/file
+ *     lrwxrwxrwx user/group        0 2026-01-01 00:00 link -> target
+ *     hrw-r--r-- user/group        0 2026-01-01 00:00 hard link to target
+ *
+ * GNU has NO link-count column, joins owner/group with `/`, and renders the
+ * date ISO-style (`YYYY-MM-DD HH:MM`) instead of `Mon DD HH:MM`. The previous
+ * parser anchored on a `[A-Za-z]{3}` month token, so it matched NOTHING under
+ * GNU tar and returned [] — the cross-platform hole this fix closes.
+ *
+ * Robust strategy: do NOT anchor on the (format-divergent) date column. Anchor
+ * on the leading mode string (always present, position 0, stable type char),
+ * then take the SIZE as the last integer that appears before the date/time
+ * column, accepting BOTH date formats. The leading mode char is the type flag:
+ *   '-' file, 'd' dir, 'l' symlink, 'h' hardlink (GNU prints 'h'); bsdtar
+ *   prints hardlinks as files with a "link to" suffix, which we also detect.
+ */
+export function parseTarListing(verbose) {
+    const entries = [];
+    for (const raw of verbose.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        if (line.trim() === '')
+            continue;
+        const modeChar = line[0];
+        // Only accept lines that actually begin with a tar mode string (10 chars:
+        // a type flag followed by 9 permission chars, possibly with a trailing
+        // ACL/xattr '+'/'@'/'.'). This skips non-entry noise without depending on
+        // the date column at all.
+        if (!/^[-dlhpscbD][-rwxXsStT]{9}[.+@]?\s/.test(line))
+            continue;
+        // The size is the last run of digits that sits immediately before the
+        // date/time column. We accept BOTH date renderings:
+        //   bsdtar: `Mon DD HH:MM` / `Mon DD  YYYY`
+        //   GNU:    `YYYY-MM-DD HH:MM[:SS]`
+        // Anchoring the size on "the integer right before a recognized date" works
+        // identically whether or not a link-count column is present (bsdtar) and
+        // whether owner/group is one slash-joined token (GNU) or two columns
+        // (bsdtar), because we only ever look at the integer adjacent to the date.
+        const dateRe = /\s(\d+)\s+(?:[A-Za-z]{3}\s+\d{1,2}\s+(?:\d{1,2}:\d{2}|\d{4})|\d{4}-\d{2}-\d{2}\s+\d{1,2}:\d{2}(?::\d{2})?)\s+/;
+        const m = dateRe.exec(line);
+        if (!m)
+            continue;
+        const size = Number.parseInt(m[1], 10);
+        const nameAndLink = line.slice(m.index + m[0].length).trim();
+        let type;
+        let name = nameAndLink;
+        let linkTarget;
+        if (modeChar === 'd') {
+            type = 'dir';
+            name = name.replace(/\/+$/, '');
+        }
+        else if (modeChar === 'l') {
+            type = 'symlink';
+            const arrow = nameAndLink.indexOf(' -> ');
+            if (arrow >= 0) {
+                name = nameAndLink.slice(0, arrow);
+                linkTarget = nameAndLink.slice(arrow + 4);
+            }
+        }
+        else if (modeChar === 'h') {
+            type = 'hardlink';
+            // GNU: "name link to target"
+            const m = / link to /.exec(nameAndLink);
+            if (m) {
+                name = nameAndLink.slice(0, m.index);
+                linkTarget = nameAndLink.slice(m.index + m[0].length);
+            }
+        }
+        else if (modeChar === '-') {
+            // bsdtar renders hardlinks as a file entry with a trailing "link to".
+            const m = / link to /.exec(nameAndLink);
+            if (m) {
+                type = 'hardlink';
+                name = nameAndLink.slice(0, m.index);
+                linkTarget = nameAndLink.slice(m.index + m[0].length);
+            }
+            else {
+                type = 'file';
+            }
+        }
+        else {
+            type = 'other';
+        }
+        entries.push({
+            type,
+            name,
+            size: Number.isFinite(size) ? size : 0,
+            linkTarget,
+        });
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Containment — normalized prefix on the RESOLVED path (not string matching)
+// ---------------------------------------------------------------------------
+/**
+ * True iff `candidate` is `base` itself or strictly nested under it, judged on
+ * normalized absolute paths with a trailing-separator guard so that a sibling
+ * like `/a/baseEVIL` is NOT considered "under" `/a/base`.
+ */
+export function isContained(base, candidate) {
+    const b = path.resolve(base);
+    const c = path.resolve(candidate);
+    if (c === b)
+        return true;
+    const withSep = b.endsWith(path.sep) ? b : b + path.sep;
+    return c.startsWith(withSep);
+}
+/**
+ * Resolve where an entry NAME would land under `targetDir` and assert it stays
+ * inside. Rejects absolute names and any `..` that escapes. Returns the
+ * resolved absolute path on success.
+ */
+export function resolveContainedPath(targetDir, entryName) {
+    // path.resolve collapses `..` segments and makes absolute names absolute to
+    // the FS root (so `/etc/passwd` resolves to itself, which then fails
+    // containment) — exactly what we want for the check.
+    const resolved = path.resolve(targetDir, entryName);
+    if (!isContained(targetDir, resolved)) {
+        throw new UnsafeArchiveError(`Path traversal blocked: entry "${entryName}" resolves to "${resolved}", ` +
+            `outside extraction dir "${path.resolve(targetDir)}".`);
+    }
+    return resolved;
+}
+/**
+ * Validate a sym/hardlink's target stays inside `packDir`. The link is created
+ * AT `entryAbs` (already known-contained), so a relative target is resolved
+ * against the link's parent dir; an absolute target is checked as-is. Either
+ * way the final location must be contained in the pack dir.
+ */
+export function assertLinkTargetContained(packDir, entryAbs, linkTarget) {
+    const resolvedTarget = path.isAbsolute(linkTarget)
+        ? path.resolve(linkTarget)
+        : path.resolve(path.dirname(entryAbs), linkTarget);
+    if (!isContained(packDir, resolvedTarget)) {
+        throw new UnsafeArchiveError(`Link escape blocked: entry "${path.relative(packDir, entryAbs)}" points to ` +
+            `"${linkTarget}" -> "${resolvedTarget}", outside pack dir "${path.resolve(packDir)}".`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-flight: list entries, enforce containment + caps WITHOUT extracting
+// ---------------------------------------------------------------------------
+/**
+ * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
+ * argv form — never a shell string — so a hostile filename can't break out.
+ */
+export function listTarball(tarballPath) {
+    const out = execFileSync('tar', ['-tvf', tarballPath], {
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseTarListing(out);
+}
+/**
+ * Pre-flight validation against the entry headers. Enforces (a) containment of
+ * every entry name under `targetDir`, (b) containment of every link target
+ * under `targetDir`, and (c) the three decompression-bomb caps. Throws
+ * UnsafeArchiveError on the first violation — default-deny.
+ */
+export function validateEntries(entries, targetDir, caps = DEFAULT_CAPS) {
+    // Count real members (dirs included — they still occupy inodes; cheap to
+    // count and keeps "many empty dirs" bombs in scope).
+    if (entries.length > caps.maxFileCount) {
+        throw new UnsafeArchiveError(`Decompression-bomb guard: archive has ${entries.length} entries, ` +
+            `exceeding the limit of ${caps.maxFileCount}.`);
+    }
+    let total = 0;
+    for (const e of entries) {
+        if (e.type === 'other') {
+            throw new UnsafeArchiveError(`Unsupported entry type for "${e.name}" — only files, dirs, and ` +
+                `contained links are allowed.`);
+        }
+        // (a) name containment — rejects `..` traversal and absolute paths.
+        const entryAbs = resolveContainedPath(targetDir, e.name);
+        // (b) link-target containment.
+        if ((e.type === 'symlink' || e.type === 'hardlink') && e.linkTarget) {
+            assertLinkTargetContained(targetDir, entryAbs, e.linkTarget);
+        }
+        // (c) per-file + cumulative caps.
+        if (e.size > caps.maxSingleFileBytes) {
+            throw new UnsafeArchiveError(`Decompression-bomb guard: entry "${e.name}" is ${e.size} bytes, ` +
+                `exceeding the per-file limit of ${caps.maxSingleFileBytes}.`);
+        }
+        total += e.size;
+        if (total > caps.maxUncompressedBytes) {
+            throw new UnsafeArchiveError(`Decompression-bomb guard: cumulative uncompressed size exceeded ` +
+                `${caps.maxUncompressedBytes} bytes (reached ${total} before finishing the scan).`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Post-extract: independent realpath containment sweep
+// ---------------------------------------------------------------------------
+/**
+ * Walk everything actually written under `stagingDir` and assert that no entry
+ * — and, for symlinks, no link target — escapes. This is the defense-in-depth
+ * backstop: it does not trust the pre-flight scan OR the tar binary. Uses
+ * realpath on the link's PARENT (which exists) plus lstat to inspect links
+ * without following them off-tree.
+ */
+export function assertExtractContained(stagingDir) {
+    const realRoot = fs.realpathSync(stagingDir);
+    const walk = (dir) => {
+        for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, dirent.name);
+            if (dirent.isSymbolicLink()) {
+                const target = fs.readlinkSync(abs);
+                const resolved = path.isAbsolute(target)
+                    ? path.resolve(target)
+                    : path.resolve(path.dirname(abs), target);
+                if (!isContained(realRoot, resolved)) {
+                    throw new UnsafeArchiveError(`Post-extract link escape: "${path.relative(realRoot, abs)}" -> "${target}".`);
+                }
+                continue; // do not descend through links
+            }
+            // Real path of the entry's parent must stay inside the root (catches a
+            // dir that is itself a link off-tree, belt-and-suspenders).
+            const realParent = fs.realpathSync(path.dirname(abs));
+            if (!isContained(realRoot, path.join(realParent, dirent.name))) {
+                throw new UnsafeArchiveError(`Post-extract path escape: "${abs}" resolves outside "${realRoot}".`);
+            }
+            if (dirent.isDirectory())
+                walk(abs);
+        }
+    };
+    walk(realRoot);
+}
+/**
+ * Safely extract `tarballPath` so its contents land atomically at `finalDir`.
+ *
+ * Sequence:
+ *   1. Pre-flight list + validate (containment + caps) — abort before writing.
+ *   2. Extract into a sibling `*.staging-<rand>` dir on the SAME filesystem.
+ *   3. Post-extract realpath containment sweep (independent backstop).
+ *   4. `afterExtractHook` (test failure-injection seam).
+ *   5. Atomic `fs.rename(staging -> finalDir)`.
+ *   6. finally: `rm -rf` the staging dir if it still exists (rollback).
+ *
+ * On ANY failure the staging dir is removed and `finalDir` is never created,
+ * so a half-extracted pack can never be wired.
+ */
+export function safeExtractTarball(tarballPath, finalDir, opts = {}) {
+    const caps = opts.caps ?? DEFAULT_CAPS;
+    if (fs.existsSync(finalDir)) {
+        throw new Error(`safeExtractTarball: refusing to extract over existing dir "${finalDir}".`);
+    }
+    // 1. Pre-flight against headers (no bytes written yet).
+    const entries = listTarball(tarballPath);
+    validateEntries(entries, finalDir, caps);
+    // 2. Sibling staging dir on the same filesystem so the rename is atomic.
+    const parent = path.dirname(path.resolve(finalDir));
+    fs.mkdirSync(parent, { recursive: true });
+    const stagingDir = fs.mkdtempSync(path.join(parent, `.${path.basename(finalDir)}.staging-`));
+    try {
+        // `--no-same-owner` avoids chown surprises when run as root; argv form, no
+        // shell. We deliberately re-extract here (not the pre-flight listing) and
+        // re-validate after, rather than trusting tar to honor any single flag.
+        execFileSync('tar', ['-xzf', tarballPath, '-C', stagingDir, '--no-same-owner'], { stdio: 'inherit' });
+        // 3. Independent backstop sweep over what actually landed.
+        assertExtractContained(stagingDir);
+        // 4. Failure-injection seam (tests).
+        opts.afterExtractHook?.(stagingDir);
+        // 5. Atomic commit. `fs.renameSync` is atomic within a filesystem; the
+        //    staged contents are fully present and validated before this point, so
+        //    the live location only ever sees a complete pack — never a partial.
+        fs.renameSync(stagingDir, finalDir);
+    }
+    finally {
+        // Rollback: if anything before the rename threw, the staging dir still
+        // exists and is removed here — no partial/half-wired pack survives. After a
+        // successful rename the staging dir is gone, so this is a no-op.
+        if (fs.existsSync(stagingDir)) {
+            fs.rmSync(stagingDir, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=safe-extract.js.map
+//# debugId=372e4f76-03b2-5287-ac66-249543f88937