diff --git a/IPIP/0351-gateway-ipns-record-response-format.md b/IPIP/0351-gateway-ipns-record-response-format.md new file mode 100644 index 000000000..f3aa19df0 --- /dev/null +++ b/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 +k51Key + +$ ipfs name publish /ipfs/bafyHash --key= --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 diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md index 6fbbea06b..2a6bd7cee 100644 --- a/src/http-gateways/path-gateway.md +++ b/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,7 +197,8 @@ parameter, if present) Optional, `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` @@ -204,6 +206,7 @@ This is a URL-friendly alternative to sending an [`Accept`](#accept-request-head - `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`