agent-receipt-verify 0.0.0-stage → 0.2.1

package/src/x402-discovery-census.mjs

@@ -0,0 +1,247 @@
+// Census of the DECLARED layer of one x402 discovery index, counted per host.
+//
+// WAAROM DIT APART STAAT VAN x402-conformance-check.mjs. Dat bestand meet een
+// eindpunt LIVE: het stuurt een verzoek en leest wat er terugkomt. Dit bestand
+// raakt geen enkel eindpunt van iemand anders aan. Het leest alleen wat partijen
+// ZELF in een discovery-index hebben laten registreren. Dat zijn twee
+// verschillende beweringen en ze mogen nooit tot een cijfer samengeknepen worden:
+//
+//   gedeclareerd  = wat in de index staat, door de partij zelf aangemeld
+//   live          = wat het eindpunt vandaag werkelijk antwoordt
+//
+// Een census van de eerste is goedkoop en volledig. Een meting van de tweede kost
+// een verzoek aan iemand anders en kan daarom alleen op een steekproef. Daarom
+// deze volgorde: eerst de census, en de census bepaalt waar de live-steekproef
+// naar kijkt. Een willekeurige steekproef trekken voor je weet wat er te vinden
+// is, is verzoeken verspillen aan andermans server.
+//
+// DE EENHEID IS DE HOST, NIET DE RESOURCE. Een partij met driehonderd paden zou
+// anders driehonderd keer zo zwaar wegen als een partij met een pad. Zie
+// CONFORMANCE.md; dit bestand telt op dezelfde eenheid.
+//
+// WAT DIT NIET IS, en dit hoort in elke uitslag die eruit komt:
+//  - geen ecosysteem-meting. Het is EEN index, op EEN dag.
+//  - host is niet hetzelfde als operator. Twee subdomeinen van hetzelfde bedrijf
+//    tellen hier als twee. Dat is een bekende grens, niet stilzwijgend opgelost.
+//  - een registratie zegt niets over of het eindpunt vandaag nog leeft.
+
+const UA = 'x402-conformance-check/1 (read-only, github.com/holistis/agent-receipt-verify)'
+const INDEX = 'https://facilitator.payai.network/discovery/resources'
+const PAGINA = 1000
+
+const slaap = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * De door de partij zelf gedeclareerde invoer: padparameters en voorbeeldlichaam.
+ *
+ * Toegevoegd 2026-10-17, nadat de eerste editie bleek dat de index SJABLOON-URL's
+ * bevat (".../v1/ip/:ip") en dat wij die letterlijk opvroegen. De index levert de
+ * waarde ernaast; wij gebruikten hem niet. Dat gaf een 400 die niets over x402 zei.
+ * Dit veld staat er zodat een volgende meting dat niet overdoet.
+ */
+export function gedeclareerdeInvoer(item) {
+  const ext = item?.extensions ?? {}
+  for (const k of Object.keys(ext)) {
+    const inp = ext[k]?.info?.input
+    if (inp && typeof inp === 'object') {
+      return {
+        pathParams: inp.pathParams ?? null,
+        queryParams: inp.queryParams ?? null,
+        body: inp.body ?? null,
+      }
+    }
+  }
+  return { pathParams: null, queryParams: null, body: null }
+}
+
+/** De door de partij zelf gedeclareerde HTTP-methode, of null als hij niets zegt. */
+export function gedeclareerdeMethode(item) {
+  const ext = item?.extensions ?? {}
+  for (const k of Object.keys(ext)) {
+    const m = ext[k]?.info?.input?.method
+    if (typeof m === 'string' && /^(GET|POST|PUT|PATCH|DELETE)$/i.test(m.trim())) {
+      return m.trim().toUpperCase()
+    }
+  }
+  return null
+}
+
+function host(url) {
+  try {
+    return new URL(url).host.toLowerCase()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Haalt de hele index op, pagina voor pagina.
+ *
+ * Een pagina die faalt WERPT, in plaats van stil een korter resultaat te geven.
+ * Een census met een onbekend gat erin is geen census, en een halve uitslag die
+ * zich als heel voordoet is precies de fout die deze hele meetlat moet vermijden.
+ */
+export async function haalIndex({ fetchImpl = fetch, pauzeMs = 800, maxPaginas = 60 } = {}) {
+  const items = []
+  let offset = 0
+  let gemeldTotaal = null
+  for (let p = 0; p < maxPaginas; p++) {
+    const url = INDEX + '?limit=' + PAGINA + '&offset=' + offset
+    const resp = await fetchImpl(url, {
+      headers: { 'User-Agent': UA, Accept: 'application/json' },
+      signal: AbortSignal.timeout(60000),
+    })
+    if (!resp.ok) throw new Error('index page at offset ' + offset + ' returned ' + resp.status)
+    const j = await resp.json()
+    const batch = Array.isArray(j.items) ? j.items : []
+    if (gemeldTotaal === null) gemeldTotaal = j.pagination?.total ?? null
+    // De echte lusindex, niet indexOf: twee registraties kunnen inhoudelijk gelijk
+    // zijn en dan geeft indexOf beide dezelfde positie. De positie bepaalt welke
+    // resource per host de live-steekproef in gaat, dus een verschuiving hier
+    // maakt de steekproef onnavolgbaar voor iemand die hem natrekt.
+    for (let i = 0; i < batch.length; i++) items.push({ item: batch[i], offset: offset + i })
+    offset += batch.length
+    if (batch.length < PAGINA) return { items, gemeldTotaal, paginas: p + 1 }
+    if (pauzeMs) await slaap(pauzeMs)
+  }
+  throw new Error('index did not end within ' + maxPaginas + ' pages')
+}
+
+/** Vouwt de ruwe index samen tot een telling per host. */
+export function censusPerHost(ruw) {
+  const perHost = new Map()
+  let zonderHost = 0
+  const gezieneResources = new Set()
+  let dubbeleResources = 0
+
+  for (const { item, offset } of ruw) {
+    const res = item?.resource
+    const h = host(res)
+    if (!h) {
+      zonderHost++
+      continue
+    }
+    if (gezieneResources.has(res)) dubbeleResources++
+    else gezieneResources.add(res)
+
+    if (!perHost.has(h)) {
+      perHost.set(h, {
+        host: h,
+        aantalRegistraties: 0,
+        eersteOffset: offset,
+        eersteResource: res,
+        eersteMethode: gedeclareerdeMethode(item),
+        eersteInvoer: gedeclareerdeInvoer(item),
+        extensieSleutels: new Set(),
+        netwerken: new Set(),
+        schemes: new Set(),
+        x402Versies: new Set(),
+        declareertOfferReceipt: false,
+      })
+    }
+    const o = perHost.get(h)
+    o.aantalRegistraties++
+    // Eerste in index-volgorde is de deterministische keuze voor de live-meting,
+    // zodat iemand anders exact dezelfde steekproef kan natrekken.
+    if (offset < o.eersteOffset) {
+      o.eersteOffset = offset
+      o.eersteResource = res
+      o.eersteMethode = gedeclareerdeMethode(item)
+      o.eersteInvoer = gedeclareerdeInvoer(item)
+    }
+    for (const k of Object.keys(item?.extensions ?? {})) {
+      o.extensieSleutels.add(k)
+      if (/offer-?receipt/i.test(k)) o.declareertOfferReceipt = true
+    }
+    const a = Array.isArray(item?.accepts) ? item.accepts[0] : null
+    if (a?.network) o.netwerken.add(String(a.network))
+    if (a?.scheme) o.schemes.add(String(a.scheme))
+    if (item?.x402Version != null) o.x402Versies.add(String(item.x402Version))
+  }
+
+  const operators = [...perHost.values()]
+    .map((o) => ({
+      ...o,
+      extensieSleutels: [...o.extensieSleutels].sort(),
+      netwerken: [...o.netwerken].sort(),
+      schemes: [...o.schemes].sort(),
+      x402Versies: [...o.x402Versies].sort(),
+    }))
+    .sort((a, b) => b.aantalRegistraties - a.aantalRegistraties || a.host.localeCompare(b.host))
+
+  return { operators, zonderHost, dubbeleResources, uniekeResources: gezieneResources.size }
+}
+
+if (process.argv[1]?.endsWith('x402-discovery-census.mjs')) {
+  const uitPad = process.argv[2]
+  const ruw = await haalIndex()
+  const c = censusPerHost(ruw.items)
+
+  const extTelling = new Map()
+  for (const o of c.operators) {
+    for (const k of o.extensieSleutels) extTelling.set(k, (extTelling.get(k) ?? 0) + 1)
+  }
+  const netwerkTelling = new Map()
+  for (const o of c.operators) {
+    for (const n of o.netwerken) netwerkTelling.set(n, (netwerkTelling.get(n) ?? 0) + 1)
+  }
+
+  console.log('source      : ' + INDEX)
+  console.log('reported    : ' + ruw.gemeldTotaal + ' resources, in ' + ruw.paginas + ' pages')
+  console.log('seen        : ' + ruw.items.length + ' records, ' + c.uniekeResources + ' distinct resource URLs')
+  if (c.dubbeleResources) console.log('duplicates  : ' + c.dubbeleResources + ' records repeat a resource URL already seen')
+  if (c.zonderHost) console.log('unparseable : ' + c.zonderHost + ' records without a usable URL')
+  console.log('hosts       : ' + c.operators.length)
+  console.log('')
+  console.log('registrations per host, the ten largest:')
+  for (const o of c.operators.slice(0, 10)) {
+    console.log(
+      '  ' + String(o.aantalRegistraties).padStart(6) + '  ' + o.host +
+      '  [' + (o.extensieSleutels.join(', ') || 'no extensions') + ']'
+    )
+  }
+  const een = c.operators.filter((o) => o.aantalRegistraties === 1).length
+  console.log('')
+  console.log('  ' + een + ' of ' + c.operators.length + ' hosts registered exactly one resource')
+  console.log('  largest host holds ' + c.operators[0].aantalRegistraties + ' of ' + c.uniekeResources +
+    ' resources (' + ((c.operators[0].aantalRegistraties / c.uniekeResources) * 100).toFixed(1) + ' percent)')
+  console.log('')
+  console.log('extensions declared, counted per host:')
+  for (const [k, v] of [...extTelling].sort((a, b) => b[1] - a[1])) {
+    console.log('  ' + String(v).padStart(6) + '  ' + k)
+  }
+  const or = c.operators.filter((o) => o.declareertOfferReceipt)
+  console.log('')
+  console.log('offer-receipt declared by ' + or.length + ' of ' + c.operators.length + ' hosts')
+  for (const o of or.slice(0, 25)) console.log('  ' + o.host + '  ' + o.eersteResource)
+  console.log('')
+  console.log('networks, counted per host:')
+  for (const [k, v] of [...netwerkTelling].sort((a, b) => b[1] - a[1]).slice(0, 12)) {
+    console.log('  ' + String(v).padStart(6) + '  ' + k)
+  }
+
+  if (uitPad) {
+    const { writeFileSync, mkdirSync } = await import('node:fs')
+    const { dirname } = await import('node:path')
+    mkdirSync(dirname(uitPad), { recursive: true })
+    writeFileSync(
+      uitPad,
+      JSON.stringify(
+        {
+          bron: INDEX,
+          gemeldTotaal: ruw.gemeldTotaal,
+          paginas: ruw.paginas,
+          recordsGezien: ruw.items.length,
+          uniekeResources: c.uniekeResources,
+          dubbeleResources: c.dubbeleResources,
+          zonderHost: c.zonderHost,
+          operators: c.operators,
+        },
+        null,
+        2
+      )
+    )
+    console.log('')
+    console.log('written: ' + uitPad)
+  }
+}

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)
+    }
+  }
+}