Subdomain Gateway Specification

status: reliable
Editors
Marcin Rataj (Protocol Labs) GitHub
Adrian Lanzafame (Protocol Labs) GitHub
Vasco Santos (Protocol Labs) GitHub
Oli Evans (Protocol Labs) GitHub
Thibault Meunier (Cloudflare) GitHub
Steve Loeppky (Protocol Labs) GitHub
History
Commit History
Feedback
GitHub ipfs/specs (pull requests, new issue, open issues)

Subdomain Gateways extend [path-gateway] with HTTP Host header 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:

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.

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.1 Request Headers

2.1.1 Host (request header)

Defines the root that should be prepended to the path before IPFS content path resolution is performed.

The value in Host header must be a valid FQDN with at least three DNS labels: a case-insensitive content root identifier followed by ipfs or ipns namespace, and finally the domain name used by the gateway.

Converting Host into a content path depends on the nature of requested resource:

  • For content at /ipfs/{cid}:
    • Host: {cid-mbase32}.ipfs.example.net
      • Example: Host: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.dweb.link
  • For content at /ipns/{libp2p-key}:
    • Host: {libp2p-key-mbase36}.ipns.example.net
      • Example: Host: k2k4r8jl0yz8qjgqbmc2cdu5hkqek5rj6flgnlkyywynci20j0iuyfuj.ipns.dweb.link
      • Note: Base36 must be used to ensure CIDv1 with ED25519 fits in a single DNS label (63 characters).
  • For content at /ipns/{dnslink-name}:
    • Host: {inlined-dnslink-name}.ipns.example.net
      • DNSLink names include . which means they MUST be inlined into a single DNS label to provide unique origin and work with wildcard TLS certificates.
        • DNSLink label encoding:
          • Every - is replaced with --
          • Every . is replaced with -
        • DNSLink label decoding
          • Every standalone - is replaced with .
          • Every remaining -- is replaced with -
        • Example:
          • example.net/ipns/en.wikipedia-on-ipfs.orgHost: en-wikipedia--on--ipfs-org.ipns.example.net
  • If Host header does not include any subdomain, but the requested path is a valid content path, gateway MUST attempt to migrate from Path to Subdomain Gateway.
  • Finally, if it is impossible to construct a content path from Host, return HTTP Error 400 Bad Request, as seen in [path-gateway].

2.1.2 X-Forwarded-Proto (request header)

Optional. Allows http:// gateway implementation to be deployed behind reverse proxies that provide TLS (https://) termination.

Setting X-Forwarded-Proto: https on reverse proxy informs gateway implementation that it MUST:

  1. set all absolute redirect URLs to https:// (not http://)
  2. inline DNSLink names to fit in a single DNS label, making it compatible with a single wildcard TLS certificate:

Example (GET with X-Forwarded-Proto: https):

  • GET http://dweb.link/ipfs/{cid} → HTTP 301 with Location: https://{cid}.ipfs.dweb.link
  • GET http://dweb.link/ipns/your-dnslink.site.example.com → HTTP 301 with Location: https://your--dnslink-site-example-com.ipfs.dweb.link

2.1.3 X-Forwarded-Host (request header)

Optional. Enables Path Gateway requests to be redirected to a Subdomain Gateway on a different domain name.

See also: migrating from Path to Subdomain Gateway.

Example (GET with X-Forwarded-Host: example.com):

  • GET https://dweb.link/ipfs/{cid} → HTTP 301 with Location: https://{cid}.ipfs.example.com

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].

3.1 Response Headers

3.1.1 Location (response header)

Below MUST be implemented in addition to Location requirements defined in [path-gateway].

3.1.1.1 Use in interop with Path Gateway

The Location HTTP header is returned with 301 Moved Permanently ([path-gateway]) when Host header does not follow the subdomain naming convention, but the requested URL path happens to be a valid /ipfs/{cid}[/{path}][?{query}] or /ipfs/.. content path.

This redirect allows a subdomain gateway to be used as a drop-in replacement compatible with regular path gateways, as long as the rules below are followed:

  • Redirect from a path gateway URL to the corresponding subdomain URL MUST preserve the originally requested {path} and {query} parameters, if present.
    • Content path validation before the redirect SHOULD be limited to the correctness of the root CID. If the content path includes any subpath or query parameters, they SHOULD be preserved and processed after the redirect to a subdomain is completed.
      • Namely, additional logic, such as IPLD path traversal or processing the _redirects file, SHOULD only be executed by the subdomain gateway after the redirect.
  • Before redirecting, the content root identifier MUST be converted to case-insensitive/inlined form if necessary. For example:
    • https://dweb.link/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR returns HTTP 301 redirect to the same CID but in case-insensitive base32:
      • Location: https://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.dweb.link/
    • https://dweb.link/ipns/en.wikipedia-on-ipfs.org returns HTTP 301 redirect to subdomain with DNSLink name correctly inlined:
      • Location: https://en-wikipedia--on--ipfs-org.ipns.dweb.link/

See also: Migrate from Path to Subdomain Gateway.

3.1.1.2 Use in URI router

See: URI router

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 an open 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.4 URI router

Optional uri query parameter overrides regular path routing.

Subdomain gateway implementations MUST provide URI router for ipfs:// and ipns:// 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), present in web browsers. The value passed in %s should be UTF-8 percent-encode.

Example

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://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi should produce an HTTP GET request for https://dweb.link/ipfs/?uri=ipfs%3A%2F%2Fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi which in turn should redirect to https://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. 2023-03-30. 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. 2023-01-28. URL: https://specs.ipfs.tech/http-gateways/web-redirects-file/