feat(gateway): IPIP-548 Ipfs-Uri response header - #1209
Merged
Conversation
Codecov Report❌ Patch coverage is
@@ Coverage Diff @@
## main #1209 +/- ##
==========================================
+ Coverage 64.18% 64.33% +0.14%
==========================================
Files 269 269
Lines 27193 27258 +65
==========================================
+ Hits 17455 17536 +81
+ Misses 8024 8010 -14
+ Partials 1714 1712 -2
... and 13 files with indirect coverage changes 🚀 New features to boost your workflow:
|
lidel
force-pushed
the
ipip-548-ipfs-uri
branch
2 times, most recently
from
August 21, 2026 02:56
5e24c4e to
b52d029
Compare
lidel
marked this pull request as ready for review
August 21, 2026 03:35
This was referenced Aug 21, 2026
lidel
force-pushed
the
ipip-548-ipfs-uri
branch
from
August 22, 2026 12:34
b52d029 to
fd861e7
Compare
Implement the Ipfs-Uri response header from ipfs/specs#548: a canonical ipfs:// or ipns:// URI for the requested content path, safe in an HTTP field value for any UnixFS file name. - authority in canonical form: base32 CIDv1, base36 IPNS name keeping its multicodec, lowercase A-label DNSLink; header omitted when the root cannot be normalized - every path segment percent-encoded over the RFC 3986 unreserved set with uppercase hex; "." and ".." emitted as %2E / %2E%2E - sent on deserialized, redirect, and error responses up to 8192 bytes, and exposed via default Access-Control-Expose-Headers - X-Ipfs-Path no longer sent by default; restore via Config.DeprecatedXIpfsPath + Headers.WithDeprecatedXIpfsPath, still omitted for bytes invalid in a field value - CI runs gateway-conformance from ipfs/gateway-conformance#301 until a release with the IPIP-548 tests ships
lidel
force-pushed
the
ipip-548-ipfs-uri
branch
from
August 22, 2026 12:35
fd861e7 to
37cbbdd
Compare
Per IPIP-548 only dotted DNSLink names become an ipns:// authority: example.local works, examplenodot never does. Refs ipfs/helia-verified-fetch#376 (comment)
Use the conformance tests from ipfs/gateway-conformance#301 at its latest commit, which adds the dot-less DNSLink Ipfs-Uri tests.
gammazero
approved these changes
Aug 26, 2026
Contributor
Author
|
The red |
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Aug 27, 2026
* feat: Ipfs-Uri gateway header (IPIP-548) Bump boxo to the IPIP-548 implementation (ipfs/boxo#1209): gateway responses carry a canonical percent-encoded Ipfs-Uri header and stop sending the deprecated X-Ipfs-Path, which cannot represent every UnixFS file name. - sharness: CORS expects Ipfs-Uri exposed, X-Ipfs-Path gone - gateway-conformance CI pinned to the IPIP-548 test suite (ipfs/gateway-conformance#301) until a release ships - reverse-proxy doc and v0.44 changelog updated Refs ipfs/specs#548 * feat: opt-in Gateway.DeprecatedXIpfsPath Expose boxo's opt-in for the legacy X-Ipfs-Path response header as a kubo config flag, default off. Unsafe: the legacy value cannot represent every UnixFS file name, so it must only be used to facilitate migration to Ipfs-Uri, and even when enabled the header is still skipped when the value would include non-ASCII byte sequences. Refs ipfs/specs#548 * ci: bump gateway-conformance pin * ci: gateway-conformance v0.14 * chore: boxo with IPIP-548 from boxo/main * docs: Ipfs-Uri changelog in v0.43.1 * docs: assemble v0.43.1 changelog Move the v0.44 highlights and dependency lines into a new v0.43.1 section, and add the missing entry for owner-only key exports (#11428). v0.44.md returns to an empty skeleton. * docs: note boxo v0.42.2 fixes in v0.43.1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
X-Ipfs-Pathcannot carry every UnixFS file name: bytes outside visible ASCII are invalid in HTTP field values1, so a path like/ipfs/{cid}/łódź.txtreaches clients garbled or silently altered. ipfs/specs#548 deprecates the header in favor ofIpfs-Uri, a percent-encodedipfs:///ipns://URI that survives any file name.Fix
Ipfs-Uriper IPIP-548: Sunset x-ipfs-path header specs#548: canonical authority (base32 CIDv1, base36 IPNS name, A-label DNSLink), strict percent-encoding of every path segment, sent on deserialized, redirect, and error responses, exposed for CORSX-Ipfs-Pathby default;Config.DeprecatedXIpfsPathplusHeaders.WithDeprecatedXIpfsPathrestore it for legacy consumers, still omitted when the path has unsafe bytesTests
All pass, Sharness can be ignored here, it pass in Kubo using conformance and boxo/gateway from this PR:
Footnotes
RFC 9110, section 5.5: field values are limited to HTAB, SP, and visible ASCII. ↩