feat(credential_store): default keyring backend to OS-only, add keyring-with-file option

[cross32768]

Description

PR #373 enabled native OS keyring backends (apple-native, windows-native), but the keyring backend still unconditionally writes the encryption key to ~/.config/gws/.encryption_key on every run. This means the AES-256-GCM encryption of credentials.enc is only as strong as file permissions (0600), even on platforms where the OS keychain provides hardware-backed protection (macOS Keychain via Secure Enclave, Windows Credential Manager).

This PR changes the default keyring backend to store the encryption key exclusively in the OS keyring, and introduces a new keyring-with-file value that preserves the previous behavior for users who want a durable file backup.

GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND values

Value	Keyring	.encryption_key file	Use case
keyring (default)	Yes	No	Desktop with native keychain
keyring-with-file	Yes	Yes (synced)	Keychain loss protection
file	No	Yes	Docker / CI / headless

Migration

• Users upgrading with an existing .encryption_key file: on first run, the key is read from the file and copied into the OS keyring. A note is printed suggesting the user remove the file for keyring-only security.
• Users who relied on the implicit file backup can set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=keyring-with-file to restore the previous behavior.
• The file backend is unchanged.

Note on backward compatibility

This changes the default behavior: .encryption_key is no longer written to disk under the keyring backend. If this is a concern given the history of keyring reliability issues (#344, #359, #360, #373), an alternative approach would be to keep the current default as-is and add a separate keyring-only value for opt-in keyring-exclusive storage. Happy to adjust the naming/defaults if that direction is preferred.

Checklist:

• My code follows the AGENTS.md guidelines (no generated google-* crates).
• I have run cargo fmt --all to format the code perfectly.
• I have run cargo clippy -- -D warnings and resolved all warnings.
• I have added tests that prove my fix is effective or that my feature works.
• I have provided a Changeset file (e.g. via pnpx changeset) to document my changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: d69a5e3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refines the encryption key storage strategy by modifying the default behavior of the keyring backend. The primary goal is to bolster security by making the default keyring option exclusively rely on the OS keyring, thereby removing the automatic file backup. To accommodate users who still require a durable file backup, a new keyring-with-file option has been added. This change provides greater flexibility and security choices for managing sensitive encryption keys, adapting to various deployment environments and user preferences.

Highlights

• Default Keyring Backend Change: The default keyring backend now stores encryption keys exclusively in the OS keyring, enhancing security by not writing the key to a local file (.encryption_key).
• New Keyring Option: A new keyring-with-file option has been introduced. This option preserves the previous behavior of using the OS keyring while also maintaining a synced .encryption_key file as a durable backup.
• Migration Path: For users upgrading with an existing .encryption_key file, the key will be read from the file and copied into the OS keyring on the first run. A note will suggest removing the file for keyring-only security.
• Documentation and Usage Updates: Documentation (AGENTS.md, README.md) and usage messages have been updated to reflect the new GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND values and their behaviors.
• Refactored Key Resolution Logic: The core resolve_key function has been refactored to support the new backend behaviors, including distinct logic for keyring-only, keyring-with-file, and file-only storage, along with comprehensive unit tests.

Changelog

• .changeset/keyring-only-default.md
  • Added a new changeset file documenting the updated keyring backend options and default behavior.
• AGENTS.md
  • Updated documentation for the GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND environment variable to include the new keyring-with-file option and clarify the default keyring behavior.
• README.md
  • Updated the interactive authentication section to reflect changes in encryption key storage and mention the new keyring-with-file option.
• src/auth_commands.rs
  • Updated the encryption information message displayed to the user to reflect the new keyring backend options.
• src/credential_store.rs
  • Refactored the KeyringBackend enum to include KeyringWithFile and updated descriptions for all backend types.
  • Modified the from_env implementation to correctly parse the new keyring-with-file option and update warning messages.
  • Added uses_keyring and saves_to_file helper methods to KeyringBackend for clearer logic.
  • Refactored the resolve_key function to implement the new logic for Keyring (keyring-only), KeyringWithFile, and File backends, including migration logic and improved error handling.
  • Updated and added new unit tests to cover the new Keyring (keyring-only) and KeyringWithFile behaviors, including migration, error handling, and race conditions.
• src/main.rs
  • Updated the usage message for the GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND environment variable to include the new keyring-with-file option.

Activity

• The author has ensured the code adheres to AGENTS.md guidelines.
• The code has been formatted using cargo fmt --all.
• All clippy warnings have been resolved.
• New tests have been added to validate the changes and new features.
• A Changeset file has been provided to document the changes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant security improvement by changing the default keyring backend to store the encryption key exclusively in the OS keyring, avoiding writing it to disk. The previous behavior is preserved under a new keyring-with-file backend. The changes are well-structured, with clear separation of concerns and extensive test coverage for the new logic paths.

I've found one potential critical issue related to race condition handling when a key file is created, which could lead to inconsistent state between processes. My feedback includes a suggestion to make the race-handling logic safer and more consistent.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the credential store to change the default behavior of the keyring backend. It will now store the encryption key exclusively in the OS keyring, enhancing security on platforms with hardware-backed keychains. The previous behavior of syncing the key to a file is preserved under a new keyring-with-file backend. The changes are well-implemented and include comprehensive updates to documentation and tests.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the credential storage to make the OS keyring the default, exclusive backend, which is a great security improvement. A new keyring-with-file option is introduced to maintain the old behavior for users who need it. The changes are well-documented and thoroughly tested.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request is a significant improvement to the credential store's security by defaulting the keyring backend to OS-only storage, preventing the encryption key from being written to disk unnecessarily. The introduction of the keyring-with-file option provides a good backward-compatibility path for users who need a file backup. The logic is well-structured and the accompanying tests are thorough. I've identified one critical issue related to non-atomic file writes that could lead to key file corruption, which I've detailed in a review comment.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant and valuable security enhancement by changing the default keyring backend to store the encryption key exclusively in the OS keyring, avoiding writing it to disk. A new keyring-with-file option is added for users who need the previous file-backup behavior. The implementation includes making key file writes atomic, which improves robustness. The changes are well-documented and accompanied by a comprehensive set of new tests. However, I've found a critical race condition in the error recovery logic that could lead to key loss, which needs to be addressed.