Architecture: How should Vitto Desktop handle auth token delivery from the...

Documentation for Sessions

🏗️ Architecture: How should Vitto Desktop handle auth token delivery from the...

Date: 2026-03-30
Time: 16:29:24 UTC
Session: gspace1-283.11
Agent: angular
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should Vitto Desktop handle auth token delivery from the system browser when deep links are unreliable?

Task: S288: Architecture decision for robust desktop auth token delivery

🎯 Decision Made

Chosen:

Two-spec approach: Spec A (S288) fixes the deep link path immediately. Spec B (S290) adds a server-side token exchange as a parallel fallback — desktop generates a sessionId, browser POSTs token to backend keyed by sessionId, desktop polls backend. RxJS race() resolves whichever arrives first. Deep link remains as fast-path enhancement.

Options Considered:

Fix deep links only (fragile, single transport)
Replace deep links entirely with polling (loses instant-delivery benefit)
Two-transport parallel approach: deep link + server polling racing via RxJS
Add local HTTP server in Tauri like VS Code (port conflicts, firewall complexity)

💭 Reasoning

Deep links have 5+ failure modes on macOS (browser blocking without user gesture, Gatekeeper, Info.plist misconfiguration, app not in /Applications, user dismissing OS permission dialog). Production desktop apps (VS Code, Slack, 1Password) all use server-side exchange as primary or fallback. Implementing ONLY deep link fixes (Spec A) addresses the most likely immediate cause but leaves the system fragile. The server-side exchange (Spec B) is a fundamentally more reliable transport layer that works in tauri dev mode, requires no OS-level URL scheme registration, and has no browser gesture requirements. The two specs are independent — Spec B can start before Spec A ships. The backend endpoint uses an in-memory Map with 3-min TTL (adequate for single Railway instance; Redis migration trivial if needed later). UUID v4 sessionId provides 122 bits of entropy — brute force infeasible with rate limiting.

📁 Files Involved

docs/english/Plans/S290-desktop-auth-server-side-token-exchange.md
apps/gograb-ai/src/app/pages/desktop-welcome/desktop-welcome.component.ts
libs/libs-ui/auth-ui/src/lib/services/desktop-oauth.service.ts

🔗 Related

Decision ID: dev_1774888164518_jocsbng
Session: 283
Workspace: gspace1

Auto-generated by MCP Smart Consolidation