Skip to content

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

TypeScript
20.8 KB
Raw Blame
import assert from 'node:assert/strict'
import { execFileSync } from 'node:child_process'
import { createPublicKey, type KeyObject, generateKeyPairSync, randomUUID } from 'node:crypto'
import { chmodSync, copyFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, rmdirSync, symlinkSync, writeFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import { tmpdir } from 'node:os'
import { dirname, join, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import type * as Policy from '../../packages/jwt-key-policy/index.js'
import type * as Store from '../../packages/jwt-key-policy/dev-store.js'

type VerifierModule = { config: { jwtPublicKey: string; jwtIssuer: string; jwtAudience: string } }
export type VerifierContractOptions = {
  service: 'rpc-proxy' | 'external-rest-api'
  slot: 'rpc' | 'session'
  envName: string
  configSource: URL
  loadConfig: () => Promise<VerifierModule>
  resetModules: () => void
}
export type VerifierContractCase = { name: string; run: () => void | Promise<void> }

type CryptoFixtures = {
  PUBLIC_KEYS: Readonly<Record<'rpc' | 'session' | 'admin', string>>
  encodings: (pem: string) => Record<string, string>
  certificate: (material: KeyObject) => string
  certificateWithPublic: (publicPem: string) => Promise<string>
}
type RuntimeResult = {
  storeDir: string
  fingerprint?: string
  signatureVerified?: boolean
  storeOperations: number
  code?: string
  reason?: string
  productionDevModeRejected?: boolean
}

const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..')

/** Framework-neutral fixture/cases; each caller uses its own test API/types. */
export function createDevJwtVerifierContract(options: VerifierContractOptions) {
  const serviceRoot = dirname(dirname(fileURLToPath(options.configSource)))
  const serviceRequire = createRequire(options.configSource)
  const policy = serviceRequire('@clerum/jwt-key-policy') as typeof Policy
  const storeApi = serviceRequire('@clerum/jwt-key-policy/dev-store') as typeof Store
  const cryptoFixtures = serviceRequire(join(repoRoot, 'packages/jwt-key-policy/test/crypto-fixtures.cjs')) as CryptoFixtures
  const pair = generateKeyPairSync('rsa', { modulusLength: 2048 })
  const freshPublic = pair.publicKey.export({ type: 'spki', format: 'pem' }).toString().trim()
  const signingPem = pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString().trim()
  const cert = cryptoFixtures.certificate(pair.privateKey)
  const encodings = cryptoFixtures.encodings(freshPublic)
  const originalEnv = { ...process.env }
  let artifactRoot: string | undefined
  let layout: string | undefined
  let store: string
  const cases: VerifierContractCase[] = []
  const add = (name: string, run: VerifierContractCase['run']) => cases.push({ name, run })
  const publicPath = () => join(store, `${options.slot}.public.pem`)
  const publish = (pem = freshPublic) => writeFileSync(publicPath(), pem, { mode: 0o644 })
  const fingerprint = (pem: string) => policy.publicKeyPemFingerprint(pem)
  const expectFailure = (code: string, reason?: string) => assert.rejects(options.loadConfig, error => {
    const value = error as { code?: string; reason?: string }
    assert.equal(value.code, code)
    if (reason !== undefined) assert.equal(value.reason, reason)
    return true
  })

  async function withEffectiveUid(values: readonly number[], run: () => Promise<void>): Promise<void> {
    const effectiveUid = process.geteuid
    assert.equal(typeof effectiveUid, 'function', 'Ownership cases require the documented POSIX store platform')
    const descriptor = Object.getOwnPropertyDescriptor(process, 'geteuid')
    let call = 0
    Object.defineProperty(process, 'geteuid', {
      configurable: true, value: () => values[Math.min(call++, values.length - 1)],
    })
    try { await run() } finally {
      if (descriptor) Object.defineProperty(process, 'geteuid', descriptor)
      else delete process.geteuid
    }
  }

  function productionEnvironment(): void {
    process.env.NODE_ENV = 'production'
    delete process.env.CLERUM_DEV_MODE
    const prefix = options.service === 'rpc-proxy' ? 'RPC_PROXY' : 'EXTERNAL_REST_API'
    const values = {
      CORS_ORIGIN: 'http://localhost:3001', JWT_ISSUER: 'control-api',
      JWT_AUDIENCE: options.slot === 'rpc' ? 'rpc-proxy' : 'profile-ui',
      CONTROL_API_BASE_URL: 'http://localhost:8090', CONTROL_API_SERVICE_TOKEN: randomUUID(),
      HCC_BASE_URL: 'http://localhost:8081', HOST_NAMESPACE: 'mcp-host',
      DESKTOP_COOKIE_SECRET: randomUUID(), SANDBOX_UI_COOKIE_SECRET: randomUUID(),
      OAUTH_CALLBACK_BASE_URL: 'http://localhost:8090', GOOGLE_CLIENT_ID: randomUUID(),
      PUBLIC_BASE_URL: 'http://localhost:8091', DESKTOP_RPC_PROXY_BASE_URL: 'http://localhost:8094',
    }
    for (const [name, value] of Object.entries(values)) process.env[`${prefix}_${name}`] = value
  }

  // Compile the actual configuration and its TypeScript closure. Full-service
  // builds and production image validation remain separate evidence lanes.
  function prepare(): void {
    artifactRoot = realpathSync(mkdtempSync(join(tmpdir(), `evenfire-${options.slot}-jwt-artifact-`)))
    execFileSync(process.execPath, [
      serviceRequire.resolve('typescript/bin/tsc'), fileURLToPath(options.configSource),
      '--outDir', artifactRoot, '--rootDir', join(serviceRoot, 'src'),
      '--module', 'NodeNext', '--moduleResolution', 'NodeNext', '--target', 'ES2022',
      '--strict', '--skipLibCheck', '--esModuleInterop',
    ], { cwd: serviceRoot, stdio: ['ignore', 'pipe', 'pipe'], timeout: 45_000, maxBuffer: 256 * 1024 })
  }

  function reset(): void {
    options.resetModules()
    process.env = { ...originalEnv, NODE_ENV: 'test', CLERUM_DEV_MODE: 'true' }
    delete process.env[options.envName]
    layout = realpathSync(mkdtempSync(join(tmpdir(), `evenfire-${options.slot}-verifier-`)))
    store = join(layout, 'store')
    mkdirSync(store, { mode: 0o700 })
    process.env.EVENFIRE_DEV_KEY_STORE = store
  }

  function cleanup(): void {
    process.env = { ...originalEnv }
    if (layout) rmSync(layout, { recursive: true, force: true })
    layout = undefined
    options.resetModules()
  }

  function dispose(): void {
    cleanup()
    if (artifactRoot) rmSync(artifactRoot, { recursive: true, force: true })
    artifactRoot = undefined
  }

  function runRuntime(runtime: 'src' | 'dist', override: string | undefined, configure?: {
    supplied?: string; productionDev?: boolean; denied?: string; consumerOverride?: string
  }): RuntimeResult {
    assert.ok(layout && artifactRoot, 'Prepare the actual consumer artifacts before running a runtime case')
    const moduleDir = join(layout, options.service, runtime)
    const policyDir = join(layout, 'node_modules/@clerum/jwt-key-policy')
    mkdirSync(join(layout, 'control-api'), { recursive: true })
    mkdirSync(moduleDir, { recursive: true })
    mkdirSync(policyDir, { recursive: true })
    for (const name of ['package.json', 'index.cjs', 'index.d.ts', 'dev-store.cjs', 'dev-store.d.ts']) {
      copyFileSync(join(repoRoot, 'packages/jwt-key-policy', name), join(policyDir, name))
    }
    const configPath = join(moduleDir, runtime === 'src' ? 'config.ts' : 'config.js')
    copyFileSync(runtime === 'src' ? options.configSource : join(artifactRoot, 'config.js'), configPath)
    const runner = `
      const path = require('node:path');
      const fs = require('node:fs');
      const crypto = require('node:crypto');
      let storeOperations = 0;
      let storeDir = '';
      for (const name of ['lstatSync', 'openSync', 'mkdirSync', 'readFileSync', 'writeFileSync', 'linkSync', 'unlinkSync']) {
        const original = fs[name];
        fs[name] = (...args) => {
          if (storeDir && typeof args[0] === 'string' && path.resolve(args[0]).startsWith(storeDir)) storeOperations++;
          return original(...args);
        };
      }
      const policy = require(${JSON.stringify(join(policyDir, 'index.cjs'))});
      const storeApi = require(${JSON.stringify(join(policyDir, 'dev-store.cjs'))});
      storeDir = storeApi.resolveDevKeyStoreDir(${JSON.stringify(join(layout, 'control-api'))}, process.env.EVENFIRE_DEV_KEY_STORE);
      const material = storeApi.loadOrCreateDevSigningMaterial(${JSON.stringify(options.slot)}, storeDir);
      storeOperations = 0;
      if (${JSON.stringify(configure?.consumerOverride ?? null)} !== null) process.env.EVENFIRE_DEV_KEY_STORE = ${JSON.stringify(configure?.consumerOverride ?? null)};
      if (${JSON.stringify(configure?.denied ?? null)}) {
        const parse = policy.parseVerifierMaterial;
        policy.parseVerifierMaterial = (raw, source, options) => parse(raw, source, { ...options, fingerprints: [${JSON.stringify(configure?.denied ?? '')}] });
      }
      try {
        const { config } = require(${JSON.stringify(configPath)});
        const input = Buffer.from('actual-verifier-key-contract');
        const signature = crypto.sign('RSA-SHA256', input, material.privatePem);
        process.stdout.write(JSON.stringify({ storeDir, fingerprint: policy.publicKeyPemFingerprint(config.jwtPublicKey),
          signatureVerified: crypto.verify('RSA-SHA256', input, config.jwtPublicKey, signature), storeOperations }));
      } catch (error) {
        process.stdout.write(JSON.stringify({ storeDir, storeOperations, code: error.code, reason: error.reason,
          productionDevModeRejected: /CLERUM_DEV_MODE=true is not allowed with NODE_ENV=production/.test(error.message) }));
      }
    `
    const env = { ...process.env }
    if (override === undefined) delete env.EVENFIRE_DEV_KEY_STORE
    else env.EVENFIRE_DEV_KEY_STORE = override
    delete env[options.envName]
    if (configure?.supplied !== undefined) env[options.envName] = configure.supplied
    if (configure?.productionDev) env.NODE_ENV = 'production'
    const args = runtime === 'src' ? ['--import', serviceRequire.resolve('tsx'), '-e', runner] : ['-e', runner]
    return JSON.parse(execFileSync(process.execPath, args, {
      cwd: join(layout, options.service), env, encoding: 'utf8', timeout: 15_000,
      maxBuffer: 64 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
    })) as RuntimeResult
  }

  add('verifies the real producer public identity and distinguishes another identity', async () => {
    const material = storeApi.loadOrCreateDevSigningMaterial(options.slot, store)
    const { config } = await options.loadConfig()
    assert.equal(fingerprint(config.jwtPublicKey), material.fingerprint)
    assert.equal(fingerprint(config.jwtPublicKey) === fingerprint(freshPublic), false)
  })
  for (const runtime of ['src', 'dist'] as const) {
    for (const override of [undefined, '', ' \t ']) {
      add(`${runtime} shares the default store with ${JSON.stringify(override)} override and restarts`, () => {
        const first = runRuntime(runtime, override)
        const second = runRuntime(runtime, override)
        assert.equal(first.storeDir, join(layout!, 'control-api', '.dev-keys'))
        assert.equal(first.signatureVerified, true)
        assert.equal(second.signatureVerified, true)
        assert.equal(second.fingerprint, first.fingerprint)
      })
    }
    add(`${runtime} shares an absolute producer store and restarts`, () => {
      const first = runRuntime(runtime, store)
      const second = runRuntime(runtime, store)
      assert.equal(first.storeDir, store)
      assert.equal(first.signatureVerified, true)
      assert.equal(second.fingerprint, first.fingerprint)
    })
  }
  for (const [name, encoded] of Object.entries(encodings)) {
    for (const origin of ['environment', 'store'] as const) {
      add(`accepts ${name} from ${origin} as canonical SPKI`, async () => {
        if (origin === 'environment') process.env[options.envName] = encoded
        else publish(encoded)
        assert.equal((await options.loadConfig()).config.jwtPublicKey === freshPublic, true)
      })
    }
    for (const [slot, publicPem] of Object.entries(cryptoFixtures.PUBLIC_KEYS)) {
      add(`rejects historical ${slot} in ${name} in production`, async () => {
        productionEnvironment()
        process.env[options.envName] = cryptoFixtures.encodings(publicPem)[name]
        await expectFailure('ERR_JWT_KEY_BANNED', 'banned_identity')
      })
      add(`rejects historical ${slot} in ${name} from the public store`, async () => {
        publish(cryptoFixtures.encodings(publicPem)[name])
        await expectFailure('ERR_JWT_KEY_BANNED', 'banned_identity')
      })
    }
  }
  const carriers = {
    pkcs1: createPublicKey(freshPublic).export({ type: 'pkcs1', format: 'pem' }).toString(),
    certificate: cert,
  }
  for (const [name, pem] of Object.entries(carriers)) {
    for (const origin of ['environment', 'store'] as const) {
      add(`accepts RSA ${name} from ${origin}`, async () => {
        if (origin === 'environment') process.env[options.envName] = pem
        else publish(pem)
        assert.equal(fingerprint((await options.loadConfig()).config.jwtPublicKey), fingerprint(freshPublic))
      })
    }
    for (const [slot, publicPem] of Object.entries(cryptoFixtures.PUBLIC_KEYS)) {
      add(`rejects historical ${slot} as ${name}`, async () => {
        process.env[options.envName] = name === 'certificate'
          ? await cryptoFixtures.certificateWithPublic(publicPem)
          : createPublicKey(publicPem).export({ type: 'pkcs1', format: 'pem' }).toString()
        await expectFailure('ERR_JWT_KEY_BANNED', 'banned_identity')
      })
      add(`rejects historical ${slot} as ${name} from the public store`, async () => {
        const material = name === 'certificate'
          ? await cryptoFixtures.certificateWithPublic(publicPem)
          : createPublicKey(publicPem).export({ type: 'pkcs1', format: 'pem' }).toString()
        publish(material)
        await expectFailure('ERR_JWT_KEY_BANNED', 'banned_identity')
      })
    }
  }
  for (const [name, pem] of Object.entries({
    pkcs8: signingPem, pkcs1: pair.privateKey.export({ type: 'pkcs1', format: 'pem' }).toString(),
  })) {
    add(`accepts legacy ${name} environment input but exports public only`, async () => {
      process.env[options.envName] = pem
      const { config } = await options.loadConfig()
      assert.equal(config.jwtPublicKey === freshPublic, true)
      assert.equal(config.jwtPublicKey.includes('PRIVATE'), false)
    })
    add(`rejects private ${name} in a public store`, async () => {
      publish(pem)
      await expectFailure('ERR_JWT_KEY_INVALID', 'wrong_key_role')
    })
  }
  add('accepts RSA-4096 and refuses RSA-1024 verification material', async () => {
    for (const bits of [4096, 1024]) {
      const publicPem = generateKeyPairSync('rsa', { modulusLength: bits }).publicKey.export({ type: 'spki', format: 'pem' }).toString()
      options.resetModules()
      process.env[options.envName] = publicPem
      if (bits === 4096) assert.equal(fingerprint((await options.loadConfig()).config.jwtPublicKey), fingerprint(publicPem))
      else await expectFailure('ERR_JWT_KEY_INVALID', 'undersized_rsa_key')
    }
  })
  for (const origin of ['environment', 'store'] as const) {
    for (const [name, value] of Object.entries({
      malformed: 'not a PEM key',
      ec: generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).publicKey.export({ type: 'spki', format: 'pem' }).toString(),
      publicBundle: `${freshPublic}\n${cryptoFixtures.PUBLIC_KEYS.admin}`,
      mixedBundle: `${cert}\n${signingPem}`,
      reverseMixedBundle: `${signingPem}\n${cert}`,
      certificateBundle: `${cert}\n${cert}`,
      escapedBundle: `${freshPublic}\n${cert}`.replace(/\n/g, '\\n'),
    })) {
      add(`rejects ${name} from ${origin}`, async () => {
        if (origin === 'environment') process.env[options.envName] = value
        else publish(value)
        await expectFailure('ERR_JWT_KEY_INVALID')
      })
    }
  }
  add('explicit material uses zero store I/O with an unused relative override', async () => {
    process.env[options.envName] = freshPublic
    process.env.EVENFIRE_DEV_KEY_STORE = 'unused-relative-store'
    assert.equal(fingerprint((await options.loadConfig()).config.jwtPublicKey), fingerprint(freshPublic))
    const result = runRuntime('dist', store, { supplied: freshPublic, consumerOverride: 'unused-relative-store' })
    assert.equal(result.storeOperations, 0)
    assert.equal(result.fingerprint, fingerprint(freshPublic))
  })
  add('malformed explicit input never falls back to a valid producer store', () => {
    const rejected = runRuntime('dist', store, { supplied: 'malformed explicit input' })
    assert.equal(rejected.code, 'ERR_JWT_KEY_INVALID')
    assert.equal(rejected.storeOperations, 0)
    const valid = runRuntime('dist', store)
    assert.equal(valid.signatureVerified, true)
    assert.equal(valid.storeOperations > 0, true)
  })
  add('generated denied identity fails at the actual emitted config boundary', () => {
    const denied = runRuntime('dist', store, { supplied: freshPublic, denied: fingerprint(freshPublic) })
    assert.equal(denied.code, 'ERR_JWT_KEY_BANNED')
    assert.equal(denied.reason, 'banned_identity')
    assert.equal(denied.storeOperations, 0)
    assert.equal(runRuntime('dist', store).signatureVerified, true)
  })
  add('production dev mode rejects before store access with or without explicit material', () => {
    productionEnvironment()
    process.env.CLERUM_DEV_MODE = 'true'
    for (const supplied of [undefined, freshPublic]) {
      const result = runRuntime('dist', store, { supplied, productionDev: true })
      assert.equal(result.productionDevModeRejected, true)
      assert.equal(result.storeOperations, 0)
    }
  })
  for (const devFlag of [undefined, '', 'false', 'TRUE', '1']) {
    add(`fails closed when dev flag is ${JSON.stringify(devFlag)}`, async () => {
      if (devFlag === undefined) delete process.env.CLERUM_DEV_MODE
      else process.env.CLERUM_DEV_MODE = devFlag
      await assert.rejects(options.loadConfig, new RegExp(`Missing required environment variable: ${options.envName}`))
    })
  }
  for (const value of [undefined, '']) {
    add(`fails closed in production with ${JSON.stringify(value)} material`, async () => {
      productionEnvironment()
      if (value === undefined) delete process.env[options.envName]
      else process.env[options.envName] = value
      await assert.rejects(options.loadConfig, new RegExp(`Missing required environment variable: ${options.envName}`))
    })
  }
  add('rejects relative used store paths', async () => {
    process.env.EVENFIRE_DEV_KEY_STORE = 'relative-store'
    await expectFailure('ERR_JWT_DEV_STORE', 'relative_store_path')
  })
  add('requires existing producer material without generating it', async () => {
    await expectFailure('ERR_JWT_DEV_STORE', 'missing_material')
  })
  for (const suffix of ['', '/', '/.']) {
    add(`rejects final-directory symlinks with ${JSON.stringify(suffix)} suffix`, async () => {
      rmdirSync(store)
      const target = join(layout!, 'target')
      mkdirSync(target, { mode: 0o700 })
      writeFileSync(join(target, `${options.slot}.public.pem`), freshPublic, { mode: 0o644 })
      symlinkSync(target, store)
      process.env.EVENFIRE_DEV_KEY_STORE = store + suffix
      await expectFailure('ERR_JWT_DEV_STORE', 'symbolic_link')
    })
  }
  add('rejects writable public files and broad directory permissions', async () => {
    publish()
    chmodSync(publicPath(), 0o666)
    await expectFailure('ERR_JWT_DEV_STORE', 'insecure_file')
    chmodSync(publicPath(), 0o644)
    chmodSync(store, 0o755)
    options.resetModules()
    await expectFailure('ERR_JWT_DEV_STORE', 'insecure_directory')
  })
  add('rejects public symlinks and non-regular public paths', async () => {
    const target = join(layout!, 'public-target.pem')
    writeFileSync(target, freshPublic, { mode: 0o644 })
    symlinkSync(target, publicPath())
    await expectFailure('ERR_JWT_DEV_STORE', 'symbolic_link')
    rmSync(publicPath())
    mkdirSync(publicPath())
    options.resetModules()
    await expectFailure('ERR_JWT_DEV_STORE', 'not_regular_file')
  })

  add('rejects a regular file where the producer directory must be', async () => {
    rmdirSync(store)
    writeFileSync(store, 'directory contract fixture')
    await expectFailure('ERR_JWT_DEV_STORE', 'invalid_directory')
  })
  add('rejects foreign-owned directories after a same-owner positive control', async () => {
    publish()
    const getUid = process.geteuid
    assert.ok(typeof getUid === 'function', 'Ownership cases require POSIX effective-user support')
    const uid = getUid()
    assert.equal(fingerprint((await options.loadConfig()).config.jwtPublicKey), fingerprint(freshPublic))
    options.resetModules()
    await withEffectiveUid([uid + 1], () => expectFailure('ERR_JWT_DEV_STORE', 'directory_owner_mismatch'))
  })
  add('rejects foreign-owned public files after validating the directory', async () => {
    publish()
    const getUid = process.geteuid
    assert.ok(typeof getUid === 'function', 'Ownership cases require POSIX effective-user support')
    const uid = getUid()
    await withEffectiveUid([uid, uid + 1], () => expectFailure('ERR_JWT_DEV_STORE', 'file_owner_mismatch'))
  })

  return { cases, prepare, reset, cleanup, dispose }
}