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

.changeset/keyring-only-default.md

@@ -0,0 +1,13 @@
+---
+"@googleworkspace/cli": minor
+---
+
+feat(credential_store): default `keyring` backend no longer writes encryption key to disk
+
+The `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` env var now supports three values:
+
+- `keyring` (default): OS keyring only — the encryption key is never written to `~/.config/gws/.encryption_key`, giving the strongest security on platforms with a native keychain (macOS Keychain, Windows Credential Manager).
+- `keyring-with-file`: OS keyring with `.encryption_key` file kept in sync as a durable backup (previous default behavior).
+- `file`: file only, for Docker/CI/headless environments (unchanged).
+
+Users who relied on the implicit file backup should set `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=keyring-with-file` to restore the previous behavior.

AGENTS.md

@@ -174,7 +174,7 @@ Use these labels to categorize pull requests and issues:
 |---|---|
 | `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth2 access token (highest priority; bypasses all credential file loading) |
 | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to OAuth credentials JSON (no default; if unset, falls back to encrypted credentials in `~/.config/gws/`) |
-| `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` | Keyring backend: `keyring` (default, uses OS keyring with file fallback) or `file` (file only, for Docker/CI/headless) |
+| `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` | Keyring backend: `keyring` (default, OS keyring only), `keyring-with-file` (OS keyring with `.encryption_key` file backup), or `file` (file only, for Docker/CI/headless) |
 
 | `GOOGLE_APPLICATION_CREDENTIALS` | Standard Google ADC path; used as fallback when no gws-specific credentials are configured |
 

README.md

@@ -122,7 +122,7 @@ The CLI supports multiple auth workflows so it works on your laptop, in CI, and
 
 ### Interactive (local desktop)
 
-Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or `~/.config/gws/.encryption_key` when `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file`).
+Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring. Set `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=keyring-with-file` to also keep a durable `.encryption_key` file backup, or `=file` for file-only storage (Docker/CI/headless).
 
 ```bash
 gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in

src/auth_commands.rs

@@ -359,7 +359,7 @@ async fn handle_login(args: &[String]) -> Result<(), GwsError> {
             "message": "Authentication successful. Encrypted credentials saved.",
             "account": actual_email.as_deref().unwrap_or("(unknown)"),
             "credentials_file": enc_path.display().to_string(),
-            "encryption": "AES-256-GCM (key in OS keyring or local `.encryption_key`; set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file for headless)",
+            "encryption": "AES-256-GCM (key in OS keyring; set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=keyring-with-file for file backup, =file for headless)",
             "scopes": scopes,
         });
         println!(