Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
15.6 KB
Raw Blame
/**
 * Electron wiring for the plugin SDK (spec §4).
 *
 * Everything Electron-shaped lives here so the broker, gate, store, and
 * capability catalog stay testable without an Electron runtime. This module is
 * the only one in the SDK that knows about BrowserWindow, Notification, or the
 * sandbox-ui driver.
 */
import { BrowserWindow, Notification, app } from 'electron'
import path from 'node:path'
import type { AppService } from './appService.js'
import { getActiveEnvKey } from './config.js'
import { type AuditEntry, PluginAuditLog } from './pluginAuditLog.js'
import { PluginConsentGate } from './pluginConsentGate.js'
import { type ConsentGrant, LocalConsentStore } from './pluginConsentStore.js'
import { PluginRateLimiter } from './pluginRateLimiter.js'
import { PluginSdkBroker } from './pluginSdkBroker.js'
import { CAPABILITIES, type PluginSdkDataSource, getCapability } from './pluginSdkCapabilities.js'
import {
  PLUGIN_SDK_CONSENT_CANCELLED_CHANNEL,
  PLUGIN_SDK_CONSENT_REQUESTED_CHANNEL,
  PLUGIN_SDK_EVENT_CHANNEL,
  type PluginGrantView,
  type PluginSdkEvent,
  type PluginTheme,
} from './pluginSdkProtocol.js'
import {
  type PinnedPluginSurface,
  allPinnedSurfaces,
  pinPluginSurface,
  resolvePluginSurface,
  surfacesForPlugin,
  unpinPluginSurface,
  unpinPluginSurfacesOfKind,
} from './pluginSurfaceRegistry.js'
import { PluginThemeStore } from './pluginThemeStore.js'

type RuntimeDeps = {
  service: AppService
  getMainWindow: () => BrowserWindow | null
  /** Overridable for tests. */
  userDataDir?: string
}

let runtime: PluginSdkRuntime | null = null

export class PluginSdkRuntime {
  readonly store: LocalConsentStore
  readonly audit: PluginAuditLog
  readonly limiter: PluginRateLimiter
  readonly gate: PluginConsentGate
  readonly broker: PluginSdkBroker
  readonly theme: PluginThemeStore

  /** pluginId → human title, learned at mount, used for prompts + notifications. */
  private readonly titles = new Map<string, string>()

  constructor(private readonly deps: RuntimeDeps) {
    const baseDir = deps.userDataDir ?? app.getPath('userData')
    this.store = new LocalConsentStore(path.join(baseDir, 'plugin-consent'))
    this.audit = new PluginAuditLog(path.join(baseDir, 'plugin-audit'))
    this.limiter = new PluginRateLimiter()
    this.theme = new PluginThemeStore(baseDir)

    this.gate = new PluginConsentGate({
      store: this.store,
      presentPrompt: request => this.sendToRenderer(PLUGIN_SDK_CONSENT_REQUESTED_CHANNEL, request),
      cancelPrompt: promptId =>
        this.sendToRenderer(PLUGIN_SDK_CONSENT_CANCELLED_CHANNEL, { promptId }),
      setSurfaceVisible: visible => this.deps.service.setSandboxUiVisible(visible),
      isWindowReady: () => {
        const win = this.deps.getMainWindow()
        if (!win || win.isDestroyed()) return false
        return win.isVisible() && !win.isMinimized() && win.isFocused()
      },
    })

    this.broker = new PluginSdkBroker({
      source: this.dataSource(),
      store: this.store,
      gate: this.gate,
      limiter: this.limiter,
      audit: this.audit,
      getEnvKey: () => getActiveEnvKey(),
      getUserId: () => this.currentUserId(),
    })

    this.theme.onChange(theme => {
      this.broadcastEvent({ type: 'theme.changed', theme })
    })
    void this.theme.load()
  }

  private currentUserId(): string | null {
    const metadata = this.deps.service.getTokenMetadata()
    if (!metadata.hasSession) return null
    return this.deps.service.getCachedUserId()
  }

  private sendToRenderer(channel: string, payload: unknown): void {
    const win = this.deps.getMainWindow()
    if (!win || win.isDestroyed()) return
    win.webContents.send(channel, payload)
  }

  /** Deliver an event to every mounted surface of one plugin. */
  private sendEventToPlugin(pluginId: string, event: PluginSdkEvent): void {
    for (const surface of surfacesForPlugin(pluginId)) {
      const contents = webContentsById(surface.webContentsId)
      if (!contents) continue
      contents.send(PLUGIN_SDK_EVENT_CHANNEL, event)
    }
  }

  /** Deliver an event to every mounted plugin surface. */
  private broadcastEvent(event: PluginSdkEvent): void {
    for (const surface of allPinnedSurfaces()) {
      const contents = webContentsById(surface.webContentsId)
      if (!contents) continue
      contents.send(PLUGIN_SDK_EVENT_CHANNEL, event)
    }
  }

  // ── Surface lifecycle ──────────────────────────────────────────────

  pinSandboxUiSurface(input: {
    pluginId: string
    pluginTitle: string
    webContentsId: number
    generation: number
  }): void {
    // The driver tears the previous embed down inside the next mount, so clear
    // the kind first — a stale pin would otherwise outlive its webContents.
    for (const dropped of unpinPluginSurfacesOfKind('sandbox-ui-embed')) {
      this.releasePlugin(dropped.pluginId)
    }
    this.titles.set(input.pluginId, input.pluginTitle)
    pinPluginSurface({ ...input, surface: 'sandbox-ui-embed' })
  }

  unpinSandboxUiSurface(webContentsId: number): void {
    const surface = resolvePluginSurface(webContentsId)
    unpinPluginSurface(webContentsId)
    if (surface) this.releasePlugin(surface.pluginId)
  }

  unpinAllSandboxUiSurfaces(): void {
    for (const dropped of unpinPluginSurfacesOfKind('sandbox-ui-embed')) {
      this.releasePlugin(dropped.pluginId)
    }
  }

  /** Per-mount state dies with the mount: denials, prompt budget, rate budget, cache. */
  private releasePlugin(pluginId: string): void {
    this.gate.resetPlugin(pluginId)
    this.limiter.reset(pluginId)
    this.broker.invalidateCache(pluginId)
  }

  // ── Session / theme signals ────────────────────────────────────────

  notifySessionChanged(authenticated: boolean): void {
    this.broker.invalidateCache()
    this.broadcastEvent({ type: 'session.changed', authenticated })
  }

  setTheme(theme: unknown): void {
    this.theme.set(theme)
  }

  // ── Settings surface (trusted renderer) ────────────────────────────

  async listGrants(): Promise<PluginGrantView[]> {
    const userId = this.currentUserId()
    if (!userId) return []
    const grants = await this.store.list(getActiveEnvKey(), userId)
    return grants.flatMap(grant => {
      const descriptor = getCapability(grant.capability)
      if (!descriptor) return []
      return [
        {
          pluginId: grant.pluginId,
          pluginTitle:
            this.titles.get(grant.pluginId) ?? grant.pluginId.split('/').pop() ?? grant.pluginId,
          capability: grant.capability,
          title: descriptor.consent.title,
          dataDescription: descriptor.consent.dataDescription,
          tier: descriptor.consent.tier,
          grantedAt: grant.grantedAt,
          lastUsedAt: grant.lastUsedAt,
        },
      ]
    })
  }

  async revokeGrant(pluginId: string, capability: string): Promise<void> {
    const userId = this.currentUserId()
    if (!userId) throw new Error('no active session')
    const envKey = getActiveEnvKey()
    await this.store.revoke({ envKey, userId, pluginId, capability })
    this.broker.invalidateCache(pluginId)
    await this.audit.append(envKey, {
      ts: new Date().toISOString(),
      userId,
      pluginId,
      capability,
      outcome: 'revoked',
      consent: 'user_revoked',
    })
    // Immediate, so a running plugin drops back to its unauthenticated
    // rendering instead of discovering the revocation on its next call.
    this.sendEventToPlugin(pluginId, { type: 'permission.changed', capability, granted: false })
  }

  async revokeAllForPlugin(pluginId: string): Promise<void> {
    const userId = this.currentUserId()
    if (!userId) throw new Error('no active session')
    const envKey = getActiveEnvKey()
    const existing = (await this.store.list(envKey, userId)).filter(
      grant => grant.pluginId === pluginId
    )
    await this.store.revokeAllForPlugin(envKey, userId, pluginId)
    this.broker.invalidateCache(pluginId)
    for (const grant of existing) {
      await this.audit.append(envKey, {
        ts: new Date().toISOString(),
        userId,
        pluginId,
        capability: grant.capability,
        outcome: 'revoked',
        consent: 'user_revoked',
      })
      this.sendEventToPlugin(pluginId, {
        type: 'permission.changed',
        capability: grant.capability,
        granted: false,
      })
    }
  }

  async readAudit(options?: { limit?: number; includeAmbient?: boolean }): Promise<AuditEntry[]> {
    const userId = this.currentUserId()
    if (!userId) return []
    const entries = await this.audit.read(getActiveEnvKey(), {
      limit: options?.limit ?? 200,
      userId,
    })
    if (options?.includeAmbient) return entries
    // `theme.read` fires constantly; including it by default would drown the
    // entries a user actually opened this view to see (spec §10.3).
    return entries.filter(entry => getCapability(entry.capability)?.consent.tier !== 'ambient')
  }

  async clearAudit(): Promise<void> {
    await this.audit.clear(getActiveEnvKey())
  }

  resolveConsentPrompt(promptId: string, allowed: string[]): boolean {
    return this.gate.resolvePrompt(promptId, allowed)
  }

  /** Prune grants for plugins the user can no longer reach (spec §10.5). */
  async pruneGrantsToPlugins(pluginIds: Set<string>): Promise<void> {
    const userId = this.currentUserId()
    if (!userId) return
    await this.store.pruneToPlugins(getActiveEnvKey(), userId, pluginIds)
  }

  // ── Data source ────────────────────────────────────────────────────

  private dataSource(): PluginSdkDataSource {
    const service = this.deps.service
    return {
      getSessionState: () => service.getSessionState(),
      listMyAgents: () => service.listMyAgents(),
      getAccessCatalog: () => service.getAccessCatalog(),
      listAccessibleMcpServers: () => service.listAccessibleMcpServers(),
      listAccessibleGfsResources: (drive, cursor) =>
        service.listAccessibleGfsResources(drive, cursor),
      listGfsChildren: (resourceId, drive, cursor) =>
        service.listGfsChildren(resourceId, drive, cursor),
      downloadGfsUri: uri => service.downloadGfsUri(uri),
      getPluginTheme: () => this.theme.get(),
      openGfsResource: input => this.openGfsResource(input.uri),
      showPluginNotification: input => this.showNotification(input),
    }
  }

  /**
   * Resolve a `gfs://` link with the USER's session and hand it to the trusted
   * renderer to display. The plugin gets back only whether it opened — never the
   * name, size, or bytes. The internal `reason` returned here is for the audit
   * line and the navigation path; the `gfs.open` capability drops it before the
   * plugin sees it, so absent and unauthorized both read as `opened: false`.
   * A resolvable link IS still distinguishable from a non-resolvable one, so this
   * is a narrow accessibility signal — bounded by the 6/min budget, unguessable
   * resource ids, a live user session, and a viewer that paints over the plugin
   * on every hit. Reads over that bound: mark the capability `requiresConsent`.
   *
   * Reached two ways, both landing here so they share the rate budget and the
   * audit line: `clerum.gfs.open(uri)` through the broker, and a plain
   * `<a href="gfs://…">` intercepted by the embed's navigation policy.
   */
  async openGfsResource(uri: string): Promise<{ opened: boolean; reason?: string }> {
    const link = String(uri || '').trim()
    if (!link.startsWith('gfs://')) return { opened: false, reason: 'invalid_uri' }
    const win = this.deps.getMainWindow()
    if (!win || win.isDestroyed()) return { opened: false, reason: 'unavailable' }

    let resource
    try {
      resource = await this.deps.service.resolveGfsUri(link)
    } catch (err) {
      console.warn('[PluginSDK] gfs.open resolve failed:', err)
      return { opened: false, reason: 'not_found' }
    }

    this.sendToRenderer('pluginSdk:openGfsResource', {
      gfsUri: resource.gfsUri ?? link,
      name: resource.name,
      kind: resource.kind,
      bytes: typeof resource.bytes === 'number' ? resource.bytes : null,
      version: resource.version,
    })
    return { opened: true }
  }

  /**
   * Entry point for the `<a href="gfs://…">` path. The broker owns rate limiting
   * and auditing for `clerum.gfs.open`, so a link click has to route through it
   * too — otherwise a plugin could dodge the budget by rendering anchors.
   */
  async openGfsResourceFromNavigation(webContentsId: number, uri: string): Promise<void> {
    const result = await this.broker.request(webContentsId, {
      v: 1,
      capability: 'gfs.open',
      params: { uri },
    })
    if (!result.ok) {
      console.warn('[PluginSDK] gfs link open refused:', result.error.code)
    }
  }

  private async showNotification(input: {
    pluginId: string
    pluginTitle: string
    title: string
    body?: string
    ref?: string
  }): Promise<{ delivered: boolean; reason?: 'suppressed' | 'unsupported' }> {
    // Suppressed when the user is already looking at this plugin: interrupting
    // someone about the thing on their screen is noise, not attention.
    if (this.isPluginInForeground(input.pluginId)) {
      return { delivered: false, reason: 'suppressed' }
    }
    if (!Notification.isSupported()) return { delivered: false, reason: 'unsupported' }

    // Mandatory attribution — a plugin must never be able to look like Evenfire
    // itself or like another plugin (spec §6.8, T13).
    const notification = new Notification({
      title: `${input.pluginTitle} — ${input.title}`,
      ...(input.body ? { body: input.body } : {}),
    })
    notification.on('click', () => {
      const win = this.deps.getMainWindow()
      if (win && !win.isDestroyed()) {
        if (win.isMinimized()) win.restore()
        win.show()
        win.focus()
      }
      this.sendToRenderer('pluginSdk:notificationClicked', {
        pluginId: input.pluginId,
        ref: input.ref ?? null,
      })
      this.sendEventToPlugin(input.pluginId, {
        type: 'notification.clicked',
        ref: input.ref ?? null,
      })
    })
    notification.show()
    return { delivered: true }
  }

  private isPluginInForeground(pluginId: string): boolean {
    const win = this.deps.getMainWindow()
    if (!win || win.isDestroyed() || !win.isVisible() || win.isMinimized() || !win.isFocused()) {
      return false
    }
    return surfacesForPlugin(pluginId).some(surface => surface.surface === 'sandbox-ui-embed')
  }
}

function webContentsById(id: number): Electron.WebContents | null {
  for (const win of BrowserWindow.getAllWindows()) {
    for (const view of win.contentView?.children ?? []) {
      const contents = (view as unknown as { webContents?: Electron.WebContents }).webContents
      if (contents && !contents.isDestroyed() && contents.id === id) return contents
    }
    if (!win.isDestroyed() && win.webContents.id === id) return win.webContents
  }
  return null
}

export function initPluginSdkRuntime(deps: RuntimeDeps): PluginSdkRuntime {
  runtime = new PluginSdkRuntime(deps)
  return runtime
}

export function getPluginSdkRuntime(): PluginSdkRuntime {
  if (!runtime) throw new Error('plugin SDK runtime not initialized')
  return runtime
}

export function tryGetPluginSdkRuntime(): PluginSdkRuntime | null {
  return runtime
}

/** ONLY for tests. */
export function _resetPluginSdkRuntimeForTests(): void {
  runtime = null
}

export type { AuditEntry, ConsentGrant }
export { CAPABILITIES }
export type { PinnedPluginSurface, PluginTheme }