Domains as Cargo Namespaces

Summary

Provide a namespacing facility which addresses the following requirements:

1. Allow claiming a namespace exclusively, thereby restricting which crates can be published under this namespace. This allows addressing Rust’s squatting issues.
2. Avoid disputes over namespaces, which can take massive amounts of time and resources to manage.
3. 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.
4. Avoid creating a hard dependency on external services. The recent AWS/GitHub service interruptions are a good example why this is important.
5. 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.

1. The user adds organization = "foobar-project.org" to their Cargo.toml file.
2. The user runs cargo publish.
3. 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

   ZG2ioiTY3tMgwDYfmb6p

   at https://foobar-project.org/.well-known/cargo-publishers

4. The user places the file “cargo-publishers” with the randomly generated string from crates.io at the specified address.
5. 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 text

Io3487xY3tjg54Ef9Opz

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
• 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

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.