agent-receipt-verify 0.0.0-stage → 0.2.1

package/src/eip3009-autorisatie.mjs

@@ -0,0 +1,195 @@
+// Een onafhankelijke verifieerder voor EIP-3009 betaalautorisaties, geschreven tegen
+// de vectoren van iamonuwa/kanon en niet tegen zijn code.
+//
+// WAAROM DIT HIER STAAT, want het is de ANDERE kant van wat deze repo tot nu toe deed.
+// Alles hier ging over de VERKOPER: zijn ondertekende aanbod, zijn bonnetje, en de
+// vraag of dat bonnetje op precies een afrekening op de keten opent. Een EIP-3009
+// autorisatie is de KOPER-kant: de handtekening waarmee een agent zijn geld vrijgeeft,
+// voor er iets afgerekend is. Samen zijn dat de twee uiteinden van dezelfde transactie,
+// en ze overlappen nergens. Dat is precies waarom een tweede implementatie hier iets
+// toevoegt in plaats van iets te verdubbelen.
+//
+// DE REGEL DIE DEZE HELE REPO DRAAGT, ook hier: geschreven tegen de GEPUBLICEERDE
+// vectoren en de specificaties (EIP-3009, EIP-712), nooit tegen de broncode van de
+// referentie-implementatie. Twee implementaties die elkaars code niet gezien hebben en
+// toch op dezelfde uitslagen komen, dat is interop. Een implementatie die met zichzelf
+// instemt bewijst niets.
+//
+// DE VOLGORDE VAN DE CONTROLES IS ZELF EEN UITSPRAAK, en zij volgt uit zijn eigen
+// beschrijvingen bij de vectoren:
+//   1. netwerk (platte tekst, voor de handtekening; zijn tekst: "the plaintext mismatch")
+//   2. kneedbaarheid van de handtekening (voor het herstellen, anders herstel je een
+//      tweede geldige vorm van dezelfde handtekening)
+//   3. geldigheidsvenster
+//   4. herstellen en de ondertekenaar vergelijken
+//   5. bedrag (zijn tekst: "caught only after the signature verifies")
+//   6. nonce al verbruikt
+// Een andere volgorde geeft bij een vector met twee gebreken een andere redencode. Waar
+// wij van hem afwijken hoort dat GEMELD te worden en niet weggepoetst tot het groen is.
+//
+// ethers is optioneel in dit pakket. Zonder dat pakket kan stap 4 niet en komt de
+// uitslag terug als ONGEMETEN, nooit als afgekeurd: een gat in onze meter is geen
+// gebrek van de betaling.
+
+import { laadEthers } from './x402-conformance-treden.mjs'
+
+/** De helft van de secp256k1-groepsorde. Daarboven is een handtekening kneedbaar. */
+const HALVE_ORDE = 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0n
+
+export const REDENEN = [
+  'VALID',
+  'NETWORK_MISMATCH',
+  'SIG_MALLEABLE',
+  'SIGNER_MISMATCH',
+  'NOT_YET_VALID',
+  'EXPIRED',
+  'NONCE_REPLAY',
+  'AMOUNT_INSUFFICIENT',
+]
+
+/** De EIP-712-types van EIP-3009, normatief en niet over de lijn verzonden. */
+export const TRANSFER_TYPES = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+}
+
+/** `eip155:84532` naar 84532. Geeft null bij een vorm die wij niet kennen. */
+export function chainIdUitNetwerk(netwerk) {
+  const m = /^eip155:(\d+)$/.exec(String(netwerk ?? ''))
+  return m ? Number(m[1]) : null
+}
+
+/**
+ * Het domein waaronder deze autorisatie hoort te zijn ondertekend.
+ *
+ * Alle drie de replay-vectoren draaien hierom: wie onder een ander domein tekent
+ * (andere keten, ander contract, andere naam) levert een handtekening die op een ANDER
+ * adres herstelt. Daarom is er geen aparte controle voor cross-chain of cross-contract
+ * nodig: het domein doet dat werk, en de uitslag heet dan terecht SIGNER_MISMATCH.
+ */
+export function domeinUit(accepted) {
+  return {
+    name: accepted?.extra?.name,
+    version: accepted?.extra?.version,
+    chainId: chainIdUitNetwerk(accepted?.network),
+    verifyingContract: accepted?.asset,
+  }
+}
+
+/** Is de s-waarde van deze handtekening boven de halve groepsorde. */
+export function isKneedbaar(signature) {
+  const h = String(signature ?? '').replace(/^0x/i, '')
+  if (h.length < 130) return false
+  const s = BigInt('0x' + h.slice(64, 128))
+  return s > HALVE_ORDE
+}
+
+/**
+ * Beoordeelt een enkele autorisatie.
+ *
+ * Geeft { valid, reason_code } terug in exact de vorm die kanon se vectoren in hun
+ * `expected` gebruiken, plus `ongemeten` met een reden als de controle niet KON
+ * draaien. Die derde mogelijkheid staat niet in zijn schema, en dat is precies het
+ * punt dat wij in x402#3396 open hebben gelegd: een gat in de verifieerder is iets
+ * anders dan een afgekeurde betaling.
+ */
+export async function beoordeelAutorisatie(input, context = {}) {
+  const doelNetwerk = context.doelNetwerk ?? input?.accepted?.network
+  const accepted = input?.accepted ?? {}
+  const auth = input?.payload?.authorization ?? {}
+  const signature = input?.payload?.signature
+  const nu = Number(context.verification_time ?? Math.floor(Date.now() / 1000))
+
+  // 1. Netwerk, in platte tekst, voor er iets met de handtekening gebeurt.
+  if (String(doelNetwerk) !== String(accepted.network)) {
+    return { valid: false, reason_code: 'NETWORK_MISMATCH' }
+  }
+
+  // 2. Kneedbaarheid, voor het herstellen. Een hoge s is een tweede geldige vorm van
+  // dezelfde handtekening, en wie eerst herstelt accepteert die vorm stilletjes.
+  if (isKneedbaar(signature)) {
+    return { valid: false, reason_code: 'SIG_MALLEABLE' }
+  }
+
+  // 3. Het geldigheidsvenster.
+  if (nu < Number(auth.validAfter)) return { valid: false, reason_code: 'NOT_YET_VALID' }
+  if (nu > Number(auth.validBefore)) return { valid: false, reason_code: 'EXPIRED' }
+
+  // 4. Herstellen en de ondertekenaar vergelijken. Zonder ethers kan dit niet, en dan
+  // is de eerlijke uitslag ONGEMETEN.
+  const ethers = await laadEthers()
+  if (!ethers) {
+    return { valid: false, reason_code: null, ongemeten: true, reden: 'ethers ontbreekt, dus de handtekening is niet te herstellen' }
+  }
+  let hersteld
+  try {
+    hersteld = ethers.verifyTypedData(domeinUit(accepted), TRANSFER_TYPES, {
+      from: auth.from, to: auth.to, value: auth.value,
+      validAfter: auth.validAfter, validBefore: auth.validBefore, nonce: auth.nonce,
+    }, signature)
+  } catch (e) {
+    // Een handtekening die niet eens te herstellen is, is geen geldige ondertekenaar.
+    return { valid: false, reason_code: 'SIGNER_MISMATCH', detail: String(e?.message ?? e).slice(0, 120) }
+  }
+  if (String(hersteld).toLowerCase() !== String(auth.from).toLowerCase()) {
+    return { valid: false, reason_code: 'SIGNER_MISMATCH', hersteld }
+  }
+
+  // 5. Het bedrag, pas NA de handtekening: een authentiek ondertekende onderbetaling.
+  if (BigInt(auth.value ?? 0) < BigInt(accepted.amount ?? 0)) {
+    return { valid: false, reason_code: 'AMOUNT_INSUFFICIENT' }
+  }
+
+  // 6. Is deze nonce al verbruikt. Dit is toestand van buiten, geen eigenschap van de
+  // autorisatie, en komt daarom uit de context in plaats van uit de betaling.
+  const gezien = (context.seen_nonces ?? []).map((n) => String(n).toLowerCase())
+  if (gezien.includes(String(auth.nonce).toLowerCase())) {
+    return { valid: false, reason_code: 'NONCE_REPLAY' }
+  }
+
+  return { valid: true, reason_code: 'VALID', ondertekenaar: hersteld }
+}
+
+/** Een hele vector beoordelen, met zijn eigen context en doelnetwerk. */
+export async function beoordeelVector(vector) {
+  return beoordeelAutorisatie(vector.input, { ...(vector.context ?? {}), doelNetwerk: vector.network })
+}
+
+// Een commandoregel, zodat een vreemde de kruiscontrole in EEN regel kan narekenen in
+// plaats van ons op ons woord te geloven. Dat is het hele punt van deze repo.
+if (process.argv[1]?.endsWith('eip3009-autorisatie.mjs')) {
+  const fs = await import('node:fs')
+  const path = await import('node:path')
+  const { fileURLToPath } = await import('node:url')
+  const map = path.join(fileURLToPath(new URL('..', import.meta.url)), 'vectors', 'kanon')
+  if (!fs.existsSync(map)) {
+    console.log('geen vectoren gevonden in ' + map)
+    process.exitCode = 2
+  } else {
+    const bestanden = fs.readdirSync(map).filter((f) => f.endsWith('.json')).sort()
+    let eens = 0, oneens = 0, ongemeten = 0
+    console.log('Cross-check against iamonuwa/kanon, EIP-3009 payment authorizations')
+    console.log('Vectors pinned at commit 0d5a7461e996, Apache-2.0, redistributed unmodified.')
+    console.log('This implementation was written against those vectors and against EIP-3009')
+    console.log('and EIP-712, never against that project\'s source.')
+    console.log('')
+    for (const f of bestanden) {
+      const v = JSON.parse(fs.readFileSync(path.join(map, f), 'utf8'))
+      const u = await beoordeelVector(v)
+      if (u.ongemeten) { ongemeten++; console.log('  not measured  ' + v.id + '  ' + u.reden); continue }
+      const zelfde = u.valid === v.expected.valid && u.reason_code === v.expected.reason_code
+      if (zelfde) { eens++; console.log('  agree         ' + v.id.padEnd(42) + ' ' + u.reason_code) }
+      else { oneens++; console.log('  DISAGREE      ' + v.id.padEnd(42) + ' ours ' + u.reason_code + ', theirs ' + v.expected.reason_code) }
+    }
+    console.log('')
+    console.log('agree on ' + eens + ' of ' + bestanden.length + ', disagree ' + oneens + ', not measured ' + ongemeten)
+    if (ongemeten) console.log('Install the optional ethers dependency to run the signature recovery.')
+    process.exitCode = oneens === 0 ? 0 : 1
+  }
+}

package/src/inam-countersigned.mjs

@@ -0,0 +1,162 @@
+// Onafhankelijke verificatie van INAM-tegengetekende bonnetjes.
+//
+// Geschreven tegen hun SPEC.md (§4.2 content-addressing, §4.3 lifecycle, §15 over
+// HTTP) en hun README, NIET tegen hun verify.mjs. Dat is het hele punt: als twee
+// implementaties die elkaars code niet hebben gezien dezelfde uitspraak doen over
+// dezelfde vectoren, is dat interop-bewijs. Eén implementatie die zichzelf
+// bevestigt, bewijst niets.
+//
+// Read-only, geen netwerk, geen sleutels van onszelf.
+
+import { createHash, createPublicKey, verify as edVerify } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+const DIRECT = process.argv[1]?.endsWith('inam-countersigned.mjs')
+const VECTOREN = process.argv[2]
+if (DIRECT && !VECTOREN) { console.error('usage: node src/inam-countersigned.mjs <vectors.json>'); process.exit(2) }
+
+// ── bouwstenen ───────────────────────────────────────────────────────────────
+
+// §4.2: "recursive key-sorted, whitespace-free JSON serializer"
+export function canoniek(x) {
+  if (x === null || typeof x !== 'object') return JSON.stringify(x)
+  if (Array.isArray(x)) return '[' + x.map(canoniek).join(',') + ']'
+  return '{' + Object.keys(x).sort().map(k => JSON.stringify(k) + ':' + canoniek(x[k])).join(',') + '}'
+}
+
+const sha256hex = s => createHash('sha256').update(s, 'utf8').digest('hex')
+
+// base58btc, zelf geschreven zodat we geen code van hen of van een pakket delen
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+export function base58decode(s) {
+  let getal = 0n
+  for (const teken of s) {
+    const i = B58.indexOf(teken)
+    if (i < 0) throw new Error('geen base58: ' + teken)
+    getal = getal * 58n + BigInt(i)
+  }
+  const bytes = []
+  while (getal > 0n) { bytes.unshift(Number(getal & 255n)); getal >>= 8n }
+  for (const teken of s) { if (teken === '1') bytes.unshift(0); else break }
+  return Buffer.from(bytes)
+}
+
+// did:key met multicodec 0xed01 = Ed25519 publieke sleutel
+export function didNaarSleutel(did) {
+  const deel = did.replace(/^did:key:/, '').split('#')[0]
+  if (!deel.startsWith('z')) throw new Error('verwacht base58btc (z...)')
+  const ruw = base58decode(deel.slice(1))
+  if (ruw[0] !== 0xed || ruw[1] !== 0x01) throw new Error('geen ed25519-multicodec')
+  const sleutel = ruw.subarray(2)
+  if (sleutel.length !== 32) throw new Error('verkeerde sleutellengte ' + sleutel.length)
+  // minimale SPKI-DER-omhulling rond een rauwe ed25519-sleutel
+  const der = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), sleutel])
+  return createPublicKey({ key: der, format: 'der', type: 'spki' })
+}
+
+export function ed25519Klopt(did, inhoud, handtekeningB64) {
+  try {
+    const sig = Buffer.from(handtekeningB64, handtekeningB64.includes('-') || handtekeningB64.includes('_') ? 'base64url' : 'base64')
+    return edVerify(null, Buffer.from(inhoud, 'utf8'), didNaarSleutel(did), sig)
+  } catch { return false }
+}
+
+let keccak256
+try {
+  // Een BARE import, en bewust geen pad op iemands schijf. Dit stond hier als
+  // file:///C:/Code/... en dat werkte alleen op de machine van de schrijver: voor
+  // iedere vreemde viel controle 1 stil weg en kreeg hij zonder het te weten een
+  // zwakkere uitslag dan wij. Dat is het tegenovergestelde van een onafhankelijke
+  // verifieerder. ethers staat nu als optionele afhankelijkheid in package.json.
+  const ethers = await import('ethers')
+  keccak256 = b => ethers.keccak256(b)
+} catch {
+  keccak256 = null
+}
+
+// ── de acht controles, zoals hun README ze beschrijft ────────────────────────
+
+export function toetsGeval(geval, vectoren) {
+  const mislukt = []
+  const bestand = geval.feedbackFile
+  const f = JSON.parse(bestand)
+  const r = f?.inam?.receipt ?? {}
+  const ev = geval.onchainEvent ?? {}
+  const obs = vectoren.observed ?? {}
+
+  // 1. keccak256 van de bestandsbytes is de feedbackHash uit het event
+  if (keccak256) {
+    const berekend = keccak256(Buffer.from(bestand, 'utf8'))
+    if (String(berekend).toLowerCase() !== String(ev.feedbackHash).toLowerCase()) mislukt.push('feedbackHashMatchesFile')
+  }
+
+  // 2. §4.2: receiptId = sha256 over canoniek van zeven velden
+  const zeven = {}
+  for (const k of ['jobId', 'agentA', 'agentB', 'task', 'result', 'settlement', 'verification']) {
+    if (r[k] !== undefined) zeven[k] = r[k]
+  }
+  if ('sha256:' + sha256hex(canoniek(zeven)) !== r.receiptId) mislukt.push('receiptIdRecomputes')
+
+  // 3+4. §4.3: beide partijen tekenen DEZELFDE canonieke inhoud, alles behalve
+  // signatures, status en dispute
+  const teTekenen = { ...r }
+  delete teTekenen.signatures; delete teTekenen.status; delete teTekenen.dispute
+  const inhoud = canoniek(teTekenen)
+  const sigs = r.signatures ?? {}
+  const didB = r.agentB?.did ?? r.agentB?.id ?? vectoren.parties?.provider?.did
+  const didA = r.agentA?.did ?? r.agentA?.id ?? vectoren.parties?.requester?.did
+  const sigB = sigs.agentB?.signature ?? sigs.agentB ?? sigs.worker
+  const sigA = sigs.agentA?.signature ?? sigs.agentA ?? sigs.requester
+  if (!sigB || !ed25519Klopt(didB, inhoud, sigB)) mislukt.push('workerSignature')
+  if (!sigA || !ed25519Klopt(didA, inhoud, sigA)) mislukt.push('requesterSignature')
+
+  // 5. waarde hoort bij de uitkomst: 100 / 50 / 0
+  const uitkomst = r.result?.outcome ?? r.result?.status
+  const hoort = { success: 100, partial: 50, failed: 0 }[uitkomst]
+  const waarde = ev.value ?? f.value
+  if (hoort !== undefined && Number(waarde) !== hoort) mislukt.push('valueMatchesOutcome')
+
+  // 6. het bestand noemt het adres dat het event verstuurde
+  const inBestand = String(f.clientAddress ?? '').split(':').pop().toLowerCase()
+  if (inBestand !== String(ev.clientAddress ?? '').toLowerCase()) mislukt.push('fileClientAddressMatchesSender')
+
+  // 7. dat adres is de wallet waarvan de requester controle bewees
+  const bewezen = String(vectoren.parties?.requester?.erc8004Address ?? '').toLowerCase()
+  if (String(ev.clientAddress ?? '').toLowerCase() !== bewezen) mislukt.push('senderIsRequesterWallet')
+
+  // 8+9. §15: hashes over de bytes die daadwerkelijk over de lijn gingen
+  const u = new URL(obs.request?.url ?? 'https://x/')
+  const verzoekBytes = `${obs.request?.method} ${u.pathname}${u.search}\n${obs.request?.body ?? ''}`
+  if ('sha256:' + sha256hex(verzoekBytes) !== r.task?.specHash) mislukt.push('specHashMatchesObservedBytes')
+  if ('sha256:' + sha256hex(obs.response?.body ?? '') !== r.result?.outputHash) mislukt.push('outputHashMatchesObservedBytes')
+
+  return { accepted: mislukt.length === 0, failedChecks: mislukt }
+}
+
+// ── draaien en vergelijken met wat de vectoren zelf verwachten ───────────────
+//
+// Alleen bij directe aanroep. Importeren levert de functies, niets anders.
+if (DIRECT) {
+
+  const v = JSON.parse(readFileSync(VECTOREN, 'utf8'))
+  console.log(`suite: ${v.suite}`)
+  console.log(`keccak256 beschikbaar: ${keccak256 ? 'ja' : 'NEE (controle 1 overgeslagen)'}\n`)
+
+  let gelijk = 0, afwijkend = 0
+  for (const geval of v.cases) {
+    const onze = toetsGeval(geval, v)
+    const hunne = geval.expected
+    const zelfdeOordeel = onze.accepted === hunne.accepted
+    const onzeSet = [...onze.failedChecks].sort().join(',')
+    const hunSet = [...(hunne.failedChecks ?? [])].sort().join(',')
+    const zelfdeChecks = onzeSet === hunSet
+    const merk = zelfdeOordeel && zelfdeChecks ? 'GELIJK  ' : (zelfdeOordeel ? 'deels   ' : 'AFWIJKEND')
+    if (zelfdeOordeel && zelfdeChecks) gelijk++; else afwijkend++
+    console.log(`${merk} ${geval.id}`)
+    console.log(`   zij : accepted=${hunne.accepted} [${hunSet || '-'}]`)
+    console.log(`   wij : accepted=${onze.accepted} [${onzeSet || '-'}]`)
+  }
+  console.log(`\n${gelijk} van ${v.cases.length} volledig gelijk, ${afwijkend} afwijkend`)
+  process.exit(afwijkend === 0 ? 0 : 1)
+
+}

package/src/mcp-server.mjs

@@ -0,0 +1,262 @@
+// Een MCP-server, zodat een agent deze controle AANROEPT in plaats van hem te moeten
+// aanbevelen.
+//
+// WAAROM DIT BESTAAT, en het is gemeten en niet bedacht. Op 2026-10-17 classificeerde
+// de gratis laag 32 marktsignalen over agent-betalingen: 14 benoemen een concreet
+// probleem en alle 14 staan aan de KOPERSKANT. Niet een enkel verkopersprobleem. De
+// titels zeggen het zelf: "5 Ways Your Paid Endpoint Gets Drained", "your agent still
+// needs a bill", en "Your AI Agent Paid a Supplier Twice. Can You Prove What It Did?"
+// In dezelfde ronde bleken er in de MCP-directories al zeven partijen DATA te
+// verkopen over x402 en geen enkele die de betaallaag zelf controleert.
+//
+// Dat is de hele reden voor deze twee gereedschappen: het voor en het na van die ene
+// pijn. Voor je betaalt, klopt dit eindpunt. Na je betaling, hoort dit bonnetje bij
+// precies een echte betaling.
+//
+// GEEN AFHANKELIJKHEDEN, EN DAT IS EEN KEUZE EN GEEN LUIHEID. Dit protocol is
+// newline-gescheiden JSON-RPC over stdio, dat is een paar regels. De officiele
+// bibliotheek erbij halen zou betekenen dat een verifieerder wiens hele waarde
+// onafhankelijkheid is, een boom afhankelijkheden meeneemt om te zeggen of een
+// handtekening klopt. De vormen hieronder zijn overgenomen uit de officiele sdk die
+// in ons andere project staat, niet uit het hoofd: protocolversie, de tools-vorm en
+// de content-vorm komen daar letterlijk uit.
+//
+// DE VALKUIL DIE EEN MCP-SERVER STIL KAPOT MAAKT: alles wat naar stdout gaat en geen
+// JSON-RPC-frame is, breekt de verbinding. Daarom gaat ELKE melding naar stderr en
+// schrijft alleen `stuur()` naar stdout.
+//
+// GEBRUIK (in een MCP-client):
+//   npx github:holistis/agent-receipt-verify mcp
+//
+// WAT DIT NIET DOET: het oordeelt over de VORM van een eindpunt en een bonnetje, niet
+// over de eerlijkheid van de partij erachter. Een eindpunt dat alles goed doet kan je
+// alsnog rommel verkopen. Zie CONFORMANCE.md voor wat met opzet niet gemeten wordt.
+
+import { meetEindpunt, hoogsteTrede } from './x402-conformance-check.mjs'
+import { TREDEN, PROFIEL } from './x402-conformance-treden.mjs'
+import { maakRpc, linkBonnetje } from './x402-link-onchain.mjs'
+
+const PROTOCOL = '2025-11-25'
+const ONDERSTEUND = [PROTOCOL, '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07']
+
+const NAAM = 'agent-receipt-verify'
+const VERSIE = '0.2.0'
+
+// Een publieke rpc per netwerk, zodat de koper niet eerst een sleutel hoeft te regelen
+// om zijn eigen bonnetje te kunnen natrekken. Een netwerk dat hier niet staat wordt
+// EERLIJK als niet-ondersteund gemeld en nooit stil op een ander netwerk gezocht.
+const RPC_PER_NETWERK = {
+  'eip155:84532': 'https://sepolia.base.org',
+  'eip155:8453': 'https://mainnet.base.org',
+  'base-sepolia': 'https://sepolia.base.org',
+  base: 'https://mainnet.base.org',
+}
+
+const log = (...a) => process.stderr.write('[' + NAAM + '] ' + a.join(' ') + '\n')
+
+const GEREEDSCHAP = [
+  {
+    name: 'check_x402_endpoint',
+    description:
+      'Check a paid x402 endpoint BEFORE paying it. Sends exactly one request, never pays, and reports which levels of ' +
+      'the published conformance ladder it reaches: does it ask for payment the way x402 says, does it declare the ' +
+      'offer-receipt extension, and does the signature on its offer actually verify. Levels that need a real settlement ' +
+      'are reported as not measured, never as failed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The paid endpoint to check, for example https://api.example.com/paid/thing' },
+        method: { type: 'string', description: 'HTTP method the endpoint expects. Defaults to POST. Use GET for a GET-only route.' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'link_receipt_to_settlement',
+    description:
+      'Check AFTER paying that a version 2 offer-receipt belongs to exactly one real on-chain settlement. Takes the ' +
+      'signed receipt payload plus the authorization salt the seller returned outside it, and resolves the salted ' +
+      'commitment against live chain state. Answers linked, not linked, or could-not-check, and never guesses between them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        payload: { type: 'object', description: 'The signed receipt payload, the object with version, network, payer and authorizationCommitment' },
+        salt: { type: 'string', description: 'The authorizationSalt from extensions["offer-receipt"].info, which is deliberately not inside the signed payload' },
+        asset: { type: 'string', description: 'The token contract from the accepts entry that was paid, for example the USDC address' },
+        rpcUrl: { type: 'string', description: 'Optional. An RPC endpoint to use instead of the public default for that network.' },
+      },
+      required: ['payload', 'salt', 'asset'],
+    },
+  },
+]
+
+function tekst(s, fout = false) {
+  return { content: [{ type: 'text', text: s }], ...(fout ? { isError: true } : {}) }
+}
+
+async function doeCheckEndpoint(args) {
+  const url = typeof args?.url === 'string' ? args.url.trim() : ''
+  if (!/^https?:\/\//.test(url)) return tekst('url must be an absolute http or https address', true)
+  const methode = typeof args?.method === 'string' && /^(GET|POST|PUT|PATCH|DELETE)$/i.test(args.method)
+    ? args.method.toUpperCase()
+    : 'POST'
+
+  const m = await meetEindpunt(url, { methode })
+  const hoogste = hoogsteTrede(m)
+  const regels = [
+    (hoogste >= 0 ? 'Reaches level ' + hoogste : 'Reaches no level') + ' of the conformance ladder.',
+    'Checked with a single ' + methode + ' request. Nothing was paid.',
+    '',
+  ]
+  for (const t of TREDEN) {
+    const staat = m.treden[t.sleutel]
+    if (!staat) continue
+    const merk = staat === 'HAALT' ? 'reached    ' : staat === 'HAALT_NIET' ? 'NOT reached' : 'not measured'
+    regels.push('L' + t.nummer + '  ' + merk + '  ' + t.naam)
+    if (m.bewijs[t.sleutel]) regels.push('      ' + m.bewijs[t.sleutel])
+  }
+  if (m.bewijs.t2afwijking) regels.push('', 'note on the key: ' + m.bewijs.t2afwijking)
+  // De uitslag draagt nu ook WAAR de ladder vandaan komt. Een cijfer zonder
+  // herkomst is een mening, en een trede die tegen een nog niet samengevoegd
+  // voorstel meet, hoort dat zelf te zeggen in plaats van het aan de lezer te laten.
+  const voorstelTreden = TREDEN.filter((t) => t.citeertVoorstel).map((t) => 'L' + t.nummer)
+  regels.push(
+    '',
+    'Ladder: profile ' + PROFIEL.profile + ' v' + PROFIEL.version + ' of ' + PROFIEL.published +
+      ', which names the clause behind every level: profiles/x402-deployed-ladder-v1.json',
+  )
+  if (voorstelTreden.length) {
+    regels.push(
+      voorstelTreden.join(' and ') + ' are measured against sections 5.6 and later of the offer-receipt ' +
+        'extension, which exist only in pull request 3827 and are not merged. Their numbering can still move.',
+    )
+  }
+  regels.push(
+    'Levels 3 to 5 cannot be observed without paying, so they are reported as not measured rather than absent.',
+    'The ladder and what it deliberately does not measure: https://github.com/holistis/agent-receipt-verify/blob/main/CONFORMANCE.md',
+    'This judges the form of an endpoint, not the honesty of the party behind it.',
+  )
+  return tekst(regels.join('\n'))
+}
+
+async function doeLinkReceipt(args) {
+  const payload = args?.payload
+  const salt = typeof args?.salt === 'string' ? args.salt.trim() : ''
+  const asset = typeof args?.asset === 'string' ? args.asset.trim() : ''
+  if (!payload || typeof payload !== 'object') return tekst('payload must be the signed receipt object', true)
+  if (!/^0x[0-9a-fA-F]{64}$/.test(salt)) return tekst('salt must be a 32 byte hex string starting with 0x', true)
+  if (!/^0x[0-9a-fA-F]{40}$/.test(asset)) return tekst('asset must be a 20 byte hex address starting with 0x', true)
+
+  const netwerk = String(payload.network ?? '')
+  const rpcUrl = typeof args?.rpcUrl === 'string' && args.rpcUrl ? args.rpcUrl : RPC_PER_NETWERK[netwerk]
+  if (!rpcUrl) {
+    return tekst(
+      'could not check: no public RPC is configured for network "' + netwerk + '".\n' +
+      'Pass rpcUrl explicitly. This is reported as could-not-check, not as not-linked, because those are different answers.',
+      true,
+    )
+  }
+
+  try {
+    const uit = await linkBonnetje(maakRpc(rpcUrl), { payload, salt, asset })
+    const regels = []
+    if (uit.linked) {
+      regels.push('LINKED. This receipt opens to exactly one on-chain authorization.')
+      regels.push('nonce       ' + uit.identifier)
+      if (uit.afrekening?.tx) regels.push('transaction ' + uit.afrekening.tx)
+      if (uit.afrekening?.blok) regels.push('block       ' + uit.afrekening.blok)
+    } else {
+      // Niet-gelinkt heeft bij deze controle altijd een REDEN mee, en die reden IS
+      // het antwoord. Nul kandidaten en twee kandidaten zijn allebei niet-gelinkt en
+      // bewust niet waarschijnlijk-gelinkt: fail-closed, zie 5.6.4 stap 3.
+      regels.push('NOT LINKED. ' + (uit.reden ?? 'the commitment did not open to exactly one authorization'))
+      regels.push('Two candidates opening the same commitment reads as not linked on purpose, not as probably linked.')
+      regels.push('A receipt signed before its settlement was mined can also read this way; retry later or widen the window.')
+    }
+    if (uit.venster) {
+      regels.push(
+        '',
+        'searched blocks ' + uit.venster.vanBlok + ' to ' + uit.venster.totBlok +
+          ' (' + uit.venster.kandidaten + ' candidate authorizations, ' + uit.venster.aanroepen + ' rpc calls)',
+      )
+    }
+    regels.push('checked against ' + rpcUrl + ' for network ' + netwerk + '.')
+    return tekst(regels.join('\n'))
+  } catch (e) {
+    return tekst('could not check: ' + String(e.message).slice(0, 180) + '\nThis is a failure of the check, not a verdict on the receipt.', true)
+  }
+}
+
+async function behandel(bericht) {
+  const { id, method, params } = bericht
+
+  if (method === 'initialize') {
+    const gevraagd = params?.protocolVersion
+    return {
+      protocolVersion: ONDERSTEUND.includes(gevraagd) ? gevraagd : PROTOCOL,
+      capabilities: { tools: {} },
+      serverInfo: { name: NAAM, version: VERSIE },
+    }
+  }
+  if (method === 'ping') return {}
+  if (method === 'tools/list') return { tools: GEREEDSCHAP }
+  if (method === 'tools/call') {
+    const naam = params?.name
+    const args = params?.arguments ?? {}
+    if (naam === 'check_x402_endpoint') return await doeCheckEndpoint(args)
+    if (naam === 'link_receipt_to_settlement') return await doeLinkReceipt(args)
+    // Een onbekend gereedschap is een fout van de aanroeper en hoort als JSON-RPC-fout
+    // terug, niet als een tekst die op een uitslag lijkt.
+    const fout = new Error('unknown tool: ' + String(naam))
+    fout.code = -32602
+    throw fout
+  }
+  const fout = new Error('method not found: ' + String(method))
+  fout.code = -32601
+  throw fout
+}
+
+function stuur(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+export function maakVerwerker() {
+  let buffer = ''
+  return async function verwerk(brok) {
+    buffer += brok
+    let grens
+    while ((grens = buffer.indexOf('\n')) >= 0) {
+      const regel = buffer.slice(0, grens).trim()
+      buffer = buffer.slice(grens + 1)
+      if (!regel) continue
+      let bericht
+      try {
+        bericht = JSON.parse(regel)
+      } catch {
+        stuur({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } })
+        continue
+      }
+      // Een notificatie heeft geen id en krijgt per specificatie GEEN antwoord. Wie
+      // daar toch op antwoordt, laat sommige clients vastlopen.
+      if (bericht.id === undefined || bericht.id === null) {
+        if (bericht.method === 'notifications/initialized') log('client is ready')
+        continue
+      }
+      try {
+        stuur({ jsonrpc: '2.0', id: bericht.id, result: await behandel(bericht) })
+      } catch (e) {
+        stuur({ jsonrpc: '2.0', id: bericht.id, error: { code: e.code ?? -32603, message: String(e.message).slice(0, 200) } })
+      }
+    }
+  }
+}
+
+if (process.argv[1]?.endsWith('mcp-server.mjs')) {
+  log('listening on stdio, protocol ' + PROTOCOL + ', ' + GEREEDSCHAP.length + ' tools')
+  const verwerk = maakVerwerker()
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', (b) => {
+    verwerk(b).catch((e) => log('handler error: ' + e.message))
+  })
+  process.stdin.on('end', () => process.exit(0))
+}