notari

Notari issues a signed Change Passport for every AI-authored pull request: a receipt any reviewer or auditor can re-verify from the signature alone, without re-running Notari or trusting a screenshot, recording which files a human approved the agent to touch and whether it stayed inside them. A human signs the boundary once; in CI, Notari checks each pull request against it and stamps the passport PASS, NEEDS_REVIEW, or BLOCK. There is no model in that verdict, so it cannot be prompt-injected. It does not judge whether the code is correct: it attests to where the change went and whether it leaked a secret, the part a human most often skims past on a large agent PR. Alpha; treat the security model as the source of truth over any one-line claim.

Start here: one command

uvx notari init

Nothing to install first. In one command, inside any git repo, that generates an approver keypair and a gate keypair, signs a secure-by-default perimeter, writes the hardened GitHub workflow (pull_request_target, SHA-pinned, the pull request checked out into a data-only directory), gitignores your private keys, and then prints your honest posture plus the exact steps still missing. Measured from a clean machine with no Python tooling configured, the CLI resolves and runs in about a second and a half.

Prefer a persistent install? pipx install notari or pip install notari, then notari init. Either way the next two commands are the whole daily loop:

notari begin "add rate limiting" --scope "src/api/**"    # sign what the agent may touch
notari verify --strict                                    # in CI: PASS, NEEDS_REVIEW, or BLOCK

notari init automatically forbids directories that look sensitive (auth, migrations, infra, terraform, deploy, and similar). Forbidden beats contract scope, so scoping a task into one of them returns BLOCK by design. When you really do need to touch one, set the boundary explicitly and sign it: notari guard --key approver.pem --allow "src/**" --forbid "migrations/**".

What you actually get

Four surfaces, each stated at its real strength rather than its most flattering one:

1. The gate, which is the provable boundary. In CI, outside the agent's reach, every changed path outside .notari/ is measured against a signed scope and a signed perimeter, each touched file is scanned for 26 vendor secret patterns, and renames (both endpoints), mode-only changes, binaries, symlinks, submodules, and .gitattributes diff-hiding are all in the inventory rather than blind spots. You name the scope per task (--scope), so a narrow scope means "only these paths", and the explicit --scope '**' means "anything the signed perimeter does not forbid", stated plainly on the passport either way so a PASS is never ambiguous. Secret detection is a finite pattern set, so it catches the common vendor-format leaks rather than proving no secret exists. There is no model in the decision path, so there is nothing to prompt-inject.

2. The receipt, which outlives the run. A Change Passport (passport.json plus a PR-ready passport.md) whose Ed25519 signature anyone can re-check later with notari verify-passport, months on, on a different machine, so a forged or tampered verdict fails and you trust the signed receipt rather than a screenshot. This checks that the gate genuinely issued this verdict, not that the code is correct, and it does not re-run the gate. Behind it sits an HMAC-chained audit log that detects edits and insertions cryptographically, and trailing truncation against a sealed high-water-mark once notari audit verify has run; the passport's footer cites the exact chain entry for its run.

3. The remediation path, so a BLOCK is actionable. notari explain turns a BLOCK into a per-finding fix and a paste-ready agent prompt, and notari agent-brief hands the next agent its approved scope before it starts. All local, all human-gated, no telemetry, and no raw code, diffs, or secret values ever leave your machine.

4. The guard on your laptop, which is defense-in-depth and not a hard boundary. An optional PreToolUse hook gates the agent's tool calls as they happen (rm -rf, git push --force, DROP TABLE, vercel --prod, .env reads), critical calls need a single-use ten-minute approval that on macOS is hardware-attested through Touch ID on the Secure Enclave, and files the agent writes get an AST pass that flags shutil.rmtree and exec(b64decode(...)) before a later python foo.py can run them.

That fourth row is deliberately labelled: an application-layer gate can be routed around by a determined adversary, and the limits are enumerated in the security model rather than buried. The boundary that holds is the CI one.

New here? Start with the Quickstart (zero to a blocked bad PR in ~10 minutes). Then: Security & threat model · Product & tiers.

Found a bypass, a confusing error, or a reason you'd never adopt this? That is exactly the feedback this alpha exists for: open an issue.

Want to attack it first? bash examples/bypass_probes.sh runs twelve bypass shapes against a freshly signed perimeter and prints the verdict for each: rename into a forbidden path, mode-only change, case variant, a secret hidden behind a .gitattributes -diff entry, an agent widening its own signed contract, and more. Eleven BLOCK; the twelfth is the documented line-split secret limit. A thirteenth shape that earns an undeserved PASS is the single most useful thing you can send.

An AI agent opens a pull request. Which files was it not approved to touch? On a 40-file agent diff that is the question a human skims past, and it is the one Notari answers, at the merge boundary in CI, with a signed Change Passport a reviewer can re-verify instead of trusting a screenshot. The verdict is a deterministic function of the diff, the signed contract, and the policy, so there is no model in it to jailbreak. It records where the change went and whether it leaked a secret; it does not prove the in-scope code is correct or free of a backdoor. That is the honest scope.

An agent edits in and out of scope, and Notari verifies each diff (PASS / NEEDS_REVIEW / BLOCK) against the signed contract (from examples/change_control_demo.sh, unedited):

# 0. one-time: create a human approver key. Keep the PRIVATE half off the build
#    box; pin the PUBLIC half so a PR cannot edit the trust root (in CI this is a
#    repo/org secret or variable, NOT a path inside the checkout).
notari keygen --out approver.pem
export NOTARI_APPROVER_PUBKEYS="$(cat approver.pem.pub)"

# 1. sign the standing boundary ONCE: what agents may touch, what is off-limits.
notari guard --key approver.pem --allow "src/**" --forbid "migrations/**"

# 2. capture AND SIGN the approved task (a signed contract can't be forged by the agent).
notari begin "Add rate-limiting to the login endpoint" --scope "src/auth/**" --key approver.pem
#    commit .notari/{perimeter.json,perimeter.sig,contract.json,contract.sig} to the BASE branch.

# 3. the agent writes the diff and opens the PR.

# 4. CI verifies the PR against the signed boundary, in strict mode.
notari verify --strict        # PASS · NEEDS_REVIEW · BLOCK   (BLOCK fails the build)
#    add --sign-key gate.pem (or NOTARI_GATE_KEY in CI) to ALSO sign the verdict,
#    so a reviewer can re-check it with `notari verify-passport`.