fix(mailtrap): validate nested payloads and unbalanced address delimiters

Response payloads (utils.ts + read transforms):
- add expectRecord / expectArray / expectContactList / expectSendingMessage
- get/create/update_contact require the `data` object; the contact-list
  transforms require a numeric `id`; get_email_log requires a `message_id`;
  list_email_logs requires a `messages` array
- a well-formed 2xx body that is missing its defining slice ({} on
  get_contact, { "messages": "bad" } on list_email_logs) now fails instead
  of producing a fabricated empty result
- the list transforms keep the lenient per-row mappers, so one bad row
  does not drop the whole page

Recipient tokenizer (utils.ts):
- splitAddressEntries throws on an unbalanced quote or angle bracket
  instead of running to the end of the string and absorbing every
  following recipient into one entry
- each address is checked against a bare-address pattern
  (/^[^\s"<>,@]+@[^\s"<>,@]+$/) rather than a bare "contains @" test, so a
  value carrying spaces, commas, or brackets is rejected

Author: dr-3lo

apps/sim/tools/mailtrap/create_contact.ts

@@ -4,7 +4,13 @@ import {
   type MailtrapCreateContactParams,
   type MailtrapCreateContactResult,
 } from '@/tools/mailtrap/types'
-import { mapContact, parseIdList, parseJsonRecord, readJsonBody } from '@/tools/mailtrap/utils'
+import {
+  expectRecord,
+  mapContact,
+  parseIdList,
+  parseJsonRecord,
+  readJsonBody,
+} from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapCreateContactTool: ToolConfig<
@@ -70,7 +76,7 @@ export const mailtrapCreateContactTool: ToolConfig<
     return {
       success: true,
       output: {
-        contact: mapContact(data.data),
+        contact: mapContact(expectRecord(data.data, 'the contact payload')),
       },
     }
   },

apps/sim/tools/mailtrap/create_contact_list.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapContactListResult,
   type MailtrapCreateContactListParams,
 } from '@/tools/mailtrap/types'
-import { mapContactList, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectContactList, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapCreateContactListTool: ToolConfig<
@@ -46,7 +46,7 @@ export const mailtrapCreateContactListTool: ToolConfig<
     const data = await readJsonBody(response)
     return {
       success: true,
-      output: { list: mapContactList(data) },
+      output: { list: expectContactList(data) },
     }
   },
 

apps/sim/tools/mailtrap/get_contact.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapGetContactParams,
   type MailtrapGetContactResult,
 } from '@/tools/mailtrap/types'
-import { mapContact, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectRecord, mapContact, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapGetContactTool: ToolConfig<
@@ -46,7 +46,7 @@ export const mailtrapGetContactTool: ToolConfig<
     return {
       success: true,
       output: {
-        contact: mapContact(data.data),
+        contact: mapContact(expectRecord(data.data, 'the contact payload')),
       },
     }
   },

apps/sim/tools/mailtrap/get_contact_list.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapContactListResult,
   type MailtrapGetContactListParams,
 } from '@/tools/mailtrap/types'
-import { mapContactList, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectContactList, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapGetContactListTool: ToolConfig<
@@ -45,7 +45,7 @@ export const mailtrapGetContactListTool: ToolConfig<
     const data = await readJsonBody(response)
     return {
       success: true,
-      output: { list: mapContactList(data) },
+      output: { list: expectContactList(data) },
     }
   },
 

apps/sim/tools/mailtrap/get_email_log.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapGetEmailLogParams,
   type MailtrapGetEmailLogResult,
 } from '@/tools/mailtrap/types'
-import { mapSendingMessage, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectSendingMessage, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapGetEmailLogTool: ToolConfig<
@@ -48,7 +48,7 @@ export const mailtrapGetEmailLogTool: ToolConfig<
       success: true,
       output: {
         message: {
-          ...mapSendingMessage(data),
+          ...expectSendingMessage(data),
           rawMessageUrl: typeof data.raw_message_url === 'string' ? data.raw_message_url : null,
           events: Array.isArray(data.events) ? (data.events as Array<Record<string, unknown>>) : [],
         },

apps/sim/tools/mailtrap/list_email_logs.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapListEmailLogsParams,
   type MailtrapListEmailLogsResult,
 } from '@/tools/mailtrap/types'
-import { mapSendingMessage, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectArray, mapSendingMessage, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 /** Splits a comma-separated filter value into trimmed, non-empty entries. */
@@ -171,7 +171,7 @@ export const mailtrapListEmailLogsTool: ToolConfig<
 
   transformResponse: async (response): Promise<MailtrapListEmailLogsResult> => {
     const data = await readJsonBody(response)
-    const messages = Array.isArray(data.messages) ? data.messages.map(mapSendingMessage) : []
+    const messages = expectArray(data.messages, 'a messages array').map(mapSendingMessage)
 
     return {
       success: true,

apps/sim/tools/mailtrap/mailtrap.test.ts

@@ -5,6 +5,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { extractErrorMessage } from '@/tools/error-extractors'
 import { mailtrapCreateContactTool } from '@/tools/mailtrap/create_contact'
 import { mailtrapDeleteContactTool } from '@/tools/mailtrap/delete_contact'
+import { mailtrapGetContactTool } from '@/tools/mailtrap/get_contact'
+import { mailtrapGetContactListTool } from '@/tools/mailtrap/get_contact_list'
 import { mailtrapGetEmailLogTool } from '@/tools/mailtrap/get_email_log'
 import { mailtrapListContactListsTool } from '@/tools/mailtrap/list_contact_lists'
 import { mailtrapListEmailLogsTool } from '@/tools/mailtrap/list_email_logs'
@@ -58,6 +60,15 @@ describe('mailtrap utils', () => {
     )
   })
 
+  it('rejects an unbalanced quote or angle bracket instead of absorbing recipients', () => {
+    expect(() => parseAddressList('Bad <bad@example.com, good@example.com')).toThrow(
+      /unbalanced quote or angle bracket/
+    )
+    expect(() => parseAddressList('"still open, a@example.com')).toThrow(
+      /unbalanced quote or angle bracket/
+    )
+  })
+
   it('keeps commas that sit inside a quoted display name', () => {
     expect(
       parseAddressList(
@@ -274,6 +285,27 @@ describe('mailtrap contact tools', () => {
     })
   })
 
+  it('fails a well-formed body that is missing the contact payload', async () => {
+    await expect(
+      mailtrapGetContactTool.transformResponse?.(new Response('{}'), {
+        apiToken: 't',
+        contactIdentifier: 'c@example.com',
+      })
+    ).rejects.toThrow(/did not include the contact payload/)
+  })
+
+  it('fails a contact list response with no numeric id', async () => {
+    await expect(
+      mailtrapGetContactListTool.transformResponse?.(
+        new Response(JSON.stringify({ name: 'News' })),
+        {
+          apiToken: 't',
+          listId: '1',
+        }
+      )
+    ).rejects.toThrow(/did not include a contact list id/)
+  })
+
   it('sends include/exclude list ids and the unsubscribe flag on update', () => {
     const body = buildBody(mailtrapUpdateContactTool, {
       apiToken: 't',
@@ -529,6 +561,24 @@ describe('mailtrap email logs tools', () => {
       'https://mailtrap.io/api/email_logs/a%20b%2Fc'
     )
   })
+
+  it('fails when the list response has no messages array', async () => {
+    await expect(
+      mailtrapListEmailLogsTool.transformResponse?.(
+        new Response(JSON.stringify({ messages: 'bad', total_count: 0 })),
+        { apiToken: 't' }
+      )
+    ).rejects.toThrow(/did not include a messages array/)
+  })
+
+  it('fails a single message response with no message id', async () => {
+    await expect(
+      mailtrapGetEmailLogTool.transformResponse?.(
+        new Response(JSON.stringify({ status: 'delivered' })),
+        { apiToken: 't', messageId: 'm-9' }
+      )
+    ).rejects.toThrow(/did not include a message id/)
+  })
 })
 
 describe('mailtrap transformResponse invariants', () => {

apps/sim/tools/mailtrap/update_contact.ts

@@ -5,6 +5,7 @@ import {
   type MailtrapUpdateContactResult,
 } from '@/tools/mailtrap/types'
 import {
+  expectRecord,
   mapContact,
   parseIdList,
   parseJsonRecord,
@@ -102,7 +103,7 @@ export const mailtrapUpdateContactTool: ToolConfig<
       success: true,
       output: {
         action: typeof data.action === 'string' ? data.action : '',
-        contact: mapContact(data.data),
+        contact: mapContact(expectRecord(data.data, 'the contact payload')),
       },
     }
   },

apps/sim/tools/mailtrap/update_contact_list.ts

@@ -4,7 +4,7 @@ import {
   type MailtrapContactListResult,
   type MailtrapUpdateContactListParams,
 } from '@/tools/mailtrap/types'
-import { mapContactList, readJsonBody } from '@/tools/mailtrap/utils'
+import { expectContactList, readJsonBody } from '@/tools/mailtrap/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const mailtrapUpdateContactListTool: ToolConfig<
@@ -53,7 +53,7 @@ export const mailtrapUpdateContactListTool: ToolConfig<
     const data = await readJsonBody(response)
     return {
       success: true,
-      output: { list: mapContactList(data) },
+      output: { list: expectContactList(data) },
     }
   },
 

apps/sim/tools/mailtrap/utils.ts

@@ -19,8 +19,12 @@ export function parseAddress(value: string | undefined): MailtrapAddress | undef
   return parseAddressList(value)[0]
 }
 
+/** A bare address: one `@`, no whitespace or list/quote/bracket delimiters on either side. */
+const BARE_EMAIL = /^[^\s"<>,@]+@[^\s"<>,@]+$/
+
 /**
- * Splits a recipient string on top-level commas only.
+ * Splits a recipient string on top-level commas only. Throws when a quote or angle
+ * bracket is left open.
  */
 function splitAddressEntries(value: string): string[] {
   const entries: string[] = []
@@ -54,6 +58,10 @@ function splitAddressEntries(value: string): string[] {
   }
   entries.push(current)
 
+  if (inQuotes || inAngle) {
+    throw new Error('Recipient list has an unbalanced quote or angle bracket')
+  }
+
   return entries
 }
 
@@ -72,7 +80,7 @@ export function parseAddressList(value: string | undefined): MailtrapAddress[] {
 
     const named = entry.match(/^\s*(.*?)\s*<\s*([^<>]+?)\s*>\s*$/)
     const email = (named ? named[2] : entry).trim()
-    if (!email.includes('@')) {
+    if (!BARE_EMAIL.test(email)) {
       throw new Error(`"${entry}" is not a valid email address`)
     }
 
@@ -210,8 +218,9 @@ function parseJsonResponse(text: string): unknown {
 /**
  * Reads a Mailtrap 2xx JSON object body. Every endpoint that calls this returns
  * a JSON object on success, so an empty, unparseable, or wrongly-shaped body
- * means the payload did not come from Mailtrap and is surfaced as a failure instead of being mapped to an empty
- * record. Delete endpoints return `204` and never call this.
+ * means the payload did not come from Mailtrap and is surfaced as a failure
+ * rather than mapped into a fabricated empty record. Delete endpoints return
+ * `204` and never call this.
  */
 export async function readJsonBody(response: Response): Promise<Record<string, unknown>> {
   const parsed = parseJsonResponse(await response.text())
@@ -233,3 +242,46 @@ export async function readJsonArray(response: Response): Promise<unknown[]> {
   }
   return parsed
 }
+
+/**
+ * Asserts that a nested payload the caller depends on is present and is a plain
+ * object. A well-formed JSON body that is missing its defining slice fails here instead of
+ * being mapped into a fabricated empty record.
+ */
+export function expectRecord(value: unknown, description: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Mailtrap response did not include ${description}`)
+  }
+  return value as Record<string, unknown>
+}
+
+/** Asserts that a nested payload the caller iterates over is present and is an array. */
+export function expectArray(value: unknown, description: string): unknown[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`Mailtrap response did not include ${description}`)
+  }
+  return value
+}
+
+/**
+ * Validates a Contacts Lists API payload (`{ id, name }`) and normalizes it.
+ * The single-list endpoints require a numeric `id`; the list endpoint keeps the
+ * lenient {@link mapContactList} for individual rows.
+ */
+export function expectContactList(data: Record<string, unknown>): MailtrapContactList {
+  if (typeof data.id !== 'number') {
+    throw new Error('Mailtrap response did not include a contact list id')
+  }
+  return mapContactList(data)
+}
+
+/**
+ * Validates an Email Logs message payload and normalizes it. Requires a
+ * `message_id` so an empty object is not mapped into a blank message.
+ */
+export function expectSendingMessage(data: Record<string, unknown>): MailtrapSendingMessage {
+  if (typeof data.message_id !== 'string' || data.message_id.length === 0) {
+    throw new Error('Mailtrap response did not include a message id')
+  }
+  return mapSendingMessage(data)
+}