ipip-462: document value format and security

Author: lidel

src/http-gateways/trustless-gateway.md

@@ -4,15 +4,21 @@ description: >
   The minimal subset of HTTP Gateway response types facilitates data retrieval
   via CID and ensures integrity verification, all while eliminating the need to
   trust the gateway itself.
-date: 2023-06-20
+date: 2024-03-22
 maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
+    affiliation:
+      name: IP Shipyard
+      url: https://ipshipyard.com
   - name: Henrique Dias
     github: hacdias
     url: https://hacdias.com/
+    affiliation:
+      name: IP Shipyard
+      url: https://ipshipyard.com
 xref:
   - url
   - path-gateway
@@ -97,6 +103,21 @@ A Client SHOULD use it to send a relevant parent content path when:
 - fetching a big file block by block (`application/vnd.ipld.raw`)
 - parallelizing DAG download by fetching each branch sub-DAG as a CAR (`application/vnd.ipld.car`)
 
+The value of `Ipfs-Path-Affinity` header SHOULD be percent-encoded
+([ECMA262: `encodeURIComponent`](https://tc39.es/ecma262/multipage/global-object.html#sec-encodeuricomponent-uricomponent))
+unless it meets the following conditions:
+- contains no path beyond the root identifier (`/ipfs/cid`)
+- contains no whitespace characters
+- contains no `:` characters
+- contains no non-ASCII characters
+
+A gateway backend SHOULD leverage this hint to improve retrieval by querying
+providers of additional content paths in addition to the requested one.
+
+Gateway implementation SHOULD support client requests with `Ipfs-Path-Affinity`
+header being present more than once, but also SHOULD set a hard limit of hints
+to process (e.g. 3) to avoid abuse.
+
 ## Request Query Parameters
 
 ### :dfn[dag-scope] (request query parameter)

src/ipips/ipip-0462.md

@@ -67,6 +67,9 @@ The client is in control when the affinity information is sent in the header,
 and an implementation SHOULD allow an end user to disable it in context where parent
 content path information is considered sensitive information.
 
+Gateway implementation that supports `Ipfs-Path-Affinity` header being present
+more than once MUST also set limit (e.g. max 3) to avoid abuse.
+
 ### Alternatives
 
 N/A