feat(oauth_claude): add macOS Keychain support for credential storage

[hanzili]

Summary

Add macOS Keychain fallback to ClaudeOAuthStorage.load() for reading Claude OAuth credentials.

Problem

Claude Code stores OAuth credentials in macOS Keychain and intentionally deletes the plain text ~/.claude/.credentials.json file for security. This is documented behavior since v1.0.5:

"This is intended behavior (cleaning up plain text credentials when successfully storing them in macos keychain)"

As a result, CCProxy fails to load credentials on macOS:

ValueError: No valid OAuth access token available for Claude API

Solution

• Try reading from ~/.claude/.credentials.json first (existing behavior)
• Fall back to macOS Keychain using the security command
• Use the service name "Claude Code-credentials" (same as Claude Code)
• Log which source was used (source=file or source=keychain)

Changes

• Added _read_from_macos_keychain() async helper function
• Modified ClaudeOAuthStorage.load() to try Keychain when file is missing
• Added timeout and error handling for subprocess call
• Platform check ensures this only runs on macOS (Darwin)

Testing

Tested locally on macOS with:

1. Removed ~/.claude/.credentials.json
2. Verified credentials exist in Keychain: security find-generic-password -s "Claude Code-credentials" -w
3. Started CCProxy - logs show claude_oauth_credentials_loaded_from_keychain
4. Made API calls successfully through CCProxy

References

• Claude Code Issue #1414 - Confirms file deletion is intentional
• Claude Code IAM Docs - "On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain"

---

🤖 Generated with Claude Code

[CaddyGlow]

Refactored to use keyring library

Replaced the subprocess-based security command with the cross-platform keyring library.

Changes

Implementation (storage.py):

• Uses keyring.get_password() instead of subprocess.run() with the security CLI
• Service name: "Claude Code" with account "credentials" (matching Claude Code's storage)
• Added _is_keyring_available() for graceful degradation when keyring isn't installed
• Improved exception handling with specific error types
• Type-safe JSON parsing (validates dict type instead of casting)

Cross-platform support:

• macOS Keychain
• Windows Credential Manager
• Linux Secret Service (GNOME Keyring, KDE Wallet)

Tests (test_storage.py):

• 15 unit tests covering keychain availability, read success/failure, fallback behavior, and error handling

Dependencies

• Added keyring>=25.0.0 to plugins-claude optional dependencies

Note

Did not have access to a macOS machine to test the keyring integration against the actual macOS Keychain. Please verify on macOS before merging.