Skip to content

📧✨ Beautiful email. For everyone.

19.2 KB
Raw Blame
import { describe, it, expect, vi } from 'vitest'
import { readFileSync } from 'node:fs'
import { JmapProvider, jmapFilter, jmapPatch, parseUnsubscribe } from '../packages/jmap/src'
import { ipcSchemas } from '../packages/core/src'
const core = 'urn:ietf:params:jmap:core',
  mail = 'urn:ietf:params:jmap:mail',
  submission = 'urn:ietf:params:jmap:submission'
const session = {
  apiUrl: 'https://mail.example/jmap',
  uploadUrl: 'https://mail.example/upload/{accountId}',
  downloadUrl: 'https://mail.example/download/{accountId}/{blobId}/{name}?type={type}',
  username: '[email protected]',
  accounts: { a: { name: 'Personal', accountCapabilities: { [mail]: {}, [submission]: {} } } },
  capabilities: {
    [core]: { maxObjectsInGet: 100, maxObjectsInSet: 100 },
    [mail]: {},
    [submission]: {},
  },
  primaryAccounts: { [mail]: 'a' },
  state: '1',
}
const raw = (id: string) => ({
  id,
  threadId: 'thread-' + id,
  receivedAt: '2026-09-23T10:00:00Z',
  subject: 'Sample',
  from: [{ email: '[email protected]', name: 'Sender' }],
  mailboxIds: { inbox: true },
  keywords: { $seen: true },
})
function fixture(overrides: Record<string, (args: any) => any> = {}, downloadBody?: string) {
  const calls: { name: string; args: any }[] = []
  const fetch = vi.fn(async (_url: any, init?: RequestInit) => {
    if (String(_url).includes('/download/') && downloadBody !== undefined)
      return new Response(downloadBody)
    if (!init?.body) return Response.json(session)
    const request = JSON.parse(String(init.body))
    return Response.json({
      methodResponses: request.methodCalls.map(([name, args, tag]: any) => {
        calls.push({ name, args })
        // RFC 8621 §4.1.2.2 forbids Text form for RFC 2369 list headers.
        // Stalwart validates this even when the message has no such header.
        if (name === 'Email/get' && args.properties?.includes('header:List-Unsubscribe:asText'))
          return ['error', { type: 'invalidArguments' }, tag]
        const response =
          overrides[name]?.(args) ??
          (
            {
              'Mailbox/get': {
                list: [
                  {
                    id: 'inbox',
                    name: 'Inbox',
                    role: 'inbox',
                    myRights: { mayReadItems: true },
                    totalEmails: 50_000,
                    unreadEmails: 1,
                  },
                ],
              },
              'Email/query': {
                ids: Array.from({ length: args.limit || 0 }, (_, i) =>
                  String((args.position || 0) + i),
                ),
                total: 50_000,
              },
              'Email/get': { list: (args.ids || []).map(raw) },
              'Thread/get': {
                list: (args.ids || []).map((id: string) => ({
                  id,
                  emailIds: [id.replace('thread-', '')],
                })),
              },
              'Email/set': { updated: {}, notUpdated: { bad: { type: 'forbidden' } } },
            } as any
          )[name]
        return [name, response, tag]
      }),
    })
  }) as unknown as typeof globalThis.fetch
  const provider = new JmapProvider({
    serverUrl: 'https://mail.example',
    connectionId: 'test',
    name: 'Test',
    authorization: 'Basic disposable',
    fetch,
  })
  return { provider, fetch, calls }
}
describe('JMAP provider', () => {
  it('loads only one conversation page from a 50k inbox and no bodies', async () => {
    const { provider, calls } = fixture()
    const [account] = await provider.connect()
    const page = await provider.query(account, { view: 'inbox' })
    expect(page.items).toHaveLength(50)
    expect(page.total).toBe(50_000)
    expect(page.next).toBe(50)
    const emailGets = calls.filter((c) => c.name === 'Email/get')
    expect(emailGets.flatMap((c) => c.args.ids)).toHaveLength(50)
    expect(emailGets.every((c) => !c.args.fetchAllBodyValues)).toBe(true)
    expect(calls.find((c) => c.name === 'Email/query')?.args.collapseThreads).toBe(true)
  })
  it('normalizes addresses without display names', async () => {
    const { provider } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('unnamed'),
            from: [{ email: '[email protected]', name: null }],
            to: [{ email: '[email protected]', name: null }],
            cc: [{ email: '[email protected]' }],
            bcc: [{ email: '[email protected]', name: null }],
            replyTo: [{ email: '[email protected]', name: null }],
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    const [message] = await provider.messages(account, ['unnamed'])
    expect(message.from).toEqual([{ email: '[email protected]', name: '' }])
    expect(message.to).toEqual([{ email: '[email protected]', name: '' }])
    expect(message.cc).toEqual([{ email: '[email protected]', name: '' }])
    expect(message.bcc).toEqual([{ email: '[email protected]', name: '' }])
    expect(message.replyTo).toEqual([{ email: '[email protected]', name: '' }])
  })
  it('omits null optional attachment fields before forwarding through IPC', async () => {
    const { provider } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('forward'),
            bodyStructure: {
              type: 'multipart/mixed',
              subParts: [
                {
                  blobId: 'attachment-blob',
                  name: 'report.pdf',
                  type: 'application/pdf',
                  size: 42,
                  cid: null,
                  disposition: 'attachment',
                },
                {
                  blobId: 'inline-blob',
                  name: null,
                  type: 'image/png',
                  size: 12,
                  cid: '[email protected]',
                  disposition: null,
                },
              ],
            },
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    const [message] = await provider.messages(account, ['forward'], true)
    expect(message.attachments).toEqual([
      {
        blobId: 'attachment-blob',
        name: 'report.pdf',
        type: 'application/pdf',
        size: 42,
        disposition: 'attachment',
      },
      {
        blobId: 'inline-blob',
        name: 'attachment',
        type: 'image/png',
        size: 12,
        cid: '[email protected]',
      },
    ])
    expect(
      ipcSchemas.stageRemoteAttachments.safeParse([account.id, message.attachments]).success,
    ).toBe(true)
  })
  it('sends with the name chosen in the app, falling back to the server identity name', async () => {
    const { provider } = fixture({
      'Identity/get': () => ({
        list: [{ id: 'i1', name: 'Server Name', email: '[email protected]' }],
      }),
    })
    const [account] = await provider.connect()
    expect((await provider.identities(account))[0].name).toBe('Server Name')
    const [identity] = await provider.identities({ ...account, senderName: 'Jane Doe' })
    expect(identity).toMatchObject({ name: 'Jane Doe', email: '[email protected]' })
  })
  it('passes full-history filters and page offsets to the server', async () => {
    const { provider, calls } = fixture()
    const [account] = await provider.connect()
    await provider.query(
      account,
      { view: 'all', text: 'invoice', from: '[email protected]', hasAttachment: true },
      49_950,
    )
    const q = calls.find((c) => c.name === 'Email/query')!.args
    expect(q.position).toBe(49_950)
    expect(JSON.stringify(q.filter)).toContain('[email protected]')
    expect(JSON.stringify(q.filter)).toContain('invoice')
  })
  it('uses the JMAP mailbox exclusion filter for starred mail and search', async () => {
    const mailboxes = [
      { id: 'spam-id', role: 'junk' },
      { id: 'trash-id', role: 'trash' },
    ] as Parameters<typeof jmapFilter>[1]
    expect(jmapFilter({ view: 'starred' }, mailboxes)).toEqual({
      operator: 'AND',
      conditions: [{ inMailboxOtherThan: ['spam-id', 'trash-id'] }, { hasKeyword: '$flagged' }],
    })
    expect(jmapFilter({ view: 'all', text: 'invoice' }, mailboxes)).toEqual({
      operator: 'AND',
      conditions: [{ inMailboxOtherThan: ['spam-id', 'trash-id'] }, { text: 'invoice' }],
    })
    expect(jmapFilter({ view: 'all' }, [])).toEqual({})
  })
  it('recovers an HTML body from nested MIME parts when htmlBody is empty', async () => {
    const { provider } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('nested'),
            htmlBody: [{ type: 'text/html', partId: 'empty-part' }],
            bodyStructure: {
              type: 'multipart/alternative',
              subParts: [{ type: 'text/html', partId: 'html-part' }],
            },
            bodyValues: {
              'empty-part': { value: '   ' },
              'html-part': { value: '<p>Visible body</p>' },
            },
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    expect((await provider.messages(account, ['nested'], true))[0].html).toBe('<p>Visible body</p>')
  })
  it('preserves plain-text formatting when JMAP lists the part in both body preferences', async () => {
    const text = readFileSync(new URL('./fixtures/plain-email.txt', import.meta.url), 'utf8')
    const part = { type: 'text/plain', partId: 'plain' }
    const { provider, fetch } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('plain'),
            textBody: [part],
            htmlBody: [part],
            bodyStructure: part,
            bodyValues: { plain: { value: text } },
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    const [message] = await provider.messages(account, ['plain'], true)
    expect(message.text).toBe(text)
    expect(message.html).toContain('white-space:pre-wrap')
    expect(message.html).toContain('Hi,\n\nI&#39;m Bartek')
    expect(message.html).toContain('     _,\n__( `)&lt;\n\\____)')
    expect(message.html).toContain('<a href="https://watchgoose.com/open-source/">')
    expect(fetch.mock.calls.some(([url]) => String(url).includes('/download/'))).toBe(false)
  })
  it('renders mixed plain-text and HTML parts in their display order', async () => {
    const parts = [
      { type: 'text/plain', partId: 'intro' },
      { type: 'text/html', partId: 'html' },
      { type: 'text/plain', partId: 'signature' },
    ]
    const { provider } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('mixed'),
            htmlBody: parts,
            textBody: parts,
            bodyValues: {
              intro: { value: 'Hi,\n\nAn introduction.' },
              html: { value: '<p>A <strong>formatted</strong> body.</p>' },
              signature: { value: 'Kind regards,\nSender <[email protected]>' },
            },
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    const [message] = await provider.messages(account, ['mixed'], true)
    expect(message.html).toBe(
      '<div style="white-space:pre-wrap">Hi,\n\nAn introduction.</div>\n' +
        '<p>A <strong>formatted</strong> body.</p>\n' +
        '<div style="white-space:pre-wrap">Kind regards,\nSender &lt;[email protected]&gt;</div>',
    )
  })
  it('keeps downloaded plain-text body parts formatted as plain text', async () => {
    const { provider, fetch } = fixture(
      {
        'Email/get': () => ({
          list: [
            {
              ...raw('plain-blob'),
              htmlBody: [{ type: 'text/plain', blobId: 'plain-blob', size: 30 }],
              bodyValues: {},
            },
          ],
        }),
      },
      'Hi,\n\nA downloaded plain body.',
    )
    const [account] = await provider.connect()
    const [message] = await provider.messages(account, ['plain-blob'], true)
    expect(message.html).toBe(
      '<div style="white-space:pre-wrap">Hi,\n\nA downloaded plain body.</div>',
    )
    expect(message.text).toBe('Hi,\n\nA downloaded plain body.')
    expect(
      fetch.mock.calls
        .filter(([url]) => String(url).includes('/download/'))
        .every(([url]) => String(url).includes('type=text%2Fplain')),
    ).toBe(true)
  })
  it('recovers a missing body value from its JMAP part blob', async () => {
    const { provider, fetch } = fixture(
      {
        'Email/get': () => ({
          list: [
            {
              ...raw('blob'),
              htmlBody: [{ type: 'text/html', blobId: 'body-blob', size: 21 }],
              bodyValues: {},
            },
          ],
        }),
      },
      '<p>Recovered body</p>',
    )
    const [account] = await provider.connect()
    expect((await provider.messages(account, ['blob'], true))[0].html).toBe('<p>Recovered body</p>')
    expect(fetch.mock.calls.some(([url]) => String(url).includes('/download/'))).toBe(true)
  })
  it('surfaces per-object mutation failures', async () => {
    const { provider } = fixture()
    const [a] = await provider.connect()
    const result = await provider.update(a, { bad: { keywords: { $seen: true } } })
    expect(result.updated).toEqual([])
    expect(result.failures).toEqual(['bad: forbidden'])
  })
  it('accepts same-origin discovery redirects and rejects cross-origin endpoints', async () => {
    const fetch = vi
      .fn()
      .mockResolvedValueOnce(new Response(null, { status: 302, headers: { location: '/session' } }))
      .mockResolvedValueOnce(Response.json(session))
    const p = new JmapProvider({
      serverUrl: 'https://mail.example',
      connectionId: 'c',
      name: '',
      authorization: 'test',
      fetch,
    })
    expect(await p.connect()).toHaveLength(1)
    expect(fetch.mock.calls[1][0]).toBe('https://mail.example/session')
    const foreign = new JmapProvider({
      serverUrl: 'https://mail.example',
      connectionId: 'c',
      name: '',
      authorization: 'test',
      fetch: vi
        .fn()
        .mockResolvedValue(Response.json({ ...session, apiUrl: 'https://elsewhere.example/api' })),
    })
    await expect(foreign.connect()).rejects.toThrow('another origin')
  })
  it('reports rate limits without automatically replaying writes', async () => {
    const fetch = vi
      .fn()
      .mockResolvedValueOnce(Response.json(session))
      .mockResolvedValueOnce(new Response(null, { status: 429, headers: { 'retry-after': '60' } }))
    const p = new JmapProvider({
      serverUrl: 'https://mail.example',
      connectionId: 'c',
      name: '',
      authorization: 'test',
      fetch,
    })
    const [a] = await p.connect()
    await expect(p.update(a, { m: { keywords: { $seen: true } } })).rejects.toMatchObject({
      code: 'rateLimit',
      retryAfter: 60,
    })
    await expect(p.update(a, { m: { keywords: { $seen: true } } })).rejects.toMatchObject({
      code: 'rateLimit',
    })
    expect(fetch).toHaveBeenCalledTimes(2)
  })
  it('uses the operation snapshot state and surfaces stale writes without retrying', async () => {
    const { provider, calls } = fixture({
      'Email/get': (args) => ({ list: args.ids.map(raw), state: 'snapshot' }),
    })
    const [account] = await provider.connect()
    await provider.messages(account, ['1'])
    const expected = provider.getStateToken(account)
    expect(expected).toBe('snapshot')
    await provider.update(account, { bad: { keywords: { $seen: true } } }, [], expected)
    expect(calls.find((c) => c.name === 'Email/set')!.args.ifInState).toBe('snapshot')
    const fetch = vi
      .fn()
      .mockResolvedValueOnce(Response.json(session))
      .mockResolvedValueOnce(
        Response.json({ methodResponses: [['error', { type: 'stateMismatch' }, 's']] }),
      )
    const stale = new JmapProvider({
      serverUrl: 'https://mail.example',
      connectionId: 'c',
      name: '',
      authorization: 'test',
      fetch,
    })
    const [a] = await stale.connect()
    await expect(
      stale.update(a, { m: { keywords: { $seen: true } } }, [], 'old'),
    ).rejects.toMatchObject({ code: 'stateMismatch' })
    expect(fetch).toHaveBeenCalledTimes(2)
  })
  it('translates typed changes into escaped JMAP patch paths', () => {
    expect(
      jmapPatch({ mailboxes: { inbox: false, 'custom/a~b': true }, keywords: { $seen: true } }),
    ).toEqual({
      'mailboxIds/inbox': null,
      'mailboxIds/custom~1a~0b': true,
      'keywords/$seen': true,
    })
  })
  it('recognizes only supported unsubscribe destinations', () => {
    expect(
      parseUnsubscribe('<https://list.example/unsubscribe>', 'List-Unsubscribe=One-Click'),
    ).toEqual({ url: 'https://list.example/unsubscribe', oneClick: true })
    expect(parseUnsubscribe('<javascript:alert(1)>')).toBeUndefined()
  })
  it.each([
    [undefined, undefined, undefined],
    [
      '<mailto:[email protected]>',
      undefined,
      { url: 'mailto:[email protected]', oneClick: false },
    ],
    [
      '<mailto:[email protected]>,\r\n <https://list.example/unsubscribe>',
      'List-Unsubscribe=One-Click',
      { url: 'https://list.example/unsubscribe', oneClick: true },
    ],
  ])('opens conversations with raw unsubscribe headers (%s)', async (value, post, expected) => {
    const { provider, calls } = fixture({
      'Email/get': (args) => ({
        list: [
          {
            ...raw('newsletter'),
            textBody: [{ partId: 'text', type: 'text/plain' }],
            bodyValues: { text: { value: 'Newsletter content' } },
            ...Object.fromEntries(
              args.properties
                .filter((property: string) => property.startsWith('header:'))
                .map((property: string) => [
                  property,
                  {
                    'header:List-Unsubscribe': value ?? null,
                    'header:List-Unsubscribe-Post': post ?? null,
                  }[property],
                ]),
            ),
          },
        ],
      }),
    })
    const [account] = await provider.connect()
    const [message] = await provider.conversation(account, 'thread-newsletter')
    expect(message.text).toBe('Newsletter content')
    expect(message.unsubscribe).toEqual(expected)
    expect(calls.find((call) => call.name === 'Email/get')?.args.properties).toEqual(
      expect.arrayContaining(['header:List-Unsubscribe', 'header:List-Unsubscribe-Post']),
    )
    provider.dispose()
  })
  it('discovers bounded Autocrypt headers without requesting bodies or message blobs', async () => {
    const { provider, calls } = fixture({
      'Email/get': () => ({
        list: [
          {
            ...raw('key'),
            'header:Autocrypt:all': [
              '[email protected]; prefer-encrypt=mutual; keydata=YWJj',
            ],
          },
          { ...raw('wrong'), from: [{ email: '[email protected]' }] },
        ],
      }),
    })
    const [account] = await provider.connect()
    const hints = await provider.encryptionHints(account, '[email protected]')
    expect(hints).toHaveLength(1)
    expect(Buffer.from(hints[0].headers).toString()).toContain('prefer-encrypt=mutual')
    const query = calls.find((call) => call.name === 'Email/query')!
    expect(query.args.limit).toBeLessThanOrEqual(40)
    const get = calls.find((call) => call.name === 'Email/get')!
    expect(get.args.properties).not.toContain('blobId')
    expect(get.args.properties).not.toContain('bodyValues')
    expect(get.args.fetchAllBodyValues).toBeUndefined()
    provider.dispose()
  })
})