Domains as Cargo Namespaces
Please refrain from linking this page on community foris of any language mentioned herein.
Summary
Provide a namespacing facility which addresses the following requirements:
- Allow claiming a namespace exclusively, thereby restricting which crates can be published under this namespace. This allows addressing Rust’s squatting issues.
- Avoid disputes over namespaces, which can take massive amounts of time and resources to manage.
- Guarantee that namespaces are unique, solving the issue of “clashing” namespaces. Non-unique namespaces work poorly and cause disputes, as demonstrated by npm’s
kik
conflict. - Avoid creating a hard dependency on external services. The recent AWS/GitHub service interruptions are a good example why this is important.
- Make receiving a namespace as seamless as possible for users. Namespaces should be an additional benefit crate authors receive, not some annoying bureaucratic hurdle they have to jump over.
Design
- Use (sub)domains as namespaces. Maven has shown that this approach has been working exceedingly well for more than a decade.
- Control of a (sub)domain is established using domain validation (DV) and RFC5785. Let’s Encrypt is successfully using this approach to generate millions of certificates each year.
- Crates.io maintainer will never need to get involved in namespace disputes, as ICANN’s Uniform Domain-Name Dispute-Resolution Policy deals with this.
Basic User Experience
Basic task: A user wants to publish their foobar
crate under their domain foobar-project.org
.
- The user adds
organization = "foobar-project.org"
to theirCargo.toml
file. - The user runs
cargo publish
. - The command prints the following text to the console:
Crates.io couldn’t verify that you own
foobar-project.org
. To prove ownership, place a file with the following contentsZG2ioiTY3tMgwDYfmb6p
at https://foobar-project.org/.well-known/cargo-publishers
- The user places the file “cargo-publishers” with the randomly generated string from crates.io at the specified address.
- The user reruns
cargo publish
. crates.io checks that the string matches and publishes the crate under the namespace.
Details
Upon the first request to publish a crate with a namespace, crates.io generates a random string that is user-, crate- and domain-specific.
On each following request crates.io checks whether a file named “domain-owner” at the given domain exists and verifies that the contents are identical to what crates.io has on file for the specific user/crate/domain combination.
The ability to publish a crate is not limited to one person: If a different person wants to publish a crate to a domain, crates.io returns a similar reply:
Crates.io couldn’t verify that you own
foobar-project.org
. To prove ownership, add the following textIo3487xY3tjg54Ef9Opz
to the file at https://foobar-project.org/.well-known/cargo-publishers.
This person would then contact the owner of the domain, who could decide whether to accept or reject this request (by adding or not adding the line to his “domain-owner” file).
This also serves as a very easy way to allow external contributors to publish add-on crates to a crate in an organization, without allowing them to publish to the main crate. E.g. authors of serde could publish their own crate under serde.rs/serde
and allow vetted, “official” add-on crates to be published by external contributors under e. g. serde.rs/serde-abc
or serde.rs/serde-xyz
by adding those users’ verifications to their “domain-owner” file.
Changes
This requires some changes to cargo and crates.io:
- cargo needs to support
- adding
organization
keys to Cargo.toml files and treat them correctly - adding dependencies on namespaced crates to Cargo.toml files
- adding
- crates.io needs to be extended
- to understand
organization
keys and namespacing - to validate control of (sub)domains as specified above
- to correctly display such crates on the web
- to understand
No changes to the language are required. Source code of crates does not need to be changed to enable namespaces.
Further Suggestions
It is recommended that /
is used as a separator between the namespace and the crate name.
This would mean that a fully-qualified crate would look like a URL, making it easy to find further documentation or the project’s homepage:
Consider a crate called foobar
with the namespace foobar-project.org
. The fully-qualified name would be foobar-project.org/foobar
.
This looks like a real URL and the namespace owner could place documentation there, forward to the crates GitHub page, or redirect to doc.rs.
Future Tasks
This proposal does not discuss what should happen with the global namespace. This is intentional – there are plenty of policy decisions that can be made with various advantages and disadvantages.
FAQ
This FAQ is not meant as a complete enumeration of all possible scenarios, but is intended to show how this proposal functions, and which potential policy decisions can be made:
Do I need my own domain?
No. A subdomain is sufficient. Every Rust crate author owns at least one already through their GitHub account.
I no longer care about maintaining the domain, what should I do?
Ask your maintainers or contributors to take over the domain. (This is not much different from a situation where the original author loses interest in maintaining his/her crate.)
My domain was hacked!
Use your domain registry’s support channels to resolve this issue. In the meantime, it might make sense to let crates.io maintainers know, so that the publication of new crates or versions can be disabled until the issue is resolved. (This is not much different from your crates.io account being compromised.)
Someone else owns my domain now!
Pick a new domain. If there is an acute danger of misuse, let crates.io maintainers know, so that publications of newer versions of existing crates under that namespace can be blocked.