agent-receipt-verify 0.2.3 → 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

@@ -58,6 +58,15 @@ function gebruik() {
   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')
@@ -76,6 +85,7 @@ const onderdelen = {
   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.3",
+  "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 && node test/settlement-link-vectors.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",
@@ -20,7 +20,9 @@
     "bundel": "node tools/bundel-bouw.mjs build/bundle",
     "kanon": "node src/eip3009-autorisatie.mjs --vectoren",
     "bench-eip3009": "node bench/eip3009-beleid.mjs",
-    "link-vectors": "node src/settlement-link-vectors.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

@@ -37,24 +37,114 @@ export const VECTORMAP = path.join(WORTEL, 'vectors', 'settlement-link')
  * 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)) {
-    const kandidaten = v.input.candidates ?? []
+    // 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
-      const passend = kandidaten.filter((k) =>
-        String(berekenCommitment({
+      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,
-        })).toLowerCase() === String(p.authorizationCommitment).toLowerCase())
+        }, p.authorizationCommitment))
       if (passend.length !== 1) {
         return { outcome: 'NOT_LINKED', reden: `receipt ${i} opened on ${passend.length} candidates, expected exactly one` }
       }
@@ -73,15 +163,25 @@ export function beoordeelVector(v) {
 
   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((k) =>
-    String(berekenCommitment({
+  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,
-    })).toLowerCase() === String(p.authorizationCommitment).toLowerCase())
+    }, 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` }
@@ -112,6 +212,15 @@ if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(ditBestand
         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}`)
@@ -120,9 +229,13 @@ if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(ditBestand
     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 from the signed receipt, not copied:')
-    console.log('the commitment is recomputed from tag, method, asset, authorizer, identifier and')
-    console.log('salt, and compared against what the seller actually signed.')
+    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
   }
 }