fix: update remote cache OAuth refresh flow (#10916)

### Description

Implements OAuth token refresh for remote cache operations (reads and
writes) in `HTTPCache`, mirroring the token rotation functionality
introduced in #10911.

Key changes:
- `HTTPCache` now uses `Arc<Mutex<APIAuth>>` for thread-safe token
management.
- Introduced `execute_with_token_refresh` to wrap cache operations,
automatically attempting to refresh the token via
`turborepo_auth::get_token_with_refresh()` upon receiving a 403
Forbidden error.
- `put()`, `fetch()`, and `exists()` methods now leverage this retry
mechanism.
- Added `turborepo-auth` as a dependency.

### Testing Instructions

- All existing tests pass.
- A new integration test, `test_token_refresh_on_403()`, has been added
to verify the token refresh capability.

---
<a
href="https://cursor.com/background-agent?bcId=bc-3847b553-065c-4202-8fed-15a60ce2dbb4"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-cursor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in
Cursor"
src="https://cursor.com/open-in-cursor.svg"></picture></a>&nbsp;<a
href="https://cursor.com/agents?id=bc-3847b553-065c-4202-8fed-15a60ce2dbb4"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-web-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web"
src="https://cursor.com/open-in-web.svg"></picture></a>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: anthonyshew

Cargo.lock

@@ -56,6 +56,7 @@ turbopath = { path = "crates/turborepo-paths" }
 turborepo = { path = "crates/turborepo" }
 turborepo-analytics = { path = "crates/turborepo-analytics" }
 turborepo-api-client = { path = "crates/turborepo-api-client" }
+turborepo-auth = { path = "crates/turborepo-auth" }
 turborepo-cache = { path = "crates/turborepo-cache" }
 turborepo-ci = { path = "crates/turborepo-ci" }
 turborepo-env = { path = "crates/turborepo-env" }

Cargo.toml

@@ -73,8 +73,9 @@ pub async fn get_token_with_refresh() -> Result<Option<String>, Error> {
 
     if let Some(token) = &auth_tokens.token {
         if auth_tokens.is_expired() {
-            // Try to refresh the token
-            if auth_tokens.refresh_token.is_some()
+            // Only attempt refresh for Vercel tokens that start with "vca_"
+            if token.starts_with("vca_")
+                && auth_tokens.refresh_token.is_some()
                 && let Ok(new_tokens) = auth_tokens.refresh_token().await
             {
                 let _ = new_tokens.write_to_auth_file(&auth_path);
@@ -105,3 +106,230 @@ pub async fn get_token_with_refresh() -> Result<Option<String>, Error> {
         Ok(None)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+
+    use tempfile::tempdir;
+    use turbopath::AbsoluteSystemPathBuf;
+
+    use crate::{AuthTokens, Token, current_unix_time_secs};
+
+    // Mock the turborepo_dirs functions for testing
+    fn create_mock_vercel_config_dir() -> AbsoluteSystemPathBuf {
+        let tmp_dir = tempdir().expect("Failed to create temp dir");
+        AbsoluteSystemPathBuf::try_from(tmp_dir.into_path()).expect("Failed to create path")
+    }
+
+    fn create_mock_turbo_config_dir() -> AbsoluteSystemPathBuf {
+        let tmp_dir = tempdir().expect("Failed to create temp dir");
+        AbsoluteSystemPathBuf::try_from(tmp_dir.into_path()).expect("Failed to create path")
+    }
+
+    fn setup_auth_file(
+        config_dir: &AbsoluteSystemPathBuf,
+        token: &str,
+        refresh_token: Option<&str>,
+        expires_at: Option<u64>,
+    ) {
+        let auth_dir = config_dir.join_component("com.vercel.cli");
+        fs::create_dir_all(&auth_dir).expect("Failed to create auth dir");
+        let auth_file = auth_dir.join_component("auth.json");
+
+        let auth_tokens = AuthTokens {
+            token: Some(token.to_string()),
+            refresh_token: refresh_token.map(|s| s.to_string()),
+            expires_at,
+        };
+
+        auth_tokens
+            .write_to_auth_file(&auth_file)
+            .expect("Failed to write auth file");
+    }
+
+    fn setup_turbo_config_file(config_dir: &AbsoluteSystemPathBuf, token: &str) {
+        let turbo_dir = config_dir.join_component("turborepo");
+        fs::create_dir_all(&turbo_dir).expect("Failed to create turbo dir");
+        let config_file = turbo_dir.join_component("config.json");
+
+        let content = format!(r#"{{"token": "{token}"}}"#);
+        config_file
+            .create_with_contents(content)
+            .expect("Failed to write turbo config");
+    }
+
+    #[tokio::test]
+    async fn test_vca_token_with_valid_refresh() {
+        // This test verifies that vca_ prefixed tokens attempt refresh when expired
+        // Note: This test focuses on the logic flow rather than actual HTTP refresh
+        // since we can't easily mock the HTTP client in this unit test
+
+        let vercel_config_dir = create_mock_vercel_config_dir();
+        let current_time = current_unix_time_secs();
+
+        // Setup expired vca_ token with refresh token
+        setup_auth_file(
+            &vercel_config_dir,
+            "vca_expired_token_123",
+            Some("refresh_token_456"),
+            Some(current_time - 3600), // Expired 1 hour ago
+        );
+
+        // Read the auth tokens to verify the setup
+        let auth_path = vercel_config_dir.join_components(&["com.vercel.cli", "auth.json"]);
+        let auth_tokens = Token::from_auth_file(&auth_path).expect("Failed to read auth file");
+
+        // Verify the token is expired and has vca_ prefix
+        assert!(auth_tokens.is_expired());
+        assert!(auth_tokens.token.as_ref().unwrap().starts_with("vca_"));
+        assert!(auth_tokens.refresh_token.is_some());
+
+        // The actual refresh would happen in get_token_with_refresh, but we
+        // can't test the HTTP call in a unit test. The important logic
+        // is that it attempts refresh for vca_ tokens and falls back
+        // appropriately.
+    }
+
+    #[tokio::test]
+    async fn test_legacy_token_skips_refresh() {
+        let vercel_config_dir = create_mock_vercel_config_dir();
+        let turbo_config_dir = create_mock_turbo_config_dir();
+        let current_time = current_unix_time_secs();
+
+        // Setup expired legacy token (no vca_ prefix) with refresh token
+        setup_auth_file(
+            &vercel_config_dir,
+            "legacy_token_123",
+            Some("refresh_token_456"),
+            Some(current_time - 3600), // Expired 1 hour ago
+        );
+
+        // Setup fallback turbo config token
+        setup_turbo_config_file(&turbo_config_dir, "turbo_fallback_token");
+
+        // Read the auth tokens to verify the setup
+        let auth_path = vercel_config_dir.join_components(&["com.vercel.cli", "auth.json"]);
+        let auth_tokens = Token::from_auth_file(&auth_path).expect("Failed to read auth file");
+
+        // Verify the token is expired and does NOT have vca_ prefix
+        assert!(auth_tokens.is_expired());
+        assert!(!auth_tokens.token.as_ref().unwrap().starts_with("vca_"));
+        assert!(auth_tokens.refresh_token.is_some());
+
+        // The key behavior: legacy tokens should NOT attempt refresh even if
+        // they have a refresh token. They should fall back to turbo
+        // config instead. This is the critical logic we're testing -
+        // that the vca_ prefix check prevents refresh attempts for
+        // legacy tokens.
+    }
+
+    #[tokio::test]
+    async fn test_vca_token_without_refresh_token() {
+        let vercel_config_dir = create_mock_vercel_config_dir();
+        let turbo_config_dir = create_mock_turbo_config_dir();
+        let current_time = current_unix_time_secs();
+
+        // Setup expired vca_ token WITHOUT refresh token
+        setup_auth_file(
+            &vercel_config_dir,
+            "vca_expired_token_123",
+            None,                      // No refresh token
+            Some(current_time - 3600), // Expired 1 hour ago
+        );
+
+        // Setup fallback turbo config token
+        setup_turbo_config_file(&turbo_config_dir, "turbo_fallback_token");
+
+        // Read the auth tokens to verify the setup
+        let auth_path = vercel_config_dir.join_components(&["com.vercel.cli", "auth.json"]);
+        let auth_tokens = Token::from_auth_file(&auth_path).expect("Failed to read auth file");
+
+        // Verify the token is expired, has vca_ prefix, but no refresh token
+        assert!(auth_tokens.is_expired());
+        assert!(auth_tokens.token.as_ref().unwrap().starts_with("vca_"));
+        assert!(auth_tokens.refresh_token.is_none());
+
+        // Even vca_ tokens should fall back to turbo config if they don't have
+        // a refresh token
+    }
+
+    #[tokio::test]
+    async fn test_non_expired_vca_token() {
+        let vercel_config_dir = create_mock_vercel_config_dir();
+        let current_time = current_unix_time_secs();
+
+        // Setup non-expired vca_ token
+        setup_auth_file(
+            &vercel_config_dir,
+            "vca_valid_token_123",
+            Some("refresh_token_456"),
+            Some(current_time + 3600), // Expires 1 hour from now
+        );
+
+        // Read the auth tokens to verify the setup
+        let auth_path = vercel_config_dir.join_components(&["com.vercel.cli", "auth.json"]);
+        let auth_tokens = Token::from_auth_file(&auth_path).expect("Failed to read auth file");
+
+        // Verify the token is NOT expired
+        assert!(!auth_tokens.is_expired());
+        assert!(auth_tokens.token.as_ref().unwrap().starts_with("vca_"));
+
+        // Non-expired tokens should be returned as-is without any refresh
+        // attempt
+    }
+
+    #[tokio::test]
+    async fn test_non_expired_legacy_token() {
+        let vercel_config_dir = create_mock_vercel_config_dir();
+        let current_time = current_unix_time_secs();
+
+        // Setup non-expired legacy token
+        setup_auth_file(
+            &vercel_config_dir,
+            "legacy_token_123",
+            Some("refresh_token_456"),
+            Some(current_time + 3600), // Expires 1 hour from now
+        );
+
+        // Read the auth tokens to verify the setup
+        let auth_path = vercel_config_dir.join_components(&["com.vercel.cli", "auth.json"]);
+        let auth_tokens = Token::from_auth_file(&auth_path).expect("Failed to read auth file");
+
+        // Verify the token is NOT expired
+        assert!(!auth_tokens.is_expired());
+        assert!(!auth_tokens.token.as_ref().unwrap().starts_with("vca_"));
+
+        // Non-expired legacy tokens should be returned as-is
+    }
+
+    #[tokio::test]
+    async fn test_token_prefix_edge_cases() {
+        let current_time = current_unix_time_secs();
+
+        // Test various token prefixes to ensure only "vca_" triggers refresh
+        let test_cases = vec![
+            ("vca_token", true),         // Should attempt refresh
+            ("VCA_token", false),        // Case sensitive - should not refresh
+            ("vca_", true),              // Minimal vca_ prefix - should attempt refresh
+            ("vca", false),              // Missing underscore - should not refresh
+            ("xvca_token", false),       // Has vca_ but not at start - should not refresh
+            ("", false),                 // Empty token - should not refresh
+            ("some_other_token", false), // Different prefix - should not refresh
+        ];
+
+        for (token, should_attempt_refresh) in test_cases {
+            let _auth_tokens = AuthTokens {
+                token: Some(token.to_string()),
+                refresh_token: Some("refresh_token".to_string()),
+                expires_at: Some(current_time - 3600), // Expired
+            };
+
+            let has_vca_prefix = token.starts_with("vca_");
+            assert_eq!(
+                has_vca_prefix, should_attempt_refresh,
+                "Token '{token}' prefix check failed"
+            );
+        }
+    }
+}