Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { BrowserWindow, WebContentsView, screen, session } from 'electron'
import path from 'node:path'
import { getActiveEnvKey } from './config.js'
import { createSandboxFindResultGate } from './sandboxFindSession.js'
import { extractSandboxUiViewRoute, normalizeSandboxUiRoute } from './sandboxUiDeepLinks.js'
import { touchSandboxUiPartition } from './sandboxUiPartitionGc.js'
import {
applySandboxUiNavigationPolicies,
applySandboxUiPartitionPolicies,
isSandboxUiNavigationWithinPrefix as isNavigationWithinPrefix,
} from './sandboxUiPartitionPolicies.js'
import { wireDesktopShortcutRouting } from './shortcutRouter.js'
import type { SandboxUiReleaseReason, SandboxUiReleasedEvent, SandboxUiRoute } from './types.js'
export type { SandboxUiReleaseReason, SandboxUiReleasedEvent, SandboxUiRoute }
/**
* Sandbox UI embed driver. Owns the lifecycle of the single active
* `WebContentsView` that hosts a recipe's sandbox UI inside the main
* desktop window.
*
* One-at-a-time embed: the driver is a singleton. Mounting recipe B while A
* is up tears down A first; A's per-recipe Electron partition is left intact
* so a quick A → B → A round-trip doesn't lose cookies/storage (the launch-
* time GC pass handles eventual eviction).
*
* Cookie installation: the rpc-proxy session-mint runs in the main process
* (via `RpcProxyClient.mintSandboxUiSession`). Its raw Set-Cookie value is
* parsed and written into the partition's session BEFORE the first `view/*`
* navigation, so the cookie is on the very first request. The proxy also
* validates the cookie's recipeNs/recipeName claim against the URL path on
* every hit, so a partition that ended up with a cookie minted for a
* different recipe still gets rejected with 401 by rpc-proxy — the JWT
* claim binding is the second line of defence.
*
* Hardened webPreferences:
* nodeIntegration:false — no Node API exposed to embed JS
* contextIsolation:true — preload runs in its own world
* sandbox:true — Chromium sandbox (OS-level)
* webSecurity:true — same-origin policy enforced
* no `remote` — Electron's deprecated remote module never on
*/
export const SANDBOX_UI_COOKIE_NAME = 'clerum_sandbox_ui_session'
const CLIENT_ROUTE_HANDOFF_TIMEOUT_MS = 30_000
export type SandboxUiBounds = {
x: number
y: number
width: number
height: number
dpr?: number
}
export type SandboxUiFindResult = {
requestId: number
activeMatchOrdinal: number
matches: number
finalUpdate: boolean
}
export type SandboxUiFindOperation = 'start' | 'next' | 'previous'
export type SandboxUiFindStartResult =
| { status: 'started'; requestId: number }
| { status: 'unavailable'; reason: 'no-active-view' | 'document-loading' | 'no-session' }
export function sandboxFindOptionsForOperation(operation: SandboxUiFindOperation): {
forward: boolean
findNext: boolean
} {
return operation === 'start'
? { forward: true, findNext: true }
: { forward: operation === 'next', findNext: false }
}
function toViewBounds(
bounds: SandboxUiBounds,
parentWindow: BrowserWindow
): { x: number; y: number; width: number; height: number } {
// Renderer's CSS pixels and macOS points diverge when the user is on a
// scaled display (e.g. "Larger Text" mode reports devicePixelRatio=2.4
// to the renderer while the screen's scaleFactor stays at 2.0).
// WebContentsView.setBounds expects points, so multiply by dpr/scaleFactor
// — a no-op when they match (the common 1× / 2× case).
const sf = screen.getDisplayMatching(parentWindow.getBounds()).scaleFactor
const dpr = bounds.dpr ?? sf
if (Math.abs(dpr - sf) < 0.01) {
return { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height }
}
const factor = dpr / sf
return {
x: Math.round(bounds.x * factor),
y: Math.round(bounds.y * factor),
width: Math.round(bounds.width * factor),
height: Math.round(bounds.height * factor),
}
}
export type MountSandboxUiArgs = {
/** Names this mount in every event about the view it creates. */
launchId: string
recipeNs: string
recipeName: string
setCookie: string
rpcProxyUrl: string
defaultPath?: string
parentWindow: BrowserWindow
bounds: SandboxUiBounds
routePath?: string
/** Main-side cleanup for a teardown nobody asked for (crash, parent closed). */
onClosed?: () => void
/**
* Fired exactly once when this mount's view is torn down, for any reason,
* including a teardown that fails half-way. Only a mount that got as far as
* making its view the active one fires it: a view created but not yet active
* (a step between its construction and its activation threw) never does.
*/
onReleased?: (event: SandboxUiReleasedEvent) => void
/**
* Fired when the embedded document's `<title>` changes (`page-title-updated`).
* The driver only forwards the plugin-controlled title; the renderer decides
* whether to surface it (its app tab title) and trims/ignores empty values.
* Read-only: it never grants the embed any privilege.
*/
onTitleChanged?: (title: string) => void
/**
* Spec §9.9 — recipe-author Connect button affordance. Fired when the
* embed navigates to `clerum://oauth?clientId=…`. The driver's only
* job is to forward; the AppService method this points at calls
* rpc-proxy for the provider authorize URL and `shell.openExternal`s it.
*/
onOauthAuthorize?: (oauthClientId: string, background: boolean) => void
/**
* Fired when the embed navigates to `gfs://<drive>/<resource>` — a plugin
* rendering a link to a shared file. The driver only forwards; the host
* resolves the URI with the USER's session and shows it in the Desktop's own
* viewer, so a click reveals nothing to the plugin.
*/
onGfsOpen?: (uri: string) => void
/**
* Fired when a main-frame navigation inside the app's `view/` prefix
* commits with HTTP 401 — the session cookie was rejected and the page left
* behind has no script that could ask for a refresh. Lives as long as the
* view, unlike the one-shot client-route handoff listener.
*/
onUnauthorizedNavigation?: (webContentsId: number) => void
/**
* Re-checked at every await before a session effect (cookie write, view
* creation). False means the caller's authenticated session ended while this
* mount was in flight, so it must not attach anything for it.
*/
isCurrent?: () => boolean
}
type ActiveView = {
launchId: string
view: WebContentsView
onReleased?: (event: SandboxUiReleasedEvent) => void
recipeNs: string
recipeName: string
defaultPath: string
partition: string
parentWindow: BrowserWindow
rpcProxyOrigin: string
cleanupClientRouteHandoff?: () => void
cleanupParentClosed?: () => void
cleanupRenderProcessGone?: () => void
cleanupShortcutRouting?: () => void
cleanupDocumentLifecycle?: () => void
cleanupFindResults?: () => void
/** The route the open asked for, as `representedSandboxUiLocation` reports it. */
requestedRoute: SandboxUiRoute
/**
* False while the document cannot yet stand for the requested route: it has
* not loaded, or the route handoff is pending or failed with no navigation
* since. Once true it stays true: a reload keeps the committed URL.
*/
routeSettled: boolean
documentGeneration: number
documentReady: boolean
findSession?: {
query: string
clientRequestId: number
documentGeneration: number
nativeRequestId: number
complete: boolean
}
}
let active: ActiveView | null = null
let mountGeneration = 0
export const isSandboxUiNavigationWithinPrefix = isNavigationWithinPrefix
export function getActiveSandboxUi(): {
launchId: string
recipeNs: string
recipeName: string
appRef: string
webContentsId: number
} | null {
if (!active) return null
return {
launchId: active.launchId,
recipeNs: active.recipeNs,
recipeName: active.recipeName,
appRef: `${active.recipeNs}/${active.recipeName}`,
webContentsId: active.view.webContents.id,
}
}
export function getActiveSandboxUiLocation(): {
recipeNs: string
recipeName: string
path?: string
} | null {
if (!active) return null
if (active.view.webContents.isDestroyed()) return null
const { routePath } = representedSandboxUiLocation(active)
return {
recipeNs: active.recipeNs,
recipeName: active.recipeName,
...(routePath ? { path: routePath } : {}),
}
}
/**
* The single reader of the route a view stands for. Until the document can
* represent the requested route, the live URL is empty or the default route,
* and reporting it would overwrite the route the user is on with a wrong one.
* Throws when the live URL is outside the app; each caller decides what that
* means for it.
*/
function representedSandboxUiLocation(view: ActiveView): SandboxUiRoute {
if (!view.routeSettled) return { ...view.requestedRoute }
const routePath = resolveSandboxUiSharePath({
currentUrl: view.view.webContents.getURL(),
rpcProxyOrigin: view.rpcProxyOrigin,
recipeNs: view.recipeNs,
recipeName: view.recipeName,
defaultPath: view.defaultPath,
})
return routePath ? { routePath } : {}
}
export function resolveSandboxUiSharePath(input: {
currentUrl: string
rpcProxyOrigin: string
recipeNs: string
recipeName: string
defaultPath: string
}): string | undefined {
if (!input.currentUrl.trim()) return undefined
const currentPath = extractSandboxUiViewRoute(input)
if (currentPath === null) throw new Error('Cannot read the current app route')
return currentPath === sharedPathForDefaultPath(input.defaultPath) ? undefined : currentPath
}
export function partitionFor(envKey: string, recipeNs: string, recipeName: string): string {
// Per-(environment, recipe) partition — Chromium isolates storage (cookies,
// IndexedDB, localStorage, service workers) by partition. `envKey` (spec §5.2)
// scopes it so the same recipe ns/name in two clusters never shares KasmVNC
// cookies/storage. The launch-time GC pass walks the current env's
// `persist:sandbox-ui-${envKey}-*` partitions and wipes the ones the user no
// longer has ACL for; other environments' partitions are left untouched.
return `persist:sandbox-ui-${envKey}-${recipeNs}-${recipeName}`
}
/**
* Pull the cookie value out of a Set-Cookie header. Accepts either a
* single value or an array (Node's `getSetCookie()` API). Returns null
* when the named cookie is absent or the header is malformed.
*/
export function extractSandboxUiCookie(
setCookie: string | string[],
name: string = SANDBOX_UI_COOKIE_NAME
): string | null {
const list = Array.isArray(setCookie) ? setCookie : [setCookie]
const prefix = `${name}=`
for (const header of list) {
if (header.startsWith(prefix)) {
const rest = header.slice(prefix.length)
const end = rest.indexOf(';')
return end === -1 ? rest : rest.slice(0, end)
}
}
return null
}
/**
* Pull the Path attribute out of a Set-Cookie header. Falls back to
* '/api/v1/sandbox-ui/<ns>/<name>/' if the header omits it (rpc-proxy
* always sets it, but we never want to install a cookie at a wider path
* than the one the server intended).
*/
export function extractSandboxUiPath(
setCookie: string | string[],
recipeNs: string,
recipeName: string
): string {
const list = Array.isArray(setCookie) ? setCookie : [setCookie]
for (const header of list) {
const match = /;\s*Path=([^;]+)/i.exec(header)
const captured = match?.[1]
if (captured) return captured.trim()
}
return `/api/v1/sandbox-ui/${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/`
}
/**
* Write a session cookie into the per-recipe Electron partition. Used both
* at mount-time (initial cookie) and at refresh-time (rotated cookie). The
* cookie is keyed on `(name, path)` so calling this with a fresh value at
* the same Path replaces the existing entry — the embed sees the new JWT
* on its next request without any `view/*` reload.
*/
async function writeSandboxUiCookie(args: {
rpcProxyOrigin: string
recipeNs: string
recipeName: string
setCookie: string | string[]
partition: string
}): Promise<void> {
const { rpcProxyOrigin, recipeNs, recipeName, setCookie, partition } = args
const cookieValue = extractSandboxUiCookie(setCookie)
if (!cookieValue) {
throw new Error(`session response did not include ${SANDBOX_UI_COOKIE_NAME} cookie`)
}
const cookiePath = extractSandboxUiPath(setCookie, recipeNs, recipeName)
const ses = session.fromPartition(partition)
await ses.cookies.set({
url: `${rpcProxyOrigin}${cookiePath}`,
name: SANDBOX_UI_COOKIE_NAME,
value: cookieValue,
path: cookiePath,
httpOnly: true,
sameSite: 'strict',
// Mirror the proxy's Secure attribute when it's serving https.
secure: rpcProxyOrigin.startsWith('https:'),
})
}
/**
* Undo `writeSandboxUiCookie`: removes the cookie it would set for the same
* arguments. Removal matches by name and by the URL the cookie is sent to, so
* it also clears an older value left at that Path by a previous mount.
*/
async function removeSandboxUiCookie(args: {
rpcProxyOrigin: string
recipeNs: string
recipeName: string
setCookie: string | string[]
partition: string
}): Promise<void> {
const { rpcProxyOrigin, recipeNs, recipeName, setCookie, partition } = args
const cookiePath = extractSandboxUiPath(setCookie, recipeNs, recipeName)
await session
.fromPartition(partition)
.cookies.remove(`${rpcProxyOrigin}${cookiePath}`, SANDBOX_UI_COOKIE_NAME)
}
/**
* Refresh the active partition's session cookie. No-op when nothing is
* mounted (refresh can race with teardown). Throws on a missing cookie
* value or a partition write error so the caller can surface a refresh
* failure to the user.
*/
export async function installSandboxUiCookie(setCookie: string | string[]): Promise<void> {
if (!active) return
const expectedPath =
`/api/v1/sandbox-ui/${encodeURIComponent(active.recipeNs)}/` +
`${encodeURIComponent(active.recipeName)}/`
const cookiePath = extractSandboxUiPath(setCookie, active.recipeNs, active.recipeName)
if (cookiePath !== expectedPath) {
throw new Error(`sandbox-ui refresh cookie path ${cookiePath} does not match the active recipe`)
}
await writeSandboxUiCookie({
rpcProxyOrigin: active.rpcProxyOrigin,
recipeNs: active.recipeNs,
recipeName: active.recipeName,
setCookie,
partition: active.partition,
})
}
function readReleasedLocation(
view: ActiveView,
reason: SandboxUiReleaseReason
): SandboxUiRoute | null {
if (reason === 'crashed') return null
try {
return representedSandboxUiLocation(view)
} catch (err) {
console.warn('[SandboxUI] could not read the route of a view being torn down:', err)
return null
}
}
function runTeardownStep(step: string, reason: SandboxUiReleaseReason, run: () => void): void {
try {
run()
} catch (err) {
console.error(`[SandboxUI] teardown step ${step} failed:`, err, 'reason:', reason)
}
}
/**
* Synchronous on purpose: the release event must leave before anything else
* can run, so a caller that rejects after a teardown always reports the release
* first. Every step is isolated; a failing listener unhook must not leave the
* view attached, alive or unreported.
*/
function teardownActive(reason: SandboxUiReleaseReason): void {
if (!active) return
const current = active
active = null
const location = readReleasedLocation(current, reason)
const webContents = current.view.webContents
try {
runTeardownStep('cleanupClientRouteHandoff', reason, () =>
current.cleanupClientRouteHandoff?.()
)
runTeardownStep('cleanupParentClosed', reason, () => current.cleanupParentClosed?.())
runTeardownStep('cleanupRenderProcessGone', reason, () => current.cleanupRenderProcessGone?.())
runTeardownStep('cleanupShortcutRouting', reason, () => current.cleanupShortcutRouting?.())
runTeardownStep('cleanupDocumentLifecycle', reason, () => current.cleanupDocumentLifecycle?.())
runTeardownStep('cleanupFindResults', reason, () => current.cleanupFindResults?.())
runTeardownStep('stopFindInPage', reason, () => {
if (!webContents.isDestroyed()) webContents.stopFindInPage('clearSelection')
})
} finally {
// Every step above is guarded today; the finally keeps detach, close and
// release unconditional if a step is ever added without its guard.
// removeChildView both detaches the view from layout and severs the
// parent's ownership ref.
runTeardownStep('removeChildView', reason, () => {
if (!current.parentWindow.isDestroyed()) {
current.parentWindow.contentView.removeChildView(current.view)
}
})
// Closing the webContents stops loading and frees the renderer process.
runTeardownStep('closeWebContents', reason, () => {
if (!webContents.isDestroyed()) webContents.close()
})
runTeardownStep('onReleased', reason, () =>
current.onReleased?.({ launchId: current.launchId, reason, location })
)
runTeardownStep('verifyDetached', reason, () => {
if (
!current.parentWindow.isDestroyed() &&
current.parentWindow.contentView.children.includes(current.view)
) {
console.error('[SandboxUI] a torn-down view is still attached to its window')
}
})
}
}
export async function mountSandboxUiView(args: MountSandboxUiArgs): Promise<void> {
const {
launchId,
recipeNs,
recipeName,
setCookie,
rpcProxyUrl,
defaultPath,
parentWindow,
bounds,
routePath,
onClosed,
onReleased,
onTitleChanged,
isCurrent = () => true,
} = args
if (parentWindow.isDestroyed()) {
throw new Error('parent window is destroyed')
}
if (!recipeNs.trim() || !recipeName.trim()) {
throw new Error('recipeNs and recipeName are required')
}
// Publish intent before the first await. A newer mount or unmount invalidates
// this operation while cookie installation is in flight, preventing an older
// request from attaching a view after the user has moved on.
const generation = ++mountGeneration
// Tear down any existing view before mounting (one-at-a-time embed). The
// per-recipe partition is left in place so storage survives a re-mount
// within the ACL window.
// AppService already tore down before minting; this covers callers that
// mount through the driver without that queue.
teardownActive('replaced')
if (generation !== mountGeneration || !isCurrent()) return
const partition = partitionFor(getActiveEnvKey(), recipeNs, recipeName)
const proxyOriginUrl = new URL(rpcProxyUrl).toString().replace(/\/+$/, '')
const viewPath = resolveSandboxUiDefaultPath(defaultPath)
const clientRoutePath = normalizeSandboxUiRoute(routePath || '')
const sharedViewPath = sharedPathForDefaultPath(viewPath)
const needsClientRouteHandoff = Boolean(clientRoutePath && clientRoutePath !== sharedViewPath)
const requestedRoute: SandboxUiRoute =
needsClientRouteHandoff && clientRoutePath ? { routePath: clientRoutePath } : {}
const allowedNavigationPrefix =
`${proxyOriginUrl}/api/v1/sandbox-ui/` +
`${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view`
// Install the session cookie BEFORE creating the view so the very first
// navigation request carries it. The proxy enforces the recipe binding
// claim on every request — installing on a stale partition would still
// fail closed at rpc-proxy.
const cookieArgs = { rpcProxyOrigin: proxyOriginUrl, recipeNs, recipeName, setCookie, partition }
await writeSandboxUiCookie(cookieArgs)
if (generation !== mountGeneration) return
if (!isCurrent()) {
// The partition is keyed per recipe, not per user, and a session change
// does not clear it: the cookie just written would outlive the session
// that minted it. Only when this mount is still the newest one — a newer
// mount may already have written its own cookie at the same Path.
await removeSandboxUiCookie(cookieArgs).catch(err => {
console.warn('[SandboxUI] could not remove a stale session cookie:', err)
})
return
}
if (parentWindow.isDestroyed()) {
throw new Error('parent window is destroyed')
}
// Apply default-deny permission + download policy on the partition's
// Session before the view is constructed so the very first navigation
// already runs under those rules.
const ses = session.fromPartition(partition)
applySandboxUiPartitionPolicies(ses)
const view = new WebContentsView({
webPreferences: {
partition,
// The embed preload exposes `clerum.requestSessionRefresh()` so an
// embed can recover from an SSE 401 between scheduled refreshes. The
// handler in main process gates the call by the IPC pinning map +
// 30 s rate-limit.
preload: path.join(__dirname, 'sandboxUiEmbedPreload.js'),
nodeIntegration: false,
contextIsolation: true,
sandbox: true,
webSecurity: true,
// Defence-in-depth — no spell-check / no auto form-fill is required,
// but Electron defaults already disable those for sandboxed
// partitions. Audit if upgrading Electron majors.
},
})
view.setBounds(toViewBounds(bounds, parentWindow))
// Pin top-level navigation to this recipe's `view/*` prefix; everything
// else (links to other origins, target=_blank, window.open) goes to the
// OS browser or is dropped. `clerum://oauth?clientId=…` is intercepted
// and handed back to the AppService.
applySandboxUiNavigationPolicies(view.webContents, allowedNavigationPrefix, {
onOauthAuthorize: (oauthClientId, background) => {
args.onOauthAuthorize?.(oauthClientId, background)
},
onGfsOpen: uri => {
args.onGfsOpen?.(uri)
},
})
// `onClosed` reports a teardown nobody asked for: the parent window closed
// or the embed's renderer died. Solicited teardowns (`unmountSandboxUiView`,
// a replacing mount) stay silent — the caller already ran its own cleanup.
// The renderer learns of every teardown from `onReleased` instead.
const onParentClosed = (): void => {
teardownActive('parent_closed')
onClosed?.()
}
parentWindow.once('closed', onParentClosed)
const cleanupParentClosed = (): void => {
parentWindow.removeListener('closed', onParentClosed)
}
// A dead renderer leaves its last frame painted over the app with nothing
// behind it, whatever the reason. The identity check keeps a late signal
// from a view that was already replaced from tearing down its successor.
// `mountGeneration` is deliberately left alone: bumping it would abort an
// unrelated mount that is in flight.
const onRenderProcessGone = (): void => {
if (active?.view !== view) return
teardownActive('crashed')
onClosed?.()
}
view.webContents.on('render-process-gone', onRenderProcessGone)
const cleanupRenderProcessGone = (): void => {
view.webContents.removeListener('render-process-gone', onRenderProcessGone)
}
active = {
launchId,
view,
onReleased,
recipeNs,
recipeName,
defaultPath: viewPath,
partition,
parentWindow,
rpcProxyOrigin: proxyOriginUrl,
cleanupParentClosed,
cleanupRenderProcessGone,
requestedRoute,
routeSettled: false,
documentGeneration: 0,
documentReady: false,
}
const invalidateFindForNavigation = (requiresDocumentLoad: boolean): void => {
if (!active || active.view !== view) return
active.documentGeneration += 1
if (requiresDocumentLoad) active.documentReady = false
stopActiveSandboxUiFind()
}
const onDidStartNavigation = (
_event: Electron.Event,
_url: string,
isInPlace: boolean,
isMainFrame: boolean
): void => {
if (isMainFrame) invalidateFindForNavigation(!isInPlace)
}
let documentLoaded = false
// Cleared by the handoff when it applies the route, fails, times out or is
// abandoned.
let clientRouteHandoffPending = needsClientRouteHandoff
let lastMainFrameUrl = ''
const onDocumentReady = (): void => {
if (active?.view !== view) return
documentLoaded = true
active.documentReady = true
if (!needsClientRouteHandoff) active.routeSettled = true
}
// A navigation inside the loaded document is the user's (or the app's) own:
// from then on the live URL is the route, whatever became of the handoff.
const onDidNavigateInPage = (_event: Electron.Event, url: string, isMainFrame: boolean): void => {
if (active?.view !== view || !isMainFrame) return
// A router can move the URL before the first load; a later reload commits
// that URL and must still read as a reload.
lastMainFrameUrl = url
if (documentLoaded) active.routeSettled = true
}
// Forward the embed's live `document.title` so the renderer can name its app
// tab after it (mirrors the URL-report pattern). The title is plugin content,
// so it stays read-only — the renderer trims/ignores empty values.
const onPageTitleUpdated = (_event: Electron.Event, title: string): void => {
if (active?.view === view) onTitleChanged?.(title)
}
// `did-navigate` only fires for the main frame.
const onDocumentNavigated = (
_event: Electron.Event,
navigatedUrl: string,
httpResponseCode: number
): void => {
if (active?.view !== view) return
const previousUrl = lastMainFrameUrl
lastMainFrameUrl = navigatedUrl
const withinApp = isSandboxUiNavigationWithinPrefix(navigatedUrl, allowedNavigationPrefix)
// With no requested route there is nothing a boot rewrite could overwrite,
// so the first document committed inside the app is already the live
// route; waiting for the load would drop where the user goes meanwhile.
// Otherwise, a new document the user reached after the handoff gave up (a
// multi-page app) is the live route. A reload commits the same URL and the
// commits a pending handoff is still waiting through are not the user's:
// neither may replace the requested route.
if (
withinApp &&
(!needsClientRouteHandoff ||
(documentLoaded && !clientRouteHandoffPending && navigatedUrl !== previousUrl))
) {
active.routeSettled = true
}
if (httpResponseCode !== 401 || !withinApp) return
args.onUnauthorizedNavigation?.(view.webContents.id)
}
view.webContents.on('did-start-navigation', onDidStartNavigation)
view.webContents.on('did-finish-load', onDocumentReady)
view.webContents.on('did-navigate-in-page', onDidNavigateInPage)
view.webContents.on('page-title-updated', onPageTitleUpdated)
view.webContents.on('did-navigate', onDocumentNavigated)
active.cleanupDocumentLifecycle = () => {
view.webContents.removeListener('did-start-navigation', onDidStartNavigation)
view.webContents.removeListener('did-finish-load', onDocumentReady)
view.webContents.removeListener('did-navigate-in-page', onDidNavigateInPage)
view.webContents.removeListener('page-title-updated', onPageTitleUpdated)
view.webContents.removeListener('did-navigate', onDocumentNavigated)
}
active.cleanupShortcutRouting = wireDesktopShortcutRouting({
source: 'sandbox',
sourceWebContents: view.webContents,
trustedRenderer: parentWindow.webContents,
isCurrentSource: () => active?.view.webContents.id === view.webContents.id,
})
parentWindow.contentView.addChildView(view)
// Re-apply bounds after attach. On macOS at fractional DPR (e.g. 2.4 on a
// "More Space" scaled display), setBounds called pre-attach lands the view
// in a slightly offset coordinate system; re-applying after addChildView
// forces it into the parent's now-resolved coords.
view.setBounds(toViewBounds(bounds, parentWindow))
// Record the mount as the partition's most recent access so the next
// launch's LRU GC has fresh data. Fire-and-forget; a write failure is
// logged inside the GC module and must not block the mount.
void touchSandboxUiPartition(`${recipeNs}/${recipeName}`).catch(err => {
console.warn('[SandboxUI] touchSandboxUiPartition failed:', err)
})
const url =
`${proxyOriginUrl}/api/v1/sandbox-ui/` +
`${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view${encodeSandboxUiDefaultPath(
viewPath
)}`
if (needsClientRouteHandoff && clientRoutePath) {
const encodedClientRoutePath = encodeSandboxUiRoutePath(clientRoutePath)
const clientRouteUrl =
`${proxyOriginUrl}/api/v1/sandbox-ui/` +
`${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view${encodedClientRoutePath}`
let lastNavigation = { url: '', status: 0 }
let handoffFinished = false
let handoffTimeout: NodeJS.Timeout | null = null
const cleanupClientRouteHandoff = () => {
if (handoffFinished) return
handoffFinished = true
clientRouteHandoffPending = false
if (handoffTimeout) clearTimeout(handoffTimeout)
view.webContents.removeListener('did-navigate', onDidNavigate)
view.webContents.removeListener('did-finish-load', onDidFinishLoad)
}
const onDidNavigate = (
_event: Electron.Event,
navigatedUrl: string,
httpResponseCode: number
) => {
lastNavigation = { url: navigatedUrl, status: httpResponseCode }
}
const onDidFinishLoad = () => {
if (!active || active.view !== view || view.webContents.isDestroyed()) {
cleanupClientRouteHandoff()
return
}
if (
!canApplySandboxUiClientRoute({
allowedNavigationPrefix,
currentUrl: view.webContents.getURL(),
navigatedUrl: lastNavigation.url,
httpResponseCode: lastNavigation.status,
})
) {
if (
lastNavigation.status >= 200 &&
lastNavigation.status < 400 &&
!isSandboxUiNavigationWithinPrefix(view.webContents.getURL(), allowedNavigationPrefix)
) {
console.warn(
'[SandboxUI] client route handoff abandoned after navigation left the app prefix:',
view.webContents.getURL()
)
cleanupClientRouteHandoff()
}
return
}
void applySandboxUiClientRoute(view.webContents, clientRouteUrl)
.then(applied => {
if (applied && active?.view === view) active.routeSettled = true
if (!applied) {
console.warn('[SandboxUI] client route handoff did not update the app URL')
}
cleanupClientRouteHandoff()
})
.catch(err => {
console.warn('[SandboxUI] client route handoff failed:', err)
cleanupClientRouteHandoff()
})
}
view.webContents.on('did-navigate', onDidNavigate)
view.webContents.on('did-finish-load', onDidFinishLoad)
handoffTimeout = setTimeout(() => {
console.warn('[SandboxUI] client route handoff timed out before the app became ready')
cleanupClientRouteHandoff()
}, CLIENT_ROUTE_HANDOFF_TIMEOUT_MS)
if (active && active.view === view) {
active.cleanupClientRouteHandoff = cleanupClientRouteHandoff
}
}
// Drop the HTTP cache on every open so a stale entry from a prior
// broken pod can't keep painting after the recipe is healthy. The
// partition is persistent (cookies, IndexedDB, localStorage all
// survive), only `Cache` is wiped — clearStorageData would also
// nuke the session cookie and break auth on the very next request.
// Fire-and-forget; loadURL re-issues unconditional GETs once the
// cache directory is gone.
void session
.fromPartition(partition)
.clearCache()
.catch(err => {
console.warn('[SandboxUI] clearCache failed:', err)
})
// No await — the load runs concurrently with the renderer animation.
// The view is already attached + has bounds, so the user sees the URL
// resolve into the embed naturally.
void view.webContents.loadURL(url)
}
export async function applySandboxUiClientRoute(
webContents: Pick<WebContentsView['webContents'], 'executeJavaScript' | 'isDestroyed'>,
targetUrl: string
): Promise<boolean> {
if (webContents.isDestroyed()) return false
const serializedTarget = JSON.stringify(targetUrl)
return Boolean(
await webContents.executeJavaScript(`(() => {
const targetUrl = new URL(${serializedTarget}).href;
const previousUrl = window.location.href;
if (new URL(previousUrl).href === targetUrl) return true;
window.history.replaceState(window.history.state, '', targetUrl);
window.dispatchEvent(new PopStateEvent('popstate', { state: window.history.state }));
return new URL(window.location.href).href === targetUrl;
})()`)
)
}
export function resolveSandboxUiDefaultPath(defaultPath?: string): string {
const rawDefaultPath = String(defaultPath || '')
if (!rawDefaultPath.trim()) return '/'
const normalized = normalizeSandboxUiDefaultPath(rawDefaultPath)
if (normalized) return normalized
console.warn('[SandboxUI] Invalid recipe defaultPath; falling back to "/":', rawDefaultPath)
return '/'
}
function encodeSandboxUiRoutePath(routePath: string): string {
return routePath
.split('/')
.map((segment, index) => (index === 0 ? '' : encodeURIComponent(segment)))
.join('/')
}
function firstDefaultPathMetaIndex(defaultPath: string): number | undefined {
const firstQueryIndex = defaultPath.indexOf('?')
const firstHashIndex = defaultPath.indexOf('#')
return [firstQueryIndex, firstHashIndex].filter(index => index !== -1).sort((a, b) => a - b)[0]
}
function sharedPathForDefaultPath(defaultPath: string): string {
const firstMetaIndex = firstDefaultPathMetaIndex(defaultPath)
const pathname = firstMetaIndex === undefined ? defaultPath : defaultPath.slice(0, firstMetaIndex)
return normalizeSandboxUiRoute(pathname || '/') || '/'
}
function normalizeSandboxUiDefaultMetadata(metadata: string): string | null {
const hashIndex = metadata.indexOf('#')
if (hashIndex === -1) return metadata
const hashRouteStart = hashIndex + 1
const hashRemainder = metadata.slice(hashRouteStart)
const hashQueryIndex = hashRemainder.indexOf('?')
const hashRoute = hashQueryIndex === -1 ? hashRemainder : hashRemainder.slice(0, hashQueryIndex)
if (!hashRoute.startsWith('/')) return metadata
const normalizedHashRoute = normalizeSandboxUiRoute(hashRoute)
if (!normalizedHashRoute) return null
return (
metadata.slice(0, hashRouteStart) +
normalizedHashRoute +
(hashQueryIndex === -1 ? '' : hashRemainder.slice(hashQueryIndex))
)
}
function encodeSandboxUiDefaultMetadata(metadata: string): string {
const hashIndex = metadata.indexOf('#')
if (hashIndex === -1) return metadata
const hashRouteStart = hashIndex + 1
const hashRemainder = metadata.slice(hashRouteStart)
const hashQueryIndex = hashRemainder.indexOf('?')
const hashRoute = hashQueryIndex === -1 ? hashRemainder : hashRemainder.slice(0, hashQueryIndex)
if (!hashRoute.startsWith('/')) return metadata
return (
metadata.slice(0, hashRouteStart) +
encodeSandboxUiRoutePath(hashRoute) +
(hashQueryIndex === -1 ? '' : hashRemainder.slice(hashQueryIndex))
)
}
function encodeSandboxUiDefaultPath(defaultPath: string): string {
const firstMetaIndex = firstDefaultPathMetaIndex(defaultPath)
const pathname = firstMetaIndex === undefined ? defaultPath : defaultPath.slice(0, firstMetaIndex)
const metadata = firstMetaIndex === undefined ? '' : defaultPath.slice(firstMetaIndex)
return `${encodeSandboxUiRoutePath(pathname || '/')}${encodeSandboxUiDefaultMetadata(metadata)}`
}
function normalizeSandboxUiDefaultPath(rawPath: string): string | null {
const routePath = String(rawPath || '')
if (!routePath.trim()) return '/'
if (
routePath.length > 4096 ||
routePath.includes('\\') ||
/[\u0000-\u001f\u007f\u2028\u2029]/.test(routePath)
) {
return null
}
const firstMetaIndex = firstDefaultPathMetaIndex(routePath)
const pathname = firstMetaIndex === undefined ? routePath : routePath.slice(0, firstMetaIndex)
const metadata = firstMetaIndex === undefined ? '' : routePath.slice(firstMetaIndex)
const normalizedPathname = normalizeSandboxUiRoute(pathname || '/')
if (!normalizedPathname) return null
const normalizedMetadata = normalizeSandboxUiDefaultMetadata(metadata)
if (normalizedMetadata === null) return null
return `${normalizedPathname}${normalizedMetadata}`
}
export function canApplySandboxUiClientRoute(input: {
allowedNavigationPrefix: string
currentUrl: string
navigatedUrl: string
httpResponseCode: number
}): boolean {
return (
isSandboxUiNavigationWithinPrefix(input.currentUrl, input.allowedNavigationPrefix) &&
isSandboxUiNavigationWithinPrefix(input.navigatedUrl, input.allowedNavigationPrefix) &&
input.httpResponseCode >= 200 &&
input.httpResponseCode < 400
)
}
/**
* Unmount the active view (no-op if nothing is mounted). Called on user
* "Close" / navigate-away. Leaves the per-recipe partition intact so a
* re-mount within the ACL window is fast.
*/
export async function unmountSandboxUiView(
reason: SandboxUiReleaseReason = 'closed'
): Promise<void> {
mountGeneration += 1
teardownActive(reason)
}
/**
* Move/resize the active view. The renderer fires this on resize / scroll /
* sidebar-collapse so the embed visually tracks its slot div.
*/
export function setSandboxUiBounds(bounds: SandboxUiBounds): void {
if (!active) return
active.view.setBounds(toViewBounds(bounds, active.parentWindow))
}
/**
* Hide the native WebContentsView while renderer-owned overlays are open.
* WebContentsView always paints above the renderer DOM regardless of CSS
* z-index, so visibility is the reliable way to let menus and toasts win.
*/
export function setSandboxUiVisible(visible: boolean): void {
if (!active) return
active.view.setVisible(visible)
}
type FindableSandboxWebContents = Pick<
WebContentsView['webContents'],
'findInPage' | 'on' | 'removeListener'
>
export function beginSandboxUiFind(
webContents: FindableSandboxWebContents,
query: string,
options: { forward: boolean; findNext: boolean },
onResult: (result: SandboxUiFindResult) => void,
isCurrent: () => boolean = () => true
): { requestId: number; cleanup: () => void } {
let requestId: number | null = null
const pendingResults: Electron.FoundInPageResult[] = []
const deliver = (result: Electron.FoundInPageResult) => {
if (requestId === null) {
pendingResults.push(result)
return
}
if (!isCurrent() || result.requestId !== requestId) return
onResult({
requestId: result.requestId,
activeMatchOrdinal: result.activeMatchOrdinal,
matches: result.matches,
finalUpdate: result.finalUpdate,
})
}
const listener = (_event: Electron.Event, result: Electron.FoundInPageResult) => deliver(result)
webContents.on('found-in-page', listener)
requestId = webContents.findInPage(query, options)
for (const result of pendingResults.splice(0)) deliver(result)
return {
requestId,
cleanup: () => webContents.removeListener('found-in-page', listener),
}
}
export function findInActiveSandboxUi(
query: string,
operation: SandboxUiFindOperation,
clientRequestId: number,
onResult: (result: SandboxUiFindResult) => void
): SandboxUiFindStartResult {
if (!active || active.view.webContents.isDestroyed()) {
return { status: 'unavailable', reason: 'no-active-view' }
}
const current = active
if (!current.documentReady) {
return { status: 'unavailable', reason: 'document-loading' }
}
const continuing = operation !== 'start'
if (
continuing &&
(!current.findSession ||
!current.findSession.complete ||
current.findSession.query !== query ||
current.findSession.clientRequestId !== clientRequestId ||
current.findSession.documentGeneration !== current.documentGeneration)
) {
return { status: 'unavailable', reason: 'no-session' }
}
const webContents = current.view.webContents
current.cleanupFindResults?.()
if (operation === 'start') webContents.stopFindInPage('clearSelection')
const options = sandboxFindOptionsForOperation(operation)
let completedSynchronously = false
const documentGeneration = current.documentGeneration
const resultGate = createSandboxFindResultGate(result => {
if (result.finalUpdate && active === current) {
completedSynchronously = true
if (current.findSession?.nativeRequestId === result.requestId) {
current.findSession.complete = true
}
}
onResult(result)
})
const session = beginSandboxUiFind(
webContents,
query,
options,
resultGate.accept,
() =>
active === current &&
current.documentReady &&
documentGeneration === current.documentGeneration
)
current.cleanupFindResults = () => {
resultGate.dispose()
session.cleanup()
}
current.findSession = {
query,
clientRequestId,
documentGeneration,
nativeRequestId: session.requestId,
complete: completedSynchronously,
}
return { status: 'started', requestId: session.requestId }
}
export function stopActiveSandboxUiFind(): void {
if (!active) return
active.cleanupFindResults?.()
active.cleanupFindResults = undefined
active.findSession = undefined
if (!active.view.webContents.isDestroyed()) {
active.view.webContents.stopFindInPage('clearSelection')
}
}
export function focusActiveSandboxUi(): boolean {
if (!active || active.view.webContents.isDestroyed()) return false
active.view.webContents.focus()
return true
}
export async function captureSandboxUiPreview(): Promise<string | null> {
if (!active) return null
if (active.view.webContents.isDestroyed()) return null
const image = await active.view.webContents.capturePage()
if (image.isEmpty()) return null
return image.toDataURL()
}
/**
* Hard-reload an embed's webContents in place. Pure + injectable so the
* decision (skip a torn-down view, otherwise cache-busting reload) is unit
* tested without Electron. Returns whether a reload was actually issued.
*
* `reloadIgnoringCache` is the browser "hard refresh": it re-issues the
* navigation with no-cache request headers so freshly-arrived server data
* (e.g. a new inbox item) is fetched instead of repainting a stale
* HTTP-cached response — the same stale-pod concern the mount path guards
* with `clearCache()`.
*/
export function reloadSandboxUiWebContents(
webContents: { isDestroyed(): boolean; reloadIgnoringCache(): void } | null | undefined
): boolean {
if (!webContents || webContents.isDestroyed()) return false
webContents.reloadIgnoringCache()
return true
}
/**
* Reload the active embed in place, keeping its view, session and refresh loop.
* Used by the user-facing Refresh of a healthy view and by the session refresh
* once it has re-minted the cookie after the document came back 401. No-op when
* nothing is mounted or the view was already torn down.
*/
export function reloadActiveSandboxUiView(): void {
reloadSandboxUiWebContents(active?.view.webContents)
}
export type SandboxUiOauthCompletedPayload = {
oauthClientId: string
provider: string
}
/**
* Spec §9.9 — push the OAuth completion envelope into the active embed.
* Called by `main.ts`'s `open-url` handler after the provider redirect
* lands in the OS browser, control-api stores the grant, and the success
* page bounces to `clerum://oauth-completed`. The embed preload exposes
* this as `clerum.onOauthCompleted(callback)` to recipe JS.
*
* No-op when no embed is mounted (deep-link arrives after the user closed
* the embed). The recipe can re-trigger Connect if it cares.
*/
export function dispatchSandboxUiOauthCompleted(payload: SandboxUiOauthCompletedPayload): void {
if (!active) return
if (active.view.webContents.isDestroyed()) return
active.view.webContents.send('clerum:sandbox-ui:oauth-completed', payload)
}