@dzhechkov/harness-core 0.3.107 → 0.3.108

package/src/sign.ts

@@ -0,0 +1,421 @@
+/**
+ * `dz sign` / `dz verify` — Ed25519 tamper-evidence for a skill pack.
+ *
+ * SCOPE, stated once so a green check mark cannot overstate itself (recalled lesson, security,
+ * 2026-07-06): *"Verifying a signature against a public key EMBEDDED in the same signed object proves
+ * nothing about issuer identity. Trust must bind issuer -> a PINNED out-of-band key. Ed25519 gives
+ * provenance/tamper-evidence, never truthfulness."*
+ *
+ * So: `verifyManifest` takes the public key as a REQUIRED PARAMETER. There is no default, no fallback,
+ * and no lookup inside the pack. A `pubkey.pem` sitting in the pack is data, not a key.
+ *
+ * Zero dependencies: `node:crypto`, `node:fs`, `node:path`.
+ */
+
+import { createHash, sign as cryptoSign, verify as cryptoVerify, createPrivateKey, createPublicKey } from 'node:crypto';
+import { readFileSync, existsSync, readdirSync, openSync, fstatSync, closeSync, constants as fsConstants } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+export const MANIFEST_NAME = '.dz-manifest.json';
+export const SBOM_NAME = 'sbom.json';
+export const MANIFEST_VERSION = 1;
+
+export interface ManifestEntry {
+  readonly path: string;
+  readonly sha256: string;
+}
+
+export interface Manifest {
+  readonly version: number;
+  readonly pack: string;
+  readonly files: readonly ManifestEntry[];
+}
+
+export interface SignedManifest {
+  readonly manifest: Manifest;
+  /** base64 Ed25519 signature over `canonicalizeManifest(manifest.files)`. */
+  readonly signature: string;
+}
+
+export interface VerifyFailure {
+  readonly path: string;
+  readonly reason: string;
+}
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly failures: readonly VerifyFailure[];
+}
+
+/** sha256 of a file's bytes, hex. Follows symlinks — used only when building a manifest we control. */
+export function hashFile(absPath: string): string {
+  return createHash('sha256').update(readFileSync(absPath)).digest('hex');
+}
+
+/**
+ * Round-2 review (codex exec): `lstat` then `readFile` is a TOCTOU window — the path can be swapped
+ * for a symlink between the two calls. Open ONCE with `O_NOFOLLOW`, `fstat` the descriptor, and read
+ * from that same descriptor. The bytes hashed are the bytes the stat described.
+ *
+ * Returns `null` when the path is not a regular file, or is a symlink.
+ */
+export function hashRegularFileNoFollow(absPath: string): string | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    if (!fstatSync(fd).isFile()) return null;
+    return createHash('sha256').update(readFileSync(fd)).digest('hex');
+  } catch {
+    return null; // ELOOP on a symlink, ENOENT, EACCES — all fail closed
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * Cross-model security review (codex exec, 2026-07-10) — a SIGNED manifest is not a TRUSTED manifest.
+ * Its own contents are attacker-controlled until the signature checks out, and even then they must be
+ * structurally sane before they touch the filesystem.
+ *
+ *   - `join(root, '../../etc/passwd')` escaped the pack (traversal).
+ *   - a newline in a path makes the canonical `<hex>  <path>\n` encoding ambiguous.
+ *   - duplicate paths make canonical bytes depend on input order — the sort is not a total order.
+ *   - a non-string `path` threw inside `hashFile` instead of failing closed.
+ */
+const SAFE_MANIFEST_PATH = /^[A-Za-z0-9._-][A-Za-z0-9._/-]*$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export function isSafeManifestPath(p: unknown): p is string {
+  if (typeof p !== 'string' || p.length === 0 || p.length > 4096) return false;
+  if (!SAFE_MANIFEST_PATH.test(p)) return false;          // no control chars, no backslash, no leading /
+  if (p.split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) return false;
+  return true;
+}
+
+/** Returns an error message, or `null` when the entry list is structurally sound. */
+export function checkManifestEntries(files: unknown): string | null {
+  if (!Array.isArray(files)) return 'manifest has no file list';
+  if (files.length === 0) return 'manifest signs nothing';
+  const seen = new Set<string>();
+  for (const f of files) {
+    if (!f || typeof f !== 'object') return 'manifest entry is not an object';
+    const { path: pth, sha256 } = f as { path?: unknown; sha256?: unknown };
+    if (!isSafeManifestPath(pth)) return 'manifest entry has an unsafe path: ' + JSON.stringify(pth);
+    if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256)) return 'manifest entry has a malformed sha256 for ' + pth;
+    // Round-2 review: an exact-string `seen` set misses collisions on case-insensitive filesystems
+    // (`Readme` vs `README`). Unicode normalization (`e\u0301.txt` vs `é.txt`) cannot arise: paths are
+    // ASCII-only by `SAFE_MANIFEST_PATH`, and a non-ASCII path is refused before it reaches here. An
+    // NFC check here would be unreachable code pretending to be a guard.
+    const fold = pth.toLowerCase();
+    if (seen.has(fold)) return 'manifest lists ' + pth + ' twice (case/unicode fold) — canonical bytes would depend on order';
+    seen.add(fold);
+  }
+  return null;
+}
+
+/** Every file under `root`, POSIX-relative, excluding the manifest and the SBOM themselves. */
+export function listPackFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, rel: string): void => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
+      const abs = join(dir, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) walk(abs, r);
+      else out.push(r);
+    }
+  };
+  walk(root, '');
+  return out.sort();
+}
+
+/**
+ * The bytes that get signed (FR-7). Sorted by path, LF endings, no trailing whitespace, and no
+ * dependence on JSON key order — a signature must not depend on how a serialiser felt that day.
+ * Format is `sha256sum`-compatible: `<hex>  <path>\n`.
+ */
+export function canonicalizeManifest(files: readonly ManifestEntry[]): Buffer {
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const body = sorted.map((f) => f.sha256 + '  ' + f.path + '\n').join('');
+  return Buffer.from(body, 'utf8');
+}
+
+/**
+ * The bytes actually signed. Cross-model review (2026-07-10) found `pack` and `version` were carried
+ * in the manifest but NOT covered by the signature: an attacker could relabel a signed pack. Nothing
+ * is signed yet, so the format can change today. It can never change once packs are in the wild.
+ */
+export function canonicalizeSigned(manifest: Manifest): Buffer {
+  const header = 'dz-manifest\nversion ' + String(manifest.version) + '\npack ' + manifest.pack + '\n';
+  return Buffer.concat([Buffer.from(header, 'utf8'), canonicalizeManifest(manifest.files)]);
+}
+
+/** Build a manifest for `files` (paths relative to `root`, POSIX separators). */
+export function buildManifest(root: string, pack: string, files: readonly string[]): Manifest {
+  const entries = files.map((rel) => ({
+    path: rel.split(sep).join('/'),
+    sha256: hashFile(join(root, rel)),
+  }));
+  return { version: MANIFEST_VERSION, pack, files: entries };
+}
+
+export function signManifest(manifest: Manifest, privateKeyPem: string): SignedManifest {
+  // Defence in depth (round-2 review): `pack` is interpolated into a newline-delimited signed header.
+  // `verifyManifest` already refuses an unsafe pack name, so an ambiguous header could never verify —
+  // but refusing to CREATE one is cheaper than reasoning about why it cannot be exploited.
+  if (!isSafeManifestPath(manifest.pack)) throw new Error('refusing to sign an unsafe pack name: ' + JSON.stringify(manifest.pack));
+  if (!Number.isInteger(manifest.version)) throw new Error('refusing to sign a non-integer manifest version');
+  const structural = checkManifestEntries(manifest.files);
+  if (structural) throw new Error('refusing to sign a malformed manifest: ' + structural);
+  const key = createPrivateKey(privateKeyPem);
+  const sig = cryptoSign(null, canonicalizeSigned(manifest), key);
+  return { manifest, signature: sig.toString('base64') };
+}
+
+/**
+ * FR-8 / risk R1: every degenerate input FAILS CLOSED. Absence must never read as success — that is the
+ * failure mode that turns a security tool into a lie.
+ *
+ * `pubKeyPem` is required. It comes from the repo, never from `root`.
+ */
+/**
+ * Round-2 review killed the `expectedFiles` option: a caller could NARROW the added-file check and
+ * silently allow an unsigned `evil.js` to sit in the pack. A safety option that a caller may disable
+ * is not a safety option. The pack is always scanned.
+ */
+export function verifyManifest(
+  root: string,
+  signed: SignedManifest | null | undefined,
+  pubKeyPem: string,
+): VerifyResult {
+  const fail = (path: string, reason: string): VerifyResult => ({ ok: false, failures: [{ path, reason }] });
+
+  if (!signed || typeof signed !== 'object') return fail(MANIFEST_NAME, 'no manifest');
+  const { manifest, signature } = signed;
+  if (!manifest || typeof manifest !== 'object') return fail(MANIFEST_NAME, 'manifest is missing');
+  if (typeof manifest.version !== 'number' || !Number.isInteger(manifest.version)) {
+    return fail(MANIFEST_NAME, 'manifest version is not an integer');
+  }
+  if (!isSafeManifestPath(manifest.pack)) {
+    return fail(MANIFEST_NAME, 'manifest pack name is unsafe: ' + JSON.stringify(manifest.pack));
+  }
+  const structural = checkManifestEntries(manifest.files);
+  if (structural) return fail(MANIFEST_NAME, structural);
+  if (typeof signature !== 'string' || signature.length === 0) {
+    return fail(MANIFEST_NAME, 'manifest is unsigned');
+  }
+  if (typeof pubKeyPem !== 'string' || pubKeyPem.length === 0) {
+    return fail(MANIFEST_NAME, 'no public key supplied — refusing to verify');
+  }
+
+  // The signature first: if the manifest itself was rewritten, its file list is not evidence.
+  let sigOk = false;
+  try {
+    sigOk = cryptoVerify(
+      null,
+      canonicalizeSigned(manifest),
+      createPublicKey(pubKeyPem),
+      Buffer.from(signature, 'base64'),
+    );
+  } catch {
+    return fail(MANIFEST_NAME, 'signature is malformed');
+  }
+  if (!sigOk) return fail(MANIFEST_NAME, 'signature does not verify against the pinned key');
+
+  const failures: VerifyFailure[] = [];
+  for (const entry of manifest.files) {
+    const abs = join(root, entry.path);
+    if (!existsSync(abs)) {
+      failures.push({ path: entry.path, reason: 'listed in the manifest but absent' });
+      continue;
+    }
+    // One open, O_NOFOLLOW, fstat the descriptor, hash from it: no symlink follow, no TOCTOU window.
+    const digest = hashRegularFileNoFollow(abs);
+    if (digest === null) {
+      failures.push({ path: entry.path, reason: 'is a symlink or not a regular file — refusing to hash it' });
+      continue;
+    }
+    if (digest !== entry.sha256) {
+      failures.push({ path: entry.path, reason: 'content does not match its signed hash' });
+    }
+  }
+
+  // Bidirectional, always: hashing only what the manifest lists lets an attacker ADD a file.
+  const present = listPackFiles(root);
+  const listed = new Set(manifest.files.map((f) => f.path));
+  for (const rel of present) {
+    const p = rel.split(sep).join('/');
+    if (!listed.has(p)) failures.push({ path: p, reason: 'present in the pack but not signed' });
+  }
+
+  return { ok: failures.length === 0, failures };
+}
+
+/**
+ * FR-5, the one irreversible mistake. `.gitignore` covers `*.pem` and `*.key` and nothing else — a key
+ * written as `signing-key.json` would be committed without complaint. Refuse by location, not by name.
+ */
+export function isInsideTree(keyPath: string, repoRoot: string): boolean {
+  const key = resolve(keyPath);
+  const root = resolve(repoRoot);
+  if (key === root) return true;
+  const rel = relative(root, key);
+  // `relative` yields '' for the root itself, a '..'-prefixed path for anything outside, and an
+  // absolute path when the two share no root. Anything else is inside.
+  if (rel === '') return true;
+  if (rel === '..' || rel.startsWith('..' + sep)) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
+
+export function assertKeyOutsideTree(keyPath: string, repoRoot: string): void {
+  if (isInsideTree(keyPath, repoRoot)) {
+    throw new Error(
+      'refusing to write a private key inside the repository working tree: ' +
+        resolve(keyPath) +
+        ' (a leaked signing key cannot be reverted — it means a new key and re-signing every pack)',
+    );
+  }
+}
+
+export interface SbomComponent {
+  readonly type: 'file';
+  readonly name: string;
+  readonly hashes: readonly { readonly alg: 'SHA-256'; readonly content: string }[];
+}
+
+export interface Sbom {
+  readonly bomFormat: 'CycloneDX';
+  readonly specVersion: '1.5';
+  readonly version: number;
+  readonly metadata: { readonly component: { readonly type: 'library'; readonly name: string } };
+  readonly components: readonly SbomComponent[];
+}
+
+/** CycloneDX 1.5 JSON, hand-built — it is JSON against a schema, not a reason for a dependency. */
+export function buildSbom(manifest: Manifest): Sbom {
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.5',
+    version: 1,
+    metadata: { component: { type: 'library', name: manifest.pack } },
+    components: manifest.files.map((f) => ({
+      type: 'file' as const,
+      name: f.path,
+      hashes: [{ alg: 'SHA-256' as const, content: f.sha256 }],
+    })),
+  };
+}
+
+// ── The publish gate (FR-4), as a pure decision ─────────────────────────────
+//
+// The operator's decision was "the publish gate BLOCKS". Reality intervened: with no trust root
+// committed, refusing to publish an unsigned pack refuses to publish anything, forever — a gate that
+// blocks on nothing. You cannot verify against a key you do not have.
+//
+// So the gate's strictness is a function of the trust root's existence, and that is stated out loud:
+//   - trust root present  → every pack MUST verify. A missing or failing manifest blocks the release.
+//   - trust root absent   → packs publish UNSIGNED, and the CLI says so on every run. `--require-signing`
+//                           turns that into a refusal for anyone who wants the strict posture today.
+
+export type PublishGateAction = 'block' | 'publish-unsigned' | 'publish-verified';
+
+export interface PublishGateInput {
+  readonly trustRootPresent: boolean;
+  readonly manifestPresent: boolean;
+  readonly verifyOk: boolean;
+  readonly requireSigning: boolean;
+}
+
+export interface PublishGateDecision {
+  readonly action: PublishGateAction;
+  readonly reason: string;
+}
+
+export function decidePublishGate(input: PublishGateInput): PublishGateDecision {
+  if (!input.trustRootPresent) {
+    if (input.requireSigning) {
+      return { action: 'block', reason: 'no trust root (keys/dz.pub) and --require-signing was passed' };
+    }
+    return {
+      action: 'publish-unsigned',
+      reason: 'no trust root committed (keys/dz.pub) — packs publish UNSIGNED and unverifiable',
+    };
+  }
+  if (!input.manifestPresent) {
+    return { action: 'block', reason: 'trust root is present but the pack carries no signature manifest' };
+  }
+  if (!input.verifyOk) {
+    return { action: 'block', reason: 'the pack does not match its signed manifest' };
+  }
+  return { action: 'publish-verified', reason: 'manifest verified against the pinned key' };
+}
+
+// ── The consumer-side apply-leg (ADR-001, verify-apply-leg) ─────────────────
+//
+// A verifier nobody runs is a signature nobody checks. These two pure functions carry the whole
+// security content of `dz doctor` / `dz upgrade`; the CLI bodies only print and exit.
+
+export type PackVerdict = 'verified' | 'unsigned' | 'tampered' | 'no-trust-root';
+
+export interface TrustRootCandidates {
+  /** `--pubkey <path>`, if the caller passed one and it exists. */
+  readonly explicit?: string | undefined;
+  /** `keys/dz.pub` in the repository, if present. */
+  readonly repo?: string | undefined;
+  /** The key shipped inside harness-cli — the verifier vouching for OTHER packs. */
+  readonly packaged?: string | undefined;
+}
+
+export interface TrustRoot {
+  readonly source: 'explicit' | 'repo' | 'packaged';
+  readonly path: string;
+}
+
+/**
+ * Precedence, explicit and pure: `--pubkey` > repo `keys/dz.pub` > the packaged key.
+ * Never derived from the pack under verification.
+ */
+export function resolveTrustRoot(c: TrustRootCandidates): TrustRoot | null {
+  if (c.explicit) return { source: 'explicit', path: c.explicit };
+  if (c.repo) return { source: 'repo', path: c.repo };
+  if (c.packaged) return { source: 'packaged', path: c.packaged };
+  return null;
+}
+
+export type PolicyAction = 'ok' | 'report' | 'fail';
+
+export interface PolicyDecision {
+  readonly action: PolicyAction;
+  readonly reason: string;
+}
+
+/**
+ * The whole feature, as a table:
+ *
+ * | verdict        | requireSigning off | on   |
+ * |----------------|--------------------|------|
+ * | verified       | ok                 | ok   |
+ * | unsigned       | report             | fail |
+ * | tampered       | FAIL               | FAIL |
+ * | no-trust-root  | report             | fail |
+ *
+ * `tampered` is fatal in both columns; `no-trust-root` is never success. That is the load-bearing
+ * property. Today every pack is `unsigned` or `no-trust-root` — the leg is wired, not armed.
+ */
+export function decideVerifyPolicy(verdict: PackVerdict, requireSigning: boolean): PolicyDecision {
+  if (verdict === 'tampered') {
+    return { action: 'fail', reason: 'pack does not match its signed manifest' };
+  }
+  if (verdict === 'verified') {
+    return { action: 'ok', reason: 'verified against the pinned key' };
+  }
+  if (verdict === 'no-trust-root') {
+    return requireSigning
+      ? { action: 'fail', reason: 'no trust root available and --require-signing was passed' }
+      : { action: 'report', reason: 'no trust root available — nothing could be verified' };
+  }
+  return requireSigning
+    ? { action: 'fail', reason: 'pack is unsigned and --require-signing was passed' }
+    : { action: 'report', reason: 'pack is unsigned — not verified' };
+}

package/src/skill-schema.ts

@@ -0,0 +1,53 @@
+/**
+ * Single-source trustTier (ADR-001, trusttier-single-source).
+ *
+ * A skill's `schemas/output.json` used to hardcode `properties.trustTier.const` — a second copy of the
+ * `trust_tier` in its `SKILL.md` frontmatter. Nothing read the schema copy; the frontmatter is the
+ * single source (`registry.ts` reads it). Two copies of a value drift by construction, and this one
+ * had. This transform removes the value, leaving only a shape constraint.
+ */
+
+export interface TrustTierStripResult {
+  /** The schema object, mutated in place if a const was present. */
+  readonly schema: Record<string, unknown>;
+  /** True iff a `const` was found under `properties.trustTier` and replaced. */
+  readonly changed: boolean;
+}
+
+/**
+ * Replace `properties.trustTier.const: N` with `{ minimum: 1, maximum: 3 }`, preserving every sibling
+ * key (`type`, `description`, …). Idempotent: a schema that already uses a range, has no `const`, or has
+ * no `trustTier`, is returned unchanged with `changed: false`.
+ *
+ * Pure w.r.t. inputs it does not own: it mutates the passed object (the caller owns it) and returns it,
+ * so it is trivially testable without a filesystem.
+ */
+export function stripTrustTierConst(schema: Record<string, unknown>): TrustTierStripResult {
+  const props = schema.properties as Record<string, unknown> | undefined;
+  if (!props || typeof props !== 'object') return { schema, changed: false };
+
+  const tt = props.trustTier as Record<string, unknown> | undefined;
+  // Cross-model review: `'const' in tt` also matches an INHERITED const on the prototype, and
+  // `!== undefined` cannot tell 'key absent' from 'key present, value undefined'. Use own-property
+  // checks throughout so a crafted object cannot trick the transform.
+  if (!tt || typeof tt !== 'object' || !Object.hasOwn(tt, 'const')) return { schema, changed: false };
+
+  // Preserve type/description; drop the value; add the range. Order kept sane for a clean diff:
+  // type (if any) → minimum → maximum → description (if any) → any other siblings.
+  const { const: _dropped, type, description, ...rest } = tt as {
+    const: unknown;
+    type?: unknown;
+    description?: unknown;
+  } & Record<string, unknown>;
+
+  const rebuilt: Record<string, unknown> = {};
+  rebuilt.type = Object.hasOwn(tt, 'type') ? type : 'integer';
+  rebuilt.minimum = 1;
+  rebuilt.maximum = 3;
+  if (Object.hasOwn(tt, 'description')) rebuilt.description = description;
+  // `rest` already excludes const/type/description via destructuring; Object.entries is own-keys only.
+  for (const [k, v] of Object.entries(rest)) rebuilt[k] = v;
+
+  props.trustTier = rebuilt;
+  return { schema, changed: true };
+}