Skip to content

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

TypeScript
16.1 KB
Raw Blame
import {
  constants as cryptoConstants,
  createPublicKey,
  createHmac,
  timingSafeEqual,
  verify as cryptoVerify,
} from 'node:crypto'
import type { KeyObject } from 'node:crypto'
import { readFileSync } from 'node:fs'
import type { IncomingHttpHeaders } from 'node:http'
import type { VerifyOutcome, WebhookConfigEntry } from './types'

/**
 * Read a signing secret from disk and return its raw bytes. We use
 * `Buffer` (not `string`) so embedded NULs / non-utf8 bytes survive.
 * Trailing newlines are stripped because `kubectl create secret` adds
 * them and providers sign without them.
 */
export function readSecretFromPath(path: string): Buffer {
  const raw = readFileSync(path)
  // Strip a single trailing \n if present — common Secret-on-disk artefact.
  if (raw.length > 0 && raw[raw.length - 1] === 0x0a) {
    return raw.subarray(0, raw.length - 1)
  }
  return raw
}

/**
 * Decode the per-scheme signature value from its wire encoding into raw
 * bytes for `timingSafeEqual`. Returns `null` on malformed input — the
 * caller maps that to `invalid_signature` (NOT a 4xx telling the
 * attacker their decode failed).
 */
function decodeSignature(value: string, encoding: 'hex' | 'base64'): Buffer | null {
  try {
    if (encoding === 'hex') {
      // Buffer.from(hex) silently truncates on odd length → reject explicitly.
      if (value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) return null
      return Buffer.from(value, 'hex')
    }
    if (!/^[A-Za-z0-9+/=]+$/.test(value)) return null
    return Buffer.from(value, 'base64')
  } catch {
    return null
  }
}

/**
 * Pull a single header value as a lowercase-keyed lookup. Returns
 * `undefined` if the header is absent or arrives multiple times (we
 * reject duplicates — providers don't send dup signature headers, and
 * accepting them lets an attacker stuff a forged value alongside a
 * valid one).
 */
function singleHeader(headers: IncomingHttpHeaders, lowercaseName: string): string | undefined {
  const value = headers[lowercaseName]
  if (value === undefined) return undefined
  if (Array.isArray(value)) return undefined
  return value
}

/**
 * Slice the signaturePrefix off the signature header, if any, and
 * return the bare encoded value. Compound headers like Stripe's
 * `t=...,v1=...` need scheme-aware parsing in W1.2; for v1.1 with
 * only `hmac-sha256-body` the prefix is a flat string match.
 */
function stripPrefix(value: string, prefix: string | undefined): string {
  if (!prefix) return value
  if (value.startsWith(prefix)) return value.slice(prefix.length)
  return value
}

export function verify(
  entry: WebhookConfigEntry,
  headers: IncomingHttpHeaders,
  body: Buffer,
  now: () => number = Date.now
): VerifyOutcome {
  const v = entry.verification
  switch (v.scheme) {
    case 'hmac-sha256-body':
      return verifyHmacSha256Body(v, headers, body)
    case 'static-bearer':
      return verifyStaticBearer(v, headers)
    case 'hmac-sha256-timestamp-body':
      return verifyHmacSha256TimestampBody(v, entry.replay, headers, body, now)
    case 'jwt-bearer-jwks':
      return verifyJwtBearerJwks(v, headers, now)
  }
}

/**
 * Default header / prefix for `static-bearer` when the recipe omits them.
 * Matches the canonical `Authorization: Bearer <token>` shape so existing
 * recipes that just set `secretRef` keep working. Telegram authors set
 * `tokenHeader: x-telegram-bot-api-secret-token` and `tokenPrefix: ''`.
 */
const STATIC_BEARER_DEFAULT_HEADER = 'authorization'
const STATIC_BEARER_DEFAULT_PREFIX = 'Bearer '

function verifyStaticBearer(
  v: Extract<WebhookConfigEntry['verification'], { scheme: 'static-bearer' }>,
  headers: IncomingHttpHeaders
): VerifyOutcome {
  // Header name normalization happens in config.ts. Empty-string prefix is
  // explicit "no prefix" — distinct from undefined which means "use default".
  const headerName = v.tokenHeader ?? STATIC_BEARER_DEFAULT_HEADER
  const prefix = v.tokenPrefix ?? STATIC_BEARER_DEFAULT_PREFIX

  const raw = singleHeader(headers, headerName)
  if (!raw) return { kind: 'invalid_signature' }
  if (prefix.length > 0 && !raw.startsWith(prefix)) {
    // Missing prefix is a verification failure, not a misconfig — we want
    // attackers to learn no more from "wrong prefix" than from "wrong token".
    return { kind: 'invalid_signature' }
  }
  const presented = prefix.length > 0 ? raw.slice(prefix.length) : raw
  if (presented.length === 0) return { kind: 'invalid_signature' }

  let secret: Buffer
  try {
    secret = readSecretFromPath(v.secretPath)
  } catch (err) {
    return {
      kind: 'verifier_misconfigured',
      detail: err instanceof Error ? err.message : String(err),
    }
  }

  const presentedBuf = Buffer.from(presented, 'utf8')
  // timingSafeEqual requires equal-length buffers. Always pad-compare against
  // an equal-length view of secret to keep timing flat regardless of which
  // side is shorter.
  if (presentedBuf.length !== secret.length) {
    // Burn a comparison cycle against secret to keep the timing profile
    // similar to the equal-length path. Result is discarded.
    const padded = Buffer.alloc(secret.length)
    presentedBuf.copy(padded, 0, 0, Math.min(presentedBuf.length, secret.length))
    timingSafeEqual(padded, secret)
    return { kind: 'invalid_signature' }
  }
  return timingSafeEqual(presentedBuf, secret) ? { kind: 'ok' } : { kind: 'invalid_signature' }
}

function verifyHmacSha256Body(
  v: Extract<WebhookConfigEntry['verification'], { scheme: 'hmac-sha256-body' }>,
  headers: IncomingHttpHeaders,
  body: Buffer
): VerifyOutcome {
  const headerValue = singleHeader(headers, v.signatureHeader)
  if (!headerValue) return { kind: 'invalid_signature' }
  const decoded = decodeSignature(stripPrefix(headerValue, v.signaturePrefix), v.signatureEncoding)
  if (!decoded) return { kind: 'invalid_signature' }

  let secret: Buffer
  try {
    secret = readSecretFromPath(v.secretPath)
  } catch (err) {
    // Secret file missing / unreadable is a platform fault, not a request fault.
    return {
      kind: 'verifier_misconfigured',
      detail: err instanceof Error ? err.message : String(err),
    }
  }

  const expected = createHmac('sha256', secret).update(body).digest()
  if (expected.length !== decoded.length) return { kind: 'invalid_signature' }
  // timingSafeEqual requires equal-length buffers; we already short-circuit above.
  return timingSafeEqual(expected, decoded) ? { kind: 'ok' } : { kind: 'invalid_signature' }
}

/**
 * Stripe-style "v1=<hex>" / Slack-style "v0=<hex>" HMAC over `${ts}.${body}`.
 * The timestamp is signed alongside the body so replays of an old, otherwise
 * valid request fall outside the tolerance window and get rejected with
 * `timestamp_skew` (mapped to 408 by the server). We require config-layer
 * presence of `entry.replay` — the config validator already enforces this for
 * the timestamp scheme, but we re-check defensively because the type cannot.
 */
function verifyHmacSha256TimestampBody(
  v: Extract<WebhookConfigEntry['verification'], { scheme: 'hmac-sha256-timestamp-body' }>,
  replay: WebhookConfigEntry['replay'],
  headers: IncomingHttpHeaders,
  body: Buffer,
  now: () => number
): VerifyOutcome {
  if (!replay) {
    return {
      kind: 'verifier_misconfigured',
      detail: 'hmac-sha256-timestamp-body requires replay config',
    }
  }

  const tsRaw = singleHeader(headers, replay.timestampHeader)
  if (!tsRaw) return { kind: 'invalid_signature' }
  // Whole-number seconds only — providers (Stripe, Slack) send Unix seconds as
  // an integer string. Reject decimals, signs, whitespace, leading zeros are
  // tolerated by Number() but the regex rejects everything non-digit so the
  // signing-input string equals the header value byte-for-byte.
  if (!/^[0-9]+$/.test(tsRaw)) return { kind: 'invalid_signature' }
  const ts = Number(tsRaw)
  if (!Number.isFinite(ts)) return { kind: 'invalid_signature' }
  const nowSec = Math.floor(now() / 1000)
  if (Math.abs(nowSec - ts) > replay.toleranceSec) {
    return { kind: 'timestamp_skew' }
  }

  const headerValue = singleHeader(headers, v.signatureHeader)
  if (!headerValue) return { kind: 'invalid_signature' }
  const decoded = decodeSignature(stripPrefix(headerValue, v.signaturePrefix), v.signatureEncoding)
  if (!decoded) return { kind: 'invalid_signature' }

  let secret: Buffer
  try {
    secret = readSecretFromPath(v.secretPath)
  } catch (err) {
    return {
      kind: 'verifier_misconfigured',
      detail: err instanceof Error ? err.message : String(err),
    }
  }

  // Stripe/Slack canonical signing input: `${tsRaw}.${body}`. The dot is a
  // literal separator — both providers document it. We MUST use the timestamp
  // string as it appeared on the wire (not a parsed/normalized form), because
  // the provider signed those exact bytes.
  const signingInput = Buffer.concat([
    Buffer.from(tsRaw, 'utf8'),
    Buffer.from('.', 'utf8'),
    body,
  ])
  const expected = createHmac('sha256', secret).update(signingInput).digest()
  if (expected.length !== decoded.length) return { kind: 'invalid_signature' }
  return timingSafeEqual(expected, decoded) ? { kind: 'ok' } : { kind: 'invalid_signature' }
}

// ─── jwt-bearer-jwks ──────────────────────────────────────────────────────

/**
 * Algorithms we accept. HS* is intentionally excluded — using HMAC with a
 * public-key set is the classic JWT confusion attack, and JWKS endpoints
 * publish public keys. `none` is excluded for the same reason — never honor
 * an unsigned JWT regardless of header.
 */
const JWT_ALG_TO_NODE: Record<string, { algorithm: string; padding?: number; dsaEncoding?: 'der' | 'ieee-p1363' }> = {
  RS256: { algorithm: 'RSA-SHA256' },
  RS384: { algorithm: 'RSA-SHA384' },
  RS512: { algorithm: 'RSA-SHA512' },
  PS256: { algorithm: 'RSA-SHA256', padding: cryptoConstants.RSA_PKCS1_PSS_PADDING },
  PS384: { algorithm: 'RSA-SHA384', padding: cryptoConstants.RSA_PKCS1_PSS_PADDING },
  PS512: { algorithm: 'RSA-SHA512', padding: cryptoConstants.RSA_PKCS1_PSS_PADDING },
  ES256: { algorithm: 'sha256', dsaEncoding: 'ieee-p1363' },
  ES384: { algorithm: 'sha384', dsaEncoding: 'ieee-p1363' },
  ES512: { algorithm: 'sha512', dsaEncoding: 'ieee-p1363' },
}

/** Clock-skew tolerance for JWT `exp`/`nbf` checks. 60s matches industry default. */
const JWT_CLOCK_SKEW_SEC = 60

interface JwtHeader {
  alg: string
  kid?: string
  typ?: string
}

interface JwtPayload {
  iss?: string
  aud?: string | string[]
  sub?: string
  exp?: number
  nbf?: number
  iat?: number
  [k: string]: unknown
}

interface Jwk {
  kty: string
  kid?: string
  use?: string
  alg?: string
  [k: string]: unknown
}

interface Jwks {
  keys: Jwk[]
}

function decodeBase64UrlJson<T>(segment: string): T | null {
  try {
    const buf = Buffer.from(segment, 'base64url')
    if (buf.length === 0) return null
    const text = buf.toString('utf8')
    const parsed = JSON.parse(text)
    if (typeof parsed !== 'object' || parsed === null) return null
    return parsed as T
  } catch {
    return null
  }
}

function loadJwks(path: string): Jwks | { error: string } {
  let raw: Buffer
  try {
    raw = readFileSync(path)
  } catch (err) {
    return { error: err instanceof Error ? err.message : String(err) }
  }
  try {
    const parsed = JSON.parse(raw.toString('utf8'))
    if (
      typeof parsed !== 'object' ||
      parsed === null ||
      !Array.isArray((parsed as { keys: unknown }).keys)
    ) {
      return { error: 'jwks file missing "keys" array' }
    }
    const keys = (parsed as { keys: unknown[] }).keys.filter(
      (k): k is Jwk => typeof k === 'object' && k !== null && typeof (k as Jwk).kty === 'string'
    )
    return { keys }
  } catch (err) {
    return { error: err instanceof Error ? err.message : String(err) }
  }
}

function pickKey(jwks: Jwks, kid: string | undefined): Jwk | null {
  if (kid !== undefined) {
    return jwks.keys.find(k => k.kid === kid) ?? null
  }
  // No kid in the header — only acceptable if the JWKS has exactly one key.
  // Otherwise we cannot identify which to use, and silently picking the first
  // is a footgun (rotation invalidates the wrong-key set).
  return jwks.keys.length === 1 ? jwks.keys[0] : null
}

function importJwkKey(jwk: Jwk): KeyObject | null {
  try {
    return createPublicKey({ key: jwk as Record<string, unknown>, format: 'jwk' })
  } catch {
    return null
  }
}

function verifyJwtBearerJwks(
  v: Extract<WebhookConfigEntry['verification'], { scheme: 'jwt-bearer-jwks' }>,
  headers: IncomingHttpHeaders,
  now: () => number
): VerifyOutcome {
  const auth = singleHeader(headers, 'authorization')
  if (!auth || !auth.startsWith('Bearer ')) return { kind: 'invalid_signature' }
  const token = auth.slice('Bearer '.length)
  if (token.length === 0) return { kind: 'invalid_signature' }

  const parts = token.split('.')
  if (parts.length !== 3) return { kind: 'invalid_signature' }
  const [headerSeg, payloadSeg, sigSeg] = parts
  if (!headerSeg || !payloadSeg || !sigSeg) return { kind: 'invalid_signature' }

  const header = decodeBase64UrlJson<JwtHeader>(headerSeg)
  if (!header || typeof header.alg !== 'string') return { kind: 'invalid_signature' }
  const algSpec = JWT_ALG_TO_NODE[header.alg]
  if (!algSpec) {
    // Unsupported alg (incl. `none`, HS256/384/512) — reject as an invalid
    // signature so attackers learn nothing about which algs we accept.
    return { kind: 'invalid_signature' }
  }
  const kid = typeof header.kid === 'string' ? header.kid : undefined

  const payload = decodeBase64UrlJson<JwtPayload>(payloadSeg)
  if (!payload) return { kind: 'invalid_signature' }

  let signature: Buffer
  try {
    signature = Buffer.from(sigSeg, 'base64url')
    if (signature.length === 0) return { kind: 'invalid_signature' }
  } catch {
    return { kind: 'invalid_signature' }
  }

  // Load JWKS from disk on every request — the file is small and the
  // reconciler bakes a fresh copy each rotation. If perf is ever an issue,
  // wrap this in an mtime-keyed cache.
  const jwks = loadJwks(v.jwksPath)
  if ('error' in jwks) {
    return { kind: 'verifier_misconfigured', detail: `jwks load: ${jwks.error}` }
  }
  const jwk = pickKey(jwks, kid)
  if (!jwk) return { kind: 'invalid_signature' }

  // If the JWK pins an alg, reject mismatches before importing — a key
  // tagged RS256 must not be used to verify an ES256 token, even if the
  // crypto operation would succeed mechanically.
  if (typeof jwk.alg === 'string' && jwk.alg !== header.alg) {
    return { kind: 'invalid_signature' }
  }

  const publicKey = importJwkKey(jwk)
  if (!publicKey) {
    return { kind: 'verifier_misconfigured', detail: 'jwks entry rejected by crypto.createPublicKey' }
  }

  const signingInput = Buffer.from(`${headerSeg}.${payloadSeg}`, 'utf8')
  const keyForVerify: Parameters<typeof cryptoVerify>[2] =
    algSpec.padding !== undefined || algSpec.dsaEncoding !== undefined
      ? {
          key: publicKey,
          ...(algSpec.padding !== undefined ? { padding: algSpec.padding } : {}),
          ...(algSpec.dsaEncoding !== undefined ? { dsaEncoding: algSpec.dsaEncoding } : {}),
        }
      : publicKey
  let ok = false
  try {
    ok = cryptoVerify(algSpec.algorithm, signingInput, keyForVerify, signature)
  } catch {
    return { kind: 'invalid_signature' }
  }
  if (!ok) return { kind: 'invalid_signature' }

  // Claim checks run AFTER signature verification — never trust claim values
  // from an unverified token.
  const nowSec = Math.floor(now() / 1000)
  if (typeof payload.exp !== 'number') return { kind: 'invalid_signature' }
  if (nowSec >= payload.exp + JWT_CLOCK_SKEW_SEC) return { kind: 'invalid_signature' }
  if (typeof payload.nbf === 'number' && nowSec + JWT_CLOCK_SKEW_SEC < payload.nbf) {
    return { kind: 'invalid_signature' }
  }
  if (payload.iss !== v.issuer) return { kind: 'invalid_signature' }
  // aud may be a string or array per RFC 7519. The configured audience must
  // appear in either form.
  if (typeof payload.aud === 'string') {
    if (payload.aud !== v.audience) return { kind: 'invalid_signature' }
  } else if (Array.isArray(payload.aud)) {
    if (!payload.aud.includes(v.audience)) return { kind: 'invalid_signature' }
  } else {
    return { kind: 'invalid_signature' }
  }

  return { kind: 'ok' }
}