Skip to content

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

TypeScript
18.8 KB
Raw Blame
/**
 * The capability catalog (spec §6).
 *
 * One immutable descriptor per capability. `minimize` is MANDATORY, not an
 * optional passthrough: adding a capability must force an explicit decision
 * about what the plugin sees. A `minimize` that returns its input unchanged is
 * a review finding, not a shortcut.
 *
 * Every provider reaches upstream through the user's OWN session (the narrow
 * `PluginSdkDataSource` view of AppService), so control-api authorizes exactly
 * as it does for the Desktop's own pages. Consent is an additional gate on top
 * of the user's ACL, never a substitute for it.
 */
import type {
  GfsAccessibleResourcesPage,
  GfsChildrenPage,
  ResolvedGfsResource,
} from './gfs/uriHandler.js'
import type { PluginCapabilityTier, PluginTheme } from './pluginSdkProtocol.js'
import type {
  AccessCatalog,
  AgentWithMcpServers,
  RpcAllowedServersResult,
  SessionState,
} from './types.js'

/** Image bytes ceiling, matching the Desktop's own GFS preview limit. */
export const PLUGIN_GFS_IMAGE_MAX_BYTES = 10 * 1024 * 1024
export const PLUGIN_GFS_TEXT_MAX_BYTES = 2 * 1024 * 1024

/**
 * Renderable image types. `image/svg+xml` is deliberately ABSENT: an SVG in an
 * `<img>` cannot execute script, but it can pull external resources and is a
 * standing parser-bug surface. A plugin that wants vector art ships it in its
 * own bundle.
 */
export const PLUGIN_GFS_IMAGE_MIME_TYPES = [
  'image/png',
  'image/jpeg',
  'image/gif',
  'image/webp',
  'image/avif',
] as const

/** Magic-byte prefixes, so a `.png` whose bytes are not a PNG is refused. */
const IMAGE_MAGIC: Array<{ mime: string; test: (b: Buffer) => boolean }> = [
  {
    mime: 'image/png',
    test: b =>
      b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])),
  },
  { mime: 'image/jpeg', test: b => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
  { mime: 'image/gif', test: b => b.subarray(0, 6).toString('ascii').startsWith('GIF8') },
  {
    mime: 'image/webp',
    test: b =>
      b.subarray(0, 4).toString('ascii') === 'RIFF' &&
      b.subarray(8, 12).toString('ascii') === 'WEBP',
  },
  {
    mime: 'image/avif',
    test: b =>
      b.subarray(4, 8).toString('ascii') === 'ftyp' &&
      b.subarray(8, 12).toString('ascii').startsWith('avi'),
  },
]

export function detectImageMime(bytes: Buffer): string | null {
  for (const entry of IMAGE_MAGIC) {
    try {
      if (entry.test(bytes)) return entry.mime
    } catch {
      // A file shorter than a magic prefix simply is not that format.
    }
  }
  return null
}

/** The narrow slice of AppService a provider may touch. Keeps tests Electron-free. */
export interface PluginSdkDataSource {
  getSessionState(): Promise<SessionState>
  listMyAgents(): Promise<AgentWithMcpServers[]>
  getAccessCatalog(): Promise<AccessCatalog>
  listAccessibleMcpServers(): Promise<RpcAllowedServersResult>
  listAccessibleGfsResources(drive?: string, cursor?: string): Promise<GfsAccessibleResourcesPage>
  listGfsChildren(resourceId: string, drive?: string, cursor?: string): Promise<GfsChildrenPage>
  downloadGfsUri(uri: string): Promise<{ resource: ResolvedGfsResource; bytes: ArrayBuffer }>
  getPluginTheme(): PluginTheme
  openGfsResource(input: { uri: string }): Promise<{ opened: boolean; reason?: string }>
  showPluginNotification(input: {
    pluginId: string
    pluginTitle: string
    title: string
    body?: string
    ref?: string
  }): Promise<{ delivered: boolean; reason?: 'suppressed' | 'unsupported' }>
}

export type ProviderContext = {
  source: PluginSdkDataSource
  pluginId: string
  pluginTitle: string
  userId: string
}

export type CapabilityDescriptor = {
  id: string
  /** Bump when the payload widens; older grants stop covering it (spec §9.6). */
  descriptorVersion: number
  requiresConsent: boolean
  consent: {
    title: string
    dataDescription: string
    tier: PluginCapabilityTier
  }
  limits: { perMinute: number; perHour: number; maxResponseBytes: number }
  /** Milliseconds a result may be reused. 0 disables caching. */
  cacheTtlMs: number
  validate: (raw: unknown) => Record<string, unknown>
  run: (ctx: ProviderContext, params: Record<string, unknown>) => Promise<unknown>
}

export class CapabilityInputError extends Error {}
export class CapabilityNotFoundError extends Error {}
export class CapabilityTooLargeError extends Error {}

function noParams(raw: unknown): Record<string, unknown> {
  if (raw === undefined || raw === null) return {}
  if (typeof raw !== 'object' || Array.isArray(raw)) {
    throw new CapabilityInputError('this capability takes no parameters')
  }
  const keys = Object.keys(raw as Record<string, unknown>)
  if (keys.length > 0) {
    throw new CapabilityInputError(`unexpected parameter: ${keys[0]}`)
  }
  return {}
}

function optionalString(value: unknown, field: string, maxLength: number): string | undefined {
  if (value === undefined || value === null || value === '') return undefined
  if (typeof value !== 'string') throw new CapabilityInputError(`${field} must be a string`)
  if (value.length > maxLength) throw new CapabilityInputError(`${field} is too long`)
  return value
}

function requiredString(value: unknown, field: string, maxLength: number): string {
  const parsed = optionalString(value, field, maxLength)
  if (!parsed) throw new CapabilityInputError(`${field} is required`)
  return parsed
}

function allowKeys(raw: unknown, allowed: string[]): Record<string, unknown> {
  if (raw === undefined || raw === null) return {}
  if (typeof raw !== 'object' || Array.isArray(raw)) {
    throw new CapabilityInputError('params must be an object')
  }
  const record = raw as Record<string, unknown>
  for (const key of Object.keys(record)) {
    if (!allowed.includes(key)) throw new CapabilityInputError(`unexpected parameter: ${key}`)
  }
  return record
}

/** Strip control characters from user-visible plugin-supplied text. */
function plainText(value: string): string {
  return value.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
}

export const CAPABILITIES: Record<string, CapabilityDescriptor> = {
  'identity.read': {
    id: 'identity.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See who you are',
      dataDescription: 'Your name, email address, and user id.',
      tier: 'personal',
    },
    limits: { perMinute: 10, perHour: 60, maxResponseBytes: 4 * 1024 },
    cacheTtlMs: 60_000,
    validate: noParams,
    run: async ctx => {
      const state = await ctx.source.getSessionState()
      if (!state.authenticated || !state.me) throw new CapabilityNotFoundError('no session')
      // `picture` is omitted on purpose: it is a remote URL and the embed CSP is
      // `img-src 'self' data:`, so the plugin could not render it — shipping it
      // would leak an identifier for zero benefit (spec §6.1).
      return { userId: state.me.id, email: state.me.email, name: state.me.name }
    },
  },

  'org.read': {
    id: 'org.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See your current team',
      dataDescription: 'Its name and your role in it.',
      tier: 'workspace',
    },
    limits: { perMinute: 10, perHour: 60, maxResponseBytes: 4 * 1024 },
    cacheTtlMs: 60_000,
    validate: noParams,
    run: async ctx => {
      const state = await ctx.source.getSessionState()
      if (!state.authenticated || !state.me) throw new CapabilityNotFoundError('no session')
      return {
        teamId: state.me.teamId,
        teamName: state.me.teamName,
        role: state.me.role,
      }
    },
  },

  'agents.read': {
    id: 'agents.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See the agents you have access to',
      dataDescription: 'Their names and which MCP servers they use.',
      tier: 'workspace',
    },
    limits: { perMinute: 10, perHour: 120, maxResponseBytes: 256 * 1024 },
    cacheTtlMs: 30_000,
    validate: noParams,
    run: async ctx => {
      const agents = await ctx.source.listMyAgents()
      return {
        agents: agents.map(agent => ({
          // `gfsSubject.id` is the stable grant-target id (`1st:<ns>/<name>`);
          // older servers omit it, so `name` is the fallback identity.
          id: agent.gfsSubject?.id ?? agent.name,
          name: agent.name,
          contextRef: agent.contextRef ?? null,
          provider: agent.provider ?? null,
          mcpServers: (agent.mcpServers ?? []).map(server => server.name),
        })),
      }
    },
  },

  'contexts.read': {
    id: 'contexts.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See the contexts you have access to',
      dataDescription: 'The names of the contexts available to you.',
      tier: 'workspace',
    },
    limits: { perMinute: 10, perHour: 120, maxResponseBytes: 64 * 1024 },
    cacheTtlMs: 30_000,
    validate: noParams,
    run: async ctx => {
      const catalog = await ctx.source.getAccessCatalog()
      const userIds = new Set(catalog.userContextIds ?? [])
      const seen = new Set<string>()
      const contexts: Array<{ id: string; scope: 'user' | 'team' }> = []
      for (const id of [...(catalog.userContextIds ?? []), ...(catalog.teamContextIds ?? [])]) {
        if (seen.has(id)) continue
        seen.add(id)
        contexts.push({ id, scope: userIds.has(id) ? 'user' : 'team' })
      }
      return { contexts }
    },
  },

  'mcp.read': {
    id: 'mcp.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See the MCP servers you have access to',
      dataDescription: 'Their names and which of your agents can call them.',
      tier: 'workspace',
    },
    limits: { perMinute: 10, perHour: 120, maxResponseBytes: 128 * 1024 },
    cacheTtlMs: 30_000,
    validate: noParams,
    run: async ctx => {
      const [result, catalog] = await Promise.all([
        ctx.source.listAccessibleMcpServers(),
        ctx.source.getAccessCatalog().catch(() => null),
      ])
      const byServer = new Map<string, string[]>()
      for (const [agent, servers] of Object.entries(catalog?.mcpServersByAgent ?? {})) {
        for (const server of servers ?? []) {
          byServer.set(server, [...(byServer.get(server) ?? []), agent])
        }
      }
      // Every `url` is dropped. A cluster-internal URL is infrastructure detail
      // the embed cannot even reach under `connect-src 'self'`, and shipping it
      // would turn a read capability into a lateral-movement hint (spec §6.5).
      return {
        servers: (result.servers ?? []).map(server => ({
          name: server.name,
          agents: byServer.get(server.name) ?? [],
        })),
      }
    },
  },

  'gfs.list': {
    id: 'gfs.list',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'See the shared files you have access to',
      dataDescription: 'Their names, folders, and sizes. It will not be able to open them.',
      tier: 'workspace',
    },
    limits: { perMinute: 30, perHour: 600, maxResponseBytes: 512 * 1024 },
    cacheTtlMs: 0,
    validate: raw => {
      const record = allowKeys(raw, ['drive', 'resourceId', 'cursor'])
      return {
        drive: optionalString(record.drive, 'drive', 64),
        resourceId: optionalString(record.resourceId, 'resourceId', 128),
        cursor: optionalString(record.cursor, 'cursor', 512),
      }
    },
    run: async (ctx, params) => {
      const drive = params.drive as string | undefined
      const resourceId = params.resourceId as string | undefined
      const cursor = params.cursor as string | undefined
      const page = resourceId
        ? await ctx.source.listGfsChildren(resourceId, drive, cursor)
        : await ctx.source.listAccessibleGfsResources(drive, cursor)
      return {
        items: (page.items ?? []).map(item => ({
          resourceId: item.resourceId,
          gfsUri: item.gfsUri,
          name: item.name,
          kind: item.kind,
          bytes: typeof item.bytes === 'number' ? item.bytes : null,
          version: item.version,
        })),
        nextCursor: page.nextCursor ?? null,
      }
    },
  },

  'gfs.read': {
    id: 'gfs.read',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'Open shared files you have access to',
      dataDescription: 'It will be able to read the contents of any file you can read.',
      tier: 'personal',
    },
    limits: { perMinute: 20, perHour: 300, maxResponseBytes: PLUGIN_GFS_IMAGE_MAX_BYTES * 2 },
    cacheTtlMs: 0,
    validate: raw => {
      const record = allowKeys(raw, ['uri', 'as'])
      const uri = requiredString(record.uri, 'uri', 2048)
      if (!uri.startsWith('gfs://')) throw new CapabilityInputError('uri must be a gfs:// link')
      const as = requiredString(record.as, 'as', 16)
      if (as !== 'text' && as !== 'dataUrl') {
        throw new CapabilityInputError("as must be 'text' or 'dataUrl'")
      }
      return { uri, as }
    },
    run: async (ctx, params) => {
      const uri = params.uri as string
      const as = params.as as 'text' | 'dataUrl'
      const { resource, bytes } = await ctx.source.downloadGfsUri(uri)
      const buffer = Buffer.from(bytes)
      const base = {
        gfsUri: resource.gfsUri,
        name: resource.name,
        bytes: buffer.byteLength,
      }

      if (as === 'dataUrl') {
        if (buffer.byteLength > PLUGIN_GFS_IMAGE_MAX_BYTES) {
          throw new CapabilityTooLargeError('image is larger than 10 MB')
        }
        // Trust the bytes, not the name. The declared MIME must be renderable
        // AND the magic bytes must agree (spec §6.6, T12).
        const detected = detectImageMime(buffer)
        if (!detected || !PLUGIN_GFS_IMAGE_MIME_TYPES.includes(detected as never)) {
          throw new CapabilityInputError(
            'file is not a renderable image (png, jpeg, gif, webp, avif)'
          )
        }
        return {
          ...base,
          as,
          mimeType: detected,
          dataUrl: `data:${detected};base64,${buffer.toString('base64')}`,
        }
      }

      if (buffer.byteLength > PLUGIN_GFS_TEXT_MAX_BYTES) {
        throw new CapabilityTooLargeError('file is larger than 2 MB')
      }
      const text = buffer.toString('utf8')
      // A lossy decode means the bytes were not UTF-8; returning replacement
      // characters would silently corrupt whatever the plugin does next.
      if (text.includes('\uFFFD')) {
        throw new CapabilityInputError('file is not valid UTF-8 text')
      }
      return { ...base, as, mimeType: 'text/plain', text }
    },
  },

  'gfs.open': {
    id: 'gfs.open',
    descriptorVersion: 1,
    // Unscoped, and the second capability to qualify. The rule from §6.7 is that
    // `requiresConsent: false` needs the response to carry nothing about the
    // user; this one adds the other half: the ACTION must be unmissable. The
    // plugin gets back a bare `{ opened }` and nothing else — not the file's
    // name, size, contents, nor WHY a failure happened (the `run` below drops the
    // internal `reason`, so absent/unauthorized/transient all collapse to
    // `opened: false`). What happens is that the Desktop's own viewer opens, over
    // the plugin, showing the user a file they already have access to, resolved
    // with their session. Prompting "may this plugin show you your own file?"
    // would be noise in front of an action the user can see.
    requiresConsent: false,
    consent: {
      title: 'Open a shared file in the Evenfire viewer',
      dataDescription: 'Shows you a file you already have access to. The plugin does not see it.',
      tier: 'ambient',
    },
    // Tighter than the reads: this one paints over the user's screen. A plugin
    // that spams it hides itself behind viewers, so it is largely self-limiting,
    // but the budget makes that bounded rather than merely awkward.
    limits: { perMinute: 6, perHour: 60, maxResponseBytes: 1024 },
    cacheTtlMs: 0,
    validate: raw => {
      const record = allowKeys(raw, ['uri'])
      const uri = requiredString(record.uri, 'uri', 2048)
      if (!uri.startsWith('gfs://')) throw new CapabilityInputError('uri must be a gfs:// link')
      return { uri }
    },
    run: async (ctx, params) => {
      // Never forward the internal `reason` to the plugin: it would turn a
      // failed open into an accessibility oracle (not_found vs unavailable).
      const result = await ctx.source.openGfsResource({ uri: params.uri as string })
      return { opened: result.opened }
    },
  },

  'theme.read': {
    id: 'theme.read',
    descriptorVersion: 1,
    // The ONE unscoped capability. Permitted only because the response says
    // nothing about the user, their org, or their data — only about the
    // Desktop's own presentation (spec §6.7). It is still audited, and still
    // listed on the plugin's Settings row.
    requiresConsent: false,
    consent: {
      title: 'See the app appearance',
      dataDescription: 'Whether the desktop app is in light or dark mode.',
      tier: 'ambient',
    },
    limits: { perMinute: 60, perHour: 600, maxResponseBytes: 1024 },
    cacheTtlMs: 0,
    validate: noParams,
    run: async ctx => ({ theme: ctx.source.getPluginTheme() }),
  },

  'notifications.notify': {
    id: 'notifications.notify',
    descriptorVersion: 1,
    requiresConsent: true,
    consent: {
      title: 'Send you notifications',
      dataDescription: 'It will be able to get your attention while you work elsewhere.',
      tier: 'workspace',
    },
    limits: { perMinute: 2, perHour: 20, maxResponseBytes: 1024 },
    cacheTtlMs: 0,
    validate: raw => {
      const record = allowKeys(raw, ['title', 'body', 'ref'])
      const title = plainText(requiredString(record.title, 'title', 120))
      if (!title) throw new CapabilityInputError('title is required')
      const body = optionalString(record.body, 'body', 400)
      const ref = optionalString(record.ref, 'ref', 256)
      return { title, body: body ? plainText(body) : undefined, ref }
    },
    run: async (ctx, params) =>
      ctx.source.showPluginNotification({
        pluginId: ctx.pluginId,
        pluginTitle: ctx.pluginTitle,
        title: params.title as string,
        body: params.body as string | undefined,
        ref: params.ref as string | undefined,
      }),
  },
}

export const CAPABILITY_IDS = Object.keys(CAPABILITIES)

export function getCapability(id: string): CapabilityDescriptor | null {
  return Object.prototype.hasOwnProperty.call(CAPABILITIES, id) ? (CAPABILITIES[id] ?? null) : null
}

/** Prompt row ordering: most sensitive first, never buried at the bottom. */
const TIER_ORDER: Record<PluginCapabilityTier, number> = { personal: 0, workspace: 1, ambient: 2 }

export function sortCapabilitiesForPrompt(ids: string[]): string[] {
  return [...ids].sort((a, b) => {
    const left = getCapability(a)
    const right = getCapability(b)
    const delta =
      TIER_ORDER[left?.consent.tier ?? 'workspace'] - TIER_ORDER[right?.consent.tier ?? 'workspace']
    return delta !== 0 ? delta : a.localeCompare(b)
  })
}