npm - tamperward - Versions diffs - 2.14.1 → 2.15.0 - Mend

tamperward 2.14.1 → 2.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -225,6 +225,17 @@ but this generated GitHub-hosted authority refuses deterministically and tells y
 much outer time is required, so a custom runner/workflow can provide it instead of
 GitHub killing verification mid-verdict.
+Since **2.15.0**, `tamperward doctor` is also the one-shot installation/posture
+report promised by `init`'s security model. It reuses `init`'s canonical wiring
+planner rather than maintaining a second definition of “installed correctly”, and
+reports named `OK`, `WARN`, or `BROKEN` checks for policy/schema, Claude hooks,
+pre-commit, generated CI wiring, CODEOWNERS, workflow permissions, binary/pin
+alignment, verifier trust mode + declared inputs, platform residuals, CI verifier
+outer time, observer health, and (with `--github`) repository authority. Use
+`--json` for one machine-readable document with `authoritative: true|false`.
+Local early-layer gaps remain posture findings rather than silently changing the
+existing generated-CI exit contract; hard CI/GitHub validation failures still exit 2.
 Legitimate exceptions are out-of-band PR labels, `tamperward:allow:<rule>@<head-sha>`.
 The workflow passes the head SHA to both steps through `TAMPERWARD_OOB_HEAD`, so an
 approval is bound to the exact commit it was granted for and a new push invalidates it.
@@ -364,7 +375,7 @@ option can never be reinterpreted as the agent command.
 | --- | --- |
 | `check` | one view — `--staged` · `--worktree` · `--diff <base>...<head>` — plus `--format text\|json\|github\|auto` (default `auto`) · `--json` (alias for `--format json`) · `--cwd <dir>` |
 | `verify` | `--base <rev>` (default `HEAD`) · `--cmd <suite command>` · `--budget <seconds>` · `--json` · `--keep` (keep the two materialised copies and report their paths) · `--require-ancestor` (refuse a base that is not an ancestor of `HEAD`) · `--cwd <dir>` |
-| `doctor` | `--base <rev>` (trusted policy revision) · `--workflow <path>` (default `.github/workflows/tamperward.yml`) · `--cwd <dir>` — validates every job that runs `tamperward verify` has a static outer timeout covering visible + pristine + authority reserve |
+| `doctor` | `--base <rev>` (trusted policy revision) · `--workflow <path>` · `--cwd <dir>` · `--json` · `--github` · `--repo <owner/repo>` · `--branch <name>` — read-only installation/authority posture plus CI verifier outer-time validation |
 | `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` (per verifier suite) · `--agent-budget <seconds>` (optional wrapped-agent wall clock) · `--observe-transients` (start a session-scoped transient observer) · `--allow-dirty` · `--settle <seconds>` (wait before the final quiescence check) · `--allow-dep-drift` · `--cwd <dir>` · then `-- <agent command...>` |
 | `allow` | `<rule>` · `--file <path>` · `--reason "<why>"` (required) · `--cwd <dir>` |
 | `init` | `--cwd <dir>` · `--dry-run` · `--force-workflow` |

package/dist/cli/index.js CHANGED Viewed

@@ -10,6 +10,7 @@ import { join } from "node:path";
 // src/policy.ts
 import picomatch from "picomatch";
 var POLICY_FILE = ".tamperward.yml";
+var POLICY_VERSION = 1;
 var BLOCK_SINCE = {};
 function applyVersionGates(rules, version, gates = BLOCK_SINCE) {
   const out2 = { ...rules };
@@ -8375,9 +8376,21 @@ import { existsSync as existsSync10, readFileSync as readFileSync13, readdirSync
 import { join as join13, resolve as resolve4 } from "node:path";
 import { parse as parse3 } from "yaml";
 var VERIFY_COMMAND = /\btamperward(?:@\S+)?\s+verify\b/;
-function err(message) {
-  process.stderr.write(`tamperward doctor: ${message}
+function err(message, opts, id = "doctor", checks = []) {
+  if (opts?.json) {
+    const report2 = {
+      command: "doctor",
+      authoritative: false,
+      checks: [
+        ...checks.filter((check2) => check2.id !== id),
+        { id, state: "BROKEN", detail: message }
+      ]
+    };
+    process.stdout.write(JSON.stringify(report2) + "\n");
+  } else {
+    process.stderr.write(`tamperward doctor: ${message}
 `);
+  }
   return 2;
 }
 function policyFor(opts, cwd) {
@@ -8388,6 +8401,161 @@ function policyFor(opts, cwd) {
 function asMapping(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
+function wiringState(status, authority) {
+  if (status === "ok") return "OK";
+  if (status === "skip") return "WARN";
+  return authority ? "BROKEN" : "WARN";
+}
+function pinsInFile(path) {
+  if (!existsSync10(path)) return [];
+  let src = "";
+  try {
+    src = readFileSync13(path, "utf8");
+  } catch {
+    return [];
+  }
+  return Array.from(src.matchAll(/\btamperward@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))\b/g), (m) => m[1]);
+}
+function workflowPermissionCheck(cwd) {
+  const rel = ".github/workflows/tamperward.yml";
+  const path = join13(cwd, rel);
+  if (!existsSync10(path)) return { id: "workflow-permissions", state: "BROKEN", detail: `${rel} is missing` };
+  let doc;
+  try {
+    doc = parse3(readFileSync13(path, "utf8"));
+  } catch (e) {
+    return {
+      id: "workflow-permissions",
+      state: "BROKEN",
+      detail: `${rel} is not valid YAML (${e instanceof Error ? e.message : String(e)})`
+    };
+  }
+  const root = asMapping(doc);
+  const permissions = asMapping(root?.permissions);
+  if (!permissions) {
+    return {
+      id: "workflow-permissions",
+      state: "BROKEN",
+      detail: "workflow does not declare least-privilege permissions; repository defaults could grant write access"
+    };
+  }
+  const writes = Object.entries(permissions).filter(
+    ([, value]) => typeof value === "string" && /write/i.test(value)
+  );
+  if (writes.length) {
+    return {
+      id: "workflow-permissions",
+      state: "BROKEN",
+      detail: "workflow grants write permission: " + writes.map(([name]) => name).join(", ")
+    };
+  }
+  if (permissions.contents !== "read") {
+    return {
+      id: "workflow-permissions",
+      state: "WARN",
+      detail: "workflow permissions are explicit but contents: read is not declared"
+    };
+  }
+  return { id: "workflow-permissions", state: "OK", detail: "workflow token is explicitly read-only (contents: read)" };
+}
+function collectLocalPosture(cwd, policy) {
+  const checks = [];
+  checks.push(
+    policy.version <= POLICY_VERSION ? { id: "policy", state: "OK", detail: `policy version ${policy.version} is understood (current schema ${POLICY_VERSION})` } : { id: "policy", state: "WARN", detail: `policy version ${policy.version} is newer than this binary's schema ${POLICY_VERSION}; only known gates can be evaluated` }
+  );
+  let plan = [];
+  try {
+    plan = planInit(cwd);
+  } catch (e) {
+    checks.push({
+      id: "installation-plan",
+      state: "BROKEN",
+      detail: `canonical wiring could not be evaluated: ${e instanceof Error ? e.message : String(e)}`
+    });
+  }
+  const byItem = new Map(plan.map((x) => [x.item, x]));
+  const addWiring = (id, item, authority) => {
+    const action = byItem.get(item);
+    if (!action) {
+      checks.push({ id, state: authority ? "BROKEN" : "WARN", detail: `${item} wiring could not be evaluated` });
+      return;
+    }
+    checks.push({
+      id,
+      state: wiringState(action.status, authority),
+      detail: action.status === "ok" ? action.detail : `${action.status}: ${action.detail}`
+    });
+  };
+  addWiring("claude-hooks", "agent", true);
+  addWiring("pre-commit", "pre-commit", false);
+  addWiring("ci-wiring", "ci", true);
+  addWiring("codeowners", "codeowners", true);
+  checks.push(workflowPermissionCheck(cwd));
+  const pins = [
+    ...pinsInFile(join13(cwd, ".claude", "settings.json")),
+    ...pinsInFile(join13(cwd, ".git", "hooks", "pre-commit")),
+    ...pinsInFile(join13(cwd, ".husky", "pre-commit"))
+  ];
+  const below = pins.filter((pin) => (compareVersions(pin, TW_VERSION) ?? 0) < 0);
+  const above = pins.filter((pin) => (compareVersions(TW_VERSION, pin) ?? 0) < 0);
+  checks.push(
+    below.length ? { id: "binary-version", state: "BROKEN", detail: `wiring pins older TamperWard version(s): ${Array.from(new Set(below)).join(", ")}; running binary is ${TW_VERSION}` } : above.length ? { id: "binary-version", state: "WARN", detail: `repository wiring targets newer TamperWard version(s): ${Array.from(new Set(above)).join(", ")}; running binary is ${TW_VERSION}` } : pins.length ? { id: "binary-version", state: "OK", detail: `wiring pins agree with running TamperWard ${TW_VERSION}` } : { id: "binary-version", state: "WARN", detail: `no canonical TamperWard version pin was found; running binary is ${TW_VERSION}` }
+  );
+  if (!policy.verify?.command) {
+    checks.push({ id: "verifier", state: "BROKEN", detail: "verify.command is not configured" });
+  } else {
+    const backend = policy.verify.backend ?? "local";
+    const inputs = policy.verify.inputs?.length ?? 0;
+    checks.push({
+      id: "verifier",
+      state: backend === "container" ? "OK" : "WARN",
+      detail: backend === "container" ? `isolated-container verifier; budget ${policy.verify.budget}s/stage; ${inputs} declared verify.inputs glob(s); runtime/image availability is checked by verify` : `checkpointed-local verifier; budget ${policy.verify.budget}s/stage; ${inputs} declared verify.inputs glob(s); same-host/self-restoring mutation remains a documented residual`
+    });
+  }
+  checks.push(
+    process.platform === "linux" ? { id: "platform", state: "OK", detail: "Linux: POSIX generated wiring and /proc runtime/quiescence controls are available" } : process.platform === "win32" ? { id: "platform", state: "WARN", detail: "Windows: generated shell wiring has POSIX assumptions and Linux /proc survivor controls are unavailable" } : { id: "platform", state: "WARN", detail: `${process.platform}: POSIX wiring is available, but Linux /proc survivor controls are unavailable` }
+  );
+  return checks;
+}
+function observerCheck(cwd) {
+  const observer = watcherTelemetry(defaultEventLog(cwd));
+  if (observer.state === "healthy" && observer.health) {
+    return {
+      id: "observer",
+      state: "OK",
+      detail: `healthy ${observer.health.backend}; ${observer.health.watched_dirs} watched dir(s), ${observer.health.event_count} event(s); advisory telemetry only`
+    };
+  }
+  if (observer.state === "degraded" && observer.health) {
+    return {
+      id: "observer",
+      state: "WARN",
+      detail: `degraded: ${observer.health.error_count} error(s), ${observer.health.dropped_events} dropped event(s); ${observer.reason ?? "telemetry may be incomplete"}; advisory only`
+    };
+  }
+  return {
+    id: "observer",
+    state: "WARN",
+    detail: `unavailable${observer.reason ? ": " + observer.reason : ""}; optional/advisory, and zero events are not evidence of no transient activity`
+  };
+}
+function emitReport(opts, checks) {
+  const authoritative = !checks.some((x) => x.state === "BROKEN");
+  if (opts.json) {
+    const report2 = { command: "doctor", authoritative, checks };
+    process.stdout.write(JSON.stringify(report2) + "\n");
+    return;
+  }
+  for (const check2 of checks) {
+    if (check2.id === "observer") {
+      process.stdout.write(`tamperward doctor: transient observer: ${check2.detail}
+`);
+    } else {
+      process.stdout.write(`tamperward doctor: [${check2.state}] ${check2.id} \u2014 ${check2.detail}
+`);
+    }
+  }
+}
 function evaluateGitHubProtection(snapshot2, requiredCheck = "tamperward") {
   let hasRequiredCheck = false;
   let hasCodeOwnerReview = false;
@@ -8570,10 +8738,15 @@ function runDoctor(opts = {}) {
   try {
     policy = policyFor(opts, cwd);
   } catch (e) {
-    return err(e instanceof PolicyError || e instanceof Error ? e.message : String(e));
+    return err(
+      e instanceof PolicyError || e instanceof Error ? e.message : String(e),
+      opts,
+      "policy"
+    );
   }
+  const fail = (id, message) => err(message, opts, id, collectLocalPosture(cwd, policy));
   if (!policy.verify?.command) {
-    return err("trusted policy has no verify.command; generated CI cannot verify this repository");
+    return fail("verifier", "trusted policy has no verify.command; generated CI cannot verify this repository");
   }
   const workflowRels = [];
   if (opts.workflow) {
@@ -8582,13 +8755,14 @@ function runDoctor(opts = {}) {
     const workflowDirRel = ".github/workflows";
     const workflowDir = resolve4(cwd, workflowDirRel);
     if (!existsSync10(workflowDir)) {
-      return err(`${workflowDirRel}: workflow directory does not exist`);
+      return fail("ci-verifier", `${workflowDirRel}: workflow directory does not exist`);
     }
     let entries;
     try {
       entries = readdirSync3(workflowDir).filter((name) => /\.ya?ml$/i.test(name)).sort();
     } catch (e) {
-      return err(
+      return fail(
+        "ci-verifier",
         `${workflowDirRel}: could not enumerate workflows (${e instanceof Error ? e.message : String(e)})`
       );
     }
@@ -8600,13 +8774,14 @@ function runDoctor(opts = {}) {
   for (const workflowRel of workflowRels) {
     const workflowPath = resolve4(cwd, workflowRel);
     if (!existsSync10(workflowPath)) {
-      return err(`${workflowRel}: workflow does not exist`);
+      return fail("ci-verifier", `${workflowRel}: workflow does not exist`);
     }
     let doc;
     try {
       doc = parse3(readFileSync13(workflowPath, "utf8"));
     } catch (e) {
-      return err(
+      return fail(
+        "ci-verifier",
         `${workflowRel}: workflow is not valid YAML (${e instanceof Error ? e.message : String(e)})`
       );
     }
@@ -8615,32 +8790,38 @@ function runDoctor(opts = {}) {
     for (const { name, job } of jobs) {
       const timeout = job["timeout-minutes"];
       if (timeout === void 0 || timeout === null) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes is missing; requires at least ${requiredMinutes} minutes`
         );
       }
       if (typeof timeout === "string" && timeout.includes("${{")) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes must be a static numeric value; requires at least ${requiredMinutes} minutes`
         );
       }
       if (typeof timeout !== "number" || !Number.isFinite(timeout)) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes must be numeric; got ${JSON.stringify(timeout)}`
         );
       }
       if (timeout <= 0) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes must be positive; got ${timeout}`
         );
       }
       if (!Number.isInteger(timeout)) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes must be a whole number; got ${timeout}`
         );
       }
       if (timeout < requiredMinutes) {
-        return err(
+        return fail(
+          "ci-verifier",
           `${workflowRel} job "${name}": timeout-minutes ${timeout} is too small; trusted verify.budget ${policy.verify.budget}s requires at least ${requiredMinutes} minutes for visible + pristine + authority overhead`
         );
       }
@@ -8648,47 +8829,48 @@ function runDoctor(opts = {}) {
   }
   if (verifyJobCount === 0) {
     const scope = opts.workflow ?? ".github/workflows/*.yml|*.yaml";
-    return err(`${scope}: no job contains a tamperward verify step`);
+    return fail("ci-verifier", `${scope}: no job contains a tamperward verify step`);
   }
   let github = null;
   if (opts.github) {
     try {
       github = githubAuthority(opts, cwd);
     } catch (e) {
-      return err(e instanceof Error ? e.message : String(e));
+      return fail("github-authority", e instanceof Error ? e.message : String(e));
     }
     if (github.findings.length > 0) {
-      return err(
+      return fail(
+        "github-authority",
         "GitHub repository authority for " + github.repo + "#" + github.branch + " is incomplete: " + github.findings.join("; ")
       );
     }
   }
-  process.stdout.write(
-    `tamperward doctor: CI verifier envelope OK \u2014 ${verifyJobCount} verify job(s), trusted budget ${policy.verify.budget}s/stage, requires >=${requiredMinutes}m outer timeout.
-`
-  );
+  const checks = collectLocalPosture(cwd, policy);
+  checks.push({
+    id: "ci-verifier",
+    state: "OK",
+    detail: `${verifyJobCount} verify job(s); trusted budget ${policy.verify.budget}s/stage requires >=${requiredMinutes}m outer timeout`
+  });
   if (github) {
-    process.stdout.write(
-      "tamperward doctor: GitHub repository authority OK \u2014 " + github.repo + "#" + github.branch + " requires tamperward, Code Owner review, and stale-review dismissal on new pushes.\n"
-    );
+    checks.push({
+      id: "github-authority",
+      state: "OK",
+      detail: github.repo + "#" + github.branch + " requires tamperward status, Code Owner review, and stale-review dismissal on new pushes"
+    });
   }
-  const observer = watcherTelemetry(defaultEventLog(cwd));
-  if (observer.state === "healthy" && observer.health) {
+  checks.push(observerCheck(cwd));
+  if (!opts.json) {
     process.stdout.write(
-      `tamperward doctor: transient observer: healthy \u2014 ${observer.health.backend}, ${observer.health.watched_dirs} watched dir(s), ${observer.health.event_count} event(s); advisory telemetry only, not verification authority.
-`
-    );
-  } else if (observer.state === "degraded" && observer.health) {
-    process.stdout.write(
-      `tamperward doctor: transient observer: degraded \u2014 ${observer.health.error_count} error(s), ${observer.health.dropped_events} dropped event(s); ${observer.reason ?? "telemetry may be incomplete"}. Advisory only; zero events are not evidence of no transient activity.
-`
-    );
-  } else {
-    process.stdout.write(
-      `tamperward doctor: transient observer: unavailable${observer.reason ? " \u2014 " + observer.reason : ""}. Observer telemetry is optional/advisory; zero events are not evidence of no transient activity.
+      `tamperward doctor: CI verifier envelope OK \u2014 ${verifyJobCount} verify job(s), trusted budget ${policy.verify.budget}s/stage, requires >=${requiredMinutes}m outer timeout.
 `
     );
+    if (github) {
+      process.stdout.write(
+        "tamperward doctor: GitHub repository authority OK \u2014 " + github.repo + "#" + github.branch + " requires tamperward, Code Owner review, and stale-review dismissal on new pushes.\n"
+      );
+    }
   }
+  emitReport(opts, checks);
   return 0;
 }
@@ -10852,6 +11034,7 @@ function parseDoctor(args) {
     else if (a === "--base") o.base = args[++i];
     else if (a === "--workflow") o.workflow = args[++i];
     else if (a === "--github") o.github = true;
+    else if (a === "--json") o.json = true;
     else if (a === "--repo") o.repo = args[++i];
     else if (a === "--branch") o.branch = args[++i];
   }
@@ -10981,7 +11164,7 @@ function validateCliArgs(cmd, args) {
   }
   if (cmd === "doctor") {
     return validateFlatArgs(args, {
-      flags: ["--github"],
+      flags: ["--github", "--json"],
       values: {
         "--cwd": "string",
         "--base": "string",
@@ -11068,8 +11251,9 @@ Formats:
                                             every tool the gate must see.
                                             --force-workflow replaces a workflow it
                                             did not write, or one you have edited.
-  tamperward doctor [--base R]              validate the CI verifier's outer-time
-             [--workflow F] [--cwd D]       envelope against the trusted policy.
+  tamperward doctor [--base R]              report installation + authority posture
+             [--workflow F] [--cwd D]       and validate the CI verifier's outer-time
+             [--json]                       envelope against the trusted policy.
              [--github] [--repo O/R]        --github also validates repository
              [--branch B]                   authority: required tamperward status,
                                             Code Owner review, and stale-review

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "The deterministic agent-integrity gate. One ruleset, evaluated on the actual diff/commands as a verdict, enforced everywhere a change can be made.",
   "license": "Apache-2.0",
   "author": "hexrift",