diff --git a/src/http-gateways/gateway-detection.md b/src/http-gateways/gateway-detection.md new file mode 100644 index 00000000..d58d22fa --- /dev/null +++ b/src/http-gateways/gateway-detection.md @@ -0,0 +1,107 @@ +--- +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: 2025-12-16 +maturity: reliable +editors: + - name: Mark Gaiser + github: markg85 + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: Shipyard + url: https://ipshipyard.com +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-preferred 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 SHOULD 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. Try OS-specific paths: + - Linux/Unix: + 1. `$XDG_CONFIG_HOME/ipfs/gateway` (only if `XDG_CONFIG_HOME` is set) + 2. `$HOME/.config/ipfs/gateway` (default XDG location) + 3. `/etc/ipfs/gateway` (system-wide) + - Windows: + 1. `%LOCALAPPDATA%/ipfs/gateway` (local user) + 2. `%APPDATA%/ipfs/gateway` (roaming user) + 3. `%PROGRAMDATA%/ipfs/gateway` (system-wide) + - macOS: + 1. `$HOME/Library/Application Support/ipfs/gateway` (user) + 2. `/Library/Application Support/ipfs/gateway` (system-wide) + +When `gateway` file is present, the file contents MUST be interpreted as an +ASCII text file with one URL per line (separated by `\n` or `\r\n`). + +The first line MUST be a valid `http://` or `https://` URL without a path +(e.g., `http://127.0.0.1:8080`). The gateway at this URL MUST support +:cite[trustless-gateway], SHOULD support :cite[path-gateway] when deserialized +responses are required, and SHOULD support :cite[subdomain-gateway] when Origin +isolation is required. + +Implementations MAY support additional lines for gateway pools or failover. +Implementations that do not support multiple URLs SHOULD read only the first +line 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 27b633a1..650248bf 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/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md index aa678157..9c7ee1b6 100644 --- a/src/http-gateways/libp2p-gateway.md +++ b/src/http-gateways/libp2p-gateway.md @@ -19,7 +19,7 @@ xref: - http-routing-v1 - path-gateway - trustless-gateway -tags: ['httpGateways', 'lowLevelHttpGateways', 'exchange', 'transport'] +tags: ['httpGateways', 'integratingHttpGateways', 'exchange', 'transport'] order: 3 --- diff --git a/src/index.html b/src/index.html index d5b3e1b3..127b2c70 100644 --- a/src/index.html +++ b/src/index.html @@ -107,6 +107,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 %}

Data Formats

diff --git a/src/ipips/ipip-0280.md b/src/ipips/ipip-0280.md new file mode 100644 index 00000000..b9b81008 --- /dev/null +++ b/src/ipips/ipip-0280.md @@ -0,0 +1,123 @@ +--- +title: "IPIP-0280: Conventions for HTTP Gateway Detection" +date: 2025-12-16 +ipip: ratified +editors: + - name: Mark Gaiser + github: markg85 + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: Shipyard + url: https://ipshipyard.com +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 creates conventions for how applications can identify available IPFS gateway, +and how IPFS gateway implementations can signal own endpoint. + +This convention has been implemented and in use since 2022 (Kubo 0.15, ffmpeg, curl 8.4). + +## 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-preferred 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 preferred 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)) +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 + +#### Browser Environment Detection + +Detection via browser APIs (e.g., `localStorage.getItem('IPFS_GATEWAY')`) was +considered but is explicitly out of scope. Any JavaScript running on a page +could overwrite such values and hijack gateway requests. Browser-based detection +requires a separate IPIP with proper security review. + +#### Gateway Health Checking + +This specification does not mandate health checking of detected gateways. +Implementations MAY verify that a gateway is responsive before using it, +but the specific approach is left to implementers. + +#### Stale Gateway File Handling + +If a daemon crashes without removing the `gateway` file, it may contain a stale +URL. This specification does not mandate specific handling. Implementations MAY +implement timeout-based health checks or other recovery mechanisms. + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).