Pacioli — the governed front door to your ERPNext books

Least-privilege governance for ERPNext, and a governed agent front door built on top of it — MCP and A2A, one spine behind both. A door admits; it never decides.

In 1494, in Venice, Luca Pacioli printed the Summa de arithmetica — and inside it, the tract that taught the world double-entry bookkeeping. He wrote it down not because merchants couldn't count, but because they couldn't trust. His rule is one sentence deep: no debit without a credit. Every action gets an equal, opposite, recorded counterpart — and a book that doesn't balance confesses on the spot. Five hundred years of prove it or it didn't happen.

This repo is that tract, written again for a new clerk. The merchant's problem hasn't changed; the clerk has. He balanced books for merchants who couldn't watch every clerk. This balances them for owners who can't watch every agent. Same problem, five centuries apart. Same fix.

See it before you read the rest: the demo. One command on a bare pip install pacioli pacioli-guard shows the floor deciding, and a sealed receipt that will not be quietly rewritten. Every verdict is the shipped code; nothing is staged.

Tavola I — The friar at his slate, attributed to Jacopo de' Barbari, 1495. The glass rhombicuboctahedron hangs at his left; the Summa sits under the dodecahedron at his right. This repo's device is that hanging solid.

Distinctio I — Of the Two Instruments

There are two instruments in this house, and they compose — they do not couple. The first guards every api-key credential on the site whether an agent is involved or not; the second is the one governed door an agent may use. The first is the floor under that door; the second stands on it and submits to it. What follows is each instrument as the treatise would have it: what it is, what it refuses, and how it is installed.

What the floor covers, plainly, because a floor that overstates itself is not a floor. Two questions, two of frappe's own public hooks, each at the altitude where its question is legible.

Which credential is acting, and what may it call? The credential gate rides auth_hooks, which runs when an api-key credential authenticates. It governs token/Basic api-key requests across every REST mount, and it does not govern OAuth2 Bearer tokens, desk/cookie sessions, background jobs, the scheduler, server scripts, or the bench console. "Which credential is this" only exists at authentication time, so this gate can only live here, and that boundary is inherent to it.

Was this act consented? That is a property of a document, so it is enforced on the document, via doc_events on before_submit and before_cancel, plus before_gl_preview and before_sl_preview since guard 0.13.0. The last two gate a rehearsal of a posting rather than a posting: ERPNext previews a ledger by performing it and rolling the transaction back, so previewing a submit requires the same marker the submit requires, and does not spend it. Every path that posts to the ledger through the ORM passes it: REST, run_doc_method, frappe.client.submit, frappe.client.insert with a submitted body, the desk Save/Submit endpoint, bulk submit, a raw docstatus field write followed by a save, a background job, a server script, and the bench console. Consent does not inherit the credential gate's transport boundary.

What still walks around both, stated up front rather than discovered later:

1. A write that skips the document lifecycle entirely: raw SQL, and db_update/db_set-style field writes. ERPNext core does this itself when reposting.
2. An actor who can break the grant read. The consent handler runs on every document on the site, so if reading the grant raises it returns rather than throwing — a wildcard handler that crashes takes the site with it. A deliberate trade, and a real residual.
3. Document.discard. It is whitelisted, so it is reachable, and it sets docstatus = 2 with db_set while firing before_discard rather than before_cancel. It refuses anything that is not a draft, so no ledger entry is ever reversed by it and nothing posts — the exposure is a draft being taken out of play, not books moving. Gating it wants its own act type rather than being folded into "cancel", since consenting to reverse a posted entry and consenting to abandon a draft are different permissions. Named here rather than rounded off.

No single frappe extension point covers all of it, so coverage here is a composition with a stated residual rather than a claim of totality, which is a thing the platform cannot give anyone.

The Guard — the counting-house door

No one writes in the books but the appointed hand, and only in the books appointed to them.

A Frappe/ERPNext bench app (distribution name pacioli-guard on PyPI; installs as the pacioli_guard bench app). It binds any API credential — an integration, a Zapier/n8n flow, a script, a vendor token, a cron job, an AI agent — to an allowlist of methods (and, if granted, DocTypes), enforced at the credential layer through Frappe's public auth_hooks extension point, deny-by-default. No core fork. It governs every api-key credential on the site, agent or not — see the coverage note above for what that does and does not reach, and for the separate document-layer gate that carries consent.

# from your bench directory: wheel into the bench env, then install the app
env/bin/pip install pacioli-guard
bench --site <your-site> install-app pacioli_guard

The Broker — hand it the books

The clerk may propose; only the merchant disposes.

A standalone, pip-installable broker (pip install pacioli) that gives an AI agent a governed way to touch ERPNext — through the door of your choosing: MCP or A2A, one spine behind both. 51 governed doctypes, 265 tools — the full submittable transaction surface of an ERPNext company — every write through PLAN → CONSENT → execute → PROVE, deny-by-default beyond that. The door admits; the spine decides.

pip install pacioli

How the instruments compose

Guard is the floor; the broker is one consumer that binds itself to it. Guard scopes and enforces any credential on the site — you don't need to run an agent to need it. The broker is the agent-facing front door, and its own ERPNext credential must itself be pacioli_guard-scoped to exactly the calls it makes (the governed doctypes and their submit/cancel vectors — shipped as data lists the deploy kit applies). Without that scoping, anything holding the broker's raw credential can call ERPNext's REST API directly and bypass PLAN, CONSENT, and PROVE entirely — so the broker's own README states that scoping as a hard precondition, not an optional hardening step.

And scoping alone is not sufficient — this was proven against a live bench on 2026-07-25, and it is worth stating plainly rather than leaving as an inference. The broker must be allowed to submit invoices, because submitting invoices is what the broker is for. So its credential is allowed to submit invoices, and a direct run_doc_method call holding that credential submitted one with no plan, no marker and no receipt. The ledger moved. The guard behaved exactly as designed and the allowlist was exactly right: no allowlist can close this, because the call being made is the call the broker exists to make. Possession of the key was permission to post.

The guard closes it at the floor rather than in the broker: API Key Scope.require_consent (opt-in, off by default) refuses a docstatus-changing act unless it carries a live, single-use Pacioli Consent Marker minted for that exact document and that exact act, and spends the marker on use. Consent to post is not consent to reverse: cancel moves the same document and writes the opposite GL entries, so a submit marker never spends on a cancel. And the marker must be written by a different principal than the credential it authorises — the floor compares the minter against the caller and refuses a match, because a credential that can mint its own consent is a gate writing its own permission slip. minted_by is set by the server from the authenticated session, overwriting anything the caller supplies, so that separation is established rather than self-reported.

This gate is enforced on the document, not on the request: doc_events before_submit / before_cancel, and since guard 0.13.0 before_gl_preview / before_sl_preview as well. That is deliberate and it is the difference between governing one door and governing the act. A credential holder who avoids the api-key REST path entirely, via an OAuth token, a desk session, a background job, a server script or the bench console, still meets this gate.