tamperward weekly downloads statistics

<p align="center"> <img src="assets/logo.png" width="76" height="76" alt=""> </p> <h1 align="center">Tamperward</h1> <p align="center"><em>A ward is the obstruction inside a lock that blocks the wrong key.</em></p> <p align="center"> <a href="https://www.npmjs.com/package/tamperward"><img src="https://img.shields.io/npm/v/tamperward?label=npm&color=4F46E5" alt="npm version"></a> <a href="https://github.com/hexrift/tamperward/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/hexrift/tamperward/release.yml?label=release" alt="release"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey" alt="license"></a> </p>

Quick start · Docs & guide · See the evidence → — every round, study and correction in one place, each number bound to its committed artifact · The research series — every registered prediction published beside its outcome

What it is

Coding agents can modify both the implementation and the tests, configuration, CI, hooks and verifier used to judge that implementation — and in observed trajectories, some modify or attempt to modify verification in ways that can turn incorrect work into apparent success. Under pressure, the cheaper route to green is sometimes to weaken the checks instead of fixing the failure.

In plain English: Tamperward lets a coding agent change your code, but not the trusted starting point, the rules, or the checks used to judge that code.

Tamperward is a deterministic verification-integrity layer. It blocks known weakening moves as they happen, observes protected-state effects, and independently re-adjudicates apparent success outside the agent's normal completion path. No runtime LLM judge. It fails closed when adjudication is impossible.

Project status: active research release. Tamperward is usable today, but its enforcement architecture and supporting evidence are still being tested and hardened. Use it as one layer of defence in depth alongside protected CI, independent tests and human review. Findings, limitations and corrections are published openly. The 2.0 major marks the Node 18 drop, not a declaration of security maturity; the distance to that is tracked, milestone by milestone, in SPEC §9.1.

Quick start

npx tamperward onboard

Requires Node.js 20.19 or later. JavaScript and TypeScript are the fully supported detector surface; the other documented ecosystems get file-level and pattern-based protection.

onboard is the guided first run: it previews the installation, explains each enforcement point, asks before writing anything, runs the canonical init, offers the detected suite command for your explicit acceptance, runs and explains the first verify, offers a safe demonstration of a weakening move on a disposable worktree, checks the GitHub controls, and ends with a READY / READY WITH WARNINGS / BROKEN / INCOMPLETE posture. The deterministic primitive underneath is npx tamperward init — one idempotent command that wires the policy, the agent hooks, the pre-commit hook, a CI workflow running both the diff-time check and pristine verification, and a CODEOWNERS requirement on the paths that decide whether the gate runs. It never overwrites anything you wrote; --dry-run prints the plan.

A real deployment needs a verify command configured — the generated CI verify step fails closed (exit 2) without one. In .tamperward.yml:

verify:
  command: npm test
  budget: 300
  inputs: ['scripts/**']   # files the command DELEGATES to
  # Optional stronger final-verification boundary:
  # backend: container
  # image: ghcr.io/acme/verifier@sha256:<64-hex-digest>

That block is itself a guarded surface: changing the command, lowering the budget, narrowing inputs, removing backend: container, or changing its pinned image is flagged as policy weakening. The four primitives:

npx tamperward check --staged                # pre-commit view
npx tamperward check --diff "main...HEAD"    # CI view over the PR's commit range
npx tamperward verify --base main            # pristine-suite re-execution
npx tamperward run --agent-budget 1800 -- <agent command...>  # optional agent-runtime bound

Full flags, exit codes, verifier configuration and the trace-verify advisory tool are in the getting-started guide.

Choose your path

Goal	Destination
Install TamperWard	Quick start (this README)
Configure authoritative CI	Enforcement guide
Understand the architecture	Architecture reference
Browse detectors and rules	Rules guide
Evaluate a model	Research guide
Inspect published evidence	Research overview
Contribute code	Development

Architecture

The agent may produce the work, but it must not control how that work is judged. Tamperward separates steering from adjudication. In-loop hooks steer the agent while it works — denying known weakening operations and detecting protected-tree drift — but they are not the final authority. After the agent exits, tamperward run independently judges the tree it left behind: "visible" verification runs the candidate as it stands; "pristine" verification restores the protected verification state from the trusted base and runs the checks again. Visible green followed by pristine red is a masked failure.

Core invariant: the agent may author the candidate tree, but it must not choose the trusted baseline, the governing policy, the verifier, or the final verdict.…