diff --git a/AGENTS.md b/AGENTS.md index ee2e5e53d..06c587706 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ observation), with Python and TypeScript SDKs and framework integrations. [HIGH | `tracekit/report.py` | `tracekit report`: a window of a signer's store on one page, built on the viewer's reader, check and review (experimental) | [HIGH CONFIDENCE] | | `tracekit/why/` | `tracekit why`: causal investigation and replay | [HIGH CONFIDENCE] | | `tracekit/pcm/` | PCM 0.1, proof-carrying messages (experimental): `__init__.py` (message, schema and grant checks, replay, `verify`), `claims.py` (claim evidence), `cli.py` (`tracekit pcm verify`, `tracekit pcm demo`), `tools.json` (the frozen tool placement table, part of the protocol); its signer RPCs (`pcm_*`, contract version 20) are in `tracekit/signer/` | [HIGH CONFIDENCE] | +| `tracekit/grants.py` | Intent grants (experimental, docs/intent-grants.md): the `payment.send` intent, amounts, the payment reader and the caveat and limit checks the signer (`grant_*` RPCs, contract version 22; releases in `_decide`), the CLI (`tracekit grant`, `approvals approve --grant`) and the verifier (`intent grants`) share; a grant is a PCM grant as it is | [HIGH CONFIDENCE] | | `tracekit/findings_v2.py`, `tracekit/findings_text.py`, `tracekit/findings_effects.py`, `tracekit/parsers.py`, `tracekit/review_model.py` | `tracekit analyze --v2`: intent, reasoning and action checks (TK-X200..X204, X208) over a v2 run and its content vault, the text checks (TK-X205 and v1's say-vs-do checks) and the effect checks (TK-X206, TK-X207: kernel sensor effects joined to calls); `parsers.said()` reads what a model said before each tool use; `--review`: the reviewer model (TK-X210, warn only) | [HIGH CONFIDENCE] | | `tracekit/storage/`, `tracekit/identity/`, `tracekit/transport/` | v2 storage (file, Postgres), caller identities (uid, token, mTLS, k8s service account, OIDC, WebAuthn), RPC transports | [HIGH CONFIDENCE] | | `tracekit/daemon.py` | v1 signer daemon (tracekitd): socket, peer identity, run state, approvals, checkpoints | [HIGH CONFIDENCE] | diff --git a/Makefile b/Makefile index eb24492ba..9994bc2c6 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ help: @echo "make release-dry-run build every release artifact, SBOM and sum locally, publish nothing, and check them (needs the package index and npm)" @echo "make demo run the scripted end-to-end demo" @echo "make demos record the offline demos in docs/demos/ again (scripts/record_demos.py; --check checks them)" - @echo "make eval offline evaluations E1 (integrity), E2 (overhead), E3 (policy gate), E4 (seeded faults, v1 and v2), E6 (findings), E17 (server policy corpora, detection), E18 (agent approvers), E19 (egress observation), E20 (intent, reasoning and action checks), E21 (policy robustness: held-out calls, and shell rewrites), on Linux E9 --quick (signer perf); rewrites eval/results/" + @echo "make eval offline evaluations E1 (integrity), E2 (overhead), E3 (policy gate), E4 (seeded faults, v1 and v2), E6 (findings), E17 (server policy corpora, detection), E18 (agent approvers), E19 (egress observation), E20 (intent, reasoning and action checks), E21 (policy robustness: held-out calls, and shell rewrites), E23 (intent grants), on Linux E9 --quick (signer perf); rewrites eval/results/" @echo "make eval-agents E5: real Claude Code runs (needs the claude CLI; spends model usage)" @echo "make eval-scale E7: SQL index over a million-event ledger (contrib/query)" @echo "E8 (insider attacks) needs root and a Linux system-mode signer; CI runs it, see eval/e8_insider.py" @@ -82,6 +82,7 @@ eval: $(PY) eval/e20_alignment.py $(PY) eval/e21_policy_robustness.py $(PY) eval/e21_robustness.py + $(PY) eval/e23_grants.py if [ "$$(uname)" = Linux ]; then $(PY) eval/e9_signer_perf.py --quick; fi eval-agents: diff --git a/docs/approvals.md b/docs/approvals.md index d5d4c53ca..f4c003204 100644 --- a/docs/approvals.md +++ b/docs/approvals.md @@ -130,6 +130,13 @@ unchanged: the hook only chooses which arguments the retry is decided with, and the approval. So a retry exactly as approved, description included, runs under that approval even when another wording of the command was rejected: the person approved that call. It runs once; the approval is used up then. +## Approve calls like this one: grants + +For a held payment, `tracekit approvals approve ID --grant --payee … --max '200 USDC' --total '500 USDC' --for 1h` +approves the call and grants the run more payments like it, within those limits: they run without a stop, and +anything outside them is held with the reason. `tracekit approvals show ID` says how a grant reads the call. See +[intent grants](intent-grants.md). + ## Tiers: T1 and T2 executors - **T1** (default): the approval binds the arguments the agent reported. The adapter runs the call in the agent's diff --git a/docs/evaluation.md b/docs/evaluation.md index 1bfd14964..83a27e2c2 100644 --- a/docs/evaluation.md +++ b/docs/evaluation.md @@ -1,7 +1,8 @@ # Evaluation -Twenty-one experiments, E1 to E22 (there is no E13). `make eval` runs the offline ones: E1 to E4 (E4 on v1 and v2 -bundles), E6, E10, E11, E12, E14 (as `--quick`; POSIX), E16, E17, E18, E19, E20 and E21, and E9 `--quick` on Linux. +Twenty-two experiments, E1 to E23 (there is no E13). `make eval` runs the offline ones: E1 to E4 (E4 on v1 and v2 +bundles), E6, E10, E11, E12, E14 (as `--quick`; POSIX), E16, E17, E18, E19, E20, E21 and E23, and E9 `--quick` on +Linux. E5 uses real Claude Code runs and is opt-in (`make eval-agents`, needs the `claude` CLI and spends model usage); E7 is `make eval-scale`; E22 (`eval/e22_verifier_agreement.py`) runs on its own. In CI, E8 (insider attacks, which needs root and a Linux system-mode signer) is a merge gate, and E9 (`eval/e9_signer_perf.py`, latency and throughput over the Unix @@ -645,6 +646,19 @@ rewrite let a log origin widen it past a phone's screen. Not in `make eval`: it Chrome and each framework (`--python NAME=PY` runs an example with an interpreter that has it; an example that can't run is listed as skipped). Firefox and Safari are not run. +## E23: intent grants + +`eval/e23_grants.py` runs a payout agent against one in-process signer whose payment rule opts into +[intent grants](intent-grants.md), with a named approver. Seven parts: 30 payments, 24 within the grant and 6 outside it +(an unknown payee, over the most for one payment, past the total), where the person's stops fall from 30 to 7 and +nothing outside the limits runs; 25 calls a grant must not read as within it (amounts in other units, hundredths of a +USDC past the cap, a currency with no known unit, payee look-alikes, a second payee, arguments that can move money or +pick what is paid, such as a fee, a split, a memo, an invoice or order id, another currency, another tool), all held; +the agent issuing a grant +for its own run, passing one on, or asking for one past a day, all refused; 100 payments of 7 USDC under a 50 USDC +total, of which 7 run; a revoked and an expired grant, which release nothing; totals across a signer restart; and the +run's bundle, whose `intent grants` line re-checks every release. Results: `eval/results/e23_grants.json`. + ## What is not measured Signer throughput with a separate-user signer or over the remote gateway, durability across crashes beyond the diff --git a/docs/format-v2.md b/docs/format-v2.md index c68212c88..36ef4cbe4 100644 --- a/docs/format-v2.md +++ b/docs/format-v2.md @@ -575,7 +575,7 @@ them, all critical; from 1.4.0 the bundle layouts it reads, critical too (`layou | 1.2.0 | `run.child`, `approval.escalated`, `approval.revoked`, `approval.suggested`, `approval.agents`, `incident.opened`, `incident.updated`, `incident.capped`, `run.held`, `run.resumed`, `run.quarantined`, `incident.resolved`, `incident.response`, `identity.suspension`, `effect.observed` | `run.registered`: `parent_run`, `session`, `posture`; `capture.gap`: `run_id`; `run.final`: `provider_executed`, `paired_by_args`, `matrix`; `policy.decision`: `via`, `caller`, `detect`, `incident_id`; `approval.request`: `agent`, `via`, `incident_id`, `passkey`; `tool.result`, `input.observed`: `via`; `approval`: `approver_kind`, `asserted`, `spent`, `not_before`, `consume_by`, `incident_id`; `approval.expired`: `reason`; `reconcile.unexplained_effect`: `observer`, `kind`, `host`, `port` | `capture.gap` `kind`: `decided_not_completed`, `late_activity`, `concurrent_run`, `tailer_redelegated`, `reask_after_reject`, `held_call_unresolved`, `observer_lost`, `effect_outside_run`; `run.closing` `reason`: `quarantine` | — | | 1.3.0 | `reconcile.result_mismatch` | — | `capture.gap` `kind`: `result_unchecked` | — | | 1.4.0 | `constraint.added` | `effect.observed`: `sensor`, `denied`; `review`: `cites`; `model.exchange`: `said_only`; `capture.gap`: `sensor` | `capture.gap` `kind`: `constraint_refused` | `amended`, `openshell.policy`; and the slot itself (`ext` fields, `ext` records: critical) | -| 1.6.0 | — | — | — | `box`: on `run.registered`, `{id, image_digest, allow, engine, channel?}`, the label of a Tracekit Box box's run (a `box_daemons` uid's) and, copied with `parent_run`, of each run its agent channel registered; the signer takes the engine from its config. Read as `boxed agent`: `PROOF AGAINST THE BOXED AGENT (micro-VM)` and no more | +| 1.6.0 | — | — | — | `box`: on `run.registered`, `{id, image_digest, allow, engine, channel?}`, the label of a Tracekit Box box's run (a `box_daemons` uid's) and, copied with `parent_run`, of each run its agent channel registered; the signer takes the engine from its config. Read as `boxed agent`: `PROOF AGAINST THE BOXED AGENT (micro-VM)` and no more; `intent.grant` and `intent.revoked` (`ext` records of source `signer`) and `grant` (on a `policy.decision`), a person's [intent grant](intent-grants.md) and the payments it released | Layouts (critical): 1.4.0 adds `run parts`, a run in parts (above). @@ -613,6 +613,10 @@ a new critical row, so a verifier from 1.4.0 on keeps verifying later bundles: - `box` is non-critical: a box channel's run records `signer_isolation: unknown`, so a verifier that doesn't read the label claims nothing for it; one that reads it adds a `boxed agent` line, which narrows what the run proves (against the boxed agent only) and never widens it. +- `intent.grant`, `intent.revoked` and `grant` are non-critical: a payment a grant released is a `flag` decision + either way, so a verifier that doesn't read them says the call ran without a stop, which is true; one that reads them + adds an `intent grants` line that re-checks each release against its grant ([intent grants](intent-grants.md)), and + fails the verification when the signer released a payment its own grant holds. - `review.cites` and `effect.observed.sensor` stay critical: a verifier that passed over a signed finding's citations would label it `imported`, a false line; and a sensor's effects are records of what the agent's own processes did, in its run, which a verifier must read to verify that run. So does `capture.gap.sensor`: a 1.3 verifier counts every @@ -733,7 +737,18 @@ line and verdict is in [verdicts](verdicts.md). policy`, passing with `OpenShell changed the sandbox policy or configuration n time(s) (: , ... the first 8 in code-point order), as OpenShell reported it`, a warning listing the records (the first 20) that carry it other than as an `ext` record of source `signer` with a `change` of `[a-z0-9_.-]{1,64}` and a non-empty - `observer`. `box` (1.6.0): `boxed agent`, a warning listing the records (the first 20) when any record carries it + `observer`. `intent.grant`, `intent.revoked` and `grant` (1.6.0), read together with every `policy.decision` + whose `rule_ids` name `TK-GRANT`: `intent grants`, failing, listing the records (the first 20), where a released + payment (a `flag` with `TK-GRANT`) names no grant the bundle holds earlier in its run, or one whose record fails + the grant rules below, or breaks its grant: its fields aren't whole numbers of the intent's, its tool isn't one + the grant covers, its grant was revoked or expired before it or its fields break a caveat or a limit, its totals + aren't the previous plus its own as whole numbers, or its tier isn't the record's; and where a decision names + `TK-GRANT` without `ext.grant`. A warning, listing the records, where a grant isn't a person's PCM grant for its own + run and tenant, never passed on, its `id` its hash's, naming 1 to 16 tools, valid for its intent in a currency with + a known unit with an expiry within 24 h of its `ts`, and its first totals those of no call or of the held call it + came from; a revocation names no grant live earlier in its run; or an `ext.grant` isn't on a `flag` with + `TK-GRANT`. Else it passes with the grants, who issued them, and the payments released at T2 and T1. + `box` (1.6.0): `boxed agent`, a warning listing the records (the first 20) when any record carries it other than on a `run.registered` whose `data.identity.scheme` is `uid`, as an object with exactly `id` (`[A-Za-z0-9._:-]{1,128}`), `image_digest` (`sha256:` and 64 hex digits), `allow` (a list of strings), `engine` (`firecracker`, read as `micro-VM`) and optionally `channel` (`agent`). Else only the labels on the first record of diff --git a/docs/intent-grants.md b/docs/intent-grants.md new file mode 100644 index 000000000..bb581b24c --- /dev/null +++ b/docs/intent-grants.md @@ -0,0 +1,309 @@ +# Intent grants: approve costly payments once, with limits + +> **Experimental:** this works and is tested, but may change and gets less hardening than the [stable core](support.md). + +An agent pays this week's invoices to the same two contractors. Each payment waits for a person, so the person +approves ten payments one at a time. With an intent grant, the person approves the first payment and states the +bounds for the rest once: who may be paid, the most for one payment, the total, and for how long. The signer then lets +each payment inside those bounds run, records it as within the grant, and holds anything outside them with the exact +reason. `tracekit verify` re-checks every released payment against the grant and its running total, from the bundle +alone. + +Payments are the first kind of call a grant covers (the intent `payment.send`). A grant covers one run. + +## A worked example + +A Claude Code agent on a laptop pays through an MCP tool, `mcp__payments__send_money`. The dev signer holds money-moving +MCP tools for a person (rule `TK-A044` of the coding pack). + +**1. The first payment is held.** The agent pays the first contractor 120 USDC: + +```text +[tracekit] HELD, nothing ran: apr-99c7fe5d7ff4ef1014c764c787b56c4f (TK-A044, TK-F006), expires 07:19 UTC. +Why: moving money through an MCP tool (sending, transferring or converting money, or a refund) +Instead: Check the amount, currency and recipient in the call's arguments before approving it; a refund with no amount refunds in full. +Person: look with `! tracekit approvals show apr-99c7fe5d7ff4ef1014c764c787b56c4f`; allow once with `! tracekit approvals approve apr-99c7fe5d7ff4ef1014c764c787b56c4f`; refuse with `! tracekit approvals reject apr-99c7fe5d7ff4ef1014c764c787b56c4f`. +``` + +**2. The person looks.** `tracekit approvals show` says how a payment grant reads the call, and gives a command with +limits taken from it, to edit: + +```text +$ tracekit approvals show apr-99c7fe5d7ff4ef1014c764c787b56c4f +approval apr-99c7fe5d7ff4ef1014c764c787b56c4f (requested) +tool "mcp__payments__send_money" +why moving money through an MCP tool (sending, transferring or converting money, or a refund) (TK-A044) +... +grant a payment grant reads it as 120 USDC to "0x1111111111111111111111111111111111111111"; to approve it and let more payments like it run, set your own limits: + tracekit approvals approve apr-99c7fe5d7ff4ef1014c764c787b56c4f --grant --payee 0x1111111111111111111111111111111111111111 --max '120 USDC' --total '600 USDC' --for 1h +... +arguments (the signer's copy, in full): +{ + "amount": 120000000, + "currency": "USDC", + "to": "0x1111111111111111111111111111111111111111" +} +``` + +**3. The person approves it and grants payments like it.** Both contractors, at most 200 USDC each, 500 USDC in all, +for an hour: + +```text +$ tracekit approvals approve apr-99c7fe5d7ff4ef1014c764c787b56c4f --grant \ + --payee 0x1111111111111111111111111111111111111111 --payee 0x2222222222222222222222222222222222222222 \ + --max '200 USDC' --total '500 USDC' --for 1h --note "this week's two contractors" +grant g-2f9deebdfc669a5b issued for run 1c2fd065d4cddefa68a4aca823c9631a: payments through "mcp__payments__send_money" to 0x1111111111111111111111111111111111111111, 0x2222222222222222222222222222222222222222, up to 200 USDC each, 380 of 500 USDC left, until 2026-11-06T07:20:58.856118Z. Recorded as self-approved: the dev signer runs as your own user and can't tell you from your agent +approved: apr-99c7fe5d7ff4ef1014c764c787b56c4f, by you. ... +``` + +The grant covers the held call's tool, `mcp__payments__send_money`, and no other. The held payment is the grant's +first: its 120 USDC count toward the total. The agent's retry of it runs on the approval, and the grant doesn't count +it again. + +**4. Payments within the grant run.** 200 USDC to the second contractor, then 150 USDC to the first: no stop. Each +decision is signed as `flag` with `TK-GRANT`, and says what it released and what is left +(`within grant g-2f9deebdfc669a5b: 150 USDC to 0x1111…; 30 of 500 USDC left`). + +**5. A payment outside it is held, with the reason.** 20 USDC to an address the person never named: + +```text +[tracekit] HELD, nothing ran: apr-… (TK-A044, TK-F006), expires … +Why: grant g-2f9deebdfc669a5b: payee "0x3333333333333333333333333333333333333333" is not one of "0x1111111111111111111111111111111111111111", "0x2222222222222222222222222222222222222222"; moving money through an MCP tool (sending, transferring or converting money, or a refund) +``` + +**6. The grant, as it stands.** + +```text +$ tracekit grant list +g-2f9deebdfc669a5b live run=1c2fd065d4cddefa68a4aca823c9631a payment.send tools="mcp__payments__send_money" self-approved (the run's own user, which the agent can be) to 0x1111111111111111111111111111111111111111, 0x2222222222222222222222222222222222222222, up to 200 USDC each, 30 of 500 USDC left until 2026-11-06T07:20:58.856118Z "this week's two contractors" +``` + +**7. Verify.** `tracekit last` exports the run and verifies it; with `--detail` the report has the grant's line: + +```text +intent grants 1 grant(s) (1 self-approved: issued by the run's own user, which the agent can be); 2 call(s) released + within them (0 at T2, decided and run by an executor or gateway; 2 at T1, on the arguments the harness + reported), each re-checked against its grant and its running totals +``` + +In `tracekit view`, the run's PERMISSIONS page lists the grant (who issued it, its limits, what is left, until when), +and each payment it released reads `WITHIN GRANT`, with the payment and what the grant had left after it. The tab +`WITHIN A GRANT` shows only those. + +## Commands + +| Command | What it does | +|---|---| +| `tracekit approvals show ID` | For a held payment, how a grant reads it (amount, currency, payee) and a command to approve it with a grant, limits taken from the call for you to edit; or why a grant can't read it | +| `tracekit approvals approve ID --grant LIMITS` | Issues a grant from the held call, then approves the call: the call is the grant's first payment, and its tool one the grant covers | +| `tracekit grant add --run RUN --tool TOOL LIMITS` | Issues a grant for a run before it asks, covering the tools you name | +| `tracekit grant list [--run RUN] [--json]` | The grants of the open runs you may see: who issued each, its tools and limits, what is left, and its state (`live`, `used_up`, `expired`, `revoked`) | +| `tracekit grant revoke GRANT_ID [--reason TEXT]` | Ends a grant: every payment it would release is held again | + +`LIMITS` are these flags: + +| Flag | Meaning | +|---|---| +| `--tool TOOL` | A tool whose calls the grant covers, as the policy names it (`mcp__payments__send_money`); repeat it for each (required for `grant add`; from a held call, its tool is one already) | +| `--payee ADDRESS` | A payee the agent may pay; repeat it for each (required) | +| `--total '500 USDC'` | The most all the grant's payments add up to (required) | +| `--max '200 USDC'` | The most one payment may be (default: the total) | +| `--count N` | The most payments it releases | +| `--for 4h` | How long it lasts: minutes or hours, 24h at most (default 1h) | +| `--note TEXT` | Your own words for what it is for, shown in `grant list` and the viewer | + +Amounts are written as you say them, a number and a currency (`500 USDC`, `12.50 USD`). Tracekit knows the units of +USD, EUR, GBP, INR, CAD, AUD, CHF, SGD, JPY, USDC and USDT; records hold whole smallest units (`500 USDC` is +500000000). `--signer` names another signer, as for `tracekit approvals`. + +From code, the signer's calls are `grant_issue`, `grant_list` and `grant_revoke` (signer protocol 22), for example +`tracekit.sdk.client.Client().grant_issue({...})`: + +| Call | Request | Answer | +|---|---|---| +| `grant_issue` | `run_id`, `intent` (`payment.send`), `caveats`, `limits`, `expires_at`; `tools` (the tools it covers), `approval_id` (a pending approval of the run: the held call it is issued from, whose tool joins `tools`), `description` | `grant_id`, the signed `grant`, `tools`, `used` (its totals so far), `self_approved`, `run_seq` | +| `grant_list` | `run_id` | `grants`: each one's `grant_id`, `run_id`, `grant`, `tools`, `limits`, `used`, `state`, `self_approved`, `description` | +| `grant_revoke` | `grant_id`, `reason` | `grant_id`, `run_id`, `run_seq` | + +`caveats` are PCM caveats (`{field, op, value}`): `currency == USDC`, `payee in [...]` (or `==`), and optionally +`amount <= N`. `limits` are `{op: sum, field: amount, max: N}` (required) and `{op: count, max: N}`. + +## The grant + +A grant is a [PCM grant](pcm.md#grants) in PCM's own format: signed by the signer's log key, issued by a person for +one run (`issuer.run`) to the run's agent (`subject`), for an intent, within caveats, until `expires_at`. It can't be +passed on (`delegable: false`), so it reaches nothing past its run. A grant made in Tracekit can ride in a PCM message +as it is. The signer writes it into the run in an `intent.grant` record, with the tools it covers, its limits, its +totals so far and the note: + +```json +{"name": "intent.grant", "id": "g-2f9deebdfc669a5b", + "grant": {"pcm_grant": 0, "ts": "2026-11-06T06:20:58.856118Z", + "issuer": {"kind": "person", "id": "uid:501", "run": "1c2fd065d4cddefa68a4aca823c9631a", "tenant": "default", + "approval_id": "apr-99c7fe5d7ff4ef1014c764c787b56c4f"}, + "subject": "uid:501", "intent": "payment.send@sha256:…", + "caveats": [{"field": "currency", "op": "==", "value": "USDC"}, + {"field": "payee", "op": "in", "value": ["0x1111…", "0x2222…"]}, + {"field": "amount", "op": "<=", "value": 200000000}], + "expires_at": "2026-11-06T07:20:58.856118Z", "delegable": false, "parent": null, "sig": {"key": "…", "sig": "…"}}, + "tools": ["mcp__payments__send_money"], + "limits": [{"op": "sum", "field": "amount", "max": 500000000}], "used": [120000000], "self_approved": true, + "first": {"approval_id": "apr-99c7fe5d7ff4ef1014c764c787b56c4f", "tool_call_id": "pay-1", + "fields": {"amount": 120000000, "currency": "USDC", "payee": "0x1111…"}}, + "description": "this week's two contractors"} +``` + +The intent's schema document (`payment.send`: `amount` an int, `currency` and `payee` ids) ships with Tracekit +(`tracekit/grants.py`). + +The names follow Google's Agent Payments Protocol (AP2) where they meet: the Intent Mandate's +`natural_language_description` is the grant's `description`, its `intent_expiry` the grant's `expires_at`, its +`merchants` and the open Payment Mandate's `payment.allowed_payees` the `payee in [...]` caveat, `payment.amount_range` +(integer minor units) the currency and amount caveats, `payment.budget` the `sum` limit, and +`payment.agent_recurrence.max_occurrences` the `count` limit. As in AP2, a grant field the signer doesn't know is +refused. Source: AP2 at +[`e1ea56db`](https://github.com/google-agentic-commerce/AP2/tree/e1ea56db72a6385bce3e5c1112b3a56ce60acb43) +(`code/sdk/python/ap2/models/mandate.py`, `code/sdk/schemas/ap2/open_payment_mandate.json`). + +## What a grant reads + +A grant reads a payment call of a tool it covers, whose rules opt into payment grants: `TK-A044` (MCP money tools) in +the coding pack, which the dev and server packs extend, and `TK-M001` and `TK-M002` in the server packs. It reads: + +- **currency**: `currency`, compared in upper case, one of those whose unit Tracekit knows: USD, EUR, GBP, INR, CAD, + AUD, CHF, SGD and JPY (ISO 4217's digits after the decimal point) and USDC and USDT (6); +- **amount**: exactly one of `amount`, a whole number of the currency's smallest unit (cents, or a token's base unit, as + Stripe takes them), and `amount_cents`, hundredths of its whole unit, which must come to a whole number of that + smallest unit (150 JPY cents is 1.5 yen, so it is held), above zero; +- **payee**: every payee key the call has (`payee`, `to`, `recipient`, `destination`, `account`, `account_number`, + `iban`), which must all name one payee, of letters, digits and `._:@/+=-`. An EVM address is compared in lower case; +- **free text** that moves no money: `description` and `note`, as plain strings. + +A call with anything else is held as it would be without a grant, and the hold names what the grant couldn't read: a +call of a tool the grant doesn't cover, another argument (`memo`, which routes funds on some chains, an invoice or +order id, which picks what is paid, an idempotency key, a fee or a split), an amount as a string or a decimal, a +currency without a known unit, a second payee, a payee in an object. + +## How the signer decides a payment + +1. The policy decides the call as usual. A grant can release only an `ask`; a deny stays a deny. +2. Every rule that held the call (flags aside) must opt into the grant's intent. A call held by any other rule, by + `TK-HOLD`, `TK-CONSTRAINT` or `TK-SHELL-PARSE`, or in a held or quarantined run, is held as without a grant. +3. A grant that covers the call's tool reads its amount, currency and payee. +4. Every caveat must pass, and the totals must stay within every limit. The signer checks the totals as it writes the + decision, so two payments at once can't both spend the last of a total. A payment counts when it is decided. + What a grant releases still passes every limit the operator's policy sets: a sum limit that can't read the call + holds it (`TK-LIMIT-SUM`), and one it takes past its maximum holds the run, as for any call. +5. Within the grant: the call runs. The decision is `flag`, its rule ids those that held the call and `TK-GRANT`, + with the payment and what is left; its `ext.grant` records the grant's id, the payment's fields, the totals after + it and its tier. +6. Outside: the call is held, and the reason names the grant and the bound it breaks. + +| A payment, under a grant of 200 USDC each, 500 in all, to two payees | Decision | Reason | +|---|---|---| +| 120 USDC to the first payee | runs | `within grant g-…: 120 USDC to 0x1111…; 380 of 500 USDC left` | +| 250 USDC | held | `grant g-…: amount 250 USDC is over 200 USDC each` | +| to a third address | held | `grant g-…: payee "0x3333…" is not one of "0x1111…", "0x2222…"` | +| in EUR | held | `grant g-…: currency "EUR" is not "USDC"` | +| 200 USDC with 400 used | held | `grant g-…: 400 of 500 USDC used; this call needs 200 USDC` | +| amount `"120"` | held | `grant g-…: amount "120" is not a whole number of the currency's smallest unit …, so a person decides` | +| `amount_cents` 19999999 (199,999.99 USDC) | held | `grant g-…: amount 199999.99 USDC is over 200 USDC each` | +| with an `invoice_id` | held | `grant g-…: argument "invoice_id" is not one a payment grant reads, so a person decides` | +| through another tool | held | `grant g-… covers mcp__payments__send_money, not mcp__payments__pay_invoice` | +| after `tracekit grant revoke` | held | `grant g-… was revoked` | +| past `--for` | held | `grant g-… expired at …` | + +A call a person already approved (the agent's retry of the held call a grant was issued from) runs on that approval, +and no grant counts it again. + +## Who may issue a grant + +As who may answer the run's approvals ([approvals](approvals.md#who-may-answer)): + +- With signer.yaml's `approvals`: an approver of the run's tenant, never the run's own user or principal (unless + `approvals: {self_approval: allow}`). The grant names the person `approvals.persons` maps them to. +- On the dev signer: any identity that may answer the run's approvals, which there is any identity of the run's + tenant. The grant records who issued it; one from the run's own user is recorded `self_approved`, and the verifier + says so, because the agent runs as that user too. +- Never an agent approver, and never in a held, quarantined or ending run. + +A person runs every grant command. The coding pack (and the dev and server packs, which extend it) denies every +`tracekit grant` the agent runs, whatever its options and action, `list` and `revoke` included, and its +`tracekit approvals approve --grant` (`TK-D012`): as `tracekit`, as `python -m tracekit`, and through a path to it or a +runner such as `uvx`, as it denies the agent's own approvals. The signer's `grant_list` and `grant_revoke` calls are +open to anyone who may see the run, the run's own user included: revoking only narrows what the agent may do. + +A grant lasts at most 24 hours. No call widens a grant or extends one; a new grant is a new decision by a person. + +## Settings + +**Policy.** An ask rule opts its calls into grants with `approval: {grant: payment.send}`: + +```yaml +ask: + - id: PAY + class: payment + pattern: '^' + approval: {grant: payment.send} +``` + +A rule with `approval: {passkey: required}` can't opt in: each of its calls needs a person's passkey. `TK-GRANT` is +the signer's own id, so no rule may use it. + +**Signer.** An operator can cap what a person may grant, per currency, in signer.yaml: + +```yaml +grants: + payment.send: + ceiling: ["1000 USDC", "500 USD"] +``` + +A grant whose total is over the ceiling is refused when it is issued (`the total 1500 USDC is over this signer's +ceiling of 1000 USDC a grant`), and with a ceiling set, a grant in a currency it doesn't list is refused too. + +## Records and verification + +| Record | What it holds | +|---|---| +| `ext` record `intent.grant` | the grant, the tools it covers, its limits, its totals at issue, `self_approved`, the held call it was issued from (`first`), the note | +| `ext` record `intent.revoked` | the grant's id, who revoked it, the reason | +| `policy.decision` with `ext.grant` | a payment the grant released: `{id, fields, used, tier}` | + +These go in format v2's non-critical `ext` slot ([format v2](format-v2.md#9-bundle-layout)): a verifier older than +1.6 verifies the run and says it doesn't interpret these names. `tracekit verify` and the TypeScript verifier check: + +- each grant: issued as a person's, for its own run and tenant, never passed on, its id its hash's, within 24 hours, + naming its tools, with the caveats and limits a payment grant has in a currency with a known unit, and its first + totals those of the held call it came from; +- each released payment: a `flag` decision with `TK-GRANT`, of a tool its grant covers, of a grant recorded earlier in + the run and not revoked before it, decided before the grant expired, its fields whole numbers within every caveat, + its totals the previous ones plus its own, whole numbers within every limit, and its tier the record's; +- each revocation: of a grant still live in its run. + +The `intent grants` line says how many grants there are and who issued them (`by alice`, or how many were +self-approved), and how many payments they released, at which tier: T2 when an executor or gateway decided and ran the +call ([executor](executor.md)), T1 when the harness reported the arguments. These fail the line and the verification, +because the records are the signer's own word that the payment was within a person's grant: +- a released payment that breaks its grant (outside its caveats, past a limit or after it ended, wrong totals, another + tool, an amount that isn't a whole number, a tier that isn't its record's); +- one whose grant the bundle doesn't hold earlier in its run (export the whole run), or holds only in a grant record + no signer writes (an expiry past 24 hours, a caveat missing, its id recomputed); +- a decision flagged `TK-GRANT` that names no grant. + +Any other record in a shape the signer never writes is a warning. + +The fields a decision records are the signer's reading of the arguments, which the bundle holds as commitments, and +the verifier doesn't open them. Checking the fields against the arguments is a manual step: open the arguments +(`tracekit signer reveal`) and run `grants.read` in `tracekit/grants.py` on them. + +## Limits + +See [limits](limits.md#intent-grants-experimental): one run per grant, payments only, amounts in whole smallest units, +only `description` and `note` beside them, payments typed into a shell command stay held, and what a dev-mode grant +proves. + +## Later + +Production changes (`change.apply`: an environment, and counts of what a plan creates, changes and destroys, from a plan +the executor makes and applies) and messages to people (`message.send`: recipients, their domains and how many) come +next, each as its own release. For on-chain payments, the later step is Proof-Gated Signing (arXiv 2610.00354). diff --git a/docs/limits.md b/docs/limits.md index 5c74af294..cca4227d6 100644 --- a/docs/limits.md +++ b/docs/limits.md @@ -778,6 +778,22 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees]( | Nothing enforces PCM between agents yet: the A2A gateway forwards PCM parts without checking them, and there is no `transfer` payload. | The A2A gateway is merged; enforcing PCM in it, and a `transfer` payload, are a follow-up. | Call `pcm.verify` in the receiving agent before it acts. | [PCM](pcm.md#agent-to-agent-transport) | | TypeScript has the four RPC schemas, so its client can call them, but no PCM verifier. | No TypeScript agent receives PCM yet. | Verify in Python, or with `tracekit pcm verify`. | [PCM](pcm.md#python-sdk) | +## Intent grants (experimental) + +| Limit | Why it is so | What to do | Details | +|---|---|---|---| +| A grant covers one run: a new run of the same agent asks again. | A grant's totals are counted in its run's records, so that run's bundle is enough to recount them. | Grant each run (`tracekit grant add --run RUN`). A grant over several runs is a later step. | [intent grants](intent-grants.md#the-grant) | +| Grants cover payments only (`payment.send`). | Payments are the first intent; production changes and messages to people come next. | Approve other held calls one at a time. | [intent grants](intent-grants.md#later) | +| A grant reads an integer `amount` as the currency's smallest unit (cents, a token's base unit) and `amount_cents` as hundredths of its whole unit. A tool that takes whole dollars in `amount` is read 100 times smaller. | The arguments carry no unit; the smallest unit is Stripe's convention, and the one a grant compares exactly. | Before you grant, read the `grant` line of `tracekit approvals show`: it prints the amount as the grant reads it. If it reads wrong, approve that tool's calls one at a time. | [what a grant reads](intent-grants.md#what-a-grant-reads) | +| A payment typed into a shell command (`curl` to a payments API, the Stripe CLI) stays held. | Its amount and payee are text in a command line; a grant reads a tool's structured arguments. | Pay through an MCP or framework tool with structured arguments. | [what a grant reads](intent-grants.md#what-a-grant-reads) | +| On the dev signer, any identity of the run's tenant may issue a grant, as it may answer the run's approvals, and the agent runs as your user, so it could issue one (recorded self-approved). | The dev signer can't tell you from your agent. The dev pack denies every `tracekit grant` and `approvals approve` command the agent runs (`TK-D012`) as a tripwire; code that calls `grant_issue` itself (`python -c`, a script) isn't read, as for approvals. | Run [system mode](deploy.md#laptop-system-mode), or a signer with `approvals`, where only a named approver issues grants. | [who may issue](intent-grants.md#who-may-issue-a-grant) | +| A release at T1 rests on the arguments the harness reported: the agent's own process runs the call. | A hook sees a call before it runs; the agent's process runs it. | Run payments through the [tool executor](executor.md) or the [MCP gateway](mcp-gateway.md) (T2): the call runs with the arguments the signer decided. | [records](intent-grants.md#records-and-verification) | +| A payment counts when it is decided, also when the payment then fails. | Counting at the decision keeps two payments at once from spending the same room. | Revoke the grant and issue a new one when failed payments used up its total. | [how the signer decides](intent-grants.md#how-the-signer-decides-a-payment) | +| The fields a release records are the signer's reading of the arguments. The verifier checks them against the grant; checking them against the arguments is a manual step. | The bundle holds the arguments as commitments, which the verifier doesn't open. | Open them with `tracekit signer reveal` and read them with `grants.read` in `tracekit/grants.py`. | [records](intent-grants.md#records-and-verification) | +| Grants know the units of USD, EUR, GBP, INR, CAD, AUD, CHF, SGD, JPY, USDC and USDT: a payment in another currency stays held, and a grant can't be issued in one. | A fixed table in `tracekit/grants.py`, each currency with the digits of its smallest unit. | Ask for the currency you need in an issue. | [what a grant reads](intent-grants.md#what-a-grant-reads) | +| A payment with any argument besides its amount, currency, payee, `description` and `note` stays held: an idempotency key or an invoice id too. | A grant releases only what it reads; an argument it doesn't read may pick what is paid or where the money goes (`memo` routes funds on some chains). | Approve those calls one at a time. | [what a grant reads](intent-grants.md#what-a-grant-reads) | +| The Go verifier in `contrib/` reports the grant records as not interpreted. | It hasn't been ported yet. | Verify with `tracekit verify` or the TypeScript verifier. | [records](intent-grants.md#records-and-verification) | + ## Tracekit Box (experimental) A Tracekit Box daemon named in signer.yaml's `box_daemons` labels its box's run (`ext.box`), and opens each box's agent channel, through which the coding agent's hooks inside the box record its calls as the box's own identity, `box:/`. diff --git a/docs/policy-v2.md b/docs/policy-v2.md index f41ede148..9f6d161fe 100644 --- a/docs/policy-v2.md +++ b/docs/policy-v2.md @@ -138,6 +138,14 @@ Lint errors: `approval.agent` with `passkey: required`, or on a `from: untrusted arguments the agent reported rather than what runs. The signer refuses to start with a policy that has agent rules and no `approvals.agents`. +### Intent grants (`approval.grant`) + +`approval: {grant: payment.send}` lets a person's [intent grant](intent-grants.md) release the rule's held calls within +the grant's limits; anything else the rule holds stays held. A call held by several rules is released only when each +of them (flags aside) opts in. Lint error: `approval.grant` with `passkey: required`. `TK-GRANT` is the signer's id for +a call a grant released, so no rule may use it. The shipped packs opt in `TK-A044` (coding) and `TK-M001` and +`TK-M002` (server). + `policy_hash` is `sha256:` of the compiled policy as sorted-key, compact JSON (`policy2.compile.canonical`). ## Classes and fields diff --git a/docs/support.md b/docs/support.md index 0e70cd234..edf73dfaf 100644 --- a/docs/support.md +++ b/docs/support.md @@ -49,6 +49,7 @@ experimental. | Verified tool results (signer.yaml `verify_tool_results`) | [gateway](gateway.md#verified-tool-results) | | Tracekit Box's agent channel (signer.yaml `box_daemons`, `channel_open`, `ext.box` and verify's `boxed agent` line; tested against a stand-in daemon on the signer's Unix socket, not Tracekit Box itself) | [limits](limits.md#tracekit-box-experimental) | | The kernel sensor import (`tracekit sensor import`), Linux: checked against event lines shaped as Tetragon's and Falco's source writes them, not a live sensor | [Tetragon](integrations/tetragon.md), [Falco](integrations/falco.md) | +| Intent grants: `tracekit grant`, `tracekit approvals approve --grant`, the `grant_*` RPCs, signer.yaml `grants`, a rule's `approval: {grant: ...}` and verify's `intent grants` line | [intent grants](intent-grants.md) | | OTLP import and export, the v1 OTLP receiver, ingest gateway and model proxy (these three need `--experimental`) | [OpenTelemetry](otel.md) | | Witnesses, the public witness, Rekor and RFC 3161 anchors, `tracekit monitor`, the record-key issuer, external and KMS log keys, SLH-DSA hybrid checkpoints | [witnesses](witnesses.md), [monitor](monitor.md), [issuer](issuer.md) | | Cost, usage, coverage and findings (`tracekit cost`, `tracekit analyze`), and the intent, reasoning and action checks of v2 runs (`tracekit analyze --v2`, signed into a findings run with `review_finding`; `--review`, a reviewer model) | [findings](findings.md) | diff --git a/docs/verdicts.md b/docs/verdicts.md index 6235b4b38..d8c0a77c8 100644 --- a/docs/verdicts.md +++ b/docs/verdicts.md @@ -245,6 +245,7 @@ is `witnessed` plus a fresh, conflict-free report of a monitor your trust config | `tiers` (`decided and completed by different capture paths`) | a tool call's decision and result records name different `source` or `tier`, for example a call a gateway decided (T2) completed by the agent, which a current signer refuses; each such call is listed and counted at the weaker tier | which record is false, or that the call didn't run | | `gateway amendments` | `ext.amended` is on a record other than an LLM gateway's model request, or isn't a list of JSON pointers: the signer never writes that. It passes otherwise: `gateway amended n request(s) to show reasoning (/thinking/display: n)`, the requests the [gateway](gateway.md#readable-reasoning) sent with a field changed so the provider shows reasoning, each record committing to the request as sent | that the records are false: they verified like every other | | `openshell policy` | `ext.openshell.policy` is on anything but a signer-written `ext` record with OpenShell's name for the change and the observer: the signer never writes that. It passes otherwise: `OpenShell changed the sandbox policy or configuration n time(s) (approved: n, ...), as OpenShell reported it`, from the [OpenShell middleware's OCSF import](integrations/openshell.md#openshells-ocsf-events) | that OpenShell's report is true, or complete: it is what OpenShell said | +| `intent grants` | fails when a released payment breaks its grant: outside its caveats or past a limit, after the grant was revoked or expired, of a tool the grant doesn't cover, an amount or totals that aren't whole numbers, totals that don't add up, or a tier that isn't its record's; when its grant isn't in the bundle earlier in its run, or is only in a grant record no signer writes; and when a decision flagged `TK-GRANT` names no grant. Warns when any other grant, revocation or release record isn't as the signer writes them (a grant that isn't a person's for its own run, with no release under it). It passes otherwise: `n grant(s) by alice` (and how many were self-approved, issued by the run's own user, which the agent can be), the revocations, and the payments released at T2 and at T1, each re-checked against its grant and its running totals ([intent grants](intent-grants.md)) | that a payment was right to make: it was within what the person granted | | `boxed agent` | `ext.box` is on anything but a `run.registered` under a uid's identity, or isn't a box label the signer writes ({id, image_digest, allow, engine `firecracker`, channel `agent`}): no claim is made, and the short result says `NOT SHOWN`. It passes otherwise, for the runs the bundle holds (not a run-set's records of other runs) of a [Tracekit Box](limits.md#tracekit-box-experimental) box and its agent's channel: `PROOF AGAINST THE BOXED AGENT (micro-VM): the signing key was outside its box for this run.`, then that an agent run's records are its own account and the box's doors (its connections and file writes) are the record of what it could do, to review what the box wrote before running it, and `anchored by at