Specification

Version 1.0.0, 2026-11-12.

This specification states what Keelson signs, logs and enforces. It describes the deployed system and marks the one part still being built. Each section names the component that implements it; that component's README is the detailed reference. A mandate is what the user allows an agent to buy. A countersign is the TEE legs' signed decision on one cart. An Alibi is the verifiable record of that decision. A verdict is the TEE legs' signed attribution of a dispute.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

1. Primitives

The TypeScript and Rust implementations MUST produce the same output for every vector in packages/core/test/vectors.

2. Mandate

A mandate is a keelson.mandate.1 JSON payload, defined by the schema in packages/mandate/src/schema.ts. A verifier MUST reject a payload that has an unknown key or an unknown constraint type, a string that contains a Unicode control (Cc) or format (Cf) character, or a lifetime (exp − iat) longer than 30 days.

Selective disclosure. The payload is issued as SD-JWT (RFC 9901), so an Alibi can show an arbiter one field without the others.

Signing. Let H_sd = H("keelson/mandate/v1", payload_SD). The passkey challenge MUST be M = SHA-256("keelson/mandate-challenge/v1" ‖ 0x00 ‖ H_sd ‖ C_m). The user signs M with a WebAuthn passkey on the RP ID keelson.finance, through Secure Payment Confirmation where the browser supports it. What the user signs MUST be the card rendered from the payload, never a model's summary of it. When embed is present, the assertion MUST name that top-level origin.

Field colors. Each field of the card says who answers for it:

Evidence MAY raise a field's color: a merchant-signed checkout, or a zkTLS proof of the field.

Compilation. packages/compiler turns a natural-language request into a mandate. Two models draft it independently. The merge MUST NOT be wider than either draft, and a field the drafts disagree on MUST be shown gray. A third model checks the card against the request. Nothing a model returns is signed without the user's passkey.

3. Policy

Mandate rules are a Cedar policy set, in engine/policy. The evaluator MUST fail closed: an error is a DENY. Every decision records a keelson.eval/1 trace whose hash is evalHash. Extras a user adds MUST compile only to forbid, so they can narrow a mandate and never widen it.

cedar-policy-symcc proves that the policy set states the rules in engine/policy/policy/spec.cedar. The proof bundle is committed, checked for freshness in CI and attested on main. The WebAssembly evaluator in packages/policy is pinned byte for byte to the Rust one by a parity job.

4. Countersign

The engine runs in two TEE legs built from one reproducible image, in engine/tee:

• Leg A, Intel TDX on Phala Cloud, holds the KMS root, issues credentials, keeps the budget ledger, reads PayPal and produces the Observation of each countersign.
• Leg B, an AWS Nitro Enclave with no network and no KMS root, verifies everything again and countersigns over leg A's Observation. Leg B MUST NOT trust leg A's decision; it re-evaluates the request itself.

Each leg MUST sign every decision, ALLOW or DENY, with a secp256k1 key generated in RAM at boot. The signed message is the EIP-712 Countersign:

Countersign(bytes32 requestId, bytes32 mandateHash, bytes32 mandateCommitment, bytes32 cartHash,
            uint256 agentId, bytes32 merchantId, uint64 amount, uint16 currency, uint8 category,
            bytes32 evidenceRoot, bytes32 evalHash, bytes32 policySetHash, uint8 decision,
            uint32 failedFieldsMask, uint40 issuedAt, uint40 expiresAt)

failedFieldsMask is pinned by packages/core/test/vectors/failed-fields-mask.json.

Idempotence. A request id is answered once per mandate. Retrying the same input MUST return the same countersign, and any other input under that id, including the same id on another mandate, MUST fail with replay (engine/tee/src/budget.rs).

Budget. Leg A's available budget is max − captured − live reservations, with captured taken from its own PayPal read. Leg A MUST NOT ALLOW a cart whose total exceeds it.

Two of two. A purchase is countersigned by both legs. When leg B is unreachable, leg A MAY sign alone; every artifact of that purchase MUST then say degraded. On chain, a degraded result waits a longer veto window (DEGRADED_WINDOW, 72 hours, in contracts/src/KeelsonBondVault.sol). Vectors: packages/core/test/vectors/countersign-2of2.json, packages/core/test/vectors/countersign-degraded.json.

Attestation binding. Each leg's attestation MUST carry

report_data = keccak256(abi.encode(keccak256("KEELSON_TEE_SIGNER_V1"), chainid, bondVault, teeKind,
              signer, policySetHash, engineBuildId, bootEpoch, issuerJwkThumbprint)) ‖ blockHash

with blockHash from a recent Arbitrum block (engine/tee/src/report_data.rs). VerdictVerifier MUST register a signer only from such an attestation, under an allowed measurement, and only for 72 hours (SIGNER_TTL in contracts/src/VerdictVerifier.sol).

5. Evidence

What the agent saw is sealed item by item, in packages/evidence: the product and cart data, what the model received, a DOM snapshot in keelson-dom-v1, the accessibility tree, a screenshot, MHTML, a normalized HAR, outside observations and the PayPal amount countersigned.

Each item is a salted leaf (keelson/evidence-item/v1) of an RFC 6962 Merkle tree whose root is evidenceRoot, so one item can be shown without the others and an unrevealed item cannot be guessed from its hash. PII MUST be redacted from every public item; the originals are kept encrypted. A hidden-text detector records text a page hid from people but showed to the agent.

Two kinds of outside testimony MAY be attached:

• Channel3, a third party's live product data, compared field by field with what the agent saw. It is testimony, not proof.
• TLSNotary: leg A notarizes a TLS session with the store's public product endpoint and signs a WebFact (hostHash, urlPathHash, tCapture, rangeCommitment, attId). TLSNotary is alpha software.

6. Alibi

An Alibi is the bundle that lets anyone check a purchase without trusting Keelson. It is built by packages/alibi and checked by apps/verify. It holds the log leaf, its inclusion proof, the on-chain anchor, both TEE attestations and signatures, the selectively disclosed mandate, the evidence manifest, the evaluation trace, optional ZK proofs, card records and PayPal references. It is served as JSON, as a .alibi file, and as a PDF with the file embedded and a QR link to verify.keelson.finance. The Alibi hash fields are pinned by packages/core/test/vectors/alibi.json.

A verifier MUST check an Alibi against trust roots pinned in its code, never against roots the Alibi or a Keelson server supplies: the log keys and witness quorum, the TSA roots, Intel's and AWS's attestation roots, the allowed engine builds, and the contract addresses. The reference verifier runs in the browser and reads the chain once, in one Multicall. A verifier MUST NOT report an Alibi as valid when any check fails. Each check, with a command that runs it, is listed in Verify every claim.

7. Transparency log

Every countersign, ALLOW or DENY, MUST be a leaf of the public log in services/log:

leaf      = "keelson.finance/alibi/v1\n" ‖ JCS(object)
leaf_hash = SHA-256(0x00 ‖ leaf)

The object MUST hold hashes and ids only: agent_id, alibi_id, cart_hash, countersign_digest, eval_hash, evidence_root, issued_at, mandate_commitment, mandate_hash, measurements, mode, paypal_ref_commit, policy_set_hash, optional prev_alibi_by_user, and tee_sigs. A user's kill switch is logged as a keelson.finance/stop/v1 leaf.

8. PayPal

PayPal is the rail. Keelson uses the Orders v2 and Payments v2 APIs with intent: AUTHORIZE, through packages/paypal and services/api:

1. Hold. One AUTHORIZE order per mandate for its cap, approved with the JavaScript SDK v6, then authorized. A mandate on the PayPal rail that allows several merchants MUST instead hold each cart on its own (one order per cart), since one authorization pays one payee.
2. Capture. Each countersigned ALLOW MUST be captured from the hold for exactly the countersigned total. final_capture MUST be true only for the capture that uses up the hold, or for a per-cart hold. invoice_id names the purchase, and PayPal-Request-Id MUST be derived from the countersign digest, so a retry cannot charge twice.
3. Close. The remainder MUST be voided when the mandate ends. An authorization older than three days, the end of PayPal's honor period, is reauthorized.
4. Webhooks. A webhook MUST be verified before it is used, and it only points at a resource: Keelson MUST act on an authenticated GET of that resource, never on the notification body.
5. Disputes are read, evaluated and answered through the Disputes API (section 10).
6. Refunds and Payouts MUST carry a verdict reference and a PayPal-Request-Id derived from it, so a retry is the same operation.

The identifiers Keelson writes into PayPal objects (custom_id, invoice_id, PayPal-Request-Id and the references on refunds and payouts) are an open convention, specified in the PayPal Agent Mandate Extension.

Card rail. A mandate with payment.rail: card holds the user's budget on PayPal, on Keelson's account, which pays the card network; merchants that take cards are paid through a single-use card. The card MUST be issued only after both legs ALLOW, MUST be capped at the countersigned total, and MUST be limited to the mandate's merchant category codes and country. Every authorization the card network sends MUST be checked again by both legs (POST /v1/card/authorize), and the settled charge is captured from the PayPal hold. See card mandates.

9. On chain

Contracts are deployed on Arbitrum Sepolia from contracts. They are unaudited.

Governance. A timelock (5 minutes on testnets, 48 hours on Arbitrum One) is the only admin of the access manager. A 2-of-3 guardian Safe can cancel timelock operations, veto slashes and revoke signers. A relayer pays gas, so operators, merchants and buyers never hold ETH.

10. Disputes and attribution

A PayPal dispute is attributed by an ordered decision list compiled to Cedar, with symcc proofs that it is total, exclusive and reachable (engine/policy). Attribution fails closed.

Both TEE legs sign the EIP-712 Verdict:

Verdict(bytes32 disputeId, bytes32 coverageId, uint256 agentId, address payee, uint96 amount,
        uint8 ruleId, uint8 liable, uint8 fieldId, bytes32 evidenceHash, bytes32 inputsHash,
        bytes32 policySetHash, bytes32 checkpointRoot, uint40 issuedAt, uint40 deadline)

disputeId = keccak256(paypalDisputeId ‖ coverageId) is a nullifier: a verdict MUST NOT be applied twice for one disputeId. A merchant is settled in PYUSD on chain or by PayPal Payout, as it chooses. PayPal adjudicates the dispute; the verdict decides the evidence, the slash and the warranty.

11. Zero-knowledge circuits

Noir circuits proved with Barretenberg UltraHonk, in circuits:

12. Agents

Agents reach Keelson over REST or MCP (https://api.keelson.finance/mcp, Streamable HTTP), an OAuth 2.1 protected resource (services/mcp). An operator's agent uses client credentials and closes mandates with its own key. A host acting for a user uses the authorization code grant with PKCE and MUST buy only under mandates the user approved for it. The kill switch, per-host disconnects, and push and email alerts are described in how it works. The OpenAPI document is in openapi.

13. Risk

Every operator has a trust grade, a premium and a minimum bond, set by the red team's results and its own record (GET /v1/operators/{agentId}/grade). The risk model is described in services/api/README.md.

14. Limits

What Keelson does not protect against is stated in the threat model.