Internet-Draft Marketplace Discovery October 2026
Artamokhov Expires 3 May 2027 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-artamokhov-dawn-marketplace-discovery-01
Published:
Intended Status:
Standards Track
Expires:
Author:
A. Artamokhov
Independent

A Discovery Document and Signed Catalogue for Capability Marketplaces

Abstract

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.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 3 May 2027.

▲

Table of Contents

1. Introduction

Capability indexes (catalogues of invocable services offered by many providers) are now operated by many independent parties, alongside protocols for machine payment [X402], agent-to-agent interaction [A2A] and tool registries [MCPREG]. 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.

[I-D.jimenez-dawn-discovery-landscape] 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 [FEDERATION].

1.1. Scope

This document specifies:

  • a discovery document served at a well-known URI (Section 2);

  • requirements for the catalogue referenced from it (Section 3), including requirements for any signature profile, and one profile (Section 5);

  • key pinning by readers (Section 4).

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.

1.2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.3. 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 Section 2.

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.

2. Discovery document

An index MUST serve a discovery document at the well-known URI /.well-known/agent-marketplace ([RFC8615], Section 7.1) using the "https" scheme. It MUST answer both GET and HEAD requests for it, and SHOULD support conditional requests ([RFC9110], Section 13).

The document is a JSON object [RFC8259] with media type application/json. The following members are defined:

Table 1
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 [RFC3986] of the catalogue (Section 3). 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 (Section 5). Readers handle the key as described in Section 4.

capabilities_count, generated_at:

The number of catalogue entries when the document was generated, and the generation time ([RFC3339]). 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; [FEDERATION] 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.

2.1. Example 

{
  "name": "Example Capability Hub",
  "protocol_versions": ["v1", "v2"],
  "catalogue_url": "https://hub.example/catalogue",
  "signer_public_key": "11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=",
  "signature_profile": "ed25519-pipe-2",
  "capabilities_count": 47,
  "generated_at": "2026-10-30T09:00:00Z",
  "peers": [
    "https://other.example/.well-known/agent-marketplace"
  ]
}

2.2. Relation to api-catalog

[RFC9727] 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.

3. 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.

3.1. Minimum content

protocol_version:

A string listed in the discovery document's protocol_versions.

generated_at:

The generation time ([RFC3339]).

capabilities:

An array of objects, each with at least name (string), description (string) and input_schema (object).

signature:

A signature object (Section 3.3), when the discovery document names a signature profile.

3.2. Requirements for signature profiles

A signature profile MUST specify:

  1. the signature algorithm and the encoding of keys and signature values;

  2. the exact byte string that is signed and how it is derived from the catalogue;

  3. 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;

  4. 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.

3.3. Signature object

The signature member of a catalogue is a JSON object:

{
  "algorithm": "<profile-defined>",
  "public_key": "<encoded public key, OPTIONAL>",
  "value": "<encoded signature>"
}

public_key MAY be omitted when the reader already holds a pinned key (Section 4). 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.

4. 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:

As a consequence, a key change at the index requires action at each reader. See Section 6.4.

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.

5. 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 Section 8.

5.1. Algorithm and encodings

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

5.2. 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:

capabilities_count:<n>|generated_at:<t>|protocol_version:<v>|
tools_hash:<h1>|by_hub_hash:<h2>

(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 (Section 5.3) 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.

5.3. Digest rule

The digest of a JSON value is the lowercase hexadecimal SHA-256 [RFC6234] of the UTF-8 encoding of its serialisation with these rules:

  1. object members in ascending order of member name, compared by Unicode code point;

  2. member separator , (comma, space) and name separator : (colon, space);

  3. non-ASCII characters emitted as themselves, not as \uXXXX escapes;

  4. integers without a fractional part; other numbers in the shortest decimal form that round-trips to the same IEEE 754 double;

  5. no leading or trailing whitespace.

Rule 2 differs from [RFC8785], which emits no whitespace. Changing it would change every existing signature; an RFC 8785 based variant would be defined as a separate profile name.

5.4. Verification

[RFC8032] 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:

  1. 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

  2. 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 [RFC8032] pass these checks except with negligible probability.

5.5. Test vectors

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

6. Security Considerations

6.1. 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.

6.2. 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.

6.3. 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 [FEDERATION]: 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.

6.4. Key rotation

Because readers do not accept a new key automatically (Section 4), 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.

7. IANA Considerations

7.1. Well-Known URI registration

IANA is requested to register the following in the "Well-Known URIs" registry [RFC8615]:

URI suffix:

agent-marketplace

Change controller:

IETF

Specification document:

This document, Section 2

Status:

permanent

Related information:

JSON document describing a capability index: name, protocol versions, catalogue location and catalogue signing key.

7.2. 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.

8. Implementation Status

This section records the status of known implementations at the time of writing, per [RFC7942]. It is to be removed before publication as an RFC.

No implementation by another party is known to have been written from this document.

9. References

9.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3339]
Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, , <https://www.rfc-editor.org/rfc/rfc3339>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/rfc/rfc3986>.
[RFC4648]
Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <https://www.rfc-editor.org/rfc/rfc4648>.
[RFC6234]
Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, , <https://www.rfc-editor.org/rfc/rfc6234>.
[RFC8032]
Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, , <https://www.rfc-editor.org/rfc/rfc8032>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8259]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/rfc/rfc8259>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/rfc/rfc8615>.
[RFC9110]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.

9.2. Informative References

[A2A]
"Agent2Agent (A2A) Protocol Specification, version 1.0", , <https://a2a-protocol.org/latest/specification/>.
[FEDERATION]
Artamokhov, A., "Federation Between Capability Indexes: Crawl, Reciprocal Identification and Admission", Work in Progress, Internet-Draft, draft-artamokhov-dawn-index-federation-01, , <https://datatracker.ietf.org/doc/html/draft-artamokhov-dawn-index-federation-01>.
[I-D.jimenez-dawn-discovery-landscape]
Jimenez, J., Feng, J., Arkko, J., Kühlewind, M., and R. Kandoi, "A Survey of AI Agent Discovery Mechanisms", Work in Progress, Internet-Draft, draft-jimenez-dawn-discovery-landscape-00, , <https://datatracker.ietf.org/doc/html/draft-jimenez-dawn-discovery-landscape-00>.
[MCPREG]
"Model Context Protocol Registry", , <https://registry.modelcontextprotocol.io/>.
[RFC7942]
Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, , <https://www.rfc-editor.org/rfc/rfc7942>.
[RFC8785]
Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, , <https://www.rfc-editor.org/rfc/rfc8785>.
[RFC9727]
Smith, K., "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs", RFC 9727, DOI 10.17487/RFC9727, , <https://www.rfc-editor.org/rfc/rfc9727>.
[VECTORS]
"AIMarket Protocol v2 test vectors and conformance runner", , <https://github.com/alexar76/aimarket-protocol/tree/main/test-vectors>.
[X402]
"x402 Payment Protocol Specification, version 2", , <https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md>.

Mapping to the deployed wire format

Table 2
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:

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 [I-D.jimenez-dawn-discovery-landscape].

Author's Address

Aleksandr Artamokhov
Independent