initial draft of rfc for crates.io username by carols10cents · Pull Request #1 · carols10cents/oauth-crates-rfcs

carols10cents · 2026-02-12T21:29:11Z

For crates.io team feedback!

Updated rendered as of 2026-04-06

Turbo87

thanks for your work @carols10cents! :)

Co-authored-by: Tobias Bieniek <tobias@bieniek.cloud>

jtgeibel

Just a few general comment from me:

We should allow for an id:1234 form that would be tied to the primary key of the users table. This would provide a stable identifier that always points to the same user even if they rename their account.
We should document what we consider to be a valid username. Based on on the current GitHub rules, I'm thinking:
- Only allow alphanumeric characters [a-zA-Z0-9] and hyphens -.
- Hyphens must not appear at the start or end of the name, and cannot show up as consecutive characters.
- Cap the length to something reasonable (GH is capped at 39 characters).
- Additionally, maybe we should require at least 1 non-numeric character, to avoid potential confusion with id numbers. (Though if GH doesn't already deny this we might have some existing usernames that would break this rule.)
We should document that usernames are case-insensitive, such that username, UserName, etc. are considered equivalent. Like we do with crate names we would probably store the original casing and apply a distinct constraint to a normalized version of the column.

(I've largely inferred the GitHub username rules from what is documented in their enterprise SAML documentation regarding username normalization.)

eth3lbert

I think it would be less confusing/surprising to users if we used a consistent registration process for all users. What I've seen on most other services is a flow that looks more like this:

user clicks on "login with XXX" button

server checks if a corresponding account on XXX is known

if yes: login successful

server shows the user a "register your account" page with a username field that is prefilled with the username from XXX

the username fields checks for collisions with existing usernames on the server and only lets the user register once they've chosen a free username

it would probably also make sense to have the user confirm their email address in the same registration form. I could also imagine that the registration form then triggers a email verification and only after verification activates the account, but I guess that is somewhat orthogonal and not directly related to this RFC :)

Yeah, this is exactly the flow I had in mind too. I’m also not a fan of syncing usernames automatically, much like Tobi mentioned earlier. There might be significantly more work required once we support multiple login methods, such as handling a user who logs in with GitHub first and then tries other methods later. However, I think the first step is helping users understand that their crates.io username might not map 1:1 to their GitHub handle or other future providers. Other than that, Tobi has already covered most of the points I noticed at first glance.

Regarding the warning icon or text, I’m wondering if we should also display it in the owners' section of the crate page sidebar?

LawnGnome

I haven't had a chance to dig into the reference section in depth yet, but here are some high level thoughts, as promised.

I think I'm with @Turbo87 that we're going to need some sort of prefixed alias type thing for this to be viable from a user experience perspective (so github:LawnGnome as a valid identifier). As I mentioned below, I'm not sure if we then also need some sort of fully qualified user name like crates.io:LawnGnome as a requirement, but it's probably ultimately going to be needed at least as an optional thing for ambiguous situations.

Overall, though, I think this aligns well with my own thoughts, and my concerns are mostly around the edges. Feels like we're on the right track. Thanks for writing this up!

Co-authored-by: Adam Harvey <adam@adamharvey.name>

carols10cents · 2026-02-27T22:06:26Z

Only allow alphanumeric characters [a-zA-Z0-9] and hyphens -.

No underscore?

Actually, I think I just figured it out-- we have github usernames with underscores in them in users.gh_login now, but I think GitHub does enterprise integration by adding _[enterprise name] to the end of the github username, so regular non-enterprise github accounts aren't allowed to have underscores.

But I think we need to allow them so that all current usernames are valid, and I think we're going to want to do the same (important but annoying) hyphen/underscore normalization for uniqueness that we use for crate names.

carols10cents · 2026-02-27T22:21:54Z

Additionally, maybe we should require at least 1 non-numeric character, to avoid potential confusion with id numbers. (Though if GH doesn't already deny this we might have some existing usernames that would break this rule.)

Yeah just checked and GitHub allows all-numeric usernames. Ex: https://github.com/1141265442

So I think we'll have to allow that too.

There are usernames that end in hyphen (but none that end in underscore, I don't think it's worth outlawing one without the other though). There are usernames that have two consecutive hyphens (but none with two consecutive underscores, again I don't think worth it to disallow one but not both)

carols10cents · 2026-03-05T19:45:23Z

Regarding the warning icon or text, I’m wondering if we should also display it in the owners' section of the crate page sidebar?

Yup, I have that already around line 55, bolded here:

When you visit a user's page at https://crates.io/users/example_username, see a user account
listed as an owner of a crate in the crate's sidebar, or run cargo owner add example_username
and the account's crates.io username differs from the GitHub username associated with the account,
you will see a warning icon similar to ⚠️

Do you have any suggestions on how to make this clearer?

carols10cents · 2026-03-05T20:12:43Z

We should allow for an id:1234 form that would be tied to the primary key of the users table. This would provide a stable identifier that always points to the same user even if they rename their account.

I've added this as an unresolved question. On one hand, I'm not sure that this is needed; on the other hand, this is something we could add today independently of this RFC, if we wanted.

…lities

… format I'm pretty sure we're going to want this and it fits nicely in the section on valid username requirements now.

I'm pretty sure we'll want this and want it not to be public.

For renamed and deleted accounts. So this is now a "present possibility", not a "future possibility".

Also I totally had the command wrong, `add` is a flag not a subcommand. That's embarassing.

carols10cents · 2026-03-12T17:34:22Z

Ok I think I've resolved all the comments! I tried to make changes in topical commits so that wouldn't be terrible to review just what changed commit-by-commit, but I'm also interested in how the RFC reads overall. Here's an updated rendered link.

Turbo87

only made it to the "Rationale and alternatives" section before I ran out of time, but it's looking great so far. only got a few small comments :)

Turbo87 · 2026-03-16T10:18:00Z

+As other services are added, we will add a prefix that can be used to only look up usernames in
+that service's table. If the username isn't found in the specified table (say, the `cratesio`
+prefix that specfies the `users` table), the request will return an error even if the username is
+in another table (such as the `oauth_github` table, for this example).


do we really want to add support for other services to this API? in my mind these prefixes were only meant for the disambiguation that is currently needed because people assume GitHub/crates.io username match up, but I'm not sure we need to support e.g. gitlab:foo

To me, it's a safety+convenience thing. If someone knows the gitlab username of the person they'd like to add, and they want to be really confident they're adding the right person without having to first go verify that their crates.io username does or does not match, this gives them a convenient way to be confident.

jtgeibel · 2026-03-29T22:38:53Z

No underscore?

Thanks for double checking against the database (on this and that all-numeric usernames already exist too). My understanding was that GH didn't allow underscores because usernames must be valid DNS hostnames. Presumably, enterprise accounts don't get a subdomain under github.io.

Regarding an id:1234 form:

I've added this as an unresolved question. On one hand, I'm not sure that this is needed; on the other hand, this is something we could add today independently of this RFC, if we wanted.

Thanks for adding that. I agree this could be done independently. I was thinking it would be useful as a stable identifier for cargo owner commands, but at the same time adding/removing an owner is a one-off command and probably isn't hard-coded into scripts very often.

Rather than only proposing that as an alternative

carols10cents · 2026-04-05T22:35:32Z

Ok, I'm feeling like this is in good enough shape to open as a real RFC maybe immediately after our meeting this week - please register any objections before then!

Updated rendered link

Yes i know JSON doesn't have comments for real, too bad

joshtriplett · 2026-04-06T02:23:01Z

Only allow alphanumeric characters [a-zA-Z0-9] and hyphens -.

No underscore?

Actually, I think I just figured it out-- we have github usernames with underscores in them in users.gh_login now, but I think GitHub does enterprise integration by adding _[enterprise name] to the end of the github username, so regular non-enterprise github accounts aren't allowed to have underscores.

But I think we need to allow them so that all current usernames are valid, and I think we're going to want to do the same (important but annoying) hyphen/underscore normalization for uniqueness that we use for crate names.

Ah, just found this comment after I reviewed the RFC.

Would be helpful to have this rationale included. But I'm also wondering if we could handle this another way, and avoid needing the underscore/hyphen normalization code.

carols10cents · 2026-04-06T11:45:58Z

Would be helpful to have this rationale included. But I'm also wondering if we could handle this another way, and avoid needing the underscore/hyphen normalization code.

I can add that... Do you have any ideas on how to handle this another way? I can't think of anything that wouldn't cause disruption for existing usernames :(

carols10cents · 2026-04-07T12:27:52Z

This is now a real RFC! If you've gotten here somehow, please go comment on rust-lang/rfcs#3946 instead :) Archiving this repo!

initial draft of rfc

82014c8

Turbo87 reviewed Feb 16, 2026

View reviewed changes

Fix link

2889dd8

Co-authored-by: Tobias Bieniek <tobias@bieniek.cloud>

jtgeibel reviewed Feb 23, 2026

View reviewed changes

eth3lbert reviewed Feb 23, 2026

View reviewed changes

LawnGnome reviewed Feb 24, 2026

View reviewed changes

carols10cents and others added 2 commits February 27, 2026 16:06

Fix spelling

8a951bd

Co-authored-by: Adam Harvey <adam@adamharvey.name>

Make username choice always an explicit part of signing up

d611dcd

carols10cents commented Feb 27, 2026

View reviewed changes

Comment thread username-identity.md

Change to explicitly NOT automatically pick up GitHub account renames

069fbbf

carols10cents added 2 commits February 27, 2026 17:23

Add a section on crates.io username requirements

948a23d

carols10cents added 2 commits March 5, 2026 14:57

Add a note about someday removing the username mismatch warning

ec3cc8d

Add unresolved Q about whether we need a way to refer to user by ID

e96b838

carols10cents added 9 commits March 5, 2026 15:18

Expand discussion of avatars to include Gravatar, placeholder possibi…

3f99b2b

…lities

Add a TL;DR of the big changes at the top

13d65e3

Address concerns about impersonation more directly

faa32aa

Move unresolved q on blocked usernames to section on allowed username…

81eb904

… format I'm pretty sure we're going to want this and it fits nicely in the section on valid username requirements now.

Move section on historical tracking to the impersonation section

1a262c3

I'm pretty sure we'll want this and want it not to be public.

I've convinced myself we should be proactively checking github

4c730f3

For renamed and deleted accounts. So this is now a "present possibility", not a "future possibility".

Clarify the paragraph about signup, that it's for new users only

6b90b8b

Clarify UX of cargo owner

7d983e8

Also I totally had the command wrong, `add` is a flag not a subcommand. That's embarassing.

Rework reference section to be about API changes

f070e0c

carols10cents force-pushed the username-identity branch from 427d121 to f070e0c Compare March 12, 2026 17:30

carols10cents requested review from Turbo87 and jtgeibel March 12, 2026 17:32

carols10cents requested review from LawnGnome and eth3lbert March 12, 2026 17:32

Turbo87 reviewed Mar 16, 2026

View reviewed changes

carols10cents added 4 commits April 5, 2026 18:02

Add qualification that we'll change usernames if they violate policy

48b829c

Move user API disambiguation support to unresolved questions

f7296fc

Change from github_username to github_username_matches

8d7dab6

Rather than only proposing that as an alternative

Acknowledge that cratesio prefix might be a variation

6eeeb50

carols10cents force-pushed the username-identity branch from 179fd16 to 6eeeb50 Compare April 5, 2026 22:32

carols10cents added 2 commits April 5, 2026 18:47

Ensure all code blocks have syntax highlighting

221b95c

Yes i know JSON doesn't have comments for real, too bad

Remove extra paren that messed up markdown rendering

6385e68

joshtriplett reviewed Apr 6, 2026

View reviewed changes

Comment thread username-identity.md Outdated

Add a footnote explaining why we must support underscores

edab78b

carols10cents force-pushed the username-identity branch from 28f36c5 to edab78b Compare April 6, 2026 13:58

carols10cents added 2 commits April 6, 2026 10:00

Add an unresolved question about how to handle hyphen/underscore

ef4eb5a

Add unresolved question about consecutive/ending in hyphens

90a711a

carols10cents closed this Apr 7, 2026

Conversation

carols10cents commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Turbo87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jtgeibel left a comment

Choose a reason for hiding this comment

Uh oh!

eth3lbert left a comment

Choose a reason for hiding this comment

Uh oh!

LawnGnome left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carols10cents commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carols10cents commented Feb 27, 2026

Uh oh!

carols10cents commented Mar 5, 2026

Uh oh!

carols10cents commented Mar 5, 2026

Uh oh!

carols10cents commented Mar 12, 2026

Uh oh!

Turbo87 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Turbo87 Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

carols10cents Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

jtgeibel commented Mar 29, 2026

Uh oh!

carols10cents commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

joshtriplett commented Apr 6, 2026

Uh oh!

carols10cents commented Apr 6, 2026

Uh oh!

carols10cents commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

carols10cents commented Feb 12, 2026 •

edited

Loading

carols10cents commented Feb 27, 2026 •

edited

Loading

Turbo87 left a comment •

edited

Loading

carols10cents commented Apr 5, 2026 •

edited

Loading