Documentation

Heron

A vendor platform calls Heron before every agent tool call, and afterwards sends a signed statement of what it actually executed. Heron signs its own decision, chains it into the session, pairs the two statements, and publishes an evidence page a security reviewer can check without trusting our server.

Heron enforces.Every before-action call is judged against the vendor’s published policy and answered with the real verdict — ALLOW, DENY or STEP_UP — which the vendor honours before it executes. It fails closed, with an audited break-glass switch for incidents.

Which reader are you?

I am integrating a platform →Two calls, one signing key, twenty minutes. The hook before the tool call, the signed statement after it, and what happens when we are unreachable.I was handed an evidence link →How to read the page, how to verify a signature in your own browser, and — just as important — what the page does not prove.What is this AARM thing? →The specification the evidence page answers: nine requirements, what each one asks for, and why a green badge from us is not a certification.

The model, in five sentences

  1. The vendor opens a session for an agent run and calls POST /v1/actions before each tool call.
  2. Heron returns a decision — the real verdict, ALLOW · DENY · STEP_UP, judged against the project’s published policy — signed with Ed25519, and links the action into a hash chain.
  3. The tool executes if the decision allowed it. The vendor then posts execution evidence: what it did, signed with its own key, whose private half Heron never holds.
  4. A worker reconciles the two statements and raises an anomaly when they disagree — a decision with no execution, an execution with no decision, a signature that does not check out, a chain that no longer recomputes.
  5. Everything provable is published on an evidence page, which carries hashes, verdicts and signatures — and no user data.

Why two signatures instead of one

A log the vendor writes about itself proves nothing to a stranger, and neither does a log we write about them. So there are two independent statements for every action: ours (what we decided, signed with our key) and theirs (what they executed, signed with theirs). The product is the comparison between them, and neither side can quietly change its half after the fact.

The reviewer does not have to take our word for any of it: our public keys are published at /.well-known/heron-jwks.json, the signed bytes are the RFC 8785 canonical form of the payloads shown on the page, and the check runs in the reviewer’s browser. See verify it yourself.

What Heron cannot do — stated up front

  • It cannot see an action taken around the hook. The absence of a record is indistinguishable from the absence of an action. Coverage is declared by the vendor, not proven by us, and the evidence page says so rather than implying the gap does not exist.
  • It does not judge intent. The policy engine classifies an action and enforces it against published rules. It does not decide whether the action matched what the user asked for — that is intent alignment, and it is a later stage.
  • It is not an auditor, and it certifies nobody. Heron is a trust centre and an evidence pipeline: an evidence page is a record to examine, not an attestation to rely on. Independent audit belongs with independent auditors.

The long version, including key lifecycle and tenancy: the security model.