@indigoai-us/hq-cli 5.33.0 → 5.33.1

package/dist/commands/__fixtures__/make-tar.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Deterministic, platform-independent malicious-tar fixture builder.
+ *
+ * WHY THIS EXISTS (cross-platform zip-slip coverage). The adversarial
+ * safe-extract / marketplace-security suites need archives that GENUINELY carry
+ * hostile entries — a `../` traversal name, an absolute path, an escaping
+ * symlink/hardlink. The obvious approach (shell out to the system `tar` to
+ * CREATE the archive) is NOT portable: GNU tar (Linux / CI / prod Lambdas)
+ * STRIPS the leading `../` and absolute `/` when it WRITES an archive, so the
+ * resulting "malicious" fixture contains a benign `evil-escape` entry and the
+ * guard has nothing to reject — the test passes on macOS bsdtar (which
+ * preserves them) but fails on Linux. The guard itself is correct; only the
+ * fixture construction was platform-dependent.
+ *
+ * Fix: WRITE THE TAR BYTES DIRECTLY here. A tar archive is just a sequence of
+ * 512-byte ustar headers, each optionally followed by the file's content padded
+ * to a 512-byte boundary, terminated by two zero blocks. By emitting the bytes
+ * ourselves we control the recorded entry names verbatim — `../evil-escape`,
+ * `/tmp/evil`, a symlink with linkname `../../etc/passwd` — identically on every
+ * platform, with no create-time stripping. The reading side (`tar -tvf`, which
+ * safeExtractTarball's pre-flight uses) does NOT strip anything; it faithfully
+ * lists whatever bytes we wrote, so the guard sees the real attack everywhere.
+ */
+/** ustar typeflag values we use. */
+export type TarType = 'file' | 'symlink' | 'hardlink';
+export interface TarEntrySpec {
+    /** Recorded entry name — written VERBATIM (may contain `..`, be absolute…). */
+    name: string;
+    type?: TarType;
+    /** For sym/hardlinks: the recorded link target (also written verbatim). */
+    linkname?: string;
+    /** File content (regular files only). */
+    content?: string | Buffer;
+}
+/**
+ * Build one 512-byte ustar header (plus content blocks for regular files) for a
+ * single entry. The header checksum is computed exactly per spec: sum every
+ * header byte treating the 8 checksum bytes themselves as ASCII spaces, then
+ * write that sum as 6 octal digits + NUL + space.
+ */
+export declare function makeTarEntry(spec: TarEntrySpec): Buffer;
+/** Concatenate entries and append the two zero blocks that end every tar. */
+export declare function makeTar(entries: TarEntrySpec[]): Buffer;
+/** Build the tar, gzip it, and write it to `outPath`. Returns `outPath`. */
+export declare function writeMaliciousTarGz(outPath: string, entries: TarEntrySpec[]): string;
+//# sourceMappingURL=make-tar.d.ts.map

package/dist/commands/__fixtures__/make-tar.js

@@ -0,0 +1,105 @@
+/**
+ * Deterministic, platform-independent malicious-tar fixture builder.
+ *
+ * WHY THIS EXISTS (cross-platform zip-slip coverage). The adversarial
+ * safe-extract / marketplace-security suites need archives that GENUINELY carry
+ * hostile entries — a `../` traversal name, an absolute path, an escaping
+ * symlink/hardlink. The obvious approach (shell out to the system `tar` to
+ * CREATE the archive) is NOT portable: GNU tar (Linux / CI / prod Lambdas)
+ * STRIPS the leading `../` and absolute `/` when it WRITES an archive, so the
+ * resulting "malicious" fixture contains a benign `evil-escape` entry and the
+ * guard has nothing to reject — the test passes on macOS bsdtar (which
+ * preserves them) but fails on Linux. The guard itself is correct; only the
+ * fixture construction was platform-dependent.
+ *
+ * Fix: WRITE THE TAR BYTES DIRECTLY here. A tar archive is just a sequence of
+ * 512-byte ustar headers, each optionally followed by the file's content padded
+ * to a 512-byte boundary, terminated by two zero blocks. By emitting the bytes
+ * ourselves we control the recorded entry names verbatim — `../evil-escape`,
+ * `/tmp/evil`, a symlink with linkname `../../etc/passwd` — identically on every
+ * platform, with no create-time stripping. The reading side (`tar -tvf`, which
+ * safeExtractTarball's pre-flight uses) does NOT strip anything; it faithfully
+ * lists whatever bytes we wrote, so the guard sees the real attack everywhere.
+ */
+
+!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]="3b6b9745-1cda-547f-a99d-34b70ea052c8")}catch(e){}}();
+import { gzipSync } from 'node:zlib';
+import * as fs from 'node:fs';
+const BLOCK = 512;
+const TYPEFLAG = {
+    file: '0', // regular file
+    symlink: '2', // symbolic link
+    hardlink: '1', // hard link
+};
+/** Write an ASCII string into a fixed-width field at `offset`, NUL-padded. */
+function writeField(buf, offset, width, value) {
+    // Truncate defensively; ustar fields are fixed-width.
+    const s = value.slice(0, width);
+    buf.write(s, offset, 'ascii');
+    // Remaining bytes are already 0 from Buffer.alloc.
+}
+/** Write an octal numeric field: `width-1` octal digits, space-or-NUL terminated. */
+function writeOctal(buf, offset, width, value) {
+    // Classic ustar numeric field: zero-padded octal in (width-1) chars + NUL.
+    const digits = width - 1;
+    const oct = value.toString(8).padStart(digits, '0').slice(-digits);
+    buf.write(oct, offset, 'ascii');
+    buf[offset + digits] = 0; // NUL terminator
+}
+/**
+ * Build one 512-byte ustar header (plus content blocks for regular files) for a
+ * single entry. The header checksum is computed exactly per spec: sum every
+ * header byte treating the 8 checksum bytes themselves as ASCII spaces, then
+ * write that sum as 6 octal digits + NUL + space.
+ */
+export function makeTarEntry(spec) {
+    const type = spec.type ?? 'file';
+    const content = type === 'file'
+        ? Buffer.isBuffer(spec.content)
+            ? spec.content
+            : Buffer.from(spec.content ?? '', 'utf-8')
+        : Buffer.alloc(0); // links carry no content payload
+    const header = Buffer.alloc(BLOCK); // zero-filled
+    writeField(header, 0, 100, spec.name); // name
+    writeOctal(header, 100, 8, 0o644); // mode
+    writeOctal(header, 108, 8, 0); // uid
+    writeOctal(header, 116, 8, 0); // gid
+    writeOctal(header, 124, 12, content.length); // size (0 for links)
+    writeOctal(header, 136, 12, 0); // mtime (deterministic: epoch)
+    // checksum field (148, 8) — filled below; start as spaces for the sum.
+    header.fill(' '.charCodeAt(0), 148, 156);
+    writeField(header, 156, 1, TYPEFLAG[type]); // typeflag
+    if (spec.linkname !== undefined) {
+        writeField(header, 157, 100, spec.linkname); // linkname (verbatim)
+    }
+    writeField(header, 257, 6, 'ustar'); // magic "ustar\0"
+    writeField(header, 263, 2, '00'); // version "00"
+    // uname/gname left empty; devmajor/devminor zero (already NUL).
+    // Header checksum: unsigned sum of all 512 bytes (with the checksum field as
+    // spaces, which we set above). Written as 6 octal digits, NUL, space.
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++)
+        sum += header[i];
+    const cksum = sum.toString(8).padStart(6, '0').slice(-6);
+    header.write(cksum, 148, 'ascii');
+    header[154] = 0; // NUL
+    header[155] = ' '.charCodeAt(0); // space
+    if (type !== 'file' || content.length === 0)
+        return header;
+    // Content padded up to a 512-byte boundary.
+    const pad = (BLOCK - (content.length % BLOCK)) % BLOCK;
+    return Buffer.concat([header, content, Buffer.alloc(pad)]);
+}
+/** Concatenate entries and append the two zero blocks that end every tar. */
+export function makeTar(entries) {
+    const blocks = entries.map(makeTarEntry);
+    blocks.push(Buffer.alloc(BLOCK * 2)); // end-of-archive marker
+    return Buffer.concat(blocks);
+}
+/** Build the tar, gzip it, and write it to `outPath`. Returns `outPath`. */
+export function writeMaliciousTarGz(outPath, entries) {
+    fs.writeFileSync(outPath, gzipSync(makeTar(entries)));
+    return outPath;
+}
+//# sourceMappingURL=make-tar.js.map
+//# debugId=3b6b9745-1cda-547f-a99d-34b70ea052c8

package/dist/commands/pack-install.d.ts

@@ -33,8 +33,11 @@
  * registry file under the v12 layout. (`hq update <pack>` re-resolves source
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
+import { type KeyObject } from 'node:crypto';
 import type { PackManifest } from '../types.js';
-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 declare const MARKETPLACE_PREFIX = "marketplace:";
 export declare function classify(source: string): Transport;
 /**
  * Parse a git source's '#<...>' fragment into { url, subpath, ref }.
@@ -52,6 +55,112 @@ export declare function parseGitFragment(source: string): {
  * back to the legacy registry flow.
  */
 export declare function sourceMatchesPackPattern(source: string): boolean;
+interface FetchResult {
+    payloadDir: string;
+    resolvedSource: string;
+    resolvedSha?: string;
+}
+/**
+ * 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;
+}
+/** Parsed `marketplace:<slug>[@version]` source. */
+export declare function parseMarketplaceSource(source: string): {
+    slug: string;
+    version?: string;
+};
+/**
+ * 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;
+    }>;
+}
+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 declare function toMarketplaceListing(raw: RawListingDetail): MarketplaceListing;
+/** Default production marketplace deps — public listings API + presigned S3. */
+export declare function defaultMarketplaceDeps(): MarketplaceDeps;
+/**
+ * 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 declare function fetchMarketplace(source: string, tmpDir: string, deps: MarketplaceDeps, opts?: {
+    requireSignature?: boolean;
+}): Promise<FetchResult>;
 export interface LatestResult {
     transport: Transport;
     /** Identifier of the currently-installed pack (sha for git, version for npm). */
@@ -72,6 +181,63 @@ export interface LatestResult {
  * @param installedVersion the installed pack's manifest `version` (npm compare)
  */
 export declare function resolveLatest(source: string, installedVersion?: string): LatestResult;
+/**
+ * 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 declare function resolveLatestMarketplace(source: string, installedVersion?: string, deps?: MarketplaceDeps): Promise<LatestResult>;
+/** Thrown when a downloaded artifact fails hash or signature verification. */
+export declare class ArtifactVerificationError extends Error {
+    constructor(message: string);
+}
+/** Hash algorithm for the content hash — pinned to sha256 (matches publish). */
+export declare const ARTIFACT_HASH_ALG: "sha256";
+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 declare function computeArtifactHash(tarballBytes: Uint8Array): string;
+/**
+ * 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 declare function verifyArtifact(input: VerifyArtifactInput): void;
+export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
 /**
  * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
  * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
@@ -136,6 +302,26 @@ 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 declare function installPack(source: string, opts?: InstallPackOptions): Promise<void>;
+export {};
 //# sourceMappingURL=pack-install.d.ts.map