Merge pull request #495 from ipfs/gateway-clarify-peer-id-and-http-auth

libp2p+http: clarify peerid auth optionality and gw type detection

Author: lidel

src/http-gateways/libp2p-gateway.md

@@ -1,48 +1,46 @@
 ---
 title: libp2p+HTTP Transport Gateway Specification
 description: >
-  Describes how HTTP Gateway semantics can be used over libp2p transports.
-date: 2024-04-20
+  Describes how HTTP Gateway semantics can be used over libp2p transports and how libp2p can coexist with other HTTP services on the same host.
+date: 2025-03-06
 maturity: draft
 editors:
   - name: Adin Schmahmann
     github: aschmahmann
     affiliation:
-        name: Protocol Labs
-        url: https://protocol.ai/
+      name: Shipyard
+      url: https://ipshipyard.com
   - name: Marcin Rataj
     github: lidel
-    url: https://lidel.org/
     affiliation:
-        name: Protocol Labs
-        url: https://protocol.ai/
+      name: Shipyard
+      url: https://ipshipyard.com
 xref:
   - path-gateway
   - trustless-gateway
 tags: ['httpGateways', 'lowLevelHttpGateways', 'exchange', 'transport']
 order: 3
 ---
 
-## Introduction
-
 This specification describes how HTTP Gateway semantics
-and APIs can be used over [libp2p](https://github.com/libp2p/specs) transports.
+and APIs can be used over [libp2p](https://github.com/libp2p/specs) transports,
+and how libp2p can coexist with other HTTP services on the same host.
 
-## Specification
+# libp2p HTTP Protocols Manifest
 
-The [libp2p+HTTP specification](https://github.com/libp2p/specs/pull/508)
-describes how to use HTTP semantics over stream transports, as well as how
+The [libp2p+HTTP specification](https://github.com/libp2p/specs/blob/master/http/README.md)
+describes how to use libp2p with HTTP semantics over stream transports, as well as how
 to do discovery of what protocols are available (and where they are mounted).
 
-### `.well-known/libp2p/protocols`
+## `.well-known/libp2p/protocols`
 
-libp2p application sub-protocols exposed behind `/http/1.1` protocol can be
+Any libp2p application sub-protocols exposed behind `/http/1.1` protocol can be
 discovered by the well-known resource (:cite[rfc8615]) at `.well-known/libp2p/protocols`.
 
-#### Protocol identifier
+### Protocol Identifier
 
-In order for a given HTTP Gateway protocol like the :cite[trustless-gateway] to
-work in this environment it requires a protocol identifier to act as a key in
+In order for a pure HTTP Gateway protocol like the :cite[trustless-gateway] to
+coexist with libp2p in this environment it requires a protocol identifier to act as a key in
 the `.well-known/libp2p/protocols` mapping file.
 
 The `/http/1.1` sub-protocol identifier for the IPFS Gateway when used over libp2p is:
@@ -51,7 +49,7 @@ The `/http/1.1` sub-protocol identifier for the IPFS Gateway when used over libp
 /ipfs/gateway
 ```
 
-#### Protocol mounting
+### Protocol Mounting
 
 A reference `.well-known/libp2p/protocols` JSON body with mapping that assumes the gateway to be mounted at `/`:
 
@@ -63,20 +61,20 @@ A reference `.well-known/libp2p/protocols` JSON body with mapping that assumes t
 }
 ```
 
-## Gateway type detection
+# Peer ID Authentication
 
-The protocol identifier is shared among Gateway specifications.
+[Peer ID Authentication over HTTP](https://github.com/libp2p/specs/blob/master/http/peer-id-auth.md) is optional and SHOULD NOT be required by [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/)  HTTP endpoint defined for `/ipfs/gateway` handler.
 
-HTTP server mounted behind the `/ipfs/gateway` identifier MUST expose
-:cite[trustless-gateway], but is free to also support other gateway types and
-features.
+Clients following the Trustless Gateway specification MUST verify each CID individually, without being concerned with peer identity.
+PeerID authentication is not required for trustless retrieval and HTTP-only clients SHOULD work without it.
 
-:::note
+# Gateway Type Detection
 
-Signaling Features on HTTP Gateways is wip in [IPIP-425](https://github.com/ipfs/specs/pull/425).
+The `/ipfs/gateway` protocol identifier is shared among all Gateway specifications.
 
-Until the IPIP is finalized, client implementations SHOULD perform feature
-detection on their own, or assume only the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
-response type from :cite[trustless-gateway] is available.
+An HTTP server mounted behind the `/ipfs/gateway` identifier MUST expose the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
+responses from :cite[trustless-gateway], but MAY also support other gateway types and features.
 
-:::
+Client implementations SHOULD [perform feature detection](https://specs.ipfs.tech/http-gateways/trustless-gateway/#dedicated-probe-paths) on their own,
+or assume only the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
+response type from :cite[trustless-gateway] is available.