Reference rust-lang/cargo#17197 as the BSD-gap PR for the in-tree alternative

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: quinnjr

text/0000-keyring-credential-default.md

@@ -31,7 +31,7 @@ If you're on a headless server or in CI, nothing changes at all. `CARGO_REGISTRY
 # Reference-level explanation
 [reference-level-explanation]: #reference-level-explanation
 
-Rather than maintaining three separate built-in providers, Cargo's default provider would be a single `cargo:keyring` provider built on the `keyring` crate, which already abstracts over the macOS Security Framework, Windows Credential Manager, and Secret Service (with a kernel keyutils fallback on Linux, and Secret Service coverage on FreeBSD and OpenBSD). To be clear about why an external crate is being suggested rather than extending Cargo's in-tree providers: the `keyring` crate supports the BSDs today, and Cargo's existing built-in credential providers do not. Building on it means BSD users are covered from the first release, allowing quicker adoption of the secure default across every tier-supported platform. If the Cargo team would rather keep the provider implementations in-tree, that's a legitimate choice, but it should come with a separate PR adding BSD support to the built-in providers, so that flipping the default doesn't ship with a platform gap the external crate has already closed. The default provider list becomes `["cargo:keyring", "cargo:token"]`: try the keyring, fall back to the file.
+Rather than maintaining three separate built-in providers, Cargo's default provider would be a single `cargo:keyring` provider built on the `keyring` crate, which already abstracts over the macOS Security Framework, Windows Credential Manager, and Secret Service (with a kernel keyutils fallback on Linux, and Secret Service coverage on FreeBSD and OpenBSD). To be clear about why an external crate is being suggested rather than extending Cargo's in-tree providers: the `keyring` crate supports the BSDs today, and Cargo's existing built-in credential providers do not. Building on it means BSD users are covered from the first release, allowing quicker adoption of the secure default across every tier-supported platform. If the Cargo team would rather keep the provider implementations in-tree, that's a legitimate choice, but it should come with a separate PR adding BSD support to the built-in providers, so that flipping the default doesn't ship with a platform gap the external crate has already closed. Such a PR now exists: [rust-lang/cargo#17197](https://github.com/rust-lang/cargo/pull/17197) widens the `cargo:libsecret` gate from Linux-only to all Unix platforms except macOS and mobile targets (the BSD gap was an artifact of the cfg gate — the provider already loads libsecret dynamically at runtime), verified working on FreeBSD 15.1 against gnome-keyring. The default provider list becomes `["cargo:keyring", "cargo:token"]`: try the keyring, fall back to the file.
 
 Migration is gated by a transition period. In the first phase, the only migration path is explicit: `cargo login --migrate-to-keyring` reads the token from `credentials.toml`, writes it to the keyring, verifies the write by reading it back, and only then removes it from the file. During this phase, credential resolution that falls through to the file provider and finds a token prints a notice recommending the flag but leaves the file alone. After a fixed number of stable releases, stated in the stabilization announcement so the deadline is public from day one, the second phase begins: the same write-verify-delete sequence runs automatically in the credential-resolution path whenever a plaintext token is found and the keyring provider reported itself available, and the `--migrate-to-keyring` flag is removed (passing it becomes a no-op warning for one further release, then an error). In both phases, if the keyring write or read-back fails, the file is left untouched and the token is used as before. This ordering means an interrupted migration can duplicate a credential but never lose one. Tokens supplied via `CARGO_REGISTRY_TOKEN` or `--token` bypass migration entirely, since they were never Cargo's to store.
 
@@ -51,7 +51,7 @@ The obvious alternative is the status quo: the secure providers exist, just turn
 
 Migrating only on `cargo login` would be simpler, but it leaves every existing user in plaintext indefinitely, since a working token means there's no reason to ever run `login` again. That's why the manual `--migrate-to-keyring` window is time-boxed rather than permanent: an opt-in migration flag that lives forever is just the current opt-in provider situation with extra steps. The window exists to give cautious users and platform maintainers a controlled on-ramp; the automatic phase that follows is what actually moves the installed base, because the goal is hardening the ecosystem's default posture, not offering secure storage as a menu item.
 
-The Rust Maintainers could also keep the three separate per-platform providers and just change the default list per platform. That works, but it's three implementations to keep behaviorally in sync where one crate already does the job, and, more concretely, none of the existing built-in providers support the BSDs while the `keyring` crate already does. Adopting the crate is the faster route to a secure default on every platform; keeping the providers in-tree is viable only if the Cargo team commits to a separate PR closing the BSD gap first.
+The Rust Maintainers could also keep the three separate per-platform providers and just change the default list per platform. That works, but it's three implementations to keep behaviorally in sync where one crate already does the job, and, more concretely, none of the existing built-in providers support the BSDs while the `keyring` crate already does. Adopting the crate is the faster route to a secure default on every platform; keeping the providers in-tree is viable only if the Cargo team commits to a separate PR closing the BSD gap first. [rust-lang/cargo#17197](https://github.com/rust-lang/cargo/pull/17197) is that PR — if it lands, the in-tree alternative becomes a live option, and the remaining trade-off is three implementations to keep in sync versus one external dependency to vet.
 
 # Prior art
 [prior-art]: #prior-art