feat: Implement OS keyring-backed encrypted token storage for OAuth2 credentials.

Author: jpoehnelt

AGENTS.md

@@ -61,5 +61,5 @@ ASCII art title cards live in `art/`. The `scripts/show-art.sh` helper clears th
 ## Environment Variables
 
 - `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 then plaintext credentials in `~/.config/gws/`)
+- `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` — Path to OAuth credentials JSON (no default; if unset, falls back to credentials secured by the OS Keyring and encrypted in `~/.config/gws/`)
 - Supports `.env` files via `dotenvy`

Cargo.lock

@@ -50,6 +50,8 @@ derive_builder = "0.20.2"
 ratatui = "0.30.0"
 crossterm = "0.29.0"
 chrono = "0.4.44"
+keyring = "3.6.3"
+async-trait = "0.1.89"
 
 
 # The profile that 'cargo dist' will build with

Cargo.toml

@@ -79,6 +79,12 @@ gws schema drive.files.list
 # Dynamic help for any resource
 gws drive files --help
 gws drive files list --help
+
+# Preview a request without sending it
+gws chat spaces messages create \
+  --params '{"parent": "spaces/xyz"}' \
+  --json '{"text": "Hello world"}' \
+  --dry-run
 ```
 
 ## Authentication
@@ -87,20 +93,18 @@ The CLI supports three primary authentication workflows depending on your enviro
 
 ### 1. Interactive Auth (Local Desktop)
 
-For interactive use on your personal machine where a web browser is available. By default, credentials are encrypted at rest using AES-256-GCM.
+For interactive use on your personal machine where a web browser is available. 
+
+**Security**: By default, credentials and access tokens are encrypted at rest using AES-256-GCM. The encryption key is stored securely in your OS Keyring (Apple Keychain, Secret Service, or Windows Credential Manager). If a keyring is unavailable (e.g., headless Linux), it falls back to a strictly permissioned (`0600`) local key file.
 
-**Google Cloud Setup:**
-1. Create a project: `gcloud projects create my-gws-cli`
-2. Enable Workspace APIs: `gcloud services enable --project my-gws-cli drive.googleapis.com ...`
-3. Create an OAuth consent screen at [Credentials/Consent](https://console.cloud.google.com/apis/credentials/consent).
-4. Create an OAuth **Desktop app** Client ID at [Credentials](https://console.cloud.google.com/apis/credentials).
+**Google Cloud Setup & Login:**
+The CLI includes a built-in setup wizard to help you configure your Google Cloud Project, enable APIs, and generate the necessary OAuth credentials. Note that this requires the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install) to be installed and authenticated (`gcloud auth login`).
 
-**Login:**
 ```bash
-export GOOGLE_WORKSPACE_CLI_CLIENT_ID=your_client_id.apps.googleusercontent.com
-export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET=your_client_secret
+# Run the interactive setup and login wizard
+gws setup
 
-# Opens browser for OAuth2 consent
+# Or login directly if you already have client_secret.json configured
 gws auth login
 
 # Or login with custom scopes
@@ -163,7 +167,7 @@ The CLI evaluates authentication sources in the following strict order:
 |----------|--------|------------|
 | 1 (highest) | Raw access token | `GOOGLE_WORKSPACE_CLI_TOKEN` env var |
 | 2 | Credentials file (user or service account) | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` env var |
-| 3 | Encrypted credentials | `~/.config/gws/credentials.enc` (created by `gws auth login`) |
+| 3 | Encrypted credentials & token cache | `~/.config/gws/credentials.enc` and `token_cache.json` (created by `gws auth login`, secured via OS Keyring) |
 | 4 | Plaintext credentials | `~/.config/gws/credentials.json` |
 | — | No auth | Proceeds unauthenticated; shows error if the API rejects |
 

README.md

@@ -70,7 +70,9 @@ async fn get_token_inner(
         Credential::AuthorizedUser(secret) => {
             let token_cache = config_dir.join("token_cache.json");
             let auth = yup_oauth2::AuthorizedUserAuthenticator::builder(secret)
-                .persist_tokens_to_disk(&token_cache)
+                .with_storage(Box::new(crate::token_storage::EncryptedTokenStorage::new(
+                    token_cache,
+                )))
                 .build()
                 .await
                 .context("Failed to build authorized user authenticator")?;
@@ -83,8 +85,10 @@ async fn get_token_inner(
         }
         Credential::ServiceAccount(key) => {
             let token_cache = config_dir.join("service_account_token_cache.json");
-            let mut builder = yup_oauth2::ServiceAccountAuthenticator::builder(key)
-                .persist_tokens_to_disk(&token_cache);
+            let mut builder =
+                yup_oauth2::ServiceAccountAuthenticator::builder(key).with_storage(Box::new(
+                    crate::token_storage::EncryptedTokenStorage::new(token_cache),
+                ));
 
             // Check for impersonation
             if let Some(user) = impersonated_user {

src/auth.rs

@@ -155,7 +155,9 @@ async fn handle_login(args: &[String]) -> Result<(), GwsError> {
         secret,
         yup_oauth2::InstalledFlowReturnMethod::HTTPRedirect,
     )
-    .persist_tokens_to_disk(&temp_path)
+    .with_storage(Box::new(crate::token_storage::EncryptedTokenStorage::new(
+        temp_path.clone(),
+    )))
     .force_account_selection(true) // Adds prompt=consent so Google always returns a refresh_token
     .flow_delegate(Box::new(CliFlowDelegate))
     .build()
@@ -202,7 +204,7 @@ async fn handle_login(args: &[String]) -> Result<(), GwsError> {
             "status": "success",
             "message": "Authentication successful. Encrypted credentials saved.",
             "credentials_file": enc_path.display().to_string(),
-            "encryption": "AES-256-GCM (key derived from hostname + username)",
+            "encryption": "AES-256-GCM (key secured by OS Keyring or local `.encryption_key`)",
             "scopes": scopes,
         });
         println!(

src/auth_commands.rs

@@ -16,27 +16,111 @@ use std::path::PathBuf;
 
 use aes_gcm::aead::{Aead, KeyInit, OsRng};
 use aes_gcm::{AeadCore, Aes256Gcm, Nonce};
-use sha2::{Digest, Sha256};
 
-/// Derives an AES-256 key from hostname + username.
-fn derive_key() -> [u8; 32] {
-    let hostname = hostname::get()
-        .map(|h| h.to_string_lossy().to_string())
-        .unwrap_or_else(|_| "unknown-host".to_string());
+use keyring::Entry;
+use rand::RngCore;
+use std::sync::OnceLock;
+
+/// Returns the encryption key derived from the OS keyring, or falls back to a local file.
+/// Generates a random 256-bit key and stores it securely if it doesn't exist.
+fn get_or_create_key() -> anyhow::Result<[u8; 32]> {
+    static KEY: OnceLock<[u8; 32]> = OnceLock::new();
+
+    if let Some(key) = KEY.get() {
+        return Ok(*key);
+    }
 
     let username = std::env::var("USER")
         .or_else(|_| std::env::var("USERNAME"))
         .unwrap_or_else(|_| "unknown-user".to_string());
 
-    let mut hasher = Sha256::new();
-    hasher.update(format!("gws-cli:{hostname}:{username}"));
-    hasher.finalize().into()
+    let entry = Entry::new("gws-cli", &username);
+
+    if let Ok(entry) = entry {
+        match entry.get_password() {
+            Ok(b64_key) => {
+                use base64::{engine::general_purpose::STANDARD, Engine as _};
+                if let Ok(decoded) = STANDARD.decode(&b64_key) {
+                    if decoded.len() == 32 {
+                        let mut arr = [0u8; 32];
+                        arr.copy_from_slice(&decoded);
+                        let _ = KEY.set(arr);
+                        return Ok(arr);
+                    }
+                }
+            }
+            Err(keyring::Error::NoEntry) => {
+                // Generate a random 32-byte key
+                let mut key = [0u8; 32];
+                rand::thread_rng().fill_bytes(&mut key);
+
+                use base64::{engine::general_purpose::STANDARD, Engine as _};
+                let b64_key = STANDARD.encode(key);
+
+                if entry.set_password(&b64_key).is_ok() {
+                    let _ = KEY.set(key);
+                    return Ok(key);
+                }
+            }
+            Err(_) => {} // Fallthrough to file storage
+        }
+    }
+
+    // Fallback: Local file `.encryption_key`
+    let key_file = crate::auth_commands::config_dir().join(".encryption_key");
+    if key_file.exists() {
+        if let Ok(b64_key) = std::fs::read_to_string(&key_file) {
+            use base64::{engine::general_purpose::STANDARD, Engine as _};
+            if let Ok(decoded) = STANDARD.decode(b64_key.trim()) {
+                if decoded.len() == 32 {
+                    let mut arr = [0u8; 32];
+                    arr.copy_from_slice(&decoded);
+                    let _ = KEY.set(arr);
+                    return Ok(arr);
+                }
+            }
+        }
+    }
+
+    // Generate new key and save to local file
+    let mut key = [0u8; 32];
+    rand::thread_rng().fill_bytes(&mut key);
+
+    use base64::{engine::general_purpose::STANDARD, Engine as _};
+    let b64_key = STANDARD.encode(key);
+
+    if let Some(parent) = key_file.parent() {
+        let _ = std::fs::create_dir_all(parent);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o700));
+        }
+    }
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut options = std::fs::OpenOptions::new();
+        options.write(true).create(true).truncate(true).mode(0o600);
+        if let Ok(mut file) = options.open(&key_file) {
+            use std::io::Write;
+            let _ = file.write_all(b64_key.as_bytes());
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = std::fs::write(&key_file, b64_key);
+    }
+
+    let _ = KEY.set(key);
+    Ok(key)
 }
 
 /// Encrypts plaintext bytes using AES-256-GCM with a machine-derived key.
 /// Returns nonce (12 bytes) || ciphertext.
 pub fn encrypt(plaintext: &[u8]) -> anyhow::Result<Vec<u8>> {
-    let key = derive_key();
+    let key = get_or_create_key()?;
     let cipher = Aes256Gcm::new_from_slice(&key)
         .map_err(|e| anyhow::anyhow!("Failed to create cipher: {e}"))?;
 
@@ -57,7 +141,7 @@ pub fn decrypt(data: &[u8]) -> anyhow::Result<Vec<u8>> {
         anyhow::bail!("Encrypted data too short");
     }
 
-    let key = derive_key();
+    let key = get_or_create_key()?;
     let cipher = Aes256Gcm::new_from_slice(&key)
         .map_err(|e| anyhow::anyhow!("Failed to create cipher: {e}"))?;
 
@@ -82,16 +166,27 @@ pub fn save_encrypted(json: &str) -> anyhow::Result<PathBuf> {
     let path = encrypted_credentials_path();
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o700));
+        }
     }
 
     let encrypted = encrypt(json.as_bytes())?;
-    std::fs::write(&path, encrypted)?;
 
-    // Set file permissions to 600 on Unix
     #[cfg(unix)]
     {
-        use std::os::unix::fs::PermissionsExt;
-        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut options = std::fs::OpenOptions::new();
+        options.write(true).create(true).truncate(true).mode(0o600);
+        let mut file = options.open(&path)?;
+        use std::io::Write;
+        file.write_all(&encrypted)?;
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::write(&path, encrypted)?;
     }
 
     Ok(path)
@@ -205,15 +300,15 @@ mod tests {
     }
 
     #[test]
-    fn derive_key_is_deterministic() {
-        let key1 = derive_key();
-        let key2 = derive_key();
+    fn get_or_create_key_is_deterministic() {
+        let key1 = get_or_create_key().unwrap();
+        let key2 = get_or_create_key().unwrap();
         assert_eq!(key1, key2);
     }
 
     #[test]
-    fn derive_key_produces_256_bits() {
-        let key = derive_key();
+    fn get_or_create_key_produces_256_bits() {
+        let key = get_or_create_key().unwrap();
         assert_eq!(key.len(), 32);
     }
 }

src/credential_store.rs

@@ -20,10 +20,10 @@
 //! interactive prompts, and integration with Model Armor.
 
 mod auth;
-mod auth_commands;
+pub(crate) mod auth_commands;
 mod client;
 mod commands;
-mod credential_store;
+pub(crate) mod credential_store;
 mod discovery;
 mod error;
 mod executor;
@@ -35,6 +35,7 @@ mod schema;
 mod services;
 mod setup;
 mod setup_tui;
+mod token_storage;
 
 use error::{print_error_json, GwsError};