For agents that look other agents up

Your agent asked one directory where to send the booking. What if it was wrong?

John tells Pim, his personal agent, to book a trip with Travel26. Pim looks up Travel26's booking agent, gets an answer, and sends John's details there. The answer came from one place. If that place was stale, tampered with, or answering Pim differently from everyone else, nothing in the answer says so.

An agent is usually listed in more than one place: its own DNS zone, a registry, a transparency log, the company's catalog. sm-divergence asks all of them, reduces each answer to the same shape, compares them, and signs a record of what each one said. Agreement becomes something Pim can show. Disagreement becomes a finding that names who said what.

Checking the live service…
Asking one source

Pim takes the answer it gets

  • PimLooks the booking agent up in one registry. It returns an agent card address.
  • The answerWell-formed, served over TLS, and unable to say whether anyone else would give the same one.
  • John's optionsTrust it. There is nothing to check it against, and nothing to show afterwards.
One answer. Nothing to compare it with.
Asking every source

The answers are compared

  • SweepThe zone through two resolvers, the registry, the log, the catalog. Each answer is present, absent, or an error with a reason.
  • CompareAddress against address, digest against digest. A source that failed makes no claim; it is never counted as "not listed".
  • RecordEvery claim, every finding and the verdict, content-addressed and signed. Checked in the browser, offline.
Agreement Pim can show. Disagreement with names on it.
01 / How a sweep works

Five steps. Each source keeps its own wire format; the comparison doesn't care.

Travel26's booking agent is listed in four places, and every run of this demo builds all four: a zone served over DNS-over-HTTPS, a registry, a transparency log that issues signed receipts, and a catalog document. The library asks them over HTTP; nothing is mocked inside it.

1 · Ask every source

One adapter per place the agent is listed. Each knows that source's own id for the agent and its own format.

SVCB row · JSON record · COSE receipt · catalog entry
2 · Reduce

Every answer becomes the same small view: where the agent's card is, and what it should hash to. Three spellings of one digest become one.

RecordView(endpoint, digest)
3 · Classify

Present, absent, or error. A timeout, a 503, a receipt that doesn't verify, a revoked registration: each is an error with its reason, and none is a claim of absence.

present · absent · error(outcome)
4 · Compare

The claims are diffed. Different address, different digest, one source missing the agent, one source telling two vantages different things.

AGREE · DIVERGENT · INSUFFICIENT
5 · Sign the record

One record per sweep, whatever the verdict: an AGREE record is the proof the check ran. Canonical JSON, a content address, an Ed25519 signature.

verifyRecord(record) → ok

One source alone is INSUFFICIENT, never AGREE. A verdict says whether the sources agree with each other. It doesn't say which one is right.

02 / The stories

Each story runs live against fresh sources. Run one yourself.

Every run builds a new zone, registry, log and catalog for Travel26, changes what one of them says, runs the sweep, and checks the result. Below is the latest live run of each story. While a run is kept, its sources stay open under /runs/<id>/.

03 / The record

Check the latest record yourself, in this browser.

This page recomputes the record's content address and verifies its signature itself (WebCrypto when available, pure JavaScript otherwise). It doesn't ask the server whether the record is valid.

No live run yet.

A valid record proves that this key signed exactly these claims and that nothing changed since. It doesn't prove the signer asked the sources honestly, and it doesn't prove any source told the truth. This site's key is at /key.

For the technically minded: the record is RFC 8785 canonical JSON. record_id is SHA-256 over every member except itself and signature; signature is Ed25519 over every member except itself; sweeper is a did:key, which is the public key. Format corroboration/0.4, specified in the repository.

04 / Your sources

The same sweep, against the places your agents are really listed.

Install

The library

Python 3.11+. Adapters for a DNS zone, a registry record by id, a transparency log and a published catalog; bring your own with three methods.

pip install 'sm-divergence[ans,attestation]'
One subject

From the command line

Ask a zone through a resolver you choose, a log and a catalog about one agent, and print each claim, each finding and the verdict.

python examples/live_sweep.py agent.example.com \
  --zone --doh https://…/dns-query \
  --log https://… --catalog https://…
In your agent

Before it acts on a lookup

Sweep, then decide. The record is what you keep: what every source said at that moment, signed.

(result,) = await Corroborator(sources).check([agent_id])
record = build_corroboration_record(result, …)
05 / What it is

What this is, and what it isn't.

What this is

  • A working demo of sm-divergence on the sm-resolver kernel: the DNS, registry, log and catalog adapters, the comparison, and the signed Corroboration Record.
  • John, Pim and Travel26 are fictional. Every name ends in .example, and every key is made for the run.
  • The four sources are real servers of their formats: DNS answers in wire format over RFC 8484, COSE_Sign1 receipts with RFC 9162 inclusion proofs, signed status tokens, a catalog document. The library reads them with the same code it uses against production sources.
  • What goes wrong in a story goes wrong in a source. Every check reads the sweep's result or the signed record.

What it isn't

  • Not a verdict on who is right. DIVERGENT means the sources disagree. Deciding which one to believe is a policy, and it is yours.
  • Not proof the sources are independent. Four listings fed from one database agree with each other however wrong that database is.
  • Not a check of the agent card itself. The card is never fetched. Sources' stated addresses and digests are compared with each other.
  • Not proof of an honest sweeper. A signature shows which key signed a record and that it hasn't changed, not that the signer asked what the record says it asked.
  • Not a monitor. A sweep is one moment. Two sources that agree now can disagree in an hour.
  • Not independently tested. One team built the sources, the stories and the checks.
06 / Resources

The code, the spec, and the demos next to this one.