spec: ipfs:// and ipns:// URI schemes - #544
Open
lidel wants to merge 2 commits into
Open
Conversation
Write down as a spec what the ADDRESSING.md memo in ipfs/in-web-browsers has carried informally, so the rules browsers, gateways, and protocol handlers already follow live somewhere citable. ipfs-uri.md covers what both schemes share: the required authority form and why // is not optional, the case-insensitivity and base32 normalization rules for the content root, the origin model and how it may be serialized, and how the root CID's codec drives path traversal. ipns-uri.md adds only what mutable roots need: the IPNS Name and DNSLink authority forms, the ordered parse that tells them apart, and a key codec rule left open so a new key type can ship without revising the spec. Closes #138 Closes #432 Closes #474 Closes #248
🚀 Build Preview on IPFS ready
|
The "RSA names may not fit" note had it backwards. An IPNS Name is a multihash of the serialized public key, and go-libp2p only inlines the key with the identity hash when its marshalled form is at most 42 bytes. RSA and ECDSA keys exceed that, so they get a sha2-256 digest and produce the shortest names, around 57 characters in base36 against 63 for an inlined Ed25519 key. Reframe the note around inlining rather than length: what a non-inlined key costs is that the resolver cannot recover it from the name, so the record carries a copy that MUST hash back to the authority, and the key is content-addressed under that same multihash. Correct the two claims the same error had seeded: post-quantum names will be digests rather than oversized keys, and Ed25519 is the largest name in practice precisely because it is inlined.
lidel
added a commit
to ipfs/in-web-browsers
that referenced
this pull request
Aug 2, 2026
lidel
marked this pull request as ready for review
August 2, 2026 00:18
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
1 participant
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
What browsers and gateways need to know about
ipfs://andipns://has only ever lived in ADDRESSING.md, a memo inipfs/in-web-browsers. Nothing can cite a memo, and it leaves the sharp edges implicit: why the authority has to survive case-folding, what actually defines an origin, when a CID must be normalized before a request goes out. Implementers keep rediscovering those by shipping something that breaks.Fix
Two draft specs that supersede the memo:
ipfs-uri.md: the required authority form, base32 normalization of the content root, the origin model and the two serializations that work, and how the root CID's codec decides path traversal.ipns-uri.md: the IPNS Name and DNSLink authority forms, the ordered parse that separates them, and a key codec rule left open so post-quantum keys can land without a revision.They also fill in the syntax, encoding, interoperability, and security sections that the IANA provisional registrations for
ipfsandipnsleft open. Gateway behavior is unchanged, and path resolution stays in the Path Gateway spec.Refs
ipfs:andipns:URI schemes #138