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

Documentation for Sessions

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

Date: 2026-03-30
Time: 17:02:22 UTC
Session: gspace1-290.3
Agent: angular
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should the Vitto Desktop app handle auth token delivery when deep links fail on macOS?

Task: S290: Server-side token exchange fallback for Vitto Desktop auth

🎯 Decision Made

Chosen:

Server-side token exchange: browser POSTs token to backend exchange endpoint, Tauri app polls GET endpoint every 2s. Both deep link and polling race via RxJS merge().pipe(take(1), timeout(120s)) — whichever delivers first wins, the other is cancelled.

Options Considered:

WebSocket push from backend to Tauri
Local HTTP server inside Tauri (VS Code pattern)
Polling-only (remove deep link)
Server-side token exchange racing with deep link

💭 Reasoning

ROOT CAUSE: Deep links (vitto://auth?token=...) have 5 documented failure modes on macOS: browser blocks custom scheme without user gesture, Gatekeeper blocks unsigned apps, Info.plist misconfiguration, app not in /Applications (tauri dev), and user dismisses macOS permission dialog. S288 improved the deep link path but these are inherent OS-level limitations. ALTERNATIVES: (1) WebSocket push — more complex, requires persistent connection, additional infra. (2) Local HTTP server in Tauri — VS Code does this but adds port conflict risk, firewall rules. (3) Polling-only (remove deep link) — loses the instant delivery when deep links work. CHOSEN: Additive polling fallback preserves deep link speed (instant when it works) while guaranteeing delivery via HTTPS polling (universally reliable). Industry standard: VS Code, Slack, 1Password all use server-side exchange. In-memory Map with 3-min TTL for MVP (single Railway instance), UUID v4 sid provides 122 bits of entropy for security. One-time read + TTL minimizes attack surface.

📁 Files Involved

APIs/backend-api/src/app/auth/desktop-exchange.controller.ts
libs/libs-ui/auth-ui/src/lib/services/desktop-auth-exchange.service.ts
apps/gograb-ai/src/app/pages/desktop-welcome/desktop-welcome.component.ts
apps/gograb-ai/src/app/pages/desktop-auth/desktop-auth.component.ts

🔗 Related

Decision ID: dev_1774890142704_zqxad90
Session: 290
Workspace: gspace1

Auto-generated by MCP Smart Consolidation