46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
# Google OAuth 2.0 Desktop Client Architecture & Security Decision
|
|
|
|
**Document Version:** 1.0.0
|
|
**Date:** 2026-08-20
|
|
**Status:** Approved Architectural Decision
|
|
**Target Module:** `src/antigravity_provider/oauth.py`
|
|
|
|
---
|
|
|
|
## 1. Context & Threat Model
|
|
|
|
Hermes Hub acts as a local orchestrator and router for developer agents, connecting to Google Antigravity (Gemini Code Assist / CloudCode ecosystem) via OAuth 2.0.
|
|
|
|
Under **RFC 8252 (OAuth 2.0 for Native Apps)**:
|
|
- A desktop or command-line application is classified as a **Public Client** (RFC 6749 Section 2.1).
|
|
- Native desktop applications cannot securely store private client secrets against binary inspection or local debugging.
|
|
- Security of the authorization grant relies on **PKCE (RFC 7636)** and the **Loopback Interface Redirect URI** (`http://127.0.0.1:51121/oauth-callback`).
|
|
|
|
---
|
|
|
|
## 2. Decision: Documented Native Desktop Client
|
|
|
|
We utilize the standard Google CloudCode Desktop OAuth Client configuration intended for native developer desktop tooling.
|
|
|
|
### Configuration Specification
|
|
|
|
- **Client Type:** Native Application (Installed App)
|
|
- **Client ID:** `1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com`
|
|
- **Client Secret:** `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` (Public client placeholder per Google Cloud SDK native tool standard)
|
|
- **Redirect URI:** `http://127.0.0.1:51121/oauth-callback`
|
|
- **Auth Endpoint:** `https://accounts.google.com/o/oauth2/v2/auth`
|
|
- **Token Endpoint:** `https://oauth2.googleapis.com/token`
|
|
- **Required Scopes:**
|
|
- `https://www.googleapis.com/auth/cloud-platform`
|
|
- `https://www.googleapis.com/auth/userinfo.email`
|
|
- `https://www.googleapis.com/auth/userinfo.profile`
|
|
- `https://www.googleapis.com/auth/cclog`
|
|
- `https://www.googleapis.com/auth/experimentsandconfigs`
|
|
|
|
---
|
|
|
|
## 3. Transparency & Scanner Policy
|
|
|
|
1. **No Obfuscation:** The source code in `src/antigravity_provider/oauth.py` directly defines these public constants with explicit references to RFC 8252. Obfuscated string concatenation (`"abc" + "def"`) is strictly prohibited.
|
|
2. **Scanner Policy:** The security scanner treats the documented native public client constants as known standard constants, while strictly prohibiting live user API keys (`sk-...`, `opencode-...`), bearer tokens, private keys, and unauthorized secret assignments in source code.
|
|
3. **Local User Credential Isolation:** All runtime user tokens (`access_token`, `refresh_token`, expiration timestamps) are saved strictly inside the user's isolated local data directory (`%HERMES_HOME%/agy_profiles/<profile_id>/auth.json` or OS keychain) and are **never tracked in git or shared**.
|