@soverai/verify

Independent, zero-dependency verifier for Sovereign Receipts (soverai-receipt/v1).

A Sovereign Receipt is a small, signed JSON document that records exactly what an AI agent did, on whose data, in which jurisdiction, under which policies. The receipt is signed with Ed25519 over a deterministic canonicalization of the payload; anybody — your security team, a regulator, an external auditor — can re-verify it offline, without calling AgentAnywhere Swaraj.

This package is the canonical reference verifier. It runs as a CLI under npx, or as a library in any Node 18.18+ application. It has zero runtime dependencies — only node:crypto and built-in fetch.

Install / run

# One-shot via npx (no install)
npx @soverai/verify path/to/receipt.json

# Or globally
npm install -g @soverai/verify
soverai-verify path/to/receipt.json

CLI

soverai-verify [options] <receipt.json | ->

OPTIONS
  --issuer <url>            Origin to fetch /.well-known/soverai-receipts from.
                            Default: https://sovereign.agentanywhere.ai
  --public-key-b64url <b64> Skip /.well-known and verify against this SPKI
                            Ed25519 public key (offline mode).
  --json                    Print machine-readable JSON output.
  --quiet                   No output; rely on the exit code.
  --help                    Show full usage.

EXIT CODES
  0  verified
  1  signature mismatch / kid unknown / spec mismatch
  2  schema or format error
  3  network error fetching /.well-known
  4  CLI usage error

Examples

# Verify a receipt against the issuing org's published key
soverai-verify receipt.json

# Pipe a receipt downloaded from a regulator share-link
curl -s https://sovereign.agentanywhere.ai/r/abc123.json \
  | soverai-verify --issuer https://sovereign.agentanywhere.ai

# Fully offline — pin the public key explicitly
soverai-verify --public-key-b64url MCowBQYDK2VwAyEA... receipt.json

# Get a JSON result you can grep / log / route on
soverai-verify --json receipt.json | jq '.summary'

Library

import {
  verifyReceipt,
  wellKnownResolver,
  staticKeyResolver,
} from "@soverai/verify";

// Online — fetch the issuer's published JWKS
const resolver = wellKnownResolver("https://sovereign.agentanywhere.ai");
const result = await verifyReceipt(receipt, resolver);

if (result.ok) {
  console.log("verified", result.summary);
} else {
  console.error("verification failed:", result.reason, result.message);
}

VerifyResult is a discriminated union — { ok: true, payload, summary, kid } or { ok: false, reason, message }. Possible reasons:

| Reason | Meaning | | --------------- | -------------------------------------------------------- | | schema | The input is not a valid Sovereign Receipt. | | spec-version | The receipt declares an unsupported spec version. | | kid-unknown | The resolver has no public key for the receipt's kid. | | signature | Ed25519 signature did not verify. | | fetch-failed | Resolver threw (e.g. /.well-known unreachable). | | internal | Anything else, including unexpected exceptions. |

Spec

Public spec, with the canonicalization algorithm and JWKS shape, lives at:

• https://sovereign.agentanywhere.ai/sovereign-receipts
• /.well-known/soverai-receipts on every issuing org's domain

The spec version pinned by this verifier is soverai-receipt/v1.

Security model

• Receipts are signed, not encrypted. A receipt's contents are visible to anyone holding it — that is the entire point. Don't store unredacted PII in a receipt; use the redaction profile.
• The verifier needs the issuer's public key. It fetches it from the issuer's /.well-known/soverai-receipts (online), or you pass it explicitly with --public-key-b64url (offline, e.g. air-gapped).
• Trust is rooted in the public key, not in this package. Independent re-implementations are encouraged. The canonicalization algorithm is fully documented in the spec and trivially auditable.

License

Apache-2.0