use well-known providers/ instead of providers/{peerid}

Author: guillaumemichel

src/ipips/ipip-0501.md

@@ -23,13 +23,13 @@ tags: ['ipips']
 ## Summary
 
 This IPIP introduces a secure mechanism for advertising `/tls/http`
-multiaddresses in the Amino DHT. By requiring HTTP servers to host an empty
-file at the well-known path `.well-known/libp2p/amino/providers/{peerid}` for
-each authorized libp2p peer ID the DHT servers ensure that only providers
-safelisted by the HTTP server can advertise its content. This additional
-verification step mitigates potential DDoS attacks and prevents malicious
-actors from falsely claiming that HTTP server hosts content, while leaving
-existing libp2p records unaffected.
+multiaddresses in the Amino DHT. HTTP servers are now required to host a text
+file at the well-known path `.well-known/libp2p/amino/providers` listing the
+libp2p peer IDs of authorized providers. This verification step enables DHT
+servers to ensure that only approved providers can advertise content,
+mitigating potential DDoS attacks and preventing malicious actors from falsely
+asserting that an HTTP server hosts content, all while leaving existing libp2p
+records unchanged.
 
 ## Motivation
 
@@ -64,49 +64,46 @@ into browsers, as browser development teams prioritize robust DDoS prevention.
 
 ## Detailed design
 
-Providers advertising content hosted on an HTTP server MUST host an empty file
-for each libp2p peer ID authorized to advertise that HTTP server’s content to
-the Amino DHT at the [well-known
-location](https://www.rfc-editor.org/rfc/rfc8615)
-`.well-known/libp2p/amino/providers/{peerid}`. The existence of an empty file
-named of the the peer ID serves as the authorization marker. The filename peer
+Providers advertising content hosted on an HTTP server MUST host a text file at
+the [well-known location](https://www.rfc-editor.org/rfc/rfc8615)
+`.well-known/libp2p/amino/providers`. This file lists the libp2p peer IDs that are
+authorized to advertise that HTTP server’s content to the Amino DHT. Each peer
 ID MUST follow [string representation from Libp2p PeerID
 specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation)
-(base58btc multihash or CID with libp2p codec):
+(base58btc multihash or CID with libp2p codec), with one peer ID per line:
 
 ```
-.well-known/libp2p/amino/providers/12D3KooBase58MH
-.well-known/libp2p/amino/providers/k51KooBase36CID
+12D3KooBase58MH
+k51KooBase36CID
 ```
 
-By hosting these individual empty files, the HTTP server grants permission for
-the corresponding providers to advertise that the server hosts content
-identified by any CID.
+By listing these peer IDs, the HTTP server grants permission for the
+corresponding providers to advertise that the server hosts content identified
+by any CID.
 
-When a DHT server receives an `ADD_PROVIDER` RPC from a given `peerID` that
-includes `/tls/http` multiaddresses, it MUST verify the existence of the file
-at `.well-known/libp2p/amino/provider/peerID` on the advertised HTTP server by
-issuing an HTTP HEAD request for each `/tls/http` address. If the HTTP HEAD
-request does not return a `200` response, the DHT server MUST NOT associate
-that `/tls/http` address with the provider record.
+When a DHT Server receives an `ADD_PROVIDER` RPC that includes `/tls/http`
+multiaddresses, it MUST verify that the provider’s peer ID is listed in the
+file located at `.well-known/libp2p/amino/providers` on the advertised HTTP
+server, for all `/tls/http` addresses. If the peer ID is not found, the server
+MUST NOT associate that `/tls/http` address with the provider record.
 
 DHT Servers SHOULD cache the resolved mapping of each `/tls/http` multiaddress
 to its peer IDs for the duration of the `ReprovideInterval` to minimize
-repetitive HTTP HEAD requests. Additionally, for addresses that fail
-verification, a negative cache entry SHOULD be maintained for 15 minutes to
+repetitive HTTP GET requests. Additionally, for addresses that fail
+verification, a negative cache entry SHOULD be maintained for `15` minutes to
 reduce unnecessary load and mitigate potential abuse.
 
 ## Design rationale
 
 * **Lightweight Verification:** Each HTTP server only answers approximately one
-HEAD request per DHT Server per `ReprovideInterval`, regardless of the number
+GET request per DHT Server per `ReprovideInterval`, regardless of the number
 of CIDs being advertised.
 * **Revocation Considerations:** If a provider revokes a peer ID, the
 previously published records will persist until the next reprovide cycle. Thus,
 a cache duration equal to the `ReprovideInterval` is appropriate.
 * **Negative Caching:** A 15-minute negative cache prevents malicious actors
-from triggering repeated HEAD requests, as the cost of generating a DHT provide
-request is higher than that of performing an HTTP HEAD, mitigating
+from triggering repeated GET requests, as the cost of generating a DHT provide
+request is higher than that of performing an HTTP GET, mitigating
 amplification attacks.
 
 ### User benefit
@@ -127,7 +124,7 @@ record.
 
 Given that there are currently around 10k DHT servers in the Amino DHT
 ([source](https://web.archive.org/web/20250404174746/https://probelab.io/ipfs/amino/#dht-availability-classified-overall-plot)),
-the HTTP server is expected to receive roughly 10k HEAD requests every
+the HTTP server is expected to receive roughly 10k GET requests every
 `ReprovideInterval`, one from each DHT server.
 
 Around 300k libp2p clients interact with the Amino DHT on a daily basis
@@ -161,7 +158,7 @@ expected from current providers.
 
 The same verification mechanism could be used by other content routing systems,
 such as IPNI. For more control, it is recommended that each content routing
-system use a dedicated path, e.g `.well-known/libp2p/ipni/provider/{peerid}`
+system use a dedicated path, e.g `.well-known/libp2p/ipni/providers`
 for IPNI.
 
 ### Security
@@ -229,7 +226,7 @@ it lacks a "server-only" authentication option. While mutual authentication
 could be halted after the server responds with an HTTP 401 status and includes
 its own PeerID in the HTTP header, this approach introduces notable challenges:
 
-* It increases complexity, requiring not just a standard HTTP HEAD request but
+* It increases complexity, requiring not just a standard HTTP GET request but
 also the implementation of a custom Authorization header workflow.
 * It restricts the HTTP server to representing only a single PeerID, preventing
 the sharding of announcements across multiple PeerIDs and thus making
@@ -252,16 +249,18 @@ even years for full adoption by DHT servers. In addition, if other applications
 begin using this generic file, DHT servers may end up retrieving unnecessary
 extra information.
 
-#### Single `.well-known/libp2p/amino/providers` file
+#### Flat `.well-known/libp2p/amino/providers/{peerid}` empty files
 
-An alternative approach is to consolidate all authorized peer IDs into a single
-file located at `.well-known/libp2p/amino/providers` instead of using separate
-files at `.well-known/libp2p/amino/providers/{peerid}`. However, this method
-has drawbacks. DHT servers would need to download more data than they would
-with a simple HTTP HEAD request. Additionally, they cannot benefit from caching
-all addresses contained in the `.well-known/libp2p/amino/providers` at once,
-because they should only cache addresses used by an actual DHT node to avoid
-caching an unbounded number of peer IDs.
+An alternative approach is to host an empty file for each authorized provider
+peer ID at `./well-known/libp2p/amino/providers/{peerid}`. This approach allows
+for HTTP HEAD requests instead of GET requests, which is more efficient on the
+wire.
+
+However, this method doesn't support the different [string representation
+from the Libp2p PeerID
+specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation)
+and would lead to false negatives if the DHT server looks for another
+string representation than the one used on the HTTP server.
 
 #### Reuse `did:web` Method Specification