@shipfox/api-integration-slack 4.0.0 → 5.0.0

package/src/core/webhook.ts

@@ -1,4 +1,5 @@
 import type {
+  ClaimWebhookDeliveryFn,
   GetIntegrationConnectionByIdFn,
   IntegrationConnection,
   IntegrationTx,
@@ -6,15 +7,23 @@ import type {
   RecordDeliveryOnlyFn,
 } from '@shipfox/api-integration-core-dto';
 import {
+  SLACK_APP_UNINSTALLED_EVENT,
   SLACK_PROVIDER,
   SLACK_SLASH_COMMAND_EVENT,
   type SlackEventBaseEnvelopeDto,
+  type SlackLifecycleEventType,
   type SlackSlashCommandDto,
   slackEventEnvelopeSchema,
+  slackLifecycleEventTypes,
+  slackTokensRevokedEventSchema,
 } from '@shipfox/api-integration-slack-dto';
 import {logger} from '@shipfox/node-opentelemetry';
 import {z} from 'zod';
-import {getSlackInstallationByTeamId, type SlackInstallation} from '#db/installations.js';
+import {
+  getSlackInstallationByTeamId,
+  markSlackInstallationRevoked,
+  type SlackInstallation,
+} from '#db/installations.js';
 
 const slackSelfAuthoredEventSchema = z
   .object({
@@ -35,6 +44,9 @@ export type SlackWebhookOutcome =
   | 'duplicate'
   | 'unknown-team'
   | 'revoked-installation'
+  | 'revoked'
+  | 'unaffected-revocation'
+  | 'stale-lifecycle-event'
   | 'missing-connection'
   | 'inactive-connection'
   | 'unsupported-event'
@@ -50,6 +62,7 @@ interface SlackWebhookParams {
 
 export interface HandleSlackEventParams extends SlackWebhookParams {
   envelope: SlackEventBaseEnvelopeDto;
+  claimWebhookDelivery: ClaimWebhookDeliveryFn;
 }
 
 export interface HandleSlackCommandParams extends SlackWebhookParams {
@@ -60,15 +73,25 @@ type SlackConnectionResolution =
   | {kind: 'ok'; connection: IntegrationConnection; installation: SlackInstallation}
   | {
       kind: 'drop';
-      outcome: Exclude<
-        SlackWebhookOutcome,
-        'published' | 'duplicate' | 'unsupported-event' | 'self-message'
-      >;
+      outcome: SlackConnectionDropOutcome;
     };
 
+type SlackCommandOutcome = Exclude<
+  SlackWebhookOutcome,
+  | 'unsupported-event'
+  | 'self-message'
+  | 'revoked'
+  | 'unaffected-revocation'
+  | 'stale-lifecycle-event'
+>;
+type SlackConnectionDropOutcome = Exclude<SlackCommandOutcome, 'published' | 'duplicate'>;
+
 export async function handleSlackEvent(
   params: HandleSlackEventParams,
 ): Promise<{outcome: SlackWebhookOutcome}> {
+  const lifecycleType = asSlackLifecycleEventType(params.envelope.event.type);
+  if (lifecycleType) return handleSlackLifecycleEvent(params, lifecycleType);
+
   const resolution = await resolveSlackConnection({
     ...params,
     teamId: params.envelope.team_id,
@@ -120,7 +143,7 @@ export async function handleSlackEvent(
 
 export async function handleSlackCommand(
   params: HandleSlackCommandParams,
-): Promise<{outcome: Exclude<SlackWebhookOutcome, 'unsupported-event' | 'self-message'>}> {
+): Promise<{outcome: SlackCommandOutcome}> {
   const resolution = await resolveSlackConnection({
     ...params,
     teamId: params.command.team_id,
@@ -158,6 +181,120 @@ export function isSelfAuthoredSlackEvent(event: unknown, botUserId: string): boo
   );
 }
 
+function asSlackLifecycleEventType(eventType: string): SlackLifecycleEventType | undefined {
+  return slackLifecycleEventTypes.find((type) => type === eventType);
+}
+
+async function handleSlackLifecycleEvent(
+  params: HandleSlackEventParams,
+  lifecycleType: SlackLifecycleEventType,
+): Promise<{outcome: SlackWebhookOutcome}> {
+  const claim = await params.claimWebhookDelivery({
+    tx: params.tx,
+    provider: SLACK_PROVIDER,
+    deliveryId: params.deliveryId,
+  });
+  if (!claim.claimed) {
+    logger().info(
+      {deliveryId: params.deliveryId, teamId: params.envelope.team_id, lifecycleType},
+      'slack lifecycle event: duplicate delivery, dropping',
+    );
+    return {outcome: 'duplicate'};
+  }
+
+  const installation = await getSlackInstallationByTeamId(params.envelope.team_id, {tx: params.tx});
+  if (!installation) {
+    logger().warn(
+      {deliveryId: params.deliveryId, teamId: params.envelope.team_id, lifecycleType},
+      'slack lifecycle event: unknown team, dropping',
+    );
+    return {outcome: 'unknown-team'};
+  }
+
+  if (installation.status !== 'installed') {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.envelope.team_id,
+        connectionId: installation.connectionId,
+        lifecycleType,
+      },
+      'slack lifecycle event: installation is not installed, dropping',
+    );
+    return {outcome: 'revoked-installation'};
+  }
+
+  if (
+    isSlackLifecycleEventOlderThanInstallation(params.envelope.event_time, installation.updatedAt)
+  ) {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.envelope.team_id,
+        connectionId: installation.connectionId,
+      },
+      'slack lifecycle event: predates the current installation, dropping',
+    );
+    return {outcome: 'stale-lifecycle-event'};
+  }
+
+  const revokesInstallation =
+    lifecycleType === SLACK_APP_UNINSTALLED_EVENT ||
+    slackTokensRevokedAffectsBot(params.envelope.event, installation.botUserId);
+  if (!revokesInstallation) {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.envelope.team_id,
+        connectionId: installation.connectionId,
+      },
+      'slack lifecycle event: token revocation does not affect installation bot, dropping',
+    );
+    return {outcome: 'unaffected-revocation'};
+  }
+
+  const revoked = await markSlackInstallationRevoked(installation.connectionId, {
+    tx: params.tx,
+    expectedGeneration: installation.generation,
+  });
+  if (!revoked) {
+    logger().info(
+      {
+        deliveryId: params.deliveryId,
+        teamId: params.envelope.team_id,
+        connectionId: installation.connectionId,
+      },
+      'slack lifecycle event: installation changed before revocation, dropping',
+    );
+    return {outcome: 'stale-lifecycle-event'};
+  }
+
+  logger().info(
+    {
+      deliveryId: params.deliveryId,
+      teamId: params.envelope.team_id,
+      connectionId: installation.connectionId,
+      lifecycleType,
+    },
+    'slack lifecycle event: installation revoked',
+  );
+  return {outcome: 'revoked'};
+}
+
+function slackTokensRevokedAffectsBot(event: unknown, botUserId: string): boolean {
+  const parsed = slackTokensRevokedEventSchema.safeParse(event);
+  // Only a named bot token proves this installation credential was revoked; OAuth-only and missing lists do not.
+  return parsed.success && (parsed.data.tokens?.bot?.includes(botUserId) ?? false);
+}
+
+function isSlackLifecycleEventOlderThanInstallation(
+  eventTime: number,
+  installationUpdatedAt: Date,
+): boolean {
+  // Slack event_time has second precision, so an event stamped in the installation second is not provably stale.
+  return eventTime < Math.floor(installationUpdatedAt.getTime() / 1000);
+}
+
 async function resolveSlackConnection(
   params: SlackWebhookParams & {teamId: string},
 ): Promise<SlackConnectionResolution> {

package/src/db/installations.test.ts

@@ -90,4 +90,19 @@ describe('slack installations', () => {
 
     expect(result?.status).toBe('revoked');
   });
+
+  it('does not revoke an installation updated after the lifecycle event was read', async () => {
+    const input = createInstallationInput();
+    const installation = await upsertSlackInstallation(input);
+    await upsertSlackInstallation(input);
+
+    const result = await markSlackInstallationRevoked(input.connectionId, {
+      expectedGeneration: installation.generation,
+    });
+
+    expect(result).toBeUndefined();
+    await expect(getSlackInstallationByConnectionId(input.connectionId)).resolves.toMatchObject({
+      status: 'installed',
+    });
+  });
 });

package/src/db/installations.ts

@@ -1,5 +1,5 @@
 import {isUniqueViolation} from '@shipfox/node-drizzle';
-import {eq} from 'drizzle-orm';
+import {and, eq, sql} from 'drizzle-orm';
 import {
   SlackConnectionAlreadyLinkedError,
   SlackInstallationAlreadyLinkedError,
@@ -18,6 +18,7 @@ export interface SlackInstallation {
   botUserId: string;
   scopes: string[];
   status: SlackInstallationStatus;
+  generation: number;
   tokenExpiresAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
@@ -69,6 +70,7 @@ export async function upsertSlackInstallation(
           botUserId: params.botUserId,
           scopes: params.scopes,
           status: params.status,
+          generation: sql`${slackInstallations.generation} + 1`,
           tokenExpiresAt: params.tokenExpiresAt ?? null,
           updatedAt: now,
         },
@@ -128,13 +130,19 @@ export async function deleteSlackInstallationByConnectionId(
 
 export async function markSlackInstallationRevoked(
   connectionId: string,
-  options: {tx?: unknown} = {},
+  options: {tx?: unknown; expectedGeneration?: number | undefined} = {},
 ): Promise<SlackInstallation | undefined> {
   const executor = (options.tx ?? db()) as SlackDb | SlackTx;
+  const expectedInstallation = options.expectedGeneration
+    ? and(
+        eq(slackInstallations.connectionId, connectionId),
+        eq(slackInstallations.generation, options.expectedGeneration),
+      )
+    : eq(slackInstallations.connectionId, connectionId);
   const [row] = await executor
     .update(slackInstallations)
     .set({status: 'revoked', updatedAt: new Date()})
-    .where(eq(slackInstallations.connectionId, connectionId))
+    .where(expectedInstallation)
     .returning();
   if (!row) return undefined;
   return toSlackInstallation(row);

package/src/db/schema/installations.ts

@@ -1,5 +1,5 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
-import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {integer, jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
 import type {SlackInstallation} from '#db/installations.js';
 import {pgTable} from './common.js';
 
@@ -14,6 +14,7 @@ export const slackInstallations = pgTable(
     botUserId: text('bot_user_id').notNull(),
     scopes: jsonb('scopes').notNull().$type<string[]>(),
     status: text('status').notNull().$type<SlackInstallation['status']>(),
+    generation: integer('generation').notNull().default(1),
     tokenExpiresAt: timestamp('token_expires_at', {withTimezone: true}),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
@@ -37,6 +38,7 @@ export function toSlackInstallation(row: SlackInstallationDb): SlackInstallation
     botUserId: row.botUserId,
     scopes: row.scopes,
     status: row.status,
+    generation: row.generation,
     tokenExpiresAt: row.tokenExpiresAt,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,

package/src/index.test.ts

@@ -22,4 +22,15 @@ describe('createSlackIntegrationProvider', () => {
 
     expect(catalog).toBe(slackAgentToolCatalog);
   });
+
+  it('exposes explicit connection cleanup without requiring routes', () => {
+    const deleteConnectionRecords = vi.fn(() => Promise.resolve());
+    const deleteConnectionSecrets = vi.fn(() => Promise.resolve());
+    const provider = createSlackIntegrationProvider({
+      cleanup: {deleteConnectionRecords, deleteConnectionSecrets},
+    });
+
+    expect(provider.deleteConnectionRecords).toBe(deleteConnectionRecords);
+    expect(provider.deleteConnectionSecrets).toBe(deleteConnectionSecrets);
+  });
 });

package/src/index.ts

@@ -113,6 +113,15 @@ export interface CreateSlackIntegrationProviderOptions {
   slack?: SlackApiClient | undefined;
   agentTools?: {tokenStore: Pick<SlackTokenStore, 'getAccessToken'>} | undefined;
   getSlackInstallationByConnectionId?: typeof getSlackInstallationByConnectionId | undefined;
+  cleanup?:
+    | {
+        deleteConnectionRecords?: (
+          connection: {id: string},
+          options: {tx: unknown},
+        ) => Promise<void>;
+        deleteConnectionSecrets?: (connection: {id: string; workspaceId: string}) => Promise<void>;
+      }
+    | undefined;
   routes?: SlackRouteOptions | undefined;
 }
 
@@ -169,6 +178,7 @@ export function createSlackIntegrationProvider(
       if (!installation) return undefined;
       return `https://app.slack.com/client/${encodeURIComponent(installation.teamId)}`;
     },
+    ...options.cleanup,
     routes,
   };
 }
@@ -189,6 +199,7 @@ function hasSlackWebhookRoutesOptions(
 ): routes is CreateSlackWebhookRoutesOptions {
   return (
     routes.coreDb !== undefined &&
+    routes.claimWebhookDelivery !== undefined &&
     routes.publishIntegrationEventReceived !== undefined &&
     routes.recordDeliveryOnly !== undefined &&
     routes.getIntegrationConnectionById !== undefined

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

@@ -2,7 +2,7 @@ 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 {getSlackInstallationByTeamId, upsertSlackInstallation} from '#db/installations.js';
 import {slackInstallations} from '#db/schema/installations.js';
 import {createSlackWebhookRoutes, SLASH_COMMAND_ACK} from './webhooks.js';
 
@@ -46,10 +46,12 @@ async function createTestApp(connection = fakeConnection()): Promise<{
 }> {
   const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
   const recordDeliveryOnly = vi.fn(() => Promise.resolve());
+  const claimWebhookDelivery = vi.fn(() => Promise.resolve({claimed: true}));
   const getIntegrationConnectionById = vi.fn(() => Promise.resolve(connection));
   const app = await createApp({
     routes: createSlackWebhookRoutes({
       coreDb: db,
+      claimWebhookDelivery,
       publishIntegrationEventReceived,
       recordDeliveryOnly,
       getIntegrationConnectionById,
@@ -186,6 +188,31 @@ describe('Slack webhook routes', () => {
     );
   });
 
+  it('revokes an installation after a signed app-uninstalled event', 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_uninstalled'},
+      event_id: 'Ev-route-uninstalled',
+      event_time: Math.floor(Date.now() / 1000) + 60,
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/slack/events',
+      headers: slackHeaders(rawBody, 'application/json'),
+      payload: rawBody,
+    });
+
+    const installation = await getSlackInstallationByTeamId('T1');
+    expect(response.statusCode).toBe(200);
+    expect(installation?.status).toBe('revoked');
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
   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({

package/src/presentation/routes/webhooks.ts

@@ -1,5 +1,6 @@
 import {Buffer} from 'node:buffer';
 import type {
+  ClaimWebhookDeliveryFn,
   GetIntegrationConnectionByIdFn,
   PublishIntegrationEventReceivedFn,
   RecordDeliveryOnlyFn,
@@ -29,6 +30,7 @@ const slackFormRawBodyPlugin = createRawBodyPlugin({
 
 export interface CreateSlackWebhookRoutesOptions {
   coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  claimWebhookDelivery: ClaimWebhookDeliveryFn;
   publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
   recordDeliveryOnly: RecordDeliveryOnlyFn;
   getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
@@ -84,6 +86,7 @@ export function createSlackWebhookRoutes(options: CreateSlackWebhookRoutesOption
           tx,
           deliveryId: eventRequest.event_id,
           envelope: eventRequest,
+          claimWebhookDelivery: options.claimWebhookDelivery,
           publishIntegrationEventReceived: options.publishIntegrationEventReceived,
           recordDeliveryOnly: options.recordDeliveryOnly,
           getIntegrationConnectionById: options.getIntegrationConnectionById,