tamperward 2.12.0 → 2.13.0

package/README.md

@@ -254,13 +254,26 @@ CI workflow that runs both the diff-time check and pristine verification, and a
 `CODEOWNERS` requirement on the paths that decide whether the gate runs at all.
 It never overwrites anything you wrote; `--dry-run` prints the plan.
 
-**`init` is not sufficient on its own, and it will tell you so.** In your
-branch-protection or ruleset settings you must require the check *and* enable
-"Require review from Code Owners". A `pull_request` workflow runs from the pull
-request's own head and a required check is matched by job name, so without that
-a PR can keep the job name, replace the gate with `true`, and present a green
-required check over a change the gate would have blocked. That is reproduced on
-this project's own CI, not a theoretical concern.
+**`init` is not sufficient on its own, and it will tell you so.** The protected
+branch needs all three repository-authority controls:
+
+1. require the **`tamperward`** status check;
+2. enable **Require review from Code Owners**; and
+3. enable **Dismiss stale pull request approvals when new commits are pushed**.
+
+The third control is load-bearing: an approval for an older gate-critical diff must
+not authorize a later push. GitHub's "require approval of the most recent reviewable
+push" can be useful in addition, but it is not equivalent here because that fresh
+approver is not necessarily the Code Owner for the gate path. A `pull_request`
+workflow runs from the pull request's own head and a required check is matched by job
+name, so without this human boundary a PR can keep the job name, replace the gate with
+`true`, and present a green required check over a change the gate would have blocked.
+That is reproduced on this project's own CI, not a theoretical concern.
+
+After configuring GitHub, verify the boundary with
+`tamperward doctor --github --repo OWNER/REPO --branch <default-branch>`.
+Public rulesets can be read anonymously; set `GH_TOKEN` or `GITHUB_TOKEN` when
+authentication is required.
 
 A real deployment needs a verify command configured — the generated CI verify step
 **fails closed (exit 2) without one** rather than passing quietly. In

package/dist/cli/index.js

@@ -8221,12 +8221,13 @@ tamperward init: ${changed} change(s) applied. Commit them so the gate travels w
 `
   );
   w.write(
-    '\nONE STEP LEFT, AND IT IS NOT OPTIONAL. In your branch-protection or ruleset\nsettings for the default branch, require the tamperward check AND enable\n"Require review from Code Owners".\n\nUntil you do, the CI gate is advisory. A pull request runs the workflow from\nits OWN head, and a required check is matched by job name \u2014 so a pull request\ncan keep the job called `tamperward`, replace the gate with `true`, and present\na green required check over a change the gate would have blocked. That is\nreproduced, not theoretical. CODEOWNERS is what puts a human in front of it;\nbranch protection is what makes CODEOWNERS bind.\n'
+    '\nONE STEP LEFT, AND IT IS NOT OPTIONAL. In your branch-protection or ruleset\nsettings for the default branch, configure ALL THREE repository-authority controls:\n  1. require the tamperward check;\n  2. enable "Require review from Code Owners"; and\n  3. enable "Dismiss stale pull request approvals when new commits are pushed".\n\nThe freshness control is part of the security boundary: an approval for an older\ngate-critical diff must not authorize a later push. "Require approval of the most\nrecent reviewable push" can be useful in addition, but is not a substitute here\nbecause the fresh approver is not necessarily the Code Owner for the gate path.\n\nUntil all three are enforced, the CI gate is advisory. A pull request runs the\nworkflow from its OWN head, and a required check is matched by job name \u2014 so a\npull request can keep the job called `tamperward`, replace the gate with `true`,\nand present a green required check over a change the gate would have blocked.\nCODEOWNERS puts a human in front of gate-critical paths; branch protection or an\nactive ruleset makes that review fresh and binding. Verify with: tamperward doctor\n--github --repo OWNER/REPO --branch <default-branch>.\n'
   );
   return 0;
 }
 
 // src/cli/doctor.ts
+import { execFileSync as execFileSync7 } from "node:child_process";
 import { existsSync as existsSync10, readFileSync as readFileSync13, readdirSync as readdirSync3 } from "node:fs";
 import { join as join13, resolve as resolve4 } from "node:path";
 import { parse as parse3 } from "yaml";
@@ -8244,6 +8245,166 @@ function policyFor(opts, cwd) {
 function asMapping(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
+function evaluateGitHubProtection(snapshot2, requiredCheck = "tamperward") {
+  let hasRequiredCheck = false;
+  let hasCodeOwnerReview = false;
+  let dismissesStaleReviews = false;
+  if (Array.isArray(snapshot2.rules)) {
+    for (const raw of snapshot2.rules) {
+      const rule = asMapping(raw);
+      const params = asMapping(rule?.parameters);
+      if (!rule || !params) continue;
+      if (rule.type === "pull_request") {
+        if (params.require_code_owner_review === true) hasCodeOwnerReview = true;
+        if (params.dismiss_stale_reviews_on_push === true) dismissesStaleReviews = true;
+      }
+      if (rule.type === "required_status_checks") {
+        const checks = params.required_status_checks;
+        if (Array.isArray(checks)) {
+          hasRequiredCheck ||= checks.some((rawCheck) => {
+            const check2 = asMapping(rawCheck);
+            return check2?.context === requiredCheck;
+          });
+        }
+      }
+    }
+  }
+  const classic = asMapping(snapshot2.branchProtection);
+  const reviews = asMapping(classic?.required_pull_request_reviews);
+  if (reviews?.require_code_owner_reviews === true) hasCodeOwnerReview = true;
+  if (reviews?.dismiss_stale_reviews === true) dismissesStaleReviews = true;
+  const status = asMapping(classic?.required_status_checks);
+  if (status) {
+    const contexts = status.contexts;
+    if (Array.isArray(contexts)) {
+      hasRequiredCheck ||= contexts.some((x) => x === requiredCheck);
+    }
+    const checks = status.checks;
+    if (Array.isArray(checks)) {
+      hasRequiredCheck ||= checks.some((rawCheck) => {
+        const check2 = asMapping(rawCheck);
+        return check2?.context === requiredCheck;
+      });
+    }
+  }
+  const findings = [];
+  if (!hasRequiredCheck) findings.push("require the tamperward status check");
+  if (!hasCodeOwnerReview) findings.push("require Code Owner review");
+  if (!dismissesStaleReviews) findings.push("dismiss stale pull request approvals on new pushes");
+  return findings;
+}
+function gitText(cwd, args) {
+  try {
+    return execFileSync7("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function githubRepoFromRemote(remote) {
+  const m = remote.match(/github\.com(?::|\/)([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i);
+  return m ? m[1] + "/" + m[2].replace(/\.git$/i, "") : null;
+}
+function inferGitHubRepo(cwd) {
+  const envRepo = process.env.GITHUB_REPOSITORY;
+  if (envRepo && /^[^/\s]+\/[^/\s]+$/.test(envRepo)) return envRepo;
+  const remote = gitText(cwd, ["config", "--get", "remote.origin.url"]);
+  return remote ? githubRepoFromRemote(remote) : null;
+}
+var GITHUB_API_SCRIPT = [
+  "const endpoint = process.argv[1];",
+  "const token = process.env.TAMPERWARD_GITHUB_TOKEN || '';",
+  "const headers = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2026-03-10', 'User-Agent': 'tamperward-doctor' };",
+  "if (token) headers.Authorization = 'Bearer ' + token;",
+  "fetch('https://api.github.com/' + endpoint, { headers }).then(async (r) => {",
+  "  const body = await r.text();",
+  "  if (!r.ok) { process.stderr.write('HTTP ' + r.status + ': ' + body); process.exit(22); }",
+  "  process.stdout.write(body);",
+  "}).catch((e) => { process.stderr.write(String(e)); process.exit(23); });"
+].join("\n");
+function githubApiInvocation(endpoint, token) {
+  return {
+    executable: process.execPath,
+    args: ["-e", GITHUB_API_SCRIPT, endpoint],
+    env: {
+      TAMPERWARD_GITHUB_TOKEN: token,
+      LANG: "C",
+      LC_ALL: "C"
+    }
+  };
+}
+function githubApi(cwd, endpoint) {
+  const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? "";
+  const invocation = githubApiInvocation(endpoint, token);
+  try {
+    const stdout = execFileSync7(
+      invocation.executable,
+      invocation.args,
+      {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: invocation.env,
+        timeout: 15e3
+      }
+    );
+    return JSON.parse(stdout);
+  } catch (e) {
+    const x = e;
+    const detail = x.stderr ? String(x.stderr).replace(/\s+/g, " ").trim() : x.message;
+    throw new Error(
+      "GitHub API " + endpoint + " failed: " + (detail || "unknown error")
+    );
+  }
+}
+function githubAuthority(opts, cwd) {
+  const repo = opts.repo ?? inferGitHubRepo(cwd);
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+    throw new Error(
+      "cannot determine GitHub repository; pass --repo OWNER/REPO or configure a github.com origin"
+    );
+  }
+  let branch = opts.branch ?? process.env.GITHUB_BASE_REF ?? "";
+  if (!branch) {
+    const meta2 = asMapping(githubApi(cwd, "repos/" + repo));
+    if (typeof meta2?.default_branch === "string") branch = meta2.default_branch;
+  }
+  if (!branch) throw new Error("cannot determine protected branch; pass --branch BRANCH");
+  let rules;
+  let rulesError = null;
+  try {
+    rules = githubApi(cwd, "repos/" + repo + "/rules/branches/" + encodeURIComponent(branch));
+  } catch (e) {
+    rulesError = e instanceof Error ? e : new Error(String(e));
+  }
+  let findings = evaluateGitHubProtection({ rules });
+  if (findings.length === 0) return { repo, branch, findings };
+  let branchProtection;
+  let classicError = null;
+  try {
+    branchProtection = githubApi(
+      cwd,
+      "repos/" + repo + "/branches/" + encodeURIComponent(branch) + "/protection"
+    );
+  } catch (e) {
+    classicError = e instanceof Error ? e : new Error(String(e));
+  }
+  findings = evaluateGitHubProtection({ rules, branchProtection });
+  if (findings.length > 0 && rules === void 0 && branchProtection === void 0) {
+    throw new Error(
+      "cannot inspect GitHub repository authority. Rules API: " + (rulesError?.message ?? "unavailable") + ". Classic branch protection API: " + (classicError?.message ?? "unavailable") + ". Authenticate gh with metadata read; classic-protection fallback may also need Administration read."
+    );
+  }
+  if (findings.length > 0 && branchProtection === void 0 && classicError) {
+    findings.push(
+      "classic branch protection could not be inspected; if it supplies a missing requirement, use GH_TOKEN/GITHUB_TOKEN with Administration read"
+    );
+  }
+  return { repo, branch, findings };
+}
 function verifyJobs(doc) {
   const root = asMapping(doc);
   const jobs = asMapping(root?.jobs);
@@ -8346,25 +8507,43 @@ function runDoctor(opts = {}) {
     const scope = opts.workflow ?? ".github/workflows/*.yml|*.yaml";
     return err(`${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));
+    }
+    if (github.findings.length > 0) {
+      return err(
+        "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.
 `
   );
+  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"
+    );
+  }
   return 0;
 }
 
 // src/cli/verify.ts
-import { execFileSync as execFileSync8, spawnSync as spawnSync2 } from "node:child_process";
+import { execFileSync as execFileSync9, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
 import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync4, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname7, isAbsolute as isAbsolute10, join as join16, relative as relative5, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/fingerprint.ts
-import { execFileSync as execFileSync7 } from "node:child_process";
+import { execFileSync as execFileSync8 } from "node:child_process";
 import { createHash as createHash7 } from "node:crypto";
 function treeFingerprint(cwd, keepIgnored) {
-  const listed = execFileSync7("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+  const listed = execFileSync8("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
     cwd,
     encoding: "utf8",
     maxBuffer: 1 << 28,
@@ -9271,7 +9450,7 @@ var VERIFICATION_SURFACE = [
   "**/*.runsettings"
 ];
 function git2(args, cwd) {
-  return execFileSync8("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
+  return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
 function resolveBase(base, cwd) {
   assertRev(base);
@@ -9467,7 +9646,7 @@ function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
     if (e.type === "commit") {
       throw new Error(`the base's ${e.path} is a submodule; the pristine copy cannot reproduce it`);
     }
-    const content = execFileSync8("git", ["show", `${base}:${e.path}`], { cwd, maxBuffer: 1 << 28, env: trustedGitEnv() });
+    const content = execFileSync9("git", ["show", `${base}:${e.path}`], { cwd, maxBuffer: 1 << 28, env: trustedGitEnv() });
     const out2 = join16(dest, e.path);
     mkdirSync6(dirname7(out2), { recursive: true });
     rmSync3(out2, { force: true });
@@ -9856,7 +10035,7 @@ function parseVerify(args) {
 }
 
 // src/cli/run.ts
-import { execFileSync as execFileSync9, spawnSync as spawnSync3 } from "node:child_process";
+import { execFileSync as execFileSync10, spawnSync as spawnSync3 } from "node:child_process";
 import { mkdtempSync as mkdtempSync3, readdirSync as readdirSync5, readFileSync as readFileSync17, readlinkSync as readlinkSync4, realpathSync as realpathSync6, rmSync as rmSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join17, resolve as resolve8 } from "node:path";
@@ -10079,7 +10258,7 @@ function runAgentWithBudget(argv2, cwd, budgetSecs) {
   }
 }
 function git3(args, cwd) {
-  return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
+  return execFileSync10("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
 function nowTicks() {
   try {
@@ -10276,7 +10455,7 @@ tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMEN
   });
   if (opts.settle && opts.settle > 0) {
     try {
-      execFileSync9("sleep", [String(opts.settle)]);
+      execFileSync10("sleep", [String(opts.settle)]);
     } catch {
     }
   }
@@ -10372,6 +10551,9 @@ function parseDoctor(args) {
     if (a === "--cwd") o.cwd = args[++i];
     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 === "--repo") o.repo = args[++i];
+    else if (a === "--branch") o.branch = args[++i];
   }
   return o;
 }
@@ -10451,9 +10633,12 @@ Formats:
                                             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.
-                                            Generated PR CI passes the base SHA so
-                                            candidate policy edits cannot choose
-                                            their own timing requirement.
+             [--github] [--repo O/R]        --github also validates repository
+             [--branch B]                   authority: required tamperward status,
+                                            Code Owner review, and stale-review
+                                            dismissal after new pushes. Public
+                                            rules can be read anonymously; set
+                                            GH_TOKEN/GITHUB_TOKEN when needed.
 
 Exit codes: 0 clean \xB7 1 a blocking finding (check), MASKED_FAILURE or SUITE_RED
             (verify), any blocking finding or masked failure (run) \xB7 2 cannot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.12.0",
+  "version": "2.13.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",