From f6fedc59d97b66e31af78770b10a06e3cf6e9af6 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 18 May 2023 15:16:58 +0200 Subject: [PATCH] chore: apply suggestions from code review --- src/ipips/ipip-0337.md | 2 +- src/ipips/ipip-0379.md | 19 +++++++------------ src/routing/http-ipns-routing.md | 6 ++++-- 3 files changed, 12 insertions(+), 15 deletions(-) diff --git a/src/ipips/ipip-0337.md b/src/ipips/ipip-0337.md index d0d853885..d7ba81d25 100644 --- a/src/ipips/ipip-0337.md +++ b/src/ipips/ipip-0337.md @@ -70,7 +70,7 @@ To understand the design rationale, it is important to consider the concrete Ref So this API proposal makes the following changes: - The Delegated Content Routing API is defined using HTTP semantics, and can be implemented without introducing Reframe concepts nor IPLD -- There is a clear distinction between the RPC protocol (HTTP) and the API (Delegated Content Routing) +- There is a clear distinction between the [Kubo RPC](https://docs.ipfs.tech/reference/kubo/rpc/) and the vendor-agnostic Routing V1 HTTP API (introduced in :cite[ipip-0377]). - "Method names" and cache-relevant parameters are pushed into the URL path - Streaming support is removed, and default response size limits are added. - We will add streaming support in a subsequent IPIP, but we are trying to minimize the scope of this IPIP to what is immediately useful diff --git a/src/ipips/ipip-0379.md b/src/ipips/ipip-0379.md index d13423d1b..a139d4078 100644 --- a/src/ipips/ipip-0379.md +++ b/src/ipips/ipip-0379.md @@ -39,7 +39,7 @@ The rationale for delegated IPNS over HTTP APIs closely follows the reasoning li The document proposes the following: - Use of HTTP semantics for publication and resolution of naming records. - Preference for human-readable request and response encoding, such as JSON format -- Optional backward compatibility support for the existing ProtocolBuffer format using `Content-Type: application/vnd.ipfs.ipns-record` +- Mandatory support for the existing [IPNS Record serialization format](https://specs.ipfs.tech/ipns/ipns-record/#record-serialization-format) using `Content-Type: application/vnd.ipfs.ipns-record` - Use of extra headers in `OPTIONS` response to communicate the supported capabilities and limitations, namely: - `X-Ipns-Allow-Max-Size` -- to signal maximum supported IPNS record size - `X-Ipns-Allow-Protobuf` -- to signal whether the server supports ProtocolBuffer formatted records. @@ -55,7 +55,7 @@ The ability of offload naming onto another process or server via an idiomatic an ##### Serialization Format -:cite[ipns-record] use ProtocolBuffer serialisation format. +:cite[ipns-record] use `application/vnd.ipfs.ipns-record` protobuf serialization format. This format is widely in use in IPNS over PubSub and DHT routing systems. One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems. Further, interoperability across the existing and HTTP APIs is also desirable in order to reduce the barrier for adoption of the delegated HTTP APIs. @@ -63,32 +63,27 @@ Further, interoperability across the existing and HTTP APIs is also desirable in The specification here maintains backwards compatibility in terms of record serialisation, with preference for human-readable formats such as JSON. To maximize interoperability with existing ecosystem, the canonical IPNS record serialization format :cite[ipns-record] (`0x0300`) can be requested with content type `application/vnd.ipfs.ipns-record`. -##### Reframe +#### Compatibility -See "Backwards Compatibility" section of :cite[ipip-0337]. - -#### Forwards Compatibility - -See "Forwards Compatibility" section of :cite[ipip-0337]. +See "Compatibility" section of :cite[ipip-0337]. ### Security All interaction over the APIs should use TLS to protect against third-party observation and tampering. -Additionally, the IPNS records are signed by the publisher's identity and contain sequence number to avoid replay attacks. +Additionally, the IPNS records must be [validated according to the rules stated in the IPNS spec](https://specs.ipfs.tech/ipns/ipns-record/#record-verification) before further processing. -To avoid Denial of Service attack, maximum IPNS record size of `10 KiB` applies. +To avoid Denial of Service attack, [maximum IPNS record size defined in IPNS spec](https://specs.ipfs.tech/ipns/ipns-record/#record-size-limit) applies. Implements are permitted to set a lower limit. If lower than the default maximum, the limit should be discoverable via `OPTIONS` request with header key `X-Ipns-Allow-Max-Size` with value specified as the number of bytes. Similarly, a client may check if a server supports ProtocolBuffer formatted records by checking the `X-Ipns-Allow-Protobuf` header key in response to `OPTIONS` request. If present the header value must be either `true` or `false` the absence of the header indicates that ProtocolBuffer formatted records are not supported. Privacy in delegated IPNS is out of scope for this work. -- The usual JSON parsing rules apply. To prevent potential Denial of Service (DoS) attack, clients should ignore responses larger than 100 providers and introduce a byte size limit that is applicable to their use case. ### Alternatives See: - [Libp2p-based IPNS](https://github.com/ipfs/go-ipns). -- Reframe; find out more on "Design Rationale" section of :cite[ipip-0337]. +- Reframe; it was deprecated and now removed. Historical reasons can be found in :cite[ipip-0337]. ### Copyright diff --git a/src/routing/http-ipns-routing.md b/src/routing/http-ipns-routing.md index bafd1c371..5f2d048c9 100644 --- a/src/routing/http-ipns-routing.md +++ b/src/routing/http-ipns-routing.md @@ -72,6 +72,8 @@ Where: cached. - `PublicKey` represents the optional public key used to sign the record. This field is only required if it cannot be extracted from the IPNS name, e.g. in the case of legacy RSA keys. + The idea here is that IPNS Record should always have all information neccessary + for signature verification in offline mode, without additional lookups to retrieve the public key. - `ExtendedData` represents the extensible data as arbitrary JSON object. ## Versioning @@ -81,7 +83,7 @@ increment the version number. ## API -### `GET /naming/v1/records/{ipns-name}` +### `GET /routing/v1/ipns/{ipns-name}` **Path Parameters** @@ -121,7 +123,7 @@ The response body contains the [IPNS record](#ipns-record). } ``` -### `PUT /naming/v1/records/{ipns-name}` +### `PUT /routing/v1/ipns/{ipns-name}` **Path Parameters**