@dzhechkov/harness-cli 0.3.210 → 0.3.211

package/keys/README.md

@@ -0,0 +1,8 @@
+# Trust root
+
+`dz.pub` — the pinned Ed25519 public key that `dz doctor` / `dz upgrade` use to verify **other**
+`skills-*` packs. It is not here yet: no project key has been generated (see task #36). Until it is,
+every pack reports `no-trust-root`, and nothing fails.
+
+This key verifies other packs, never `harness-cli` itself. A compromised verifier is outside the threat
+model: you have already executed its code. See `features/verify-apply-leg/03_adr/001-keyring-in-the-verifier.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.210",
+  "version": "0.3.211",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "keys"
   ],
   "dependencies": {
     "@dzhechkov/harness-presets": "^0.5.0",
@@ -54,7 +55,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.107"
+    "@dzhechkov/harness-core": "0.3.108"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/cli.ts

@@ -6,10 +6,10 @@
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmdirSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
 
 import {
   createSkill,
@@ -96,8 +96,20 @@ import {
   RECALL_USAGE_LOG_MAX_BYTES,
   parseRecallUsageLog,
   buildRecallUsageReport,
+  buildManifest,
+  buildSbom,
+  resolveTrustRoot,
+  decideVerifyPolicy,
+  decideProvenance,
+  isInsideTree,
+  signManifest,
+  verifyManifest,
+  assertKeyOutsideTree,
+  decidePublishGate,
+  MANIFEST_NAME,
+  SBOM_NAME,
 } from '@dzhechkov/harness-core';
-import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow } from '@dzhechkov/harness-core';
+import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -111,13 +123,16 @@ Usage:
   dz list   [--skills-dir <dir>]
   dz info   <skill-id> [--skills-dir <dir>]
   dz migrate [--project <dir>]
-  dz doctor [--project <dir>]
   dz create-skill --name <id> [--description <text>] [--skills-dir <dir>] [--tier <1-3>] [--with-references] [--no-evals] [--bto]
   dz scout   [--topics <list>] [--since <date>] [--deep] [--output <file>] [--diff] [--report]
   dz workflow <task> [--dry-run]
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
-  dz publish [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm/--no-dry-run to go live; claim-check gate default warn — surfaces README claim findings, never blocks; error fails an offending package)
+  dz doctor  [--project <dir>] [--pubkey <path>] [--require-signing]   (health + signature check of installed packs)
+  dz upgrade [--target <name>] [--pubkey <path>] [--require-signing]   (a TAMPERED pack aborts the upgrade)
+  dz sign   --pack <dir> --key <path-outside-repo>          (Ed25519 manifest + CycloneDX SBOM for a pack)
+  dz verify-pack --pack <dir> [--pubkey <path>]             (signature check; fail-closed; key from the repo, never the pack)
+  dz publish [--filter <name>] [--bump-only] [--claim-check <off|warn|error>] [--require-signing] [--provenance|--no-provenance]   (dry-run by default; pass --yes/--confirm/--no-dry-run to go live; claim-check gate default warn — surfaces README claim findings, never blocks; error fails an offending package)
   dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force] [--enrich]
   dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
@@ -146,7 +161,6 @@ Usage:
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
   dz diff <skill-dir>
-  dz upgrade [--target <name>] [--project <dir>]
   dz auto-canonicalize --source <github-url> --pack <skills-pack>
   dz registry [search <query>] [--category <cat>]
   dz benchmark <skill-dir> [--compare <dir>] [--all]
@@ -653,14 +667,18 @@ function cmdMigrate(options: Map<string, string>, cwd: string, write: Write): nu
   return 0;
 }
 
-async function cmdDoctor(options: Map<string, string>, cwd: string, write: Write): Promise<number> {
+async function cmdDoctor(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const report = await runDoctor({ projectRoot });
   write(`dz doctor (${report.node}):`);
   for (const check of report.checks) {
     write(`  [${check.ok ? 'OK' : 'XX'}] ${check.name} - ${check.detail}`);
   }
-  return report.ok ? 0 : 1;
+  // ADR-001 (verify-apply-leg): the consumer-side apply-leg. A TAMPERED pack is fatal; an unsigned
+  // pack or a missing trust root is reported. A signature proves the bytes are unmodified — never
+  // that the skill is any good.
+  const sigFatal = reportPackVerification(projectRoot, options.get('pubkey'), flags.has('require-signing'), write);
+  return report.ok && sigFatal === 0 ? 0 : 1;
 }
 
 function cmdRoam(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
@@ -2873,7 +2891,7 @@ function cmdRecommend(options: Map<string, string>, cwd: string, write: Write):
   return 0;
 }
 
-function cmdUpgrade(options: Map<string, string>, cwd: string, write: Write): number {
+function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const targetOpt = options.get('target') ?? 'claude-code';
   if (!isTargetName(targetOpt)) {
     write(`dz upgrade: --target must be one of: ${TARGET_NAMES.join(', ')}`);
@@ -2917,6 +2935,12 @@ function cmdUpgrade(options: Map<string, string>, cwd: string, write: Write): nu
   if (report.needsUpdate > 0) {
     write(`\n${report.needsUpdate} skill(s) need update. Run: dz init --target ${targetOpt} --force`);
   }
+  // ADR-001 (verify-apply-leg): verify what we just left on disk. A TAMPERED pack aborts.
+  const sigFatal = reportPackVerification(projectRoot, options.get('pubkey'), flags.has('require-signing'), write);
+  if (sigFatal !== 0) {
+    write('dz upgrade: aborting — an installed pack does not match its signed manifest');
+    return 1;
+  }
   return 0;
 }
 
@@ -2988,10 +3012,213 @@ async function cmdAutoCanonicalize(options: Map<string, string>, cwd: string, wr
   }
 }
 
+
+/** The pinned trust root. A key inside the artifact under verification is data, not a key (ADR-001). */
+const TRUST_ROOT_REL = 'keys/dz.pub';
+
+function packFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string, rel: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
+      const abs = join(d, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) walk(abs, r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  walk(dir, '');
+  return out.sort();
+}
+
+
+/**
+ * The consumer-side apply-leg (ADR-001, verify-apply-leg). All security content lives in the two pure
+ * functions in harness-core; this only resolves paths, reads bytes, and reports.
+ *
+ * The packaged key sits inside harness-cli — the VERIFIER — and vouches for other packs. It never
+ * comes from the pack under verification.
+ */
+function packagedTrustRootPath(): string | undefined {
+  // dist/cli.js -> ../keys/dz.pub  (and src/cli.ts -> ../keys/dz.pub when run from source)
+  const p = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'keys', 'dz.pub');
+  return existsSync(p) ? p : undefined;
+}
+
+interface PackCheck {
+  readonly pack: string;
+  readonly verdict: PackVerdict;
+  readonly failures: readonly { path: string; reason: string }[];
+}
+
+function verifyInstalledPacks(cwd: string, explicitPubkey?: string | undefined): {
+  readonly trustRoot: ReturnType<typeof resolveTrustRoot>;
+  readonly checks: PackCheck[];
+} {
+  // Cross-model review: `--pubkey ./missing.pub` used to fall back to the repo/packaged key and could
+  // then report `verified` against a key the caller never asked for. An explicit request that cannot be
+  // honoured is an error, not a suggestion.
+  const explicit = explicitPubkey ? resolve(cwd, explicitPubkey) : undefined;
+  if (explicit !== undefined && !existsSync(explicit)) {
+    throw new Error('dz: --pubkey ' + explicit + ' does not exist — refusing to fall back to another key');
+  }
+  const repoKey = resolve(cwd, TRUST_ROOT_REL);
+  const trustRoot = resolveTrustRoot({
+    explicit: explicit && existsSync(explicit) ? explicit : undefined,
+    repo: existsSync(repoKey) ? repoKey : undefined,
+    packaged: packagedTrustRootPath(),
+  });
+
+  const packs = discoverSkillPackDirs(cwd);
+
+  // Cross-model review: `--pubkey <pack>/evil.pub` would let the artifact supply its own verifying key
+  // through the caller. The tool must never verify a pack against a key that lives inside it.
+  if (trustRoot?.source === 'explicit') {
+    for (const { dir } of packs) {
+      if (isInsideTree(trustRoot.path, dir)) {
+        throw new Error('dz: --pubkey lives inside the pack being verified (' + dir + ') — refusing');
+      }
+    }
+  }
+
+  const checks: PackCheck[] = [];
+  for (const { pack, dir } of packs) {
+    if (trustRoot === null) {
+      checks.push({ pack, verdict: 'no-trust-root', failures: [] });
+      continue;
+    }
+    const manifestPath = join(dir, MANIFEST_NAME);
+    if (!existsSync(manifestPath)) {
+      checks.push({ pack, verdict: 'unsigned', failures: [] });
+      continue;
+    }
+    let signed: unknown;
+    try {
+      signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+      checks.push({ pack, verdict: 'tampered', failures: [{ path: MANIFEST_NAME, reason: 'not valid JSON' }] });
+      continue;
+    }
+    // The key existed when the trust root was resolved; it can vanish before it is read. A crash is
+    // not a verdict — fail closed with a named reason.
+    let keyPem: string;
+    try {
+      keyPem = readFileSync(trustRoot.path, 'utf8');
+    } catch {
+      checks.push({ pack, verdict: 'no-trust-root', failures: [] });
+      continue;
+    }
+    const res = verifyManifest(dir, signed as never, keyPem);
+    checks.push({
+      pack,
+      verdict: res.ok ? 'verified' : 'tampered',
+      failures: res.failures.map((f) => ({ path: f.path, reason: f.reason })),
+    });
+  }
+  return { trustRoot, checks };
+}
+
+/** Print the pack verdicts and return 1 iff the policy says any of them is fatal. */
+function reportPackVerification(
+  cwd: string,
+  explicitPubkey: string | undefined,
+  requireSigning: boolean,
+  write: Write,
+): number {
+  let trustRoot: ReturnType<typeof resolveTrustRoot>;
+  let checks: PackCheck[];
+  try {
+    ({ trustRoot, checks } = verifyInstalledPacks(cwd, explicitPubkey));
+  } catch (err) {
+    // A refusal is a result, not a crash: the user gets one line, not a stack trace.
+    write(`  [XX] ${(err as Error).message}`);
+    return 1;
+  }
+  if (checks.length === 0) return 0;
+
+  const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0 } as Record<PackVerdict, number>;
+  let fatal = 0;
+  for (const c of checks) {
+    counts[c.verdict]++;
+    const decision = decideVerifyPolicy(c.verdict, requireSigning);
+    // Only a FATAL verdict earns a line of its own. 22 identical "unverifiable" lines is noise, and
+    // noise is how a real failure gets scrolled past.
+    if (decision.action === 'fail') {
+      fatal++;
+      write(`  [XX] ${c.pack} - ${decision.reason}`);
+      for (const f of c.failures) write(`         ${f.path}: ${f.reason}`);
+    }
+  }
+  const root = trustRoot ? `${trustRoot.source} (${trustRoot.path})` : 'none';
+  write(
+    `  signatures: ${counts.verified} verified, ${counts.unsigned} unsigned, ` +
+      `${counts.tampered} TAMPERED, ${counts['no-trust-root']} unverifiable; trust root: ${root}`,
+  );
+  // A signature proves the bytes are unmodified. It never proves the skill is any good.
+  return fatal > 0 ? 1 : 0;
+}
+
+function cmdSign(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const pack = options.get('pack');
+  const key = options.get('key');
+  if (!pack || !key) {
+    write('dz sign: --pack <dir> and --key <path> are both required');
+    write('  the key path MUST be outside the repository working tree (a leaked signing key is not revertible)');
+    return 1;
+  }
+  const packDir = resolve(cwd, pack);
+  if (!existsSync(packDir)) { write(`dz sign: no such pack: ${packDir}`); return 1; }
+
+  try {
+    assertKeyOutsideTree(resolve(cwd, key), cwd);
+  } catch (err) {
+    write(`dz sign: ${(err as Error).message}`);
+    return 1;
+  }
+  if (!existsSync(resolve(cwd, key))) { write(`dz sign: private key not found: ${resolve(cwd, key)}`); return 1; }
+
+  const files = packFiles(packDir);
+  if (files.length === 0) { write('dz sign: the pack contains no files — refusing to sign nothing'); return 1; }
+
+  const manifest = buildManifest(packDir, basename(packDir), files);
+  const signed = signManifest(manifest, readFileSync(resolve(cwd, key), 'utf8'));
+  writeFileSync(join(packDir, MANIFEST_NAME), JSON.stringify(signed, null, 2) + '\n');
+  writeFileSync(join(packDir, SBOM_NAME), JSON.stringify(buildSbom(manifest), null, 2) + '\n');
+  write(`dz sign: signed ${files.length} file(s) in ${packDir}`);
+  write(`  ${MANIFEST_NAME} + ${SBOM_NAME} written. Ed25519 gives tamper-evidence, never truthfulness.`);
+  return 0;
+}
+
+function cmdVerifyPack(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const pack = options.get('pack');
+  if (!pack) { write('dz verify-pack: --pack <dir> is required'); return 1; }
+  const packDir = resolve(cwd, pack);
+
+  // The key is pinned in the repo. Never read it from the pack (ADR-001, recalled lesson).
+  const pubPath = resolve(cwd, options.get('pubkey') ?? TRUST_ROOT_REL);
+  if (!existsSync(pubPath)) {
+    write(`dz verify-pack: no trust root at ${pubPath} — refusing to verify (fail closed)`);
+    return 1;
+  }
+  const manifestPath = join(packDir, MANIFEST_NAME);
+  if (!existsSync(manifestPath)) { write(`dz verify-pack: ${packDir} carries no ${MANIFEST_NAME}`); return 1; }
+
+  let signed: unknown = null;
+  try { signed = JSON.parse(readFileSync(manifestPath, 'utf8')); }
+  catch { write(`dz verify-pack: ${MANIFEST_NAME} is not valid JSON`); return 1; }
+
+  const res = verifyManifest(packDir, signed as never, readFileSync(pubPath, 'utf8'));
+  if (res.ok) { write(`dz verify-pack: OK — ${packDir} matches its signed manifest`); return 0; }
+  write(`dz verify-pack: FAILED — ${packDir}`);
+  for (const f of res.failures) write(`  ${f.path}: ${f.reason}`);
+  return 1;
+}
+
 function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
   // silently swallowed and flip the command into live-publish mode.
-  const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help']);
+  const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help', 'require-signing', 'provenance', 'no-provenance']);
   const allowedOptions = new Set(['filter', 'claim-check']);
   const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>';
   for (const flag of flags) {
@@ -3010,6 +3237,20 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     }
   }
 
+  // ADR-001 (publish-provenance): decide BEFORE any work — flag validation, then a pre-flight that
+  // refuses `--provenance` where no OIDC token can be minted. `off` is an escape hatch that names itself.
+  if (flags.has('provenance') && flags.has('no-provenance')) {
+    write('dz publish: --provenance and --no-provenance are mutually exclusive');
+    return 1;
+  }
+  const provenance: ProvenanceMode = flags.has('provenance') ? 'on' : flags.has('no-provenance') ? 'off' : 'auto';
+  try {
+    write(`dz publish: ${decideProvenance(provenance, process.env).reason}`);
+  } catch (err) {
+    write((err as Error).message);
+    return 1;
+  }
+
   // Pre-publish claim-check gate strictness: reject (never coerce) an invalid value. Default 'warn'
   // per ADR-001 — findings are SURFACED on every publish, but 'warn' never changes publish status,
   // so the success path is unchanged. 'off' disables the gate; 'error' fails an offending package.
@@ -3065,7 +3306,46 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     write(`╚══════════════════════════════════════════════════════════════════════╝`);
   }
 
-  const report = publishPackages(cwd, { dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
+  // FR-4 — the signature gate, BEFORE anything is published (ADR-001).
+  // Strictness follows the trust root: with no keys/dz.pub committed there is nothing to verify
+  // against, and blocking would refuse every release forever. That is stated on every run.
+  {
+    const trustRoot = resolve(cwd, TRUST_ROOT_REL);
+    const trustRootPresent = existsSync(trustRoot);
+    const requireSigning = flags.has('require-signing');
+    // `filter` is a string[] of substrings (matching publishPackages' own semantics), not a string.
+    const targets = discoverPackages(cwd).filter(
+      (pk) => !filter || filter.length === 0 || filter.some((f) => pk.name.includes(f)),
+    );
+    let blocked = 0;
+
+    for (const pk of targets) {
+      const manifestPath = join(pk.dir, MANIFEST_NAME);
+      const manifestPresent = existsSync(manifestPath);
+      let verifyOk = false;
+      if (trustRootPresent && manifestPresent) {
+        try {
+          const signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+          verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8')).ok;
+        } catch {
+          verifyOk = false;
+        }
+      }
+      const decision = decidePublishGate({ trustRootPresent, manifestPresent, verifyOk, requireSigning });
+      if (decision.action === 'block') {
+        write(`dz publish: BLOCKED ${pk.name} — ${decision.reason}`);
+        blocked++;
+      } else if (decision.action === 'publish-unsigned') {
+        write(`dz publish: ${pk.name} — ${decision.reason}`);
+      }
+    }
+    if (blocked > 0) {
+      write(`dz publish: refusing to publish (${blocked} package(s) failed the signature gate)`);
+      return 1;
+    }
+  }
+
+  const report = publishPackages(cwd, { provenance, dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
 
   write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}${claimCheckOpt !== 'warn' ? ` --claim-check ${claimCheckOpt}` : ''}`);
   write(`  Published: ${report.published}  Skipped: ${report.skipped}  Errors: ${report.errors}\n`);
@@ -4094,7 +4374,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'migrate':
         return cmdMigrate(options, cwd, write);
       case 'doctor':
-        return await cmdDoctor(options, cwd, write);
+        return await cmdDoctor(options, flags, cwd, write);
       case 'install':
         return await cmdInstall(options, flags, cwd, write);
       case 'bundle':
@@ -4115,6 +4395,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdUsage(options, optionLists, flags, cwd, write);
       case 'claim-check':
         return cmdClaimCheck(options, optionLists, flags, cwd, write);
+      case 'sign':
+        return cmdSign(options, flags, cwd, write);
+      case 'verify-pack':
+        return cmdVerifyPack(options, flags, cwd, write);
       case 'setup':
         return await cmdSetup(options, flags, cwd, write);
       case 'pretrain':
@@ -4126,7 +4410,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'recommend':
         return cmdRecommend(options, cwd, write);
       case 'upgrade':
-        return cmdUpgrade(options, cwd, write);
+        return cmdUpgrade(options, flags, cwd, write);
       case 'auto-canonicalize':
         return await cmdAutoCanonicalize(options, cwd, write);
       case 'publish':