agent-receipt-verify 0.0.0-stage → 0.2.2

package/src/x402-index-liveness.mjs

@@ -0,0 +1,201 @@
+// Van de hosts die in een discovery-index STAAN, hoeveel antwoorden er vandaag
+// werkelijk zoals x402 voorschrijft.
+//
+// WAAROM DEZE VRAAG, en niet de vraag waar de ladder voor gebouwd is. De census
+// (x402-discovery-census.mjs) heeft op 2026-10-17 geteld dat nul van de 1127 hosts
+// de offer-receipt-extensie declareert. Trede 1 tot 5 van de ladder hebben dus
+// geen populatie. Een uitslag daarover zou een tabel met nullen zijn plus ons
+// eigen eindpunt, en dat is geen meting maar een advertentie. Trede 0 heeft wel
+// een populatie, en die vraag is nog door niemand gepubliceerd: een registratie
+// in een index zegt niets over of het eindpunt nog leeft.
+//
+// DE STEEKPROEFREGEL STAAT HIER, zodat iemand anders exact dezelfde hosts kan
+// natrekken en kan zien waar hij afwijkt:
+//  1. Per host de resource met de LAAGSTE index-positie (de census bepaalt die).
+//  2. Hosts gesorteerd op die positie, oplopend.
+//  3. Daaruit elke n-de, met n zo gekozen dat de steekproef over de hele
+//     registratievolgorde ligt. Niet de eerste N: die zijn van een handvol
+//     partijen die vroeg massaal aanmeldden, en dat meet dan die partijen in
+//     plaats van de index.
+//  4. De methode die de partij ZELF declareert in de index. Blind POST sturen
+//     laat een GET-route zakken op een 405 die niets over x402 zegt.
+//
+// TWEE CONTROLES, want een meting waarin alles faalt bewijst niet dat de
+// werkelijkheid faalt, hij kan ook bewijzen dat het meetgereedschap kapot is:
+//  - positief: een eindpunt waarvan wij weten dat het trede 2 haalt.
+//  - negatief: een gewone pagina die niets met x402 doet.
+// Gaan die twee niet zoals verwacht, dan is de uitslag ongeldig en zegt het
+// script dat, in plaats van de cijfers alsnog op te leveren.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { meetEindpunt, hoogsteTrede } from './x402-conformance-check.mjs'
+
+const POSITIEVE_CONTROLE = { url: 'https://api.tokenizen.nl/api/paid/verify-ownership', methode: 'POST', verwacht: 2 }
+const NEGATIEVE_CONTROLE = { url: 'https://example.com/', methode: 'GET', verwacht: -1 }
+
+const slaap = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * Vult sjabloon-parameters in een resource-URL met de waarden die de index zelf geeft.
+ *
+ * TOEGEVOEGD NA EEN EIGEN FOUT, 2026-10-17. De index bevat URL's als
+ * "https://api.apibooth.com/v1/ip/:ip" en wij vroegen die LETTERLIJK op, inclusief
+ * de dubbele punt. Dat gaf een 400 die wij bijna als "weigert het verzoek" hadden
+ * gepubliceerd, terwijl de index de waarde ("8.8.8.8") ernaast vermeldde. Dat is je
+ * eigen verzoek meten in plaats van het eindpunt.
+ *
+ * Geeft {url, ingevuld, resterend} terug: resterend is wat NIET ingevuld kon worden,
+ * zodat een meting op een half-ingevuld sjabloon zichzelf kan diskwalificeren in
+ * plaats van een getal te produceren dat nergens op rust.
+ */
+export function vulSjabloon(url, pathParams) {
+  const gevonden = [...String(url).matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1])
+  const uniek = [...new Set(gevonden)]
+  if (uniek.length === 0) return { url, ingevuld: [], resterend: [] }
+  let uit = url
+  const ingevuld = []
+  const resterend = []
+  for (const naam of uniek) {
+    const waarde = pathParams?.[naam]
+    if (waarde === undefined || waarde === null || String(waarde) === '') {
+      resterend.push(naam)
+      continue
+    }
+    uit = uit.split(':' + naam).join(encodeURIComponent(String(waarde)))
+    ingevuld.push(naam)
+  }
+  return { url: uit, ingevuld, resterend }
+}
+
+/** Stap 1 tot 3 van de steekproefregel hierboven, puur rekenwerk, geen netwerk. */
+export function kiesSteekproef(operators, aantal) {
+  const opPositie = [...operators].sort((a, b) => a.eersteOffset - b.eersteOffset)
+  if (aantal >= opPositie.length) return opPositie
+  const stap = opPositie.length / aantal
+  const uit = []
+  for (let i = 0; i < aantal; i++) uit.push(opPositie[Math.floor(i * stap)])
+  return uit
+}
+
+/**
+ * Verdeelt een meting in emmers die NIET door elkaar lopen.
+ *
+ * Het verschil tussen "doet geen x402" en "wees mijn verzoek af voor het ooit bij
+ * de betaalmuur kwam" is echt, en een meting die beide als mislukking telt is met
+ * een enkele controle onderuit te halen. Een correcte implementatie geeft zijn
+ * 402 voor hij een lichaam valideert; niet iedereen doet dat.
+ */
+export function emmer(meting) {
+  const trede = hoogsteTrede(meting)
+  if (trede >= 0) return 'x402_ok'
+  const s = meting.bewijs?.status
+  if (s == null) return 'onbereikbaar'
+  if (s === 402) return 'status_402_onbruikbaar'
+  if (s === 401 || s === 403) return 'afgeschermd'
+  if (s === 404 || s === 410) return 'pad_weg'
+  if (s === 405) return 'methode_geweigerd'
+  if (s === 429) return 'tempo_geweigerd'
+  if (s >= 400 && s < 500) return 'verzoek_geweigerd'
+  if (s >= 500) return 'serverfout'
+  return 'geen_betaalmuur'
+}
+
+export async function meetSteekproef(gekozen, { pauzeMs = 1200, fetchImpl = fetch } = {}) {
+  const uit = []
+  for (const o of gekozen) {
+    const methode = o.eersteMethode ?? 'POST'
+    const sjab = vulSjabloon(o.eersteResource, o.eersteInvoer?.pathParams)
+    const m = await meetEindpunt(sjab.url, { methode, fetchImpl, lichaam: o.eersteInvoer?.body ?? null })
+    uit.push({
+      host: o.host,
+      url: sjab.url,
+      urlInIndex: o.eersteResource,
+      sjabloonIngevuld: sjab.ingevuld,
+      sjabloonNietIngevuld: sjab.resterend,
+      lichaamUitIndex: o.eersteInvoer?.body != null,
+      indexPositie: o.eersteOffset,
+      registratiesVanDezeHost: o.aantalRegistraties,
+      gedeclareerdeMethode: o.eersteMethode,
+      gebruikteMethode: methode,
+      status: m.bewijs?.status ?? null,
+      hoogsteTrede: hoogsteTrede(m),
+      emmer: emmer(m),
+      treden: m.treden,
+      bewijs: m.bewijs,
+    })
+    if (pauzeMs) await slaap(pauzeMs)
+  }
+  return uit
+}
+
+if (process.argv[1]?.endsWith('x402-index-liveness.mjs')) {
+  const censusPad = process.argv[2]
+  const aantal = Number(process.argv[3] ?? 50)
+  const uitPad = process.argv[4]
+  if (!censusPad) {
+    console.log('usage: node src/x402-index-liveness.mjs <census.json> [sample size] [out.json]')
+    process.exitCode = 2
+  } else {
+    const census = JSON.parse(readFileSync(censusPad, 'utf8'))
+    const gekozen = kiesSteekproef(census.operators, aantal)
+
+    console.log('--- controls first, because a sweep where everything fails proves nothing ---')
+    const controles = []
+    for (const c of [POSITIEVE_CONTROLE, NEGATIEVE_CONTROLE]) {
+      const m = await meetEindpunt(c.url, { methode: c.methode })
+      const t = hoogsteTrede(m)
+      const ok = t === c.verwacht
+      controles.push({ ...c, gemeten: t, emmer: emmer(m), status: m.bewijs?.status ?? null, ok })
+      console.log((ok ? '  ok   ' : '  FAIL ') + c.url + '  expected L' + c.verwacht + ', measured L' + t)
+      await slaap(1200)
+    }
+    const controlesGoed = controles.every((c) => c.ok)
+    if (!controlesGoed) {
+      console.log('')
+      console.log('The harness did not behave as expected on the controls. Treat the numbers below')
+      console.log('as invalid until that is explained. A measurement you cannot trust on a known')
+      console.log('case tells you nothing about the unknown ones.')
+    }
+
+    console.log('')
+    console.log('--- sample: ' + gekozen.length + ' of ' + census.operators.length + ' hosts ---')
+    const metingen = await meetSteekproef(gekozen)
+
+    const tel = new Map()
+    for (const m of metingen) tel.set(m.emmer, (tel.get(m.emmer) ?? 0) + 1)
+    for (const m of metingen) {
+      console.log(
+        (m.hoogsteTrede >= 0 ? 'L' + m.hoogsteTrede : '--') +
+        '  ' + String(m.status ?? '---').padStart(3) +
+        '  ' + m.emmer.padEnd(22) +
+        '  ' + m.host
+      )
+    }
+    console.log('')
+    for (const [k, v] of [...tel].sort((a, b) => b[1] - a[1])) {
+      console.log('  ' + String(v).padStart(4) + '  ' + k + '  (' + ((v / metingen.length) * 100).toFixed(1) + '%)')
+    }
+    const ok = metingen.filter((m) => m.hoogsteTrede >= 0).length
+    console.log('')
+    console.log('  ' + ok + ' of ' + metingen.length + ' sampled hosts answer the way x402 says (level 0)')
+    console.log('  levels 1 to 5 are not reported here: the census found 0 of ' + census.operators.length +
+      ' hosts declaring the offer-receipt extension, so there is no population to measure')
+
+    if (uitPad) {
+      mkdirSync(dirname(uitPad), { recursive: true })
+      writeFileSync(uitPad, JSON.stringify({
+        bron: census.bron,
+        steekproefregel: 'per host the resource with the lowest index position; hosts sorted by that position ascending; every nth taken so the sample spans the whole registration order; the method each party declares in the index',
+        hostsInCensus: census.operators.length,
+        steekproefGrootte: metingen.length,
+        controles,
+        controlesGoed,
+        emmers: Object.fromEntries(tel),
+        metingen,
+      }, null, 2))
+      console.log('')
+      console.log('written: ' + uitPad)
+    }
+  }
+}

package/src/x402-link-onchain.mjs

@@ -0,0 +1,280 @@
+// De tweede helft van 5.6.4: het commitment openen tegen de KETEN zelf.
+//
+// WAT HIER HET VERSCHIL MAAKT. Het commitment narekenen kan iedereen die het
+// zout en de nonce al heeft. Maar wie alleen een bonnetje en een zout krijgt
+// toegestuurd, HEEFT die nonce niet. 5.6.4 zegt daarom: vraag de keten welke
+// nonces deze betaler ooit heeft verbruikt, en reken het commitment na voor elke
+// kandidaat. Precies een MOET matchen. Dat is het moment waarop een bewering van
+// de ondertekenaar verandert in bewijs, en volgens 5.6.5 is dat ook het enige
+// moment waarop een teller een afrekening mag meetellen.
+//
+// GEEN SLEUTEL, GEEN ACCOUNT, GEEN PAKKETTEN. Alleen een publieke RPC en de
+// ingebouwde fetch. Dat is bewust: een controle die een API-sleutel vereist, is
+// voor een vreemde geen controle maar een drempel.
+//
+// HET ZOEKVENSTER, en waarom het niet "de hele keten" is. De publieke Base
+// Sepolia-RPC staat per aanroep maar 200 blokken toe, GEMETEN en niet uit
+// documentatie. Terugscannen over een dag zou dus ruim 200 aanroepen kosten. Een
+// bonnetje draagt echter zijn eigen tijdstip (issuedAt), en daar zoeken we
+// SYMMETRISCH rond.
+//
+// Symmetrisch, en niet alleen ervoor, en dat is een gecorrigeerde aanname. Een
+// eerdere versie van dit commentaar beweerde dat de afrekening per definitie
+// vlak VOOR het bonnetje ligt. Dat is onjuist: volgens 5.6.3 houdt de verkoper
+// de nonce al vast voordat de afrekening draait, dus een versie-2-bonnetje kan
+// ondertekend zijn voordat zijn betaling op de keten staat. De code zocht al
+// symmetrisch, de uitleg erbij was fout. Gecorrigeerd door babyblueviper1 op
+// x402#3827, en het staat hier omdat de volgende lezer anders dezelfde verkeerde
+// reden overneemt.
+//
+// We melden ALTIJD welk venster is afgezocht, zodat een lege uitslag leest als
+// "niet in dit venster" en nooit als "bestaat niet". Verbreden gaat via
+// --window, en dat is ook wat de spec-notitie nu aanraadt bij geen match.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { opentCommitment } from './x402-offer-receipt.mjs'
+
+// keccak256("AuthorizationUsed(address,bytes32)"). Hardgecodeerd omdat dit
+// pakket geen afhankelijkheden heeft en een keccak-implementatie meeslepen meer
+// risico is dan deze ene constante. Zelf na te rekenen met een regel ethers:
+//   ethers.id('AuthorizationUsed(address,bytes32)')
+export const AUTHORIZATION_USED_TOPIC =
+  '0x98de503528ee59b575ef0c0a2576a82497bfc029a5685b209e9ec333479b10a5'
+
+const hex = n => '0x' + Number(n).toString(16)
+const getal = h => parseInt(h, 16)
+
+/** Een adres als 32-byte topic. Een onjuiste lengte zou stil op niets matchen. */
+export function adresAlsTopic(adres) {
+  const kaal = String(adres).replace(/^0x/i, '').toLowerCase()
+  if (!/^[0-9a-f]{40}$/.test(kaal)) throw new Error(`geen adres: ${adres}`)
+  return '0x' + kaal.padStart(64, '0')
+}
+
+export function maakRpc(url, fetchImpl = fetch) {
+  let id = 0
+  return async function rpc(method, params) {
+    const r = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: ++id, method, params }),
+      signal: AbortSignal.timeout(25000),
+    })
+    const j = await r.json()
+    if (j.error) throw new Error(`${method}: ${j.error.message}`)
+    return j.result
+  }
+}
+
+/**
+ * Zoek het blok dat bij een tijdstip hoort, door te meten in plaats van te rekenen.
+ *
+ * Een vaste bloktijd aannemen is precies het soort gok dat later stil misgaat:
+ * ketens veranderen hun tempo. Daarom eerst twee echte blokken meten voor een
+ * eerste schatting, en die daarna corrigeren tot het verschil klein genoeg is.
+ */
+export async function blokBijTijd(rpc, doelTijd, maxRondes = 6) {
+  const laatsteNr = getal(await rpc('eth_blockNumber', []))
+  const laatste = await rpc('eth_getBlockByNumber', [hex(laatsteNr), false])
+  const eerder = await rpc('eth_getBlockByNumber', [hex(laatsteNr - 1000), false])
+  const blokTijd = (getal(laatste.timestamp) - getal(eerder.timestamp)) / 1000
+  if (!(blokTijd > 0)) throw new Error('kon de bloktijd niet meten')
+
+  let kandidaat = laatsteNr - Math.round((getal(laatste.timestamp) - doelTijd) / blokTijd)
+  kandidaat = Math.max(1, Math.min(kandidaat, laatsteNr))
+  for (let i = 0; i < maxRondes; i++) {
+    const b = await rpc('eth_getBlockByNumber', [hex(kandidaat), false])
+    const verschil = getal(b.timestamp) - doelTijd
+    if (Math.abs(verschil) <= blokTijd * 2) break
+    const stap = Math.round(verschil / blokTijd)
+    const volgende = Math.max(1, Math.min(kandidaat - stap, laatsteNr))
+    if (volgende === kandidaat) break
+    kandidaat = volgende
+  }
+  return { blok: kandidaat, blokTijd, laatsteBlok: laatsteNr }
+}
+
+/**
+ * Alle nonces die deze autorisator in dit venster heeft verbruikt.
+ *
+ * In stukken van `stap` blokken, want de publieke RPC weigert een groter bereik.
+ * Een geweigerde aanroep wordt NOOIT als "geen treffers" doorgegeven: dan stopt
+ * dit met een fout, zodat een onmeetbaar venster niet als leeg venster leest.
+ */
+export async function haalKandidaten(rpc, { asset, authorizer, vanBlok, totBlok, stap = 200, maxAanroepen = 200 }) {
+  // Een bovengrens op het aantal aanroepen, want een te ruim venster is hier
+  // geen trage controle maar een onbedoelde aanval op een publieke dienst: bij
+  // 200 blokken per aanroep kost een venster van een miljoen blokken vijfduizend
+  // verzoeken. Liever vooraf stoppen met een duidelijke reden dan iemands IP
+  // laten blokkeren door ons gereedschap.
+  const nodig = Math.ceil((totBlok - vanBlok + 1) / stap)
+  if (nodig > maxAanroepen) {
+    throw new Error(
+      `that window needs ${nodig} RPC calls (limit ${maxAanroepen}); narrow it, or raise maxAanroepen deliberately`,
+    )
+  }
+  const topics = [AUTHORIZATION_USED_TOPIC, adresAlsTopic(authorizer)]
+  const nonces = []
+  let aanroepen = 0
+  for (let van = vanBlok; van <= totBlok; van += stap) {
+    const tot = Math.min(van + stap - 1, totBlok)
+    const logs = await rpc('eth_getLogs', [{ address: asset, topics, fromBlock: hex(van), toBlock: hex(tot) }])
+    aanroepen++
+    for (const l of logs) {
+      // Drie topics: de gebeurtenis zelf plus twee geindexeerde velden. Een log
+      // met een andere vorm hoort niet bij deze gebeurtenis en wordt genegeerd
+      // in plaats van half geinterpreteerd.
+      if (!Array.isArray(l.topics) || l.topics.length !== 3) continue
+      nonces.push({ nonce: l.topics[2], blok: getal(l.blockNumber), tx: l.transactionHash })
+    }
+  }
+  return { nonces, aanroepen }
+}
+
+/** Het volledige 5.6.4-pad: van bonnetje plus zout naar precies een afrekening. */
+export async function linkBonnetje(rpc, { payload, salt, asset, venster = 400 }) {
+  if (!payload?.payer) throw new Error('het bonnetje heeft geen payer, dus er is geen autorisator')
+  const issuedAt = Number(payload.issuedAt)
+  if (!Number.isFinite(issuedAt) || issuedAt <= 0) throw new Error('het bonnetje heeft geen bruikbare issuedAt')
+
+  const { blok, blokTijd, laatsteBlok } = await blokBijTijd(rpc, issuedAt)
+  const vanBlok = Math.max(1, blok - venster)
+  const totBlok = Math.min(laatsteBlok, blok + venster)
+
+  const { nonces, aanroepen } = await haalKandidaten(rpc, {
+    asset,
+    // 5.6.4 stap 1: de autorisator komt uit het ONDERTEKENDE payer-veld. Nooit
+    // uit een waarde die naast het zout is aangeleverd, want dan kan iemand het
+    // commitment laten openen op de afrekening van een ander.
+    authorizer: payload.payer,
+    vanBlok,
+    totBlok,
+  })
+
+  const uitslag = opentCommitment({
+    receipt: { payload },
+    salt,
+    asset,
+    kandidaatIdentifiers: nonces.map(n => n.nonce),
+  })
+  const treffer = uitslag.linked ? nonces.find(n => n.nonce.toLowerCase() === uitslag.identifier.toLowerCase()) : null
+
+  return {
+    ...uitslag,
+    venster: { vanBlok, totBlok, blokTijd, aanroepen, kandidaten: nonces.length },
+    afrekening: treffer ?? null,
+  }
+}
+
+// ── commandoregel ────────────────────────────────────────────────────────────
+//
+// De vlaggen en de uitslag zijn ENGELS, het commentaar hierboven Nederlands. Dat
+// is geen slordigheid: dit gereedschap is bedoeld om door een vreemde in een
+// protocoldraad gedraaid te worden, en een uitslag die hij niet kan lezen is
+// geen controle. De Nederlandse namen blijven wel werken.
+
+function vlag(namen, standaard) {
+  for (const naam of [].concat(namen)) {
+    const v = process.argv.find(a => a.startsWith(`--${naam}=`))
+    if (v) return v.slice(naam.length + 3)
+  }
+  return standaard
+}
+
+/**
+ * Waar ligt dit bonnetje: in de werkmap van de aanroeper, of meegeleverd met het pakket.
+ *
+ * WAAROM DIT BESTAAT. De drie live voorbeelden worden met het pakket meegeleverd, en
+ * elke publieke uitleg zegt `--receipt=examples/...`. Wie dat via npx draait staat in
+ * zijn EIGEN map, heeft daar geen examples/, en kreeg tot vandaag een kale
+ * ENOENT-stacktrace. Voor een gereedschap dat om narekenbaarheid vraagt is dat de
+ * ergste uitkomst die er is: het commando dat wij publiceren moet draaien bij de
+ * vreemde die het probeert, niet alleen bij ons.
+ *
+ * Een pad dat de aanroeper zelf meegeeft gaat ALTIJD voor. Pas als dat niet bestaat
+ * komt het meegeleverde bestand in beeld, en dan meldt de aanroeper dat ook, want stil
+ * een ander bestand lezen dan gevraagd is erger dan een foutmelding.
+ *
+ * Pure functie met een injecteerbare bestaat-check, zodat een test beide takken kan
+ * aantonen zonder bestanden aan te maken of het proces af te breken.
+ */
+export function kiesBonnetjePad(pad, { bestaat = existsSync } = {}) {
+  if (bestaat(pad)) return { pad, uitPakket: false }
+  const inPakket = fileURLToPath(new URL('../' + String(pad).replace(/^\.?\//, ''), import.meta.url))
+  if (bestaat(inPakket)) return { pad: inPakket, uitPakket: true }
+  return null
+}
+
+if (process.argv[1]?.endsWith('x402-link-onchain.mjs')) {
+  const pad = vlag(['receipt', 'bonnetje'])
+  if (!pad) {
+    console.log(`usage: node src/x402-link-onchain.mjs --receipt=<file.json> [--salt=0x..] [--asset=0x..] [--rpc=<url>] [--window=400]
+
+The file may be the bare artifact ({format,payload,signature}), or any JSON that
+already stores the salt and the asset next to the receipt. Section 5.6.4 needs all
+three: receipt, salt and asset. A receipt and a salt alone cannot link.`)
+    process.exit(2)
+  }
+
+  const gekozen = kiesBonnetjePad(pad)
+  if (!gekozen) {
+    console.log(`cannot find ${pad}, neither here nor inside the package.`)
+    console.log('The three live examples ship with it: examples/receipt-live-base-sepolia.json, -2.json and -3.json.')
+    process.exit(2)
+  }
+  if (gekozen.uitPakket) console.log(`(not found in the working directory, using the copy shipped with the package: ${pad})`)
+  const bestand = JSON.parse(readFileSync(gekozen.pad, 'utf8'))
+  const artefact = bestand.receipt ?? bestand.bonnetje ?? bestand
+  const payload = artefact?.payload ?? artefact
+  const salt = vlag(['salt', 'zout'], bestand.authorizationSalt ?? bestand.salt)
+  const asset = vlag('asset', bestand.asset)
+  const rpcUrl = vlag('rpc', 'https://sepolia.base.org')
+  const venster = Number(vlag(['window', 'venster'], '400'))
+
+  const ontbreekt = [
+    !payload?.payer && 'payer inside the receipt',
+    !salt && 'salt (--salt=)',
+    !asset && 'asset (--asset=)',
+  ].filter(Boolean)
+  if (ontbreekt.length) {
+    console.error('missing: ' + ontbreekt.join(', '))
+    process.exit(2)
+  }
+
+  console.log(`receipt     : version ${payload.version}, payer ${payload.payer}`)
+  console.log(`commitment  : ${payload.authorizationCommitment ?? 'none (version 1)'}`)
+  console.log(`asset       : ${asset}`)
+  console.log(`rpc         : ${rpcUrl}`)
+
+  const rpc = maakRpc(rpcUrl)
+
+  // Drie uitkomsten, drie exitcodes, en dat is precies het onderscheid dat
+  // 5.6.4 sinds faa611f eist: gelinkt, niet gelinkt op een VERKREGEN
+  // kandidatenlijst, of een controle die niet kon draaien. De module gooide al
+  // bij een geweigerde aanroep, maar een onbehandelde fout ziet er voor een
+  // script hetzelfde uit als "niet gelinkt", en dat is nu juist het verschil
+  // waarop een teller een bonnetje ten onrechte zou weggooien.
+  let r
+  try {
+    r = await linkBonnetje(rpc, { payload, salt, asset, venster })
+  } catch (e) {
+    console.log('LINKED      : unknown, the check could not be completed')
+    console.log(`  reason    : ${e.message}`)
+    console.log('  note: this is an incomplete check, not a receipt that fails to link.')
+    process.exit(2)
+  }
+
+  console.log(`searched    : blocks ${r.venster.vanBlok} to ${r.venster.totBlok} (${r.venster.aanroepen} calls, measured block time ${r.venster.blokTijd.toFixed(2)}s)`)
+  console.log(`candidates  : ${r.venster.kandidaten} nonce(s) consumed by this payer in that window`)
+  if (r.linked) {
+    console.log('LINKED      : yes, to exactly one settlement')
+    console.log(`  nonce     : ${r.identifier}`)
+    console.log(`  tx        : ${r.afrekening.tx}`)
+    console.log(`  block     : ${r.afrekening.blok}`)
+    process.exit(0)
+  }
+  console.log(`LINKED      : no (${r.reden})`)
+  console.log('  note: that is a statement about the window searched, not about the whole chain.')
+  process.exit(1)
+}

package/src/x402-metingen-bundel.mjs

@@ -0,0 +1,96 @@
+// Vouwt alle edities samen tot EEN platte lijst: welk eindpunt haalde welke trede,
+// op welke datum, in welke editie.
+//
+// WAAROM DIT BESTAAT. Een badge die een operator op zijn eigen voordeur plakt, moet
+// uit een VASTGELEGDE meting komen en nooit uit een live meting op het moment dat
+// iemand de badge opvraagt. Twee redenen, en de tweede is de belangrijkste:
+//  - live meten betekent dat iedereen onze server kan gebruiken om willekeurige
+//    hosts af te tasten, op ons IP en in ons logboek. Dat is andermans rate limit
+//    en niet de onze om weg te geven.
+//  - een badge die bij elke pagina-weergave opnieuw meet, geeft bij elke storing
+//    een andere uitslag. Een cijfer dat per minuut verandert is geen meting.
+//
+// De prijs daarvan is dat een badge kan VEROUDEREN, en daar is maar een eerlijk
+// antwoord op: de datum staat IN de badge. Dan is een oude badge zichtbaar oud in
+// plaats van stil verkeerd, en dat is precies het patroon dat ons eerder een
+// publieke tekst heeft gekost die weken iets onwaars beweerde.
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+
+const WORTEL = resolve(import.meta.dirname, '..')
+
+/** Alle editie-mappen, nieuwste eerst. Een map is een editie als hij een datum heet. */
+export function editieMappen(basis = join(WORTEL, 'editions')) {
+  if (!existsSync(basis)) return []
+  return readdirSync(basis)
+    .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d))
+    .sort()
+    .reverse()
+}
+
+/**
+ * Leest de live-metingen uit een editie.
+ *
+ * Een editie kan meerdere metingbestanden hebben, waarvan latere eerdere CORRIGEREN
+ * (zoals de hermeting na een ladderwijziging). De later gelezen waarde wint daarom,
+ * en de bestandsnaam waaruit een uitslag komt gaat mee in de bundel zodat niemand
+ * hoeft te raden welke van de twee hij ziet.
+ */
+export function leesEditie(map) {
+  const uit = new Map()
+  const bestanden = ['liveness-payai.json', 'liveness-payai-na-ladderwijziging.json', 'liveness-payai-na-invoerfix.json']
+  for (const naam of bestanden) {
+    const pad = join(map, naam)
+    if (!existsSync(pad)) continue
+    let j
+    try { j = JSON.parse(readFileSync(pad, 'utf8')) } catch { continue }
+    for (const m of j.metingen ?? []) {
+      const trede = m.hoogsteTrede
+      if (typeof trede !== 'number') continue
+      uit.set(m.url, { url: m.url, host: m.host, trede, uitBestand: naam })
+    }
+    // De CONTROLES zijn ook echte metingen, en ze ontbraken hier.
+    //
+    // Gevonden door de badge live na te kijken: ons EIGEN eindpunt kwam terug als
+    // "niet gemeten", omdat het in die ronde de positieve controle was en controles
+    // niet in de metinglijst stonden. Een meetlat die zijn eigen ijkpunt niet kan
+    // tonen, is precies zo kapot als hij klinkt. Een controle krijgt wel een eigen
+    // rol mee, zodat niemand later denkt dat hij uit de steekproef kwam.
+    for (const c of j.controles ?? []) {
+      if (typeof c.gemeten !== 'number' || !c.url) continue
+      let host = null
+      try { host = new URL(c.url).host } catch { host = null }
+      uit.set(c.url, { url: c.url, host, trede: c.gemeten, uitBestand: naam, rol: 'controle' })
+    }
+  }
+  return uit
+}
+
+export function bundel(basis = join(WORTEL, 'editions')) {
+  const metingen = []
+  const gezien = new Set()
+  // Nieuwste editie eerst, en een eindpunt dat daar al in staat wordt niet door een
+  // oudere editie overschreven: een badge hoort de MEEST RECENTE meting te tonen.
+  for (const map of editieMappen(basis)) {
+    for (const m of leesEditie(join(basis, map)).values()) {
+      if (gezien.has(m.url)) continue
+      gezien.add(m.url)
+      metingen.push({ ...m, editie: map })
+    }
+  }
+  return { gegenereerd: new Date().toISOString().slice(0, 10), aantal: metingen.length, metingen }
+}
+
+if (process.argv[1]?.endsWith('x402-metingen-bundel.mjs')) {
+  const b = bundel()
+  const uit = process.argv[2] ?? join(WORTEL, 'editions', 'metingen.json')
+  writeFileSync(uit, JSON.stringify(b, null, 2))
+  const perTrede = new Map()
+  for (const m of b.metingen) perTrede.set(m.trede, (perTrede.get(m.trede) ?? 0) + 1)
+  console.log('endpoints in the bundle: ' + b.aantal)
+  for (const [t, n] of [...perTrede].sort((a, b2) => b2[0] - a[0])) {
+    console.log('  ' + (t >= 0 ? 'L' + t : 'L-') + '  ' + n)
+  }
+  console.log('written: ' + uit)
+}

package/src/x402-offer-receipt.mjs

@@ -0,0 +1,84 @@
+// Onafhankelijke verificatie van het x402 offer-receipt autorisatie-commitment.
+//
+// Geschreven tegen de spec-tekst van de extensie (§5.6 Authorization Commitment),
+// niet tegen een implementatie. Het commitment bindt een bonnetje aan precies één
+// afrekening op de keten, zonder dat het bonnetje die afrekening prijsgeeft.
+//
+// Waarom dit ertoe doet: sinds §5.6.5 (16 oktober 2026) staat in de spec dat een
+// consument die afrekeningen telt ALLEEN geopende commitments mag tellen. Zolang een
+// commitment dicht is, is het een uitspraak van de ondertekenaar over zichzelf: hij
+// kan twee bonnetjes maken voor één afrekening, of een bonnetje dat nergens op
+// uitkomt. Openen is dus geen formaliteit maar het moment waarop een bewering bewijs
+// wordt, en dat is precies wat hier narekenbaar wordt gemaakt.
+
+import { createHash } from 'node:crypto'
+
+const TAG = Buffer.from('x402-receipt-authorization/0', 'ascii')
+const NUL = Buffer.from([0])
+
+const bytes = (h, naam, verwacht) => {
+  const b = Buffer.from(String(h ?? '').replace(/^0x/, ''), 'hex')
+  if (verwacht !== undefined && b.length !== verwacht) {
+    throw new Error(`${naam} moet ${verwacht} bytes zijn, kreeg ${b.length}`)
+  }
+  return b
+}
+
+// §5.6.2. Elk veld na `method` heeft een vaste lengte, dus het voorbeeld is
+// ondubbelzinnig. Lengtes worden hier afgedwongen: een veld van de verkeerde lengte
+// zou stilzwijgend een ander commitment opleveren dat nergens op opent.
+export function berekenCommitment({ method, asset, authorizer, identifier, salt }) {
+  if (!method) throw new Error('method ontbreekt')
+  const lengtes = { eip3009: { asset: 20, authorizer: 20 } }[method]
+  if (!lengtes) throw new Error(`onbekende authorizationMethod: ${method}`)
+
+  const pre = Buffer.concat([
+    TAG, NUL,
+    Buffer.from(method, 'ascii'), NUL,
+    bytes(asset, 'asset', lengtes.asset),
+    bytes(authorizer, 'authorizer', lengtes.authorizer),
+    bytes(identifier, 'identifier', 32),
+    bytes(salt, 'salt', 32),
+  ])
+  return '0x' + createHash('sha256').update(pre).digest('hex')
+}
+
+// §5.6.4 stap 1: de authorizer komt uit het ONDERTEKENDE payer-veld van het bonnetje,
+// nooit uit een waarde die naast het zout wordt aangeleverd. Anders kan iemand een
+// commitment laten openen op een afrekening van een ander.
+export function opentCommitment({ receipt, salt, asset, kandidaatIdentifiers }) {
+  const payload = receipt?.payload ?? receipt
+  const method = payload?.authorizationMethod
+  const commitment = payload?.authorizationCommitment
+  if (!method || !commitment) return { linked: false, reden: 'receipt carries no commitment' }
+
+  const treffers = []
+  for (const identifier of kandidaatIdentifiers ?? []) {
+    let berekend
+    try { berekend = berekenCommitment({ method, asset, authorizer: payload.payer, identifier, salt }) } catch { continue }
+    if (berekend.toLowerCase() === String(commitment).toLowerCase()) treffers.push(identifier)
+  }
+
+  // §5.6.4 stap 3: precies een MOET matchen, anders linkt het bonnetje niet.
+  // Bewust fail-closed: nul en twee zijn allebei "niet gelinkt", niet "waarschijnlijk".
+  if (treffers.length === 1) return { linked: true, identifier: treffers[0] }
+  if (treffers.length === 0) return { linked: false, reden: 'no candidate opens this commitment' }
+  return { linked: false, reden: `${treffers.length} candidates open the same commitment, so it is ambiguous` }
+}
+
+// Het voorbeeld dat in hun eigen spec staat, met de verwachte uitkomst erbij.
+// Het commit staat erbij omdat die PR nog open is: een tak beweegt, een commit niet.
+// Zonder dat nummer zou deze vector stil kunnen verouderen zonder dat de test valt.
+// Dit is de hele interop-toets voor deze kant: rekenen wij uit hun tekst hetzelfde
+// getal uit als zij publiceren?
+export const SPEC_VOORBEELD = {
+  bron: 'x402-foundation/x402, specs/extensions/extension-offer-and-receipt.md §5.6.2, tak receipt-authorization-commitment op commit 0e492d6730bef14b9c722428386c114f3475a914',
+  invoer: {
+    method: 'eip3009',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    authorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66',
+    identifier: '0x5135a00b531830a13a751f3c48944d7a5fdfde7a3b87f73493591cd77efdef4f',
+    salt: '0x10d2ae5f0c8536e82d882bf3d2c31a663597e890ca6c3fede0d278fd2a78f655',
+  },
+  verwacht: '0x5d905bbf08a97e04ab551d276d8e94b1abaff7d0737324d360e983c2796af23b',
+}