ipip: ipns signed records response format

IPIP/0351-gateway-ipns-record-response-format.md

@@ -0,0 +1,77 @@
+# IPIP 0351: IPNS Signed Records Response Format on HTTP Gateways
+
+- Start Date: 2022-11-29
+- Related Issues:
+  - [ipfs/specs/issues/320](https://github.com/ipfs/specs/issues/320)
+  - [ipfs/specs/pull/351](https://github.com/ipfs/specs/pull/351)
+  - [ipfs/kubo/pull/9399](https://github.com/ipfs/kubo/pull/9399)
+
+## Summary
+
+Add IPNS Signed Records response format to the [HTTP Gateway](../http-gateways/).
+
+## Motivation
+
+Currently, the gateway allows for trustless retrieval of data under the `/ipfs`
+namespace, bu fetching the data as a CAR, or Block, and then verifying it locally.
+This is especially important for light IPFS clients, so that they can retrieve
+data from other gateways without delegating any of the trust to them. Unfortunately,
+this is not possible under the `/ipns` namespace.
+
+In contrary to DNSLink, IPNS provides cryptographically-verifiable records that
+can be verified by the client. This means that, if a gateway is able to provide
+the IPNS signed record to an HTTP client, trustless retrieval would also be available
+under the `/ipns` namespace.
+
+In this IPIP, we propose adding [IPNS signed records][ipld-record] as a response
+format to the gateway under the `/ipns` namespace, allowing for trustless
+retrieval of IPNS records.
+
+## Detailed design
+
+The solution is to allow the Gateway to provide an IPNS signed record by
+requesting it using either the `Accept` HTTP header or the `format` URL query.
+
+## Test fixtures
+
+IPNS records for testing can be generated in Kubo by creating an IPNS record:
+
+```bash
+$ ipfs key gen <key-name>
+k51Key
+
+$ ipfs name publish /ipfs/bafyHash --key=<key-name> --ttl=<record-ttl>
+Published to k51Key: /ipfs/bafyHash
+
+$ ipfs routing get /ipns/k51Key > key.pb
+```
+
+## Design rationale
+
+The current gateway already supports different response formats via the
+`Accept` HTTP header and the `format` URL query. This IPIP proposes adding
+one more supported format to that list.
+
+### User benefit
+
+By providing IPNS records through the gateway, IPFS light clients are able
+to race multiple gateways in search for an IPNS record for a certain IPNS key.
+This way, IPFS light clients do not necessarily need to implement the required
+machinery to fetch IPNS records from other IPFS nodes through the DHT or PubSub.
+
+In addition, the retrieval of IPNS records is trustless in the sense that they can
+be verified by the client since the IPNS record includes a cryptographic signature
+provided by its creator.
+
+### Compatibility
+
+This IPIP proposes a new format to be added to the gateway, but does not change
+any prior format. Therefore, this IPIP is backwards compatible. Please note
+that IPNS records are also added  to the [Trustless Gateway](../http-gateways/TRUSTLESS_GATEWAY.md)
+specification.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+[ipld-record]: ../ipns/IPNS.md#ipns-record

src/http-gateways/path-gateway.md

@@ -132,6 +132,7 @@ For example:
 - [application/vnd.ipld.dag-cbor](https://www.iana.org/assignments/media-types/application/vnd.ipld.dag-cbor) – requests [IPLD Data Model](https://ipld.io/docs/data-model/) representation serialized into [DAG-CBOR format](https://ipld.io/docs/codecs/known/dag-cbor/). If the requested CID already has `dag-cbor` (0x71) codec,  data is validated as DAG-CBOR before being returned as-is. Invalid DAG-CBON produces HTTP Error 500.
 - [application/json](https://www.iana.org/assignments/media-types/application/json) – same as `application/vnd.ipld.dag-json`, unless the CID's codec already is `json` (0x0200). Then, the raw JSON block can be returned as-is without any conversion.
 - [application/cbor](https://www.iana.org/assignments/media-types/application/cbor) – same as `application/vnd.ipld.dag-cbor`, unless the CID's codec already is `cbor` (0x51). Then, the raw CBOR block can be returned as-is without any conversion.
+- [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable [IPNS Record](../ipns/IPNS.md#ipns-record) to be returned. Produces 400 Bad Request if the content is not under the IPNS namespace, or contains a path.
 
 ### `Range` (request header)
 
@@ -196,14 +197,16 @@ parameter, if present)
 
 Optional, `format=<format>` can be used to request specific response format.
 
-This is a URL-friendly alternative to sending an [`Accept`](#accept-request-header) header. These are the equivalents:
+This is a URL-friendly alternative to sending an [`Accept`](#accept-request-header) header.
+These are the equivalents:
 - `format=raw` → `Accept: application/vnd.ipld.raw`
 - `format=car` → `Accept: application/vnd.ipld.car`
 - `format=tar` → `Accept: application/x-tar`
 - `format=dag-json` → `Accept: application/vnd.ipld.dag-json`
 - `format=dag-cbor` → `Accept: application/vnd.ipld.dag-cbor`
 - `format=json` → `Accept: application/json`
 - `format=cbor` → `Accept: application/cbor`
+- `format=ipns-record` → `Accept: application/vnd.ipfs.ipns-record`
 
 <!-- TODO Planned: https://github.com/ipfs/go-ipfs/issues/8769
 - `selector=<cid>`  can be used for passing a CID with [IPLD selector](https://ipld.io/specs/selectors)
@@ -570,6 +573,8 @@ The following response types require an explicit opt-in, can only be requested w
   - Arbitrary DAG as a verifiable CAR file or a stream, see [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car).
 - TAR (`?format=tar`)
   - Deserialized UnixFS files and directories as a TAR file or a stream, see [IPIP-288](https://github.com/ipfs/specs/pull/288)
+- IPNS Record
+  - Protobuf bytes representing a verifiable [IPNS Record](../ipns/IPNS.md#record-serialization-format) (multicodec `0x0300`)
 
 # Appendix: notes for implementers
 

src/http-gateways/trustless-gateway.md

@@ -30,6 +30,14 @@ Downloads data at specified CID.
 
 Same as GET, but does not return any payload.
 
+## `GET /ipns/{key}[?{params}]`
+
+Downloads data at specified IPNS Key. Verifiable :cite[ipns-record] can be requested via `?format=ipns-record`
+
+## `HEAD /ipns/{key}[?{params}]`
+
+same as GET, but does not return any payload.
+
 # HTTP Request
 
 Same as in :cite[path-gateway], but with limited number of supported response types.
@@ -47,6 +55,7 @@ Below response types MUST to be supported:
 
 - [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) – requests a single, verifiable raw block to be returned
 - [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) – disables IPLD/IPFS deserialization, requests a verifiable CAR stream to be returned
+- [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable :cite[ipns-record] (multicodec `0x0300`).
 
 # HTTP Response