Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

64.0 KB
Raw Blame
import { register } from 'prom-client'

import { defaultConfig } from '~/common/config/config'
import { logger } from '~/common/utils/logger'

import { SesWebhookHandler, nonexistentRecipients, normalizeClickUrl, resolveClickDestination } from './ses'
import { EmailTrackingCodeSigner } from './tracking-code'

// Hardcoded (not imported) so a change to the header constant fails this test.
const TRACKING_CODE_HEADER = 'X-PostHog-Tracking-Code'

const signer = new EmailTrackingCodeSigner(defaultConfig.ENCRYPTION_SALT_KEYS, 'http://localhost:8010')

describe('SesWebhookHandler', () => {
    let handler: SesWebhookHandler
    beforeEach(() => {
        handler = new SesWebhookHandler(signer)
    })

    // Mirrors what the sender writes: the custom header carries the full signed code (including
    // distinct_id, the authoritative source), the SES tag carries the short unsigned code
    // (no distinct_id) as a fallback. The parser prefers the header.
    const baseInvocation = {
        functionId: 'abc123',
        id: 'inv456',
        teamId: 1,
        state: { actionId: 'act789' },
        distinctId: 'user-123',
    } as const

    const baseMail = {
        timestamp: '2025-10-03T12:00:00Z',
        source: '[email protected]',
        messageId: 'msg-123',
        destination: ['[email protected]'],
        headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(baseInvocation) }],
        tags: {
            ph_id: [signer.generateShort(baseInvocation)],
        },
    }

    it('parses a raw Open event', async () => {
        const body = [
            {
                eventType: 'Open',
                mail: baseMail,
                open: {
                    ipAddress: '1.2.3.4',
                    userAgent: 'UA',
                    timestamp: '2025-10-03T12:01:00Z',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.body).toEqual({ ok: true })
        expect(result.metrics).toEqual([
            {
                functionId: 'abc123',
                invocationId: 'inv456',
                actionId: 'act789',
                distinctId: 'user-123',
                teamId: '1',
                metricName: 'email_opened',
                properties: { $email_to: '[email protected]' },
                timestamp: '2025-10-03T12:01:00Z',
            },
        ])
    })

    it('includes $email_subject from the SES commonHeaders', async () => {
        const mailWithSubject = { ...baseMail, commonHeaders: { subject: 'Welcome aboard' } }
        const body = [
            {
                eventType: 'Open',
                mail: mailWithSubject,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].properties).toMatchObject({
            $email_to: '[email protected]',
            $email_subject: 'Welcome aboard',
        })
    })

    it.each([
        ['without linkTags', {}],
        ['with null linkTags', { linkTags: null }],
    ])('parses a raw Click event with link URL %s', async (_name, linkTags) => {
        const body = [
            {
                eventType: 'Click',
                mail: baseMail,
                click: {
                    ipAddress: '1.2.3.4',
                    link: 'https://example.com',
                    userAgent: 'UA',
                    timestamp: '2025-10-03T12:02:00Z',
                    ...linkTags,
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].metricName).toBe('email_link_clicked')
        expect(result.metrics?.[0].distinctId).toBe('user-123')
        expect(result.metrics?.[0].properties).toEqual({
            $email_to: '[email protected]',
            $link_url: 'https://example.com',
        })
        expect(result.metrics?.[0].timestamp).toBe('2025-10-03T12:02:00Z')
        expect(result.metrics?.[1].instanceIdOverride).toBe('act789||https://example.com')
    })

    it('unwraps a legacy redirect link and surfaces the SES link tag', async () => {
        const body = [
            {
                eventType: 'Click',
                mail: baseMail,
                click: {
                    link: `http://localhost:8010/public/m/redirect?ph_id=${signer.generate(
                        baseInvocation
                    )}&target=${encodeURIComponent('https://example.com/pricing?a=1')}`,
                    linkTags: { phl: ['2'] },
                    timestamp: '2025-10-03T12:02:00Z',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].properties).toEqual({
            $email_to: '[email protected]',
            $link_url: 'https://example.com/pricing?a=1',
            $link_index: '2',
        })
    })

    it('records a click from a sensitive email with only the link origin and no subject', async () => {
        const body = [
            {
                eventType: 'Click',
                mail: {
                    ...baseMail,
                    commonHeaders: { subject: 'Your login code is 482913' },
                    tags: { ...baseMail.tags, ph_sensitive: ['true'] },
                },
                click: {
                    link: 'https://app.posthog.com/reset/Xk3pR9mQ2a?token=s3cret',
                    linkTags: { phl: ['1'] },
                    timestamp: '2025-10-03T12:02:00Z',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.metrics?.[0].properties).toEqual({
            $email_to: '[email protected]',
            $link_url: 'https://app.posthog.com',
            $link_index: '1',
        })
        expect(result.metrics?.[1].instanceIdOverride).toEqual('act789|1|https://app.posthog.com')
    })

    it('emits a per-link companion metric keyed by action, link index and normalized url', async () => {
        const body = [
            {
                eventType: 'Click',
                mail: baseMail,
                click: {
                    link: 'https://example.com/pricing/?utm_content=hero&uid=abc',
                    linkTags: { phl: ['3'] },
                    timestamp: '2025-10-03T12:02:00Z',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        // The rollup keeps its own name so existing totals and trends can't double-count the
        // per-link row, and the query string is dropped so per-recipient values don't fragment it.
        expect(result.metrics?.map((m) => [m.metricName, m.instanceIdOverride])).toEqual([
            ['email_link_clicked', undefined],
            ['email_link_clicked_by_link', 'act789|3|https://example.com/pricing'],
        ])
    })

    it('skips the per-link metric when the send has no action id', async () => {
        const noActionInvocation = { functionId: 'abc123', id: 'inv456', teamId: 1 } as const
        const body = [
            {
                eventType: 'Click',
                mail: {
                    ...baseMail,
                    headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(noActionInvocation) }],
                    tags: undefined,
                },
                click: { link: 'https://example.com/a', timestamp: '2025-10-03T12:02:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        // Without an action id the key would fall back to the invocation id, producing one row per
        // send per link instead of an aggregate.
        expect(result.metrics?.map((m) => m.metricName)).toEqual(['email_link_clicked'])
    })

    describe('normalizeClickUrl', () => {
        it.each([
            ['drops the query string', 'https://example.com/a?b=1', 'https://example.com/a'],
            ['drops the fragment', 'https://example.com/a#top', 'https://example.com/a'],
            ['drops a trailing slash', 'https://example.com/a/', 'https://example.com/a'],
            ['keeps the path', 'https://example.com/a/b/c', 'https://example.com/a/b/c'],
            ['passes through a hostless scheme', 'mailto:x', 'mailto:x'],
            ['passes through an unparseable link', 'not a url', 'not a url'],
        ])('%s', (_name, link, expected) => {
            expect(normalizeClickUrl(link)).toBe(expected)
        })

        // Per-recipient tokens in the path would otherwise land in the metrics sort key, making its
        // cardinality scale with audience size and putting recipient secrets in a team-readable store.
        it.each([
            [
                'a uuid',
                'https://example.com/verify/123e4567-e89b-12d3-a456-426614174000',
                'https://example.com/verify/*',
            ],
            [
                'a long hex digest',
                'https://example.com/unsubscribe/a1b2c3d4e5f6a7b8',
                'https://example.com/unsubscribe/*',
            ],
            ['a bare numeric id', 'https://example.com/users/1234567', 'https://example.com/users/*'],
            [
                'a long opaque token',
                'https://example.com/magic/AbCdEfGhIjKlMnOpQrStUvWx',
                'https://example.com/magic/*',
            ],
            [
                'a dot-separated jwt',
                'https://example.com/reset/eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.dBjftJeZ4CV',
                'https://example.com/reset/*',
            ],
            [
                'a percent-encoded token',
                'https://example.com/verify/%31%32%33e4567-e89b-12d3-a456-426614174000',
                'https://example.com/verify/*',
            ],
            ['a mixed-case token', 'https://example.com/m/aB3xK9mZq2LpW7fT', 'https://example.com/m/*'],
            [
                'a token carrying base64url separators',
                'https://example.com/m/aB3-xK9_mZq2LpW7fT5vN8cR1jH4gY6s',
                'https://example.com/m/*',
            ],
        ])('redacts %s from the path', (_name, link, expected) => {
            expect(normalizeClickUrl(link)).toBe(expected)
        })

        // Over-redacting empties the breakdown of the very thing it exists to show, so slugs long
        // enough to resemble a token have to survive.
        it.each([
            ['a hyphenated slug', 'https://example.com/blog/how-to-set-up-feature-flags'],
            ['a title-cased slug', 'https://example.com/blog/Getting-Started-With-PostHog'],
            ['an unbroken lowercase word', 'https://example.com/docs/gettingstartedguide'],
            ['a dated filename', 'https://example.com/files/annual-report-2026.pdf'],
            ['a short path word', 'https://example.com/pricing/enterprise-plan'],
        ])('keeps %s', (_name, link) => {
            expect(normalizeClickUrl(link)).toBe(link)
        })

        it('caps the length so a long url cannot bloat the metrics sort key', () => {
            // Many short segments, because a single long segment is collapsed by the redaction above
            // and would never reach the cap.
            expect(normalizeClickUrl(`https://example.com/${'ab/'.repeat(100)}`)).toHaveLength(200)
        })
    })

    describe('resolveClickDestination', () => {
        it.each([
            ['a destination link is passed through', 'https://example.com/x?a=1', 'https://example.com/x?a=1'],
            [
                'a redirect wrapper resolves to its target',
                'https://webhooks.us.posthog.com/public/m/redirect?ph_id=abc.def&target=https%3A%2F%2Fexample.com%2Fx',
                'https://example.com/x',
            ],
            [
                'a redirect wrapper with no target falls back to the raw link',
                'https://webhooks.us.posthog.com/public/m/redirect?ph_id=abc.def',
                'https://webhooks.us.posthog.com/public/m/redirect?ph_id=abc.def',
            ],
            ['an unparseable link is passed through', 'not a url', 'not a url'],
        ])('%s', (_name, link, expected) => {
            expect(resolveClickDestination(link)).toBe(expected)
        })
    })

    it('parses tracking code from header only when SES tag is absent', async () => {
        // Simulates a future state where the EmailTag backwards-compat carrier has been removed.
        const headerOnlyMail = {
            ...baseMail,
            tags: undefined,
        }
        const body = [
            {
                eventType: 'Open',
                mail: headerOnlyMail,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].functionId).toBe('abc123')
        expect(result.metrics?.[0].invocationId).toBe('inv456')
        expect(result.metrics?.[0].distinctId).toBe('user-123')
    })

    it('falls back to SES tag when the custom header is absent (in-flight backwards compat)', async () => {
        // Simulates a webhook for a message sent before the header carrier was rolled out,
        // or arriving from an environment where IncludeOriginalHeaders is not yet enabled
        // on the SES configuration set. The tag still carries the (pre-distinct_id) shape.
        const tagOnlyMail = {
            ...baseMail,
            headers: undefined,
        }
        const body = [
            {
                eventType: 'Open',
                mail: tagOnlyMail,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].functionId).toBe('abc123')
        expect(result.metrics?.[0].invocationId).toBe('inv456')
        // distinct_id is omitted because the short tag carrier doesn't include it.
        expect(result.metrics?.[0].distinctId).toBeUndefined()
    })

    it('prefers the custom header over the SES tag when both are present', async () => {
        // Header carries the canonical (full) code; tag carries the short code as a fallback.
        // The parser must read from the header so distinct_id is recovered.
        const result = await handler.handleWebhook({
            body: [
                {
                    eventType: 'Open',
                    mail: baseMail,
                    open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
                },
            ],
            headers: {},
        })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].distinctId).toBe('user-123')
    })

    it('skips Send events (email_sent is recorded synchronously, not from webhooks)', async () => {
        const body = [{ eventType: 'Send', mail: baseMail }]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics).toHaveLength(0)
    })

    it('parses the signed code from the header when the SES tag is absent', async () => {
        const headerOnlyMail = { ...baseMail, tags: undefined }
        const body = [
            {
                eventType: 'Open',
                mail: headerOnlyMail,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0]).toMatchObject({ functionId: 'abc123', invocationId: 'inv456' })
    })

    it('falls back to the SES tag when the custom header is absent (in-flight backwards compat)', async () => {
        const tagOnlyMail = { ...baseMail, headers: undefined }
        const body = [
            {
                eventType: 'Open',
                mail: tagOnlyMail,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0]).toMatchObject({ functionId: 'abc123', invocationId: 'inv456' })
    })

    // The `if (metricName && !isTest)` guard applies to every metric-emitting event type, so
    // suppression must hold for all of them — not just Delivery.
    it.each([
        ['Open', { open: { timestamp: 't' } }],
        ['Click', { click: { link: 'l', timestamp: 't' } }],
        ['Delivery', { delivery: { timestamp: 't' } }],
    ])('skips metrics for test sends on a %s event (isTest tracking code)', async (eventType, eventFields) => {
        const testMail = {
            ...baseMail,
            // isTest rides on the signed header code (preferred by the webhook); the short tag
            // code stays legacy-shaped without it.
            headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(baseInvocation, true) }],
            tags: { ph_id: [signer.generateShort(baseInvocation)] },
        }
        const body = [{ eventType, mail: testMail, ...eventFields }]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics).toEqual([])
    })

    it('does not suppress recipients on a permanent bounce for test sends', async () => {
        // Editor "Run test" traffic must not be able to suppress a production address just by
        // targeting a bad recipient — the isTest gate on suppressionAllowed blocks the write.
        const testMail = {
            ...baseMail,
            // isTest rides on the signed header code (preferred by the webhook); the short tag
            // code stays legacy-shaped without it.
            headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(baseInvocation, true) }],
            tags: { ph_id: [signer.generateShort(baseInvocation)] },
        }
        const body = [
            {
                eventType: 'Bounce',
                mail: testMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [
                        { emailAddress: '[email protected]', action: 'failed', status: '5.1.1', diagnosticCode: 'bad' },
                    ],
                    timestamp: '2025-10-03T12:04:00Z',
                    reportingMTA: 'mta',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.metrics).toEqual([])
        expect(result.logEntries).toEqual([])
        expect(result.hardBounceRecipients).toEqual([])
    })

    it.each([
        [
            'Transient bounce',
            {
                eventType: 'Bounce',
                bounce: {
                    bounceType: 'Transient',
                    bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'temp' }],
                    timestamp: '2025-10-03T12:04:00Z',
                },
            },
            'transientBounceRecipients' as const,
        ],
        [
            'Delivery',
            {
                eventType: 'Delivery',
                delivery: { timestamp: '2025-10-03T12:04:00Z', recipients: ['[email protected]'] },
            },
            'deliveredRecipients' as const,
        ],
        [
            'Complaint',
            {
                eventType: 'Complaint',
                complaint: {
                    complainedRecipients: [{ emailAddress: '[email protected]' }],
                    timestamp: '2025-10-03T12:05:00Z',
                },
            },
            'complainedRecipients' as const,
        ],
    ])('does not populate %s suppression writes for test sends', async (_label, eventFields, arrayKey) => {
        // Same guarantee as the permanent-bounce test above but for the other state-changing
        // events: a "Run test" from the editor must not push into the suppression counter
        // (transient), reset it (delivery), or suppress outright (complaint), which could
        // otherwise perturb production suppression state.
        const testMail = {
            ...baseMail,
            headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(baseInvocation, true) }],
            tags: { ph_id: [signer.generateShort(baseInvocation)] },
        }
        const result = await handler.handleWebhook({ body: [{ mail: testMail, ...eventFields }], headers: {} })
        expect(result[arrayKey]).toEqual([])
    })

    it('parses a raw Delivery event', async () => {
        const body = [
            {
                eventType: 'Delivery',
                mail: baseMail,
                delivery: { timestamp: '2025-10-03T12:03:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics).toEqual([
            {
                functionId: 'abc123',
                invocationId: 'inv456',
                actionId: 'act789',
                distinctId: 'user-123',
                teamId: '1',
                metricName: 'email_delivered',
                properties: { $email_to: '[email protected]' },
                timestamp: '2025-10-03T12:03:00Z',
            },
        ])
    })

    it('parses a raw Bounce event and surfaces permanent bounces for suppression', async () => {
        const body = [
            {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [
                        { emailAddress: '[email protected]', action: 'failed', status: '5.1.1', diagnosticCode: 'bad' },
                    ],
                    timestamp: '2025-10-03T12:04:00Z',
                    reportingMTA: 'mta',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        // Hard bounces emit both the catch-all metric and the AWS-comparable hard-only one
        expect(result.metrics?.map((m) => m.metricName)).toEqual(['email_bounced', 'email_bounced_hard'])
        expect(result.metrics?.[0].distinctId).toBe('user-123')
        // Without this the engagement event says only "bounced", and a sender cannot tell a dead
        // address from a full mailbox.
        expect(result.metrics?.[0].properties).toMatchObject({ $bounce_type: 'hard' })
        expect(result.hardBounceRecipients).toEqual([
            { teamId: '1', emailAddresses: ['[email protected]'], diagnostic: 'bad' },
        ])
        expect(result.transientBounceRecipients).toEqual([])
    })

    it('surfaces transient bounces for the soft-bounce counter, not the hard-bounce list', async () => {
        const body = [
            {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Transient',
                    bouncedRecipients: [
                        { emailAddress: '[email protected]', action: 'failed', status: '4.1.1', diagnosticCode: 'temp' },
                    ],
                    timestamp: '2025-10-03T12:04:00Z',
                    reportingMTA: 'mta',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        // Transient bounces must NOT emit email_bounced_hard — AWS's account rate excludes them
        expect(result.metrics?.map((m) => m.metricName)).toEqual(['email_bounced', 'email_bounced_transient'])
        expect(result.metrics?.[0].distinctId).toBe('user-123')
        // A transient bounce reported as hard would read as a dead address and understate recovery.
        expect(result.metrics?.[0].properties).toMatchObject({ $bounce_type: 'soft' })
        expect(result.hardBounceRecipients).toEqual([])
        expect(result.transientBounceRecipients).toEqual([
            { teamId: '1', emailAddresses: ['[email protected]'], diagnostic: 'temp' },
        ])
    })

    it('surfaces delivered recipients so the suppression counter can reset', async () => {
        const body = [
            {
                eventType: 'Delivery',
                mail: baseMail,
                delivery: {
                    timestamp: '2025-10-03T12:04:00Z',
                    recipients: ['[email protected]'],
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.deliveredRecipients).toEqual([
            { teamId: '1', emailAddresses: ['[email protected]'], timestamp: '2025-10-03T12:04:00Z' },
        ])
        expect(result.transientBounceRecipients).toEqual([])
    })

    it('rejects raw (non-SNS) deliveries when signature verification is required', async () => {
        const body = [
            {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [
                        {
                            emailAddress: '[email protected]',
                            action: 'failed',
                            status: '5.1.1',
                            diagnosticCode: 'bad',
                        },
                    ],
                    timestamp: '2025-10-03T12:04:00Z',
                    reportingMTA: 'mta',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {}, verifySignature: true })
        expect(result.status).toBe(403)
        expect(result.hardBounceRecipients).toBeUndefined()
    })

    it.each([
        // A registered spam complaint surfaces the recipient for suppression.
        {
            feedbackType: 'abuse',
            expectedRecipients: [{ teamId: '1', emailAddresses: ['[email protected]'], feedbackType: 'abuse' }],
        },
        // "not-spam" is a correction, not a complaint, so the recipient must not be suppressed. The
        // metric still counts the event.
        { feedbackType: 'not-spam', expectedRecipients: [] },
    ])(
        'parses a raw Complaint event with feedback type "$feedbackType" and surfaces the right recipients',
        async ({ feedbackType, expectedRecipients }) => {
            const body = [
                {
                    eventType: 'Complaint',
                    mail: baseMail,
                    complaint: {
                        complainedRecipients: [{ emailAddress: '[email protected]' }],
                        timestamp: '2025-10-03T12:05:00Z',
                        complaintFeedbackType: feedbackType,
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.status).toBe(200)
            expect(result.metrics?.[0].metricName).toBe('email_blocked')
            expect(result.metrics?.[0].distinctId).toBe('user-123')
            expect(result.metrics?.[0].properties).toMatchObject({ $complaint_feedback_type: feedbackType })
            expect(result.complainedRecipients).toEqual(expectedRecipients)
        }
    )

    it.each([
        [
            'Permanent bounce',
            'hardBounceRecipients' as const,
            (emailAddresses: string[]) => ({
                eventType: 'Bounce',
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: emailAddresses.map((emailAddress) => ({ emailAddress, status: '5.1.1' })),
                    timestamp: '2025-10-03T12:04:00Z',
                },
            }),
        ],
        [
            'Transient bounce',
            'transientBounceRecipients' as const,
            (emailAddresses: string[]) => ({
                eventType: 'Bounce',
                bounce: {
                    bounceType: 'Transient',
                    bouncedRecipients: emailAddresses.map((emailAddress) => ({ emailAddress, status: '4.2.2' })),
                    timestamp: '2025-10-03T12:04:00Z',
                },
            }),
        ],
        [
            'Complaint',
            'complainedRecipients' as const,
            (emailAddresses: string[]) => ({
                eventType: 'Complaint',
                complaint: {
                    complainedRecipients: emailAddresses.map((emailAddress) => ({ emailAddress })),
                    timestamp: '2025-10-03T12:05:00Z',
                },
            }),
        ],
    ])('keeps only sent-to recipients of a %s for suppression', async (_label, arrayKey, buildEvent) => {
        // The send passes a display name with the address, so the destination entry can carry it too.
        const mail = { ...baseMail, destination: ['"Recipient Name" <[email protected]>'] }
        const body = [
            { mail, ...buildEvent(['[email protected]', '[email protected]']) },
            { mail, ...buildEvent(['[email protected]']) },
        ]
        // Other tests in the process add to the counter, so read it as a delta.
        const notSentToCount = async (): Promise<number> => {
            const metric = await register.getSingleMetric('email_tracking_recipients_not_sent_to_total')!.get()
            return metric.values.find((v) => v.labels.event_type === body[0].eventType)?.value ?? 0
        }
        const countBefore = await notSentToCount()

        const result = await handler.handleWebhook({ body, headers: {} })

        expect(result[arrayKey]).toEqual([expect.objectContaining({ teamId: '1', emailAddresses: ['[email protected]'] })])
        expect((await notSentToCount()) - countBefore).toBe(2)
    })

    it('returns 200, no metrics and no logged payload if tracking code is missing from both carriers', async () => {
        const logSpies = (['info', 'warn', 'error'] as const).map((level) => jest.spyOn(logger, level))
        const body = [
            {
                eventType: 'Click',
                mail: {
                    ...baseMail,
                    commonHeaders: { subject: 'Your login code is 482913' },
                    tags: { ph_sensitive: ['true'] },
                    headers: [],
                },
                click: {
                    link: 'https://app.example.com/reset?token=s3cret',
                    timestamp: '2025-10-03T12:01:00Z',
                },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics).toEqual([])
        const logged = JSON.stringify(logSpies.flatMap((spy) => spy.mock.calls))
        expect(logged).not.toContain('s3cret')
        expect(logged).not.toContain('482913')
        logSpies.forEach((spy) => spy.mockRestore())
    })

    it('labels a dropped record "missing" when no code is present and "invalid" when it is present but unparseable', async () => {
        // Read the specific label combination as a delta, so accumulation from other tests in the
        // process cannot make this assertion flaky.
        const droppedCount = async (reason: string): Promise<number> => {
            const metric = await register.getSingleMetric('email_tracking_unattributed_total')!.get()
            return metric.values.find((v) => v.labels.event_type === 'Open' && v.labels.reason === reason)?.value ?? 0
        }
        const missingBefore = await droppedCount('missing')
        const invalidBefore = await droppedCount('invalid')

        const open = { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' }
        const body = [
            // Neither carrier holds a value: the code is missing.
            { eventType: 'Open', mail: { ...baseMail, tags: {}, headers: [] }, open },
            // A signed header is present but its signature no longer verifies (e.g. after a signing
            // key rotated out): the code is present but invalid, and this incident must not read as a
            // carrier loss.
            {
                eventType: 'Open',
                mail: {
                    ...baseMail,
                    tags: {},
                    headers: [{ name: TRACKING_CODE_HEADER, value: 'stale-payload.badsignature' }],
                },
                open,
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(await droppedCount('missing')).toBe(missingBefore + 1)
        expect(await droppedCount('invalid')).toBe(invalidBefore + 1)
    })

    // Real SNS SubscriptionConfirmation shape: SubscribeURL is a top-level envelope field and
    // Message is human-readable text, not JSON.
    const buildConfirmationEnvelope = (subscribeUrl: string): Record<string, any> => ({
        Type: 'SubscriptionConfirmation',
        MessageId: 'sns-msg-1',
        Token: 'token-123',
        TopicArn: 'arn:aws:sns:us-east-1:123456789012:ses-topic',
        Message:
            'You have chosen to subscribe to the topic arn:aws:sns:us-east-1:123456789012:ses-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.',
        SubscribeURL: subscribeUrl,
        Timestamp: '2025-10-03T12:10:00Z',
        SignatureVersion: '1',
        Signature: 'fake',
        SigningCertURL: 'https://sns.us-east-1.amazonaws.com/cert.pem',
    })

    it('confirms SubscriptionConfirmation with valid SNS SubscribeURL', async () => {
        const fetchSpy = jest.spyOn(handler as any, 'fetchText').mockResolvedValue('')
        const snsEnvelope = buildConfirmationEnvelope(
            'https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:ses-topic&Token=token-123'
        )
        const result = await handler.handleWebhook({ body: snsEnvelope, headers: {}, verifySignature: false })
        expect(result.status).toBe(200)
        expect(fetchSpy).toHaveBeenCalledWith(expect.stringContaining('https://sns.us-east-1.amazonaws.com/'))
        fetchSpy.mockRestore()
    })

    // Signs like AWS SNS SignatureVersion=1: alphabetical key/value lines of the fields each
    // envelope type signs, and serves the matching certificate.
    const SIGNED_FIELDS: Record<string, string[]> = {
        Notification: ['Message', 'MessageId', 'Timestamp', 'TopicArn', 'Type'],
        SubscriptionConfirmation: ['Message', 'MessageId', 'SubscribeURL', 'Timestamp', 'Token', 'TopicArn', 'Type'],
    }
    const signEnvelope = (envelope: Record<string, any>): jest.SpyInstance => {
        const { generateKeyPairSync, createSign } = jest.requireActual<typeof import('node:crypto')>('node:crypto')
        const { publicKey, privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 })
        const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString()
        const stringToSign = SIGNED_FIELDS[envelope.Type].map((k) => `${k}\n${envelope[k]}`).join('\n') + '\n'
        const sign = createSign('RSA-SHA1')
        sign.update(stringToSign, 'utf8')
        envelope.Signature = sign.sign(privateKey, 'base64')
        return jest
            .spyOn(handler as any, 'fetchText')
            .mockImplementation((url) => Promise.resolve((url as string).endsWith('.pem') ? publicKeyPem : ''))
    }

    it('confirms a signed SubscriptionConfirmation end to end (SubscribeURL is part of the signed string)', async () => {
        const envelope = buildConfirmationEnvelope(
            'https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:ses-topic&Token=token-123'
        )
        const fetchSpy = signEnvelope(envelope)

        const result = await handler.handleWebhook({ body: envelope, headers: {}, verifySignature: true })
        expect(result.status).toBe(200)
        expect(fetchSpy).toHaveBeenCalledWith(envelope.SubscribeURL)
        fetchSpy.mockRestore()
    })

    describe('a Notification whose Message is not JSON', () => {
        const plainText = 'Successfully validated SNS topic for Amazon SES event publishing.'
        const plainTextNotification = (message = plainText): Record<string, any> => ({
            Type: 'Notification',
            MessageId: 'sns-msg-1',
            TopicArn: 'arn:aws:sns:us-east-1:123456789012:ses-topic',
            Message: message,
            Timestamp: '2025-10-03T12:10:00Z',
            SignatureVersion: '1',
            Signature: 'forged',
            SigningCertURL: 'https://sns.us-east-1.amazonaws.com/cert.pem',
        })
        const ignoredCount = async (): Promise<number> => {
            const metric = await register.getSingleMetric('ses_webhook_ignored_notifications_total')?.get()
            return metric?.values.find((v) => v.labels.reason === 'non_json_message')?.value ?? 0
        }

        it.each([
            { label: 'plain text', message: plainText, logged: plainText },
            { label: 'control character', message: '\u001b[31mforged\nline', logged: ' (31mforged line' },
            {
                label: 'truncated SES JSON',
                message: '{"eventType":"Bounce","mail":{"destination":["[email protected]"',
                logged: undefined,
            },
        ])(
            'is acknowledged without metrics when signed, logging its $label prefix only if not JSON-shaped',
            async ({ message, logged }) => {
                const warnSpy = jest.spyOn(logger, 'warn')
                const envelope = plainTextNotification(message)
                const fetchSpy = signEnvelope(envelope)
                const before = await ignoredCount()

                const result = await handler.handleWebhook({ body: envelope, headers: {}, verifySignature: true })

                expect(result.status).toBe(200)
                expect(result.metrics).toEqual([])
                expect(await ignoredCount()).toBe(before + 1)
                expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('not JSON'), {
                    topicArn: envelope.TopicArn,
                    messageId: envelope.MessageId,
                    messageLength: message.length,
                    messagePrefix: logged,
                })
                fetchSpy.mockRestore()
                warnSpy.mockRestore()
            }
        )

        it('is rejected when its signature does not verify', async () => {
            const fetchSpy = jest.spyOn(handler as any, 'fetchText').mockResolvedValue('not a certificate')
            const before = await ignoredCount()

            const result = await handler.handleWebhook({
                body: plainTextNotification(),
                headers: {},
                verifySignature: true,
            })

            expect(result.status).toBe(403)
            expect(await ignoredCount()).toBe(before)
            fetchSpy.mockRestore()
        })
    })

    it.each([
        ['non-SNS SubscribeURL', 'https://evil.lhr.life/latest/meta-data/iam/security-credentials/role'],
        ['HTTP SubscribeURL', 'http://sns.us-east-1.amazonaws.com/subscribe'],
    ])('rejects SubscriptionConfirmation with %s', async (_label, subscribeUrl) => {
        const result = await handler.handleWebhook({
            body: buildConfirmationEnvelope(subscribeUrl),
            headers: {},
            verifySignature: false,
        })
        expect(result.status).toBe(403)
    })

    it('propagates parentRunId from the tracking code so batch runs get correct attribution', async () => {
        const batchInvocation = {
            functionId: 'workflow-id',
            id: 'child-invocation-id',
            teamId: 1,
            parentRunId: 'batch-run-id',
            state: { actionId: 'email-action' },
        }
        const mailWithParentRun = {
            ...baseMail,
            headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(batchInvocation) }],
            tags: { ph_id: [signer.generateShort(batchInvocation)] },
        }
        const body = [
            {
                eventType: 'Open',
                mail: mailWithParentRun,
                open: { ipAddress: '1.2.3.4', userAgent: 'UA', timestamp: '2025-10-03T12:01:00Z' },
            },
        ]
        const result = await handler.handleWebhook({ body, headers: {} })
        expect(result.status).toBe(200)
        expect(result.metrics).toEqual([
            {
                functionId: 'workflow-id',
                invocationId: 'child-invocation-id',
                actionId: 'email-action',
                parentRunId: 'batch-run-id',
                teamId: '1',
                metricName: 'email_opened',
                properties: { $email_to: '[email protected]' },
                timestamp: '2025-10-03T12:01:00Z',
            },
        ])
    })

    it('parses an SNS envelope Notification event', async () => {
        const snsEnvelope = {
            Type: 'Notification',
            MessageId: 'sns-msg-1',
            TopicArn: 'arn:aws:sns:us-east-1:123456789012:ses-topic',
            Message: JSON.stringify({
                eventType: 'Open',
                mail: baseMail,
                open: {
                    ipAddress: '1.2.3.4',
                    userAgent: 'UA',
                    timestamp: '2025-10-03T12:01:00Z',
                },
            }),
            Timestamp: '2025-10-03T12:10:00Z',
            SignatureVersion: '1',
            Signature: 'fake',
            SigningCertURL: 'https://sns.us-east-1.amazonaws.com/cert.pem',
        }
        const result = await handler.handleWebhook({ body: snsEnvelope, headers: {}, verifySignature: false })
        expect(result.status).toBe(200)
        expect(result.metrics?.[0].metricName).toBe('email_opened')
    })

    describe('log entries', () => {
        const logCases: { name: string; event: Record<string, any>; level: string; message: string }[] = [
            {
                name: 'Bounce permanent',
                event: {
                    eventType: 'Bounce',
                    mail: baseMail,
                    bounce: {
                        bounceType: 'Permanent',
                        bouncedRecipients: [
                            {
                                emailAddress: '[email protected]',
                                status: '5.1.1',
                                diagnosticCode: 'mailbox does not exist',
                            },
                        ],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
                level: 'error',
                message: '[Action:act789] Permanent bounce to [email protected], mailbox does not exist (5.1.1)',
            },
            {
                name: 'Bounce transient',
                event: {
                    eventType: 'Bounce',
                    mail: baseMail,
                    bounce: {
                        bounceType: 'Transient',
                        bouncedRecipients: [
                            { emailAddress: '[email protected]', status: '4.1.1', diagnosticCode: 'temp' },
                        ],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
                level: 'warn',
                message: '[Action:act789] Transient bounce to [email protected], temp (4.1.1)',
            },
            {
                name: 'Complaint',
                event: {
                    eventType: 'Complaint',
                    mail: baseMail,
                    complaint: {
                        complainedRecipients: [{ emailAddress: '[email protected]' }],
                        timestamp: '2025-10-03T12:05:00Z',
                        complaintFeedbackType: 'abuse',
                    },
                },
                level: 'warn',
                message: '[Action:act789] Complaint from [email protected], feedback type: abuse',
            },
            {
                name: 'RenderingFailure',
                event: {
                    eventType: 'RenderingFailure',
                    mail: baseMail,
                    renderingFailure: { errorMessage: 'bad template', templateName: 'welcome' },
                },
                level: 'error',
                message: '[Action:act789] Rendering failure for template welcome: bad template',
            },
            {
                name: 'Reject',
                event: { eventType: 'Reject', mail: baseMail, reject: { reason: 'spam' } },
                level: 'error',
                message: '[Action:act789] Message rejected by SES: spam',
            },
        ]

        it.each(logCases)('emits a $name log entry', async ({ event, level, message }) => {
            const result = await handler.handleWebhook({ body: [event], headers: {} })
            expect(result.logEntries).toEqual([
                expect.objectContaining({ functionId: 'abc123', invocationId: 'inv456', level, message }),
            ])
        })

        it.each([
            { name: 'Open', event: { eventType: 'Open', mail: baseMail, open: { timestamp: '2025-10-03T12:01:00Z' } } },
            {
                name: 'Delivery',
                event: { eventType: 'Delivery', mail: baseMail, delivery: { timestamp: '2025-10-03T12:03:00Z' } },
            },
            { name: 'Send', event: { eventType: 'Send', mail: baseMail } },
        ])('does not emit a log entry for the info-level $name event', async ({ event }) => {
            const result = await handler.handleWebhook({ body: [event], headers: {} })
            expect(result.logEntries).toEqual([])
        })

        it('emits one log entry per bounced recipient', async () => {
            const body = [
                {
                    eventType: 'Bounce',
                    mail: baseMail,
                    bounce: {
                        bounceType: 'Permanent',
                        bouncedRecipients: [
                            { emailAddress: '[email protected]', diagnosticCode: 'mailbox full' },
                            { emailAddress: '[email protected]', diagnosticCode: 'mailbox full' },
                        ],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.logEntries?.map((e) => e.message)).toEqual([
                '[Action:act789] Permanent bounce to [email protected], mailbox full',
                '[Action:act789] Permanent bounce to [email protected], mailbox full',
            ])
        })

        it('does not duplicate the status when SES inlines it inside diagnosticCode', async () => {
            const body = [
                {
                    eventType: 'Bounce',
                    mail: baseMail,
                    bounce: {
                        bounceType: 'Permanent',
                        bouncedRecipients: [
                            {
                                emailAddress: '[email protected]',
                                status: '5.1.1',
                                diagnosticCode: 'smtp; 550 5.1.1 user unknown <[email protected]>',
                            },
                        ],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.logEntries?.[0].message).toBe(
                '[Action:act789] Permanent bounce to [email protected], smtp; 550 5.1.1 user unknown <[email protected]>'
            )
        })

        it('drops the [Action:...] prefix when the actionId contains unsafe characters', async () => {
            // A ph_id whose actionId would close the Action token early and inject an Actor token
            // must not reach the rich-log viewer with brackets intact.
            const maliciousInvocation = {
                ...baseInvocation,
                state: { actionId: 'act] [Actor:[email protected]' },
            }
            const maliciousMail = {
                ...baseMail,
                headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(maliciousInvocation) }],
                tags: { ph_id: [signer.generateShort(maliciousInvocation)] },
            }
            const body = [
                {
                    eventType: 'Bounce',
                    mail: maliciousMail,
                    bounce: {
                        bounceType: 'Permanent',
                        bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'unknown' }],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.logEntries?.[0].message).toBe('Permanent bounce to [email protected], unknown')
        })

        it('accepts DeliveryDelay without producing a metric or log (so SNS does not retry)', async () => {
            const body = [
                {
                    eventType: 'DeliveryDelay',
                    mail: baseMail,
                    deliveryDelay: {
                        delayType: 'MailboxFull',
                        timestamp: '2025-10-03T12:06:00Z',
                        delayedRecipients: [{ emailAddress: '[email protected]' }],
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.status).toBe(200)
            expect(result.metrics).toEqual([])
            expect(result.logEntries).toEqual([])
        })
    })

    describe('email status updates', () => {
        // A transactional send carries the status tag and is addressed To one recipient; the cc copy
        // shares the message, so its feedback must not move the email's status.
        const transactionalMail = {
            ...baseMail,
            destination: ['[email protected]', '[email protected]'],
            commonHeaders: { subject: 'Reset your password', to: ['"Jane Doe" <[email protected]>'] },
            tags: { ...baseMail.tags, ph_email_status: ['true'] },
        }
        const delivery = (recipients: string[]) => ({
            eventType: 'Delivery',
            delivery: { timestamp: '2025-10-03T12:01:00Z', recipients },
        })
        const bounce = (bounceType: string, emailAddress = '[email protected]') => ({
            eventType: 'Bounce',
            bounce: { bounceType, bouncedRecipients: [{ emailAddress }], timestamp: '2025-10-03T12:02:00Z' },
        })
        const complaint = (emailAddress = '[email protected]', complaintFeedbackType?: string) => ({
            eventType: 'Complaint',
            complaint: {
                complainedRecipients: [{ emailAddress }],
                timestamp: '2025-10-03T12:03:00Z',
                ...(complaintFeedbackType ? { complaintFeedbackType } : {}),
            },
        })
        const update = (status: string, timestamp: string, reason?: string) => [
            { teamId: '1', invocationId: 'inv456', status, timestamp, ...(reason ? { reason } : {}) },
        ]

        it.each([
            [
                'a delivery to the To recipient',
                {},
                delivery(['[email protected]']),
                update('delivered', '2025-10-03T12:01:00Z'),
            ],
            ['a hard bounce', {}, bounce('Permanent'), update('bounced', '2025-10-03T12:02:00Z', 'hard')],
            ['a soft bounce', {}, bounce('Transient'), update('bounced', '2025-10-03T12:02:00Z', 'soft')],
            [
                'an undetermined bounce',
                {},
                bounce('Undetermined'),
                update('bounced', '2025-10-03T12:02:00Z', 'unknown'),
            ],
            ['a complaint', {}, complaint(), update('complained', '2025-10-03T12:03:00Z')],
            ['a not-spam correction', {}, complaint('[email protected]', 'Not-Spam'), []],
            [
                'a rejection after SES accepted the send',
                {},
                { eventType: 'Reject', reject: { reason: 'Bad content' } },
                update('failed', transactionalMail.timestamp, 'provider_rejected'),
            ],
            [
                'an open',
                {},
                { eventType: 'Open', open: { timestamp: '2025-10-03T12:04:00Z' } },
                update('opened', '2025-10-03T12:04:00Z'),
            ],
            [
                'a click',
                {},
                { eventType: 'Click', click: { link: 'https://example.com/reset', timestamp: '2025-10-03T12:05:00Z' } },
                update('clicked', '2025-10-03T12:05:00Z'),
            ],
            [
                'an open of an untagged email',
                { tags: baseMail.tags },
                { eventType: 'Open', open: { timestamp: '2025-10-03T12:04:00Z' } },
                [],
            ],
            ['a delivery of an untagged email', { tags: baseMail.tags }, delivery(['[email protected]']), []],
            ['a delivery to the cc recipient only', {}, delivery(['[email protected]']), []],
            ['a bounce of the cc recipient', {}, bounce('Permanent', '[email protected]'), []],
            ['a complaint from a bcc recipient', {}, complaint('[email protected]'), []],
            [
                'a bounce of a test send',
                { headers: [{ name: TRACKING_CODE_HEADER, value: signer.generate(baseInvocation, true) }] },
                bounce('Permanent'),
                [],
            ],
            ['a bounce with only the unsigned tag code', { headers: undefined }, bounce('Permanent'), []],
        ])('gives the status update for %s', async (_desc, mailOverrides, eventFields, expected) => {
            const body = [{ mail: { ...transactionalMail, ...mailOverrides }, ...eventFields }]

            const result = await handler.handleWebhook({ body, headers: {} })

            expect(result.emailStatusUpdates).toEqual(expected)
        })
    })

    describe('security: TopicArn allowlist + signed-code gate', () => {
        // Two-layer hardening: the TopicArn allowlist restricts which SNS topics we accept events from,
        // and state-changing writes require a signed tracking code (unsigned carriers only contribute
        // to engagement metrics/log entries).
        const buildEnvelope = (
            topicArn: string,
            innerRecord: object,
            envelopeType: 'Notification' | 'SubscriptionConfirmation' = 'Notification'
        ): Record<string, any> => ({
            Type: envelopeType,
            MessageId: 'sns-msg-1',
            TopicArn: topicArn,
            Message:
                envelopeType === 'Notification'
                    ? JSON.stringify(innerRecord)
                    : `You have chosen to subscribe to the topic ${topicArn}.`,
            ...(envelopeType === 'SubscriptionConfirmation'
                ? {
                      Token: 'token-123',
                      SubscribeURL: 'https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription',
                  }
                : {}),
            Timestamp: '2025-10-03T12:10:00Z',
            SignatureVersion: '1',
            Signature: 'stubbed',
            SigningCertURL: 'https://sns.us-east-1.amazonaws.com/cert.pem',
        })

        const globalBounce = {
            eventType: 'Bounce',
            mail: baseMail,
            bounce: {
                bounceType: 'Permanent',
                bounceSubType: 'General',
                bouncedRecipients: [
                    { emailAddress: '[email protected]', status: '5.1.1' },
                    { emailAddress: '[email protected]', status: '5.1.1' },
                ],
                timestamp: '2025-10-03T12:04:00Z',
            },
        }
        const globalDelivery = {
            eventType: 'Delivery',
            mail: baseMail,
            delivery: { timestamp: '2025-10-03T12:05:00Z', recipients: ['[email protected]'] },
        }

        it.each([
            ['an allowlisted topic', ['arn:aws:sns:us-east-1:123456789012:allowed-topic'], true, ['[email protected]']],
            ['an empty allowlist', [], true, undefined],
            ['a raw delivery', ['arn:aws:sns:us-east-1:123456789012:allowed-topic'], false, undefined],
        ] as const)(
            'writes the global hard-bounce list only for sent-to addresses from %s',
            async (_label, topics, enveloped, expected) => {
                const restricted = new SesWebhookHandler(signer, [...topics])
                const wrap = (record: object): object =>
                    enveloped ? buildEnvelope('arn:aws:sns:us-east-1:123456789012:allowed-topic', record) : [record]
                const bounce = await restricted.handleWebhook({
                    body: wrap(globalBounce),
                    headers: {},
                    verifySignature: false,
                })
                const delivery = await restricted.handleWebhook({
                    body: wrap(globalDelivery),
                    headers: {},
                    verifySignature: false,
                })
                expect(bounce.hardBounceRecipients?.[0].nonexistentAddresses).toEqual(expected)
                expect(delivery.deliveredRecipients?.[0].clearsGlobalHardBounces).toEqual(expected ? true : undefined)
            }
        )

        it('rejects a Notification whose TopicArn is not on the allowlist', async () => {
            const restricted = new SesWebhookHandler(signer, ['arn:aws:sns:us-east-1:123456789012:allowed-topic'])
            const envelope = buildEnvelope('arn:aws:sns:us-east-1:999999999999:other-topic', {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'bad' }],
                    timestamp: '2025-10-03T12:04:00Z',
                },
            })
            const result = await restricted.handleWebhook({ body: envelope, headers: {}, verifySignature: false })
            expect(result.status).toBe(403)
            expect(result.hardBounceRecipients).toBeUndefined()
        })

        it('accepts a Notification whose TopicArn matches the allowlist', async () => {
            const restricted = new SesWebhookHandler(signer, ['arn:aws:sns:us-east-1:123456789012:allowed-topic'])
            const envelope = buildEnvelope('arn:aws:sns:us-east-1:123456789012:allowed-topic', {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'bad' }],
                    timestamp: '2025-10-03T12:04:00Z',
                },
            })
            const result = await restricted.handleWebhook({ body: envelope, headers: {}, verifySignature: false })
            expect(result.status).toBe(200)
            expect(result.hardBounceRecipients).toEqual([
                { teamId: '1', emailAddresses: ['[email protected]'], diagnostic: 'bad' },
            ])
        })

        it('empty allowlist means no restriction (dev/test backward compat)', async () => {
            // The default `handler` in the outer beforeEach was constructed without an allowlist.
            const envelope = buildEnvelope('arn:aws:sns:us-east-1:999999999999:some-topic', {
                eventType: 'Bounce',
                mail: baseMail,
                bounce: {
                    bounceType: 'Permanent',
                    bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'bad' }],
                    timestamp: '2025-10-03T12:04:00Z',
                },
            })
            const result = await handler.handleWebhook({ body: envelope, headers: {}, verifySignature: false })
            expect(result.status).toBe(200)
        })

        it('rejects a SubscriptionConfirmation from a disallowed topic', async () => {
            const restricted = new SesWebhookHandler(signer, ['arn:aws:sns:us-east-1:123456789012:allowed-topic'])
            const envelope = buildEnvelope(
                'arn:aws:sns:us-east-1:999999999999:other-topic',
                {},
                'SubscriptionConfirmation'
            )
            const result = await restricted.handleWebhook({ body: envelope, headers: {}, verifySignature: false })
            expect(result.status).toBe(403)
        })

        it('does not populate suppression writes for an unsigned tracking code', async () => {
            // Only signed tracking codes drive state changes. Unsigned codes still contribute to
            // metrics/log entries (engagement signal) but not to suppression / opt-out / delivery resets.
            const unsignedMail = {
                ...baseMail,
                headers: undefined,
                tags: { ph_id: [signer.generateShort(baseInvocation)] },
            }
            const body = [
                {
                    eventType: 'Bounce',
                    mail: unsignedMail,
                    bounce: {
                        bounceType: 'Transient',
                        bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'temp' }],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
                {
                    eventType: 'Bounce',
                    mail: unsignedMail,
                    bounce: {
                        bounceType: 'Permanent',
                        bouncedRecipients: [{ emailAddress: '[email protected]', diagnosticCode: 'bad' }],
                        timestamp: '2025-10-03T12:04:00Z',
                    },
                },
                {
                    eventType: 'Delivery',
                    mail: unsignedMail,
                    delivery: { timestamp: '2025-10-03T12:05:00Z', recipients: ['[email protected]'] },
                },
                {
                    eventType: 'Complaint',
                    mail: unsignedMail,
                    complaint: {
                        complainedRecipients: [{ emailAddress: '[email protected]' }],
                        timestamp: '2025-10-03T12:06:00Z',
                    },
                },
            ]
            const result = await handler.handleWebhook({ body, headers: {} })
            expect(result.status).toBe(200)
            expect(result.transientBounceRecipients).toEqual([])
            expect(result.hardBounceRecipients).toEqual([])
            expect(result.complainedRecipients).toEqual([])
            expect(result.deliveredRecipients).toEqual([])
            // Metrics are unaffected — engagement signal is still emitted for the parsed events.
            expect(result.metrics?.length).toBeGreaterThan(0)
        })
    })
    describe('nonexistentRecipients', () => {
        // A sender-side rejection going global would let one team's broken DNS block valid addresses for all.
        it.each([
            ['Permanent', 'NoEmail', undefined, undefined, true],
            ['Permanent', 'General', '5.1.1', 'smtp; 550 5.1.1 user unknown', true],
            ['Permanent', 'General', '5.1.10', 'smtp; 556 5.1.10 null MX', true],
            ['Permanent', 'General', undefined, 'smtp; 550 5.1.1 user unknown', true],
            ['Permanent', 'General', '5.7.1', 'smtp; 550 5.7.1 rejected by DMARC policy', false],
            ['Permanent', 'General', '5.7.26', 'smtp; 550 5.7.26 rejected for 5.1.1.example.com', false],
            ['Permanent', 'General', undefined, 'smtp; 550 5.7.26 rejected for 5.1.1.example.com', false],
            ['Permanent', 'General', undefined, 'smtp; 554 sender domain blocked', false],
            ['Permanent', 'Suppressed', '5.1.1', undefined, false],
            ['Permanent', 'OnAccountSuppressionList', undefined, undefined, false],
            ['Transient', 'General', '5.1.1', 'smtp; 550 5.1.1 user unknown', false],
        ] as const)(
            '%s/%s bounce with status %s counts: %s',
            (bounceType, bounceSubType, status, diagnosticCode, expected) => {
                const recipients = nonexistentRecipients({
                    bounceType,
                    bounceSubType,
                    bouncedRecipients: [{ emailAddress: '[email protected]', status, diagnosticCode }],
                    timestamp: '2026-01-01T00:00:00.000Z',
                })
                expect(recipients).toEqual(expected ? ['[email protected]'] : [])
            }
        )
    })
})