@indigoai-us/hq-cli 5.32.0 → 5.33.1

package/src/commands/safe-extract.ts

@@ -0,0 +1,444 @@
+/**
+ * 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/index.ts

@@ -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";
@@ -101,6 +102,11 @@ registerPacksCommand(program);
 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")

package/src/lib/local-tree-diff.test.ts

@@ -21,6 +21,7 @@ import * as crypto from "node:crypto";
 
 import {
   buildNarrowPlan,
+  toPosixKey,
   formatBytes,
   formatNarrowPlanSummary,
 } from "./local-tree-diff.js";
@@ -87,6 +88,24 @@ afterEach(() => {
 
 // ── Happy-path partitioning ─────────────────────────────────────────────────
 
+describe("toPosixKey — POSIX key normalization (Windows client regression)", () => {
+  // Regression: on a non-POSIX (Windows) client, path.relative() yields
+  // "\\"-separated paths. Emitted verbatim as a vault key, `knowledge\books-eoi.md`
+  // has no "/", so the server's listing (which splits on "/") renders it flat at
+  // the root. The narrow-plan must emit POSIX keys regardless of client OS.
+  it("converts a Windows-style nested path to a POSIX key", () => {
+    expect(toPosixKey("knowledge\\books-eoi.md")).toBe("knowledge/books-eoi.md");
+    expect(toPosixKey("data\\sub\\boots-accounts.json")).toBe(
+      "data/sub/boots-accounts.json",
+    );
+  });
+
+  it("leaves an already-POSIX key unchanged (idempotent)", () => {
+    expect(toPosixKey("meetings/2026/notes.md")).toBe("meetings/2026/notes.md");
+    expect(toPosixKey("flat.md")).toBe("flat.md");
+  });
+});
+
 describe("buildNarrowPlan — partition by prefix coverage", () => {
   it("separates files into staying / clean / dirty buckets", () => {
     // Staying — covered by prospective prefix.

package/src/lib/local-tree-diff.ts

@@ -182,6 +182,22 @@ function emptyPlan(): NarrowPlan {
  * 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: string): string {
+  return p.split("\\").join("/");
+}
+
 function walkLocal(
   dir: string,
   // Rel-root for `relPath` — the company walk root (`<hqRoot>/companies/<slug>`),
@@ -202,7 +218,7 @@ function walkLocal(
 
   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

package/src/types.ts

@@ -82,6 +82,18 @@ export type PackContributeKey =
   | '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;                 // ^hq-pack-[a-z0-9][a-z0-9-]*$
   version: string;              // semver
@@ -94,4 +106,15 @@ export interface PackManifest {
   repository?: string;
   keywords?: string[];
   conditional?: string;         // bash predicate; skip install if exits non-zero
+  /**
+   * 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[];
 }

package/src/utils/vault-api.ts

@@ -43,6 +43,47 @@ export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
   return 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 async function vaultApiFetchPublic(opts: {
+  path: string;
+  query?: Record<string, string>;
+}): Promise<Response> {
+  const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
+  if (opts.query) {
+    for (const [k, v] of Object.entries(opts.query)) {
+      url.searchParams.set(k, v);
+    }
+  }
+  const safeUrl = url.search
+    ? `${url.origin}${url.pathname}?<redacted>`
+    : `${url.origin}${url.pathname}`;
+  Sentry.addBreadcrumb({
+    category: 'http',
+    message: `GET ${opts.path}`,
+    level: 'info',
+    data: { url: safeUrl, method: 'GET' },
+  });
+  const response = await fetch(url.toString(), {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!response.ok) {
+    Sentry.addBreadcrumb({
+      category: 'http',
+      message: `GET ${opts.path} → ${response.status}`,
+      level: 'warning',
+      data: { url: safeUrl, status: response.status },
+    });
+  }
+  return response;
+}
+
 interface MembershipEntry {
   companyUid: string;
   role: string;