@fairseal/verify

@fairseal/verify

Independent, fail-closed verification for FairSeal receipts (VEO objects).

Every check runs from public inputs. You do not need to trust FairSeal — or this package's authors — to re-verify a receipt: signatures verify against the keys embedded or supplied, and anchors verify against Base mainnet through any RPC you choose.

npm install @fairseal/verify

Requires Node >= 18. Both ESM (import) and CJS (require) are supported on all Node versions from 18 onward. @noble v2 cryptography is bundled into the dist so CJS consumers do not need --experimental-require-module.

Quick start (VEO-2)

import { verifyVEO } from '@fairseal/verify';

const result = await verifyVEO(receipt); // receipt = a VEO-2 object

if (result.valid) {
  // ALL applicable checks passed AND (if an anchor is present)
  // the anchor was verified on-chain.
} else {
  console.log(result.checks);   // structure / integrity / signature / anchor
  console.log(result.errors);   // machine-readable failure reasons
}

Result semantics (fail-closed)

Field	Meaning
valid	true only when all applicable checks pass and, if an anchor is present, it verified on-chain. Never true for an anchored object whose chain check was skipped or failed.
structural	Structure + integrity + signature only. Can be true while valid is false (anchor pending/failed).
anchored	true (verified on-chain) / false (check ran and failed) / "unknown" (chain unreachable) / "not_present" (no anchor on this object) / "not_checked" (structuralOnly mode)
checks.*	Each check is pass, fail, or skipped with a detail string.

"We could not verify" and "we verified it is wrong" are different states — this package never collapses them.

Offline pre-screening

const result = await verifyVEO(receipt, { structuralOnly: true });
// result.anchored === 'not_checked'
// result.valid will be false when an anchor is present:
// structurally-valid-but-not-chain-verified is NOT called "valid".

VEO-1 receipts (EIP-191 / secp256k1)

FairSeal API receipts (VEO-1) are signed with personal_sign (EIP-191) over a canonical serialization:

import { verifyEIP191Signature, canonicalizeVEO1 } from '@fairseal/verify';

const check = verifyEIP191Signature(veo1Object);
// recovers the secp256k1 signer address and compares to the declared signer

Merkle and on-chain anchor utilities

import { verifyMerklePath, verifyAnchor, DEFAULT_CONTRACT_ADDRESSES } from '@fairseal/verify';

// Pure sha256 fold — no network needed:
const ok = verifyMerklePath(leafHash, merklePath, expectedRoot);

// Confirm the batch root on Base mainnet via any RPC you trust:
const anchor = await verifyAnchor(anchorInfo, { rpcUrl: 'https://mainnet.base.org' });

verifyMerklePath alone proves inclusion against a root offline; it does not prove the root is on-chain. Use verifyAnchor (or call MerkleAnchor.getBatchRoot on any Base RPC yourself) for chain confirmation.

What verification proves — and what it does not

Proves:

• the object's content matches its hashes (integrity),
• the declared signer produced the signature (EIP-191 secp256k1 for VEO-1, Ed25519 for VEO-2),
• when anchored: the receipt's hash is included in a Merkle batch whose root exists on Base mainnet.

Does not prove:

• that the decision or output described by the receipt was correct, safe, or compliant,
• that the issuing agent recorded all of its actions (capture completeness),
• signer identity beyond the key itself, unless you bind keys to identities out-of-band.

A fully receipted agent can still be wrong. Audit reasoning separately.

API surface

• verifyVEO(veo, options) / verifyVEOSync(veo, options) — top-level VEO-2 verification
• verifyStructure, verifyIntegrity, verifySignature, isSigned — individual VEO-2 checks
• verifyEIP191Signature, canonicalizeVEO1, eip191Hash, pubKeyToAddress — VEO-1
• computeMerkleRoot, verifyMerklePath, normalizeHex, toBytes32Hex — Merkle
• verifyAnchor, DEFAULT_CONTRACT_ADDRESSES, DEFAULT_RPC_URLS — on-chain anchor
• RPC constants: TOPIC_BATCH_ANCHORED, SELECTOR_GET_BATCH_ROOT, SELECTOR_BATCH_EXISTS

Links

• Verify in a browser: https://verify.fairseal.io
• API docs: https://api.fairseal.io/docs
• Site: https://fairseal.io

License

MIT