@open-mercato/channel-imap 0.6.4

package/src/modules/channel_imap/lib/__tests__/convert-outbound.test.ts

@@ -0,0 +1,73 @@
+import { convertOutboundForEmail } from '../convert-outbound'
+
+describe('convertOutboundForEmail', () => {
+  it('produces text + html from html input', async () => {
+    const native = await convertOutboundForEmail({
+      body: '<p>Hello <strong>world</strong></p>',
+      bodyFormat: 'html',
+      channelMetadata: {
+        subject: 'Hi',
+        to: ['bob@example.com'],
+      },
+    })
+    expect(native.content.html).toContain('<strong>world</strong>')
+    expect(native.content.text).toContain('Hello world')
+    expect(native.metadata).toMatchObject({ subject: 'Hi', to: ['bob@example.com'] })
+  })
+
+  it('keeps plain text untouched', async () => {
+    const native = await convertOutboundForEmail({
+      body: 'Hello\n\nworld',
+      bodyFormat: 'text',
+      channelMetadata: { to: 'bob@example.com', subject: 'Re: hi' },
+    })
+    expect(native.content.text).toBe('Hello\n\nworld')
+    expect(native.content.html).toBeUndefined()
+    expect(native.metadata?.to).toEqual(['bob@example.com'])
+  })
+
+  it('splits comma-separated address strings into arrays', async () => {
+    const native = await convertOutboundForEmail({
+      body: 'hi',
+      bodyFormat: 'text',
+      channelMetadata: { to: 'a@x.com, b@y.com', cc: 'c@z.com;d@z.com' },
+    })
+    expect(native.metadata?.to).toEqual(['a@x.com', 'b@y.com'])
+    expect(native.metadata?.cc).toEqual(['c@z.com', 'd@z.com'])
+  })
+
+  it('preserves threading headers from channelMetadata', async () => {
+    const native = await convertOutboundForEmail({
+      body: 'reply',
+      bodyFormat: 'text',
+      channelMetadata: {
+        to: ['root@example.com'],
+        inReplyTo: '<root@example.com>',
+        references: ['<root@example.com>', '<parent@example.com>'],
+      },
+    })
+    expect(native.metadata?.inReplyTo).toBe('<root@example.com>')
+    expect(native.metadata?.references).toEqual(['<root@example.com>', '<parent@example.com>'])
+  })
+
+  it('rejects payloads without recipients', async () => {
+    await expect(
+      convertOutboundForEmail({ body: 'hi', bodyFormat: 'text', channelMetadata: {} }),
+    ).rejects.toThrow(/at least one recipient/i)
+  })
+
+  it('strips CRLF from header-shaped fields (defense-in-depth)', async () => {
+    const native = await convertOutboundForEmail({
+      body: 'hi',
+      bodyFormat: 'text',
+      channelMetadata: {
+        subject: 'Hello\r\nBcc: attacker@evil.com',
+        to: ['bob@example.com'],
+        inReplyTo: '<root@example.com>\r\nX-Injected: 1',
+      },
+    })
+    expect(native.metadata?.subject).toBe('Hello Bcc: attacker@evil.com')
+    expect(native.metadata?.subject).not.toMatch(/[\r\n]/)
+    expect(native.metadata?.inReplyTo).not.toMatch(/[\r\n]/)
+  })
+})

package/src/modules/channel_imap/lib/__tests__/credentials.test.ts

@@ -0,0 +1,154 @@
+import { imapCredentialsSchema, imapChannelStateSchema, isInternalHost } from '../credentials'
+
+describe('imapCredentialsSchema', () => {
+  const valid = {
+    imapHost: 'imap.example.com',
+    imapPort: 993,
+    imapTls: 'tls' as const,
+    imapUser: 'alice@example.com',
+    imapPassword: 'secret',
+    smtpHost: 'smtp.example.com',
+    smtpPort: 465,
+    smtpTls: 'tls' as const,
+    smtpUser: 'alice@example.com',
+    smtpPassword: 'secret',
+    fromAddress: 'alice@example.com',
+  }
+
+  it('accepts a fully populated payload', () => {
+    expect(imapCredentialsSchema.parse(valid)).toMatchObject(valid)
+  })
+
+  it('coerces string ports into numbers', () => {
+    const parsed = imapCredentialsSchema.parse({
+      ...valid,
+      imapPort: '993' as unknown as number,
+      smtpPort: '587' as unknown as number,
+      smtpTls: 'starttls' as const,
+    })
+    expect(parsed.imapPort).toBe(993)
+    expect(parsed.smtpPort).toBe(587)
+  })
+
+  it('rejects out-of-range ports', () => {
+    expect(() => imapCredentialsSchema.parse({ ...valid, imapPort: 0 })).toThrow(/IMAP port/i)
+    expect(() => imapCredentialsSchema.parse({ ...valid, smtpPort: 70_000 })).toThrow(/SMTP port/i)
+  })
+
+  it('rejects missing required strings', () => {
+    expect(() => imapCredentialsSchema.parse({ ...valid, imapHost: '' })).toThrow(/IMAP host/i)
+    expect(() => imapCredentialsSchema.parse({ ...valid, imapPassword: '' })).toThrow(/IMAP password/i)
+    expect(() => imapCredentialsSchema.parse({ ...valid, smtpPassword: '' })).toThrow(/SMTP password/i)
+  })
+
+  it('rejects invalid TLS modes', () => {
+    expect(() => imapCredentialsSchema.parse({ ...valid, imapTls: 'plain' as never })).toThrow()
+    expect(() => imapCredentialsSchema.parse({ ...valid, smtpTls: 'tls/1.3' as never })).toThrow()
+  })
+
+  it('rejects non-email From address', () => {
+    expect(() => imapCredentialsSchema.parse({ ...valid, fromAddress: 'not-an-email' })).toThrow(
+      /From address must be a valid email/i,
+    )
+  })
+
+  it('rejects an internal IMAP host (SSRF guard wired into the schema)', () => {
+    expect(() => imapCredentialsSchema.parse({ ...valid, imapHost: '169.254.169.254' })).toThrow(
+      /private or loopback/i,
+    )
+    expect(() => imapCredentialsSchema.parse({ ...valid, smtpHost: 'localhost' })).toThrow(/private or loopback/i)
+  })
+
+  it('honors the OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS escape hatch', () => {
+    const previous = process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS
+    process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS = 'true'
+    try {
+      expect(() =>
+        imapCredentialsSchema.parse({ ...valid, imapHost: '127.0.0.1', smtpHost: '127.0.0.1' }),
+      ).not.toThrow()
+    } finally {
+      if (previous === undefined) delete process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS
+      else process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS = previous
+    }
+  })
+})
+
+describe('isInternalHost (SSRF guard)', () => {
+  const blocked = [
+    'localhost',
+    'LOCALHOST',
+    'foo.localhost',
+    'localhost6',
+    'ip6-localhost',
+    'metadata.google.internal',
+    '127.0.0.1',
+    '127.1',
+    '10.0.0.5',
+    '172.16.0.1',
+    '172.31.255.255',
+    '192.168.1.1',
+    '169.254.169.254',
+    '100.64.0.1',
+    '0.0.0.0',
+    '2130706433',
+    '0x7f.0.0.1',
+    '0177.0.0.1',
+    '::1',
+    '[::1]',
+    '::',
+    '[::]',
+    '0000:0000:0000:0000:0000:0000:0000:0001',
+    'fc00::1',
+    'fd12:3456::1',
+    'fe80::1',
+    '::ffff:127.0.0.1',
+    '::ffff:169.254.169.254',
+  ]
+
+  const allowed = [
+    'imap.example.com',
+    'smtp.fastmail.com',
+    'mail.proton.me',
+    '8.8.8.8',
+    '1.1.1.1',
+    '203.0.113.10',
+    '2001:4860:4860::8888',
+  ]
+
+  it.each(blocked)('blocks internal/obfuscated host %s', (host) => {
+    expect(isInternalHost(host)).toBe(true)
+  })
+
+  it.each(allowed)('allows public host %s', (host) => {
+    expect(isInternalHost(host)).toBe(false)
+  })
+
+  it('treats an empty host as not-internal (length validation handles it)', () => {
+    expect(isInternalHost('')).toBe(false)
+    expect(isInternalHost('   ')).toBe(false)
+  })
+})
+
+describe('imapChannelStateSchema', () => {
+  it('accepts numeric uidValidity and uidNext', () => {
+    expect(imapChannelStateSchema.parse({ uidValidity: 123, uidNext: 456 })).toMatchObject({
+      uidValidity: 123,
+      uidNext: 456,
+    })
+  })
+
+  it('accepts string uidValidity (some servers ship 64-bit values as strings)', () => {
+    expect(imapChannelStateSchema.parse({ uidValidity: '9007199254740993' })).toMatchObject({
+      uidValidity: '9007199254740993',
+    })
+  })
+
+  it('accepts empty state', () => {
+    expect(imapChannelStateSchema.parse({})).toEqual({})
+  })
+
+  it('passes through additional provider fields without erroring', () => {
+    const state = imapChannelStateSchema.parse({ uidValidity: 1, customMarker: 'hi' })
+    expect(state).toMatchObject({ uidValidity: 1, customMarker: 'hi' })
+  })
+})

package/src/modules/channel_imap/lib/__tests__/host-pinning.test.ts

@@ -0,0 +1,68 @@
+import { resolveSafeHostAddress, type HostLookup } from '../host-pinning'
+
+function fakeLookup(records: Array<{ address: string; family: number }>): HostLookup {
+  return jest.fn(async () => records)
+}
+
+describe('resolveSafeHostAddress — connect-time SSRF pinning', () => {
+  afterEach(() => {
+    delete process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS
+  })
+
+  it('resolves a public hostname to its IP and pins the original hostname as TLS servername', async () => {
+    const lookup = fakeLookup([{ address: '93.184.216.34', family: 4 }])
+    const result = await resolveSafeHostAddress('imap.example.com', { lookup })
+    expect(result).toEqual({ host: '93.184.216.34', servername: 'imap.example.com' })
+    expect(lookup).toHaveBeenCalledWith('imap.example.com')
+  })
+
+  it('rejects a hostname that resolves to a private address (DNS rebinding)', async () => {
+    const lookup = fakeLookup([{ address: '10.0.0.5', family: 4 }])
+    await expect(resolveSafeHostAddress('rebind.attacker.test', { lookup })).rejects.toThrow(
+      /private or loopback/i,
+    )
+  })
+
+  it('rejects when ANY resolved address is internal (cloud metadata in a mixed record set)', async () => {
+    const lookup = fakeLookup([
+      { address: '93.184.216.34', family: 4 },
+      { address: '169.254.169.254', family: 4 },
+    ])
+    await expect(resolveSafeHostAddress('mixed.attacker.test', { lookup })).rejects.toThrow(
+      /private or loopback/i,
+    )
+  })
+
+  it('rejects a hostname that resolves to IPv6 loopback', async () => {
+    const lookup = fakeLookup([{ address: '::1', family: 6 }])
+    await expect(resolveSafeHostAddress('v6.attacker.test', { lookup })).rejects.toThrow(
+      /private or loopback/i,
+    )
+  })
+
+  it('returns a literal public IP unchanged with no servername and does not resolve it', async () => {
+    const lookup = fakeLookup([{ address: '203.0.113.7', family: 4 }])
+    const result = await resolveSafeHostAddress('93.184.216.34', { lookup })
+    expect(result).toEqual({ host: '93.184.216.34' })
+    expect(lookup).not.toHaveBeenCalled()
+  })
+
+  it('rejects a literal internal IP even though the schema should have caught it (defense in depth)', async () => {
+    await expect(resolveSafeHostAddress('169.254.169.254')).rejects.toThrow(/private or loopback/i)
+  })
+
+  it('throws when the hostname does not resolve to any address', async () => {
+    const lookup = fakeLookup([])
+    await expect(resolveSafeHostAddress('nxdomain.attacker.test', { lookup })).rejects.toThrow(
+      /did not resolve/i,
+    )
+  })
+
+  it('skips resolution and returns the host verbatim when OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS=true', async () => {
+    process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS = 'true'
+    const lookup = fakeLookup([{ address: '10.0.0.5', family: 4 }])
+    const result = await resolveSafeHostAddress('mail.internal.lan', { lookup })
+    expect(result).toEqual({ host: 'mail.internal.lan' })
+    expect(lookup).not.toHaveBeenCalled()
+  })
+})

package/src/modules/channel_imap/lib/__tests__/imap-client.test.ts

@@ -0,0 +1,180 @@
+import {
+  credentialsToConnection,
+  getImapClient,
+  pickSentMailbox,
+  setImapClient,
+  type ImapConnectionOptions,
+} from '../imap-client'
+
+const mockFetch = jest.fn((_range: string, _query: unknown, _options?: unknown) =>
+  (async function* () {
+    yield {
+      uid: 150,
+      source: Buffer.from('raw mime'),
+      internalDate: new Date('2026-01-01T00:00:00Z'),
+      flags: ['\\Seen'],
+    }
+  })(),
+)
+
+let lastImapFlowOptions: Record<string, unknown> | undefined
+let fakeMailboxes: Array<{ path?: string; specialUse?: string }> = []
+const appendSpy = jest.fn(async (_mailbox: string, _message: Buffer, _flags?: string[]) => undefined)
+
+// Connect-time SSRF pinning resolves the host via node:dns. Stub it to a fixed
+// public IP so these tests stay offline and deterministic.
+jest.mock('node:dns/promises', () => ({
+  lookup: jest.fn(async (_host: string) => [{ address: '93.184.216.34', family: 4 }]),
+}))
+
+jest.mock('imapflow', () => {
+  class FakeImapFlow {
+    secureConnection = true
+    constructor(options: Record<string, unknown>) {
+      lastImapFlowOptions = options
+    }
+    on() {}
+    async connect() {}
+    async logout() {}
+    async getMailboxLock() {
+      return { release() {} }
+    }
+    fetch(range: string, query: unknown, options?: unknown) {
+      return mockFetch(range, query, options)
+    }
+    async list() {
+      return fakeMailboxes
+    }
+    async append(mailbox: string, message: Buffer, flags?: string[]) {
+      return appendSpy(mailbox, message, flags)
+    }
+  }
+  return { ImapFlow: FakeImapFlow }
+})
+
+const connection: ImapConnectionOptions = {
+  host: 'imap.example.com',
+  port: 993,
+  user: 'user@example.com',
+  pass: 'secret',
+  transport: 'tls',
+}
+
+describe('ImapflowClient.fetchUidRange — UID range mode', () => {
+  beforeEach(() => {
+    mockFetch.mockClear()
+    // Force getImapClient() to construct the real ImapflowClient over the mocked imapflow.
+    setImapClient(null)
+  })
+  afterAll(() => setImapClient(null))
+
+  it('passes { uid: true } as FetchOptions so the range is read as UIDs, not sequence numbers', async () => {
+    const client = getImapClient()
+    const result = await client.fetchUidRange(connection, '61978:*', {})
+
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    const [range, query, options] = mockFetch.mock.calls[0]
+    expect(range).toBe('61978:*')
+    expect(query).toMatchObject({ source: true })
+    // Regression guard for the silent inbound-drop bug: a sequence-number range
+    // "n:*" collapses to the single newest message, so each poll fetched only the
+    // latest mail and skipped everything else. The third arg MUST request UID-mode.
+    expect(options).toEqual({ uid: true })
+
+    expect(result).toHaveLength(1)
+    expect(result[0].uid).toBe(150)
+  })
+})
+
+describe('pickSentMailbox — server Sent-folder discovery', () => {
+  it('returns the \\Sent special-use mailbox path', () => {
+    expect(
+      pickSentMailbox([{ path: 'INBOX' }, { path: '[Gmail]/Sent Mail', specialUse: '\\Sent' }]),
+    ).toBe('[Gmail]/Sent Mail')
+  })
+
+  it('returns a localized special-use path (not the English "Sent")', () => {
+    expect(pickSentMailbox([{ path: 'Wysłane', specialUse: '\\Sent' }])).toBe('Wysłane')
+  })
+
+  it('falls back to "Sent" when no \\Sent mailbox exists', () => {
+    expect(pickSentMailbox([{ path: 'INBOX' }, { path: 'Drafts', specialUse: '\\Drafts' }])).toBe(
+      'Sent',
+    )
+  })
+
+  it('falls back to "Sent" for an empty or nullish listing', () => {
+    expect(pickSentMailbox([])).toBe('Sent')
+    expect(pickSentMailbox(null)).toBe('Sent')
+    expect(pickSentMailbox(undefined)).toBe('Sent')
+  })
+})
+
+describe('ImapflowClient.appendSent — targets the discovered Sent folder', () => {
+  beforeEach(() => {
+    setImapClient(null)
+    appendSpy.mockClear()
+  })
+  afterAll(() => setImapClient(null))
+
+  it('appends to the server-advertised \\Sent folder, not a hardcoded "Sent"', async () => {
+    fakeMailboxes = [{ path: 'INBOX' }, { path: '[Gmail]/Sent Mail', specialUse: '\\Sent' }]
+    await getImapClient().appendSent(connection, Buffer.from('raw mime'))
+    expect(appendSpy).toHaveBeenCalledWith('[Gmail]/Sent Mail', expect.any(Buffer), ['\\Seen'])
+  })
+
+  it('falls back to "Sent" when the server exposes no \\Sent special-use mailbox', async () => {
+    fakeMailboxes = [{ path: 'INBOX' }]
+    await getImapClient().appendSent(connection, Buffer.from('raw mime'))
+    expect(appendSpy).toHaveBeenCalledWith('Sent', expect.any(Buffer), ['\\Seen'])
+  })
+})
+
+describe('ImapflowClient.openConnection — SSRF host pinning', () => {
+  beforeEach(() => {
+    setImapClient(null)
+    lastImapFlowOptions = undefined
+    fakeMailboxes = []
+  })
+  afterAll(() => setImapClient(null))
+
+  it('connects to the resolved IP while keeping the hostname as the TLS servername', async () => {
+    await getImapClient().selectInbox(connection)
+    expect(lastImapFlowOptions?.host).toBe('93.184.216.34')
+    expect(lastImapFlowOptions?.tls).toMatchObject({
+      rejectUnauthorized: true,
+      servername: 'imap.example.com',
+    })
+  })
+})
+
+describe('credentialsToConnection — socket timeout override', () => {
+  const baseCredentials = {
+    imapHost: 'imap.example.com',
+    imapPort: 993,
+    imapTls: 'tls',
+    imapUser: 'alice@example.com',
+    imapPassword: 'secret',
+  } as unknown as Parameters<typeof credentialsToConnection>[0]
+
+  afterEach(() => {
+    delete process.env.OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS
+  })
+
+  it('omits timeoutMs (client falls back to its 60s default) when the env var is unset', () => {
+    delete process.env.OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS
+    expect(credentialsToConnection(baseCredentials).timeoutMs).toBeUndefined()
+  })
+
+  it('reads a positive OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS override', () => {
+    process.env.OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS = '90000'
+    expect(credentialsToConnection(baseCredentials).timeoutMs).toBe(90000)
+  })
+
+  it('ignores a non-numeric or non-positive override', () => {
+    process.env.OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS = 'abc'
+    expect(credentialsToConnection(baseCredentials).timeoutMs).toBeUndefined()
+    process.env.OM_CHANNEL_IMAP_SOCKET_TIMEOUT_MS = '0'
+    expect(credentialsToConnection(baseCredentials).timeoutMs).toBeUndefined()
+  })
+})

package/src/modules/channel_imap/lib/__tests__/normalize-inbound.test.ts

@@ -0,0 +1,126 @@
+import { normalizeInboundImapMessage } from '../normalize-inbound'
+
+function buildMimeMessage(parts: {
+  messageId?: string
+  inReplyTo?: string
+  references?: string
+  subject?: string
+  from?: string
+  to?: string
+  date?: string
+  text?: string
+  html?: string
+}): Buffer {
+  const headers: string[] = []
+  if (parts.messageId) headers.push(`Message-ID: ${parts.messageId}`)
+  if (parts.inReplyTo) headers.push(`In-Reply-To: ${parts.inReplyTo}`)
+  if (parts.references) headers.push(`References: ${parts.references}`)
+  if (parts.subject) headers.push(`Subject: ${parts.subject}`)
+  if (parts.from) headers.push(`From: ${parts.from}`)
+  if (parts.to) headers.push(`To: ${parts.to}`)
+  if (parts.date) headers.push(`Date: ${parts.date}`)
+  headers.push('MIME-Version: 1.0')
+  if (parts.html && parts.text) {
+    headers.push('Content-Type: multipart/alternative; boundary="alt-boundary"')
+    const body = [
+      '',
+      '--alt-boundary',
+      'Content-Type: text/plain; charset=utf-8',
+      '',
+      parts.text,
+      '--alt-boundary',
+      'Content-Type: text/html; charset=utf-8',
+      '',
+      parts.html,
+      '--alt-boundary--',
+      '',
+    ].join('\r\n')
+    return Buffer.from(headers.join('\r\n') + body, 'utf-8')
+  }
+  if (parts.html) {
+    headers.push('Content-Type: text/html; charset=utf-8')
+    return Buffer.from(headers.join('\r\n') + '\r\n\r\n' + parts.html, 'utf-8')
+  }
+  headers.push('Content-Type: text/plain; charset=utf-8')
+  return Buffer.from(headers.join('\r\n') + '\r\n\r\n' + (parts.text ?? ''), 'utf-8')
+}
+
+describe('normalizeInboundImapMessage', () => {
+  it('uses the Message-ID header as externalMessageId', async () => {
+    const result = await normalizeInboundImapMessage({
+      rawMessage: buildMimeMessage({
+        messageId: '<root@example.com>',
+        from: '"Alice" <alice@example.com>',
+        to: 'bob@example.com',
+        subject: 'Greetings',
+        text: 'Hello world',
+        date: 'Wed, 21 May 2026 10:00:00 +0000',
+      }),
+      uid: 42,
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.externalMessageId).toBe('root@example.com')
+    expect(result.externalConversationId).toBe('root@example.com')
+    expect(result.senderIdentifier).toBe('alice@example.com')
+    expect(result.senderDisplayName).toBe('Alice')
+    expect(result.subject).toBe('Greetings')
+    expect(result.body).toContain('Hello world')
+    expect(result.bodyFormat).toBe('text')
+    expect(result.channelContentType).toBe('email/mime')
+  })
+
+  it('synthesises a deterministic fallback message id when missing', async () => {
+    const result = await normalizeInboundImapMessage({
+      rawMessage: buildMimeMessage({
+        from: 'eve@example.com',
+        to: 'bob@example.com',
+        subject: 'no id',
+        text: 'hi',
+      }),
+      uid: 7,
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.externalMessageId).toBe('imap:7@bob@example.com')
+    expect(result.externalConversationId).toBe('imap:7@bob@example.com')
+  })
+
+  it('threads replies via In-Reply-To and root References', async () => {
+    const result = await normalizeInboundImapMessage({
+      rawMessage: buildMimeMessage({
+        messageId: '<reply@example.com>',
+        inReplyTo: '<parent@example.com>',
+        references: '<root@example.com> <parent@example.com>',
+        from: 'alice@example.com',
+        to: 'bob@example.com',
+        subject: 'Re: original',
+        text: 'replying',
+      }),
+      uid: 100,
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.externalMessageId).toBe('reply@example.com')
+    expect(result.replyToExternalId).toBe('parent@example.com')
+    expect(result.externalConversationId).toBe('root@example.com')
+    expect((result.channelMetadata as { references: string[] }).references).toEqual([
+      'root@example.com',
+      'parent@example.com',
+    ])
+  })
+
+  it('prefers html body when both html and text are present', async () => {
+    const result = await normalizeInboundImapMessage({
+      rawMessage: buildMimeMessage({
+        messageId: '<html@example.com>',
+        from: 'alice@example.com',
+        to: 'bob@example.com',
+        subject: 'rich',
+        text: 'plain',
+        html: '<p><b>rich</b></p>',
+      }),
+      uid: 1,
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.bodyFormat).toBe('html')
+    expect(result.body).toContain('<b>rich</b>')
+  })
+})

package/src/modules/channel_imap/lib/__tests__/transport.test.ts

@@ -0,0 +1,68 @@
+import type { ImapCredentials } from '../credentials'
+import { credentialsToConnection } from '../imap-client'
+import { credentialsToSmtpConnection } from '../smtp-client'
+import { assertTransportAllowed } from '../transport'
+
+const baseCredentials: ImapCredentials = {
+  imapHost: 'imap.example.com',
+  imapPort: 993,
+  imapTls: 'tls',
+  imapUser: 'alice@example.com',
+  imapPassword: 'secret',
+  smtpHost: 'smtp.example.com',
+  smtpPort: 465,
+  smtpTls: 'tls',
+  smtpUser: 'alice@example.com',
+  smtpPassword: 'secret',
+  fromAddress: 'alice@example.com',
+}
+
+afterEach(() => {
+  delete process.env.OM_CHANNEL_IMAP_ALLOW_INSECURE_TRANSPORT
+})
+
+describe('assertTransportAllowed', () => {
+  it('throws an [internal]-prefixed error when imapTls is none and the flag is unset', () => {
+    expect(() => assertTransportAllowed({ ...baseCredentials, imapTls: 'none' })).toThrow(/^\[internal\]/)
+    expect(() => assertTransportAllowed({ ...baseCredentials, imapTls: 'none' })).toThrow(/cleartext/i)
+  })
+
+  it('throws when smtpTls is none and the flag is unset', () => {
+    expect(() => assertTransportAllowed({ ...baseCredentials, smtpTls: 'none' })).toThrow(/cleartext/i)
+  })
+
+  it('allows none transport when OM_CHANNEL_IMAP_ALLOW_INSECURE_TRANSPORT is truthy', () => {
+    process.env.OM_CHANNEL_IMAP_ALLOW_INSECURE_TRANSPORT = 'true'
+    expect(() => assertTransportAllowed({ ...baseCredentials, imapTls: 'none', smtpTls: 'none' })).not.toThrow()
+  })
+
+  it('always allows tls and starttls', () => {
+    expect(() => assertTransportAllowed({ ...baseCredentials, imapTls: 'tls', smtpTls: 'starttls' })).not.toThrow()
+  })
+})
+
+describe('credentialsToConnection (poll/send IMAP build) enforces transport', () => {
+  it('throws when imapTls is none and the flag is unset', () => {
+    expect(() => credentialsToConnection({ ...baseCredentials, imapTls: 'none' })).toThrow(/cleartext/i)
+  })
+
+  it('builds the connection when the flag is set', () => {
+    process.env.OM_CHANNEL_IMAP_ALLOW_INSECURE_TRANSPORT = 'true'
+    const connection = credentialsToConnection({ ...baseCredentials, imapTls: 'none' })
+    expect(connection.transport).toBe('none')
+    expect(connection.host).toBe('imap.example.com')
+  })
+})
+
+describe('credentialsToSmtpConnection (send SMTP build) enforces transport', () => {
+  it('throws when smtpTls is none and the flag is unset', () => {
+    expect(() => credentialsToSmtpConnection({ ...baseCredentials, smtpTls: 'none' })).toThrow(/cleartext/i)
+  })
+
+  it('builds the connection when the flag is set', () => {
+    process.env.OM_CHANNEL_IMAP_ALLOW_INSECURE_TRANSPORT = 'true'
+    const connection = credentialsToSmtpConnection({ ...baseCredentials, smtpTls: 'none' })
+    expect(connection.transport).toBe('none')
+    expect(connection.host).toBe('smtp.example.com')
+  })
+})