diff --git a/src/http-gateways/gateway-detection.md b/src/http-gateways/gateway-detection.md new file mode 100644 index 000000000..36ace1baf --- /dev/null +++ b/src/http-gateways/gateway-detection.md @@ -0,0 +1,102 @@ +--- +title: Detecting User-Preferred IPFS Gateway +description: > + Specification of the rules and standards for detecting and identifying + user-preferred IPFS gateways within applications, enabling seamless + integration and user control. +date: 2023-10-03 +maturity: reliable +editors: + - name: Mark Gaiser + github: markg85 + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ +tags: ['httpGateways', 'integratingHttpGateways'] +order: 99 +--- + + +## Introduction + +This document defines conventions for how applications can identify available +IPFS gateway, and how IPFS gateway implementations can signal own endpoint to +client applications. + +## Specification + +There are two ways of hinting user-prefered gateway URL: + +- Setting the `IPFS_GATEWAY` environment variable +- Creating a `gateway` file at a well-known path + +Applications SHOULD evaluate these hints in order and stop on the first match: + +1. Check if a valid `IPFS_GATEWAY` environment variable is set +2. Check if a valid `gateway` file is present at one of well-known filesystem paths + + +### `IPFS_GATEWAY` Environment Variable + +When `IPFS_GATEWAY` environment variable is set, the value MUST be interpreted +as URL of IPFS Gateway application to use. + +This variable SHOULD override gateway selection done by all other means, including +internal application configuration. + +### The `gateway` Configuration File + +Client application SHOULD check if file is present at specific filesystem paths, in order: + +1. If `IPFS_PATH` is set, try `$IPFS_PATH/gateway` +2. If `HOME` is set, try `$HOME/.ipfs/gateway` +3. If `$XDG_CONFIG_HOME` is set, try `$XDG_CONFIG_HOME/ipfs/gateway` +4. If `/etc` exists, try `/etc/ipfs/gateway` +5. Try OS-specific paths + - Windows + 1. `%LOCALAPPDATA%/ipfs/gateway` (local user) + 2. `%APPDATA%/ipfs/gateway` (roaming user) + 3. `%PROGRAMDATA%/ipfs/gateway` (global) + - macOS + 1. `$HOME/Library/Application Support/ipfs/gateway` (user) + 2. `/Library/Application Support/ipfs/gateway` (global) + - Linux + 1. `$HOME/.config/ipfs/gateway` (user) + 2. `/etc/ipfs/gateway` (global) + +When `gateway` file is present, the file contents MUST be interpreted as line +separated (`\n` or `\r\n`) `text/plain` file. + +The first line of `gateway` file MUST be a valid `http://` or `https://` URL. + +Implementations that only need one URL SHOULD use the first one and ignore the rest of the file. + +### Security + +Applications that integrate IPFS support via HTTP gateway: + +MUST NOT hard-code non-localhost URL as a default fallback. Instead, SHOULD ask +user to define preferred IPFS gateway using one of methods defined in this +document. + +SHOULD either warn user when non-localhost gateway is used for deserialized +responses (warning about the risk of MITM), or (preferred) limit HTTP use +outside of localhost to verifiable response types defined in +:cite[trustless-gateway]. + +### Privacy and User Control + +Applications SHOULD never default to public gateways. Instead, suggest to the +user how to run a local node. + +### Compatibility and Testing + +Implementers should test against implementations mentioned in :cite[ipip-0280] +as the baseline for making decisions around maximizing interoperability. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/src/http-gateways/index.html b/src/http-gateways/index.html index 27b633a18..650248bf8 100644 --- a/src/http-gateways/index.html +++ b/src/http-gateways/index.html @@ -19,6 +19,8 @@

Web

origin-based security model.

{% include 'list.html', posts: collections.webHttpGateways %} +

Integration

+ {% include 'list.html', posts: collections.integratingHttpGateways %} {% include 'footer.html' %} diff --git a/src/index.html b/src/index.html index db6e7849e..01439e502 100644 --- a/src/index.html +++ b/src/index.html @@ -93,6 +93,10 @@

HTTP Gateways

Web semantics (for website hosting and web browsers):

{% include 'list.html', posts: collections.webHttpGateways %} +

+ Other integrations: +

+ {% include 'list.html', posts: collections.integratingHttpGateways %}

InterPlanetary Naming System

diff --git a/src/ipips/ipip-0280.md b/src/ipips/ipip-0280.md new file mode 100644 index 000000000..ea493ece9 --- /dev/null +++ b/src/ipips/ipip-0280.md @@ -0,0 +1,104 @@ +--- +title: "IPIP-0280: Conventions for HTTP Gateway Detection" +date: 2023-10-03 +ipip: proposal +editors: + - name: Mark Gaiser + github: markg85 + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ +relatedIssues: + - https://github.com/ipfs/kubo/issues/8847 + - https://git.ffmpeg.org/gitweb/ffmpeg.git/commit/f889837e00d3b2388a24c0a9d075ad62f47da825 + - https://github.com/curl/curl/pull/8805 +order: 280 +tags: ['ipips'] +--- + +## Summary + +This IPIP aims to create conventions for how applications can identify available IPFS gateway, +and how IPFS gateway implementations can signal own endpoint. + +## Motivation + +Applications wanting to leverage IPFS Gateways are, without a common +convention, left to invent their own ways of finding a gateway, including naive +approaches such as localhost port scanning. + +This IPIP introduces specification that defines how an application wanting to +implement IPFS support can find a local or user-preferred gateways. + +## Detailed design + +We introduce two ways of hinting user-prefered gateway URL to cover +the majority of runtimes and use cases: + +- `IPFS_GATEWAY` environment variable +- `gateway` file and filesystem paths to look for it + +See: :cite[gateway-detection] for details. + +## Design rationale + +### User benefit + +End users can define their prefered gateway once, and benefit from +opportunistic support in applications they use. + +Application developers save time as they only need to implement support for +vendor-agnostic convention to be able to read user preferred gateway. + +### Compatibility + +#### Kubo + +Kubo ([>0.15.0](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.15.md#-ipfs_pathgateway-file)) +creates a hint file in `$IPFS_PATH/gateway` (default being `$HOME/.ipfs/gateway`, see [kubo#8847](https://github.com/ipfs/kubo/issues/8847)). + +The file contains a single line being the local HTTP gateway URL. For example: `http://localhost:8080`. + +Every time `ipfs daemon` starts, it updates the the content of `$IPFS_PATH/gateway` or creates the file if it doesn't exist. + +#### IPFS Chromium + +ipfs-chromium uses `IPFS_GATEWAY` environment variable +([ipfs-chrompium#29](https://github.com/little-bear-labs/ipfs-chromium/issues/29)). + +It can be a single URL, or a whitespace-separated URLs to be used as the initial gateway pool. + +Ref. + +#### FFMPEG + +FFMPEG's libavformat supports both `$HOME/.ipfs/gateway` file and `IPFS_GATEWAY` environment variable +([ffmpeg.git/commit/f889837](https://git.ffmpeg.org/gitweb/ffmpeg.git/commit/f889837e00d3b2388a24c0a9d075ad62f47da825)). + + +Ref. + +#### Curl + +Curl (>8.4.0, [curl#8805](https://github.com/curl/curl/pull/8805)) supports +will try the `IPFS_GATEWAY` environment variable first, and then look for +`$IPFS_PATH/gateway` or `$HOME/.ipfs/gateway`, if present. + +It expects a single URL. + +Ref. + +### Security + +See "Security" section of :cite[gateway-detection]. + +### Alternatives + +N/A. This IPIP covers both environment variable and configuration file. + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).