agent-receipt-verify 0.0.0-stage → 0.2.1

package/src/profiel.mjs

@@ -0,0 +1,145 @@
+// Het profiel inlezen en toetsen, zodat de ladder één waarheid heeft.
+//
+// WAAROM DIT BESTAAT. Onze ladder stond als data in een JavaScript-bestand. Dat is
+// prima voor ons en onbruikbaar voor iedereen anders: een tweede implementatie kan
+// een .mjs niet inlezen, en dus bleef onze meetlat opgesloten in onze eigen code.
+// Precies die opsluiting is wat x402#3396 als probleem benoemt: gereedschappen
+// coderen de regels in code, dus ze lopen uiteen en zijn het oneens over wat een
+// gebrek is. Vanaf nu staat de ladder in profiles/x402-deployed-ladder-v1.json en
+// leest deze code dat bestand. Verandert de ladder, dan verandert het bestand, en
+// dan ziet een vreemde dat aan de versie en de datum.
+//
+// WAAROM EIGEN TOETSING EN GEEN JSON-SCHEMA-BIBLIOTHEEK. Dit project heeft geen
+// verplichte afhankelijkheden en dat is een eigenschap, niet een gemis: een
+// verifieerder die zelf een halve boom aan pakketten binnentrekt, vraagt vertrouwen
+// in plaats van het te geven. Het schema in profiles/profile.schema.json is er voor
+// een buitenstaander die wél een validator heeft. De controles hieronder dekken
+// bovendien iets wat geen JSON-schema kan uitdrukken: de verbanden TUSSEN velden.
+
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const pad = (rel) => fileURLToPath(new URL(rel, import.meta.url))
+
+export const PROFIEL_PAD = pad('../profiles/x402-deployed-ladder-v1.json')
+
+/**
+ * De verbanden die een JSON-schema niet kan uitdrukken, en die allemaal een keer
+ * een echte fout zouden zijn geweest als niemand ze had gecontroleerd.
+ *
+ * Geeft een lijst klachten terug. Leeg is goed. Gooit niet: de aanroeper beslist of
+ * een kapot profiel een harde fout is (bij ons: ja, zie onderaan dit bestand).
+ */
+export function toetsProfiel(p) {
+  const klachten = []
+  const zeg = (m) => klachten.push(m)
+
+  if (!p || typeof p !== 'object') return ['het profiel is geen object']
+  for (const veld of ['profile', 'version', 'published', 'intent', 'outcomes', 'specs', 'checks']) {
+    if (p[veld] === undefined) zeg(`verplicht veld ontbreekt: ${veld}`)
+  }
+  if (!Array.isArray(p.checks) || p.checks.length === 0) return klachten.concat('checks is leeg of geen lijst')
+
+  // Vier uitkomsten, niet drie. Drie is de fout die wij zelf maakten: dan valt
+  // "wij hebben het niet geprobeerd" samen met "wij konden niet beslissen", en een
+  // lezer kan een gat in de meter niet onderscheiden van een gebrek in het eindpunt.
+  const verwachteUitkomsten = ['pass', 'fail', 'skip', 'inconclusive']
+  const gegeven = Object.keys(p.outcomes ?? {}).sort()
+  if (gegeven.join(',') !== verwachteUitkomsten.slice().sort().join(',')) {
+    zeg(`outcomes moet exact ${verwachteUitkomsten.join(', ')} zijn, gevonden: ${gegeven.join(', ') || 'niets'}`)
+  }
+
+  // Elke gepinde spec moet compleet zijn, anders is een clausuleverwijzing een
+  // verwijzing naar wat er vandaag staat.
+  for (const [naam, s] of Object.entries(p.specs ?? {})) {
+    for (const veld of ['repo', 'path', 'commit', 'state']) {
+      if (!s?.[veld]) zeg(`spec ${naam} mist ${veld}`)
+    }
+    if (s?.state && !['merged on main', 'proposed, not merged'].includes(s.state)) {
+      zeg(`spec ${naam} heeft een onbekende state: ${s.state}`)
+    }
+    // Een voorstel zonder PR-nummer is niet terug te vinden door een vreemde.
+    if (s?.state === 'proposed, not merged' && typeof s.pullRequest !== 'number') {
+      zeg(`spec ${naam} is een voorstel maar noemt geen pullRequest`)
+    }
+  }
+
+  const ids = new Set(), keys = new Set(), niveaus = []
+  for (const c of p.checks) {
+    if (ids.has(c.id)) zeg(`dubbele check-id: ${c.id}`)
+    ids.add(c.id)
+    if (keys.has(c.key)) zeg(`dubbele check-key: ${c.key}`)
+    keys.add(c.key)
+    niveaus.push(c.level)
+
+    if (!Array.isArray(c.clause) || c.clause.length === 0) zeg(`${c.id} heeft geen clausuleverwijzing`)
+    for (const cl of c.clause ?? []) {
+      if (!p.specs?.[cl.spec]) zeg(`${c.id} verwijst naar een onbekende spec: ${cl.spec}`)
+      if (!cl.section || String(cl.section).length < 3) zeg(`${c.id} heeft een clausule zonder sectie`)
+    }
+    for (const rv of c.relatedVectors ?? []) {
+      if (!p.relatedWork?.[rv.set]) zeg(`${c.id} verwijst naar een onbekende vectorset: ${rv.set}`)
+    }
+    if (!['skip', 'inconclusive'].includes(c.whenNotObservable)) {
+      zeg(`${c.id} heeft een onbekende whenNotObservable: ${c.whenNotObservable}`)
+    }
+    if (!c.assertion?.evaluator || !c.assertion?.describes) zeg(`${c.id} mist evaluator of describes`)
+    if (!['MUST', 'SHOULD'].includes(c.normative)) zeg(`${c.id} heeft een onbekende normative: ${c.normative}`)
+    if (!c.input || typeof c.input.pays !== 'boolean') zeg(`${c.id} zegt niet of hij betaalt`)
+
+    // DE INVARIANT DIE HET MEEST UITMAAKT. Een passief profiel mag een check die
+    // een echte afrekening nodig heeft nooit als fail rapporteren: dat zou een
+    // eindpunt afstraffen voor iets dat wij bewust niet hebben geprobeerd. Precies
+    // deze regel staat als zin in onze CONFORMANCE.md en was tot nu toe nergens
+    // mechanisch afgedwongen.
+    if (c.input?.pays === true && c.whenNotObservable !== 'skip') {
+      zeg(`${c.id} heeft een afrekening nodig maar valt niet terug op skip, dus een passieve run zou hem kunnen afkeuren`)
+    }
+    if (c.input?.pays === false && c.whenNotObservable === 'skip') {
+      zeg(`${c.id} heeft geen afrekening nodig, dus skip is hier de verkeerde terugval: dit hoort inconclusive te zijn`)
+    }
+  }
+
+  // Niveaus moeten 0 tot n zijn zonder gat: de hoogste-trede-regel loopt van onder
+  // naar boven en stopt bij de eerste die niet haalt. Een gat zou die lus stil laten
+  // stoppen op een trede die niemand heeft gemeten.
+  const gesorteerd = niveaus.slice().sort((a, b) => a - b)
+  for (let i = 0; i < gesorteerd.length; i++) {
+    if (gesorteerd[i] !== i) { zeg(`niveaus lopen niet van 0 op zonder gat: ${gesorteerd.join(', ')}`); break }
+  }
+  for (let i = 1; i < niveaus.length; i++) {
+    if (niveaus[i] <= niveaus[i - 1]) { zeg('checks staan niet op oplopend niveau in het bestand'); break }
+  }
+
+  return klachten
+}
+
+/** Laadt en toetst het profiel. Gooit bij een klacht, want een kapot profiel levert stil verkeerde metingen. */
+export function laadProfiel(bestand = PROFIEL_PAD) {
+  const p = JSON.parse(fs.readFileSync(bestand, 'utf8'))
+  const klachten = toetsProfiel(p)
+  if (klachten.length) throw new Error('profiel niet in orde:\n  ' + klachten.join('\n  '))
+  return p
+}
+
+/**
+ * De treden zoals de rest van deze codebase ze al jaren verwacht, nu AFGELEID uit
+ * het profiel in plaats van ernaast geschreven. Bewust dezelfde veldnamen, zodat
+ * geen enkele aanroeper hoeft te veranderen en de omzetting dus aantoonbaar niets
+ * aan het gedrag verandert.
+ */
+export function tredenUitProfiel(p) {
+  return p.checks.map((c) => ({
+    sleutel: c.key,
+    nummer: c.level,
+    naam: c.name,
+    eis: c.requirement,
+    meetbaarZonderTeBetalen: c.input.pays === false,
+    // Nieuw en alleen toegevoegd: waar deze trede vandaan komt, en of dat een
+    // voorstel is. Daarmee kan een uitslag eerlijk zeggen tegen wat hij meet.
+    profielId: c.id,
+    clausule: c.clause.map((cl) => `${p.specs[cl.spec].path} §${cl.section}`),
+    citeertVoorstel: c.clause.some((cl) => p.specs[cl.spec].state === 'proposed, not merged'),
+    terugvalAlsNietTeZien: c.whenNotObservable,
+  }))
+}

package/src/x402-conformance-check.mjs

@@ -0,0 +1,194 @@
+// Meet een x402-eindpunt tegen de conformance-ladder uit CONFORMANCE.md.
+//
+// WAAROM DIT BESTAAT, en het is geen getal maar een EENHEID. Er zijn metingen van
+// de x402-wereld in omloop ("zoveel duizend resources", "nul declareren de
+// offer-receipt-extensie") en geen enkele zegt wat er precies geteld is. Zonder
+// gedefinieerde eenheid is elk percentage onvergelijkbaar: twintig eindpunten van
+// een operator tellen dan twintig keer zo zwaar als een operator met een
+// eindpunt, en "werkt" betekent voor iedere meter iets anders. Dat is precies hoe
+// een eerdere eigen meting een onzinnige kop opleverde (15 procent, volledig
+// bepaald door een partij met honderden paden) tot er per operator geteld werd.
+//
+// Dit bestand is daarom de meetlat, niet de uitslag. Wie een andere uitslag
+// krijgt kan hier nalezen wat wij geteld hebben en waar hij het anders doet.
+//
+// GEDRAGSREGELS, hard, want dit raakt eindpunten van anderen:
+//  - precies een GET of POST per eindpunt, zoals een gewone koper
+//  - NOOIT betalen, nooit fuzzen, nooit herhalen om iets af te dwingen
+//  - een eerlijke user-agent zodat iedereen in zijn log ziet wie dit was
+//  - rustig tempo tussen eindpunten
+//
+// WAT NIET MEETBAAR IS ZONDER TE BETALEN, en dat staat met opzet in de uitslag in
+// plaats van weggelaten: trede 3 tot 5 vereisen een echte afrekening. Een
+// eindpunt dat daar "ongemeten" scoort is NIET afgekeurd; het is niet getoetst.
+
+import { verifyOfferSignature, TREDEN } from './x402-conformance-treden.mjs'
+
+const UA = 'x402-conformance-check/1 (read-only, github.com/holistis/agent-receipt-verify)'
+
+const slaap = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/** Base64-JSON uit een header halen zonder op een kapotte header te klappen. */
+function decodeerHeader(waarde) {
+  if (!waarde) return null
+  try {
+    return JSON.parse(Buffer.from(waarde, 'base64').toString('utf8'))
+  } catch {
+    try {
+      return JSON.parse(waarde)
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * Trede 0 tot 2 van de ladder, meetbaar zonder te betalen.
+ *
+ * Geeft per trede HAALT / HAALT_NIET / ONGEMETEN terug plus het bewijs waarop dat
+ * oordeel rust, zodat iemand anders hetzelfde eindpunt kan nameten en kan zien
+ * waar hij afwijkt.
+ */
+export async function meetEindpunt(url, { fetchImpl = fetch, methode = 'POST', lichaam = null } = {}) {
+  const r = { url, treden: {}, bewijs: {} }
+  let resp
+  try {
+    resp = await fetchImpl(url, {
+      method: methode,
+      headers: { 'User-Agent': UA, Accept: 'application/json', 'Content-Type': 'application/json' },
+      // Een gedeclareerd voorbeeldlichaam als de index er een geeft. Een lege {} naar
+      // een route die velden eist, levert een 400 die niets over x402 zegt: dan meet
+      // je je eigen verzoek in plaats van het eindpunt.
+      body: methode === 'GET' || methode === 'DELETE' ? undefined : lichaam != null ? JSON.stringify(lichaam) : '{}',
+      signal: AbortSignal.timeout(15000),
+    })
+  } catch (e) {
+    r.treden.t0 = 'ONGEMETEN'
+    r.bewijs.t0 = 'not reachable: ' + String(e.message).slice(0, 80)
+    return r
+  }
+
+  r.bewijs.status = resp.status
+  const tekst = await resp.text().catch(() => '')
+  const kopNaam = [...resp.headers.keys()].find((k) => /^payment-required$/i.test(k))
+  const uitKop = decodeerHeader(kopNaam ? resp.headers.get(kopNaam) : null)
+  const uitLichaam = tekst.trim() ? decodeerHeader(tekst) : null
+  const aanbod = uitKop ?? uitLichaam
+
+  // TREDE 0: vraagt dit eindpunt uberhaupt om betaling, op de manier die x402
+  // voorschrijft? Een 402 met niets erin haalt dit NIET: de eisen horen mee te
+  // komen, anders weet een koper niet wat hij moet betalen.
+  if (resp.status !== 402) {
+    r.treden.t0 = 'HAALT_NIET'
+    r.bewijs.t0 = 'status ' + resp.status + ' instead of 402'
+    return r
+  }
+  const accepts = aanbod?.accepts ?? aanbod?.paymentRequirements
+  if (!Array.isArray(accepts) || accepts.length === 0) {
+    r.treden.t0 = 'HAALT_NIET'
+    r.bewijs.t0 = kopNaam
+      ? 'a 402 with a Payment-Required header but no usable accepts'
+      : 'a 402 with no payment requirements, neither in the header nor in the body'
+    return r
+  }
+  const a = accepts[0]
+  const mist = ['scheme', 'network', 'payTo'].filter((k) => !a?.[k])
+  if (!(a?.maxAmountRequired ?? a?.amount)) mist.push('an amount')
+  if (mist.length) {
+    r.treden.t0 = 'HAALT_NIET'
+    r.bewijs.t0 = 'accepts[0] is missing: ' + mist.join(', ')
+    return r
+  }
+  r.treden.t0 = 'HAALT'
+  r.bewijs.t0 = a.scheme + ' on ' + a.network + ', ' + (a.maxAmountRequired ?? a.amount) + ' to ' + a.payTo
+  r.bewijs.accepts0 = { scheme: a.scheme, network: a.network, asset: a.asset ?? null, payTo: a.payTo }
+
+  // TREDE 1: declareert het de offer-receipt-extensie? Dat is de stap van "ik wil
+  // geld" naar "ik geef een bewijsstuk af".
+  const ext = aanbod?.extensions ?? {}
+  const orSleutel = Object.keys(ext).find((k) => /offer-?receipt/i.test(k))
+  if (!orSleutel) {
+    r.treden.t1 = 'HAALT_NIET'
+    r.bewijs.t1 = 'no offer-receipt in extensions (' + (Object.keys(ext).join(', ') || 'no extensions') + ')'
+    return r
+  }
+  r.treden.t1 = 'HAALT'
+  r.bewijs.t1 = 'declares ' + orSleutel
+
+  // TREDE 2: zit er een ONDERTEKEND aanbod in, en klopt die handtekening? Een
+  // declaratie zonder geldige handtekening is een bewering over een bewering.
+  const aanbiedingen = ext[orSleutel]?.info?.offers ?? []
+  if (!Array.isArray(aanbiedingen) || aanbiedingen.length === 0) {
+    r.treden.t2 = 'HAALT_NIET'
+    r.bewijs.t2 = 'declares the extension but carries no signed offer'
+    return r
+  }
+  const controle = await verifyOfferSignature(aanbiedingen[0])
+  // ONGEMETEN, niet HAALT_NIET, als de controle niet KON draaien: een onbekend
+  // algoritme of een sleutel die niet op te halen is, zegt niets over de partij.
+  // Dit bestand beweert dat beginsel in zijn eigen kop al en volgde het hier niet.
+  r.treden.t2 = controle.ok ? 'HAALT' : controle.ongemeten ? 'ONGEMETEN' : 'HAALT_NIET'
+  r.bewijs.t2 = controle.ok
+    ? 'offer signed by ' + controle.signer + (controle.codering ? ', key as ' + controle.codering : '')
+    : controle.ongemeten
+      ? 'the signature was not checked: ' + controle.reden
+      : 'the signature on the offer does not verify: ' + controle.reden
+  // Een afwijkende sleutelcodering is een eigen uitslag: de handtekening klopt, maar
+  // een verifieerder die zich aan de specificatie houdt weigert de sleutel. Dat mag
+  // niet verdwijnen achter een groene trede.
+  if (controle.afwijking) r.bewijs.t2afwijking = controle.afwijking
+
+  // TREDE 3 tot 5 vereisen een echte betaling. Ongemeten is niet afgekeurd, en
+  // dat onderscheid hoort in de uitslag te staan in plaats van te verdwijnen.
+  for (const t of ['t3', 't4', 't5']) {
+    r.treden[t] = 'ONGEMETEN'
+    r.bewijs[t] = 'needs a real settlement, not attempted'
+  }
+  return r
+}
+
+/** De hoogste trede die dit eindpunt aantoonbaar haalt. */
+export function hoogsteTrede(meting) {
+  let hoogste = -1
+  for (const t of TREDEN) {
+    if (meting.treden[t.sleutel] === 'HAALT') hoogste = t.nummer
+    else break
+  }
+  return hoogste
+}
+
+export async function meetLijst(urls, { fetchImpl = fetch, pauzeMs = 1200 } = {}) {
+  const uit = []
+  for (const u of urls) {
+    uit.push(await meetEindpunt(u, { fetchImpl }))
+    if (pauzeMs) await slaap(pauzeMs)
+  }
+  return uit
+}
+
+if (process.argv[1]?.endsWith('x402-conformance-check.mjs')) {
+  const urls = process.argv.slice(2).filter((a) => a.startsWith('http'))
+  if (urls.length === 0) {
+    console.log('usage: node src/x402-conformance-check.mjs <url> [url ...]')
+    console.log('')
+    console.log('Measures levels 0 to 2 of the ladder in CONFORMANCE.md without paying.')
+    console.log('Levels 3 to 5 need a real settlement and are reported as not measured.')
+    process.exitCode = 2
+  } else {
+    const metingen = await meetLijst(urls)
+    for (const m of metingen) {
+      const h = hoogsteTrede(m)
+      console.log((h >= 0 ? 'L' + h : 'L-') + '  ' + m.url)
+      for (const t of TREDEN) {
+        const staat = m.treden[t.sleutel]
+        if (!staat) continue
+        const merk = staat === 'HAALT' ? ' ok ' : staat === 'HAALT_NIET' ? 'FAIL' : ' .. '
+        console.log('    [' + merk + '] L' + t.nummer + ' ' + t.naam + ': ' + (m.bewijs[t.sleutel] ?? ''))
+      }
+    }
+    const gehaald = metingen.filter((m) => hoogsteTrede(m) >= 0).length
+    console.log('')
+    console.log(gehaald + ' of ' + metingen.length + ' endpoint(s) reach level 0 or higher.')
+    console.log('Definition and what is deliberately not measured: CONFORMANCE.md')
+  }
+}

package/src/x402-conformance-treden.mjs

@@ -0,0 +1,246 @@
+// De conformance-ladder, en de optionele crypto die een deel ervan nodig heeft.
+//
+// De treden staan hier als DATA en niet als losse regels code, omdat de ladder de
+// eenheid is: wie een ander getal publiceert moet kunnen aanwijzen welke trede hij
+// anders heeft gelegd. Verandert de ladder, dan verandert de editie, en dan hoort
+// dat met een datum opgeschreven te worden in CONFORMANCE.md.
+//
+// WIJZIGING 2026-10-17, en dit is een gebrek in onze eigen eenheid dat een meting
+// blootlegde, geen uitbreiding uit enthousiasme. Trede 2 eiste een eip712-artefact.
+// Een live meting vond een partij die zijn aanbod wel degelijk ondertekent, maar in
+// JWS met een EdDSA-handtekening en een did:web-sleutel. Onze meetlat noemde dat een
+// mislukking. Dat is niet hun fout maar onze fout: een ladder die een geldige vorm
+// niet kent, meet die partij verkeerd en zou een gepubliceerd cijfer onjuist maken.
+// Trede 2 vraagt daarom nu om een ONDERTEKEND aanbod waarvan de handtekening
+// verifieert, ongeacht in welke van beide vormen.
+
+import { createPublicKey, verify as edVerify } from 'node:crypto'
+import { laadProfiel, tredenUitProfiel } from './profiel.mjs'
+
+// De treden komen nu UIT het profiel en staan niet meer hier. Zie src/profiel.mjs
+// voor waarom: een meetlat die in een .mjs opgesloten zit, kan geen tweede
+// implementatie voeden, en dat is precies de scheefgroei die x402#3396 benoemt.
+// De veldnamen zijn met opzet onveranderd gelaten, zodat geen enkele aanroeper
+// hoeft te wijzigen en de omzetting dus aantoonbaar niets aan het gedrag verandert.
+// Nieuw per trede, alleen toegevoegd: profielId, clausule, citeertVoorstel en
+// terugvalAlsNietTeZien.
+export const PROFIEL = laadProfiel()
+export const TREDEN = tredenUitProfiel(PROFIEL)
+
+/**
+ * ethers, als het er is.
+ *
+ * Een BARE import, en bewust niet een pad op iemands schijf. Een vorige versie van
+ * dit project importeerde ethers vanaf file:///C:/Code/... en dat werkte alleen op
+ * de machine van de schrijver: voor iedere vreemde viel de controle stil weg en hij
+ * kreeg zonder het te weten een zwakkere uitslag dan wij. Dat is precies het
+ * tegenovergestelde van wat een onafhankelijke verifieerder hoort te zijn.
+ *
+ * Niet aanwezig betekent ONGEMETEN en nooit stil overgeslagen: de aanroeper krijgt
+ * een reden terug die hij in zijn uitslag kan laten zien.
+ */
+let ethersCache
+export async function laadEthers() {
+  if (ethersCache !== undefined) return ethersCache
+  try {
+    ethersCache = await import('ethers')
+  } catch {
+    ethersCache = null
+  }
+  return ethersCache
+}
+
+/** §4.3, normatief. Reist niet over de lijn, dus een verifier haalt het uit de spec. */
+export const OFFER_EIP712_DOMAIN = { name: 'x402 offer', version: '1', chainId: 1 }
+export const OFFER_EIP712_TYPES = {
+  Offer: [
+    { name: 'version', type: 'uint256' },
+    { name: 'resourceUrl', type: 'string' },
+    { name: 'scheme', type: 'string' },
+    { name: 'network', type: 'string' },
+    { name: 'asset', type: 'string' },
+    { name: 'payTo', type: 'string' },
+    { name: 'amount', type: 'string' },
+    { name: 'validUntil', type: 'uint256' },
+  ],
+}
+
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+function base58decode(s) {
+  let getal = 0n
+  for (const teken of s) {
+    const i = B58.indexOf(teken)
+    if (i < 0) throw new Error('not 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:web naar de URL van zijn document, volgens de did:web-methode.
+ *
+ * Zonder pad staat het document op /.well-known/did.json; met padsegmenten staat
+ * het op dat pad. Een poort zit in het eerste segment als %3A.
+ */
+export function didWebNaarUrl(did) {
+  if (!did.startsWith('did:web:')) throw new Error('not a did:web')
+  const delen = did.slice('did:web:'.length).split(':').map(decodeURIComponent)
+  const host = delen[0]
+  if (!host || host.includes('/')) throw new Error('unusable did:web host')
+  return delen.length === 1
+    ? 'https://' + host + '/.well-known/did.json'
+    : 'https://' + host + '/' + delen.slice(1).join('/') + '/did.json'
+}
+
+/**
+ * Een did:web-document ophalen.
+ *
+ * DIT HAALT EEN URL OP DIE DE GEMETEN PARTIJ ZELF BEPAALT, en dat is precies waarom
+ * er grenzen om heen staan. Dit bestand wordt door vreemden gedraaid, dus het mag
+ * nooit een omleiding naar een intern adres volgen of naar iets anders dan https:
+ *  - alleen https, afgedwongen door didWebNaarUrl
+ *  - redirect: 'error', zodat een omleiding een fout is en niet stil gevolgd wordt
+ *  - een harde tijdslimiet
+ * Dit lost niet elk denkbaar geval op (een host die zelf naar een intern adres
+ * resolveert blijft mogelijk), en dat staat hier zodat het een bekende grens is in
+ * plaats van een stille aanname.
+ */
+async function haalDidDocument(did, { fetchImpl = fetch } = {}) {
+  const url = didWebNaarUrl(did)
+  const resp = await fetchImpl(url, {
+    headers: {
+      'User-Agent': 'x402-conformance-check/1 (read-only, github.com/holistis/agent-receipt-verify)',
+      Accept: 'application/did+json, application/json',
+    },
+    redirect: 'error',
+    signal: AbortSignal.timeout(15000),
+  })
+  if (!resp.ok) throw new Error('did document at ' + url + ' returned ' + resp.status)
+  return await resp.json()
+}
+
+/**
+ * Een Ed25519 publieke sleutel uit een verificationMethod halen.
+ *
+ * Geeft {sleutel, codering} terug. De codering is ZELF een uitslag: did-core wil bij
+ * publicKeyMultibase een multibase-multicodec-waarde (0xed01 voor Ed25519, die als
+ * z6Mk... rendert). Een rauwe sleutel van 32 bytes zonder die prefix is afwijkend,
+ * maar de handtekening eronder kan prima kloppen. Dat onderscheid hoort gemeld te
+ * worden in plaats van opgelost of doodgezwegen: wie zich aan de specificatie houdt
+ * weigert zo een sleutel, en de eigenaar hoort dat te weten.
+ */
+export function sleutelUitVerificationMethod(vm) {
+  if (vm?.publicKeyJwk) {
+    return { sleutel: createPublicKey({ key: vm.publicKeyJwk, format: 'jwk' }), codering: 'publicKeyJwk' }
+  }
+  const mb = vm?.publicKeyMultibase
+  if (typeof mb !== 'string' || !mb.startsWith('z')) {
+    throw new Error('no usable publicKeyJwk or base58btc publicKeyMultibase')
+  }
+  const ruw = base58decode(mb.slice(1))
+  const omhul = (k) =>
+    createPublicKey({ key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), k]), format: 'der', type: 'spki' })
+  if (ruw.length === 34 && ruw[0] === 0xed && ruw[1] === 0x01) {
+    return { sleutel: omhul(ruw.subarray(2)), codering: 'multicodec ed25519-pub' }
+  }
+  if (ruw.length === 32) {
+    return {
+      sleutel: omhul(ruw),
+      codering: 'raw 32 bytes',
+      afwijking:
+        'publicKeyMultibase decodes to 32 raw bytes with no multicodec prefix; did-core requires the 0xed01 ed25519-pub prefix for a Multikey, which renders as z6Mk...',
+    }
+  }
+  throw new Error('publicKeyMultibase decodes to ' + ruw.length + ' bytes, which is neither 32 nor 0xed01 plus 32')
+}
+
+/**
+ * Controleer een JWS-aanbod.
+ *
+ * Alleen EdDSA (Ed25519), want dat is wat er in het veld is aangetroffen. Een ander
+ * alg geeft een expliciete reden terug in plaats van een stille mislukking: niet
+ * ondersteund is iets anders dan ongeldig, en dat verschil hoort in de uitslag.
+ */
+export async function verifyJwsOffer(artefact, { fetchImpl = fetch } = {}) {
+  const jws = typeof artefact.signature === 'string' ? artefact.signature : null
+  if (!jws || jws.split('.').length !== 3) return { ok: false, reden: 'jws artifact without a three-part compact signature' }
+  const [h, p, s] = jws.split('.')
+  let kop
+  try {
+    kop = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'))
+  } catch {
+    return { ok: false, reden: 'jws header is not json' }
+  }
+  if (kop.alg !== 'EdDSA') {
+    return { ok: false, ongemeten: true, reden: 'alg ' + kop.alg + ' is not supported by this checker, so the signature was NOT checked' }
+  }
+  const kid = kop.kid
+  if (typeof kid !== 'string' || !kid.startsWith('did:web:')) {
+    return { ok: false, ongemeten: true, reden: 'kid is not a did:web, so the key could not be resolved: ' + String(kid).slice(0, 60) }
+  }
+  let doc
+  try {
+    doc = await haalDidDocument(kid.split('#')[0], { fetchImpl })
+  } catch (e) {
+    return { ok: false, ongemeten: true, reden: 'could not resolve the key: ' + String(e.message).slice(0, 90) }
+  }
+  const vms = Array.isArray(doc?.verificationMethod) ? doc.verificationMethod : []
+  const vm = vms.find((v) => v?.id === kid) ?? (kid.includes('#') ? vms.find((v) => String(v?.id).endsWith('#' + kid.split('#')[1])) : null)
+  if (!vm) return { ok: false, reden: 'the did document has no verificationMethod with id ' + kid.slice(0, 70) }
+  let uit
+  try {
+    uit = sleutelUitVerificationMethod(vm)
+  } catch (e) {
+    return { ok: false, reden: 'key in the did document unusable: ' + String(e.message).slice(0, 110) }
+  }
+  const ok = edVerify(null, Buffer.from(h + '.' + p, 'ascii'), uit.sleutel, Buffer.from(s, 'base64url'))
+  if (!ok) return { ok: false, reden: 'the EdDSA signature does not verify against the key in the did document' }
+  let lading = null
+  try {
+    lading = JSON.parse(Buffer.from(p, 'base64url').toString('utf8'))
+  } catch {
+    return { ok: false, reden: 'signature verifies but the payload is not json' }
+  }
+  return { ok: true, signer: kid, codering: uit.codering, afwijking: uit.afwijking, payload: lading }
+}
+
+/**
+ * Controleer de handtekening op een aangeboden offer.
+ *
+ * Geeft {ok, signer} of {ok:false, reden}. Zonder ethers komt er bij een eip712-
+ * artefact expliciet ongemeten terug, want een overgeslagen controle mag nooit als
+ * geslaagde controle lezen.
+ */
+export async function verifyOfferSignature(artefact, opties = {}) {
+  if (!artefact || typeof artefact !== 'object') {
+    return { ok: false, reden: 'geen eip712-artefact met payload en signature' }
+  }
+  if (artefact.format === 'jws') return await verifyJwsOffer(artefact, opties)
+  if (artefact.format !== 'eip712' || !artefact.payload || !artefact.signature) {
+    // De oude tekst blijft staan voor het geval dat er al een test op leunt, met
+    // de werkelijk aangetroffen vorm erachter zodat een uitslag bruikbaar blijft:
+    // "onbekend formaat" is iets anders dan "ongeldige handtekening".
+    const vorm = artefact.format ? 'format "' + String(artefact.format).slice(0, 20) + '"' : 'no format field'
+    return { ok: false, reden: 'geen eip712-artefact met payload en signature (' + vorm + ')' }
+  }
+  const ethers = await laadEthers()
+  if (!ethers) {
+    return { ok: false, ongemeten: true, reden: 'ethers niet beschikbaar, dus de handtekening is NIET gecontroleerd' }
+  }
+  try {
+    const signer = ethers.verifyTypedData(OFFER_EIP712_DOMAIN, OFFER_EIP712_TYPES, artefact.payload, artefact.signature)
+    return { ok: true, signer }
+  } catch (e) {
+    return { ok: false, reden: String(e.message).slice(0, 90) }
+  }
+}