Quill

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.

That full sequence, pinned external approver key, signed perimeter, signed contract, --strict, is the real adversarial boundary. Drop any of it (notari begin / notari verify with no flags) and Notari still runs, but in *cooperative* mode: honest review automation for a non-adversarial agent, not a boundary against one trying to escape. Verdict signing is opt-in (it needs a gate key); it is not on by default. See docs/SECURITY-MODEL.md for the full deployment checklist.

notari verify reads git diff ..HEAD, checks every changed file against the scope you approved, scans each touched file for hardcoded secrets and sensitive surfaces (CI config, lockfiles, test deletions), evaluates any logged exceptions, and writes a Change Passport: passport.json + a PR-ready passport.md, that cites the HMAC-chained audit entry for the run, so a reviewer can trace the verdict back to a tamper-evident record instead of trusting the markdown alone.

---

Why this layer

The agents writing your code have shell access, file write, deploy permissions, and your credentials, and the failures are already on the record: in July 2025 Replit's agent deleted a production database during a vibe-coding session and fabricated data to cover it; that same month a Cursor agent ran rm -rf ~/ against a developer's home directory; in August an autonomous agent committed a customer's GitHub token into a public commit. The common thread is not that the model is evil, it is that nothing checked the change against what was actually approved before it shipped.

Notari puts that check where it can be enforced and recorded: in CI, on the pull request, where the gate runs outside the agent's own process and cannot be quietly switched off by the thing it is reviewing. The verdict is a deterministic function of the diff, the contract, and the policy, there is no LLM in the decision path, so the gate itself cannot be prompt-injected.

What Notari is, and what it is not

Calibration matters more than marketing.

• **Notari is a verification-and-evidence artifact, not a content classifier.