@shipfox/api-integration-slack 4.0.0

package/src/presentation/routes/install.test.ts

@@ -0,0 +1,229 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+  type UserContextMembership,
+} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import type {SlackApiClient} from '#api/client.js';
+import {SlackTokenRotationUnsupportedError} from '#core/errors.js';
+import type {ConnectSlackInstallationInput} from '#core/install.js';
+import {verifySlackInstallState} from '#core/state.js';
+import type {SlackTokenStore} from '#core/tokens.js';
+import {createSlackIntegrationProvider} from '#index.js';
+
+vi.mock('@shipfox/api-workspaces', () => ({
+  requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+}));
+
+let authenticatedMemberships: UserContextMembership[] = [];
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    if (request.headers.authorization !== 'Bearer user') {
+      throw new ClientError('Invalid user token', 'unauthorized', {status: 401});
+    }
+    setUserContext(
+      request,
+      buildUserContext({
+        userId: 'user-1',
+        email: 'user@example.com',
+        memberships: authenticatedMemberships,
+      }),
+    );
+    return Promise.resolve();
+  },
+};
+
+function slackClient(overrides: Partial<SlackApiClient> = {}): SlackApiClient {
+  return {
+    exchangeAuthorizationCode: vi.fn(() =>
+      Promise.resolve({
+        accessToken: 'xoxb-token',
+        botUserId: 'U123',
+        appId: 'A123',
+        teamId: 'T123',
+        teamName: 'Acme',
+        scopes: [
+          'app_mentions:read',
+          'im:history',
+          'chat:write',
+          'channels:history',
+          'groups:history',
+          'channels:read',
+          'groups:read',
+          'users:read',
+          'reactions:read',
+          'reactions:write',
+          'commands',
+        ],
+      }),
+    ),
+    revokeToken: vi.fn(() => Promise.resolve()),
+    callMethod: vi.fn(() => Promise.resolve({ok: true})),
+    ...overrides,
+  };
+}
+
+function connection(input: Partial<IntegrationConnection<'slack'>> = {}) {
+  return {
+    id: '00000000-0000-4000-8000-000000000001',
+    workspaceId: '00000000-0000-4000-8000-000000000002',
+    provider: 'slack',
+    externalAccountId: 'T123',
+    slug: 'slack_acme',
+    displayName: 'Slack Acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...input,
+  } satisfies IntegrationConnection<'slack'>;
+}
+
+async function createTestApp(
+  options: {
+    slack?: SlackApiClient | undefined;
+    tokenStore?: Pick<SlackTokenStore, 'storeTokens'> | undefined;
+    agentTools?: {tokenStore: Pick<SlackTokenStore, 'getAccessToken'>} | undefined;
+    connectSlackInstallation?:
+      | ((input: ConnectSlackInstallationInput) => Promise<IntegrationConnection<'slack'>>)
+      | undefined;
+  } = {},
+): Promise<FastifyInstance> {
+  const provider = createSlackIntegrationProvider({
+    slack: options.slack ?? slackClient(),
+    agentTools: options.agentTools,
+    routes: {
+      tokenStore: options.tokenStore ?? {storeTokens: vi.fn(() => Promise.resolve())},
+      getExistingSlackConnection: vi.fn(() => Promise.resolve(undefined)),
+      connectSlackInstallation:
+        options.connectSlackInstallation ??
+        vi.fn((input: ConnectSlackInstallationInput) =>
+          Promise.resolve(connection({workspaceId: input.workspaceId})),
+        ),
+      disconnectSlackInstallation: vi.fn(() => Promise.resolve()),
+    },
+  });
+  const app = await createApp({auth: [fakeUserAuth], routes: provider.routes, swagger: false});
+  await app.ready();
+  return app;
+}
+
+describe('Slack integration routes', () => {
+  beforeEach(async () => {
+    authenticatedMemberships = [];
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('returns Slack’s bot-only OAuth URL with signed workspace state', async () => {
+    const app = await createTestApp();
+    const workspaceId = '00000000-0000-4000-8000-000000000002';
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack/install',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId},
+    });
+
+    const installUrl = new URL(res.json().install_url);
+    const state = installUrl.searchParams.get('state');
+    expect(res.statusCode).toBe(200);
+    expect(installUrl.origin + installUrl.pathname).toBe('https://slack.com/oauth/v2/authorize');
+    expect(installUrl.searchParams.get('scope')).toContain('app_mentions:read');
+    expect(installUrl.searchParams.has('user_scope')).toBe(false);
+    expect(verifySlackInstallState(state ?? '')).toEqual({workspaceId, userId: 'user-1'});
+  });
+
+  it('rejects install requests for a workspace the actor cannot access', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack/install',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: '00000000-0000-4000-8000-000000000002'},
+    });
+
+    expect(res.statusCode).toBe(403);
+  });
+
+  it.each([
+    {
+      capability: 'without agent tools',
+      agentTools: undefined,
+      expectedCapabilities: [],
+    },
+    {
+      capability: 'with agent tools',
+      agentTools: {tokenStore: {getAccessToken: vi.fn(() => Promise.resolve('xoxb-token'))}},
+      expectedCapabilities: ['agent_tools'],
+    },
+  ])('returns the connected Slack connection $capability', async ({
+    agentTools,
+    expectedCapabilities,
+  }) => {
+    const tokenStore = {storeTokens: vi.fn(() => Promise.resolve())};
+    const app = await createTestApp({tokenStore, agentTools});
+    const workspaceId = '00000000-0000-4000-8000-000000000002';
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+    const install = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack/install',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId},
+    });
+    const state = new URL(install.json().install_url).searchParams.get('state');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integrations/slack/callback/api?code=code&state=${state}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({provider: 'slack', capabilities: expectedCapabilities});
+    expect(tokenStore.storeTokens).toHaveBeenCalledWith({
+      connectionId: '00000000-0000-4000-8000-000000000001',
+      botToken: 'xoxb-token',
+      editedBy: 'user-1',
+    });
+  });
+
+  it('rejects a callback whose OAuth response enables token rotation', async () => {
+    const tokenStore = {storeTokens: vi.fn(() => Promise.resolve())};
+    const slack = slackClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SlackTokenRotationUnsupportedError()),
+      ),
+    });
+    const app = await createTestApp({slack, tokenStore});
+    const workspaceId = '00000000-0000-4000-8000-000000000002';
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+    const install = await app.inject({
+      method: 'POST',
+      url: '/integrations/slack/install',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId},
+    });
+    const state = new URL(install.json().install_url).searchParams.get('state');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integrations/slack/callback/api?code=code&state=${state}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(422);
+    expect(res.json().code).toBe('slack-token-rotation-unsupported');
+    expect(tokenStore.storeTokens).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/routes/install.ts

@@ -0,0 +1,117 @@
+import {AUTH_USER, requireUserContext, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import type {IntegrationCapability, IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {
+  createSlackInstallBodySchema,
+  createSlackInstallResponseSchema,
+  type SlackCallbackQueryDto,
+  slackCallbackQuerySchema,
+  slackCallbackResponseSchema,
+} from '@shipfox/api-integration-slack-dto';
+import {requireWorkspaceMembership} from '@shipfox/api-workspaces';
+import {defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {SlackApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {
+  type ConnectSlackInstallationInput,
+  handleSlackCallback,
+  handleSlackOAuthCallbackError,
+} from '#core/install.js';
+import {formatSlackBotScopes} from '#core/scopes.js';
+import {signSlackInstallState} from '#core/state.js';
+import type {SlackTokenStore} from '#core/tokens.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+import {slackRouteErrorHandler} from './errors.js';
+
+export interface CreateSlackIntegrationRoutesOptions {
+  slack: SlackApiClient;
+  tokenStore: Pick<SlackTokenStore, 'storeTokens'>;
+  getExistingSlackConnection: (input: {
+    teamId: string;
+  }) => Promise<IntegrationConnection<'slack'> | undefined>;
+  connectSlackInstallation: (
+    input: ConnectSlackInstallationInput,
+  ) => Promise<IntegrationConnection<'slack'>>;
+  disconnectSlackInstallation: (input: {connectionId: string}) => Promise<void>;
+  connectionCapabilities: IntegrationCapability[];
+}
+
+export function createSlackIntegrationRoutes({
+  slack,
+  tokenStore,
+  getExistingSlackConnection,
+  connectSlackInstallation,
+  disconnectSlackInstallation,
+  connectionCapabilities,
+}: CreateSlackIntegrationRoutesOptions): RouteGroup {
+  const installRoute = defineRoute({
+    method: 'POST',
+    path: '/install',
+    auth: AUTH_USER,
+    description: 'Create a Slack OAuth authorization URL for a workspace.',
+    schema: {
+      body: createSlackInstallBodySchema,
+      response: {200: createSlackInstallResponseSchema},
+    },
+    handler: (request) => {
+      const {workspace_id: workspaceId} = request.body;
+      const actor = requireUserContext(request);
+      requireWorkspaceAccess({request, workspaceId});
+      const state = signSlackInstallState({workspaceId, userId: actor.userId});
+      const installUrl = new URL('https://slack.com/oauth/v2/authorize');
+      installUrl.searchParams.set('client_id', config.SLACK_OAUTH_CLIENT_ID);
+      installUrl.searchParams.set('scope', formatSlackBotScopes());
+      installUrl.searchParams.set('redirect_uri', config.SLACK_OAUTH_REDIRECT_URL);
+      installUrl.searchParams.set('state', state);
+      return {install_url: installUrl.toString()};
+    },
+  });
+
+  const callbackApiRoute = defineRoute({
+    method: 'GET',
+    path: '/callback/api',
+    auth: AUTH_USER,
+    description: 'Handle the Slack OAuth callback.',
+    schema: {
+      querystring: slackCallbackQuerySchema,
+      response: {200: slackCallbackResponseSchema},
+    },
+    errorHandler: slackRouteErrorHandler,
+    handler: async (request) => {
+      const actor = requireUserContext(request);
+      const query = request.query;
+      if (isSlackOAuthErrorCallback(query)) {
+        return await handleSlackOAuthCallbackError({
+          state: query.state,
+          error: query.error,
+          errorDescription: query.error_description,
+          sessionUserId: actor.userId,
+          sessionMemberships: actor.memberships,
+          requireWorkspaceMembership,
+        });
+      }
+      const connection = await handleSlackCallback({
+        slack,
+        tokenStore,
+        code: query.code,
+        state: query.state,
+        sessionUserId: actor.userId,
+        sessionMemberships: actor.memberships,
+        requireWorkspaceMembership,
+        getExistingSlackConnection,
+        connectSlackInstallation,
+        disconnectSlackInstallation,
+      });
+      return toIntegrationConnectionDto(connection, {capabilities: connectionCapabilities});
+    },
+  });
+
+  return {prefix: '/integrations/slack', routes: [installRoute, callbackApiRoute]};
+}
+
+function isSlackOAuthErrorCallback(query: SlackCallbackQueryDto): query is SlackCallbackQueryDto & {
+  error: string;
+  error_description?: string | undefined;
+  state: string;
+} {
+  return 'error' in query && typeof query.error === 'string';
+}

package/src/presentation/routes/webhooks.test.ts

@@ -0,0 +1,266 @@
+import {createHmac, randomUUID} from 'node:crypto';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import {db} from '#db/db.js';
+import {upsertSlackInstallation} from '#db/installations.js';
+import {slackInstallations} from '#db/schema/installations.js';
+import {createSlackWebhookRoutes, SLASH_COMMAND_ACK} from './webhooks.js';
+
+const signingSecret = 'test-signing-secret';
+
+function fakeConnection(): IntegrationConnection {
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'slack',
+    externalAccountId: 'T1',
+    slug: 'slack_acme',
+    displayName: 'Slack Acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function slackHeaders(
+  rawBody: string,
+  contentType: string,
+  timestamp = `${Math.floor(Date.now() / 1000)}`,
+) {
+  const hex = createHmac('sha256', signingSecret)
+    .update(`v0:${timestamp}:${rawBody}`)
+    .digest('hex');
+  return {
+    'content-type': contentType,
+    'x-slack-request-timestamp': timestamp,
+    'x-slack-signature': `v0=${hex}`,
+  };
+}
+
+async function createTestApp(connection = fakeConnection()): Promise<{
+  app: Awaited<ReturnType<typeof createApp>>;
+  connection: IntegrationConnection;
+  publishIntegrationEventReceived: ReturnType<typeof vi.fn>;
+  recordDeliveryOnly: ReturnType<typeof vi.fn>;
+  getIntegrationConnectionById: ReturnType<typeof vi.fn>;
+}> {
+  const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+  const recordDeliveryOnly = vi.fn(() => Promise.resolve());
+  const getIntegrationConnectionById = vi.fn(() => Promise.resolve(connection));
+  const app = await createApp({
+    routes: createSlackWebhookRoutes({
+      coreDb: db,
+      publishIntegrationEventReceived,
+      recordDeliveryOnly,
+      getIntegrationConnectionById,
+    }),
+    swagger: false,
+  });
+  await app.ready();
+  return {
+    app,
+    connection,
+    publishIntegrationEventReceived,
+    recordDeliveryOnly,
+    getIntegrationConnectionById,
+  };
+}
+
+async function seedInstallation(connection: IntegrationConnection): Promise<void> {
+  await upsertSlackInstallation({
+    connectionId: connection.id,
+    teamId: 'T1',
+    teamName: 'Acme',
+    appId: 'A1',
+    botUserId: 'UBOT',
+    scopes: [],
+    status: 'installed',
+  });
+}
+
+describe('Slack webhook routes', () => {
+  beforeEach(async () => {
+    await closeApp();
+    await db().delete(slackInstallations);
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('answers a signed URL verification before resolving an installation', async () => {
+    const {app, getIntegrationConnectionById} = await createTestApp();
+    const rawBody = JSON.stringify({
+      type: 'url_verification',
+      token: 'token',
+      challenge: 'challenge',
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: slackHeaders(rawBody, 'application/json'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({challenge: 'challenge'});
+    expect(getIntegrationConnectionById).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unsigned request before parsing its body', async () => {
+    const {app, publishIntegrationEventReceived, recordDeliveryOnly} = await createTestApp();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: {'content-type': 'application/json'},
+      payload: '{"type":',
+    });
+
+    expect(response.statusCode).toBe(401);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('rejects a stale signed event before parsing it', async () => {
+    const {app, publishIntegrationEventReceived, recordDeliveryOnly} = await createTestApp();
+    const rawBody = JSON.stringify({
+      type: 'url_verification',
+      token: 'token',
+      challenge: 'challenge',
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: slackHeaders(rawBody, 'application/json', `${Math.floor(Date.now() / 1000) - 301}`),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(401);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('rejects signed malformed event JSON', async () => {
+    const {app, publishIntegrationEventReceived, recordDeliveryOnly} = await createTestApp();
+    const rawBody = '{"type":';
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: slackHeaders(rawBody, 'application/json'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('publishes a signed event delivery through the route transaction', async () => {
+    const {app, connection, publishIntegrationEventReceived} = await createTestApp();
+    await seedInstallation(connection);
+    const rawBody = JSON.stringify({
+      type: 'event_callback',
+      team_id: 'T1',
+      api_app_id: 'A1',
+      event: {type: 'app_mention', channel: 'C1', user: 'U1', text: 'hello', ts: '1.0'},
+      event_id: 'Ev-route',
+      event_time: 1_721_300_000,
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: slackHeaders(rawBody, 'application/json'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(publishIntegrationEventReceived).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: expect.objectContaining({event: 'app_mention', deliveryId: 'Ev-route'}),
+      }),
+    );
+  });
+
+  it('returns the fixed acknowledgement for a signed command that cannot resolve a team', async () => {
+    const {app, publishIntegrationEventReceived, recordDeliveryOnly} = await createTestApp();
+    const rawBody = new URLSearchParams({
+      token: 'verification-token',
+      command: '/deploy',
+      team_id: 'T-missing',
+      channel_id: 'C1',
+      user_id: 'U1',
+      response_url: 'https://hooks.slack.com/commands/1',
+      trigger_id: '1337.42',
+      text: '',
+    }).toString();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/commands',
+      headers: slackHeaders(rawBody, 'application/x-www-form-urlencoded'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual(SLASH_COMMAND_ACK);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).toHaveBeenCalledWith(
+      expect.objectContaining({provider: 'slack', deliveryId: '1337.42'}),
+    );
+  });
+
+  it('returns the acknowledgement for a signed command that fails validation', async () => {
+    const {app, publishIntegrationEventReceived, recordDeliveryOnly} = await createTestApp();
+    const rawBody = new URLSearchParams({team_id: 'T1'}).toString();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/commands',
+      headers: slackHeaders(rawBody, 'application/x-www-form-urlencoded'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual(SLASH_COMMAND_ACK);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('publishes a signed command without exposing its verification token', async () => {
+    const {app, connection, publishIntegrationEventReceived} = await createTestApp();
+    await seedInstallation(connection);
+    const rawBody = new URLSearchParams({
+      token: 'verification-token',
+      command: '/deploy',
+      team_id: 'T1',
+      channel_id: 'C1',
+      user_id: 'U1',
+      response_url: 'https://hooks.slack.com/commands/1',
+      trigger_id: '1337.43',
+      text: 'production',
+    }).toString();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/commands',
+      headers: slackHeaders(rawBody, 'application/x-www-form-urlencoded'),
+      payload: rawBody,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(publishIntegrationEventReceived).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: expect.objectContaining({
+          event: 'slash_command',
+          deliveryId: '1337.43',
+          payload: expect.not.objectContaining({token: expect.anything()}),
+        }),
+      }),
+    );
+  });
+});