@indigoai-us/hq-cli 5.33.0 → 5.34.0

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89e1a66a-6a45-56a3-847c-2f0beba1429b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="004dc716-c660-5745-94db-988ac49d102e")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -24,6 +24,7 @@ import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
 import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
 import { registerPackageListCommand } from "./commands/pkg-list.js";
 import { registerPacksCommand } from "./commands/packs.js";
+import { registerPublishCommand } from "./commands/publish.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
@@ -38,6 +39,8 @@ import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
 import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
+import { registerMasterSyncCommand } from "./commands/master-sync.js";
+import { registerRescueCommand } from "./commands/rescue.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
@@ -84,6 +87,10 @@ registerPacksCommand(program);
 // "hq remove <slug>"  = "hq packages remove <slug>"
 registerPackageInstallCommand(program);
 registerPackageRemoveCommand(program);
+// Marketplace publish (top-level — packer + authenticated upload, US-004)
+// "hq publish <skill-or-worker-path>" packages and submits a pack to the
+// marketplace via POST /v1/listings.
+registerPublishCommand(program);
 // Cloud sync subcommand group
 const syncCmd = program
     .command("sync")
@@ -132,6 +139,14 @@ registerMeetingsCommand(program);
 registerSourcesCommand(program);
 // Signals read surface (subcommand group — hq signals list|get|types|entities)
 registerSignalsCommand(program);
+// Skill/personal-overlay mirroring + workers-registry regen. Internal command
+// invoked by the hq-core master-sync hook shim (formerly the master-sync.sh
+// hook body). Implementation lives in @indigoai-us/hq-cloud.
+registerMasterSyncCommand(program);
+// Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
+// the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
+// shipped from @indigoai-us/hq-cloud.
+registerRescueCommand(program);
 (async () => {
     try {
         Sentry.addBreadcrumb({
@@ -158,4 +173,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=89e1a66a-6a45-56a3-847c-2f0beba1429b
+//# debugId=004dc716-c660-5745-94db-988ac49d102e

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

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

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

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

package/dist/types.d.ts

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

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

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

package/dist/utils/vault-api.js

@@ -1,5 +1,5 @@
 
-!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]="e1ca2b83-1de0-5000-ab66-f573000a579b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bdd04f0a-8d43-5072-916d-a801a2f25731")}catch(e){}}();
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
 export async function vaultApiFetch(opts) {
@@ -35,6 +35,43 @@ export async function vaultApiFetch(opts) {
     }
     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) {
+    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;
+}
 async function resolveCompanyUid(token, slug) {
     const res = await vaultApiFetch({
         token,
@@ -106,4 +143,4 @@ export async function getEntityUid(token, opts) {
     return getCompanyUid(token, opts.companySlug);
 }
 //# sourceMappingURL=vault-api.js.map
-//# debugId=e1ca2b83-1de0-5000-ab66-f573000a579b
+//# debugId=bdd04f0a-8d43-5072-916d-a801a2f25731

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.33.0",
+  "version": "5.34.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "~5.47.0",
+    "@indigoai-us/hq-cloud": "~5.48.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/__fixtures__/make-tar.ts

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+
+import { gzipSync } from 'node:zlib';
+import * as fs from 'node:fs';
+
+const BLOCK = 512;
+
+/** ustar typeflag values we use. */
+export type TarType = 'file' | 'symlink' | 'hardlink';
+
+const TYPEFLAG: Record<TarType, string> = {
+  file: '0', // regular file
+  symlink: '2', // symbolic link
+  hardlink: '1', // hard link
+};
+
+export interface TarEntrySpec {
+  /** Recorded entry name — written VERBATIM (may contain `..`, be absolute…). */
+  name: string;
+  type?: TarType; // default 'file'
+  /** For sym/hardlinks: the recorded link target (also written verbatim). */
+  linkname?: string;
+  /** File content (regular files only). */
+  content?: string | Buffer;
+}
+
+/** Write an ASCII string into a fixed-width field at `offset`, NUL-padded. */
+function writeField(buf: Buffer, offset: number, width: number, value: string): void {
+  // 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: Buffer, offset: number, width: number, value: number): void {
+  // 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: TarEntrySpec): Buffer {
+  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: TarEntrySpec[]): Buffer {
+  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: string, entries: TarEntrySpec[]): string {
+  fs.writeFileSync(outPath, gzipSync(makeTar(entries)));
+  return outPath;
+}

package/src/commands/artifact-verify.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Marketplace artifact verification (US-021, INSTALL side) tests.
+ *
+ * Proves the install-time guarantee: the bytes we install are EXACTLY the bytes
+ * a moderator approved. Covers the two E2E behaviors required by the story:
+ *   - an approved artifact whose S3 object is mutated → hash mismatch → REFUSE.
+ *   - signature verification against the platform Ed25519 PUBLIC key.
+ *
+ * SHARED CONTRACT mirror — we reproduce the publish-side signing here with an
+ * ephemeral in-test keypair (no key material in the repo) to prove both sides
+ * agree byte-for-byte.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateKeyPairSync,
+  createHash,
+  sign as cryptoSign,
+} from 'node:crypto';
+import {
+  verifyArtifact,
+  computeArtifactHash,
+  ArtifactVerificationError,
+  ARTIFACT_HASH_ALG,
+} from './pack-install.js';
+
+// Ephemeral platform keypair (regenerated each run — never committed).
+const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+
+/** Reproduce the hq-pro publish-side: sha256 hex hash + Ed25519 over the hash. */
+function publishSide(bytes: Buffer): { contentHash: string; signature: string } {
+  const contentHash = createHash('sha256').update(bytes).digest('hex');
+  const signature = cryptoSign(
+    null,
+    Buffer.from(contentHash, 'utf-8'),
+    privateKey,
+  ).toString('base64');
+  return { contentHash, signature };
+}
+
+const APPROVED_BYTES = Buffer.from('the-approved-pack.tar.gz-bytes');
+
+describe('computeArtifactHash', () => {
+  it('matches a lowercase-hex sha256 (shared contract with publish)', () => {
+    const expected = createHash('sha256').update(APPROVED_BYTES).digest('hex');
+    expect(computeArtifactHash(APPROVED_BYTES)).toBe(expected);
+    expect(ARTIFACT_HASH_ALG).toBe('sha256');
+  });
+});
+
+describe('verifyArtifact — integrity (hash)', () => {
+  it('passes when the downloaded bytes match the pinned hash + valid signature', () => {
+    const { contentHash, signature } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        signature,
+        publicKey: publicKeyPem,
+        requireSignature: true,
+      }),
+    ).not.toThrow();
+  });
+
+  it('E2E: a MUTATED S3 object → hash mismatch → REFUSES', () => {
+    // Publish/approval pinned the hash of APPROVED_BYTES…
+    const { contentHash, signature } = publishSide(APPROVED_BYTES);
+    // …but the bytes we actually downloaded were swapped by an attacker.
+    const mutatedBytes = Buffer.from('EVIL-swapped-pack.tar.gz-bytes');
+
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: mutatedBytes,
+        expectedHash: contentHash,
+        signature,
+        publicKey: publicKeyPem,
+      }),
+    ).toThrow(ArtifactVerificationError);
+
+    try {
+      verifyArtifact({
+        tarballBytes: mutatedBytes,
+        expectedHash: contentHash,
+      });
+    } catch (e) {
+      expect((e as Error).message).toMatch(/hash mismatch/i);
+    }
+  });
+
+  it('refuses when the listing provides no valid hash', () => {
+    expect(() =>
+      verifyArtifact({ tarballBytes: APPROVED_BYTES, expectedHash: '' }),
+    ).toThrow(/valid sha256 content hash/i);
+    expect(() =>
+      verifyArtifact({ tarballBytes: APPROVED_BYTES, expectedHash: 'not-a-hash' }),
+    ).toThrow(ArtifactVerificationError);
+  });
+});
+
+describe('verifyArtifact — authenticity (signature)', () => {
+  it('refuses a hash-valid artifact whose signature was forged by a different key', () => {
+    const { contentHash } = publishSide(APPROVED_BYTES);
+    // Attacker signs the (correct) hash with their OWN key.
+    const { privateKey: evilKey } = generateKeyPairSync('ed25519');
+    const forged = cryptoSign(
+      null,
+      Buffer.from(contentHash, 'utf-8'),
+      evilKey,
+    ).toString('base64');
+
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        signature: forged,
+        publicKey: publicKeyPem, // platform key — won't validate the forgery
+      }),
+    ).toThrow(/signature is invalid/i);
+  });
+
+  it('refuses on a corrupt/garbage signature', () => {
+    const { contentHash } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        signature: 'not-base64-or-a-real-sig!!!',
+        publicKey: publicKeyPem,
+      }),
+    ).toThrow(ArtifactVerificationError);
+  });
+
+  it('refuses on an invalid public key', () => {
+    const { contentHash, signature } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        signature,
+        publicKey: 'not a real pem',
+      }),
+    ).toThrow(/public key/i);
+  });
+});
+
+describe('verifyArtifact — deferred-key window', () => {
+  it('hash-verifies but skips signature when none provided (requireSignature=false)', () => {
+    const { contentHash } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({ tarballBytes: APPROVED_BYTES, expectedHash: contentHash }),
+    ).not.toThrow();
+  });
+
+  it('refuses an unsigned artifact when requireSignature=true', () => {
+    const { contentHash } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        requireSignature: true,
+      }),
+    ).toThrow(/unsigned/i);
+  });
+
+  it('refuses when a signature is present but no public key is available (requireSignature=true)', () => {
+    const { contentHash, signature } = publishSide(APPROVED_BYTES);
+    expect(() =>
+      verifyArtifact({
+        tarballBytes: APPROVED_BYTES,
+        expectedHash: contentHash,
+        signature,
+        requireSignature: true,
+      }),
+    ).toThrow(/public key/i);
+  });
+});