agent-receipt-verify 0.2.2 → 0.2.4

package/README.md

@@ -77,11 +77,23 @@ vectors, that is interop. One implementation agreeing with itself proves nothing
 | x402 settlement link (§5.6.4, same proposal) | own tests plus three live settlements | 22 offline, 3 live | yes, each resolves to its own settlement |
 
 ```sh
-npm test      # all of the above, no network, no keys
+npm test      # all of the above. No account, no key, and nobody else's server
 ```
 
-Node built-ins only, apart from keccak256. Only the settlement link below touches
-the network, and then only a public read-only RPC.
+Node built-ins only, apart from keccak256. Two honest footnotes, because "no network"
+was not quite true and is the kind of claim this package should not make loosely:
+
+- One case dials a closed port on localhost on purpose, to prove that a dead address
+  reports not-measured instead of crashing the tool. That is a socket, but it leaves
+  the machine alone and reaches no third party.
+- Until recently the suite also fetched a live discovery index belonging to someone
+  else, roughly twenty thousand entries, because one test handed an unknown flag to
+  `census` and `census` ignored unknown flags and went to work. That flag is now
+  refused, so the suite finishes in about eleven seconds and contacts nobody. A single
+  index round alone used to take over thirty.
+
+Only the settlement link below reaches a real network, and then only a public,
+read-only RPC.
 
 Confirmed from the other side, which matters more than the table: the author of
 the x402 specification ran their own implementation, which shares no code with
@@ -98,6 +110,7 @@ taken on trust:
 ```sh
 npx -y agent-receipt-verify kanon
 npx -y agent-receipt-verify beleid
+npx -y agent-receipt-verify link-vectors
 ```
 
 The first checks our EIP-3009 verifier against the ten published vectors of
@@ -107,6 +120,28 @@ about one nonce reused across two payers. Those are the two open questions in
 [x402#2725](https://github.com/x402-foundation/x402/issues/2725), and the command
 prints exactly where the two possible answers diverge and where they do not.
 
+The third runs twelve vectors for the half AFTER paying: does this receipt belong to
+that one settlement. Eleven of them need no network at all; the twelfth reads the chain
+and is marked and skipped rather than reported as a failure, because a check that could
+not run says nothing about the receipt. The same twelve also exist in the field layout
+of the Kanon vectors, in `vectors/settlement-link-kanon`, so the two corpora can sit
+side by side.
+
+Two more commands, both of which measure other people's endpoints rather than our own,
+and both read-only:
+
+```sh
+npx -y agent-receipt-verify census [out.json]
+npx -y agent-receipt-verify liveness [out.json]
+```
+
+`census` counts a discovery index per HOST rather than per resource, so a party with
+three hundred paths does not outweigh three hundred parties with one. `liveness` takes
+that census and asks each host whether it still answers 402 today, because a
+registration in an index is not a promise that the endpoint is alive. Both are slow by
+design: they pause between requests, because the hosts in that list did not ask to be
+measured.
+
 ## Linking a receipt to its settlement
 
 A receipt with an empty `transaction` field can be matched to a payment only by

package/bin/cli.mjs

@@ -57,6 +57,20 @@ function gebruik() {
   console.log('        the same ten vectors under both amount policies, plus the two cases no')
   console.log('        published vector covers: overpayment, and one nonce across two payers.')
   console.log('        Those two are the open questions in x402 issue 2725.')
+  console.log('')
+  console.log('  npx github:holistis/agent-receipt-verify liveness [uit.json]')
+  console.log('        takes the census and asks each host whether it still answers 402 today.')
+  console.log('        A registration in an index is not a promise that the endpoint is alive.')
+  console.log('')
+  console.log('  npx github:holistis/agent-receipt-verify verify-delivery --answer=<file> --endpoint=<url>')
+  console.log('        reads, at the source, whether a paid answer is TRUE. The location is')
+  console.log('        DERIVED from --endpoint and never taken from the answer, because a seller')
+  console.log('        who picks both the token and the place can stage any outcome.')
+  console.log('')
+  console.log('  npx github:holistis/agent-receipt-verify link-vectors')
+  console.log('        twelve vectors for the half AFTER paying: does this receipt belong to')
+  console.log('        that one settlement? Eleven run offline, the chain-reading one is')
+  console.log('        marked and skipped rather than failed.')
 }
 
 // Het argument bepaalt welke module draait. De modules zijn ook los te draaien en te
@@ -70,6 +84,8 @@ const onderdelen = {
   liveness: '../src/x402-index-liveness.mjs',
   kanon: '../src/eip3009-autorisatie.mjs',
   beleid: '../bench/eip3009-beleid.mjs',
+  'link-vectors': '../src/settlement-link-vectors.mjs',
+  'verify-delivery': '../src/verify-delivery.mjs',
 }
 
 if (!eerste || eerste === '--help' || eerste === '-h' || eerste === 'help') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-receipt-verify",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Checks x402 endpoint conformance before an agent pays, and links the receipt to its settlement.",
   "license": "Apache-2.0",
   "type": "module",
@@ -8,7 +8,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node test/interop.mjs && node test/canonical.mjs && node test/link-onchain.mjs && node test/profiel.mjs && node test/eip3009.mjs && node test/conformance.mjs && node test/jws-offer.mjs && node test/census.mjs && node test/poortwachters.mjs && node test/metingen-bundel.mjs && node test/mcp-server.mjs && node test/cli.mjs && node test/bundel.mjs",
+    "test": "node test/interop.mjs && node test/canonical.mjs && node test/link-onchain.mjs && node test/profiel.mjs && node test/eip3009.mjs && node test/conformance.mjs && node test/jws-offer.mjs && node test/census.mjs && node test/poortwachters.mjs && node test/metingen-bundel.mjs && node test/mcp-server.mjs && node test/cli.mjs && node test/bundel.mjs && node test/settlement-link-vectors.mjs && node test/naar-kanon-vorm.mjs && node test/verify-delivery.mjs",
     "link-example": "node src/x402-link-onchain.mjs --receipt=examples/receipt-live-base-sepolia.json && node src/x402-link-onchain.mjs --receipt=examples/receipt-live-base-sepolia-2.json && node src/x402-link-onchain.mjs --receipt=examples/receipt-live-base-sepolia-3.json",
     "conformance": "node src/x402-conformance-check.mjs",
     "bench": "node bench/robustness.mjs",
@@ -19,7 +19,10 @@
     "mcp": "node src/mcp-server.mjs",
     "bundel": "node tools/bundel-bouw.mjs build/bundle",
     "kanon": "node src/eip3009-autorisatie.mjs --vectoren",
-    "bench-eip3009": "node bench/eip3009-beleid.mjs"
+    "bench-eip3009": "node bench/eip3009-beleid.mjs",
+    "link-vectors": "node src/settlement-link-vectors.mjs",
+    "verify-delivery": "node src/verify-delivery.mjs",
+    "kanon-vorm": "node tools/naar-kanon-vorm.mjs"
   },
   "optionalDependencies": {
     "ethers": "^6.17.0"

package/src/settlement-link-vectors.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Draait de afrekening-vectoren: hoort dit bonnetje bij die ene betaling?
+//
+// WAAROM DIT EEN LOPER IS EN NIET EEN DOCUMENT. Een vectorbestand dat niemand kan
+// draaien is een bewering met extra stappen. Dit commando leest de vectoren, rekent elk
+// commitment opnieuw uit, en vergelijkt dat met wat er verwacht wordt. Een vreemde
+// draait het zonder account, zonder sleutel, en voor elf van de twaalf gevallen ook
+// zonder internet.
+//
+// DE DRIE UITKOMSTEN, en de derde is het hele punt. LINKED als het commitment op
+// precies een kandidaat opent. NOT_LINKED als er kandidaten waren en geen enkele opent.
+// NOT_MEASURED als er geen kandidatenlijst is VERKREGEN. Dat laatste is geen afkeuring
+// van het bonnetje maar een onvolledige controle, en een woordenlijst met twee waarden
+// kan dat verschil niet uitdrukken. Precies dat gat benoemde de auteur van de
+// kanon-vectoren op 2026-10-17 als iets dat hij wil toevoegen.
+//
+// LET OP HET VERSCHIL TUSSEN LEEG EN AFWEZIG. `candidates: null` betekent dat er geen
+// lijst is opgehaald, `candidates: []` dat er wel een lijst is en die leeg was. Het
+// eerste is NOT_MEASURED, het tweede NOT_LINKED. Een loper die die twee door elkaar
+// haalt, gooit geldige bonnetjes weg bij een haperende RPC.
+//
+// Gebruik:
+//   node src/settlement-link-vectors.mjs            de offline vectoren
+//   npx agent-receipt-verify link-vectors           hetzelfde, als commando
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { berekenCommitment } from './x402-offer-receipt.mjs'
+
+const WORTEL = fileURLToPath(new URL('..', import.meta.url))
+export const VECTORMAP = path.join(WORTEL, 'vectors', 'settlement-link')
+
+/**
+ * Beoordeel een enkele vector, puur rekenkundig.
+ *
+ * Geeft altijd een `outcome` terug uit de drie, nooit een throw voor een gewone
+ * uitkomst: een verifieerder die bij een ongeldig bonnetje crasht, is zelf de storing.
+ */
+/**
+ * Matcht deze kandidaat het commitment? Ja of nee, en nooit iets daartussenin.
+ *
+ * WAAROM DIT EEN BOOLEAN IS EN GEEN WAARDE. De eerste versie van deze reparatie gaf bij
+ * een onberekenbaar veld de TEKENREEKS `0x-niet-te-berekenen` terug, en die werd daarna
+ * vergeleken met het commitment uit het bonnetje. Een foutwaarde die in dezelfde ruimte
+ * leeft als de echte waarde is geen foutwaarde maar een sleutel: een bonnetje dat
+ * precies die tekst als commitment droeg, met een kandidaat die niet te berekenen was,
+ * kwam er als GELINKT uit zonder dat er een byte cryptografie aan te pas kwam. Onze
+ * eigen keuring heeft dat gedraaid, met en zonder hoofdletters, op beide takken van
+ * beoordeelVector. Dat is precies de klasse fout die dit bestand moet uitsluiten, en hij
+ * zat er een uur in.
+ *
+ * `null` teruggeven lost het NIET op, en dat is de reden dat hier een boolean staat:
+ * `String(null)` is de tekenreeks "null", dus een bonnetje met commitment "null" zou
+ * het gat meteen heropenen. De enige vorm die dicht is, is er niets uit laten komen dat
+ * ooit vergeleken wordt. De vergelijking zelf hoort daarom HIER en nergens anders.
+ *
+ * En de oorspronkelijke reden blijft staan: een kapot veld mag de ronde niet omver
+ * trekken. Een onberekenbare kandidaat is geen treffer. Dat is hier de enige betekenis.
+ */
+function kandidaatMatcht(velden, commitment) {
+  if (typeof commitment !== 'string' || !commitment) return false
+  let berekend
+  try {
+    berekend = berekenCommitment(velden)
+  } catch {
+    return false
+  }
+  // berekenCommitment geeft altijd een 0x-sha256 terug of gooit. Deze controle staat er
+  // zodat een toekomstige wijziging daar nooit stil iets anders dan een hash kan laten
+  // doorstromen naar een gelijkheidsvergelijking.
+  if (typeof berekend !== 'string' || !/^0x[0-9a-f]{64}$/i.test(berekend)) return false
+  return berekend.toLowerCase() === commitment.toLowerCase()
+}
+
+/**
+ * Is dit een kandidaat waar uberhaupt iets mee te doen valt?
+ *
+ * Zonder deze zeef overleefde een `null` in de kandidatenlijst de filter (want
+ * `k?.authorizer` is dan gewoon undefined), en als zo'n kandidaat dan matchte, knalde
+ * `passend[0].nonce` met een TypeError. De koptekst van dit bestand belooft letterlijk
+ * dat deze loper niet gooit voor een gewone uitkomst. Gemeten in de eigen keuring.
+ */
+function bruikbareKandidaat(k) {
+  return Boolean(k) && typeof k === 'object' && typeof k.nonce === 'string' && typeof k.authorizer === 'string'
+}
+
+/**
+ * Kunnen wij met ONZE eigen vaste velden uberhaupt een commitment uitrekenen?
+ *
+ * WAAROM DIT APART STAAT VAN DE KANDIDATEN. Een kapotte KANDIDAAT is geen treffer, en
+ * dat is de juiste uitkomst. Een kapot EIGEN veld (een zout of een asset die onze RPC
+ * verkeerd teruggaf) laat elke kandidaat falen, en dan rolt er een stellige "geen enkele
+ * kandidaat opende dit commitment" uit terwijl de waarheid is dat er niets te berekenen
+ * viel. De koptekst van dit bestand noemt dat zelf de ergste fout die deze loper kan
+ * maken: een geldig bonnetje weggooien bij een haperende RPC.
+ *
+ * Deze controle zat al in opentCommitment, en niet hier. Dezelfde commit repareerde de
+ * ene functie en liet de andere staan, en de eigen keuring heeft dat gemeten.
+ */
+function eigenVeldenMeetbaar({ method, asset, salt }) {
+  try {
+    berekenCommitment({ method, asset, authorizer: '0x' + '00'.repeat(20), identifier: '0x' + '00'.repeat(32), salt })
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, reden: 'cannot compute a commitment here: ' + String(e?.message ?? e).slice(0, 90) }
+  }
+}
+
+export function beoordeelVector(v) {
+  if (v.requires_chain_read) return { outcome: 'SKIPPED', reden: 'requires an RPC; run the link command for this one' }
+
+  // Het geval met twee bonnetjes tegelijk: elk moet op zijn eigen kandidaat openen en
+  // op geen enkele andere.
+  if (Array.isArray(v.input?.receipts)) {
+    // GEEN `?? []` HIER. Dat stond er en het maakte van een ONTBREKENDE lijst een LEGE
+    // lijst, dus van NOT_MEASURED een NOT_LINKED. De koptekst van dit bestand noemt dat
+    // zelf de ergste fout die deze loper kan maken, want dan beschuldigt hij een
+    // eerlijke verkoper omdat de keten even niet te lezen was.
+    if (v.input.candidates == null) {
+      return { outcome: 'NOT_MEASURED', reden: 'no candidate set was obtained' }
+    }
+    if (!Array.isArray(v.input.candidates)) {
+      return { outcome: 'NOT_MEASURED', reden: 'the candidate set is not a list' }
+    }
+    const kandidaten = v.input.candidates
+    const mapping = []
+    for (const [i, r] of v.input.receipts.entries()) {
+      const p = r?.receipt?.payload
+      if (!p) return { outcome: 'NOT_MEASURED', reden: `receipt ${i} has no payload` }
+      if (!p.authorizationCommitment) {
+        return { outcome: 'NOT_MEASURED', reden: `receipt ${i} carries no commitment` }
+      }
+      const meetbaar = eigenVeldenMeetbaar({
+        method: p.authorizationMethod ?? 'eip3009',
+        asset: r.asset,
+        salt: r.authorizationSalt,
+      })
+      if (!meetbaar.ok) return { outcome: 'NOT_MEASURED', reden: `receipt ${i}: ` + meetbaar.reden }
+      const passend = kandidaten.filter(bruikbareKandidaat).filter((k) =>
+        kandidaatMatcht({
+          method: p.authorizationMethod ?? 'eip3009',
+          asset: r.asset,
+          authorizer: k.authorizer,
+          identifier: k.nonce,
+          salt: r.authorizationSalt,
+        }, p.authorizationCommitment))
+      if (passend.length !== 1) {
+        return { outcome: 'NOT_LINKED', reden: `receipt ${i} opened on ${passend.length} candidates, expected exactly one` }
+      }
+      mapping.push({ receipt_index: i, identifier: passend[0].nonce })
+    }
+    return { outcome: 'LINKED', mapping }
+  }
+
+  const p = v.input?.receipt?.payload
+  if (!p) return { outcome: 'NOT_MEASURED', reden: 'no receipt payload in the vector' }
+  if (!p.authorizationCommitment) {
+    // Een bonnetje van versie 1 draagt geen commitment. Dat is geen fout van het
+    // bonnetje en ook geen afkeuring, er valt alleen niets te openen.
+    return { outcome: 'NOT_MEASURED', reden: 'receipt is version 1 and carries no commitment' }
+  }
+
+  const kandidaten = v.input.candidates
+  if (kandidaten == null) return { outcome: 'NOT_MEASURED', reden: 'no candidate set was obtained' }
+  // Een lijst die geen lijst is, is ook geen meting. Zonder deze regel gooide .filter
+  // en ging de hele ronde eraan.
+  if (!Array.isArray(kandidaten)) return { outcome: 'NOT_MEASURED', reden: 'the candidate set is not a list' }
+
+  const meetbaar = eigenVeldenMeetbaar({
+    method: p.authorizationMethod ?? 'eip3009',
+    asset: v.input.asset,
+    salt: v.input.authorizationSalt,
+  })
+  if (!meetbaar.ok) return { outcome: 'NOT_MEASURED', reden: meetbaar.reden }
+
+  const passend = kandidaten.filter(bruikbareKandidaat).filter((k) =>
+    kandidaatMatcht({
+      method: p.authorizationMethod ?? 'eip3009',
+      asset: v.input.asset,
+      authorizer: k.authorizer,
+      identifier: k.nonce,
+      salt: v.input.authorizationSalt,
+    }, p.authorizationCommitment))
+
+  if (passend.length === 1) return { outcome: 'LINKED', identifier: passend[0].nonce }
+  if (passend.length === 0) return { outcome: 'NOT_LINKED', reden: `none of ${kandidaten.length} candidates opened the commitment` }
+  return { outcome: 'AMBIGUOUS', reden: `${passend.length} candidates opened the same commitment, which a random 32 byte salt should make practically impossible` }
+}
+
+export function laadVectoren(map = VECTORMAP) {
+  if (!fs.existsSync(map)) return []
+  return fs.readdirSync(map).filter((f) => f.endsWith('.json')).sort()
+    .map((f) => ({ bestand: f, ...JSON.parse(fs.readFileSync(path.join(map, f), 'utf8')) }))
+}
+
+const ditBestand = fileURLToPath(import.meta.url)
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(ditBestand)) {
+  const vectoren = laadVectoren()
+  if (!vectoren.length) {
+    console.error('no vectors found in vectors/settlement-link')
+    process.exitCode = 1
+  } else {
+    console.log('settlement-link vectors: does this receipt belong to that one payment?')
+    console.log('')
+    let goed = 0, fout = 0, overgeslagen = 0
+    for (const v of vectoren) {
+      const u = beoordeelVector(v)
+      if (u.outcome === 'SKIPPED') {
+        overgeslagen++
+        console.log(`  skip  ${v.id}`)
+        console.log(`        ${u.reden}`)
+        continue
+      }
+      // Een vector zonder verwachting is een kapotte vector, geen reden om de hele
+      // ronde af te breken. Zonder deze regel gooide dit een TypeError en werd geen
+      // enkele andere vector meer beoordeeld, ook de twaalf goede niet.
+      if (!v.expected || typeof v.expected.outcome !== 'string') {
+        fout++
+        console.log(`  FAIL  ${v.id ?? v.bestand}`)
+        console.log('        this vector carries no expected outcome, so it cannot be judged')
+        continue
+      }
+      const ok = u.outcome === v.expected.outcome
+      if (ok) goed++; else fout++
+      console.log(`  ${ok ? 'pass' : 'FAIL'}  ${v.id}`)
+      console.log(`        expected ${v.expected.outcome}, got ${u.outcome}${u.reden ? ' (' + u.reden + ')' : ''}`)
+    }
+    console.log('')
+    console.log(`${goed} agree, ${fout} disagree, ${overgeslagen} skipped because they need an RPC`)
+    console.log('')
+    console.log('Every positive case here was re-derived, not copied: the commitment is recomputed')
+    console.log('from tag, method, asset, authorizer, identifier and salt, and compared against the')
+    console.log('authorizationCommitment field carried in the receipt.')
+    console.log('')
+    console.log('What this command does NOT do: it does not check the signature over that receipt.')
+    console.log('So this answers "does this commitment open on that settlement", not "is this')
+    console.log('receipt genuine". For the signature, run the conformance check on the endpoint.')
+    process.exitCode = fout === 0 ? 0 : 1
+  }
+}