S290: Server-Side Token Exchange for Desktop Auth — Technical Documentation

Session: 290.1 Branch: session-280-290 Date: 2026-03-30 Status: Implementation complete, pending build/test/deploy Depends on: S288 (deep link fixes) — no blocking dependency

Problem

Vitto Desktop auth relies entirely on macOS deep links (vitto://auth?token=...) to transfer tokens from the system browser back to the Tauri app. Deep links have 5 documented failure modes (browser gesture blocking, Gatekeeper, Info.plist misconfiguration, dev mode, user dismissal). S288 improved the deep link path but deep links remain inherently fragile on desktop. Production-grade desktop apps (VS Code, Slack, 1Password) all use server-side token exchange as primary or fallback mechanism.

Solution

Architecture

                         ┌─────────────────────────────────────┐
                         │     Backend API (port 3000)          │
                         │                                     │
                         │  POST /api/auth/desktop-exchange     │
                         │    → stores {sid, token, user}       │
                         │    → in-memory Map, 3-min TTL        │
                         │    → returns 201                     │
                         │                                     │
                         │  GET /api/auth/desktop-exchange?sid= │
                         │    → returns {token, user} if found  │
                         │    → 404 if not yet posted           │
                         │    → 410 if expired                  │
                         │    → deletes entry (one-time read)   │
                         └──────────┬──────────┬───────────────┘
                                    │          │
                    POST token      │          │  GET poll (every 2s)
                    after login     │          │  for up to 120s
                                    │          │
┌──────────────────────────┐   ┌────┴──────────┴────────────────┐
│  System Browser           │   │  Tauri Desktop App             │
│  /auth/desktop?sid={id}   │   │  DesktopWelcomeComponent       │
│                           │   │                                │
│  1. User logs in          │   │  1. Generate UUID v4 sid       │
│  2. depositTokenIfExchange│   │  2. Open browser with ?sid=    │
│     → POST to exchange    │   │  3. Start race:                │
│  3. Also try vitto:// link│   │     merge(deepLink$, poll$)    │
│  4. Show "close this tab" │   │       .pipe(take(1),           │
│                           │   │             timeout(120s))     │
└──────────────────────────┘   │  4. First to deliver wins       │
                                └────────────────────────────────┘

Race Resolution

// DesktopWelcomeComponent.startAuthRace()
const deepLink$ = createDeepLinkObservable();  // wraps Tauri event listener
const poll$ = exchangeService.pollForToken(sid);

merge(deepLink$, poll$).pipe(
  take(1),           // first emission wins, other is cancelled
  timeout(120_000),  // safety net if neither delivers
  takeUntil(destroy$),
).subscribe({
  next: handleAuthCallback,
  error: showTimeoutError,
});

Why merge + take(1) instead of race(): race() requires both sources to emit before selecting the winner. merge + take(1) takes the first emission from either source and immediately unsubscribes both. This is correct when one source (deep link) may never emit.

Implementation Details

1. DesktopExchangeController (NEW)

File: APIs/backend-api/src/app/auth/desktop-exchange.controller.ts

• POST /api/auth/desktop-exchange — deposits { sid, token, user }
• GET /api/auth/desktop-exchange?sid=... — retrieves and deletes entry
• In-memory Map<string, ExchangeEntry> with expiresAt: Date.now() + 180_000
• Lazy cleanup: iterates Map on each GET, deletes expired entries
• UUID v4 validation on sid parameter (regex with i flag)
• Rate limiting: POST 10/min, GET 60/min (per IP via ThrottlerGuard)
• @Public() — no auth required (the sid IS the secret — 122 bits of entropy)
• @UseGuards(ThrottlerGuard) — global rate limiting protection

Known limitation: In-memory store fails in multi-instance deployments. Migration path to Redis SETEX is trivial when horizontal scaling is needed.

2. DesktopAuthExchangeService (NEW)

File: libs/libs-ui/auth-ui/src/lib/services/desktop-auth-exchange.service.ts

@Injectable({ providedIn: 'root' })
export class DesktopAuthExchangeService {
  generateSessionId(): string           // crypto.randomUUID()
  postToken(sid, token, user): Obs<void> // POST to exchange endpoint
  pollForToken(sid): Obs<{token, user}>  // timer(0, 2000) + switchMap + throwIfEmpty
}

Key RxJS pipeline for pollForToken:

timer(0, 2000)
  → take(60)                    // 60 attempts = 120 seconds
  → switchMap(http.get)         // each tick fires a GET
    → catchError(404 → EMPTY)   // not yet available, keep polling
    → catchError(410 → throw)   // expired, stop immediately
    → catchError(other → EMPTY) // transient error, retry next tick
  → take(1)                    // complete after first 200
  → throwIfEmpty(→ throw)      // error if all 60 attempts exhausted

3. DesktopAuthPageComponent (MODIFIED)

File: apps/gograb-ai/src/app/pages/desktop-auth/desktop-auth.component.ts

Changes:

• Inject ActivatedRoute and DesktopAuthExchangeService
• Read sid from route.snapshot.queryParamMap.get('sid') in ngOnInit
• New depositTokenIfExchange() method: if sid present, POST token to exchange
• Called from both ngOnInit (pre-authenticated) and redirectToVitto() (post-login)
• exchangePosted signal prevents duplicate POSTs (set in next callback, not before subscribe)
• If sid is missing: falls back to deep-link-only (backward compatible with pre-S290 desktop builds)

4. DesktopWelcomeComponent (MODIFIED)

File: apps/gograb-ai/src/app/pages/desktop-welcome/desktop-welcome.component.ts

Changes:

• Inject DesktopAuthExchangeService
• signIn(): generates sid, appends ?sid={sid} to auth URL
• New createDeepLinkObservable(): wraps Tauri listen() into Observable with promise-based teardown
• New startAuthRace(sid): merges deep link Observable and polling, take(1) + timeout(120s)
• Removed: old listenForTauriAuthToken() for desktop (replaced by Observable in race)
• Removed: setTimeout for auth timeout (replaced by RxJS timeout operator)
• Removed: unlistenAuthToken field, clearAuthTimeout() method, authTimeoutId field (dead code)
• Preserved: mobile (Capacitor) listeners unchanged — mobile doesn't participate in the race

Bugs Fixed During Code Review

1. Tauri Listener Leak (TOCTOU Race)

Problem: Original createDeepLinkObservable stored the unlisten function in a local variable (let unlisten = null). The Observable teardown captured the variable by reference. If teardown ran between when listen() resolved and the .then() assigned to unlisten, the closure saw null and skipped cleanup. The Tauri native listener leaked.

Fix: Capture the entire promise chain as unlistenPromise. In teardown, call unlistenPromise.then(fn => fn()). The .catch() returns a no-op function so the promise always resolves to a callable.

2. Silent Poll Exhaustion

Problem: When all 60 poll attempts returned 404 (EMPTY), timer completed, switchMap propagated completion, take(1) completed without emitting. The merge didn't complete (deep link Observable never completes). UI stuck on "Waiting for browser..." with no error message and no recovery path.

Fix: Added throwIfEmpty(() => new Error('Token exchange timed out')) after take(1). This converts silent completion to an error that propagates through merge to the error handler in startAuthRace().

3. exchangePosted Blocking Retries

Problem: exchangePosted.set(true) was called before subscribe(). If the POST failed (network error), the flag was already set, permanently blocking retries.

Fix: Moved to next callback — flag is only set on successful POST (HTTP 201).

Files Changed

MCP Intelligence Captured

Edge Cases Handled

1. User closes browser before login — polling times out after 120s, shows clear error
2. Backend is down — POST fails, but deep link may still work. Error only if both fail
3. Multiple signIn() clicks — each generates new sid. Old sids expire in 3 minutes
4. Deep link AND poll both deliver — take(1) ensures only first is processed
5. Old desktop build (no sid) — browser page falls back to deep-link-only
6. Non-Tauri environment — createDeepLinkObservable catches import failure, returns no-op teardown, lets polling handle it
7. Network blip on POST — exchangePosted flag not set, retry is possible
8. Poll exhaustion with no response — throwIfEmpty surfaces error instead of silent completion

Testing Checklist

• Build Tauri app: tauri build --debug, install in /Applications
• Test GoGrab tab → browser opens → login → app receives token via polling
• Test with deep link working (verify race resolution — first wins)
• Test with deep link broken (unregister URL scheme) → verify polling alone works
• Test timeout: open browser, don't login, wait 120s → verify clean error
• Test concurrent: click "Sign in" twice rapidly → verify no double-login
• Test pre-authenticated: if already logged in on browser → token deposited + deep link shown
• Test backward compat: load /auth/desktop WITHOUT ?sid= → verify deep-link-only works
• Test email/phone tabs still work independently
• Verify backend logs: Token deposited for sid=..., Token retrieved for sid=...

Next Steps

1. Build & test on real Tauri app (all scenarios in checklist)
2. Deploy backend to Railway (new controller auto-registers, no config changes needed)
3. Monitor exchange endpoint usage in backend logs
4. Future: Redis migration when backend scales horizontally (change Map to Redis SETEX)
5. Future: Mobile polling — consider adding exchange fallback for Capacitor if deep link issues emerge