What this is

Veto issues Mandate JWTs when it approves an agent's spend — single-use, scoped permission slips that say "this agent can pay this recipient up to this amount within this expiry window." The mandate is signed with Ed25519.

This package is what you import to verify a mandate without contacting Veto's runtime — the JWKS + signature check happens locally. Use it from agent runtimes, wallets, settlement services, anything that needs trust signal before broadcasting a transaction.

For chain-level verification, see veto-protocol/contracts (the same mandate is also issued as an EIP-712 secp256k1 signature for ecrecover).

Install

npm install @veto-protocol/mandate-verifier
# or pnpm add @veto-protocol/mandate-verifier
# or bun add @veto-protocol/mandate-verifier

Quick start

import { createMandateVerifier } from "@veto-protocol/mandate-verifier";

const verifier = createMandateVerifier({
  jwksUrl: "https://veto-ai.com/.well-known/jwks.json",
});

// `mandate` is the JWS string returned in Veto's authorize response.
const payload = await verifier.verify(mandate, {
  expectedRecipient: "0x4242…",
  expectedAmount: 50,                  // refuses if mandate cap < 50
  expectedChain: "base",
  expectedAction: "crypto_transfer",
});

// payload is the decoded MandatePayload. Throws on any failure.
console.log(payload.scope, payload.jti, payload.exp);

If any check fails (signature, expiry, recipient, amount, chain, action, typ), verify throws a MandateVerificationError with a stable code you can branch on (EXPIRED, RECIPIENT_MISMATCH, AMOUNT_OVER_CAP, BAD_SIGNATURE, WRONG_TYP, …).

What's in a mandate

{
  "iss": "veto",
  "sub": "<veto-tx-uuid>",
  "jti": "<single-use-nonce>",
  "iat": 1714742000,
  "exp": 1714742600,
  "agent_id": "<uuid>",
  "scope": {
    "action": "payment",
    "recipient": "api.openai.com",
    "max_amount": 50,
    "currency": "USD",
    "chain": null,
    "single_use": true
  },
  "policy": { "id": "<uuid>", "version_number": 7, "hash": "<sha256>" }
}

The header carries typ: "mandate+jwt", distinguishing mandates from receipts (typ: "JWT"). A receipt JWS will be rejected with WRONG_TYP here — different artifacts with different lifecycles.

Error codes

MandateVerificationError.code is one of:

| Code | Meaning | |------|---------| | MALFORMED / MALFORMED_HEADER / MALFORMED_SIG / MALFORMED_PAYLOAD | Structural issue with the JWS string | | WRONG_ALG / WRONG_TYP / WRONG_ISS | Header or claim doesn't match Veto mandate format | | MISSING_KID / UNKNOWN_KID | Header missing kid, or kid not in JWKS (after refetch) | | BAD_SIGNATURE | Ed25519 signature verification failed | | MISSING_EXP | Mandate has no expiry | | EXPIRED | now >= exp | | FUTURE_IAT | Mandate issued in the future (allowing for clock-skew tolerance) | | MISSING_SCOPE | Mandate missing scope | | RECIPIENT_MISMATCH | scope.recipient doesn't match expectedRecipient | | AMOUNT_OVER_CAP | expectedAmount exceeds scope.max_amount | | CHAIN_MISMATCH | scope.chain doesn't match expectedChain | | ACTION_MISMATCH | scope.action doesn't match expectedAction |

Replay prevention

The verifier validates structure, signature, expiry, and scope. It does NOT track spent jti values — that's the wallet/contract's job. A mandate with single_use: true MUST be enforced once, and reused mandates MUST be rejected.

The on-chain enforcement primitive (veto-protocol/contracts) does this via a mapping(bytes32 => bool) spent lookup. If you're integrating off-chain, keep your own Set<jti> and reject duplicates.

Inline JWKS (tests / air-gapped)

const verifier = createMandateVerifier({
  jwks: { keys: [{ kty: "OKP", crv: "Ed25519", kid: "...", x: "..." }] },
});

JWKS fetcher caches in-memory (1h TTL by default), coalesces concurrent calls, and auto-refetches once on a kid miss to handle operator key rotation. Override the fetch implementation via fetchImpl for tests or non-fetch environments.

Tests

npm test

14 tests:

• 12 in-process — sign + verify with a fresh Ed25519 keypair, every error-code branch
• 2 wire-compat — verify against a fixture signed by the actual Veto Django backend (locks byte-level interop, regenerable)

Public artifacts

| Artifact | Repository | |----------|------------| | Verifier source (this repo) | veto-protocol/mandate-verifier | | Veto CLI | veto-protocol/veto-cli | | Smart wallet contract | veto-protocol/contracts | | Open policy schema (APPS) | veto-protocol/x402-policy-schema | | Documentation | veto-protocol/docs | | Public JWKS | https://veto-ai.com/.well-known/jwks.json | | Live contract on Base Sepolia | https://sepolia.basescan.org/address/0xCBbbC4b924AF40D29f135c3a88b6F650d55d92c5 |

License

MIT.

Verify a Veto mandate offline. Any agent. Any payment rail. Safe transactions.

Built by Investech Global LLC · part of the veto-protocol family.