@indigoai-us/hq-cli 5.32.0 → 5.33.1

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

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="89e1a66a-6a45-56a3-847c-2f0beba1429b")}catch(e){}}();
+!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]="83d8729b-5b5c-50b8-8785-372d61feb425")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -24,6 +24,7 @@ import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
 import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
 import { registerPackageListCommand } from "./commands/pkg-list.js";
 import { registerPacksCommand } from "./commands/packs.js";
+import { registerPublishCommand } from "./commands/publish.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
@@ -84,6 +85,10 @@ registerPacksCommand(program);
 // "hq remove <slug>"  = "hq packages remove <slug>"
 registerPackageInstallCommand(program);
 registerPackageRemoveCommand(program);
+// Marketplace publish (top-level — packer + authenticated upload, US-004)
+// "hq publish <skill-or-worker-path>" packages and submits a pack to the
+// marketplace via POST /v1/listings.
+registerPublishCommand(program);
 // Cloud sync subcommand group
 const syncCmd = program
     .command("sync")
@@ -158,4 +163,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=89e1a66a-6a45-56a3-847c-2f0beba1429b
+//# debugId=83d8729b-5b5c-50b8-8785-372d61feb425

package/dist/lib/local-tree-diff.d.ts

@@ -89,6 +89,27 @@ export interface BuildNarrowPlanInput {
  *     files yet.
  */
 export declare function buildNarrowPlan(input: BuildNarrowPlanInput): NarrowPlan;
+/**
+ * Recursive readdir walk yielding regular files (and dangling-target
+ * symlinks — those are recorded as files for narrow-plan purposes; the
+ * delete path uses `fs.unlinkSync` which handles symlinks correctly).
+ *
+ * Uses `lstat` rather than `stat` so a symlink's size doesn't follow the
+ * target chain (matches the share-engine convention).
+ */
+/**
+ * Normalize OS-native path separators to POSIX "/" for vault keys.
+ *
+ * `path.relative()` yields "\\"-separated paths on Windows, but vault S3 keys
+ * are always "/"-separated — the server splits keys on "/" to rebuild the tree
+ * and the journal + grants endpoint use that same namespace. Emit POSIX keys
+ * regardless of client OS so a Windows narrow-plan lines up with the
+ * forward-slash keys everywhere else. Mirrors the same normalization on
+ * @indigoai-us/hq-cloud's upload path. Converting "\\" explicitly (rather than
+ * only path.sep) keeps the result correct — and the regression test meaningful
+ * — on a POSIX CI too.
+ */
+export declare function toPosixKey(p: string): string;
 /**
  * Render the dry-run summary as plain text (no chalk — keep it pure). The
  * CLI wrapper can colorize lines afterwards if desired.

package/dist/lib/local-tree-diff.js

@@ -24,7 +24,7 @@
  * for the destructive side effects (delete, tombstone, PUT sync-config).
  */
 
-!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]="20a280f3-0fed-5868-9ad4-fcc562253486")}catch(e){}}();
+!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]="8f0265e5-8320-54bb-b2c9-b03ee9581af8")}catch(e){}}();
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { hashFile, isCoveredByAny, } from "@indigoai-us/hq-cloud";
@@ -109,6 +109,21 @@ function emptyPlan() {
  * Uses `lstat` rather than `stat` so a symlink's size doesn't follow the
  * target chain (matches the share-engine convention).
  */
+/**
+ * Normalize OS-native path separators to POSIX "/" for vault keys.
+ *
+ * `path.relative()` yields "\\"-separated paths on Windows, but vault S3 keys
+ * are always "/"-separated — the server splits keys on "/" to rebuild the tree
+ * and the journal + grants endpoint use that same namespace. Emit POSIX keys
+ * regardless of client OS so a Windows narrow-plan lines up with the
+ * forward-slash keys everywhere else. Mirrors the same normalization on
+ * @indigoai-us/hq-cloud's upload path. Converting "\\" explicitly (rather than
+ * only path.sep) keeps the result correct — and the regression test meaningful
+ * — on a POSIX CI too.
+ */
+export function toPosixKey(p) {
+    return p.split("\\").join("/");
+}
 function walkLocal(dir, 
 // Rel-root for `relPath` — the company walk root (`<hqRoot>/companies/<slug>`),
 // so emitted `relPath`s are company-relative. Fixed across recursion.
@@ -127,7 +142,7 @@ relRoot, emit) {
     }
     for (const entry of entries) {
         const absPath = path.join(dir, entry.name);
-        const relPath = path.relative(relRoot, absPath);
+        const relPath = toPosixKey(path.relative(relRoot, absPath));
         if (entry.isSymbolicLink()) {
             // Record the link as a file-like entry. Don't descend — narrow is
             // about pruning files that the LOCAL tree has materialized here; a
@@ -253,4 +268,4 @@ export function formatBytes(n) {
     return `${v.toFixed(2)} ${units[i]}`;
 }
 //# sourceMappingURL=local-tree-diff.js.map
-//# debugId=20a280f3-0fed-5868-9ad4-fcc562253486
+//# debugId=8f0265e5-8320-54bb-b2c9-b03ee9581af8

package/dist/types.d.ts

@@ -57,6 +57,17 @@ export interface SyncResult {
     filesChanged?: number;
 }
 export type PackContributeKey = 'workers' | 'knowledge' | 'skills' | 'commands' | 'hooks' | 'policies' | 'scripts';
+/**
+ * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —
+ * packs published before this field still validate. When present, install can
+ * attribute the pack to a creator: `uid` is the HQ person UID, `handle` the
+ * creator's marketplace handle, `displayName` the human-readable name.
+ */
+export interface PackAuthor {
+    uid: string;
+    handle: string;
+    displayName: string;
+}
 export interface PackManifest {
     name: string;
     version: string;
@@ -71,5 +82,16 @@ export interface PackManifest {
     repository?: string;
     keywords?: string[];
     conditional?: string;
+    /**
+     * Pack authorship attribution (US-001). Optional — absent on legacy packs.
+     */
+    author?: PackAuthor;
+    /**
+     * Declared capabilities the pack touches (US-001), e.g. hooks/scripts/
+     * network/fs/secrets. Optional, free-form string entries — surfaced to the
+     * user at install time for an at-a-glance trust signal. Reserved here; not
+     * yet enforced.
+     */
+    capabilities?: string[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/vault-api.d.ts

@@ -6,6 +6,17 @@ export interface VaultApiOptions {
     query?: Record<string, string>;
 }
 export declare function vaultApiFetch(opts: VaultApiOptions): Promise<Response>;
+/**
+ * Public (NONE-auth) GET against the vault API — no bearer token. The
+ * marketplace browse endpoints (`GET /v1/listings`, `GET /v1/listings/{id}`)
+ * from US-005 are public so a logged-out user can resolve + download an
+ * approved pack. Distinct from `vaultApiFetch`, which always attaches a
+ * bearer token.
+ */
+export declare function vaultApiFetchPublic(opts: {
+    path: string;
+    query?: Record<string, string>;
+}): Promise<Response>;
 export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
 export declare function resolveCallerPersonUid(token: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {