@indigoai-us/hq-cli 5.33.0 → 5.34.0

package/src/commands/pack-install.ts

@@ -39,6 +39,12 @@ import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
 import * as yaml from 'js-yaml';
+import {
+  createHash,
+  createPublicKey,
+  verify as cryptoVerify,
+  type KeyObject,
+} from 'node:crypto';
 import { execFileSync, spawnSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -47,15 +53,26 @@ import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
 import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
+import { safeExtractTarball } from './safe-extract.js';
+import { vaultApiFetchPublic } from '../utils/vault-api.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Source classification
 // ---------------------------------------------------------------------------
 
-export type Transport = 'npm' | 'git' | 'local';
+export type Transport = 'npm' | 'git' | 'local' | 'marketplace';
+
+/** Prefix that routes a source through the HQ marketplace transport (US-006). */
+export const MARKETPLACE_PREFIX = 'marketplace:';
 
 export function classify(source: string): Transport {
+  // US-006: marketplace:<slug>[@version] is recognized BEFORE the legacy
+  // registry fallback and ahead of every other transport. The slug is resolved
+  // against the public listings API, the presigned tarball is downloaded,
+  // verified (US-021), and safe-extracted (US-020) into the existing local
+  // install + symlink-wiring path.
+  if (source.startsWith(MARKETPLACE_PREFIX)) return 'marketplace';
   if (source.startsWith('@')) return 'npm';
   if (
     source.startsWith('http://') ||
@@ -154,7 +171,25 @@ interface FetchResult {
   resolvedSha?: string;   // git transport only
 }
 
-function fetchNpm(source: string, tmpDir: string): FetchResult {
+/**
+ * Optional marketplace integrity metadata for a tarball-based install (US-021).
+ * When present, `verifyArtifact` runs over the downloaded tarball bytes BEFORE
+ * `safeExtractTarball` — a hash/signature mismatch aborts the install before
+ * any byte is unpacked. US-006 populates this from the listing detail; the npm
+ * fetch path also honors it so a registry-fetched tarball can be verified.
+ */
+export interface ArtifactIntegrity {
+  expectedHash: string;
+  signature?: string;
+  publicKey?: string;
+  requireSignature?: boolean;
+}
+
+function fetchNpm(
+  source: string,
+  tmpDir: string,
+  integrity?: ArtifactIntegrity,
+): FetchResult {
   // Use `npm pack` to grab the tarball without actually installing anything.
   // Capture output to get the produced filename. Arguments are passed as an
   // argv array — never interpolated into a shell string — so `source` cannot
@@ -170,10 +205,28 @@ function fetchNpm(source: string, tmpDir: string): FetchResult {
   }
   const tarballPath = path.join(tmpDir, tarball);
   const extractDir = path.join(tmpDir, 'extracted');
-  fs.mkdirSync(extractDir, { recursive: true });
-  execFileSync('tar', ['-xzf', tarballPath, '-C', extractDir], {
-    stdio: 'inherit',
-  });
+  // SECURITY (US-021): verify integrity + authenticity over the EXACT
+  // downloaded bytes BEFORE we extract. A hash/signature mismatch throws
+  // `ArtifactVerificationError` here, so a tampered artifact is never unpacked
+  // or wired. This MUST precede `safeExtractTarball` (US-020). Only runs when
+  // the caller supplied a pinned hash (i.e. a marketplace listing did); the
+  // plain `npm pack` path with no listing metadata is unaffected.
+  if (integrity) {
+    const tarballBytes = fs.readFileSync(tarballPath);
+    verifyArtifact({
+      tarballBytes,
+      expectedHash: integrity.expectedHash,
+      signature: integrity.signature,
+      publicKey: integrity.publicKey,
+      requireSignature: integrity.requireSignature,
+    });
+  }
+  // SECURITY (US-020): the tarball is untrusted. Extract through the hardened
+  // path — zip-slip / link-escape containment + decompression-bomb caps +
+  // staged-then-atomic commit with full rollback — instead of a blind
+  // `tar -xzf`. safeExtractTarball requires the destination not to pre-exist,
+  // so we do NOT mkdir extractDir first; it is created atomically on success.
+  safeExtractTarball(tarballPath, extractDir);
   // npm tarballs unpack into ./package/
   const payloadDir = path.join(extractDir, 'package');
   if (!fs.existsSync(payloadDir)) {
@@ -194,6 +247,270 @@ function stripVersion(src: string): string {
   return src;
 }
 
+// ---------------------------------------------------------------------------
+// Marketplace transport (US-006)
+//
+// `marketplace:<slug>[@version]` resolves a slug against the PUBLIC listings
+// API (US-005, NONE-auth), downloads the presigned tarball, verifies it
+// (US-021) BEFORE extraction, and feeds it into the existing safe-extract +
+// validate + symlink-wire path. The legacy registry/npm/git/local transports
+// are untouched.
+// ---------------------------------------------------------------------------
+
+/** Parsed `marketplace:<slug>[@version]` source. */
+export function parseMarketplaceSource(source: string): {
+  slug: string;
+  version?: string;
+} {
+  if (!source.startsWith(MARKETPLACE_PREFIX)) {
+    throw new Error(`Not a marketplace source: "${source}"`);
+  }
+  const rest = source.slice(MARKETPLACE_PREFIX.length).trim();
+  if (!rest) {
+    throw new Error('marketplace: source requires a slug (marketplace:<slug>[@version]).');
+  }
+  // Split on the LAST '@' so a slug never legitimately contains one, but be
+  // defensive: only treat the suffix as a version if there's a non-empty slug.
+  const at = rest.lastIndexOf('@');
+  if (at > 0) {
+    return { slug: rest.slice(0, at), version: rest.slice(at + 1) || undefined };
+  }
+  return { slug: rest };
+}
+
+/**
+ * A resolved marketplace listing detail — the public `GET /v1/listings/{id}`
+ * shape (US-005) reduced to the fields the installer needs. The presigned
+ * `downloadUrl` is short-lived; `listingId` lets us re-resolve a fresh one if
+ * it expires mid-download.
+ */
+export interface MarketplaceListing {
+  listingId: string;
+  slug: string;
+  version?: string;
+  /** Short-lived presigned S3 URL for the tarball. */
+  downloadUrl: string;
+  /** Lowercase-hex sha256 the listing pinned + approval is bound to (US-021). */
+  contentHash: string;
+  /** Hash algorithm the server reported (e.g. `sha256`), when present. */
+  contentHashAlg?: string;
+  /** Base64 Ed25519 signature over the contentHash (optional during key-defer). */
+  signature?: string;
+  /** Identifier of the signing key the server used, when present. */
+  signingKeyId?: string;
+  /** Platform public key (PEM/SPKI) to verify the signature against. */
+  publicKey?: string;
+}
+
+/**
+ * Network seams for the marketplace transport, dependency-injected so unit
+ * tests can mock resolve + download without real HTTP/S3. Production wiring
+ * lives in `defaultMarketplaceDeps`.
+ */
+export interface MarketplaceDeps {
+  /**
+   * Resolve `slug[@version]` to a listing detail (id + presigned URL + the
+   * approved hash/signature/publicKey). Throws if no approved listing matches.
+   */
+  resolveListing: (slug: string, version?: string) => Promise<MarketplaceListing>;
+  /** Re-fetch the listing detail by id to mint a FRESH presigned URL. */
+  refreshListing: (listingId: string) => Promise<MarketplaceListing>;
+  /** Download the tarball bytes from a presigned URL. Returns null on 403/expired. */
+  download: (url: string) => Promise<Uint8Array | { expired: true }>;
+}
+
+/** True when a download result signals an expired/forbidden presigned URL. */
+function isExpired(r: Uint8Array | { expired: true }): r is { expired: true } {
+  return !(r instanceof Uint8Array) && (r as { expired?: true }).expired === true;
+}
+
+interface RawListingSummary {
+  listingId?: string;
+  id?: string;
+  slug?: string;
+  version?: string;
+  latestVersion?: string;
+  status?: string;
+}
+
+interface RawListingDetailFields extends RawListingSummary {
+  downloadUrl?: string;
+  url?: string;
+  contentHash?: string;
+  contentHashAlg?: string;
+  sha256?: string;
+  signature?: string;
+  signingKeyId?: string;
+  publicKey?: string;
+}
+
+/**
+ * `GET /v1/listings/{id}` returns the listing WRAPPED in an envelope
+ * (`{ listing: { id, downloadUrl, contentHash, ... } }`). Older/back-compat
+ * responses returned the listing fields at the top level, so we accept both.
+ */
+interface RawListingDetail extends RawListingDetailFields {
+  listing?: RawListingDetailFields;
+}
+
+/** Map a raw `GET /v1/listings/{id}` body into a MarketplaceListing. */
+export function toMarketplaceListing(raw: RawListingDetail): MarketplaceListing {
+  // Unwrap the `{ listing: {...} }` envelope when present; fall back to the
+  // top level for the legacy flat shape (backwards-compat).
+  const detail: RawListingDetailFields =
+    raw.listing && typeof raw.listing === 'object' ? raw.listing : raw;
+  // The detail uses `id`; the legacy flat shape may use `listingId`.
+  const listingId = detail.id ?? detail.listingId;
+  const downloadUrl = detail.downloadUrl ?? detail.url;
+  const contentHash = detail.contentHash ?? detail.sha256;
+  if (!listingId) throw new Error('Listing detail missing an id.');
+  if (!downloadUrl) {
+    throw new Error(`Listing ${listingId} has no download URL — it may not be approved yet.`);
+  }
+  if (!contentHash) {
+    throw new Error(
+      `Listing ${listingId} has no content hash — refusing to install an unverifiable artifact.`,
+    );
+  }
+  return {
+    listingId,
+    slug: detail.slug ?? '',
+    version: detail.version ?? detail.latestVersion,
+    downloadUrl,
+    contentHash,
+    contentHashAlg: detail.contentHashAlg,
+    signature: detail.signature,
+    signingKeyId: detail.signingKeyId,
+    publicKey: detail.publicKey,
+  };
+}
+
+/** Default production marketplace deps — public listings API + presigned S3. */
+export function defaultMarketplaceDeps(): MarketplaceDeps {
+  const fetchDetail = async (listingId: string): Promise<MarketplaceListing> => {
+    const res = await vaultApiFetchPublic({
+      path: `/v1/listings/${encodeURIComponent(listingId)}`,
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Failed to resolve listing ${listingId} (HTTP ${res.status}). The pack may be unavailable or unapproved.`,
+      );
+    }
+    const body = (await res.json().catch(() => ({}))) as RawListingDetail;
+    return toMarketplaceListing(body);
+  };
+  return {
+    resolveListing: async (slug, version) => {
+      // Search by slug (public). The API returns approved listings only.
+      const res = await vaultApiFetchPublic({
+        path: '/v1/listings',
+        query: version ? { slug, version } : { slug },
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Failed to search marketplace for "${slug}" (HTTP ${res.status}).`,
+        );
+      }
+      const body = (await res.json().catch(() => ({}))) as {
+        listings?: RawListingSummary[];
+      };
+      const listings = body.listings ?? [];
+      const match = version
+        ? listings.find((l) => (l.version ?? l.latestVersion) === version)
+        : listings[0];
+      if (!match) {
+        throw new Error(
+          `No approved marketplace listing found for "${slug}"${version ? `@${version}` : ''}.`,
+        );
+      }
+      const id = match.listingId ?? match.id;
+      if (!id) throw new Error(`Listing for "${slug}" has no id.`);
+      // The summary may omit the presigned URL; always fetch detail to mint it.
+      return fetchDetail(id);
+    },
+    refreshListing: fetchDetail,
+    download: async (url) => {
+      const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+      if (response.status === 403) return { expired: true };
+      if (!response.ok) {
+        throw new Error(`Tarball download failed (HTTP ${response.status}).`);
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  };
+}
+
+/**
+ * Fetch + verify + safe-extract a marketplace pack. Mirrors `fetchNpm`'s
+ * contract (returns a payloadDir the caller mvs into core/packages/), but
+ * resolves the tarball from the marketplace and ALWAYS verifies it against the
+ * listing's approved hash/signature BEFORE extraction (US-021 → US-020).
+ *
+ * @param requireSignature production posture once signing keys exist; during
+ *        the key-deferral window callers pass false (hash still always checked).
+ */
+export async function fetchMarketplace(
+  source: string,
+  tmpDir: string,
+  deps: MarketplaceDeps,
+  opts: { requireSignature?: boolean } = {},
+): Promise<FetchResult> {
+  const { slug, version } = parseMarketplaceSource(source);
+  let listing = await deps.resolveListing(slug, version);
+
+  // Download with a single expired-URL retry: a presigned URL can expire
+  // between resolve and download, surfacing as a raw S3 403. We re-resolve the
+  // detail by id to mint a fresh URL and retry ONCE rather than leaking the 403.
+  let bytes = await deps.download(listing.downloadUrl);
+  if (isExpired(bytes)) {
+    listing = await deps.refreshListing(listing.listingId);
+    bytes = await deps.download(listing.downloadUrl);
+    if (isExpired(bytes)) {
+      throw new Error(
+        `Marketplace download URL for "${slug}" expired and re-resolving did not help. ` +
+          `Try again in a moment.`,
+      );
+    }
+  }
+  const tarballBytes = bytes as Uint8Array;
+
+  // SECURITY (US-021): verify integrity (+ authenticity) over the EXACT
+  // downloaded bytes BEFORE extraction. A hash/signature mismatch throws
+  // `ArtifactVerificationError` and nothing is unpacked or wired. The hash is
+  // ALWAYS verified when present; signature is enforced when requireSignature.
+  verifyArtifact({
+    tarballBytes,
+    expectedHash: listing.contentHash,
+    signature: listing.signature,
+    publicKey: listing.publicKey,
+    requireSignature: opts.requireSignature ?? false,
+  });
+
+  // Write to a tmp tarball and run it through the SAME hardened extractor
+  // (US-020) as every other tarball transport.
+  const tarballPath = path.join(tmpDir, 'marketplace.tar.gz');
+  fs.writeFileSync(tarballPath, tarballBytes);
+  const extractDir = path.join(tmpDir, 'extracted');
+  safeExtractTarball(tarballPath, extractDir);
+
+  // Marketplace tarballs are packed with `tar -C payloadDir .` (publish.ts), so
+  // the manifest + contributes dirs are at the archive root — no `package/`
+  // wrapper to descend into.
+  const payloadDir = extractDir;
+  if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
+    throw new Error(
+      `Marketplace tarball for "${slug}" has no package.yaml at its root.`,
+    );
+  }
+
+  // Record the marketplace source for re-install + `hq packs update`. We stamp
+  // the resolved version so a later `update` can detect a newer listing.
+  const resolvedSource = listing.version
+    ? `${MARKETPLACE_PREFIX}${slug}@${listing.version}`
+    : `${MARKETPLACE_PREFIX}${slug}`;
+  return { payloadDir, resolvedSource };
+}
+
 function fetchGit(
   source: string,
   tmpDir: string,
@@ -384,6 +701,21 @@ export function resolveLatest(
     return { transport, updateAvailable: null, error: 'local source — re-run to re-sync' };
   }
 
+  if (transport === 'marketplace') {
+    // The marketplace probe needs an async network call (listings API), which
+    // this synchronous helper cannot make. Callers that want the marketplace
+    // update check use the async `resolveLatestMarketplace`; here we report the
+    // installed version but leave availability undeterminable (null) so the
+    // sync menubar `--check-updates` path is not regressed.
+    const { version } = parseMarketplaceSource(source);
+    return {
+      transport,
+      current: installedVersion ?? version,
+      updateAvailable: null,
+      error: 'marketplace source — use async update check',
+    };
+  }
+
   if (transport === 'npm') {
     const pkg = stripVersion(source);
     const current =
@@ -427,11 +759,206 @@ export function resolveLatest(
   }
 }
 
+/**
+ * Async marketplace update probe (US-006): resolve the slug's latest approved
+ * listing version and compare it to the installed version. Reuses the same
+ * `MarketplaceDeps.resolveListing` seam as the install path (resolving with NO
+ * version pin returns the latest listing). Never throws — network/parse
+ * failures return `{ updateAvailable: null, error }` so `hq packs update`
+ * stays resilient.
+ *
+ * @param source           the stamped `marketplace:<slug>[@version]` source
+ * @param installedVersion the installed pack's manifest version (semver compare)
+ * @param deps             injected for tests; defaults to the public API
+ */
+export async function resolveLatestMarketplace(
+  source: string,
+  installedVersion?: string,
+  deps?: MarketplaceDeps,
+): Promise<LatestResult> {
+  let slug: string;
+  let pinned: string | undefined;
+  try {
+    ({ slug, version: pinned } = parseMarketplaceSource(source));
+  } catch (e) {
+    return { transport: 'marketplace', updateAvailable: null, error: (e as Error).message };
+  }
+  const current = installedVersion ?? pinned;
+  try {
+    const d = deps ?? defaultMarketplaceDeps();
+    // No version pin → latest approved listing.
+    const listing = await d.resolveListing(slug);
+    const latest = listing.version;
+    let updateAvailable: boolean | null = null;
+    if (current && latest) {
+      // Prefer semver compare; fall back to inequality if either side isn't
+      // valid semver (so a non-semver listing version still flags a change).
+      updateAvailable =
+        semverValid(latest) && semverValid(current)
+          ? semverGt(latest, current)
+          : latest !== current;
+    }
+    return { transport: 'marketplace', current, latest, updateAvailable };
+  } catch (e) {
+    return {
+      transport: 'marketplace',
+      current,
+      updateAvailable: null,
+      error: `marketplace check failed: ${(e as Error).message}`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Marketplace artifact verification (US-021, INSTALL side)
+//
+// Guarantees the bytes we install are EXACTLY the bytes a moderator approved:
+//   1. recompute sha256 over the downloaded tarball bytes and compare it to the
+//      hash the listing pinned at publish (and approval bound to);
+//   2. verify the platform Ed25519 signature over that hash against a
+//      distributable PUBLIC key.
+//
+// SHARED CONTRACT (must match hq-pro `src/listings/signing.ts`):
+//   • CANONICAL BYTES = the gzipped tarball object EXACTLY as uploaded to S3
+//                       (i.e. exactly the bytes we downloaded — no transform).
+//   • contentHash     = sha256(canonical bytes), lowercase hex.
+//   • signature       = Ed25519 over the UTF-8 bytes of the lowercase-hex
+//                       contentHash, base64-encoded.
+//
+// This runs BEFORE safe-extract (US-020): a mismatch must abort the install
+// before any bytes are unpacked or wired. US-006 wires the marketplace
+// transport that surfaces the listing's {hash, signature, publicKey}; this
+// function is the reusable verifier it calls.
+// ---------------------------------------------------------------------------
+
+/** Thrown when a downloaded artifact fails hash or signature verification. */
+export class ArtifactVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ArtifactVerificationError';
+  }
+}
+
+/** Hash algorithm for the content hash — pinned to sha256 (matches publish). */
+export const ARTIFACT_HASH_ALG = 'sha256' as const;
+
+export interface VerifyArtifactInput {
+  /** The downloaded gzipped tarball bytes (canonical bytes). */
+  tarballBytes: Uint8Array;
+  /** Lowercase-hex sha256 the listing pinned at publish (approval bound to it). */
+  expectedHash: string;
+  /**
+   * Base64 Ed25519 signature over the lowercase-hex `expectedHash`. Optional:
+   * when the listing carries no signature (e.g. published before signing-key
+   * provisioning), hash verification still runs but signature verification is
+   * skipped UNLESS `requireSignature` is set.
+   */
+  signature?: string;
+  /**
+   * The platform PUBLIC key (Ed25519) as a PEM/SPKI string or a pre-parsed
+   * KeyObject. Required to verify a signature. The public key is distributable
+   * (embedded in / fetched by the installer).
+   */
+  publicKey?: string | KeyObject;
+  /**
+   * When true, a missing signature OR missing public key is a hard failure
+   * (production posture once signing keys are provisioned). Default false so an
+   * unsigned listing still hash-verifies during the deferred-key window.
+   */
+  requireSignature?: boolean;
+}
+
+/** Lowercase-hex sha256 of the given bytes — the install-side content hash. */
+export function computeArtifactHash(tarballBytes: Uint8Array): string {
+  return createHash(ARTIFACT_HASH_ALG).update(tarballBytes).digest('hex');
+}
+
+/**
+ * Verify a downloaded marketplace artifact's integrity (hash) and authenticity
+ * (signature). Throws `ArtifactVerificationError` on ANY mismatch — the caller
+ * MUST let it propagate so the install aborts before extraction.
+ *
+ * Constant-time-ish hash comparison: hashes are fixed-length lowercase hex, and
+ * the early-exit risk is negligible (the hash is public), but we still compare
+ * full strings rather than prefixes.
+ */
+export function verifyArtifact(input: VerifyArtifactInput): void {
+  const {
+    tarballBytes,
+    expectedHash,
+    signature,
+    publicKey,
+    requireSignature = false,
+  } = input;
+
+  if (!expectedHash || !/^[0-9a-f]{64}$/.test(expectedHash)) {
+    throw new ArtifactVerificationError(
+      `Refusing to install: listing did not provide a valid ${ARTIFACT_HASH_ALG} content hash.`,
+    );
+  }
+
+  // 1. Integrity — recompute the hash over the EXACT downloaded bytes.
+  const actualHash = computeArtifactHash(tarballBytes);
+  if (actualHash !== expectedHash) {
+    throw new ArtifactVerificationError(
+      `Artifact hash mismatch — refusing to install. ` +
+        `expected ${ARTIFACT_HASH_ALG}=${expectedHash}, got ${actualHash}. ` +
+        `The downloaded bytes are NOT the bytes that were approved.`,
+    );
+  }
+
+  // 2. Authenticity — verify the Ed25519 signature over the hash.
+  if (!signature || !publicKey) {
+    if (requireSignature) {
+      throw new ArtifactVerificationError(
+        signature
+          ? 'Artifact signature present but no public key available to verify it — refusing to install.'
+          : 'Artifact is unsigned and a signature is required — refusing to install.',
+      );
+    }
+    // Deferred-key window: hash verified, no signature to check. Caller opted to
+    // allow unsigned (requireSignature=false).
+    return;
+  }
+
+  let key: KeyObject;
+  try {
+    key = typeof publicKey === 'string' ? createPublicKey(publicKey) : publicKey;
+  } catch (e) {
+    throw new ArtifactVerificationError(
+      `Invalid artifact public key — refusing to install: ${(e as Error).message}`,
+    );
+  }
+
+  let ok = false;
+  try {
+    // Ed25519: digest algorithm is null (the scheme hashes internally). The
+    // signed payload is the UTF-8 bytes of the lowercase-hex hash — identical to
+    // what hq-pro signed at publish.
+    ok = cryptoVerify(
+      null,
+      Buffer.from(expectedHash, 'utf-8'),
+      key,
+      Buffer.from(signature, 'base64'),
+    );
+  } catch (e) {
+    throw new ArtifactVerificationError(
+      `Artifact signature verification errored — refusing to install: ${(e as Error).message}`,
+    );
+  }
+  if (!ok) {
+    throw new ArtifactVerificationError(
+      'Artifact signature is invalid — refusing to install. ' +
+        'The artifact was not signed by the platform key (possible tampering).',
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
 
-function validateManifest(
+export function validateManifest(
   payloadDir: string,
   hqVersion: string | null
 ): PackManifest {
@@ -506,6 +1033,28 @@ function validateManifest(
       }
     }
   }
+  // author + capabilities (US-001) — both OPTIONAL and backwards-compatible.
+  // Absent → fine (legacy packs). Present → must be well-shaped so a malformed
+  // attribution can't masquerade as a valid one.
+  if (m.author !== undefined) {
+    const a = m.author as unknown as Record<string, unknown>;
+    if (!a || typeof a !== 'object' || Array.isArray(a)) {
+      throw new Error('author must be a mapping with uid, handle, displayName');
+    }
+    for (const field of ['uid', 'handle', 'displayName'] as const) {
+      if (typeof a[field] !== 'string' || (a[field] as string).trim() === '') {
+        throw new Error(`author.${field} must be a non-empty string`);
+      }
+    }
+  }
+  if (m.capabilities !== undefined) {
+    if (
+      !Array.isArray(m.capabilities) ||
+      !m.capabilities.every((c) => typeof c === 'string')
+    ) {
+      throw new Error('capabilities must be a list of strings');
+    }
+  }
   return m as PackManifest;
 }
 
@@ -629,13 +1178,32 @@ export function installToPackages(
   const packagesDir = path.join(hqRoot, 'core', 'packages');
   fs.mkdirSync(packagesDir, { recursive: true });
   const destDir = path.join(packagesDir, pkg.name);
-  if (fs.existsSync(destDir)) {
-    fs.rmSync(destDir, { recursive: true, force: true });
+
+  // SECURITY/ATOMICITY (US-020): wire atomically. rsync into a sibling staging
+  // dir on the SAME filesystem first; only swap it into the final destination
+  // once the copy fully succeeds. A failed/partial rsync therefore never
+  // leaves a half-wired pack dir in place (which scan-packages.sh would then
+  // wire into host paths). On any error the staging dir is rolled back.
+  const stagingDir = fs.mkdtempSync(path.join(packagesDir, `.${pkg.name}.staging-`));
+  try {
+    // rsync preserves modes/symlinks; argv form — no shell.
+    const srcSlashed = payloadDir.endsWith('/') ? payloadDir : `${payloadDir}/`;
+    const stagingSlashed = stagingDir.endsWith('/') ? stagingDir : `${stagingDir}/`;
+    execFileSync('rsync', ['-a', srcSlashed, stagingSlashed], { stdio: 'inherit' });
+
+    // Swap into place: remove any prior install, then atomic rename. The brief
+    // window between rm and rename is unavoidable with a same-name dir, but the
+    // staged copy guarantees the NEW contents are fully present before we touch
+    // the live location.
+    if (fs.existsSync(destDir)) {
+      fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    fs.renameSync(stagingDir, destDir);
+  } finally {
+    if (fs.existsSync(stagingDir)) {
+      fs.rmSync(stagingDir, { recursive: true, force: true });
+    }
   }
-  // rsync preserves modes/symlinks; tar also works. argv form — no shell.
-  const srcSlashed = payloadDir.endsWith('/') ? payloadDir : `${payloadDir}/`;
-  const destSlashed = destDir.endsWith('/') ? destDir : `${destDir}/`;
-  execFileSync('rsync', ['-a', srcSlashed, destSlashed], { stdio: 'inherit' });
   return destDir;
 }
 
@@ -745,6 +1313,25 @@ export interface InstallPackOptions {
    * `rsync -a`, `git clone` progress -> stderr), so this is sufficient.
    */
   quiet?: boolean;
+  /**
+   * US-021 marketplace artifact integrity. When provided (a marketplace listing
+   * carries a pinned content hash + signature + public key), the downloaded
+   * tarball is verified BEFORE extraction; a mismatch aborts the install. US-006
+   * populates this from the listing detail response.
+   */
+  integrity?: ArtifactIntegrity;
+  /**
+   * US-006 marketplace transport seams (resolve/refresh/download), injected for
+   * tests. When omitted, `defaultMarketplaceDeps()` (public listings API +
+   * presigned S3) is used. Only consulted when `source` is `marketplace:...`.
+   */
+  marketplaceDeps?: MarketplaceDeps;
+  /**
+   * US-006: require a valid signature for marketplace artifacts. Default false
+   * during the signing-key-deferral window (the content hash is still ALWAYS
+   * verified); set true once platform signing keys are provisioned.
+   */
+  requireSignature?: boolean;
 }
 
 export async function installPack(
@@ -764,7 +1351,7 @@ export async function installPack(
     let fetched: FetchResult;
     switch (transport) {
       case 'npm':
-        fetched = fetchNpm(source, tmpDir);
+        fetched = fetchNpm(source, tmpDir, opts.integrity);
         break;
       case 'git':
         fetched = fetchGit(source, tmpDir, opts.followBranch ?? false);
@@ -772,6 +1359,14 @@ export async function installPack(
       case 'local':
         fetched = fetchLocal(source, tmpDir);
         break;
+      case 'marketplace':
+        fetched = await fetchMarketplace(
+          source,
+          tmpDir,
+          opts.marketplaceDeps ?? defaultMarketplaceDeps(),
+          { requireSignature: opts.requireSignature },
+        );
+        break;
     }
 
     const pkg = validateManifest(fetched.payloadDir, hqVersion);
@@ -812,7 +1407,14 @@ export async function installPack(
     // setup.sh can dedup against `core/core.yaml:recommended_packages` on
     // re-runs. Stamping the literal input (not the resolved SHA/version)
     // matches the verbatim equality check in setup.sh.
-    stampInstallSource(destDir, source);
+    //
+    // US-006 EXCEPTION: for the marketplace transport we stamp the RESOLVED
+    // source (`marketplace:<slug>@<version>`) rather than the literal input.
+    // The version is what lets `hq packs update` detect a newer listing — the
+    // bare `marketplace:<slug>` input carries no version to compare against.
+    const stampedSource =
+      transport === 'marketplace' ? fetched.resolvedSource : source;
+    stampInstallSource(destDir, stampedSource);
     runScanPackages(hqRoot, { quiet: opts.quiet });
 
     say(