A Discovery Document and Signed Catalogue for Capability Marketplaces Independent

alexar76@rambler.ru

Internet Network Working Group agents discovery marketplace well-known signed catalogue This document defines a JSON discovery document, served at a well-known URI, that carries the public properties a client needs before using a capability index: its name, the protocol versions it serves, the location of its catalogue, and the key that signs the catalogue. It also states the requirements for that signed catalogue and defines one signature profile. Discovery between indexes, catalogue exchange and trust are out of scope.

Introduction Capability indexes (catalogues of invocable services offered by many providers) are now operated by many independent parties, alongside protocols for machine payment , agent-to-agent interaction and tool registries . A client that wants to use an index needs a few public facts about it: a name, the protocol versions in use, where the catalogue is, and which key signs the catalogue. describes the current mechanisms for publishing such facts. Each defines its own well-known resource and schema, and signed catalogues rarely specify the exact bytes that are signed. This document defines one discovery document and requires any signature profile used with it to specify the signed bytes. Catalogue exchange between indexes and peer admission are described separately in .

Scope This document specifies: a discovery document served at a well-known URI (); requirements for the catalogue referenced from it (), including requirements for any signature profile, and one profile (); key pinning by readers (). It does not specify how indexes find each other, how catalogues are exchanged or ranked, how capabilities are invoked or paid for, how providers are identified, or reputation.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Index:: A server that catalogues capabilities and answers queries about them.
Capability:: A named, invocable unit of work offered by a provider and catalogued by an index.
Catalogue:: The signed document, referenced from the discovery document, that lists an index's capabilities.
Discovery document:: The JSON document defined in .
Reader:: Any party that retrieves the discovery document or the catalogue.
Signature profile:: A named set of rules that defines the signature algorithm, the signed bytes and the verification procedure for a catalogue.

Discovery document An index MUST serve a discovery document at the well-known URI /.well-known/agent-marketplace (, ) using the "https" scheme. It MUST answer both GET and HEAD requests for it, and SHOULD support conditional requests (, Section 13). The document is a JSON object with media type application/json. The following members are defined: Member Type Requirement name string REQUIRED protocol_versions array of string REQUIRED catalogue_url string (URI) REQUIRED signer_public_key string REQUIRED when the catalogue is signed signature_profile string REQUIRED when the catalogue is signed capabilities_count number RECOMMENDED generated_at string (date-time) RECOMMENDED peers array of string (URI) OPTIONAL

name:: A human-readable label chosen by the operator. Names are not unique, and a reader MUST NOT use a name as an identifier.
protocol_versions:: The versions of the catalogue and query interfaces that the index serves, as opaque strings. A reader that recognises none of them MUST NOT use the index.
catalogue_url:: An absolute "https" URI of the catalogue (). It MAY be on a different host from the discovery document.
signer_public_key, signature_profile:: The public key that signs the catalogue, encoded as the profile specifies, and the name of that profile (). Readers handle the key as described in .
capabilities_count, generated_at:: The number of catalogue entries when the document was generated, and the generation time (). They are informative; a reader MUST NOT treat a mismatch with the catalogue as an error.
peers:: Discovery-document URIs of other indexes that the operator publishes. This document gives them no further meaning; restricts what a federating index lists here.

A reader MUST ignore members it does not recognise and MUST NOT reject a document because it contains them. A member defined by this document MUST NOT change type or meaning in a later revision; a different meaning requires a new member.

Example

Relation to api-catalog defines /.well-known/api-catalog, in which a host lists its own APIs. The discovery document describes an index that lists capabilities of other hosts and identifies the key that signs that list. An index MAY publish both.

The catalogue The resource at catalogue_url is a JSON object. Its full schema depends on the protocol version; this section lists the minimum that every version has to contain.

Minimum content

protocol_version:: A string listed in the discovery document's protocol_versions.
generated_at:: The generation time ().
capabilities:: An array of objects, each with at least name (string), description (string) and input_schema (object).
signature:: A signature object (), when the discovery document names a signature profile.

Requirements for signature profiles A signature profile MUST specify: the signature algorithm and the encoding of keys and signature values; the exact byte string that is signed and how it is derived from the catalogue; for each member that is digested rather than copied into that byte string, its serialisation: handling of absent members, member order, whitespace, and non-ASCII characters; the verification procedure, including inputs that MUST be rejected before the signature is evaluated. Item 3 is required because differences there produce signatures that verify in one implementation and not in another.

Signature object The signature member of a catalogue is a JSON object:

", "public_key": "", "value": "" } ]]> public_key MAY be omitted when the reader already holds a pinned key (). Profiles MAY add members (for example, a second signature with another algorithm), and readers MUST ignore members they do not recognise. A catalogue whose signature is not an object MUST be treated as unsigned.

Key pinning A reader MUST verify a catalogue with the key it has pinned for the index. A key carried in the catalogue, or in the discovery document fetched in the same operation, does not by itself authenticate the catalogue. On first contact the reader SHOULD pin the key that the discovery document advertises and record the time. After that, the reader: MUST NOT accept a different key automatically; SHOULD record any rejected key, with the time and the document that carried it; MAY accept a new key through an explicit operator decision. As a consequence, a key change at the index requires action at each reader. See . A pinned key shows that the current publisher holds the key that was first seen. It does not identify the publisher. A reader's user interface MUST NOT present a verified signature as evidence of the operator's identity.

The ed25519-pipe-2 signature profile This profile is identified by the signature_profile value ed25519-pipe-2. It is the profile used by the implementations listed in .

Algorithm and encodings The signature is Ed25519 over the UTF-8 encoding of the canonical string defined in . Keys and signature values are base64-encoded with the standard alphabet and padding (, Section 4). The algorithm member of the signature object is ed25519.

Canonical string The canonical string is the concatenation of the following five name:value pairs, in this order, separated by the character "|" (U+007C), with no whitespace:

|generated_at:|protocol_version:| tools_hash:

|by_hub_hash:

]]>

(shown on two lines for width; the string contains no line break) where: <n> is the decimal value of capabilities_count, or 0 if absent; <t> is the value of generated_at, or the empty string if absent; <v> is the value of protocol_version, or v1 if absent; <h1> is the digest () of the capabilities array (the pair name tools_hash follows the deployed wire format, in which the array is named tools); <h2> is the digest of the by_hub object (per-peer metadata in the deployed format). If absent, the empty object {} MUST be digested. Both digests MUST be included. Without tools_hash, an intermediary could change catalogue entries, including prices, without invalidating the signature; without by_hub_hash, it could change per-peer metadata.

Digest rule The digest of a JSON value is the lowercase hexadecimal SHA-256 of the UTF-8 encoding of its serialisation with these rules: object members in ascending order of member name, compared by Unicode code point; member separator , (comma, space) and name separator : (colon, space); non-ASCII characters emitted as themselves, not as \uXXXX escapes; integers without a fractional part; other numbers in the shortest decimal form that round-trips to the same IEEE 754 double; no leading or trailing whitespace. Rule 2 differs from , which emits no whitespace. Changing it would change every existing signature; an RFC 8785 based variant would be defined as a separate profile name.

Verification allows more than one verification equation. With the permissive variant used by several common libraries, a signature made with a small-order public key can verify for any message. A verifier implementing this profile MUST reject a signature, before evaluating the verification equation, if: the public key, or the point R in the first 32 octets of the signature, has order dividing 8 (with the top bit of the last octet cleared, the encodings 00..00, 01 00..00, 26e8958f..fc05, c7176a70..037a, ecff..ff7f, and the non-canonical edff..ff7f and eeff..ff7f); or the scalar S in the last 32 octets, read as a little-endian integer, is not less than the group order L = 2^252 + 27742317777372353535851937790883648493. Keys and signatures generated as specified in pass these checks except with negligible probability.

Test vectors Signed example catalogues and negative vectors (tampered members, wrong signer, version downgrade, small-order key), with a runner, are published at .

Security Considerations

Signatures and transport The catalogue may be served from a different host, a content distribution network or a cache, and a reader that stores a catalogue needs to verify it again later without the original connection. HTTPS does not cover either case; the catalogue signature does.

Scope of a signature A valid signature shows that the holder of the pinned key produced the catalogue and that it has not been modified. It does not show that the listed capabilities exist, behave as described, or cost what is stated. A reader's user interface MUST NOT suggest otherwise.

URIs from other parties catalogue_url and peers contain URIs chosen by another party. Before retrieving them, a reader MUST apply the request-forgery safeguards of : refuse private, loopback, link-local, multicast and unspecified addresses (including IPv4-mapped forms), check the resolved address at connection time, not follow redirects automatically, and limit response size and time.

Key rotation Because readers do not accept a new key automatically (), rotating a key interrupts readers until their operators act. An index SHOULD announce a rotation in advance and SHOULD sign with the old and new keys in parallel for a period, using additional members of the signature object. A rotation announcement mechanism may be defined in a later revision.

IANA Considerations

Well-Known URI registration IANA is requested to register the following in the "Well-Known URIs" registry :

URI suffix:: agent-marketplace
Change controller:: IETF
Specification document:: This document,
Status:: permanent
Related information:: JSON document describing a capability index: name, protocol versions, catalogue location and catalogue signing key.

Signature profile names This document defines one profile name, ed25519-pipe-2. No registry is requested for a single value; if more profiles are defined, a registry with the Specification Required policy would be appropriate.

Implementation Status This section records the status of known implementations at the time of writing, per . It is to be removed before publication as an RFC. Reference implementation (Apache-2.0), deployed on six public indexes operated by the author or affiliated parties. Since 2026-10-30 they serve this document at /.well-known/agent-marketplace in addition to the earlier path /.well-known/ai-market.json, which uses the member names in . Three further implementations by the same author, written from the text and test vectors without the reference source: a Go directory node, a Rust catalogue verifier, and a JavaScript verifier. Writing them found four ambiguities in the text, which were corrected. Two services operated by parties unrelated to the author publish catalogues that verify under ed25519-pipe-2 (checked on 2026-10-30 with the conformance runner in ). Which software they run is not known. No implementation by another party is known to have been written from this document.

Date and Time on the Internet: Timestamps This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The Base16, Base32, and Base64 Data Encodings This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF) Federal Information Processing Standard, FIPS Edwards-Curve Digital Signature Algorithm (EdDSA) This document describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided. The JavaScript Object Notation (JSON) Data Interchange Format JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. Well-Known Uniform Resource Identifiers (URIs) This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. HTTP Semantics The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Improving Awareness of Running Code: The Implementation Status Section This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice. JSON Canonicalization Scheme (JCS) Cryptographic operations like hashing and signing need the data to be expressed in an invariant format so that the operations are reliably repeatable. One way to address this is to create a canonical representation of the data. Canonicalization also permits data to be exchanged in its original form on the "wire" while cryptographic operations performed on the canonicalized counterpart of the data in the producer and consumer endpoints generate consistent results. This document describes the JSON Canonicalization Scheme (JCS). This specification defines how to create a canonical representation of JSON data by building on the strict serialization methods for JSON primitives defined by ECMAScript, constraining JSON data to the Internet JSON (I-JSON) subset, and by using deterministic property sorting. api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs This document defines the "api-catalog" well-known URI and link relation. It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs). A request to the api-catalog resource will return a document providing information about, and links to, the Publisher's APIs. A Survey of AI Agent Discovery Mechanisms Ericsson Ericsson Ericsson Ericsson Ericsson This document surveys mechanisms for AI agent discovery being developed at the IETF, at AAIF, at 3GPP, and in open-source projects. It compares them by discovery model, scope, dynamism, cross-domain reach, and semantic capability. It identifies gaps, overlaps, and conflicts between the approaches to inform future standardization work. Federation Between Capability Indexes: Crawl, Reciprocal Identification and Admission Agent2Agent (A2A) Protocol Specification, version 1.0 Model Context Protocol Registry x402 Payment Protocol Specification, version 2 AIMarket Protocol v2 test vectors and conformance runner

Mapping to the deployed wire format This document Earlier deployed name /.well-known/agent-marketplace /.well-known/ai-market.json catalogue_url manifest_url capabilities tools signature_profile not present; always ed25519-pipe-2 peers (array of URI) peers (array of objects with url) The canonical string, digest rule and verification rule are the same, so a signature valid under one is valid under the other.

Implementation experience These failures in deployed implementations led to requirements in this document: An implementation that omitted by_hub_hash produced catalogues no other implementation could verify (). An earlier published vector set signed a canonical string without the digests (). Three verifiers failed on a signature encoded as a bare string (). A widely used Ed25519 library accepted a signature under a small-order key for an arbitrary message ().

Changes from -00 Editorial: the text was shortened, and explanatory passages were removed or moved to the appendix above. Implementation Status was updated. One wording correction: the requirement to ignore unrecognised members applies to readers; -00 said "index".

Acknowledgements Thanks to the authors of .