OAuth & Auth Handlers
Relevant source files
The following files were used as context for generating this wiki page:
- src/cliproxy/auth/oauth-process.ts
- src/cliproxy/auth/tests/oauth-handler-paste-callback.test.ts
- src/cliproxy/auth/tests/auth-token-manager.test.js
- src/cliproxy/auth/tests/oauth-process-error-parser.test.ts
- ui/src/pages/settings/sections/auth-section.tsx
- src/commands/help-command.ts
- src/cliproxy/services/tests/remote-token-uploader.test.ts
The OAuth & Auth Handlers system in CCS provides a robust framework for authenticating various AI service providers (such as Gemini, Codex, and Kiro) and managing the lifecycle of authentication tokens. It bridges the gap between CLI-based workflows and browser-based OAuth flows, supporting local callback servers, device code prompts, and manual "paste-callback" recovery methods.
This system ensures secure token storage, cryptographic token generation for internal management, and a unified interface for the CCS Dashboard and CLI to interact with provider-specific authentication protocols.
Authentication Architecture
The architecture is divided into process execution, lifecycle monitoring, and token management. The system spawns provider-specific binaries and monitors their output to guide the user through the authentication process.
OAuth Process Flow
The core logic resides in executeOAuthProcess, which manages the spawning of authentication binaries and handles real-time communication via stdout and stderr.
Key Components
| Component | Description |
|---|---|
| ProcessState | Tracks the internal state of an active OAuth attempt, including URLs displayed, device codes, and project prompts. |
| OAuthTraceRecorder | Records lifecycle events (Phases) for auditing and troubleshooting authentication failures. |
| AuthSessionManager | Manages active sessions, allowing for external cancellation and process attachment. |
| TokenManager | Handles the detection, snapshots, and registration of newly created provider tokens. |
Sources: src/cliproxy/auth/oauth-process.ts:47-65, src/cliproxy/auth/oauth-process.ts:650-670
Supported Authentication Flows
CCS supports several distinct OAuth and credential-based flows depending on the provider and environment.
1. Authorization Code Flow
Used by most web-based providers. A local callback server is started (typically on a loopback address) to receive the redirect from the browser.
- Manual Replay: If the browser cannot reach the local server, users can use
--paste-callbackto manually submit the full redirect URL to the CLI. - Validation: The system validates the pasted URL for loopback hostnames, matching states, and valid
codeparameters.
2. Device Code Flow
Commonly used by GitHub-based providers or in headless environments.
- User Action: The user is provided with a short alphanumeric code and a verification URL.
- Polling: The CLI polls the provider's token endpoint until the user completes authorization in their browser.
3. Personal Access Token (PAT)
Specifically used for GitLab Duo, where users can provide a token directly to the CLI instead of using a browser flow.
Sources: src/cliproxy/auth/oauth-process.ts:322-380, src/commands/help-command.ts:130-150, src/cliproxy/auth/tests/oauth-handler-paste-callback.test.ts:380-400
Token Management and Security
CCS implements strict security measures for managing both internal system tokens and external provider credentials.
Cryptographic Token Generation
Internal management keys and API keys are generated using crypto.randomBytes and encoded as base64url to ensure high entropy and URL safety.
Sources: src/cliproxy/auth/tests/auth-token-manager.test.js:20-50
Token Masking
To prevent credential leakage in the UI or logs, tokens are masked using a "first-4, last-4" pattern.
- Logic: If length > 8, show
xxxx...yyyy. If length ≤ 8, show****.
Sources: src/cliproxy/auth/tests/auth-token-manager.test.js:75-90, ui/src/pages/settings/sections/auth-section.tsx:280-320
Config Inheritance Logic
API keys follow a priority-based inheritance model:
- Variant Override:
cliproxy.variants.<name>.auth.api_key - Global Config:
cliproxy.auth.api_key - Default:
ccs-internal-managed
Sources: src/cliproxy/auth/tests/auth-token-manager.test.js:120-150
Error Diagnosis and Recovery
The system includes a sophisticated log parser to identify common authentication failures and provide actionable guidance.
| Failure Category | Detection Logic | User Guidance |
|---|---|---|
| Subscription Missing | Matches "failed to verify Copilot access" or "403 Forbidden". | Verify active subscription on provider site. |
| Network Timeout | Monitored by executeOAuthProcess timer (default 2-5 mins). | Check firewall rules or use port-forwarding. |
| Remote Upload Error | Detected during token sync to remote CLIProxy instances. | Verify Management Key permissions. |
| State Mismatch | Comparison of state parameter in OAuth callback vs original. | Restart auth flow to generate fresh session. |
Sources: src/cliproxy/auth/tests/oauth-process-error-parser.test.ts:15-50, src/cliproxy/services/tests/remote-token-uploader.test.ts:60-80
Diagnostic Tracing
The OAuthTraceRecorder captures the exact phase of failure.
- BinaryExit: Captures exit code and the last line of
stderr. - TokenFileMissing: Triggered if the process exits with
0but no new credentials appear in the token directory.
Sources: src/cliproxy/auth/oauth-process.ts:800-850, src/cliproxy/auth/tests/oauth-handler-paste-callback.test.ts:240-270
Dashboard Integration
The CCS Dashboard provides a web interface for managing these authentication settings via the AuthSection.
- Real-time Updates: Users can update the
apiKeyandmanagementSecretdirectly. - Regeneration: The dashboard allows for one-click regeneration of the management secret.
- Visibility Toggle: Sensitive values are hidden by default but can be toggled via the
Eye/EyeOfficons.
Sources: ui/src/pages/settings/sections/auth-section.tsx:50-120, ui/src/pages/settings/sections/auth-section.tsx:250-300
The OAuth and Auth Handler system is central to CCS's ability to provide a seamless multi-provider experience, ensuring that authentication is handled reliably across local and remote environments.