feat(bridge): expose per-install id to the hosted frontend

packages/comfyui-desktop-bridge-types/comfyDesktopBridge.d.ts

@@ -168,6 +168,13 @@ export interface ComfyDesktop2Bridge {
   /** Reports whether the backend server is cloud/remote, not the user's location.
    *  Optional: desktop builds predating it are still in the wild. */
   isRemote?(): boolean
+  /** Returns the per-installation id: a non-PII, stable-per-machine value
+   *  (`SHA-256(machine_id + salt)`, see main/lib/deviceId). The hosted
+   *  frontend sends it to cloud as the `X-Comfy-Install-Id` header so cloud
+   *  can attribute requests to a Desktop install. Not an identity/secret.
+   *  Undefined outside cloud-hosted pages or when the id is not
+   *  machine-derived. Absent on Desktop builds predating it. */
+  getInstallId?(): string | undefined
   openTerminal?: () => Promise<boolean>
   openMcpSetup?: () => Promise<boolean>
   /** Opens a model provider access page in the hosted frontend's browser session.

packages/comfyui-desktop-bridge-types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfyorg/comfyui-desktop-bridge-types",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript definitions for the Comfy Desktop hosted frontend bridge",
   "type": "module",
   "main": "./index.js",

src/main/lib/ipc/registerDownloadHandlers.test.ts

@@ -6,7 +6,9 @@ const mocks = vi.hoisted(() => ({
   handle: vi.fn(),
   on: vi.fn(),
   openModelAccessPageWindow: vi.fn(),
-  showItemInFolder: vi.fn()
+  showItemInFolder: vi.fn(),
+  getDeviceId: vi.fn(),
+  getIdClass: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -35,6 +37,11 @@ vi.mock('../modelAccessPage', () => ({
   openModelAccessPageWindow: mocks.openModelAccessPageWindow
 }))
 
+vi.mock('../deviceId', () => ({
+  getDeviceId: mocks.getDeviceId,
+  getIdClass: mocks.getIdClass
+}))
+
 import { registerDownloadHandlers } from './registerDownloadHandlers'
 
 type IpcHandler = (
@@ -66,3 +73,95 @@ describe('registerDownloadHandlers model access bridge', () => {
     expect(mocks.openModelAccessPageWindow).toHaveBeenCalledWith(sender, url)
   })
 })
+
+type SyncIpcEvent = { sender: unknown; senderFrame: unknown; returnValue?: unknown }
+
+const CLOUD_URL = 'https://cloud.comfy.org/'
+
+function onHandler(channel: string): (event: SyncIpcEvent) => void {
+  const call = mocks.on.mock.calls.find(([name]) => name === channel)
+  expect(call).toBeDefined()
+  return call![1] as (event: SyncIpcEvent) => void
+}
+
+type FrameShape = 'main' | 'subframe' | 'missing'
+
+function requestInstallId({ url = CLOUD_URL, frame = 'main' as FrameShape } = {}): unknown {
+  const mainFrame = { processId: 3, routingId: 1, url }
+  const senderFrames = {
+    main: { processId: 3, routingId: 1, url },
+    subframe: { processId: 3, routingId: 2, url },
+    missing: null
+  }
+  const event: SyncIpcEvent = {
+    sender: { id: 7, mainFrame },
+    senderFrame: senderFrames[frame]
+  }
+  onHandler('desktop2-get-install-id')(event)
+  return event.returnValue
+}
+
+describe('registerDownloadHandlers install id bridge', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    registerDownloadHandlers()
+  })
+
+  it('answers a cloud page with the machine-derived id', () => {
+    mocks.findEntryByComfySender.mockReturnValue({ sourceCategory: 'cloud' })
+    mocks.getIdClass.mockReturnValue('machine_derived')
+    mocks.getDeviceId.mockReturnValue('install-abc')
+
+    expect(requestInstallId()).toBe('install-abc')
+  })
+
+  it.for(['remote', 'local', null])('withholds the id from a %s page', (sourceCategory) => {
+    mocks.findEntryByComfySender.mockReturnValue({ sourceCategory })
+    mocks.getIdClass.mockReturnValue('machine_derived')
+    mocks.getDeviceId.mockReturnValue('install-abc')
+
+    expect(requestInstallId()).toBeUndefined()
+  })
+
+  it('withholds the id once a cloud view has navigated off the trusted cloud origin', () => {
+    mocks.findEntryByComfySender.mockReturnValue({ sourceCategory: 'cloud' })
+    mocks.getIdClass.mockReturnValue('machine_derived')
+    mocks.getDeviceId.mockReturnValue('install-abc')
+
+    expect(requestInstallId({ url: 'https://example.com/' })).toBeUndefined()
+  })
+
+  it('withholds the id from a subframe of a cloud page', () => {
+    mocks.findEntryByComfySender.mockReturnValue({ sourceCategory: 'cloud' })
+    mocks.getIdClass.mockReturnValue('machine_derived')
+    mocks.getDeviceId.mockReturnValue('install-abc')
+
+    expect(requestInstallId({ frame: 'subframe' })).toBeUndefined()
+  })
+
+  it('withholds the id when the sending frame is gone', () => {
+    mocks.findEntryByComfySender.mockReturnValue({ sourceCategory: 'cloud' })
+    mocks.getIdClass.mockReturnValue('machine_derived')
+    mocks.getDeviceId.mockReturnValue('install-abc')
+
+    expect(requestInstallId({ frame: 'missing' })).toBeUndefined()
+  })
+
+  it('withholds the id from an unregistered sender', () => {
+    mocks.findEntryByComfySender.mockReturnValue(null)
+    mocks.getIdClass.mockReturnValue('machine_derived')
+
+    expect(requestInstallId()).toBeUndefined()
+  })
+
+  it.for(['random_fallback', 'placeholder_fallback'])(
+    'withholds a %s id rather than sending one that changes every launch',
+    (idClass) => {
+      mocks.findEntryByComfySender.mockReturnValue({ sourceCategory: 'cloud' })
+      mocks.getIdClass.mockReturnValue(idClass)
+      mocks.getDeviceId.mockReturnValue('random-per-launch')
+
+      expect(requestInstallId()).toBeUndefined()
+    }
+  )
+})

src/main/lib/ipc/registerDownloadHandlers.ts

@@ -1,4 +1,5 @@
 import { BrowserWindow, ipcMain, shell } from 'electron'
+import type { IpcMainEvent } from 'electron'
 import path from 'path'
 import { findEntryByComfySender } from '../../host/registry'
 import {
@@ -12,14 +13,34 @@ import {
   retryDownload,
   startModelDownload
 } from '../comfyDownloadManager'
+import { getDeviceId, getIdClass } from '../deviceId'
 import { openModelAccessPageWindow } from '../modelAccessPage'
+import { isTrustedCloudUrl } from '../trustedCloudUrl'
+
+function isTrustedCloudSender({ sender, senderFrame }: IpcMainEvent): boolean {
+  if (findEntryByComfySender(sender)?.sourceCategory !== 'cloud' || !senderFrame) return false
+  const mainFrame = sender.mainFrame
+  return (
+    senderFrame.processId === mainFrame.processId &&
+    senderFrame.routingId === mainFrame.routingId &&
+    isTrustedCloudUrl(senderFrame.url)
+  )
+}
 
 export function registerDownloadHandlers(): void {
   ipcMain.on('desktop2-is-remote', (event) => {
     const entry = findEntryByComfySender(event.sender)
     event.returnValue = entry?.sourceCategory === 'cloud' || entry?.sourceCategory === 'remote'
   })
 
+  // Per-installation id for cloud attribution (sent as X-Comfy-Install-Id by
+  // the cloud-hosted frontend). Only the main frame of a trusted cloud page
+  // gets it, and only a machine-derived id: a fallback id changes every launch.
+  ipcMain.on('desktop2-get-install-id', (event) => {
+    event.returnValue =
+      isTrustedCloudSender(event) && getIdClass() === 'machine_derived' ? getDeviceId() : undefined
+  })
+
   ipcMain.handle('desktop2-open-model-access-page', (event, payload?: { url?: unknown }) =>
     openModelAccessPageWindow(event.sender, payload?.url)
   )

src/preload/comfyPreload.ts

@@ -321,8 +321,12 @@ const Auth: ComfyDesktop2AuthBridge = {
   }
 }
 
+let installId: string | undefined
+
 const bridge = {
   isRemote: (): boolean => ipcRenderer.sendSync('desktop2-is-remote') as boolean,
+  getInstallId: (): string | undefined =>
+    (installId ??= ipcRenderer.sendSync('desktop2-get-install-id') as string | undefined),
   openModelAccessPage: (url: string): Promise<boolean> => {
     return ipcRenderer.invoke('desktop2-open-model-access-page', { url })
   },

src/types/comfyDesktopBridge.ts

@@ -171,6 +171,13 @@ export interface ComfyDesktop2Bridge {
   /** Reports whether the backend server is cloud/remote, not the user's location.
    *  Optional: desktop builds predating it are still in the wild. */
   isRemote?(): boolean
+  /** Returns the per-installation id: a non-PII, stable-per-machine value
+   *  (`SHA-256(machine_id + salt)`, see main/lib/deviceId). The hosted
+   *  frontend sends it to cloud as the `X-Comfy-Install-Id` header so cloud
+   *  can attribute requests to a Desktop install. Not an identity/secret.
+   *  Undefined outside cloud-hosted pages or when the id is not
+   *  machine-derived. Absent on Desktop builds predating it. */
+  getInstallId?(): string | undefined
   openTerminal?: () => Promise<boolean>
   openMcpSetup?: () => Promise<boolean>
   /** Opens a model provider access page in the hosted frontend's browser session.