KATA Intent Agreement

Status: Concept / Open Design — not production ready.

This document specifies how a principal and an agent, and optionally a merchant, a payment provider, or an issuer, establish a verifiable agreement on what the agent may do, and how a proposed action is checked against that agreement.

It is the machinery for KATA's third question: what was the agent authorized to do? The fourth question — whether behavior matches that authorization — consumes the same signed record later. This document does not score behavior, and it does not replace the seven-outcome decision in schemas/decision.json.

KATA's own objects are authoritative here. AP2 mandates, Verifiable Intent credentials, and OAuth or GNAP grants are evidence that can be mapped into these objects. Field mapping for the commerce mandates stays in interoperability.md.

Decisions

Kaan answered the open questions. The agreement lives inside the delegation, KATA holds the spend ledger, and one delegation may carry several live intents as long as they stay inside the parent set. The table is the source for those choices. A short answer that could be read more than one way has its interpretation in the last column.

The structured intent stays schemas/intent.json. Delegation stays the answer to who authorized the agent (delegation-model.md). Amounts stay major units (1500, not 150000 cents). A mandate is signed with Ed25519 (alg: EdDSA) or P-256 (alg: ES256), as a flattened JWS, and the algorithm is a field of the signed document. The check returns ALLOW, STEP_UP, or DENY. DENY is the KATA decision BLOCK. REVOKE and QUARANTINE stay decisions of the wider engine, or an explicit signed revocation by the principal.

Where it sits

flowchart TD
    D[Delegation] --> A[Agreement inside the delegation]
    P[Wallet displays the KATA confirmation] --> S[Principal signs each mandate]
    S --> A
    C[Merchant, PSP, or issuer] -.->|optional acknowledgement| A
    AG[Agent proposes an action] --> E[Intent check]
    A --> E
    L[Ledger KATA stores on the agreement] --> E
    R[Revocation log] --> E
    E --> V{Verdict}
    V --> ALLOW
    V --> STEP_UP
    V --> DENY
    DENY --> BLOCK[KATA decision BLOCK]
    E --> Q4[Later: behavior against this mandate hash]

The intent module in architecture.md is this check plus the store of mandates. The reference library is the check and the lifecycle, in process. It is not the gateway, and it does not open a network connection.

Data model

Intent mandate

Schema: schemas/intent-mandate.json.

The signing document is those fields except signature, plus "kata_mandate": "1". The JWS protected header is {"alg":"EdDSA","kid":"<fingerprint>","typ":"kata-mandate+jws"} or the same header with "alg":"ES256". Header and payload are both canonical JSON. An ES256 signature is the raw R and S integers, 32 bytes each.

limits.per_transaction_maximum, when present, equals intent.maximum_amount. It is a restatement so a reader of the agreement sees the ceiling next to the cumulative cap. It is not a second, looser ceiling.

limits.cumulative_maximum is this intent's slice of the parent total, in limits.currency (the intent currency). It is not the per-transaction ceiling. The parent total is parent_limits.cumulative_maximum. The sum of the live slices must not exceed that total. Per-transaction ceilings are not added together.

limits.frequency is {max_count, per}. per is agreement (the whole window), P1D (one day), P7D (seven days), or P1M (thirty days, not a calendar month).

limits.merchant_denylist refuses merchants even when intent.merchant_constraints is empty. An empty merchant_constraints array still means no allowlist, as in the intent schema.

Agreement record

Schema: schemas/agreement.json.

An acknowledgement is a JWS (typ: kata-ack+jws) over kata_ack, agreement_id, mandate_hash, role, id, at, and the acknowledging public key. An agent acknowledgement must use the key named in the mandate. A merchant, PSP, or issuer acknowledgement proves that the holder of the embedded key saw this mandate hash. When the verifier supplies an institution directory, that key must also be on the KATA allowlist or in https://<domain>/.well-known/kata-keys.json, including the rotation grace (default 7 days). Without a directory, the library does not invent that check.

A revocation is a JWS (typ: kata-revocation+jws) over kata_revocation, agreement_id, mandate_hash, at, and reason. The reference implementation accepts a revocation only from the principal key that signed the mandate.

Canonical JSON

Signatures are over UTF-8 JSON with:

• object keys sorted by UTF-16 code units
• no insignificant whitespace
• strings escaped as JSON, and U+2028 / U+2029 escaped as well
• numbers in base 10, no exponent, no leading zero, no trailing fractional zero, and no decimal point when the value is an integer

1, 1.0, and 1.00 are the same amount and encode as 1. 1.50 encodes as 1.5. Non-finite numbers are rejected. This is the RFC 8785 shape for the types the library emits. A language-default serializer that writes 1.0 will not verify.

What the signature does not cover

The event log, the spend ledger, status, created_at, and updated_at are outside the mandate signature. KATA's copy of the ledger is the one evaluation uses. Each ledger entry stores entry_hash over the entry with that field removed, and prev_entry_hash of the previous entry. Each event stores event_hash the same way, and prev_event_hash of the previous event. An edit in the middle no longer matches.

A prefix of either chain still hashes. For the spend ledger, the authorization check closes that gap: it carries ledger_sequence and ledger_head. A sequence lower than the ledger being evaluated is a truncated copy and is denied. For the event log, a verifier that has stored a previous head can pass it as expected_log_head. A verifier that has not seen the log before cannot detect a dropped tail from the chain alone. The transparency log is the record of agreements and revocations outside any one copy. See Threats.

Human-readable rendering

The hardest fraud problem at grant time is a principal signing limits they did not read, or reading a sentence the agent rewrote. KATA does not render a user interface. It produces the confirmation text from the structured mandate, and the hash of that text. The wallet or bank app displays the text and collects the signature. The verifier produces the text again. The signed rendering.text and rendering.hash must both equal what KATA just produced.

English (confirmation_language: en) is built in. The line order below is fixed for that language. Another language is canonical only when the same renderer is registered on the signer and on the verifier. A translation the wallet writes, and then signs, is RENDERING_MISMATCH.

Whitespace inside the quoted instruction is collapsed to single spaces, so a newline in the source cannot push the ceilings below a one-line display.

For the laptop instruction the renderer produces:

You (K. Uluer, usr_9182) authorize agent shopper-01 to purchase.
Agent key: sha256:<fingerprint of the bound agent>.
Your words: "Find and buy a laptop for me, maximum CAD 1,500.".
Up to 1500 CAD per transaction.
Up to 1500 CAD in total under this agreement.
Category: electronics.
Merchants allowed: any.
Allowed actions: search, compare, purchase.
Valid from 2026-10-04T13:55:00Z until 2026-10-10T23:59:59Z.
Delegation: dlg_77.
The agent cannot change these limits. You can revoke this agreement.

accept, amend, and add_intent refuse a rendering_text that is not the text KATA produced. confirmed_text, when passed, must be that same text. The wallet displays it. KATA does not.

Lifecycle

flowchart LR
    P[proposed] --> C[clarifying]
    P --> A[accepted]
    C --> A
    A --> G[active]
    G --> G2[active after amend]
    P --> X[revoked]
    C --> X
    A --> X
    G --> X
    G --> E[expired]
    A --> E

Renewal is a new grant or a new version. It is not a silent extension of expires_at.

Default required acknowledgements are none. The principal's signature plus the bound agent key is enough to become active. Requiring an agent countersignature, or a merchant or issuer acknowledgement, is a field on the mandate (required_acknowledgements), so stripping it breaks the signature.

Verification

evaluate(agreement or mandate, action) -> ALLOW | STEP_UP | DENY

Inputs beyond the action:

The signature is checked first. If it fails, the result is DENY and the other fields are not interpreted. A tampered ceiling must not produce a tidy "amount exceeded" reason about attacker-controlled numbers.

When the signature holds, every other check runs. A DENY reason wins over a STEP_UP reason. Both are returned, deny codes first, so the principal sees the whole set.

There is no risk score. The decision schema's score is a different layer, and this library will not invent one.

Reason codes

Integrity and authority, all DENY:

Scope, DENY unless noted:

STEP_UP:

Ledger outcomes allowed, authorized, and settled count toward cumulative and frequency. failed does not. A price check runs only when the intent has price_expectation. A ceiling is never copied into quoted_price.

An action inside the window is not failed for being old. Replay is an id and an idempotency key, not a second look at the clock.

Threats

These sit under the assets already named in threat-model.md: intent objects, delegation records, and the decision trail. The rows below are the ones this design takes a position on.

Upstream account takeover of the AI application is unchanged from the threat model: a real principal key can sign a real mandate for the attacker's purchase. This layer will show a valid signature. Per-session step-up to the human is still the control, and it belongs to the wider decision, not to a second copy of the mandate.

Interoperability

KATA does not adopt AP2, Verifiable Intent, OAuth, or GNAP as the mandate format. A verified credential is evidence. The intent check still runs, and its verdict is a KATA verdict.

Two conversions that are easy to get wrong, and that this spec does not do:

• Do not map an amount ceiling onto price_expectation.quoted_price.
• Do not treat an AP2 or VI minor-unit integer as a KATA major-unit amount.

Worked mappings of the commerce fields remain interoperability.md. The reference library does not parse an AP2 JWS or an SD-JWT.

Reference implementation

reference/python is a Python library. Tests cover signing with Ed25519 and ES256, tampering, the lifecycle, the laptop amounts, price and fees, the hash-chained ledger, canonical confirmation text, auto-selection among live intents, pull and push revocation, the transparency log, the FX ceiling, institution keys, and schema validation. examples/purchase_check.py signs the CAD 1,500 laptop intent, allows a CAD 1,300 purchase, denies a CAD 4,200 purchase, then revokes and denies the in-scope purchase.

Demo keys in the example are derived from public seeds.

Roadmap

The next slices, in the order they unblock each other:

1. Revocation hosting. The pull cache, the push webhook, and the signed Merkle log are in the library. What remains is who operates the log, which key verifiers trust for tree heads, and gossip between logs. The library verifies a key the deployment supplies.
2. Ledger sync. Truncation and staleness are checked. What remains is a transport that carries the head between processes. This library does not open a socket.
3. Full evaluator. Identity, delegation freshness, and behavior around this verdict, emitting the seven decisions. Still no calibrated score until there is a measurement.
4. Intent capture. Propose a structured intent from the instruction, then require the KATA rendering as the confirmation. The parser is a separate component so a bad parse cannot sign itself.
5. Selective disclosure. SD-JWT, if a deployment needs to show a subset of the mandate. ES256 is already a signing algorithm. Version the signing document rather than overloading kata_mandate 1.
6. Institution-key operations. The allowlist, .well-known/kata-keys.json, and a 7-day grace are specified. Fetching that document, and who maintains the allowlist, are deployment work.
7. Evaluation against AgentCommerceBench. Run the reference check on the classes it can see (amount, category, quote, list, fees, replay, payee). Report recall at a stated false-positive budget. Do not cite a coverage number before that run. Silent downgrade still needs delivery evidence this layer does not have.
8. Envelope. Only after the fields settle: VC packaging, or carrying the intent inside RAR authorization_details. Not a second schema.

Still open

Decisions 1 through 20 are applied. These are not:

• The reference library does not open a socket. service/ is a Vercel host for the pull list, the push webhook, the transparency log, .well-known/kata-keys.json, and a Frankfurter FX stub. Gossip between logs is still not built. The wallet or bank app still displays the confirmation.