Domains as Cargo Namespaces
Please refrain from linking this page on community foris of any language mentioned herein.
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
- 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.
- 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
- The user adds
organization = "foobar-project.org"to their
- The user runs
- 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 contents
- 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.
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 text
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-xyz by adding those users’ verifications to their “domain-owner” file.
This requires some changes to cargo and crates.io:
- cargo needs to support
organizationkeys to Cargo.toml files and treat them correctly
- adding dependencies on namespaced crates to Cargo.toml files
- crates.io needs to be extended
- to understand
organizationkeys 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.
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
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.
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.
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.