docs: note vue-tsc needs a full node_modules install

## What

Browser half of GTM-93 macOS web→desktop identity stitching: when the
desktop app opens the system browser at cloud login with
`?desktop_login_code=dlc_…`, the frontend redeems that code against the
cloud backend once a Firebase session exists — after **explicit user
approval**.

Reworked on top of the preserved-query `stripAfterCapture` capability
(#13465):

- The `DESKTOP_LOGIN` namespace opts into strip-on-capture: the code is
stashed and removed from the URL **before any navigation completes**, so
it never reaches history, `previousFullPath`, later guards, or telemetry
— the hand-rolled URL scrubbing this PR previously carried (raw-string
parser + three strip sites) is gone.
- `desktopLoginRedemption.ts` is a plain module with a single export,
`installDesktopLoginRedemption(router)`, installed once in `router.ts`'s
cloud block (replaces six per-view/composable trigger sites). Redemption
reads the code only from the stash: per-code state (approval + 2-attempt
transient budget, so a second code gets its own approval and budget),
approval dialog, `POST /api/auth/desktop-login-codes/redeem` with the
raw Firebase ID token (backend route is Firebase-JWT-only), 10s fetch
timeout.
- Triggers: `router.afterEach` (the cloud auth guard settles Firebase
init before navigations complete) plus a lazy watcher on
`authStore.currentUser` for sessions that appear without a navigation
(OAuth-resume error branch, dialog sign-in). One bounded in-page retry
(5s) guarantees an approved sign-in always ends in a success or failure
toast.
- Terminal rejections (400/403/404/409/410) drop the code with an error
toast; transient failures (401/5xx/timeout/network) retry once; budget
exhaustion now surfaces a failure toast instead of dying silently.

## Why

Windows stitches web→desktop at download time via installer stamping;
macOS DMGs can't be stamped, so we stitch at login. The browser is where
both halves meet: the existing `posthog.identify(uid)` merges the web
anon person into the Firebase uid, and the backend emits
`comfy.cloud.identity.login_attributed` (uid ↔ installation_id) at
redeem. The desktop app polls the backend and receives a one-time custom
token — no auth material posted to a desktop loopback server (the
concern that stalled #12983, which this supersedes).

## Security

- **Approval dialog before redeem** — redemption mints the desktop a
sign-in token for *your* account, so a lured click must not be enough
(device-code phishing mitigation). Cancel clears the stash and does
nothing.
- Only the opaque single-use code ever appears in a URL; the tracker
strips it on first sight, pre-navigation, and it is never logged.

## Testing

Vitest, driven through a real router (createRouter/createMemoryHistory,
no vue-router mocks) and the real preserved-query manager: capture/stash
lifecycle, approval gate (no fetch before approve; decline/dismiss
clears; per-code approval), Bearer/body shape, terminal-vs-transient
statuses, timeout abort, bounded in-page retry + failure toast on budget
exhaustion, per-code regressions (second code after
success/decline/exhaustion redeems independently), auth-watcher trigger
(session appearing without navigation), unauthenticated no-op, trigger
coalescing. Typecheck/lint/format clean.

Types are hand-written with a `TODO(@comfyorg/ingest-types)` — the
generated types land automatically once the cloud PR merges and the
type-gen workflow runs.

## Landing order

1. Cloud backend: https://github.com/Comfy-Org/cloud/pull/4736 (until it
ships, redemption never triggers — this PR is inert)
2. #13465 preserved-query strip-on-capture (base of this PR)
3. #13466 global-prompt FIFO queue (runtime dependency: the approval
confirm must settle even if another prompt is open)
4. **This PR**
5. Desktop (activates the flow):
https://github.com/Comfy-Org/Comfy-Desktop/pull/1222

GTM-93 · Supersedes #12983

---------

Co-authored-by: AustinMroz <austin@comfy.org>

AGENTS.md

@@ -55,6 +55,14 @@ This project uses **pnpm**. Always prefer scripts defined in `package.json` (e.g
 - `pnpm typecheck`: Vue TSC type checking
 - `pnpm storybook`: Start Storybook development server
 
+> **`vue-tsc` needs a full `node_modules` install.** `vue-tsc --noEmit` (what
+> `pnpm typecheck` runs) resolves types through pnpm's nested `.pnpm/` store
+> paths, so a partial, symlinked, or borrowed `node_modules` makes it report
+> ~1300 phantom errors against every `.vue` file — none from your diff — and the
+> typecheck can't be trusted. For a trustworthy typecheck, run `pnpm install` in
+> the checkout first, then `pnpm typecheck` (or `npx vue-tsc --noEmit`). Vitest
+> is unaffected: it doesn't do the `.pnpm` path resolution vue-tsc does.
+
 ## Development Workflow
 
 1. Make code changes

src/locales/en/main.json

@@ -2414,6 +2414,16 @@
       "tooltipLearnMore": "Learn more..."
     }
   },
+  "desktopLogin": {
+    "confirmSummary": "Approve desktop sign-in?",
+    "confirmMessage": "The ComfyUI desktop app is waiting to sign in with your account. Only continue if you just started signing in from the ComfyUI desktop app.",
+    "successSummary": "Signed in",
+    "successDetail": "You can return to the ComfyUI desktop app.",
+    "expiredSummary": "Desktop sign-in failed",
+    "expiredDetail": "The sign-in request expired or was already used. Start signing in again from the ComfyUI desktop app.",
+    "failedSummary": "Desktop sign-in failed",
+    "failedDetail": "Something went wrong completing the desktop sign-in. Start signing in again from the ComfyUI desktop app."
+  },
   "validation": {
     "invalidEmail": "Invalid email address",
     "required": "Required",

src/platform/cloud/onboarding/desktopLoginRedemption.test.ts

@@ -0,0 +1,618 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { reactive } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+
+/**
+ * Every test drives a real in-memory router and the real preserved-query
+ * manager: the tracker strips the code from the URL at capture time, so the
+ * stash is the only carrier, and redemption fires from router.afterEach, an
+ * auth watcher, and a delayed retry after a transient failure.
+ *
+ * The fake clock (installed for every test) keeps those retry timers from
+ * leaking into later tests: afterEach discards them with vi.useRealTimers().
+ */
+
+const mockConfirm = vi.hoisted(() => vi.fn())
+vi.mock('@/services/dialogService', () => ({
+  useDialogService: () => ({
+    confirm: mockConfirm
+  })
+}))
+
+const mockToastAdd = vi.hoisted(() => vi.fn())
+vi.mock('@/platform/updates/common/toastStore', () => ({
+  useToastStore: () => ({
+    add: mockToastAdd
+  })
+}))
+
+interface MockAuthStore {
+  currentUser: {
+    uid: string
+    getIdToken: (forceRefresh?: boolean) => Promise<string>
+  } | null
+  getIdToken: () => Promise<string>
+}
+
+const mockUserGetIdToken = vi.hoisted(() => vi.fn())
+const mockStoreGetIdToken = vi.hoisted(() => vi.fn())
+
+// Reactive so the module's watcher on currentUser fires without a navigation.
+// The mock factory is cached across vi.resetModules(), so it reads a holder
+// refilled per test; watchers leaked by earlier module generations stay
+// subscribed to earlier stores and remain dormant.
+const authStoreHolder = vi.hoisted(() => ({
+  store: null as MockAuthStore | null
+}))
+vi.mock('@/stores/authStore', () => ({
+  useAuthStore: () => authStoreHolder.store
+}))
+
+vi.mock('@/i18n', () => ({
+  t: (key: string) => key
+}))
+
+vi.mock('@/scripts/api', () => ({
+  api: {
+    apiURL: (path: string) => `/api${path}`
+  }
+}))
+
+const VALID_CODE = `dlc_${'A'.repeat(43)}`
+const SECOND_CODE = `dlc_${'B'.repeat(43)}`
+const REDEEM_URL = '/api/auth/desktop-login-codes/redeem'
+const NAMESPACE = 'desktop_login'
+const STORAGE_KEY = 'Comfy.PreservedQuery.desktop_login'
+const RETRY_DELAY_MS = 5_000
+
+const mockFetch = vi.fn()
+
+let mockAuthStore: MockAuthStore
+
+function okResponse() {
+  return new Response(JSON.stringify({ status: 'redeemed' }), { status: 200 })
+}
+
+function expectedFetchOptions(code: string) {
+  return {
+    method: 'POST',
+    headers: {
+      Authorization: 'Bearer firebase-id-token',
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ code }),
+    signal: expect.any(AbortSignal)
+  }
+}
+
+// The triggers fire-and-forget the redemption; a zero-length advance of the
+// fake clock yields the event loop so the whole mocked promise chain settles.
+async function flushRedemption() {
+  await vi.advanceTimersByTimeAsync(0)
+}
+
+// vi.resetModules() also resets the preserved-query manager's in-memory map,
+// so the manager must be imported alongside the module under test.
+async function setup() {
+  const { installDesktopLoginRedemption } =
+    await import('./desktopLoginRedemption')
+  const { capturePreservedQuery, getPreservedQueryParam } =
+    await import('@/platform/navigation/preservedQueryManager')
+
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [{ path: '/:pathMatch(.*)*', component: { template: '<div />' } }]
+  })
+  installDesktopLoginRedemption(router)
+
+  let navigationCount = 0
+  const trigger = async () => {
+    await router.push(`/trigger-${navigationCount++}`)
+    await flushRedemption()
+  }
+
+  return {
+    router,
+    trigger,
+    seedStash: (code: string) =>
+      capturePreservedQuery(NAMESPACE, { desktop_login_code: code }, [
+        'desktop_login_code'
+      ]),
+    stashedCode: () => getPreservedQueryParam(NAMESPACE, 'desktop_login_code')
+  }
+}
+
+describe('installDesktopLoginRedemption', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+    sessionStorage.clear()
+    vi.stubGlobal('fetch', mockFetch)
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    mockFetch.mockReset()
+    mockConfirm.mockResolvedValue(true)
+    mockUserGetIdToken.mockResolvedValue('firebase-id-token')
+    mockAuthStore = reactive({
+      currentUser: {
+        uid: 'user-1',
+        getIdToken: mockUserGetIdToken
+      },
+      getIdToken: mockStoreGetIdToken
+    })
+    authStoreHolder.store = mockAuthStore
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('does nothing on navigation when no code is stashed', async () => {
+    const { trigger } = await setup()
+
+    await trigger()
+
+    expect(mockConfirm).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
+    expect(mockToastAdd).not.toHaveBeenCalled()
+  })
+
+  it('redeems a stashed code once on navigation with the Firebase bearer token after approval', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockResolvedValue(okResponse())
+
+    await trigger()
+
+    expect(mockConfirm).toHaveBeenCalledTimes(1)
+    expect(mockConfirm).toHaveBeenCalledWith({
+      title: 'desktopLogin.confirmSummary',
+      message: 'desktopLogin.confirmMessage'
+    })
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledWith(
+      REDEEM_URL,
+      expectedFetchOptions(VALID_CODE)
+    )
+    expect(stashedCode()).toBeUndefined()
+    expect(mockToastAdd).toHaveBeenCalledWith({
+      severity: 'success',
+      summary: 'desktopLogin.successSummary',
+      detail: 'desktopLogin.successDetail',
+      life: 4000
+    })
+  })
+
+  it('does not fetch before the user approves the confirmation dialog', async () => {
+    const { trigger, seedStash } = await setup()
+    seedStash(VALID_CODE)
+    let approve!: (value: boolean) => void
+    mockConfirm.mockReturnValue(
+      new Promise<boolean>((resolve) => {
+        approve = resolve
+      })
+    )
+    mockFetch.mockResolvedValue(okResponse())
+
+    await trigger()
+    await vi.waitFor(() => expect(mockConfirm).toHaveBeenCalledTimes(1))
+    expect(mockFetch).not.toHaveBeenCalled()
+
+    approve(true)
+    await flushRedemption()
+
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+  })
+
+  it.for([
+    ['declines', false],
+    ['dismisses', null]
+  ] as const)(
+    'clears the stash without a request or toast when the user %s the dialog',
+    async ([_label, confirmResult]) => {
+      const { trigger, seedStash, stashedCode } = await setup()
+      seedStash(VALID_CODE)
+      mockConfirm.mockResolvedValue(confirmResult)
+
+      await trigger()
+
+      expect(mockFetch).not.toHaveBeenCalled()
+      expect(stashedCode()).toBeUndefined()
+      expect(mockToastAdd).not.toHaveBeenCalled()
+
+      // Declining is final for that code: re-capturing it never re-prompts.
+      seedStash(VALID_CODE)
+      await trigger()
+
+      expect(mockConfirm).toHaveBeenCalledTimes(1)
+      expect(mockFetch).not.toHaveBeenCalled()
+      expect(stashedCode()).toBeUndefined()
+    }
+  )
+
+  it('asks for approval at most once per code across transient retries', async () => {
+    const { trigger, seedStash } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockResolvedValue(new Response(null, { status: 500 }))
+
+    await trigger()
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+
+    await vi.advanceTimersByTimeAsync(RETRY_DELAY_MS)
+
+    expect(mockConfirm).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('redeems a code hydrated lazily from sessionStorage', async () => {
+    const { trigger } = await setup()
+    sessionStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify({ desktop_login_code: VALID_CODE })
+    )
+    mockFetch.mockResolvedValue(okResponse())
+
+    await trigger()
+
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledWith(
+      REDEEM_URL,
+      expectedFetchOptions(VALID_CODE)
+    )
+  })
+
+  it('does not redeem or prompt again after a successful redemption', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockResolvedValue(okResponse())
+
+    await trigger()
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+
+    // A later navigation re-captures the already-redeemed code.
+    seedStash(VALID_CODE)
+    await trigger()
+
+    expect(mockConfirm).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it.for([400, 403, 404, 409, 410])(
+    'clears the stash, shows an error toast, and never retries on %s',
+    async (status) => {
+      const { trigger, seedStash, stashedCode } = await setup()
+      seedStash(VALID_CODE)
+      mockFetch.mockResolvedValue(new Response(null, { status }))
+
+      await trigger()
+
+      expect(stashedCode()).toBeUndefined()
+      expect(mockToastAdd).toHaveBeenCalledWith({
+        severity: 'error',
+        summary: 'desktopLogin.expiredSummary',
+        detail: 'desktopLogin.expiredDetail',
+        life: 6000
+      })
+    }
+  )
+
+  it.for([401, 500])(
+    'keeps the stash on %s for the scheduled retry without a toast',
+    async (status) => {
+      const { trigger, seedStash, stashedCode } = await setup()
+      seedStash(VALID_CODE)
+      mockFetch.mockResolvedValue(new Response(null, { status }))
+
+      await trigger()
+
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+      expect(stashedCode()).toBe(VALID_CODE)
+      expect(mockToastAdd).not.toHaveBeenCalled()
+    }
+  )
+
+  it('retries once by itself, then clears the stash and shows an error toast when the budget is spent', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockResolvedValue(new Response(null, { status: 500 }))
+
+    await trigger()
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(stashedCode()).toBe(VALID_CODE)
+    expect(mockToastAdd).not.toHaveBeenCalled()
+
+    await vi.advanceTimersByTimeAsync(RETRY_DELAY_MS)
+
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+    expect(stashedCode()).toBeUndefined()
+    expect(mockToastAdd).toHaveBeenCalledWith({
+      severity: 'error',
+      summary: 'desktopLogin.failedSummary',
+      detail: 'desktopLogin.failedDetail',
+      life: 6000
+    })
+  })
+
+  it('forces a token refresh on the retry after a 401', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch
+      .mockResolvedValueOnce(new Response(null, { status: 401 }))
+      .mockResolvedValueOnce(okResponse())
+
+    await trigger()
+    expect(mockUserGetIdToken).toHaveBeenLastCalledWith(false)
+
+    await vi.advanceTimersByTimeAsync(RETRY_DELAY_MS)
+
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+    expect(mockUserGetIdToken).toHaveBeenLastCalledWith(true)
+    expect(stashedCode()).toBeUndefined()
+    expect(mockToastAdd).toHaveBeenCalledWith(
+      expect.objectContaining({ severity: 'success' })
+    )
+  })
+
+  it('passes a timeout signal and treats an aborted request as transient', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockRejectedValue(
+      new DOMException('The operation timed out.', 'TimeoutError')
+    )
+
+    await trigger()
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      REDEEM_URL,
+      expectedFetchOptions(VALID_CODE)
+    )
+    expect(stashedCode()).toBe(VALID_CODE)
+    expect(mockToastAdd).not.toHaveBeenCalled()
+  })
+
+  it('treats an id token failure as transient without a toast', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockUserGetIdToken.mockRejectedValue(new Error('firebase unavailable'))
+
+    await trigger()
+
+    expect(mockFetch).not.toHaveBeenCalled()
+    // authStore.getIdToken surfaces failures through a modal error dialog,
+    // which this background flow must never trigger.
+    expect(mockStoreGetIdToken).not.toHaveBeenCalled()
+    expect(stashedCode()).toBe(VALID_CODE)
+    expect(mockToastAdd).not.toHaveBeenCalled()
+  })
+
+  it('clears the stash without a dialog or request for a malformed code', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash('not-a-desktop-login-code')
+
+    await trigger()
+
+    expect(mockConfirm).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it('contains an unexpected internal error instead of rejecting', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { trigger, seedStash } = await setup()
+    seedStash(VALID_CODE)
+    mockConfirm.mockRejectedValue(new Error('dialog exploded'))
+
+    await expect(trigger()).resolves.toBeUndefined()
+
+    expect(consoleError).toHaveBeenCalledWith(
+      '[DesktopLoginRedemption] Redemption failed:',
+      expect.any(Error)
+    )
+    expect(mockToastAdd).not.toHaveBeenCalled()
+  })
+
+  it('keeps the stash while unauthenticated and redeems via the auth watcher once a session appears', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockAuthStore.currentUser = null
+    mockFetch.mockResolvedValue(okResponse())
+
+    // The first completed navigation installs the watcher; without a session
+    // nothing redeems and the stash is kept.
+    await trigger()
+    expect(mockConfirm).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
+    expect(stashedCode()).toBe(VALID_CODE)
+
+    // A session appearing without any further navigation redeems via the
+    // watcher.
+    mockAuthStore.currentUser = {
+      uid: 'user-1',
+      getIdToken: mockUserGetIdToken
+    }
+
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1))
+    expect(mockFetch).toHaveBeenCalledWith(
+      REDEEM_URL,
+      expectedFetchOptions(VALID_CODE)
+    )
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it.for([
+    ['succeeded', () => mockFetch.mockResolvedValueOnce(okResponse())],
+    ['was declined', () => mockConfirm.mockResolvedValueOnce(false)]
+  ] as const)(
+    'gives a second code its own dialog and request after the first code %s',
+    async ([_label, arrangeFirstOutcome]) => {
+      const { trigger, seedStash, stashedCode } = await setup()
+      seedStash(VALID_CODE)
+      arrangeFirstOutcome()
+
+      await trigger()
+      expect(mockConfirm).toHaveBeenCalledTimes(1)
+
+      seedStash(SECOND_CODE)
+      mockFetch.mockResolvedValue(okResponse())
+      await trigger()
+
+      expect(mockConfirm).toHaveBeenCalledTimes(2)
+      expect(mockFetch).toHaveBeenLastCalledWith(
+        REDEEM_URL,
+        expect.objectContaining({ body: JSON.stringify({ code: SECOND_CODE }) })
+      )
+      expect(stashedCode()).toBeUndefined()
+    }
+  )
+
+  it('gives a second code a fresh attempt budget after the first code exhausted its own', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch.mockResolvedValue(new Response(null, { status: 500 }))
+
+    await trigger()
+    await vi.advanceTimersByTimeAsync(RETRY_DELAY_MS)
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+    expect(stashedCode()).toBeUndefined()
+
+    seedStash(SECOND_CODE)
+    await trigger()
+    expect(mockFetch).toHaveBeenCalledTimes(3)
+    expect(stashedCode()).toBe(SECOND_CODE)
+
+    await vi.advanceTimersByTimeAsync(RETRY_DELAY_MS)
+    expect(mockFetch).toHaveBeenCalledTimes(4)
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it('re-asks for approval when the account changes after approval and redeems with the new account token', async () => {
+    const { trigger, seedStash, stashedCode } = await setup()
+    seedStash(VALID_CODE)
+    mockFetch
+      .mockResolvedValueOnce(new Response(null, { status: 500 }))
+      .mockResolvedValueOnce(okResponse())
+
+    // user-1 approves; the redeem fails transiently, keeping the code stashed.
+    await trigger()
+    expect(mockConfirm).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(stashedCode()).toBe(VALID_CODE)
+
+    // The session changes to user-2 before the retry: user-1's approval must
+    // not authorize redeeming with user-2's token.
+    mockAuthStore.currentUser = {
+      uid: 'user-2',
+      getIdToken: vi.fn().mockResolvedValue('second-user-token')
+    }
+
+    await vi.waitFor(() => expect(mockConfirm).toHaveBeenCalledTimes(2))
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(2))
+    expect(mockFetch).toHaveBeenLastCalledWith(
+      REDEEM_URL,
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer second-user-token'
+        })
+      })
+    )
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it('re-prompts and redeems under the new account when the session changes while the approval dialog is open', async () => {
+    const { seedStash, stashedCode, trigger } = await setup()
+    seedStash(VALID_CODE)
+    let approve!: (value: boolean) => void
+    mockConfirm.mockReturnValueOnce(
+      new Promise<boolean>((resolve) => {
+        approve = resolve
+      })
+    )
+    mockFetch.mockResolvedValue(okResponse())
+
+    await trigger()
+    await vi.waitFor(() => expect(mockConfirm).toHaveBeenCalledTimes(1))
+
+    // The session swaps to user-2 while user-1's dialog is open: the stale
+    // approval must not redeem, and the raced auth trigger is replayed to
+    // re-prompt under user-2 without another navigation.
+    const secondUser = {
+      uid: 'user-2',
+      getIdToken: vi.fn().mockResolvedValue('second-user-token')
+    }
+    mockAuthStore.currentUser = secondUser
+    await flushRedemption()
+    approve(true)
+    await flushRedemption()
+
+    await vi.waitFor(() => expect(mockConfirm).toHaveBeenCalledTimes(2))
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1))
+    expect(mockFetch).toHaveBeenCalledWith(
+      REDEEM_URL,
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer second-user-token'
+        })
+      })
+    )
+    expect(stashedCode()).toBeUndefined()
+  })
+
+  it.for([
+    ['succeeds', () => okResponse()],
+    ['fails terminally', () => new Response(null, { status: 404 })]
+  ] as const)(
+    'processes a newer code stashed mid-flight after the older redemption %s',
+    async ([_label, firstResponse]) => {
+      const { trigger, seedStash, stashedCode } = await setup()
+      seedStash(VALID_CODE)
+      let resolveFirstFetch!: (response: Response) => void
+      mockFetch.mockReturnValueOnce(
+        new Promise<Response>((resolve) => {
+          resolveFirstFetch = resolve
+        })
+      )
+
+      await trigger()
+      await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1))
+
+      // A second code arrives while the first redemption is in flight; it
+      // must survive the first's settlement and be processed right after.
+      seedStash(SECOND_CODE)
+      mockFetch.mockResolvedValue(okResponse())
+      resolveFirstFetch(firstResponse())
+
+      await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(2))
+      expect(mockConfirm).toHaveBeenCalledTimes(2)
+      expect(mockFetch).toHaveBeenLastCalledWith(
+        REDEEM_URL,
+        expect.objectContaining({ body: JSON.stringify({ code: SECOND_CODE }) })
+      )
+      expect(stashedCode()).toBeUndefined()
+    }
+  )
+
+  it('coalesces concurrent triggers into one dialog and one request', async () => {
+    const { router, seedStash } = await setup()
+    seedStash(VALID_CODE)
+    let approve!: (value: boolean) => void
+    mockConfirm.mockReturnValue(
+      new Promise<boolean>((resolve) => {
+        approve = resolve
+      })
+    )
+    mockFetch.mockResolvedValue(okResponse())
+
+    await router.push('/burst-1')
+    await router.push('/burst-2')
+    await vi.waitFor(() => expect(mockConfirm).toHaveBeenCalledTimes(1))
+
+    approve(true)
+    await flushRedemption()
+
+    expect(mockConfirm).toHaveBeenCalledTimes(1)
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+  })
+})

src/platform/cloud/onboarding/desktopLoginRedemption.ts

@@ -0,0 +1,263 @@
+import { watch } from 'vue'
+import type { Router } from 'vue-router'
+
+import { t } from '@/i18n'
+import {
+  clearPreservedQuery,
+  getPreservedQueryParam
+} from '@/platform/navigation/preservedQueryManager'
+import { PRESERVED_QUERY_NAMESPACES } from '@/platform/navigation/preservedQueryNamespaces'
+import { useToastStore } from '@/platform/updates/common/toastStore'
+import { api } from '@/scripts/api'
+import { useDialogService } from '@/services/dialogService'
+import { useAuthStore } from '@/stores/authStore'
+
+const NAMESPACE = PRESERVED_QUERY_NAMESPACES.DESKTOP_LOGIN
+const DESKTOP_LOGIN_CODE_KEY = 'desktop_login_code'
+
+// The backend issues "dlc_" + 43 base64url chars; bounds are loose so the
+// backend stays the authority on exact code length.
+const DESKTOP_LOGIN_CODE_PATTERN = /^dlc_[A-Za-z0-9_-]{20,256}$/
+
+// Statuses that mean the desktop app must start a fresh sign-in, so the code
+// is dropped. 401 stays transient: the session may still be settling.
+const TERMINAL_REDEEM_STATUSES = new Set([400, 403, 404, 409, 410])
+
+// One delayed in-page retry, so an approved sign-in always reaches a success
+// or failure toast without ever looping within a page load.
+const MAX_REDEEM_ATTEMPTS = 2
+const RETRY_DELAY_MS = 5_000
+
+// Abort the redeem request if the backend hangs; treated as transient.
+const REDEEM_TIMEOUT_MS = 10_000
+
+interface CodeRedemptionState {
+  attempts: number
+  approvedUserUid: string | null
+  settled: boolean
+  forceTokenRefresh: boolean
+}
+
+// Keyed by code so a different code arriving later gets its own approval and
+// attempt budget, while retries of the same code reuse both.
+const codeStates = new Map<string, CodeRedemptionState>()
+
+// Coalesces concurrent triggers into one drain; a trigger arriving mid-drain
+// (e.g. the auth watcher firing while the dialog is open) is replayed as one
+// more pass instead of being dropped.
+let draining = false
+let retriggerRequested = false
+
+let authWatcherInstalled = false
+
+function getCodeState(code: string): CodeRedemptionState {
+  const existing = codeStates.get(code)
+  if (existing) return existing
+  const fresh = {
+    attempts: 0,
+    approvedUserUid: null,
+    settled: false,
+    forceTokenRefresh: false
+  }
+  codeStates.set(code, fresh)
+  return fresh
+}
+
+// A newer code can be stashed while an older one is mid-redemption; settling
+// the older one must not wipe it.
+function clearStashIfHolds(code: string): void {
+  if (getPreservedQueryParam(NAMESPACE, DESKTOP_LOGIN_CODE_KEY) === code) {
+    clearPreservedQuery(NAMESPACE)
+  }
+}
+
+function settle(code: string, state: CodeRedemptionState): void {
+  state.settled = true
+  clearStashIfHolds(code)
+}
+
+function handleTransientFailure(
+  code: string,
+  state: CodeRedemptionState,
+  reason: string
+): void {
+  console.warn(`[DesktopLoginRedemption] Redeem request failed: ${reason}`)
+  if (state.attempts < MAX_REDEEM_ATTEMPTS) {
+    // attempts only increments, so this branch runs at most once per code
+    // and cannot stack retry timers.
+    setTimeout(() => {
+      void redeemPendingDesktopLoginCode()
+    }, RETRY_DELAY_MS)
+    return
+  }
+  // Budget spent: drop the code and tell the user instead of failing silently.
+  settle(code, state)
+  useToastStore().add({
+    severity: 'error',
+    summary: t('desktopLogin.failedSummary'),
+    detail: t('desktopLogin.failedDetail'),
+    life: 6000
+  })
+}
+
+// Explicit approval defeats device-code phishing: a lured click on a leaked
+// link must not bind the victim's session to an attacker's desktop app.
+// Approval is per code *and* account.
+async function confirmRedemption(
+  state: CodeRedemptionState,
+  uid: string
+): Promise<boolean> {
+  if (state.approvedUserUid === uid) return true
+  const confirmed = await useDialogService().confirm({
+    title: t('desktopLogin.confirmSummary'),
+    message: t('desktopLogin.confirmMessage')
+  })
+  if (confirmed !== true) return false
+  state.approvedUserUid = uid
+  return true
+}
+
+async function redeemCode(code: string): Promise<void> {
+  const state = getCodeState(code)
+  if (state.settled) {
+    // A later navigation can re-capture an already-settled code; drop it.
+    clearStashIfHolds(code)
+    return
+  }
+
+  // No session yet (e.g. code captured on the login page): keep the stash and
+  // let a post-login trigger redeem it.
+  const user = useAuthStore().currentUser
+  if (!user) return
+
+  if (!(await confirmRedemption(state, user.uid))) {
+    // Declined/dismissed: drop the code without an error.
+    settle(code, state)
+    return
+  }
+
+  // Approval binds the code to one account: if the session changed while the
+  // dialog was open, keep the code stashed and let the (replayed) auth-change
+  // trigger re-prompt under the now-current account.
+  const approvedUser = useAuthStore().currentUser
+  if (!approvedUser || approvedUser.uid !== state.approvedUserUid) return
+
+  state.attempts++
+
+  // Token comes straight from the Firebase user: authStore.getIdToken()
+  // surfaces failures through a modal dialog this background flow must avoid.
+  let idToken: string
+  try {
+    idToken = await approvedUser.getIdToken(state.forceTokenRefresh)
+  } catch {
+    handleTransientFailure(code, state, 'could not get id token')
+    return
+  }
+
+  let response: Response
+  try {
+    response = await fetch(api.apiURL('/auth/desktop-login-codes/redeem'), {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${idToken}`,
+        'Content-Type': 'application/json'
+      },
+      // TODO(@comfyorg/ingest-types): type the payload with the generated
+      // request type once the desktop-login-codes openapi addition propagates.
+      body: JSON.stringify({ code }),
+      signal: AbortSignal.timeout(REDEEM_TIMEOUT_MS)
+    })
+  } catch (error) {
+    handleTransientFailure(
+      code,
+      state,
+      error instanceof Error && error.name === 'TimeoutError'
+        ? 'request timed out'
+        : 'network error'
+    )
+    return
+  }
+
+  if (response.ok) {
+    settle(code, state)
+    useToastStore().add({
+      severity: 'success',
+      summary: t('desktopLogin.successSummary'),
+      detail: t('desktopLogin.successDetail'),
+      life: 4000
+    })
+    return
+  }
+
+  if (TERMINAL_REDEEM_STATUSES.has(response.status)) {
+    settle(code, state)
+    useToastStore().add({
+      severity: 'error',
+      summary: t('desktopLogin.expiredSummary'),
+      detail: t('desktopLogin.expiredDetail'),
+      life: 6000
+    })
+    return
+  }
+
+  // A 401 usually means a stale cached id token; mint a fresh one on retry.
+  if (response.status === 401) state.forceTokenRefresh = true
+  handleTransientFailure(code, state, `status ${response.status}`)
+}
+
+async function redeemPendingDesktopLoginCode(): Promise<void> {
+  // Never rejects: the triggers fire-and-forget this.
+  if (draining) {
+    retriggerRequested = true
+    return
+  }
+  draining = true
+  try {
+    do {
+      retriggerRequested = false
+      const code = getPreservedQueryParam(NAMESPACE, DESKTOP_LOGIN_CODE_KEY)
+      if (!code) continue
+      if (!DESKTOP_LOGIN_CODE_PATTERN.test(code)) {
+        clearPreservedQuery(NAMESPACE)
+        continue
+      }
+      await redeemCode(code)
+      if (code !== getPreservedQueryParam(NAMESPACE, DESKTOP_LOGIN_CODE_KEY))
+        retriggerRequested = true
+    } while (retriggerRequested)
+  } catch (error) {
+    console.error('[DesktopLoginRedemption] Redemption failed:', error)
+  } finally {
+    draining = false
+  }
+}
+
+function installAuthWatcherOnce(): void {
+  if (authWatcherInstalled) return
+  authWatcherInstalled = true
+  // A session can appear without a navigation (e.g. dialog-based sign-in).
+  // Installed lazily because pinia is not active when router.ts evaluates.
+  watch(
+    () => useAuthStore().currentUser,
+    () => {
+      void redeemPendingDesktopLoginCode()
+    }
+  )
+}
+
+/**
+ * Redeems desktop login codes (`?desktop_login_code=dlc_...`).
+ *
+ * The desktop app opens the browser with an opaque one-time code and polls
+ * the cloud backend; redeeming the code from a signed-in browser session,
+ * with the user's approval, releases a one-time custom token to that poll
+ * and signs the desktop app in. The preserved-query tracker (configured in
+ * router.ts) strips the code from the URL at capture time, so the stash is
+ * the only place it lives.
+ */
+export function installDesktopLoginRedemption(router: Router): void {
+  router.afterEach(() => {
+    installAuthWatcherOnce()
+    void redeemPendingDesktopLoginCode()
+  })
+}

src/platform/navigation/preservedQueryNamespaces.ts

@@ -5,5 +5,6 @@ export const PRESERVED_QUERY_NAMESPACES = {
   SHARE_AUTH: 'share_auth',
   CREATE_WORKSPACE: 'create_workspace',
   OAUTH: 'oauth',
-  PRICING: 'pricing'
+  PRICING: 'pricing',
+  DESKTOP_LOGIN: 'desktop_login'
 } as const

src/router.ts

@@ -16,6 +16,7 @@ import { useUserStore } from '@/stores/userStore'
 import LayoutDefault from '@/views/layouts/LayoutDefault.vue'
 
 import { captureOAuthRequestId } from '@/platform/cloud/oauth/oauthState'
+import { installDesktopLoginRedemption } from '@/platform/cloud/onboarding/desktopLoginRedemption'
 import { installPreservedQueryTracker } from '@/platform/navigation/preservedQueryTracker'
 import { PRESERVED_QUERY_NAMESPACES } from '@/platform/navigation/preservedQueryNamespaces'
 import { preserveLoggedOutShareAuthAttribution } from '@/platform/workflow/sharing/utils/shareAuthAttribution'
@@ -118,6 +119,11 @@ installPreservedQueryTracker(router, [
   {
     namespace: PRESERVED_QUERY_NAMESPACES.PRICING,
     keys: ['pricing']
+  },
+  {
+    namespace: PRESERVED_QUERY_NAMESPACES.DESKTOP_LOGIN,
+    keys: ['desktop_login_code'],
+    stripAfterCapture: true
   }
 ])
 
@@ -249,6 +255,8 @@ if (isCloud) {
     // User is logged in and accessing protected route
     return next()
   })
+
+  installDesktopLoginRedemption(router)
 }
 
 export default router