Skip to content

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

TypeScript
11.3 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import {
  CAPABILITIES,
  CapabilityInputError,
  CapabilityTooLargeError,
  PLUGIN_GFS_IMAGE_MAX_BYTES,
  type PluginSdkDataSource,
  type ProviderContext,
  detectImageMime,
  getCapability,
  sortCapabilitiesForPrompt,
} from '../pluginSdkCapabilities.js'

const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01])
const JPEG = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10])

function source(overrides: Partial<PluginSdkDataSource> = {}): PluginSdkDataSource {
  return {
    getSessionState: async () => ({
      authenticated: true,
      me: {
        id: 'u1',
        email: '[email protected]',
        name: 'A',
        picture: 'https://cdn.example/a.png',
        teamId: 't1',
        teamName: 'Acme',
        role: 'member',
      },
    }),
    listMyAgents: async () => [
      {
        name: 'scout',
        contextRef: 'context1',
        provider: 'claude',
        mcpServers: [{ name: 'search' }],
        gfsSubject: { type: 'host', id: '1st:ns/scout' },
      },
    ],
    getAccessCatalog: async () =>
      ({
        userContextIds: ['ctx-user'],
        teamContextIds: ['ctx-team', 'ctx-user'],
        mcpServersByAgent: { scout: ['search'] },
      }) as never,
    listAccessibleMcpServers: async () =>
      ({ servers: [{ name: 'search', url: 'http://internal:3000' }] }) as never,
    listAccessibleGfsResources: async () =>
      ({
        items: [
          {
            resourceId: 'r1',
            rid: 'r1',
            gfsUri: 'gfs://main/a.png',
            drive: 'main',
            parentResourceId: null,
            name: 'a.png',
            kind: 'file',
            path: '/a.png',
            version: 3,
            bytes: 10,
            sources: ['grant'],
            permissions: ['read'],
            coversDescendants: false,
          },
        ],
        nextCursor: null,
      }) as never,
    listGfsChildren: async () => ({ items: [], nextCursor: null }),
    downloadGfsUri: async () => ({
      resource: { gfsUri: 'gfs://main/a.png', name: 'a.png' } as never,
      bytes: PNG.buffer.slice(PNG.byteOffset, PNG.byteOffset + PNG.byteLength) as ArrayBuffer,
    }),
    getPluginTheme: () => 'light',
    openGfsResource: async () => ({ opened: true }),
    showPluginNotification: async () => ({ delivered: true }),
    ...overrides,
  }
}

function ctx(overrides: Partial<PluginSdkDataSource> = {}): ProviderContext {
  return {
    source: source(overrides),
    pluginId: 'ns/plugin',
    pluginTitle: 'Plugin',
    userId: 'u1',
  }
}

async function run(id: string, params: unknown = undefined, overrides = {}) {
  const descriptor = getCapability(id)
  if (!descriptor) throw new Error(`missing ${id}`)
  return descriptor.run(ctx(overrides), descriptor.validate(params))
}

describe('capability catalog invariants', () => {
  it('gives every capability consent copy and limits', () => {
    for (const [id, descriptor] of Object.entries(CAPABILITIES)) {
      expect(descriptor.id, id).toBe(id)
      expect(descriptor.consent.title.length, id).toBeGreaterThan(0)
      expect(descriptor.consent.dataDescription.length, id).toBeGreaterThan(0)
      expect(descriptor.limits.perMinute, id).toBeGreaterThan(0)
      expect(descriptor.limits.maxResponseBytes, id).toBeGreaterThan(0)
    }
  })

  it('keeps the consent-free set to exactly the two justified capabilities', () => {
    const unscoped = Object.values(CAPABILITIES)
      .filter(descriptor => !descriptor.requiresConsent)
      .map(descriptor => descriptor.id)
      .sort()
    // Any addition here is a decision to hand a plugin something without asking.
    // `theme.read` returns nothing about the user; `gfs.open` returns only
    // whether a viewer opened, and the action itself is unmissable on screen.
    expect(unscoped).toEqual(['gfs.open', 'theme.read'])
  })

  it('sorts prompt rows most-sensitive-first', () => {
    expect(sortCapabilitiesForPrompt(['theme.read', 'agents.read', 'identity.read'])).toEqual([
      'identity.read',
      'agents.read',
      'theme.read',
    ])
  })
})

describe('minimize contracts', () => {
  it('identity.read returns exactly three fields and drops the avatar URL', async () => {
    const result = await run('identity.read')
    expect(Object.keys(result as object).sort()).toEqual(['email', 'name', 'userId'])
  })

  it('org.read returns exactly the team triple', async () => {
    const result = await run('org.read')
    expect(Object.keys(result as object).sort()).toEqual(['role', 'teamId', 'teamName'])
  })

  it('agents.read flattens MCP servers to names and exposes a stable id', async () => {
    const result = (await run('agents.read')) as { agents: Array<Record<string, unknown>> }
    expect(result.agents[0]).toEqual({
      id: '1st:ns/scout',
      name: 'scout',
      contextRef: 'context1',
      provider: 'claude',
      mcpServers: ['search'],
    })
  })

  it('mcp.read never leaks a server URL', async () => {
    const result = (await run('mcp.read')) as { servers: Array<Record<string, unknown>> }
    expect(result.servers[0]).toEqual({ name: 'search', agents: ['scout'] })
    expect(JSON.stringify(result)).not.toContain('internal')
  })

  it('contexts.read labels a context present in both lists as the user’s', async () => {
    const result = (await run('contexts.read')) as {
      contexts: Array<{ id: string; scope: string }>
    }
    expect(result.contexts).toEqual([
      { id: 'ctx-user', scope: 'user' },
      { id: 'ctx-team', scope: 'team' },
    ])
  })

  it('gfs.list returns metadata only', async () => {
    const result = (await run('gfs.list', {})) as { items: Array<Record<string, unknown>> }
    expect(Object.keys(result.items[0] ?? {}).sort()).toEqual([
      'bytes',
      'gfsUri',
      'kind',
      'name',
      'resourceId',
      'version',
    ])
  })
})

describe('gfs.read', () => {
  it('returns a data: URI, because the embed CSP allows data: and not blob:', async () => {
    const result = (await run('gfs.read', { uri: 'gfs://main/a.png', as: 'dataUrl' })) as {
      dataUrl: string
      mimeType: string
    }
    expect(result.mimeType).toBe('image/png')
    expect(result.dataUrl.startsWith('data:image/png;base64,')).toBe(true)
  })

  it('refuses a file whose bytes are not the image it claims to be', async () => {
    const notAnImage = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"></svg>')
    await expect(
      run(
        'gfs.read',
        { uri: 'gfs://main/a.png', as: 'dataUrl' },
        {
          downloadGfsUri: async () => ({
            resource: { gfsUri: 'gfs://main/a.png', name: 'a.png' } as never,
            bytes: notAnImage.buffer.slice(
              notAnImage.byteOffset,
              notAnImage.byteOffset + notAnImage.byteLength
            ) as ArrayBuffer,
          }),
        }
      )
    ).rejects.toBeInstanceOf(CapabilityInputError)
  })

  it('refuses an image over the size ceiling', async () => {
    const huge = Buffer.concat([PNG, Buffer.alloc(PLUGIN_GFS_IMAGE_MAX_BYTES)])
    await expect(
      run(
        'gfs.read',
        { uri: 'gfs://main/a.png', as: 'dataUrl' },
        {
          downloadGfsUri: async () => ({
            resource: { gfsUri: 'gfs://main/a.png', name: 'a.png' } as never,
            bytes: huge.buffer.slice(
              huge.byteOffset,
              huge.byteOffset + huge.byteLength
            ) as ArrayBuffer,
          }),
        }
      )
    ).rejects.toBeInstanceOf(CapabilityTooLargeError)
  })

  it('rejects a non-gfs uri and an unknown mode at validation time', () => {
    const descriptor = getCapability('gfs.read')
    expect(() => descriptor?.validate({ uri: 'https://evil.example/x', as: 'dataUrl' })).toThrow()
    expect(() => descriptor?.validate({ uri: 'gfs://main/a', as: 'binary' })).toThrow()
    expect(() => descriptor?.validate({ uri: 'gfs://main/a', as: 'text', extra: 1 })).toThrow()
  })

  it('refuses bytes that are not valid UTF-8 in text mode', async () => {
    const binary = Buffer.from([0xff, 0xfe, 0xfd])
    await expect(
      run(
        'gfs.read',
        { uri: 'gfs://main/a.bin', as: 'text' },
        {
          downloadGfsUri: async () => ({
            resource: { gfsUri: 'gfs://main/a.bin', name: 'a.bin' } as never,
            bytes: binary.buffer.slice(
              binary.byteOffset,
              binary.byteOffset + binary.byteLength
            ) as ArrayBuffer,
          }),
        }
      )
    ).rejects.toBeInstanceOf(CapabilityInputError)
  })
})

describe('detectImageMime', () => {
  it('identifies renderable formats by magic bytes', () => {
    expect(detectImageMime(PNG)).toBe('image/png')
    expect(detectImageMime(JPEG)).toBe('image/jpeg')
  })

  it('does not identify SVG, which is deliberately unsupported', () => {
    expect(detectImageMime(Buffer.from('<svg></svg>'))).toBeNull()
  })

  it('survives a file shorter than any magic prefix', () => {
    expect(detectImageMime(Buffer.from([0x01]))).toBeNull()
  })
})

describe('notifications.notify', () => {
  it('strips control characters and enforces length caps', () => {
    const descriptor = getCapability('notifications.notify')
    const params = descriptor?.validate({ title: 'New\u0000 lead\u001b', body: 'x' })
    expect(params?.title).toBe('New  lead')
    expect(() => descriptor?.validate({ title: 'x'.repeat(121) })).toThrow()
    expect(() => descriptor?.validate({ title: 'ok', body: 'x'.repeat(401) })).toThrow()
    expect(() => descriptor?.validate({ body: 'no title' })).toThrow()
  })

  it('passes the host-owned plugin title through for attribution', async () => {
    let seen: { pluginTitle?: string } = {}
    await run(
      'notifications.notify',
      { title: 'Hello' },
      {
        showPluginNotification: async (input: { pluginTitle?: string }) => {
          seen = input
          return { delivered: true }
        },
      }
    )
    expect(seen.pluginTitle).toBe('Plugin')
  })
})

describe('gfs.open', () => {
  it('returns only whether a viewer opened, never anything about the file', async () => {
    const result = await run('gfs.open', { uri: 'gfs://main/a.png' })
    // The plugin must not learn the name, size, or contents from an open call.
    expect(result).toEqual({ opened: true })
  })

  it('drops the internal reason on failure so it is not an accessibility oracle', async () => {
    // The producer distinguishes not_found / unavailable internally; the plugin
    // must only ever see `{ opened: false }` — otherwise it can tell an absent or
    // unauthorized resource apart from a transient failure without consent.
    const result = await run(
      'gfs.open',
      { uri: 'gfs://main/secret.png' },
      { openGfsResource: async () => ({ opened: false, reason: 'not_found' }) }
    )
    expect(result).toEqual({ opened: false })
    expect(result).not.toHaveProperty('reason')
  })

  it('rejects a non-gfs uri and unexpected params', () => {
    const descriptor = getCapability('gfs.open')
    expect(() => descriptor?.validate({ uri: 'https://evil.example/x' })).toThrow()
    expect(() => descriptor?.validate({ uri: 'gfs://main/a', as: 'dataUrl' })).toThrow()
    expect(() => descriptor?.validate({})).toThrow()
  })

  it('is budgeted more tightly than the reads, because it paints over the user', () => {
    const open = getCapability('gfs.open')
    const read = getCapability('gfs.read')
    expect(open?.limits.perMinute).toBeLessThan(read?.limits.perMinute ?? 0)
  })
})