Architecture: How should OAuth credential delegation be implemented across...

Documentation for Sessions

🏗️ Architecture: How should OAuth credential delegation be implemented across...

Date: 2026-03-18
Time: 17:30:11 UTC
Session: gspace1-234.11
Agent: backend
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How should OAuth credential delegation be implemented across the dual-backend architecture?

Task: S234.3 Phase 3: OAuth credential delegation architecture

🎯 Decision Made

Chosen:

backend-api (gograb-api) owns ALL OAuth tokens. OAuthService handles encryption (AES-256-GCM), PKCE consent flow, token storage, and API proxying. vitto-api never touches credentials — it calls backend-api's /auth/oauth/proxy endpoint via BackendApiClientService. Agent tools (oauth_status, oauth_api_call) proxy through this chain: agent → vitto-api → backend-api → provider API. Tokens never enter LLM context.

Options Considered:

Store tokens in vitto-api (closer to agent, less latency)
Store in backend-api with proxy (chosen — GDPR clean, secure)
Use Composio from day 1 (external dependency, less control)

💭 Reasoning

The dual-backend architecture demands clear data ownership. User OAuth tokens are user data — they belong in gograb-api alongside identity, billing, and preferences. This ensures GDPR deletion is one database operation. The proxy pattern (vitto-api → backend-api → Google) adds one HTTP hop (~15ms) but guarantees: (1) credentials never leave backend-api's process, (2) vitto-api can be compromised without credential exposure, (3) all OAuth operations are auditable at a single point. AES-256-GCM with per-token random IVs provides authenticated encryption — tampering is detectable. PKCE prevents authorization code interception even if the redirect URL is exposed.

📁 Files Involved

APIs/backend-api/src/app/auth/oauth/oauth.service.ts
APIs/backend-api/src/app/auth/oauth/oauth.controller.ts
APIs/backend-vitto-api/src/app/tools/plugins/oauth.plugin.ts
libs/libs-api/backend-core/src/lib/schemas/user-oauth-connection.schema.ts

🔗 Related

Decision ID: dev_1773855010649_rwxzhs5
Session: 234
Workspace: gspace1

Auto-generated by MCP Smart Consolidation