keyring_backend: keyring writes encryption key to disk (~/.config/gws/.encryption_key) on every invocation
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 55/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- rust
- Domain
- authentication, cli, security
Research direction
Start by reproducing the behavior with gws auth status and inspect the CLI startup or auth-resolution path that recreates ~/.config/gws/.encryption_key. Trace how the selected keyring backend is handled. Done means keyring mode no longer writes the encryption key to disk while authentication and CLI commands continue to work.
Written by the indexing model from the issue text.
Description
Summary
gws auth status reports keyring_backend: "keyring", but the CLI re-creates ~/.config/gws/.encryption_key on every invocation regardless of backend setting. The on-disk file contains a 44-byte base64-encoded 32-byte AES key — verified to match the keyring-stored key byte-for-byte. The "keyring backend" reporting is misleading: the key material exists in both locations.
For users in regulated environments who selected the keyring backend specifically to keep encryption keys off disk, this defeats the purpose of the setting.
Environment
- OS: Windows 11 Pro (10.0.22631)
- gws CLI:
@googleworkspace/[email protected](gws 0.16.0) - Node: v24.13.0
- npm: 11.11.1
- Keyring backend: Windows Credential Manager (default for Windows)
- Auth: OAuth Desktop client, External + Testing publishing status
Steps to reproduce
# 1. Confirm keyring backend is active gws auth status | grep keyring_backend # Output: "keyring_backend": "keyring"# 2. Capture current key bytes
ORIG=$(cat ~/.config/gws/.encryption_key)# 3. Delete the on-disk key
rm ~/.config/gws/.encryption_key
# File gone# 4. Run any gws command (status, login, drive, gmail, ANY)
gws auth status > /dev/null
# 5. Verify file is back, identical content
NEW=$(cat/.config/gws/.encryption_key)
[ "$ORIG" = "$NEW" ] && echo "SAME KEY" || echo "DIFFERENT"
# Output: SAME KEY
The file is recreated within the lifetime of the next gws process call — no idle timer, no background daemon. It's a synchronous side-effect of CLI startup or auth-resolution code.
Expected behavior
When keyring_backend: "keyring" is the active backend (and GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND is unset or set to keyring), the encryption key should live only in the OS keyring. No copy on disk.
A user who wants the file backend can opt in via GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file per the README. That opt-in path should be the only path that writes the key to disk.
Actual behavior
The CLI co-writes the encryption key to /.config/gws/.encryption_key (perms 666 on Windows / 0644 on POSIX) on every invocation, regardless of the keyring backend setting. The file is base64-encoded AES-256 key material — 44 bytes for a 32-byte key.
Security implications
- Defeats keyring-backend opt-in. The OS keyring offers per-user encryption-at-rest with OS-level access control (DPAPI on Windows, libsecret on Linux, Keychain on macOS). Co-writing to plain disk negates that protection — any process with file-system read on the user account gets the key.
- Misleading API surface.
gws auth statusreportskeyring_backend: "keyring"even though the key is on disk. Users (and security auditors reading status output) are misled about where the key lives. - Co-locates with encrypted blob. Because
credentials.encand.encryption_keysit in the same directory, an attacker with file read access has both the ciphertext and the key — encryption-at-rest reduces to no encryption.
Workarounds tried
| Approach | Result |
|---|---|
| rm ~/.config/gws/.encryption_key | Re-created on next gws call |
| chmod 000 ~/.config/gws/.encryption_key | (untested — likely breaks the CLI rather than enforcing keyring-only) |
| GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=keyring gws ... | No effect — keyring is already the default; file still written |
| Junction/symlink the file to /dev/null equivalent | (untested — Windows symlinks to NUL don't work cleanly) |
There's no documented opt-out for the on-disk file write.
Suggested fix
Add a true keyring-only mode that does not write .encryption_key to disk. Two reasonable shapes:
Default behavior change (preferred): when
keyring_backend == "keyring", do NOT write.encryption_key. The file is only created whenGOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=fileis set explicitly. This matches the README's documented contract: "Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or~/.config/gws/.encryption_keywhenGOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file)."New env var
GOOGLE_WORKSPACE_CLI_KEY_ON_DISK=falsefor users who want strict keyring-only and are willing to opt in.
Either fix should be paired with a gws auth status field that accurately reports both:
keyring_backend: "keyring" | "file"key_on_disk: true | false(or path)
So security reviewers can audit the actual storage location, not the intended one.
Why this matters
We had a security audit at our org flag the OAuth client gws registers as broad. During remediation, we instructed a user to delete the "stale" .encryption_key file (we initially believed it was residual from a prior file-backend session). The empirical test in step 1 revealed it isn't stale — it's actively maintained, contradicting the CLI's own status reporting. We've documented this as a known constraint in our internal audit, but a fix here would let users in regulated environments accurately attest where their encryption key lives.
Happy to send a PR if there's a maintainer-approved direction.
Repro artifact
The byte-equality check between pre-delete and post-recreation file contents confirms this is the same key, not a newly generated one — i.e., the on-disk file is a deterministic copy of the keyring entry, not an independent secret.
beforeDel.equals(afterRecreate) === true
(Verified on @googleworkspace/[email protected] as of 2026-05-06.)
- Dominant language
- Rust
- Stars
- 32.3k
- Forks
- 2k
- Avg merge
- 16h 3m
- Merged PRs (30d)
- 1
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from googleworkspace/cli
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
googleworkspace/cli#984 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
googleworkspace/cli#983 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
googleworkspace/cli#958 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
googleworkspace/cli#921 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
googleworkspace/cli#920 ·
Maintainers usually reply within 1 day
All issues in googleworkspace/cli
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
status: new topic: ga4gh-sdk type: bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
comp-rbac
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
ClickHouse/ClickHouse#131875 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day
-
bug(python): read_transaction raises TypeError on a Rewrite with rewritten indicesPossibly taken @Borg93 claimed this today. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
lance-format/lance#11117 ·
Maintainers usually reply within 2 days