@unisim/sdk 0.110.1 → 0.112.0

package/electron/handoff.cjs

@@ -0,0 +1,202 @@
+// Hub handoff — the MAIN-PROCESS half of the desktop bridge.
+//
+// A Universal App's Electron shell sends every http(s) navigation to the
+// system browser, which is right for arbitrary links and wrong for the hub:
+// sign-in on desktop is the SDK's in-app dialog, so the session lives in this
+// app and the browser has never seen it. "View profile" therefore landed a
+// signed-in user on a signed-out page.
+//
+// This opens hub pages in a window the app owns, with the session already
+// installed for the hub's origin — so the page is signed in before its first
+// paint, and no credential is ever written into a URL.
+//
+//   // main.cjs
+//   const { installHubHandoff } = require('@unisim/sdk/electron')
+//   installHubHandoff({ icon: ICON_PATH })
+//
+// ⚠️ The preload half CANNOT require this package. Electron sandboxes preload
+// scripts by default (since 20), and a sandboxed preload's `require` resolves
+// only a handful of built-ins — anything else throws at load and takes the
+// whole bridge with it. Each app's own preload exposes the bridge in five
+// lines using nothing but `require('electron')`; see PRELOAD_SNIPPET below.
+//
+// ⚠️ The window this opens gets NO preload and NO node integration. It renders
+// a remote origin; handing it any bridge would hand the web page the app.
+
+const { BrowserWindow, ipcMain, shell, session: electronSession } = require('electron')
+
+/** IPC channels. Preloads must use these exact strings — see PRELOAD_SNIPPET. */
+const CHANNEL_OPEN = 'unisim:open-hub'
+const CHANNEL_CLEAR = 'unisim:clear-hub'
+
+/** Must match the provider's `storageKey` and its cookie domain in the SDK. */
+const SUITE_SESSION_KEY = 'universal-suite-auth'
+const SUITE_COOKIE_DOMAIN = '.unisim.co.uk'
+
+/** A year, matching what the SDK's own cookie storage writes. */
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24 * 365
+
+/**
+ * The five lines an app's preload needs. Kept here so the channel names have
+ * exactly one home, even though the preload has to spell them out itself.
+ */
+const PRELOAD_SNIPPET = `
+contextBridge.exposeInMainWorld('unisimDesktop', {
+  openHub: (url, session) => ipcRenderer.invoke('${CHANNEL_OPEN}', { url, session }),
+  clearHub: () => ipcRenderer.invoke('${CHANNEL_CLEAR}'),
+})
+`.trim()
+
+function isSuiteUrl(url, cookieDomain) {
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch {
+    return false
+  }
+  if (parsed.protocol !== 'https:') return false
+  const bare = cookieDomain.replace(/^\./, '')
+  return parsed.hostname === bare || parsed.hostname.endsWith(`.${bare}`)
+}
+
+/**
+ * Wire up the hub-handoff IPC. Call once, after `app.whenReady()`.
+ *
+ * @param {object}  [options]
+ * @param {string}  [options.cookieDomain] Zone the session cookie is scoped to.
+ * @param {string}  [options.icon]         Window icon path (Windows/Linux).
+ * @param {object}  [options.windowOptions] Merged into the BrowserWindow opts.
+ * @returns {() => void} Removes the handlers again (tests, teardown).
+ */
+function installHubHandoff(options = {}) {
+  const {
+    cookieDomain = SUITE_COOKIE_DOMAIN,
+    icon,
+    windowOptions = {},
+  } = options
+
+  /** The one hub window, reused so repeat clicks don't stack windows up. */
+  let hubWindow = null
+
+  async function installSession(ses, url, session) {
+    const { origin } = new URL(url)
+    await ses.cookies.set({
+      url: origin,
+      name: SUITE_SESSION_KEY,
+      // The SDK's cookie storage percent-encodes the value it writes, and
+      // percent-decodes what it reads. Hand it back what it expects.
+      value: encodeURIComponent(session),
+      domain: cookieDomain,
+      path: '/',
+      secure: true,
+      sameSite: 'lax',
+      expirationDate: Math.floor(Date.now() / 1000) + SESSION_MAX_AGE_SECONDS,
+    })
+  }
+
+  ipcMain.handle(CHANNEL_OPEN, async (_event, payload) => {
+    const url = payload && typeof payload.url === 'string' ? payload.url : ''
+    const session =
+      payload && typeof payload.session === 'string' && payload.session ? payload.session : null
+
+    // Anything that is not a suite page is an ordinary external link and keeps
+    // its ordinary behaviour. This is also the guard that stops a compromised
+    // renderer from asking us to plant the session cookie on someone else's
+    // origin: the cookie is only ever set for a URL that passes here.
+    if (!isSuiteUrl(url, cookieDomain)) {
+      await shell.openExternal(url)
+      return { ok: true, external: true }
+    }
+
+    // Signed out (or a mock session that means nothing to the hub): there is
+    // nothing to hand over, so the browser is the better window — it may have
+    // a real session of its own, and it has the user's password manager.
+    if (!session) {
+      await shell.openExternal(url)
+      return { ok: true, external: true }
+    }
+
+    try {
+      if (hubWindow && !hubWindow.isDestroyed()) {
+        await installSession(hubWindow.webContents.session, url, session)
+        hubWindow.loadURL(url)
+        hubWindow.show()
+        hubWindow.focus()
+        return { ok: true }
+      }
+
+      const win = new BrowserWindow({
+        width: 1100,
+        height: 820,
+        // Painted only once the hub has rendered — the session is installed
+        // before the first load, so there is no signed-out flash to hide,
+        // but an empty white window while the page fetches still looks broken.
+        show: false,
+        title: 'Universal ID',
+        ...(icon ? { icon } : {}),
+        ...windowOptions,
+        webPreferences: {
+          contextIsolation: true,
+          nodeIntegration: false,
+          ...(windowOptions.webPreferences || {}),
+        },
+      })
+      hubWindow = win
+
+      await installSession(win.webContents.session, url, session)
+
+      win.once('ready-to-show', () => win.show())
+      win.on('closed', () => {
+        if (hubWindow === win) hubWindow = null
+      })
+
+      // Links the hub opens in a new tab belong in the real browser — this
+      // window is an account panel, not a general-purpose browser.
+      win.webContents.setWindowOpenHandler(({ url: target }) => {
+        if (/^https?:\/\//.test(target)) {
+          void shell.openExternal(target)
+          return { action: 'deny' }
+        }
+        return { action: 'deny' }
+      })
+
+      await win.loadURL(url)
+      return { ok: true }
+    } catch (err) {
+      return { ok: false, error: String((err && err.message) || err) }
+    }
+  })
+
+  ipcMain.handle(CHANNEL_CLEAR, async () => {
+    // Signing out of the app has to sign out the handed-over session too —
+    // otherwise the next "View profile" opens the account of the person who
+    // just left.
+    const ses = electronSession.defaultSession
+    const cookies = await ses.cookies.get({ name: SUITE_SESSION_KEY })
+    await Promise.all(
+      cookies.map((cookie) => {
+        const scheme = cookie.secure ? 'https' : 'http'
+        const host = cookie.domain && cookie.domain.startsWith('.')
+          ? cookie.domain.slice(1)
+          : cookie.domain
+        return ses.cookies.remove(`${scheme}://${host}${cookie.path || '/'}`, cookie.name)
+      }),
+    )
+    if (hubWindow && !hubWindow.isDestroyed()) hubWindow.close()
+    return { ok: true }
+  })
+
+  return function uninstall() {
+    ipcMain.removeHandler(CHANNEL_OPEN)
+    ipcMain.removeHandler(CHANNEL_CLEAR)
+  }
+}
+
+module.exports = {
+  installHubHandoff,
+  CHANNEL_OPEN,
+  CHANNEL_CLEAR,
+  SUITE_SESSION_KEY,
+  SUITE_COOKIE_DOMAIN,
+  PRELOAD_SNIPPET,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unisim/sdk",
-  "version": "0.110.1",
+  "version": "0.112.0",
   "description": "Shared React SDK for the Universal Suite — auth, entitlements, usage telemetry, changelog, org admin.",
   "license": "MIT",
   "author": "Universal Simulation Ltd",
@@ -32,10 +32,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./electron": {
+      "require": "./electron/handoff.cjs"
     }
   },
   "files": [
     "dist",
+    "electron",
     "README.md"
   ],
   "scripts": {