Skip to content

OAuth Plugin Architecture

This document describes how CCProxy structures OAuth-capable plugins and the shared conventions you should follow when adding new providers.

Core Concepts

  • Token Storage – Each provider ships a storage backend that persists OAuth credentials (usually JSON files under ~/.config/ccproxy).
  • Token Manager – A subclass of BaseEnhancedTokenManager responsible for refreshing tokens, exposing TokenSnapshot data, and integrating with the CLI.
  • Plugin Runtime – The plugin factory wires the manager and storage into a ProviderPluginRuntime so adapters receive authenticated HTTP clients via dependency injection.
  • Hook Integration – OAuth managers emit hook events (HookEvent.OAUTH_TOKEN_REQUEST, HookEvent.OAUTH_TOKEN_RESPONSE, etc.) for observability and analytics.

File Layout

ccproxy/plugins/<provider>/
├── manager.py           # Token manager implementation
├── storage.py           # Credential persistence helpers
├── plugin.py            # Factory + manifest wiring
├── adapter.py           # HTTP adapter using the manager
├── routes.py            # FastAPI routers (if applicable)
├── schemas.py           # Pydantic models for OAuth payloads
└── README.md            # Provider-specific notes

OAuth Flow

  1. CLI Initiation – ccproxy auth login <provider> looks up the plugin manifest and resolves its OAuthFlow descriptor.
  2. Device / Browser Grant – The CLI opens the provider authorization URL (PKCE, device-code, or standard authorization code) and polls for completion using httpx.
  3. Credential Storage – The resulting tokens are serialized via the plugin storage class. Secrets are masked when echoed back to the user.
  4. Runtime Refresh – On startup the token manager loads credentials, validates expiry, and schedules refresh jobs through the async task manager.
  5. Snapshot Reporting – Managers expose TokenSnapshot for /auth status, enabling consistent diagnostics across providers.

Implementing a New OAuth Plugin

  1. Define Settings – Create a Config model with the provider-specific endpoints and scopes. Register defaults in the plugin manifest.
  2. Implement Storage – Subclass BaseJSONTokenStorage (or equivalent) to read/write credential files. Handle migration of legacy formats in migrate().
  3. Implement Manager – Extend BaseEnhancedTokenManager and implement _build_token_snapshot() plus provider-specific refresh logic. Use AsyncHTTPClientFactory from the container for outbound requests.
  4. Expose Routes / CLI – If the provider needs webhook callbacks or additional CLI commands, add them via manifest.routes and manifest.cli_commands.
  5. Register Plugin – Export factory = <YourFactory>() at module scope so entry-point discovery works.

Security Recommendations

  • Store tokens with 0600 permissions and avoid embedding secrets in configuration files committed to source control.
  • Use PKCE (code verifier + challenge) whenever the provider supports it.
  • Rotate refresh tokens when the provider issues new ones; do not assume they are long lived.
  • Emit structured log events without leaking raw tokens. The TokenSnapshot helper masks sensitive fields by default.

Testing Checklist

  • Unit-test storage migrations to ensure existing users keep working after upgrades.
  • Mock OAuth endpoints with pytest-httpx and cover success, refresh, and error paths.
  • Run ./Taskfile test-plugins with the plugin enabled to verify end-to-end behaviour.
  • Exercise CLI flows manually using sandbox credentials before releasing a new provider version.

Troubleshooting

  • Use ccproxy auth status --provider <name> to inspect stored credentials and expiry timestamps.
  • Enable verbose logging: LOGGING__LEVEL=debug uv run ccproxy serve.
  • If refresh attempts fail repeatedly, delete the credential file and redo ccproxy auth login to obtain a clean grant.