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.

16.1 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'
import { z } from 'zod'

import { ApiClient } from '@/api/client'
import { ForwardingApiClient } from '@/lib/connection-forwarding'
import { ExecCommandError, PostHogApiError, PostHogTransportError } from '@/lib/errors'
import { StateManager } from '@/lib/StateManager'
import executeSqlTool from '@/tools/posthogAiTools/executeSql'
import { createConnectionCallTool } from '@/tools/posthogConnections/call'
import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'

const TARGET = {
    project_id: 4242,
    project_name: 'EU Team',
    organization_id: 'org-uuid',
    organization_name: 'EU Org',
    region: 'EU',
    base_url: 'https://eu.posthog.com',
}

const FORWARD_PATH = '/api/projects/7/posthog_connections/99/forward/'
const TARGET_PATH = '/api/projects/7/posthog_connections/99/target/'

/** A catalogued tool carrying `requires_ai_consent`. */
const AI_CONSENT_TOOL = 'web-analytics-path-cleaning-suggestions-generate'

/** A local client whose only job is to answer the two connection endpoints. */
function createLocalApi(request: ReturnType<typeof vi.fn>): ApiClient {
    const api = new ApiClient({ apiToken: 'local-token', baseUrl: 'https://us.posthog.com' })
    api.request = request as unknown as ApiClient['request']
    return api
}

function createContext(request: ReturnType<typeof vi.fn>): Context {
    return {
        api: createLocalApi(request),
        stateManager: { getProjectId: vi.fn().mockResolvedValue('7') } as any,
        env: {} as any,
        sessionManager: {} as any,
        cache: {} as any,
        getDistinctId: async () => 'distinct-id',
        trackEvent: async () => {},
    }
}

/** Routes every connection endpoint; `forward` echoes back what the target "returned". */
function createRequestMock(forwardResponse: { status: number; data: unknown }): ReturnType<typeof vi.fn> {
    return vi.fn(async (opts: { method: string; path: string; body?: Record<string, unknown> }) => {
        if (opts.path === TARGET_PATH) {
            return TARGET
        }
        if (opts.path === FORWARD_PATH) {
            return forwardResponse
        }
        throw new Error(`unexpected request to ${opts.path}`)
    })
}

/** Stand-in for a real registry tool: makes one API call the way generated tools do. */
function fakeTool(name: string): ToolBase<ZodObjectAny> {
    return {
        name,
        schema: z.object({ query: z.string() }),
        handler: async (context: Context, params: any) =>
            await context.api.request({
                method: 'POST',
                path: `/api/projects/${await context.stateManager.getProjectId()}/query/`,
                body: { query: params.query },
            }),
    } as ToolBase<ZodObjectAny>
}

describe('posthog connection forwarding', () => {
    afterEach(() => {
        vi.unstubAllGlobals()
        // The AI-consent cases spy on StateManager's prototype, which outlives the test without this.
        vi.restoreAllMocks()
    })

    describe('ForwardingApiClient', () => {
        it.each([200, 500])('preserves per-call private response policy for target status %s', async (status) => {
            vi.stubGlobal(
                'fetch',
                vi.fn(
                    async () =>
                        new Response(JSON.stringify({ status, data: { detail: 'Synthetic response' } }), {
                            headers: { 'X-PostHog-Suppress-Analytics': 'true' },
                        })
                )
            )
            const shared = new ForwardingApiClient(
                new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' }),
                {
                    connectionId: '99',
                    localProjectId: '7',
                    target: TARGET,
                }
            )
            const suppress = vi.fn()
            const call = shared.withAnalyticsSuppression(suppress).withIntent('Read a synthetic task')

            await call.request({ method: 'GET', path: '/api/projects/4242/tasks/example/' }).catch(() => undefined)

            expect(suppress).toHaveBeenCalledOnce()
            expect(shared.config.onPrivateResponse).toBeUndefined()
        })

        it('does not retry a forwarded read after its deadline', async () => {
            vi.useFakeTimers()
            vi.spyOn(console, 'error').mockImplementation(() => {})
            const mockFetch = vi.fn(
                (_url: string, init?: RequestInit) =>
                    new Promise<Response>((_resolve, reject) => {
                        init?.signal?.addEventListener('abort', () => reject(init.signal!.reason))
                    })
            )
            vi.stubGlobal('fetch', mockFetch)
            const forwarding = new ForwardingApiClient(
                new ApiClient({ apiToken: 'test-token', baseUrl: 'https://example.com' }),
                { connectionId: '99', localProjectId: '7', target: TARGET }
            )

            try {
                const outcome = forwarding
                    .request({ method: 'GET', path: '/api/projects/4242/insights/' })
                    .catch((error) => error)
                await vi.runAllTimersAsync()
                const error = await outcome

                expect(error).toBeInstanceOf(PostHogTransportError)
                expect(error).toMatchObject({ timedOut: true, attempts: 1 })
                expect(mockFetch).toHaveBeenCalledTimes(1)
            } finally {
                vi.useRealTimers()
            }
        })

        it('rewrites a request into the forward endpoint and unwraps the target response', async () => {
            const request = createRequestMock({ status: 200, data: { results: [[1]] } })
            const forwarding = new ForwardingApiClient(createLocalApi(request), {
                connectionId: '99',
                localProjectId: '7',
                target: TARGET,
            })

            const result = await forwarding.request({
                method: 'GET',
                path: '/api/projects/4242/insights/',
                query: { limit: 5 },
            })

            expect(request).toHaveBeenCalledWith({
                method: 'POST',
                path: FORWARD_PATH,
                body: { method: 'GET', path: 'api/projects/4242/insights/', query: { limit: '5' } },
            })
            expect(result).toEqual({ results: [[1]] })
        })

        it('sends a write body as `data`', async () => {
            const request = createRequestMock({ status: 201, data: { id: 'abc' } })
            const forwarding = new ForwardingApiClient(createLocalApi(request), {
                connectionId: '99',
                localProjectId: '7',
                target: TARGET,
            })

            await forwarding.request({ method: 'POST', path: '/api/projects/4242/query/', body: { query: 'select 1' } })

            expect(request.mock.calls[0]![0].body).toEqual({
                method: 'POST',
                path: 'api/projects/4242/query/',
                data: { query: 'select 1' },
            })
        })

        it('forwards the tool intent with a forwarded request', async () => {
            const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ status: 200, data: {} })))
            vi.stubGlobal('fetch', fetch)
            const forwarding = new ForwardingApiClient(
                new ApiClient({ apiToken: 'local-token', baseUrl: 'https://us.posthog.com' }),
                {
                    connectionId: '99',
                    localProjectId: '7',
                    target: TARGET,
                }
            )

            await forwarding.withIntent('updating the connected project').request({
                method: 'POST',
                path: '/api/projects/4242/insights/',
                body: { name: 'Updated insight' },
            })

            expect(fetch.mock.calls[0]![1].headers['x-posthog-intent']).toBe('updating the connected project')
        })

        it('surfaces a status the target returned as a thrown API error', async () => {
            // The forward endpoint answers 200 whatever the target said. Without re-raising it here,
            // a tool reads the error envelope as a successful result and reports made-up data.
            const request = createRequestMock({ status: 403, data: { detail: 'Scope missing' } })
            const forwarding = new ForwardingApiClient(createLocalApi(request), {
                connectionId: '99',
                localProjectId: '7',
                target: TARGET,
            })

            const error: any = await forwarding
                .request({ method: 'GET', path: '/api/projects/4242/insights/' })
                .catch((e) => e)

            expect(error).toBeInstanceOf(PostHogApiError)
            expect(error.status).toBe(403)
            expect(error.body).toContain('Scope missing')
        })

        it('turns a refusal from this side into the request’s own failure', async () => {
            // The gateway refusing (connection revoked, scopes too narrow) is the answer to the
            // request the tool made — it must not escape as an unrelated exception shape.
            const request = vi.fn().mockRejectedValue(
                new PostHogApiError({
                    status: 403,
                    statusText: 'Forbidden',
                    body: '{"detail":"You can only use a PostHog connection you created."}',
                    url: FORWARD_PATH,
                    method: 'POST',
                })
            )
            const forwarding = new ForwardingApiClient(createLocalApi(request), {
                connectionId: '99',
                localProjectId: '7',
                target: TARGET,
            })

            const error: any = await forwarding
                .request({ method: 'GET', path: '/api/projects/4242/insights/' })
                .catch((e) => e)

            expect(error).toBeInstanceOf(PostHogApiError)
            expect(error.status).toBe(403)
            expect(error.body).toContain('only use a PostHog connection you created')
        })
    })

    describe('posthog-connection-call', () => {
        it('runs the named tool against the connected project id, not the local one', async () => {
            // This is the promise the tool makes: the agent passes no project id and never resolves
            // one. If the forwarded context leaked the local id, every call would hit the wrong project.
            const request = createRequestMock({ status: 200, data: { results: [[1]] } })
            const tool = createConnectionCallTool((name) => (name === 'execute-sql' ? fakeTool(name) : undefined))

            const result: any = await tool.handler(createContext(request), {
                connection_id: '99',
                tool: 'execute-sql',
                arguments: { query: 'select 1 from events limit 5' },
            })

            const forwardCall = request.mock.calls.find(([opts]: any[]) => opts.path === FORWARD_PATH)
            expect(forwardCall![0].body).toEqual({
                method: 'POST',
                path: 'api/projects/4242/query/',
                data: { query: 'select 1 from events limit 5' },
            })
            expect(result.result).toEqual({ results: [[1]] })
            expect(result.ran_in).toMatchObject({ project_id: 4242, region: 'EU' })
        })

        it.each([
            ['an unknown tool name', 'no-such-tool'],
            ['a connection chained through itself', 'posthog-connection-call'],
            ['the raw forwarder', 'posthog-connection-forward'],
            ['a session-state tool', 'switch-project'],
        ])('refuses %s before contacting the connection', async (_case, toolName) => {
            const request = createRequestMock({ status: 200, data: {} })
            const tool = createConnectionCallTool((name) => (name === 'execute-sql' ? fakeTool(name) : undefined))

            const error = await tool
                .handler(createContext(request), { connection_id: '99', tool: toolName, arguments: {} })
                .catch((e) => e)

            expect(error).toBeInstanceOf(ExecCommandError)
            expect(request).not.toHaveBeenCalledWith(expect.objectContaining({ path: FORWARD_PATH }))
        })

        it('runs a tool that builds its own request through the connection, not against the target', async () => {
            // `execute-sql` reaches the API through `invokeMcpTool` rather than a generated handler.
            // Whatever route it takes has to be the client's, or it sends the caller's own bearer
            // token straight to the connected project's server and skips `forward/` entirely.
            const globalFetch = vi.fn()
            vi.stubGlobal('fetch', globalFetch)
            const request = createRequestMock({ status: 200, data: { success: true, content: 'rows' } })
            const tool = createConnectionCallTool((name) => (name === 'execute-sql' ? executeSqlTool() : undefined))

            const result: any = await tool.handler(createContext(request), {
                connection_id: '99',
                tool: 'execute-sql',
                arguments: { query: 'select 1' },
            })

            const forwardCall = request.mock.calls.find(([opts]: any[]) => opts.path === FORWARD_PATH)
            expect(forwardCall![0].body).toMatchObject({
                method: 'POST',
                path: 'api/environments/4242/mcp_tools/execute_sql/',
            })
            expect(globalFetch).not.toHaveBeenCalled()
            expect(result.result).toBe('rows')
        })

        it.each([
            ['the target has not approved it', false],
            ['the target’s approval cannot be read', undefined],
        ])('refuses an AI-consuming tool when %s', async (_case, consent) => {
            // AI consent is filtered per session locally, but a tool named here comes from the
            // registry, and it is the *other* organization's approval that governs. The API gates
            // these endpoints on a feature flag and scopes only, so nothing downstream would stop it.
            const request = createRequestMock({ status: 200, data: {} })
            const tool = createConnectionCallTool(() => fakeTool(AI_CONSENT_TOOL))
            const context = createContext(request)
            vi.spyOn(StateManager.prototype, 'getAiConsentGiven').mockResolvedValue(consent)

            const error: any = await tool
                .handler(context, { connection_id: '99', tool: AI_CONSENT_TOOL, arguments: { query: 'x' } })
                .catch((e) => e)

            expect(error).toBeInstanceOf(ExecCommandError)
            expect(error.message).toContain('has not approved AI data processing')
            expect(request).not.toHaveBeenCalledWith(expect.objectContaining({ path: FORWARD_PATH }))
        })

        it('runs an AI-consuming tool once the target has approved it', async () => {
            // Guards the other direction: a gate that refused regardless would satisfy the cases above.
            const request = createRequestMock({ status: 200, data: { ok: true } })
            const tool = createConnectionCallTool(() => fakeTool(AI_CONSENT_TOOL))
            vi.spyOn(StateManager.prototype, 'getAiConsentGiven').mockResolvedValue(true)

            const result: any = await tool.handler(createContext(request), {
                connection_id: '99',
                tool: AI_CONSENT_TOOL,
                arguments: { query: 'x' },
            })

            expect(result.result).toEqual({ ok: true })
        })

        it('rejects arguments the target tool would not accept, without contacting the connection', async () => {
            // Validating up front keeps a malformed call from burning a cross-region round trip and
            // coming back as an opaque 400 from the other project.
            const request = createRequestMock({ status: 200, data: {} })
            const tool = createConnectionCallTool(() => fakeTool('execute-sql'))

            const error: any = await tool
                .handler(createContext(request), { connection_id: '99', tool: 'execute-sql', arguments: { q: 1 } })
                .catch((e) => e)

            expect(error).toBeInstanceOf(ExecCommandError)
            expect(error.message).toContain('query')
            expect(request).not.toHaveBeenCalled()
        })
    })
})