Skip to content

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

TypeScript
12.3 KB
Raw Blame
import { readFileSync } from 'node:fs'
import type { GatewayConfig, WebhookConfigEntry } from './types'

/**
 * Slowloris budgets are *not* recipe-author tunable (spec §7). They
 * are read from environment variables so ops can tweak per-cluster
 * without rebuilding the image, but the defaults match the spec
 * verbatim and we expect them to never change in v1.
 */
export interface RuntimeBudgets {
  /** Header-receive timeout (ms). */
  headerTimeoutMs: number
  /** Body-receive idle timeout (ms). */
  bodyIdleTimeoutMs: number
  /** Total request lifetime (ms). */
  totalTimeoutMs: number
  /** Maximum concurrent in-flight requests; above → 503 gateway_busy. */
  maxInFlight: number
}

export const DEFAULT_BUDGETS: Readonly<RuntimeBudgets> = Object.freeze({
  headerTimeoutMs: 5_000,
  bodyIdleTimeoutMs: 10_000,
  totalTimeoutMs: 30_000,
  maxInFlight: 256,
})

export interface ServerOptions {
  /** Public-facing port serving /:webhookId routes. */
  httpPort: number
  /** Metrics + /healthz port. Always different from httpPort. */
  metricsPort: number
  budgets: RuntimeBudgets
  configPath: string
  /** When true, log debug info; off in production. */
  debug: boolean
}

function intFromEnv(name: string, fallback: number): number {
  const raw = process.env[name]
  if (!raw) return fallback
  const n = Number(raw)
  if (!Number.isFinite(n) || n <= 0) {
    throw new Error(`${name} must be a positive integer; got ${JSON.stringify(raw)}`)
  }
  return n
}

export function loadServerOptions(): ServerOptions {
  return {
    httpPort: intFromEnv('GATEWAY_HTTP_PORT', 8090),
    metricsPort: intFromEnv('GATEWAY_METRICS_PORT', 9090),
    budgets: {
      headerTimeoutMs: intFromEnv('GATEWAY_HEADER_TIMEOUT_MS', DEFAULT_BUDGETS.headerTimeoutMs),
      bodyIdleTimeoutMs: intFromEnv(
        'GATEWAY_BODY_IDLE_TIMEOUT_MS',
        DEFAULT_BUDGETS.bodyIdleTimeoutMs
      ),
      totalTimeoutMs: intFromEnv('GATEWAY_TOTAL_TIMEOUT_MS', DEFAULT_BUDGETS.totalTimeoutMs),
      maxInFlight: intFromEnv('GATEWAY_MAX_IN_FLIGHT', DEFAULT_BUDGETS.maxInFlight),
    },
    configPath: process.env.GATEWAY_CONFIG_PATH || '/etc/webhook-gateway/config.json',
    debug: process.env.GATEWAY_DEBUG === 'true',
  }
}

/**
 * Pattern shared between webhook-proxy URL parsing and gateway-side
 * revalidation. The gateway re-checks `webhookId` against this
 * BEFORE any config / secret / filesystem lookup as defense-in-depth
 * against a webhook-proxy bug (must-fix #2 in spec security analysis).
 */
export const WEBHOOK_ID_RE = /^[a-z0-9-]{1,63}$/

/** Read + parse the gateway config from disk. Throws on malformed JSON. */
export function loadGatewayConfig(path: string): GatewayConfig {
  const raw = readFileSync(path, 'utf8')
  const parsed = JSON.parse(raw)
  return validateGatewayConfig(parsed)
}

/**
 * Tolerant validator. We trust WRC to write correct config (it just
 * reconciled from the CRD), but we still defensively check shape so a
 * truncated or partially-written file fails loudly instead of running
 * with `undefined` upstreams.
 */
export function validateGatewayConfig(value: unknown): GatewayConfig {
  if (!isObject(value) || !isObject(value.webhooks)) {
    throw new Error('gateway config: missing or non-object `webhooks`')
  }
  const webhooks: Record<string, WebhookConfigEntry> = {}
  for (const [id, entry] of Object.entries(value.webhooks)) {
    if (!WEBHOOK_ID_RE.test(id)) {
      throw new Error(
        `gateway config: webhook id ${JSON.stringify(id)} fails ${WEBHOOK_ID_RE} (config corruption?)`
      )
    }
    webhooks[id] = validateEntry(id, entry)
  }
  return { webhooks }
}

function validateEntry(id: string, value: unknown): WebhookConfigEntry {
  if (!isObject(value)) {
    throw new Error(`gateway config: webhook ${id} is not an object`)
  }
  if (value.id !== id) {
    throw new Error(`gateway config: webhook ${id} has mismatching .id field ${JSON.stringify(value.id)}`)
  }
  const methods = value.methods
  if (!Array.isArray(methods) || methods.length === 0) {
    throw new Error(`gateway config: webhook ${id} has empty/missing methods`)
  }
  for (const m of methods) {
    if (m !== 'POST' && m !== 'GET') {
      throw new Error(`gateway config: webhook ${id} has unsupported method ${JSON.stringify(m)}`)
    }
  }
  if (!methods.includes('POST')) {
    throw new Error(`gateway config: webhook ${id} methods must include POST`)
  }
  const maxBodyBytes = value.maxBodyBytes
  if (typeof maxBodyBytes !== 'number' || maxBodyBytes < 1024 || maxBodyBytes > 10_485_760) {
    throw new Error(`gateway config: webhook ${id} maxBodyBytes out of range`)
  }
  const verification = validateVerification(id, value.verification)
  const replay = validateReplay(id, value.replay, verification.scheme)
  const upstream = validateUpstream(id, value.upstream)
  const setupHandshake = validateSetupHandshake(id, value.setupHandshake, methods as Array<string>)
  const dormant = value.dormant === true
  const dormantSecretName =
    typeof value.dormantSecretName === 'string' && value.dormantSecretName.length > 0
      ? value.dormantSecretName
      : undefined
  return {
    id,
    methods: methods as ReadonlyArray<'POST' | 'GET'>,
    maxBodyBytes,
    verification,
    setupHandshake,
    replay,
    upstream,
    dormant: dormant || undefined,
    dormantSecretName: dormant ? dormantSecretName : undefined,
  }
}

function validateSetupHandshake(
  id: string,
  value: unknown,
  methods: Array<string>,
): WebhookConfigEntry['setupHandshake'] {
  if (value === undefined) {
    if (methods.includes('GET')) {
      throw new Error(
        `gateway config: webhook ${id} methods includes GET but no setupHandshake — admission should have rejected this (W13)`,
      )
    }
    return undefined
  }
  if (!isObject(value)) {
    throw new Error(`gateway config: webhook ${id} setupHandshake is not an object`)
  }
  const strategy = value.strategy
  if (
    strategy !== 'meta-hub-challenge' &&
    strategy !== 'slack-url-verification' &&
    strategy !== 'stripe-verify'
  ) {
    throw new Error(
      `gateway config: webhook ${id} setupHandshake.strategy ${JSON.stringify(strategy)} is not supported`,
    )
  }
  const secretPath = value.secretPath
  if (strategy === 'meta-hub-challenge') {
    if (typeof secretPath !== 'string' || secretPath.length === 0) {
      throw new Error(`gateway config: webhook ${id} meta-hub-challenge requires setupHandshake.secretPath`)
    }
    if (!methods.includes('GET')) {
      throw new Error(`gateway config: webhook ${id} meta-hub-challenge requires methods to include GET`)
    }
    return { strategy, secretPath }
  }
  // slack-url-verification + stripe-verify: secretPath optional / unused.
  if (secretPath !== undefined && (typeof secretPath !== 'string' || secretPath.length === 0)) {
    throw new Error(`gateway config: webhook ${id} setupHandshake.secretPath must be a non-empty string when set`)
  }
  return { strategy, secretPath: typeof secretPath === 'string' ? secretPath : undefined }
}

function validateVerification(id: string, value: unknown): WebhookConfigEntry['verification'] {
  if (!isObject(value)) {
    throw new Error(`gateway config: webhook ${id} is missing verification`)
  }
  switch (value.scheme) {
    case 'hmac-sha256-body':
    case 'hmac-sha256-timestamp-body': {
      const sigHeader = value.signatureHeader
      const sigEncoding = value.signatureEncoding
      const secretPath = value.secretPath
      if (typeof sigHeader !== 'string' || sigHeader.length === 0) {
        throw new Error(`gateway config: webhook ${id} ${value.scheme} missing signatureHeader`)
      }
      if (sigEncoding !== 'hex' && sigEncoding !== 'base64') {
        throw new Error(
          `gateway config: webhook ${id} ${value.scheme} unsupported signatureEncoding ${JSON.stringify(sigEncoding)}`
        )
      }
      if (typeof secretPath !== 'string' || secretPath.length === 0) {
        throw new Error(`gateway config: webhook ${id} ${value.scheme} missing secretPath`)
      }
      return {
        scheme: value.scheme,
        signatureHeader: sigHeader.toLowerCase(),
        signaturePrefix: typeof value.signaturePrefix === 'string' ? value.signaturePrefix : undefined,
        signatureEncoding: sigEncoding,
        secretPath,
      }
    }
    case 'jwt-bearer-jwks': {
      // W1.4 lands the actual verifier; v1.1 schema acceptance only.
      const jwksUrl = value.jwksUrl
      const issuer = value.issuer
      const audience = value.audience
      const jwksPath = value.jwksPath
      if (
        typeof jwksUrl !== 'string' ||
        typeof issuer !== 'string' ||
        typeof audience !== 'string' ||
        typeof jwksPath !== 'string'
      ) {
        throw new Error(`gateway config: webhook ${id} jwt-bearer-jwks missing required fields`)
      }
      return { scheme: 'jwt-bearer-jwks', jwksUrl, issuer, audience, jwksPath }
    }
    case 'static-bearer': {
      const secretPath = value.secretPath
      if (typeof secretPath !== 'string' || secretPath.length === 0) {
        throw new Error(`gateway config: webhook ${id} static-bearer missing secretPath`)
      }
      // Optional custom header / prefix. Author-supplied empty string for
      // tokenPrefix is meaningful ("no prefix"), so we treat undefined and
      // empty string as distinct cases. tokenHeader stores lowercase per
      // type contract — config-write side is expected to lowercase already.
      const rawTokenHeader = value.tokenHeader
      const tokenHeader =
        rawTokenHeader === undefined
          ? undefined
          : typeof rawTokenHeader === 'string' && rawTokenHeader.length > 0
            ? rawTokenHeader.toLowerCase()
            : (() => {
                throw new Error(
                  `gateway config: webhook ${id} static-bearer tokenHeader must be a non-empty string when present`
                )
              })()
      const rawTokenPrefix = value.tokenPrefix
      const tokenPrefix =
        rawTokenPrefix === undefined
          ? undefined
          : typeof rawTokenPrefix === 'string'
            ? rawTokenPrefix
            : (() => {
                throw new Error(
                  `gateway config: webhook ${id} static-bearer tokenPrefix must be a string when present`
                )
              })()
      return {
        scheme: 'static-bearer',
        secretPath,
        ...(tokenHeader !== undefined ? { tokenHeader } : {}),
        ...(tokenPrefix !== undefined ? { tokenPrefix } : {}),
      }
    }
    default:
      throw new Error(
        `gateway config: webhook ${id} has unknown scheme ${JSON.stringify(value.scheme)}`
      )
  }
}

function validateReplay(
  id: string,
  value: unknown,
  scheme: WebhookConfigEntry['verification']['scheme']
): WebhookConfigEntry['replay'] {
  if (scheme === 'hmac-sha256-timestamp-body') {
    if (!isObject(value)) {
      throw new Error(`gateway config: webhook ${id} hmac-sha256-timestamp-body missing replay`)
    }
    if (typeof value.timestampHeader !== 'string' || value.timestampHeader.length === 0) {
      throw new Error(`gateway config: webhook ${id} replay missing timestampHeader`)
    }
    if (
      typeof value.toleranceSec !== 'number' ||
      value.toleranceSec < 10 ||
      value.toleranceSec > 3600
    ) {
      throw new Error(`gateway config: webhook ${id} replay.toleranceSec out of [10,3600]`)
    }
    return {
      timestampHeader: value.timestampHeader.toLowerCase(),
      toleranceSec: value.toleranceSec,
    }
  }
  if (value !== undefined) {
    throw new Error(`gateway config: webhook ${id} replay set on non-timestamp scheme ${scheme}`)
  }
  return undefined
}

function validateUpstream(id: string, value: unknown): WebhookConfigEntry['upstream'] {
  if (!isObject(value)) {
    throw new Error(`gateway config: webhook ${id} missing upstream`)
  }
  if (typeof value.host !== 'string' || value.host.length === 0) {
    throw new Error(`gateway config: webhook ${id} upstream missing host`)
  }
  if (typeof value.port !== 'number' || value.port < 1 || value.port > 65535) {
    throw new Error(`gateway config: webhook ${id} upstream.port out of range`)
  }
  if (typeof value.path !== 'string' || !value.path.startsWith('/')) {
    throw new Error(`gateway config: webhook ${id} upstream.path must start with /`)
  }
  return { host: value.host, port: value.port, path: value.path }
}

function isObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v)
}