Aithos Agent Card Registry (0.2.0)

Cursor-paginated. There is no search, no ranking and no scoring, and entries carry no badge of any kind.

Ties on updatedAt are broken by agentId, so the order is total and a cursor can neither skip nor repeat an entry. A client ends a listing on an empty page, not on a missing nextCursor: the registry may return a cursor whenever the page filled, without knowing whether anything follows.

A projection: status, current digest, the authorized key set, timestamps, certified domains and same-origin links. It is a convenience, never a substitute for verifying the card.

This is also the only endpoint that distinguishes a withdrawn entry from one that never existed: it answers 200 with status: WITHDRAWN, where the card and key-set paths answer 404 for both.

The body is cardBytes verbatim. The registry never re-serializes a stored card on read, because a re-serialized card is a different document and its signatures no longer verify.

ETag is opaque, in the sense of RFC 9110, and a client must not parse it as a digest. The API origin happens to derive it from the card digest; the CDN origin serves whatever validator the object store computed — two origins, two shapes, one endpoint. A client that needs the digest computes it from the bytes it received, which is not a workaround but the only correct behaviour: a digest handed over by the same server whose answer it is meant to check establishes nothing.

On 404 and 410. The API origin distinguishes a withdrawn entry from an absent one; the CDN origin, which serves objects the reconciler deletes on withdrawal, has nothing left to answer 410 from. Consumers MUST treat 404 from this path as "no current card" without inferring which of the two it means, and read the record (§7.3) when the difference matters.

Each key carries its kid — the RFC 7638 thumbprint of that key, matching the kid in the protected header of any signature it produced.

The registry rebuilds each entry from the key material it verified rather than republishing the JWK as submitted, so a submitter cannot place a kid, an alg or any other member of their choosing into the published set. The only members served are kty, crv, the coordinates, kid and use: "sig".

A withdrawn entry serves nothing here, with the same 404 shape as the card path.

Immutable exact bytes. The digest is in the request path, so it never needs carrying in a header, and these responses are cached for a year.

One version has one URL. {cardDigest} must be the exact form the registry publishes — sha256: then 64 lowercase hex characters — and any other spelling, the bare hex included, is 404: a second spelling would be a second permanently cached entry for the same bytes, with its own ETag.

agentId is client-derived — the RFC 7638 thumbprint of the genesis key — so the address is known before anything is published and this operation needs no server-allocated identifier.

The body carries the card, the public keys that signed it, and one publication proof per key entering the authorized set: the set of proof signers must equal the set of card signers. A key that signed the card but produced no proof is UNPROVEN_KEY.

That requirement is not bookkeeping. A card's signing payload is public the moment the card is published, so anyone can append a signature to someone else's card without invalidating the original; were one proof enough, an attacker could open an entry in their own name whose published key set names a holder who never asked for it.

Idempotent by construction. Submitting bytes identical to the current version answers 200 and changes nothing, including the sequence — which is exactly what a client retrying after a network timeout does, and its earlier write may well have succeeded. Different bytes at the same version are still refused by §6.4.

In V1 because the registry never holds the publisher's key: the publisher must be able to remove their own entry without asking an operator.

The signed payload names the current cardDigest, which is what prevents an older withdrawal being replayed.

The entry becomes WITHDRAWN, and the registry stops serving its current card and its JWKS. Published versions remain readable at their digest — what was published is not erased, only its status changes. The agentId is never reusable.

Two assertions, each made where that side actually has authority: the domain speaks in its own DNS zone, and the key speaks by signing. Neither half alone is accepted — a zone has no authority over someone's key, and a signed request naming example.com establishes nothing about example.com.

The signed domains array is the complete set: it replaces whatever was there, and an empty array removes every certification. There is no separate deletion operation, for the same reason there is no rotation operation — the request states the whole set, and stating a smaller one is how you shrink it.

The payload carries no cardDigest, unlike a withdrawal: a certification is a statement about domains, not about a card, and binding it to a digest would expire every certification at the next publish for no gain.

Only what the registry can currently observe is published. It re-resolves every requested domain hourly; a domain missing for three consecutive passes stops being listed and returns by itself when its record does.

The canonical origin, the pinned A2A commit, accepted alg values, the limits of §8, the domain certification parameters, and a digest of the field-presence table of §5.2.

The presence-table digest is the load-bearing member. A2A pins a protocol commit but publishes no table derived from it, so two implementations can read the same commit and still disagree about one field — which yields two canonical documents and two signatures over what looks like the same card. The digest turns "we pinned the same commit" into something a second implementation can check.