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

tamperward 2.14.1 → 2.15.1

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,26 @@ 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, CI authority 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`.
+**2.15.1 closes an authority-reporting gap in that surface.** The permission check now
+includes job-level overrides, not only workflow-root permissions; a policy schema newer
+than the running binary is BROKEN rather than certifiable; and the exact workflow(s)
+selected by `--workflow` or discovered as verifier authorities are also the workflow(s)
+used for CI-wiring and token-permission posture. A custom verifier workflow therefore
+does not get judged against an unrelated/missing generated file, and a second verifier
+workflow with a write-scoped job cannot hide behind a safe canonical workflow.
+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 +384,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,219 @@ 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 permissionWrites(value) {
+  if (typeof value === "string") {
+    if (/write/i.test(value)) return [value];
+    if (/^(?:read-all|none)$/i.test(value)) return [];
+    return null;
+  }
+  const mapping = asMapping(value);
+  if (!mapping) return null;
+  return Object.entries(mapping).filter(([, permission]) => typeof permission === "string" && /write/i.test(permission)).map(([name, permission]) => `${name}=${String(permission)}`);
+}
+function workflowPermissionCheck(cwd, workflowRels = [".github/workflows/tamperward.yml"]) {
+  const broken = [];
+  const warnings = [];
+  for (const rel of workflowRels) {
+    const path = resolve4(cwd, rel);
+    if (!existsSync10(path)) {
+      broken.push(`${rel} is missing`);
+      continue;
+    }
+    let doc;
+    try {
+      doc = parse3(readFileSync13(path, "utf8"));
+    } catch (e) {
+      broken.push(`${rel} is not valid YAML (${e instanceof Error ? e.message : String(e)})`);
+      continue;
+    }
+    const root = asMapping(doc);
+    if (!root) {
+      broken.push(`${rel} is not a YAML mapping`);
+      continue;
+    }
+    const rootPermissions = root.permissions;
+    if (rootPermissions === void 0) {
+      broken.push(`${rel}: workflow does not declare least-privilege permissions; repository defaults could grant write access`);
+    } else {
+      const writes = permissionWrites(rootPermissions);
+      if (writes === null) {
+        broken.push(`${rel}: workflow permissions shape is unsupported`);
+      } else if (writes.length) {
+        broken.push(`${rel}: workflow grants write permission: ${writes.join(", ")}`);
+      } else {
+        const mapping = asMapping(rootPermissions);
+        if (mapping && mapping.contents !== "read") {
+          warnings.push(`${rel}: workflow permissions contain no writes but contents: read is not declared`);
+        }
+      }
+    }
+    const jobs = asMapping(root.jobs);
+    if (!jobs) continue;
+    for (const [name, rawJob] of Object.entries(jobs)) {
+      const job = asMapping(rawJob);
+      if (!job || job.permissions === void 0) continue;
+      const writes = permissionWrites(job.permissions);
+      if (writes === null) {
+        broken.push(`${rel} job "${name}": permissions shape is unsupported`);
+      } else if (writes.length) {
+        broken.push(`${rel} job "${name}" grants write permission: ${writes.join(", ")}`);
+      }
+    }
+  }
+  if (broken.length) {
+    return {
+      id: "workflow-permissions",
+      state: "BROKEN",
+      detail: broken.join("; ")
+    };
+  }
+  if (warnings.length) {
+    return {
+      id: "workflow-permissions",
+      state: "WARN",
+      detail: warnings.join("; ")
+    };
+  }
+  return {
+    id: "workflow-permissions",
+    state: "OK",
+    detail: `${workflowRels.join(", ")}: workflow/job token permissions contain no write grants and workflow contents access is read-only`
+  };
+}
+function collectLocalPosture(cwd, policy, authorityWorkflows, explicitWorkflow = false) {
+  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: "BROKEN", detail: `policy version ${policy.version} is newer than this binary's schema ${POLICY_VERSION}; authority cannot be certified for unknown policy semantics` }
+  );
+  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);
+  const canonicalWorkflow = ".github/workflows/tamperward.yml";
+  if (authorityWorkflows?.length) {
+    const normalized = authorityWorkflows.map((x) => x.replace(/\\/g, "/"));
+    if (explicitWorkflow) {
+      checks.push({
+        id: "ci-wiring",
+        state: "OK",
+        detail: `explicit verifier authority workflow: ${normalized.join(", ")}; verifier step/timeout validated by doctor`
+      });
+    } else if (normalized.includes(canonicalWorkflow)) {
+      addWiring("ci-wiring", "ci", true);
+    } else {
+      checks.push({
+        id: "ci-wiring",
+        state: "OK",
+        detail: `discovered verifier authority workflow(s): ${normalized.join(", ")}; verifier step/timeout validated by doctor`
+      });
+    }
+  } else {
+    addWiring("ci-wiring", "ci", true);
+  }
+  addWiring("codeowners", "codeowners", true);
+  checks.push(workflowPermissionCheck(cwd, authorityWorkflows));
+  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 +8796,21 @@ 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"
+    );
   }
+  let postureWorkflows = opts.workflow ? [opts.workflow] : void 0;
+  const fail = (id, message) => err(
+    message,
+    opts,
+    id,
+    collectLocalPosture(cwd, policy, postureWorkflows, Boolean(opts.workflow))
+  );
   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 +8819,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)})`
       );
     }
@@ -8597,50 +8835,62 @@ function runDoctor(opts = {}) {
   const requiredSecs = requiredVerifierAuthoritySeconds(policy.verify.budget);
   const requiredMinutes = Math.ceil(requiredSecs / 60);
   let verifyJobCount = 0;
+  const authorityWorkflows = [];
   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)})`
       );
     }
     const jobs = verifyJobs(doc);
     verifyJobCount += jobs.length;
+    if (jobs.length > 0) {
+      authorityWorkflows.push(workflowRel);
+      postureWorkflows = [...authorityWorkflows];
+    }
     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 +8898,53 @@ 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,
+    authorityWorkflows,
+    Boolean(opts.workflow)
   );
+  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) {
-    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 {
+  checks.push(observerCheck(cwd));
+  if (!opts.json) {
     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 +11108,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 +11238,7 @@ function validateCliArgs(cmd, args) {
   }
   if (cmd === "doctor") {
     return validateFlatArgs(args, {
-      flags: ["--github"],
+      flags: ["--github", "--json"],
       values: {
         "--cwd": "string",
         "--base": "string",
@@ -11068,8 +11325,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.1",
   "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",