ochenstarik/hermes-hub
1
0
Fork 0
Code Issues Pull requests Projects Releases 13 Packages Wiki Activity Actions
hermes-hub/docs/OAUTH_CLIENT.md
Hermes Team 42eddb3627 fix(quota, oauth): enforce data truthfulness, honest quota sources, and fail-closed OAuth 
- Removed fabricated used_percent numbers and fake *_api source tags from quota_collector.py
- Marked quota snapshot sources as baseline/estimated and added visual estimation indicators in accounts_view.py
- Eliminated silent fallback on fake user_code/device_code in codex_oauth.py and grok_oauth.py
- Gated mock OAuth sessions strictly behind HERMES_HUB_DEV_MODE=1 with visible UI warnings
- Documented Google, OpenAI, xAI, and Claude OAuth clients in docs/OAUTH_CLIENT.md
- Relocated unused gui_server.py and gui_cockpit.html to legacy/
- Added test_data_truthfulness_and_oauth_security.py covering fail-closed and source truthfulness invariants
- Verified 98 passed tests (100%) and 7/7 release gate checks
2026-08-20 22:11:57 +07:00

5.3 KiB
Raw Permalink Blame History

OAuth 2.0 Native & Device Client Architecture & Security Decision

Document Version: 1.1.0
Date: 2026-08-21
Status: Approved Architectural Decision
Scope: src/antigravity_provider/router/*_oauth.py

1. Executive Summary & Threat Model

Hermes Hub is a local desktop orchestrator and router for developer agents running on the user's workstation. To connect seamlessly to multi-provider accounts without requiring users to create custom cloud console client applications, Hermes Hub implements standard native desktop and device authorization flows per IETF RFC specifications.

Applicable Standards

  • RFC 8252 (OAuth 2.0 for Native Apps): Native desktop applications are Public Clients (RFC 6749 Section 2.1). They cannot securely protect embedded client secrets against binary extraction or local debugging.
  • RFC 7636 (Proof Key for Code Exchange / PKCE): Protects authorization code grants against interception by dynamically generating cryptographic code verifiers and challenges.
  • RFC 8628 (OAuth 2.0 Device Authorization Grant): Allows browserless or secondary-screen authorization via standard user verification codes and polling.

2. Documented Provider Clients

2.1 Google Antigravity Native Desktop Client

  • Protocol: RFC 8252 (Native App) + RFC 7636 (PKCE S256) + Loopback Interface Redirect (http://127.0.0.1:51121/oauth-callback)
  • Module: src/antigravity_provider/router/profile_oauth.py
  • Origin: Google CloudCode / Gemini Code Assist standard native tool client
  • Client Type: Native Application (Public Client)
  • Client ID: 1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com
  • Client Secret: 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 (Public client placeholder per Google Cloud SDK native tool standard)
  • 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

2.2 OpenAI Codex Device Flow Client

  • Protocol: RFC 8628 (OAuth 2.0 Device Authorization Grant)
  • Module: src/antigravity_provider/router/codex_oauth.py
  • Origin: OpenAI Codex / ChatGPT developer tooling public client
  • Client Type: Native Device Client (Public Client)
  • Client ID: app_EMoamEEZ73f0CkXaXp7hrann
  • Endpoints:
    • User Code Request: https://auth.openai.com/deviceauth/usercode
    • User Verification: https://auth0.openai.com/activate
    • Device Token Poll: https://auth.openai.com/deviceauth/token
  • Security Invariant: User codes must originate from the OpenAI authorization server. If the server is unreachable, an immediate error is presented to the user. Mock session generation is strictly gated behind HERMES_HUB_DEV_MODE=1 with visible UI badging.

2.3 xAI Grok Device Authorization Client

  • Protocol: RFC 8628 (OAuth 2.0 Device Authorization Grant)
  • Module: src/antigravity_provider/router/grok_oauth.py
  • Origin: xAI Grok developer desktop tooling public client
  • Client Type: Native Device Client (Public Client)
  • Client ID: b1a00492-073a-47ea-816f-4c329264a828
  • Endpoints:
    • Device Code Request: https://auth.x.ai/oauth2/device/code
    • Verification URL: Complete URI provided by xAI server or https://auth.x.ai/device
    • Token Poll: https://auth.x.ai/oauth2/token
  • Required Scope: openid profile email offline_access
  • Security Invariant: Device codes must originate from xAI. In standard operation, network failures abort authorization immediately. Mock codes are permitted only under HERMES_HUB_DEV_MODE=1.

2.4 Anthropic Claude Desktop OAuth Client

  • Protocol: RFC 8252 (Native App) + RFC 7636 (PKCE S256) + Manual Code/Token Paste
  • Module: src/antigravity_provider/router/claude_oauth.py
  • Origin: Claude desktop developer tooling public client
  • Client Type: Native Application (Public Client)
  • Client ID: 9d1c250a-e274-4630-9742-1e96a2202eb8
  • Endpoints:
    • Auth URL: https://claude.ai/oauth/authorize
    • Token Exchange: https://claude.ai/api/auth/oauth/token (and official fallback exchange endpoints)
  • Redirect URI: https://claude.ai/oauth/callback
  • Required Scope: openid profile email
  • Security Invariant: Network exchange failures return explicit error messages. Manual fallback is strictly restricted to valid API tokens or HERMES_HUB_DEV_MODE=1.

3. Transparency, Credentials Isolation & Scanner Policy

  1. Explicit Constants: All public client identifiers and standard endpoints are defined clearly and explicitly in code. Obfuscated string concatenation is strictly prohibited.
  2. Local Credential Storage: Runtime credentials (access_token, refresh_token, expiration timestamps) are stored in the user's isolated local profile store (%HERMES_HOME%/*_profiles/<profile_id>/auth.json or Windows Credential Manager) with restricted file permissions (0o600) and are excluded from git.
  3. AST Secret Scanner Policy: The scanner verifies that no live user API keys (sk-..., sk-ant-..., xai-...), private tokens, or obfuscated secret assignments exist in the codebase, while allowing documented public client constants compliant with RFC 8252/8628.