S290: Making Vitto Desktop Sign-In Reliable — Progress Report

Date: March 30, 2026 Session: 290 Depends on: S288 (deep link fixes) — no blocking dependency For: Team overview — written in plain language

Background: What S288 Fixed

In Session 288, we fixed the immediate problem: when users signed in via the browser, the credentials couldn't get back to the Vitto desktop app because modern browsers silently block certain types of links without a user click. S288 added a clickable "Open Vitto" button so the browser wouldn't block the handoff.

But the underlying fragility remained. The entire flow still depends on a "deep link" (vitto://auth?token=...) — a special link that the operating system routes from the browser to the desktop app. Deep links can fail for many reasons that are outside our control:

1. The browser blocks the link (even with a click, some browsers are more aggressive)
2. macOS Gatekeeper blocks unsigned/untrusted apps from receiving links
3. The app isn't installed in /Applications (common during development)
4. The user dismisses the macOS "Do you want to open Vitto?" dialog
5. The link type isn't registered properly in the app's configuration

Session 290 solves this permanently by adding a second, completely independent channel.

What We Built (Session 290)

The Solution: A Server-Side Backup Channel

We added a backup method for delivering sign-in credentials from the browser to the desktop app. Instead of relying solely on the special vitto:// link, the browser and desktop app now also communicate through our server:

HOW IT WORKS:

1. User clicks "Sign in with GoGrab" in Vitto desktop
2. Vitto creates a unique session ID (a random code)
3. Browser opens to the sign-in page (with the session ID in the URL)
4. User signs in normally

   Then TWO things happen at the same time:

   PATH A (existing, fast):
   Browser sends credentials via vitto:// link
   → macOS routes to Vitto app
   → Instant delivery (when it works)

   PATH B (new, reliable):
   Browser uploads credentials to our server (tagged with the session ID)
   Meanwhile, Vitto desktop checks the server every 2 seconds
   → Server delivers the credentials
   → Works every time (standard web request)

5. WHICHEVER PATH DELIVERS FIRST WINS
   The other path is automatically cancelled.

Why This Approach?

• If the deep link works (Path A): the user is signed in instantly — no delay
• If the deep link fails (Path B takes over): the user waits at most 2 seconds for the server to deliver the credentials
• No user action required either way — it's automatic and invisible
• Same approach used by VS Code, Slack, 1Password — industry-proven pattern

The deep link isn't removed — it's kept as the fast path. The server polling is the reliable backup. Together, they cover every failure scenario.

Timeline of Work

What Changed (For Non-Developers)

New: Server Exchange Endpoint

A new endpoint on the backend server that acts as a temporary "mailbox." The browser drops off the credentials, and the desktop app picks them up. The mailbox entry self-destructs after 3 minutes and can only be read once — so there's no security risk from credentials sitting on the server.

Updated: Browser Sign-In Page

After the user signs in, the browser now does two things instead of one:

1. Before: Only tried to open the vitto:// link (fragile)
2. Now: Also uploads credentials to the server mailbox AND tries the vitto:// link

If the session ID is missing from the URL (e.g., an older version of the desktop app), the page gracefully falls back to the old deep-link-only behavior. No breaking change.

Updated: Desktop Welcome Screen

When the user clicks "Sign in with GoGrab":

1. Before: Opened the browser and waited for the deep link (single path)
2. Now: Opens the browser and starts BOTH a deep link listener AND server polling (two parallel paths racing)

Whichever path delivers first wins. The 120-second timeout covers both paths — if neither delivers, the user sees a clear error message suggesting email or phone sign-in.

Bugs Found and Fixed During Review

Three issues were caught during code review before delivery:

1. Native Listener Could Leak Memory

Problem: When the sign-in race ended, the deep link listener inside the desktop app might not get properly cleaned up due to a timing issue with how the listener is initialized (it's an asynchronous operation). Fix: Changed the cleanup code to properly wait for initialization before cleaning up, guaranteeing no listener leaks regardless of timing.

2. Polling Could Silently Give Up

Problem: If the server never received the credentials (e.g., network error on the browser's upload), the polling would quietly stop after 60 attempts without showing any error message. The user would be stuck on "Waiting for browser..." forever. Fix: Added explicit error handling so when polling exhausts all attempts, it surfaces a clear timeout error that the user can see and act on.

3. Retry Could Be Permanently Blocked

Problem: A safety flag that prevents duplicate uploads was being set before the upload started. If the upload failed due to a network error, the flag was already set, permanently blocking any retry. Fix: Moved the flag to only be set after a successful upload, allowing retry on failure.

Security Considerations

Impact

• Users affected: All Vitto Desktop users who sign in via the "GoGrab" tab
• Improvement: Sign-in now works even when the deep link fails (browser blocking, unsigned app, dev mode)
• Risk: Low — all changes are additive. Deep link path is preserved unchanged. Server polling is a parallel fallback
• Email/Phone sign-in: Completely unaffected — those paths don't use deep links

What's Next

Files Changed Summary (For Reference)