Skip to content

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

TypeScript
19.5 KB
Raw Blame
/**
 * Provenance boundary of the GFS download store. A shell command runs with the
 * Host UID and can write anything under `users/`, so a copy found on disk
 * proves nothing about who downloaded it or what it hashes to. These tests
 * plant such copies and check that they are counted and swept but never
 * reused, read or allowed to displace a copy this process published.
 */
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import * as crypto from 'node:crypto'
import { randomUUID } from 'node:crypto'
import * as syncFs from 'node:fs'
import * as fs from 'node:fs/promises'
import { tmpdir } from 'node:os'
import * as path from 'node:path'
import {
  callerDirectory,
  completedCopy,
  digestOf,
  downloadDirectory,
  exists,
  expiryCount,
  metaFor,
  plantDownload,
  quotaCount,
  sourceFor,
  startTransfer,
  withEnvironment,
} from '../__tests__/fixtures/gfsStoreTestKit'
import { logger } from '../logger'
import { GfsDownloadStore } from './gfsDownloadStore'

const { hashBoundary, volume } = vi.hoisted(() => ({
  hashBoundary: vi.fn(),
  volume: { totalBytes: undefined as bigint | undefined },
}))
// Pass-through: the store hashes through createHash; the kit uses crypto.hash.
vi.mock('node:crypto', async original => ({
  ...(await original<typeof crypto>()),
  createHash: hashBoundary,
}))
// statfs reports the real free space; a test that sets `volume.totalBytes`
// sizes the volume (block size 1), and with it the retained budget. Otherwise
// the volume is sized to its free space (freeSpaceSizedStatfs).
vi.mock('node:fs/promises', async original => {
  const actual = await original<typeof fs>()
  return {
    ...actual,
    statfs: async (target: string, options: { bigint: true }) => {
      if (volume.totalBytes === undefined) {
        const { freeSpaceSizedStatfs } = await import('../__tests__/fixtures/gfsStoreTestKit')
        return freeSpaceSizedStatfs(actual.statfs)(target, options)
      }
      const real = await actual.statfs(target, options)
      return { ...real, bsize: 1n, blocks: volume.totalBytes, bavail: real.bavail * real.bsize }
    },
  }
})

const A = 'caller-a'
const B = 'caller-b'
const C = 'caller-c'

let nativeCrypto: typeof crypto
let hostRoot: string
let rootA: string
let rootB: string
let store: GfsDownloadStore
const extraStores: GfsDownloadStore[] = []
const outsideRoots: string[] = []

function receiptPathOf(id: string): string {
  return `.gfs-downloads/input-${id}/source`
}

/** A complete, well-formed copy written by a shell command, not by the store. */
function plantComplete(
  root: string,
  identity: string,
  index: number,
  bytes: Buffer,
  options: { id?: string } = {}
) {
  const id = options.id ?? randomUUID()
  return plantDownload(root, {
    id,
    bytes,
    meta: metaFor(id, bytes, Date.now(), { callerIdentity: identity, source: sourceFor(index) }),
  })
}

async function openStore(): Promise<GfsDownloadStore> {
  const opened = new GfsDownloadStore(hostRoot)
  extraStores.push(opened)
  await opened.initialize()
  return opened
}

function outsideDirectory(): string {
  const outside = syncFs.mkdtempSync(path.join(tmpdir(), 'gfs-store-outside-'))
  outsideRoots.push(outside)
  return outside
}

async function expectNotServed(target: GfsDownloadStore, id: string, identity: string) {
  await expect(target.readManagedFile(receiptPathOf(id), identity)).rejects.toMatchObject({
    code: 'download_missing',
  })
  await expect(target.readManagedFilePrefix(receiptPathOf(id), identity)).rejects.toMatchObject({
    code: 'download_missing',
  })
}

function adoptedLogged(info: ReturnType<typeof vi.spyOn>, adopted: number) {
  expect(info).toHaveBeenCalledWith(
    expect.objectContaining({ component: 'GfsDownloadStore', adopted }),
    'GFS download store initialized'
  )
}

beforeEach(async () => {
  nativeCrypto = await vi.importActual<typeof crypto>('node:crypto')
  vi.useFakeTimers({ toFake: ['Date'] })
  vi.setSystemTime(new Date('2026-10-08T10:00:00.000Z'))
  hashBoundary.mockReset()
  hashBoundary.mockImplementation((algorithm: string) => nativeCrypto.createHash(algorithm))
  volume.totalBytes = undefined
  hostRoot = syncFs.mkdtempSync(path.join(tmpdir(), 'gfs-store-provenance-'))
  rootA = callerDirectory(hostRoot, A)
  rootB = callerDirectory(hostRoot, B)
  store = new GfsDownloadStore(hostRoot)
  await store.initialize()
})

afterEach(async () => {
  vi.restoreAllMocks()
  vi.useRealTimers()
  for (const opened of extraStores.splice(0)) await opened.close(0)
  await store.close(0)
  await fs.rm(hostRoot, { recursive: true, force: true })
  for (const outside of outsideRoots.splice(0))
    await fs.rm(outside, { recursive: true, force: true })
})

describe('GFS download store provenance: planted copies', () => {
  it("T-S1: a planted entry in the caller's directory is never reused", async () => {
    const bytes = Buffer.alloc(32, 0x41)
    const planted = plantComplete(rootB, B, 5, bytes)
    const info = vi.spyOn(logger, 'info')
    const restarted = await openStore()

    // Witnesses: the restarted store indexed the copy and counts it under B.
    adoptedLogged(info, 1)
    expect((await restarted.debugInventory()).byCaller.get(B)).toEqual({ files: 1, bytes: 32 })
    hashBoundary.mockClear()

    await expect(restarted.reusableReceipt(B, sourceFor(5), 32)).resolves.toBeUndefined()
    expect(hashBoundary).not.toHaveBeenCalled()
    const transfer = await restarted.createTransfer({
      callerIdentity: B,
      callerWorkspacePath: rootB,
      source: sourceFor(5),
      sizeBytes: 32,
      expiresAt: new Date(Date.now() + 60_000).toISOString(),
    })
    expect(transfer.id).not.toBe(planted.id)
    expect(exists(planted.sourcePath)).toBe(true)
  })

  it('T-S2: a planted entry is never read through the managed path', async () => {
    const own = await completedCopy(store, rootB, B, 6, 16)
    const bytes = Buffer.alloc(24, 0x42)
    const planted = plantComplete(rootB, B, 7, bytes)

    // Not yet indexed: the managed path must not look at the disk.
    await expectNotServed(store, planted.id, B)
    // Control: the same read path serves B's published copy.
    await expect(store.readManagedFile(own.receipt.path, B)).resolves.toEqual(own.bytes)

    const info = vi.spyOn(logger, 'info')
    const restarted = await openStore()
    adoptedLogged(info, 2)
    expect((await restarted.debugInventory()).byCaller.get(B)).toEqual({ files: 2, bytes: 40 })
    await expectNotServed(restarted, planted.id, B)
    expect(exists(planted.sourcePath)).toBe(true)
  })

  it('T-S3: a planted directory with a published id is removed and the published copy is untouched', async () => {
    const published = await completedCopy(store, rootB, B, 8, 32)
    const forged = Buffer.alloc(32, 0x5a)
    const planted = plantComplete(rootA, B, 8, forged, { id: published.receipt.id })

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 1 })

    expect(exists(planted.directory)).toBe(false)
    const reused = await store.reusableReceipt(B, sourceFor(8), 32)
    expect(reused).toMatchObject({ id: published.receipt.id, sha256: digestOf(published.bytes) })
    await expect(store.readManagedFile(published.receipt.path, B)).resolves.toEqual(published.bytes)
  })

  it('T-S4: a planted entry is inventoried under the directory that contains it and evicted first', async () => {
    const bytes = Buffer.alloc(10, 0x43)
    const planted = plantComplete(rootB, C, 9, bytes)
    // Budget 18; the active reservations stay within the 9 protected bytes
    // the Host allows.
    volume.totalBytes = 18n
    const limited = await withEnvironment(
      {
        MCP_HOST_GFS_MAX_FILE_BYTES: '10',
        MCP_HOST_GFS_DOWNLOAD_STORAGE_PERCENT: '100',
      },
      async () => {
        vi.resetModules()
        const { GfsDownloadStore: Store } = await import('./gfsDownloadStore')
        const opened = new Store(hostRoot)
        extraStores.push(opened as unknown as GfsDownloadStore)
        await opened.initialize()
        return opened
      }
    )
    const inventory = await limited.debugInventory()
    expect(inventory.byCaller.get(B)).toEqual({ files: 1, bytes: 10 })
    expect(inventory.byCaller.has(C)).toBe(false)
    const denied = await quotaCount('host', 'storage_bytes')

    // 10 planted + 4 requested fit the budget of 18, so nothing is evicted.
    const rootC = callerDirectory(hostRoot, C)
    await startTransfer(limited, rootC, C, 10, 4)
    expect(exists(planted.directory)).toBe(true)

    // 10 + 4 + 5 does not: the plant goes, the active reservation stays.
    await startTransfer(limited, rootB, B, 11, 5)
    expect(exists(planted.directory)).toBe(false)
    expect(await quotaCount('host', 'storage_bytes')).toBe(denied)
  })

  it('T-R1: a restart keeps the copy for accounting and cleanup but does not reuse it', async () => {
    const published = await completedCopy(store, rootB, B, 12, 20)
    await store.close(0)
    const info = vi.spyOn(logger, 'info')

    const restarted = await openStore()

    adoptedLogged(info, 1)
    expect((await restarted.debugInventory()).byCaller.get(B)).toEqual({ files: 1, bytes: 20 })
    await expect(restarted.reusableReceipt(B, sourceFor(12), 20)).resolves.toBeUndefined()
    await expectNotServed(restarted, published.receipt.id, B)
    const again = await startTransfer(restarted, rootB, B, 12, 20)
    expect(again.transfer.id).not.toBe(published.receipt.id)
    const directories = syncFs.readdirSync(path.join(rootB, '.gfs-downloads'))
    expect(directories.filter(name => name.startsWith('input-'))).toHaveLength(2)
  })

  it("P7: a planted entry with the caller's own identity is neither reused nor read", async () => {
    const bytes = Buffer.alloc(18, 0x44)
    const planted = plantComplete(rootA, A, 13, bytes)
    const info = vi.spyOn(logger, 'info')
    const restarted = await openStore()

    adoptedLogged(info, 1)
    expect((await restarted.debugInventory()).byCaller.get(A)).toEqual({ files: 1, bytes: 18 })
    await expect(restarted.reusableReceipt(A, sourceFor(13), 18)).resolves.toBeUndefined()
    await expectNotServed(restarted, planted.id, A)
    expect(exists(planted.sourcePath)).toBe(true)
  })

  it("P7b: an expired adopted entry in the caller's own directory answers download_missing, not download_expired", async () => {
    const bytes = Buffer.alloc(18, 0x46)
    // metaFor expires the plant one hour after now; the published copy lives a day.
    const planted = plantComplete(rootA, A, 22, bytes)
    const info = vi.spyOn(logger, 'info')
    const restarted = await openStore()
    adoptedLogged(info, 1)
    const own = await completedCopy(restarted, rootA, A, 23, 16, {
      expiresAt: new Date(Date.now() + 24 * 60 * 60_000).toISOString(),
    })

    vi.setSystemTime(new Date(Date.now() + 2 * 60 * 60_000))

    // The adopted entry is still indexed: the provenance guard, not openEntryContent, decides.
    expect((await restarted.debugInventory()).byCaller.get(A)).toEqual({ files: 2, bytes: 34 })
    await expectNotServed(restarted, planted.id, A)
    // Witness: the same read path serves the caller's own published copy at the same instant.
    await expect(restarted.readManagedFile(own.receipt.path, A)).resolves.toEqual(own.bytes)
    expect(exists(planted.sourcePath)).toBe(true)
  })

  it('P8: a meta identity that differs from its directory grants nothing to either caller', async () => {
    const bytes = Buffer.alloc(12, 0x45)
    const planted = plantComplete(rootB, C, 14, bytes)
    const info = vi.spyOn(logger, 'info')
    const restarted = await openStore()

    adoptedLogged(info, 1)
    expect((await restarted.debugInventory()).byCaller.get(B)).toEqual({ files: 1, bytes: 12 })
    await expectNotServed(restarted, planted.id, C)
    await expectNotServed(restarted, planted.id, B)
    await expect(restarted.reusableReceipt(C, sourceFor(14), 12)).resolves.toBeUndefined()
    expect(exists(planted.sourcePath)).toBe(true)
  })

  it('P9: duplicate ids without a published entry are all removed', async () => {
    const id = randomUUID()
    const first = plantComplete(rootA, A, 15, Buffer.alloc(8, 1), { id })
    const second = plantComplete(rootB, B, 15, Buffer.alloc(8, 2), { id })
    const unrelated = plantComplete(rootA, A, 16, Buffer.alloc(8, 3))

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 2 })

    expect(exists(first.directory)).toBe(false)
    expect(exists(second.directory)).toBe(false)
    // Witness: the sweep kept the unrelated complete plant.
    expect(exists(unrelated.directory)).toBe(true)
    expect((await store.debugInventory()).files).toBe(1)
  })

  it('P10: a planted directory with an active id is removed and the transfer still publishes', async () => {
    const { transfer, bytes } = await startTransfer(store, rootA, A, 17, 16)
    const planted = plantComplete(rootB, A, 17, Buffer.alloc(16, 0x46), { id: transfer.id })

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 1 })

    expect(exists(planted.directory)).toBe(false)
    const receipt = await store.publish(transfer.id, A, digestOf(bytes))
    await expect(store.readManagedFile(receipt.path, A)).resolves.toEqual(bytes)
  })

  it.each(['input directory', 'meta.json', 'source'] as const)('P11: symlink as %s', async kind => {
    const outside = outsideDirectory()
    const bytes = Buffer.alloc(20, 0x47)
    const id = randomUUID()
    const meta = metaFor(id, bytes, Date.now(), { callerIdentity: B, source: sourceFor(18) })
    const target = plantDownload(outside, { id, bytes, meta })
    const sibling = plantComplete(rootB, B, 19, Buffer.alloc(6, 0x48))
    let link: string
    if (kind === 'input directory') {
      link = downloadDirectory(rootB, id)
      syncFs.symlinkSync(target.directory, link)
    } else if (kind === 'meta.json') {
      const planted = plantDownload(rootB, { id, bytes, meta: 'omit' })
      link = path.join(planted.directory, 'meta.json')
      syncFs.symlinkSync(path.join(target.directory, 'meta.json'), link)
    } else {
      const planted = plantDownload(rootB, { id, bytes, meta, source: 'omit' })
      link = planted.sourcePath
      syncFs.symlinkSync(target.sourcePath, link)
    }

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 1 })

    expect(exists(link)).toBe(false)
    expect(exists(downloadDirectory(rootB, id))).toBe(false)
    expect(syncFs.readFileSync(target.sourcePath)).toEqual(bytes)
    expect(exists(path.join(target.directory, 'meta.json'))).toBe(true)
    // Witness: the sweep retained the real sibling copy.
    expect(exists(sibling.directory)).toBe(true)
    expect((await store.debugInventory()).files).toBe(1)
  })

  it('P15: a .gfs-downloads that is a file is removed and the caller can still download', async () => {
    const downloads = path.join(rootB, '.gfs-downloads')
    syncFs.writeFileSync(downloads, 'not a directory', { mode: 0o600 })

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 1 })

    expect(exists(downloads)).toBe(false)
    const copy = await completedCopy(store, rootB, B, 20, 9)
    await expect(store.readManagedFile(copy.receipt.path, B)).resolves.toEqual(copy.bytes)
  })

  it('P16: a symlinked caller directory is neither listed nor accepted as a caller root', async () => {
    const outside = outsideDirectory()
    const outsideCaller = path.join(outside, 'caller-x')
    syncFs.mkdirSync(outsideCaller, { mode: 0o700 })
    const hidden = plantComplete(outsideCaller, 'caller-x', 21, Buffer.alloc(10, 0x49))
    const linkedRoot = path.join(hostRoot, 'users', 'caller-x')
    syncFs.symlinkSync(outsideCaller, linkedRoot)
    const real = plantComplete(rootB, B, 22, Buffer.alloc(7, 0x4a))

    await expect(store.cleanupExpired()).resolves.toMatchObject({ removedIncomplete: 0 })
    const inventory = await store.debugInventory()

    // Witness: the real copy is listed and counted.
    expect(inventory.files).toBe(1)
    expect(inventory.byCaller.get(B)).toEqual({ files: 1, bytes: 7 })
    expect(inventory.byCaller.has('caller-x')).toBe(false)
    expect(exists(hidden.sourcePath)).toBe(true)
    expect(exists(real.sourcePath)).toBe(true)
    await expect(startTransfer(store, linkedRoot, 'caller-x', 23, 4)).rejects.toMatchObject({
      code: 'workspace_unavailable',
    })
  })

  it('P17: a hardlinked published source is not reused and is downloaded again', async () => {
    const published = await completedCopy(store, rootB, B, 24, 32)
    const directory = downloadDirectory(rootB, published.receipt.id)
    const link = path.join(outsideDirectory(), 'linked-source')
    syncFs.linkSync(path.join(directory, 'source'), link)
    const altered = Buffer.alloc(32, 0xee)
    syncFs.writeFileSync(link, altered)

    await expect(store.reusableReceipt(B, sourceFor(24), 32)).resolves.toBeUndefined()

    // Witness: the reuse path opened the copy and removed it.
    expect(exists(directory)).toBe(false)
    expect(syncFs.readFileSync(link)).toEqual(altered)
    const again = await completedCopy(store, rootB, B, 24, 32)
    expect(again.receipt.id).not.toBe(published.receipt.id)
  })

  it.each(['expiry sweep', 'failed reuse'] as const)(
    'P18: a caller directory replaced by a symlink after publish is not followed by the %s',
    async trigger => {
      const published = await completedCopy(store, rootB, B, 25, 16)
      const outside = outsideDirectory()
      const decoy = plantDownload(outside, {
        id: published.receipt.id,
        bytes: published.bytes,
        meta: metaFor(published.receipt.id, published.bytes, Date.now(), {
          callerIdentity: B,
          source: sourceFor(25),
        }),
      })
      syncFs.renameSync(rootB, `${rootB}-moved`)
      syncFs.symlinkSync(outside, rootB)
      const failedBefore = await expiryCount('remove_failed')
      const warn = vi.spyOn(logger, 'warn')

      if (trigger === 'expiry sweep') {
        await expect(
          store.cleanupExpired(Date.parse(published.receipt.expiresAt))
        ).resolves.toMatchObject({ removedExpired: 0, removeFailed: 1 })
      } else {
        await expect(store.reusableReceipt(B, sourceFor(25), 16)).resolves.toBeUndefined()
      }

      // Witness: the removal was reached and refused on containment.
      expect(await expiryCount('remove_failed')).toBe(failedBefore + 1)
      expect(warn).toHaveBeenCalledWith(
        expect.objectContaining({ component: 'GfsDownloadStore', code: 'workspace_unavailable' }),
        'GFS download store could not remove a download directory; the next sweep retries it'
      )
      expect(syncFs.readFileSync(decoy.sourcePath)).toEqual(published.bytes)
      expect(exists(path.join(decoy.directory, 'meta.json'))).toBe(true)
    }
  )

  it('P19: a caller directory replaced by a symlink before publish is refused and nothing is written outside', async () => {
    const { transfer, bytes } = await startTransfer(store, rootB, B, 26, 12)
    const outside = outsideDirectory()
    const decoy = downloadDirectory(outside, transfer.id)
    syncFs.mkdirSync(decoy, { recursive: true, mode: 0o700 })
    syncFs.chmodSync(path.dirname(decoy), 0o700)
    syncFs.writeFileSync(path.join(decoy, 'source.partial'), bytes, { mode: 0o600 })
    syncFs.renameSync(rootB, `${rootB}-moved`)
    syncFs.symlinkSync(outside, rootB)

    await expect(store.publish(transfer.id, B, digestOf(bytes))).rejects.toMatchObject({
      code: 'workspace_unavailable',
    })

    // Witness: the partial the decoy offered is still there, unpublished.
    expect(syncFs.readFileSync(path.join(decoy, 'source.partial'))).toEqual(bytes)
    expect(exists(path.join(decoy, 'source'))).toBe(false)
    expect(exists(path.join(decoy, 'meta.json'))).toBe(false)
    await expectNotServed(store, transfer.id, B)
  })
})