@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/safe-extract.ts

@@ -1,444 +0,0 @@
-/**
- * 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).
- */
-
-import { execFileSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-
-// ---------------------------------------------------------------------------
-// Caps (decompression-bomb guard). Named constants with documented defaults.
-// Overridable per-call so tests can trip the tripwire cheaply (and so US-024's
-// adversarial suite can reuse low caps without building literal multi-GB
-// fixtures).
-// ---------------------------------------------------------------------------
-
-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 const DEFAULT_CAPS: ExtractCaps = {
-  // 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: string) {
-    super(message);
-    this.name = 'UnsafeArchiveError';
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Entry-header model + tar listing parser
-// ---------------------------------------------------------------------------
-
-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 function parseTarListing(verbose: string): TarEntry[] {
-  const entries: TarEntry[] = [];
-  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: EntryType;
-    let name = nameAndLink;
-    let linkTarget: string | undefined;
-
-    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: string, candidate: string): boolean {
-  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: string, entryName: string): string {
-  // 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: string,
-  entryAbs: string,
-  linkTarget: string,
-): void {
-  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: string): TarEntry[] {
-  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: TarEntry[],
-  targetDir: string,
-  caps: ExtractCaps = DEFAULT_CAPS,
-): void {
-  // 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: string): void {
-  const realRoot = fs.realpathSync(stagingDir);
-  const walk = (dir: string): void => {
-    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);
-}
-
-// ---------------------------------------------------------------------------
-// Public: staged + atomic safe extraction
-// ---------------------------------------------------------------------------
-
-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 function safeExtractTarball(
-  tarballPath: string,
-  finalDir: string,
-  opts: SafeExtractOptions = {},
-): void {
-  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 });
-    }
-  }
-}

package/src/commands/secrets-scope.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  describeSecretsScope,
-  formatSecretSaved,
-  formatSecretsListEmpty,
-  formatSecretsListHeader,
-} from "./secrets-scope.js";
-
-describe("describeSecretsScope", () => {
-  it("describes the personal vault", () => {
-    expect(
-      describeSecretsScope({ personal: true, companyUid: "prs_alice" }),
-    ).toBe("your personal vault");
-  });
-
-  it("describes a company by slug when present", () => {
-    expect(
-      describeSecretsScope({
-        personal: false,
-        companySlug: "acme",
-        companyUid: "cmp_01ABC",
-      }),
-    ).toBe("company acme");
-  });
-
-  it("describes a company by uid when no slug is present", () => {
-    expect(
-      describeSecretsScope({ personal: false, companyUid: "cmp_01ABC" }),
-    ).toBe("company cmp_01ABC");
-  });
-});
-
-describe("formatSecretSaved", () => {
-  it("formats the set echo", () => {
-    expect(formatSecretSaved("MY_KEY", "your personal vault")).toBe(
-      "Secret 'MY_KEY' saved to your personal vault.",
-    );
-  });
-});
-
-describe("formatSecretsListHeader", () => {
-  it("formats the list header", () => {
-    expect(formatSecretsListHeader("company acme")).toBe(
-      "Secrets for company acme:",
-    );
-  });
-});
-
-describe("formatSecretsListEmpty", () => {
-  it("formats the empty list message", () => {
-    expect(formatSecretsListEmpty("your personal vault")).toBe(
-      "No secrets found for your personal vault.",
-    );
-  });
-});

package/src/commands/secrets-scope.ts

@@ -1,32 +0,0 @@
-/**
- * Pure helpers describing WHICH secrets scope a command acted on, so `set` and
- * `list` can echo it. Users were setting a secret in one scope (personal vs a
- * company, or company A vs B) and listing another, then seeing "no secrets" with
- * no indication the scopes differed (feedback_70e059da).
- */
-export interface SecretsScopeRef {
-  /** True when --personal was used (caller's personal vault). */
-  personal: boolean;
-  /** The slug the user passed via --company, if any. */
-  companySlug?: string;
-  /** Resolved entity uid: prs_* for personal, cmp_* for a company. */
-  companyUid: string;
-}
-
-/** Human label for a secrets scope: "your personal vault" or "company <slug-or-uid>". */
-export function describeSecretsScope(ref: SecretsScopeRef): string {
-  if (ref.personal) return "your personal vault";
-  return `company ${ref.companySlug ?? ref.companyUid}`;
-}
-
-export function formatSecretSaved(name: string, scope: string): string {
-  return `Secret '${name}' saved to ${scope}.`;
-}
-
-export function formatSecretsListHeader(scope: string): string {
-  return `Secrets for ${scope}:`;
-}
-
-export function formatSecretsListEmpty(scope: string): string {
-  return `No secrets found for ${scope}.`;
-}

package/src/commands/secrets.parse-destination.test.ts

@@ -1,38 +0,0 @@
-/**
- * Pre-landing hardening (secrets-proxy-per-secret-destination): `--destination`
- * must reject an embedded `user:pass@host` userinfo segment EXPLICITLY rather
- * than letting `new URL()` silently drop it and normalize to the bare host.
- * Mirrors hq-pro's authoritative `validateDestinations` server-side check — the
- * server re-validates and remains authoritative, but the CLI must not present a
- * userinfo URL as an accepted destination.
- */
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { parseDestinationUrl } from "./secrets.js";
-
-describe("parseDestinationUrl — userinfo hardening", () => {
-  beforeEach(() => {
-    // parseDestinationUrl logs the rejection reason to stderr; silence it so the
-    // test output stays clean while still exercising the real code path.
-    vi.spyOn(console, "error").mockImplementation(() => {});
-  });
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it.each([
-    "https://user:pass@api.openai.com",
-    "https://user@api.openai.com",
-    "https://:pass@api.openai.com",
-  ])("rejects a destination with embedded userinfo (%s)", (raw) => {
-    expect(parseDestinationUrl(raw).ok).toBe(false);
-  });
-
-  it("still accepts a bare scheme+host HTTPS destination (guards against over-rejection)", () => {
-    const result = parseDestinationUrl("https://api.openai.com");
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.url).toBe("https://api.openai.com");
-      expect(result.hostname).toBe("api.openai.com");
-    }
-  });
-});