Subdomain Gateway Specification (original) (raw)

IPFS Standards

3 April 2025

History

Commit History

Feedback

GitHub ipfs/specs (inspect source, open issue)

Subdomain Gateways extend [path-gateway] with HTTP Hostheader support. Below should be read as a delta on top of that spec.

This specification enables isolated website hosting based on root CID-derived Origins, ensures compatibility with native ipfs:// and ipns:// URIs, and aligns with the existing Same-origin security model in web browsers, including relative URL pathing and permission scopes of Web APIs.

Summary:

• Requests carry the CID as a sub-domain in the Host header rather than as a URL path prefix
  • Case-insensitive CIDv1 encoding is used in sub-domain (see DNS label limits)
  • e.g. {cidv1}.ipfs.example.net instead of example.net/ipfs/{cid}
• The root CID is used to define the Resource Origin, aligning it with the web's security model.
  • Files in a DAG defined by the root CID may request other files within the same DAG as part of the same Origin Sandbox.
• Data is retrieved from IPFS in a way that is compatible with URL-based addressing
  • URL’s path / points at the content root identified by the CID

Table of Contents

1. 1. HTTP API
   1. 1.1 GET /[{path}][?{params}]
   2. 1.2 HEAD /[{path}][?{params}]
2. 2. HTTP Request
   1. 2.1 Request Headers
      1. 2.1.1 Host (request header)
      2. 2.1.2 X-Forwarded-Proto (request header)
      3. 2.1.3 X-Forwarded-Host (request header)
   2. 2.2 Request Query Parameters
      1. 2.2.1 uri (request query parameter)
3. 3. HTTP Response
   1. 3.1 Response Headers
      1. 3.1.1 Location (response header)
         1. 3.1.1.1 Use in interop with Path Gateway
         2. 3.1.1.2 Use in URI router
4. 4. Appendix: Notes for implementers
   1. 4.1 Migrating from Path to Subdomain Gateway
   2. 4.2 DNS label limits
   3. 4.3 Security considerations
      1. 4.3.1 Wildcard TLS certificates
      2. 4.3.2 Public Suffix List and eTLD enforcement
   4. 4.4 URI router
   5. 4.5 Redirects, single-page applications, and custom 404s
5. A. References
6. B. Acknowledgments

1. HTTP API

The API is a superset of [path-gateway], the differences are documented below.

The main one is that Subdomain Gateway expects CID to be present in the Host header.

1.1 GET /[{path}][?{params}]

Downloads data at specified content path.

• path – optional path to a file or a directory under the content root sent in Host HTTP header

1.2 HEAD /[{path}][?{params}]

Same as GET, but does not return any payload.

2. HTTP Request

Below MUST be implemented in addition to "HTTP Request" of [path-gateway].

2.2 Request Query Parameters

2.2.1 uri (request query parameter)

Optional. When present, passed address should override regular path routing.

See URI router section for usage and implementation details.

3. HTTP Response

Below MUST be implemented in addition to "HTTP Response" of [path-gateway].

4. Appendix: Notes for implementers

4.1 Migrating from Path to Subdomain Gateway

Subdomain Gateway MUST implement a redirect on paths defined in [path-gateway].

HTTP redirect will route path requests to correct subdomains on the same domain name, unless X-Forwarded-Host is present.

NOTE:

During the migration from a path gateway to a subdomain gateway, even though the Location header is present, some clients may check for HTTP 200, and consider other responses as invalid.

It is up to the gateway operator to clearly communicate when such a transition is to happen, or use a different domain name for subdomain gateway to avoid breaking legacy clients that are unable to follow HTTP 301 redirects.

4.2 DNS label limits

DNS labels, must be case-insensitive, and up to a maximum of 63 characters per label (Section 11 of [rfc2181]). Representing CIDs within these limits requires some care.

Base32 multibase encoding is used for CIDs to ensure case-insensitive, URL safe characters are used.

Base36 multibase is used for ED25519 libp2p keys to get the string representation to safely fit with the 63 character limit.

How to represent CIDs with a string representation greater than 63 characters, such as those for sha2-512 hashes, remains anopen question.

Until a solution is found, subdomain gateway implementations should return HTTP 400 Bad Request for CIDs longer than 63.

4.3 Security considerations

4.3.1 Wildcard TLS certificates

Wildcard TLS certificates SHOULD be set for *.ipfs.example.netand *.ipns.example.net if a subdomain gateway is to be exposed on the public internet.

If TLS termination takes place outside of gateway implementation, then settingX-Forwarded-Proto at a reverse HTTP proxy is RECOMMENDED for preserving https protocol.

4.3.2 Public Suffix List and eTLD enforcement

Subdomain gateways assign each content root a unique origin, yet these origins share the gateway’s parent domain. Without proper isolation, all subdomains under the same effective Top-Level Domain (eTLD) face risks: a single problematic CID could trigger widespread blocking of the entire gateway by software like Safe Browsing (incident example).

To mitigate this and align with the web’s Same-origin security model, operators_SHOULD_ register a wildcard entry like *.example.netwith the Public Suffix List (PSL).

This will make ipfs.example.net and ipns.example.net eTLDs, treating each identifier (e.g., cid.ipfs.example.net) as a distinct top-level Origin. The public good gateway, listed as *.dweb.link and *.inbrowser.link on the PSL, exemplifies this approach.

Browsers supporting IPFS natively SHOULD detect URI patterns such ashttps://{content-root-id}.ip[f|n]s.example.net and dynamically update their internal PSL, bolstering security and compatibility without relying solely on operator action.

4.4 URI router

Optional uri query parameter overrides regular path routing.

Subdomain gateway implementations MUST provide URI router for ipfs:// andipns:// protocol schemes, allowing external apps to resolve these native addresses on a gateway.

The /ipfs/?uri=%s endpoint MUST be compatible with [registerProtocolHandler(scheme, url)](registerprotocolhandler%28scheme, url%29), present in web browsers. The value passed in %s should be [UTF-8 percent-encode](utf-8 percent-encode).

Given registration:

navigator.registerProtocolHandler('ipfs', 'https://dweb.link/ipfs/?uri=%s', 'IPFS resolver')
navigator.registerProtocolHandler('ipns', 'https://dweb.link/ipns/?uri=%s', 'IPNS resolver')

Opening ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdishould produce an HTTP GET request forhttps://dweb.link/ipfs/?uri=ipfs%3A%2F%2Fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdiwhich in turn should redirect tohttps://dweb.link/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.

From there, regular subdomain gateway logic applies.

4.5 Redirects, single-page applications, and custom 404s

Subdomain Gateway implementations SHOULD include _redirects file support defined in [web-redirects-file].

A. References

[path-gateway]

Path Gateway Specification. Marcin Rataj; Adrian Lanzafame; Vasco Santos; Oli Evans; Henrique Dias. 2024-04-17. URL: https://specs.ipfs.tech/http-gateways/path-gateway/

[rfc2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

[rfc2181]

Clarifications to the DNS Specification. R. Elz; R. Bush. IETF. July 1997. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2181

[web-redirects-file]

Web _redirects File Specification. Justin Johnson; Marcin Rataj. 2025-03-19. URL: https://specs.ipfs.tech/http-gateways/web-redirects-file/

B. Acknowledgments

We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.

Editors

Marcin Rataj (Shipyard)

Adrian Lanzafame (Protocol Labs)

Vasco Santos (Protocol Labs)

Oli Evans (Protocol Labs)

Thibault Meunier (Cloudflare)

Steve Loeppky (Protocol Labs)

2

1. No definition for term "registerprotocolhandler(scheme, url)".
2. No definition for term "utf-8 percent-encode".