Network Working Group A. Artamokhov Internet-Draft Independent Intended status: Standards Track 30 October 2026 Expires: 3 May 2027 A Discovery Document and Signed Catalogue for Capability Marketplaces draft-artamokhov-dawn-marketplace-discovery-01 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. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. Artamokhov Expires 3 May 2027 [Page 1] Internet-Draft Marketplace Discovery October 2026 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Discovery document . . . . . . . . . . . . . . . . . . . . . 4 2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Relation to api-catalog . . . . . . . . . . . . . . . . . 6 3. The catalogue . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Minimum content . . . . . . . . . . . . . . . . . . . . . 6 3.2. Requirements for signature profiles . . . . . . . . . . . 7 3.3. Signature object . . . . . . . . . . . . . . . . . . . . 7 4. Key pinning . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. The ed25519-pipe-2 signature profile . . . . . . . . . . . . 8 5.1. Algorithm and encodings . . . . . . . . . . . . . . . . . 8 5.2. Canonical string . . . . . . . . . . . . . . . . . . . . 8 5.3. Digest rule . . . . . . . . . . . . . . . . . . . . . . . 9 5.4. Verification . . . . . . . . . . . . . . . . . . . . . . 9 5.5. Test vectors . . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6.1. Signatures and transport . . . . . . . . . . . . . . . . 10 6.2. Scope of a signature . . . . . . . . . . . . . . . . . . 10 6.3. URIs from other parties . . . . . . . . . . . . . . . . . 10 6.4. Key rotation . . . . . . . . . . . . . . . . . . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 7.1. Well-Known URI registration . . . . . . . . . . . . . . . 11 7.2. Signature profile names . . . . . . . . . . . . . . . . . 11 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 11 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 9.2. Informative References . . . . . . . . . . . . . . . . . 13 Mapping to the deployed wire format . . . . . . . . . . . . . . . 14 Implementation experience . . . . . . . . . . . . . . . . . . . . 14 Changes from -00 . . . . . . . . . . . . . . . . . . . . . . . . 15 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 Artamokhov Expires 3 May 2027 [Page 2] Internet-Draft Marketplace Discovery October 2026 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. Artamokhov Expires 3 May 2027 [Page 3] Internet-Draft Marketplace Discovery October 2026 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: Artamokhov Expires 3 May 2027 [Page 4] Internet-Draft Marketplace Discovery October 2026 +====================+=================+=====================+ | 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- | RECOMMENDED | | | time) | | +--------------------+-----------------+---------------------+ | peers | array of string | OPTIONAL | | | (URI) | | +--------------------+-----------------+---------------------+ Table 1 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 Artamokhov Expires 3 May 2027 [Page 5] Internet-Draft Marketplace Discovery October 2026 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. Artamokhov Expires 3 May 2027 [Page 6] Internet-Draft Marketplace Discovery October 2026 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": "", "public_key": "", "value": "" } 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: * MUST NOT accept a different key automatically; Artamokhov Expires 3 May 2027 [Page 7] Internet-Draft Marketplace Discovery October 2026 * 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 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:|generated_at:|protocol_version:| tools_hash:

|by_hub_hash:

(shown on two lines for width; the string contains no line break) where: * is the decimal value of capabilities_count, or 0 if absent; * is the value of generated_at, or the empty string if absent; * is the value of protocol_version, or v1 if absent; *

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); Artamokhov Expires 3 May 2027 [Page 8] Internet-Draft Marketplace Discovery October 2026 *

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 Artamokhov Expires 3 May 2027 [Page 9] Internet-Draft Marketplace Discovery October 2026 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. Artamokhov Expires 3 May 2027 [Page 10] Internet-Draft Marketplace Discovery October 2026 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. * 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 Appendix "Mapping to the deployed wire format". * 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 [VECTORS]). Which software they run is not known. Artamokhov Expires 3 May 2027 [Page 11] Internet-Draft Marketplace Discovery October 2026 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, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, May 2011, . [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . Artamokhov Expires 3 May 2027 [Page 12] Internet-Draft Marketplace Discovery October 2026 [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . 9.2. Informative References [A2A] "Agent2Agent (A2A) Protocol Specification, version 1.0", March 2026, . [FEDERATION] Artamokhov, A., "Federation Between Capability Indexes: Crawl, Reciprocal Identification and Admission", Work in Progress, Internet-Draft, draft-artamokhov-dawn-index- federation-01, October 2026, . [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, 3 July 2026, . [MCPREG] "Model Context Protocol Registry", 2026, . [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, . [RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020, . [RFC9727] Smith, K., "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs", RFC 9727, DOI 10.17487/RFC9727, June 2025, . [VECTORS] "AIMarket Protocol v2 test vectors and conformance runner", 2026, . Artamokhov Expires 3 May 2027 [Page 13] Internet-Draft Marketplace Discovery October 2026 [X402] "x402 Payment Protocol Specification, version 2", December 2025, . 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) | +--------------------------------+-----------------------------+ Table 2 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 (Section 5.2). * An earlier published vector set signed a canonical string without the digests (Section 5.2). * Three verifiers failed on a signature encoded as a bare string (Section 3.3). * A widely used Ed25519 library accepted a signature under a small- order key for an arbitrary message (Section 5.4). Artamokhov Expires 3 May 2027 [Page 14] Internet-Draft Marketplace Discovery October 2026 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 Email: alexar76@rambler.ru Artamokhov Expires 3 May 2027 [Page 15]