Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
18.2 KB
Raw Blame
/**
 * Unit tests for the Cloudflare Email Worker's pure helpers.
 *
 * The worker itself runs on Workers Runtime, but the helpers exercised
 * here only depend on Web Platform APIs (TextEncoder, btoa, crypto) that
 * Node 24 implements natively — no special test harness needed. The
 * `email()` handler itself isn't covered here (it'd need a fake
 * ForwardableEmailMessage + a network stub for the inbound POST) — those
 * paths are best validated end-to-end with `wrangler dev`.
 *
 * Run: npm test (from repo root)
 */
import { test } from 'node:test'
import { readFile } from 'node:fs/promises'
import assert from 'node:assert/strict'
import worker, {
  recipientAccepted,
  synthesizeMessageId,
  SYNTH_ID_BUCKET_MS,
  readArrayHeader,
  toBase64,
  getHeader,
  MAX_ATTACHMENT_BYTES,
  MAX_TOTAL_ATTACHMENT_BYTES,
} from './index.js'
import { deriveAuthVerdict } from './auth-verdict.js'

/* ============================ recipientAccepted ============================ */

const envSingleDomain = { EMAIL_ROOT_DOMAINS: 'cumora.ai' } as never as Parameters<typeof recipientAccepted>[1]
const envMultiDomain = { EMAIL_ROOT_DOMAINS: 'cumora.ai, cumora.dev , example.com' } as never as Parameters<typeof recipientAccepted>[1]

test('recipientAccepted matches exact apex', () => {
  assert.equal(recipientAccepted('[email protected]', envSingleDomain), true)
})

test('recipientAccepted matches subdomain', () => {
  assert.equal(recipientAccepted('[email protected]', envSingleDomain), true)
})

test('recipientAccepted rejects unknown domain', () => {
  assert.equal(recipientAccepted('[email protected]', envSingleDomain), false)
})

test('recipientAccepted handles multi-domain allowlist', () => {
  assert.equal(recipientAccepted('[email protected]', envMultiDomain), true)
  assert.equal(recipientAccepted('[email protected]', envMultiDomain), true)
  assert.equal(recipientAccepted('[email protected]', envMultiDomain), false)
})

test('recipientAccepted is case-insensitive', () => {
  assert.equal(recipientAccepted('[email protected]', envSingleDomain), true)
})

test('recipientAccepted rejects malformed', () => {
  assert.equal(recipientAccepted('no-at-sign', envSingleDomain), false)
})

test('recipientAccepted does NOT match suffix-of-other-domain (apple.com vs evilapple.com)', () => {
  // Guards against the classic mistake of `endsWith('apple.com')` matching
  // `evilapple.com`. The check requires either an exact match OR `.<root>`.
  const env = { EMAIL_ROOT_DOMAINS: 'apple.com' } as never as Parameters<typeof recipientAccepted>[1]
  assert.equal(recipientAccepted('[email protected]', env), false)
  assert.equal(recipientAccepted('[email protected]', env), true)
})

/* ============================== readArrayHeader =========================== */

test('readArrayHeader returns [] for empty/missing', () => {
  assert.deepEqual(readArrayHeader(undefined), [])
  assert.deepEqual(readArrayHeader(''), [])
  assert.deepEqual(readArrayHeader('   '), [])
})

test('readArrayHeader splits angle-bracketed References on whitespace', () => {
  const r = readArrayHeader('<a@x> <b@y>\n<c@z>')
  assert.deepEqual(r, ['a@x', 'b@y', 'c@z'])
})

test('readArrayHeader strips repeated angle brackets', () => {
  assert.deepEqual(readArrayHeader('<<a@x>>'), ['a@x'])
})

/* =================================== toBase64 ============================== */

test('toBase64 round-trips ASCII', () => {
  const bytes = new TextEncoder().encode('Hello, world')
  const b64 = toBase64(bytes)
  assert.equal(b64, 'SGVsbG8sIHdvcmxk')
})

test('toBase64 handles binary bytes', () => {
  const bytes = new Uint8Array([0, 1, 2, 3, 255, 254])
  const b64 = toBase64(bytes)
  // Decode back via Buffer to verify symmetry without trusting our own impl.
  const back = Buffer.from(b64, 'base64')
  assert.deepEqual(Array.from(back), [0, 1, 2, 3, 255, 254])
})

test('toBase64 handles multi-chunk inputs (>32KB)', () => {
  // Chunk size in the impl is 0x8000 (32768). Build something larger so we
  // know the chunk-loop path runs.
  const big = new Uint8Array(70_000).fill(0x41)  // 70KB of 'A'
  const b64 = toBase64(big)
  const back = Buffer.from(b64, 'base64')
  assert.equal(back.length, 70_000)
  assert.equal(back[0], 0x41)
  assert.equal(back[69_999], 0x41)
})

/* =================================== getHeader ============================ */

test('getHeader does case-insensitive lookup', () => {
  const headers = [
    { key: 'X-Custom', value: 'one' },
    { key: 'auto-submitted', value: 'auto-replied' },
  ]
  assert.equal(getHeader(headers, 'Auto-Submitted'), 'auto-replied')
  assert.equal(getHeader(headers, 'x-custom'), 'one')
  assert.equal(getHeader(headers, 'missing'), undefined)
})

test('getHeader returns first match', () => {
  const headers = [
    { key: 'X-Foo', value: 'first' },
    { key: 'x-foo', value: 'second' },
  ]
  assert.equal(getHeader(headers, 'X-Foo'), 'first')
})

/* ============================== deriveAuthVerdict ========================= */

const cf = (value: string) => [{ key: 'Authentication-Results', value: `mx.cloudflare.net; ${value}` }]

test('authVerdict is derived from Cloudflare Authentication-Results', () => {
  assert.equal(deriveAuthVerdict(cf('dmarc=pass; spf=pass')), 'aligned')
  assert.equal(deriveAuthVerdict(cf('spf=pass; dkim=pass')), 'aligned')
  assert.equal(
    deriveAuthVerdict(cf('spf=pass; dkim=fail')),
    'unaligned',
    'SPF pass alone does not authenticate the header From',
  )
  assert.equal(
    deriveAuthVerdict([{ key: 'Authentication-Results', value: 'mx.cloudflare.net; dmarc=pass-not-really' }]),
    'unaligned',
    'a longer token that starts with "pass" is not a pass',
  )
  assert.equal(deriveAuthVerdict(cf('dmarc=passfail')), 'unaligned')
  assert.equal(deriveAuthVerdict(cf('dmarc=pass/fail')), 'unaligned')
})

test('authVerdict ignores a pass that only appears inside a comment', () => {
  assert.equal(deriveAuthVerdict(cf('spf=fail (dmarc=pass)')), 'unaligned')
})

test('authVerdict ignores a sender-forged Authentication-Results authserv-id', () => {
  assert.equal(
    deriveAuthVerdict([{ key: 'Authentication-Results', value: 'attacker.example; dmarc=pass' }]),
    'unaligned',
  )
  assert.equal(deriveAuthVerdict(cf('xdmarc=pass')), 'unaligned')
  assert.equal(deriveAuthVerdict(undefined), 'unaligned')
})

test('authVerdict fails closed when two records claim Cloudflare', () => {
  assert.equal(deriveAuthVerdict([
    { key: 'Authentication-Results', value: 'mx.cloudflare.net; dmarc=pass' },
    { key: 'Authentication-Results', value: 'mx.cloudflare.net; dmarc=fail' },
  ]), 'unaligned')
  // Fetch Headers joins repeated fields with ", " before the worker sees them.
  const headers = new Headers()
  headers.append('authentication-results', 'mx.cloudflare.net; dmarc=pass')
  headers.append('authentication-results', 'mx.cloudflare.net; dmarc=fail')
  assert.equal(deriveAuthVerdict(headers), 'unaligned')
})

test('authVerdict uses the single Cloudflare record and ignores a forged one', () => {
  assert.equal(deriveAuthVerdict([
    { key: 'Authentication-Results', value: 'attacker.example; dmarc=pass' },
    { key: 'Authentication-Results', value: 'mx.cloudflare.net; dmarc=fail header.from=victim.test' },
  ]), 'unaligned')
  assert.equal(deriveAuthVerdict([
    { key: 'Authentication-Results', value: 'attacker.example; dmarc=fail' },
    { key: 'Authentication-Results', value: 'mx.cloudflare.net;\r\n\tdmarc=pass (p=REJECT) header.from=victim.test' },
  ]), 'aligned')
})

test('authVerdict treats any DMARC result other than pass as unaligned', () => {
  assert.equal(deriveAuthVerdict(cf('spf=pass; dkim=pass; dmarc=fail')), 'unaligned')
  assert.equal(deriveAuthVerdict(cf('spf=pass; dkim=pass; dmarc=none')), 'unaligned')
  assert.equal(deriveAuthVerdict(cf('DMARC=Pass')), 'aligned')
})

/* ============================== attachment caps =========================== */

test('attachment byte limits are sensibly ordered', () => {
  // Sanity guards on the constants: per-attachment cap must be < total cap,
  // and total cap must leave headroom under the server's 25MB JSON limit
  // after base64 expansion (~33% overhead).
  assert.ok(MAX_ATTACHMENT_BYTES < MAX_TOTAL_ATTACHMENT_BYTES)
  assert.ok(MAX_TOTAL_ATTACHMENT_BYTES * 1.34 < 25 * 1024 * 1024)
})

/* ==================== email() handler error handling ======================= */

function createFakeMessage() {
  const rejected: string[] = []
  const rawStream = new Response(
    'From: [email protected]\r\nTo: [email protected]\r\nSubject: Test\r\nMessage-ID: <[email protected]>\r\n\r\nHello',
  ).body!
  const message = {
    to: '[email protected]',
    from: '[email protected]',
    raw: rawStream,
    setReject: (reason: string) => { rejected.push(reason) },
  } as unknown as Parameters<typeof worker.email>[0]
  return { message, rejected }
}

const fakeEnv = {
  EMAIL_ROOT_DOMAINS: 'cumora.ai',
  EMAIL_INBOUND_HMAC_SECRET: 'test-secret-value-12345',
  CUMORA_INBOUND_URL: 'http://upstream.local/inbound',
} as unknown as Parameters<typeof worker.email>[1]

const fakeCtx = {
  waitUntil: (promise: Promise<unknown>) => { void promise.catch(() => {}) },
  passThroughOnException: () => {},
} as unknown as Parameters<typeof worker.email>[2]

test('email handler throws on upstream network error (triggering SMTP tempfail)', async () => {
  const { message, rejected } = createFakeMessage()
  const originalFetch = globalThis.fetch
  globalThis.fetch = async () => {
    throw new Error('connection reset by peer')
  }
  try {
    await assert.rejects(
      () => worker.email(message, fakeEnv, fakeCtx),
      /Upstream unreachable: connection reset by peer/,
    )
    assert.deepEqual(rejected, [], 'setReject must NOT be called on transient network error')
  } finally {
    globalThis.fetch = originalFetch
  }
})

test('email handler throws on upstream 5xx error (triggering SMTP tempfail)', async () => {
  const { message, rejected } = createFakeMessage()
  const originalFetch = globalThis.fetch
  globalThis.fetch = async () => new Response('Internal Server Error', { status: 502 })
  try {
    await assert.rejects(
      () => worker.email(message, fakeEnv, fakeCtx),
      /Upstream temporary failure \(502\)/,
    )
    assert.deepEqual(rejected, [], 'setReject must NOT be called on 5xx error')
  } finally {
    globalThis.fetch = originalFetch
  }
})

/* ===================== the envelope recipient is forwarded ================= */

test('email handler forwards the envelope recipient it admitted the message on', async () => {
  // The handler gates on recipientAccepted(message.to) — the ENVELOPE
  // recipient — and then forwarded every field except that one. Whenever the
  // agent is Bcc'd or reached via an alias, a list expansion or a forwarding
  // rule, its address is in no header, so the server resolved nobody and
  // answered 404, which this handler turns into a permanent SMTP 550.
  const rejected: string[] = []
  const message = {
    // Delivered to the agent; the visible header names someone else.
    to: '[email protected]',
    from: '[email protected]',
    raw: new Response(
      'From: [email protected]\r\nTo: [email protected]\r\nSubject: Test\r\nMessage-ID: <[email protected]>\r\n\r\nHello',
    ).body!,
    setReject: (reason: string) => { rejected.push(reason) },
  } as unknown as Parameters<typeof worker.email>[0]

  let posted: Record<string, unknown> | null = null
  const originalFetch = globalThis.fetch
  globalThis.fetch = async (_url, init) => {
    posted = JSON.parse(String((init as RequestInit).body))
    return new Response('ok', { status: 200 })
  }
  try {
    await worker.email(message, fakeEnv, fakeCtx)
  } finally {
    globalThis.fetch = originalFetch
  }

  assert.deepEqual(rejected, [])
  assert.ok(posted, 'nothing was posted upstream')
  assert.equal(
    (posted as { envelopeTo?: string }).envelopeTo, '[email protected]',
    'the address the handler admitted this message on was not forwarded — a Bcc\'d agent resolves to nobody and gets a 550',
  )
  assert.equal((posted as { authVerdict?: string }).authVerdict, 'unaligned')
  assert.equal((posted as { envelopeFrom?: string }).envelopeFrom, '[email protected]')
  // The visible header is still reported as-is; envelopeTo is additive.
  assert.deepEqual((posted as { to?: string[] }).to, ['[email protected]'])
})

test('email handler rejects with 550 bounce on 404 no recipient', async () => {
  const { message, rejected } = createFakeMessage()
  const originalFetch = globalThis.fetch
  globalThis.fetch = async () => new Response('Not Found', { status: 404 })
  try {
    await worker.email(message, fakeEnv, fakeCtx)
    assert.deepEqual(rejected, ['No such recipient'])
  } finally {
    globalThis.fetch = originalFetch
  }
})

test('email handler rejects with 550 bounce on 4xx client errors', async () => {
  const { message, rejected } = createFakeMessage()
  const originalFetch = globalThis.fetch
  globalThis.fetch = async () => new Response('Bad Request', { status: 400 })
  try {
    await worker.email(message, fakeEnv, fakeCtx)
    assert.deepEqual(rejected, ['Upstream 400'])
  } finally {
    globalThis.fetch = originalFetch
  }
})

test('email handler accepts email on 200 response without setReject', async () => {
  const { message, rejected } = createFakeMessage()
  const originalFetch = globalThis.fetch
  globalThis.fetch = async () => new Response('OK', { status: 200 })
  try {
    await worker.email(message, fakeEnv, fakeCtx)
    assert.deepEqual(rejected, [])
  } finally {
    globalThis.fetch = originalFetch
  }
})


/* ========================= synthesizeMessageId ========================= */
//
// A message with no `Message-Id:` gets one fabricated here. It has to be
// DERIVED, not random: the worker throws on an upstream 5xx or a network
// failure so the sending MTA tempfails and retries, and that retry runs this
// worker again on the same physical message. The server dedups on
// smtp_message_id, so a random id per attempt is a fresh delivery per attempt.

const sameMessage = {
  envelopeFrom: '[email protected]',
  envelopeTo: '[email protected]',
  date: 'Mon, 08 Sep 2026 09:14:02 +0000',
  subject: 'disk 91% on db-2',
  body: 'threshold crossed at 09:14',
}

test('synthesizeMessageId is stable across a retry of the same message', async () => {
  // The retry arrives as a new SMTP transaction with its own Received: headers,
  // so only the parsed fields can be hashed — and they must give the same id.
  assert.equal(await synthesizeMessageId(sameMessage), await synthesizeMessageId({ ...sameMessage }))
})

test('synthesizeMessageId separates two genuinely different messages', async () => {
  const base = await synthesizeMessageId(sameMessage)
  for (const variant of [
    { ...sameMessage, envelopeFrom: '[email protected]' },
    { ...sameMessage, envelopeTo: '[email protected]' },
    { ...sameMessage, date: 'Mon, 08 Sep 2026 09:15:02 +0000' },
    { ...sameMessage, subject: 'disk 92% on db-2' },
    { ...sameMessage, body: 'threshold crossed at 09:15' },
  ]) {
    assert.notEqual(await synthesizeMessageId(variant), base)
  }
})

test('synthesizeMessageId cannot have a field boundary forged by content', async () => {
  // Fields are NUL-joined, so moving text across a boundary must change the id.
  assert.notEqual(
    await synthesizeMessageId({ ...sameMessage, subject: 'a', body: 'bc' }),
    await synthesizeMessageId({ ...sameMessage, subject: 'ab', body: 'c' }),
  )
})

test('synthesizeMessageId falls back to a coarse bucket when Date is missing', async () => {
  // A sender that omitted Message-Id may have omitted Date too. Within one
  // bucket a retry still dedups; that is the original intent of this fallback.
  const undated = { ...sameMessage, date: undefined }
  assert.equal(await synthesizeMessageId(undated), await synthesizeMessageId({ ...undated }))
  assert.ok(SYNTH_ID_BUCKET_MS >= 60 * 60 * 1000, 'the bucket must outlast an MTA first retry')
})

test('synthesizeMessageId produces a shape the server will accept', async () => {
  const id = await synthesizeMessageId(sameMessage)
  assert.match(id, /^synth-[0-9a-f]{64}@cumora-email-gate$/)
  assert.doesNotMatch(id, /[<>\s]/)
})

test('email handler forwards an aligned verdict from Cloudflare headers', async () => {
  const rejected: string[] = []
  const message = {
    to: '[email protected]',
    from: '[email protected]',
    headers: new Headers({
      'authentication-results': 'mx.cloudflare.net; dmarc=pass header.from=example.com',
    }),
    raw: new Response(
      'From: [email protected]\r\nTo: [email protected]\r\nSubject: Test\r\nMessage-ID: <[email protected]>\r\nAuthentication-Results: attacker.example; dmarc=fail\r\n\r\nHello',
    ).body!,
    setReject: (reason: string) => { rejected.push(reason) },
  } as unknown as Parameters<typeof worker.email>[0]

  let posted: { authVerdict?: string; envelopeFrom?: string } | null = null
  const originalFetch = globalThis.fetch
  globalThis.fetch = async (_url, init) => {
    posted = JSON.parse(String((init as RequestInit).body))
    return new Response('ok', { status: 200 })
  }
  try {
    await worker.email(message, fakeEnv, fakeCtx)
  } finally {
    globalThis.fetch = originalFetch
  }

  assert.deepEqual(rejected, [])
  assert.equal(posted?.authVerdict, 'aligned')
  assert.equal(posted?.envelopeFrom, '[email protected]')
})

test('the email handler derives authVerdict instead of forwarding the raw header', async () => {
  const source = await readFile(new URL('./index.ts', import.meta.url), 'utf8')
  const handler = source.slice(source.indexOf('export default {'))
  assert.match(handler, /deriveAuthVerdict\(message\.headers\)/)
  assert.match(handler, /envelopeFrom:\s*message\.from/)
  assert.doesNotMatch(
    handler,
    /dmarc=pass/,
    'the handler must not match the Authentication-Results text itself',
  )
})

test('the email handler synthesizes its id instead of drawing a random one', async () => {
  // Every test above passes just as well against a handler that went back to
  // `randomUUID()` — they exercise the helper, not the call site. Read the
  // source so the call site cannot quietly stop using it.
  const source = await readFile(new URL('./index.ts', import.meta.url), 'utf8')
  const handler = source.slice(source.indexOf('export default {'))

  assert.match(handler, /synthesizeMessageId\(/, 'the handler no longer derives the fallback id')
  assert.doesNotMatch(
    handler, /randomUUID/,
    'the fallback Message-Id is random again — every MTA retry of the same message will deliver a duplicate',
  )
})