@shipfox/api-integration-slack 5.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-slack",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -25,25 +25,24 @@
     "drizzle-orm": "^0.45.2",
     "ky": "^2.0.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "5.0.0",
-    "@shipfox/api-integration-core-dto": "5.0.0",
-    "@shipfox/api-integration-slack-dto": "5.0.0",
-    "@shipfox/api-workspaces": "5.0.0",
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-integration-slack-dto": "6.0.0",
+    "@shipfox/api-workspaces-dto": "6.0.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-drizzle": "0.3.1",
-    "@shipfox/node-fastify": "0.2.3",
+    "@shipfox/inter-module": "0.2.0",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-fastify": "0.2.4",
     "@shipfox/node-opentelemetry": "0.5.2",
     "@shipfox/node-postgres": "0.4.2"
   },
-  "peerDependencies": {
-    "@shipfox/api-secrets": "5.0.0"
-  },
   "devDependencies": {
     "@types/pg": "^8.15.5",
     "drizzle-kit": "^0.31.10",
     "fastify": "^5.3.3",
     "fishery": "^2.4.0",
     "@shipfox/biome": "1.8.2",
+    "@shipfox/depcruise": "1.0.2",
     "@shipfox/swc": "1.2.6",
     "@shipfox/ts-config": "1.3.8",
     "@shipfox/typescript": "1.1.7",
@@ -53,6 +52,7 @@
     "build": "shipfox-swc",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/core/disconnect.test.ts

@@ -10,6 +10,7 @@ const deleteSlackInstallationByConnectionIdMock = vi.mocked(deleteSlackInstallat
 describe('disconnectSlackInstallation', () => {
   beforeEach(() => {
     deleteSlackInstallationByConnectionIdMock.mockClear();
+    deleteSlackInstallationByConnectionIdMock.mockResolvedValue(true);
   });
 
   it('deletes stored tokens before deleting connection records', async () => {
@@ -46,4 +47,50 @@ describe('disconnectSlackInstallation', () => {
       deleteConnection.mock.invocationCallOrder[0] ?? 0,
     );
   });
+
+  it('keeps connection records when secret deletion fails', async () => {
+    const transaction = vi.fn();
+    const deleteConnection = vi.fn();
+
+    const run = disconnectSlackInstallation({
+      connectionId: 'connection-1',
+      getConnection: vi.fn(() => Promise.resolve({workspaceId: 'workspace-1'})),
+      deleteSecrets: vi.fn(() => Promise.reject(new Error('secret store unavailable'))),
+      transaction,
+      deleteConnection,
+    });
+
+    await expect(run).rejects.toThrow('secret store unavailable');
+    expect(transaction).not.toHaveBeenCalled();
+    expect(deleteSlackInstallationByConnectionIdMock).not.toHaveBeenCalled();
+    expect(deleteConnection).not.toHaveBeenCalled();
+  });
+
+  it('retries idempotent secret deletion after the records transaction fails', async () => {
+    const tx = Symbol('tx');
+    const deleteSecrets = vi.fn(() => Promise.resolve(0));
+    const deleteConnection = vi.fn(() => Promise.resolve(true));
+    const transaction = vi
+      .fn()
+      .mockImplementationOnce(async (fn: (value: symbol) => Promise<unknown>) => {
+        await fn(tx);
+        throw new Error('database commit failed');
+      })
+      .mockImplementationOnce(async (fn: (value: symbol) => Promise<unknown>) => await fn(tx));
+    const params = {
+      connectionId: 'connection-1',
+      getConnection: vi.fn(() => Promise.resolve({workspaceId: 'workspace-1'})),
+      deleteSecrets,
+      transaction,
+      deleteConnection,
+    };
+
+    const firstAttempt = disconnectSlackInstallation(params);
+    await expect(firstAttempt).rejects.toThrow('database commit failed');
+    await disconnectSlackInstallation(params);
+
+    expect(deleteSecrets).toHaveBeenCalledTimes(2);
+    expect(deleteSlackInstallationByConnectionIdMock).toHaveBeenCalledTimes(2);
+    expect(deleteConnection).toHaveBeenCalledTimes(2);
+  });
 });

package/src/core/signature.test.ts

@@ -3,11 +3,11 @@ import {verifySlackSignature} from './signature.js';
 
 const secret = 'test-signing-secret';
 const timestamp = '1721300000';
-const rawBody = '{"type":"event_callback"}';
+const rawBody = Buffer.from('{"type":"event_callback"}');
 const now = Number(timestamp) * 1000;
 
 function signature(body = rawBody): string {
-  return `v0=${createHmac('sha256', secret).update(`v0:${timestamp}:${body}`).digest('hex')}`;
+  return `v0=${createHmac('sha256', secret).update(`v0:${timestamp}:`).update(body).digest('hex')}`;
 }
 
 describe('verifySlackSignature', () => {
@@ -24,7 +24,7 @@ describe('verifySlackSignature', () => {
   });
 
   it.each([
-    ['a tampered body', {rawBody: '{"type":"tampered"}'}],
+    ['a tampered body', {rawBody: Buffer.from('{"type":"tampered"}')}],
     ['a missing signature', {signature: undefined}],
     ['an empty signing secret', {signingSecret: ''}],
     ['a missing timestamp', {timestamp: undefined}],

package/src/core/signature.ts

@@ -6,11 +6,25 @@ export interface VerifySlackSignatureParams {
   signingSecret: string;
   signature: string | undefined;
   timestamp: string | undefined;
-  rawBody: string;
+  rawBody: Uint8Array;
   now?: number | undefined;
   replayWindowMs?: number | undefined;
 }
 
+export function isSlackTimestampWithinReplayWindow(
+  timestamp: string,
+  now = Date.now(),
+  replayWindowMs = 300_000,
+): boolean {
+  if (!unixTimestampPattern.test(timestamp)) return false;
+
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isSafeInteger(timestampSeconds)) return false;
+  const timestampMilliseconds = timestampSeconds * 1000;
+  if (!Number.isSafeInteger(timestampMilliseconds)) return false;
+  return Math.abs(now - timestampMilliseconds) <= replayWindowMs;
+}
+
 export function verifySlackSignature({
   signingSecret,
   signature,
@@ -19,18 +33,14 @@ export function verifySlackSignature({
   now = Date.now(),
   replayWindowMs = 300_000,
 }: VerifySlackSignatureParams): boolean {
-  if (!signingSecret || !signature || !timestamp || !unixTimestampPattern.test(timestamp)) {
+  if (!signingSecret || !signature || !timestamp) {
     return false;
   }
-
-  const timestampSeconds = Number(timestamp);
-  if (!Number.isSafeInteger(timestampSeconds)) return false;
-  const timestampMilliseconds = timestampSeconds * 1000;
-  if (!Number.isSafeInteger(timestampMilliseconds)) return false;
-  if (Math.abs(now - timestampMilliseconds) > replayWindowMs) return false;
+  if (!isSlackTimestampWithinReplayWindow(timestamp, now, replayWindowMs)) return false;
 
   const expected = `v0=${createHmac('sha256', signingSecret)
-    .update(`v0:${timestamp}:${rawBody}`)
+    .update(`v0:${timestamp}:`)
+    .update(rawBody)
     .digest('hex')}`;
   const expectedBuffer = Buffer.from(expected, 'utf8');
   const receivedBuffer = Buffer.from(signature, 'utf8');

package/src/core/tokens.test.ts

@@ -9,8 +9,8 @@ import {
 
 let slackSecrets: SlackSecretsStore;
 
-beforeAll(async () => {
-  slackSecrets = await import('@shipfox/api-secrets');
+beforeEach(() => {
+  slackSecrets = createInMemorySecretsStore();
 });
 
 function createConnectionContext() {
@@ -161,3 +161,17 @@ describe('createSlackTokenStore', () => {
     await expect(result).rejects.toBeInstanceOf(SlackConnectionNotFoundError);
   });
 });
+
+function createInMemorySecretsStore(): SlackSecretsStore {
+  const values = new Map<string, string>();
+  const id = (params: {workspaceId: string; namespace: string; key: string}) =>
+    `${params.workspaceId}\0${params.namespace}\0${params.key}`;
+  return {
+    getSecret: async (params) => values.get(id(params)) ?? null,
+    setSecrets: async (params) => {
+      await Promise.resolve();
+      for (const [key, value] of Object.entries(params.values))
+        values.set(id({...params, key}), value);
+    },
+  };
+}

package/src/core/webhook-processor.test.ts

@@ -0,0 +1,106 @@
+import {createHmac, randomUUID} from 'node:crypto';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {createStoredWebhookRequest} from '@shipfox/api-integration-core-dto';
+import {db} from '#db/db.js';
+import {upsertSlackInstallation} from '#db/installations.js';
+import {slackInstallations} from '#db/schema/installations.js';
+import {createSlackWebhookProcessor} from './webhook-processor.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 signedEventRequest(input: {
+  receivedAt: string;
+  timestamp?: number;
+}): ReturnType<typeof createStoredWebhookRequest> {
+  const body = Buffer.from(
+    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-delayed',
+      event_time: 1_721_300_000,
+    }),
+  );
+  const timestamp = `${input.timestamp ?? Math.floor(new Date(input.receivedAt).getTime() / 1000)}`;
+  const signature = `v0=${createHmac('sha256', signingSecret)
+    .update(`v0:${timestamp}:`)
+    .update(body)
+    .digest('hex')}`;
+  return createStoredWebhookRequest({
+    requestId: randomUUID(),
+    routeId: 'slack.event',
+    receivedAt: input.receivedAt,
+    rawQueryString: '',
+    headers: {
+      'content-type': 'application/json',
+      'x-slack-request-timestamp': timestamp,
+      'x-slack-signature': signature,
+    },
+    body,
+  });
+}
+
+describe('Slack webhook processor', () => {
+  beforeEach(async () => {
+    await db().delete(slackInstallations);
+  });
+
+  it('accepts an event delayed after a valid receipt', async () => {
+    const connection = fakeConnection();
+    const receivedAt = new Date(Date.now() - 10 * 60_000).toISOString();
+    await upsertSlackInstallation({
+      connectionId: connection.id,
+      teamId: 'T1',
+      teamName: 'Acme',
+      appId: 'A1',
+      botUserId: 'UBOT',
+      scopes: [],
+      status: 'installed',
+    });
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const processor = createSlackWebhookProcessor({
+      coreDb: db,
+      claimWebhookDelivery: vi.fn(() => Promise.resolve({claimed: true})),
+      publishIntegrationEventReceived,
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(connection)),
+    });
+
+    const result = await processor.process(signedEventRequest({receivedAt}));
+
+    expect(result).toMatchObject({outcome: 'processed', deliveryId: 'Ev-delayed'});
+    expect(publishIntegrationEventReceived).toHaveBeenCalledTimes(1);
+  });
+
+  it('discards an event stale at receipt', async () => {
+    const receivedAt = new Date().toISOString();
+    const processor = createSlackWebhookProcessor({
+      coreDb: db,
+      claimWebhookDelivery: vi.fn(() => Promise.resolve({claimed: true})),
+      publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(),
+    });
+
+    const result = await processor.process(
+      signedEventRequest({receivedAt, timestamp: Math.floor(Date.now() / 1000) - 301}),
+    );
+
+    expect(result).toMatchObject({outcome: 'discarded', reason: 'stale_at_receipt'});
+  });
+});

package/src/core/webhook-processor.ts

@@ -0,0 +1,152 @@
+import {Buffer} from 'node:buffer';
+import type {
+  ClaimWebhookDeliveryFn,
+  GetIntegrationConnectionByIdFn,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+  StoredWebhookRequest,
+  WebhookProcessingResult,
+} from '@shipfox/api-integration-core-dto';
+import {decodeWebhookBody} from '@shipfox/api-integration-core-dto';
+import {
+  slackEventsRequestSchema,
+  slackSlashCommandSchema,
+} from '@shipfox/api-integration-slack-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {config} from '#config.js';
+import {isSlackTimestampWithinReplayWindow, verifySlackSignature} from '#core/signature.js';
+import {handleSlackCommand, handleSlackEvent, type SlackWebhookOutcome} from '#core/webhook.js';
+
+const SIGNATURE_HEADER = 'x-slack-signature';
+const TIMESTAMP_HEADER = 'x-slack-request-timestamp';
+
+export interface CreateSlackWebhookProcessorOptions {
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  claimWebhookDelivery: ClaimWebhookDeliveryFn;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export type SlackWebhookProcessingResult = WebhookProcessingResult;
+
+export interface SlackWebhookProcessor {
+  process(request: StoredWebhookRequest): Promise<WebhookProcessingResult>;
+}
+
+export function createSlackWebhookProcessor(
+  options: CreateSlackWebhookProcessorOptions,
+): SlackWebhookProcessor {
+  return {process: (request) => processSlackWebhookRequest(options, request)};
+}
+
+function processSlackWebhookRequest(
+  options: CreateSlackWebhookProcessorOptions,
+  request: StoredWebhookRequest,
+): Promise<WebhookProcessingResult> {
+  if (request.route_id !== 'slack.event' && request.route_id !== 'slack.command') {
+    throw new Error(`Slack processor cannot process ${request.route_id} requests`);
+  }
+
+  const signature = request.headers[SIGNATURE_HEADER];
+  const timestamp = request.headers[TIMESTAMP_HEADER];
+  if (!signature || !timestamp) {
+    return Promise.resolve({outcome: 'discarded', reason: 'missing_required_input'});
+  }
+
+  const rawBody = decodeWebhookBody(request.body);
+  const receiptTime = new Date(request.received_at).getTime();
+  if (!isSlackTimestampWithinReplayWindow(timestamp, receiptTime)) {
+    return Promise.resolve({outcome: 'discarded', reason: 'stale_at_receipt'});
+  }
+  if (
+    !verifySlackSignature({
+      signingSecret: config.SLACK_SIGNING_SECRET,
+      signature,
+      timestamp,
+      rawBody,
+      now: receiptTime,
+    })
+  ) {
+    return Promise.resolve({outcome: 'discarded', reason: 'invalid_signature'});
+  }
+
+  return request.route_id === 'slack.event'
+    ? processSlackEvent(options, rawBody)
+    : processSlackCommand(options, rawBody);
+}
+
+async function processSlackEvent(
+  options: CreateSlackWebhookProcessorOptions,
+  rawBody: Uint8Array,
+): Promise<WebhookProcessingResult> {
+  let rawPayload: unknown;
+  try {
+    rawPayload = JSON.parse(Buffer.from(rawBody).toString('utf8'));
+  } catch (error) {
+    logger().warn({err: error}, 'slack events payload JSON parse failed');
+    return {outcome: 'discarded', reason: 'malformed_payload'};
+  }
+
+  const event = slackEventsRequestSchema.safeParse(rawPayload);
+  if (!event.success) {
+    logger().warn({issues: event.error.issues}, 'slack events envelope failed schema validation');
+    return {outcome: 'discarded', reason: 'unsupported_event'};
+  }
+  const envelope = event.data;
+  if (envelope.type === 'url_verification') {
+    return {outcome: 'processed', challenge: envelope.challenge};
+  }
+
+  const result = await options.coreDb().transaction(async (tx) =>
+    handleSlackEvent({
+      tx,
+      deliveryId: envelope.event_id,
+      envelope,
+      claimWebhookDelivery: options.claimWebhookDelivery,
+      publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+      recordDeliveryOnly: options.recordDeliveryOnly,
+      getIntegrationConnectionById: options.getIntegrationConnectionById,
+    }),
+  );
+  return toProcessingResult(result.outcome, envelope.event_id);
+}
+
+async function processSlackCommand(
+  options: CreateSlackWebhookProcessorOptions,
+  rawBody: Uint8Array,
+): Promise<WebhookProcessingResult> {
+  const command = slackSlashCommandSchema.safeParse(
+    Object.fromEntries(new URLSearchParams(Buffer.from(rawBody).toString('utf8'))),
+  );
+  if (!command.success) {
+    logger().warn({issues: command.error.issues}, 'slack command failed schema validation');
+    return {outcome: 'discarded', reason: 'unsupported_event'};
+  }
+
+  const result = await options.coreDb().transaction(async (tx) =>
+    handleSlackCommand({
+      tx,
+      deliveryId: command.data.trigger_id,
+      command: command.data,
+      publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+      recordDeliveryOnly: options.recordDeliveryOnly,
+      getIntegrationConnectionById: options.getIntegrationConnectionById,
+    }),
+  );
+  return toProcessingResult(result.outcome, command.data.trigger_id);
+}
+
+function toProcessingResult(
+  outcome: SlackWebhookOutcome,
+  deliveryId: string,
+): WebhookProcessingResult {
+  if (outcome === 'published') return {outcome: 'processed', deliveryId};
+  if (outcome === 'duplicate') return {outcome: 'duplicate', deliveryId};
+  return {
+    outcome: 'discarded',
+    reason: outcome === 'unsupported-event' ? 'unsupported_event' : 'connection_unavailable',
+    deliveryId,
+  };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import {createSlackApiClient, type SlackApiClient} from '#api/client.js';
 import {config} from '#config.js';
 import {SlackAgentToolsProvider} from '#core/agent-tools-provider.js';
 import type {SlackTokenStore} from '#core/tokens.js';
+import {createSlackWebhookProcessor} from '#core/webhook-processor.js';
 import {closeDb, db} from '#db/db.js';
 import {getSlackInstallationByConnectionId} from '#db/installations.js';
 import {migrationsPath} from '#db/migrations.js';
@@ -67,7 +68,7 @@ export {
   SLACK_BOT_SCOPES,
 } from '#core/scopes.js';
 export type {VerifySlackSignatureParams} from '#core/signature.js';
-export {verifySlackSignature} from '#core/signature.js';
+export {isSlackTimestampWithinReplayWindow, verifySlackSignature} from '#core/signature.js';
 export type {SlackInstallStateClaims} from '#core/state.js';
 export {signSlackInstallState, verifySlackInstallState} from '#core/state.js';
 export type {
@@ -85,6 +86,12 @@ export type {
   SlackWebhookOutcome,
 } from '#core/webhook.js';
 export {handleSlackCommand, handleSlackEvent, isSelfAuthoredSlackEvent} from '#core/webhook.js';
+export type {
+  CreateSlackWebhookProcessorOptions,
+  SlackWebhookProcessingResult,
+  SlackWebhookProcessor,
+} from '#core/webhook-processor.js';
+export {createSlackWebhookProcessor} from '#core/webhook-processor.js';
 export type {
   SlackInstallation,
   SlackInstallationStatus,
@@ -147,12 +154,17 @@ export function createSlackIntegrationProvider(
     throw new Error('Slack webhook routes require every core persistence dependency');
   }
   const routes: RouteGroup[] = [];
+  const webhookProcessor =
+    options.routes && hasSlackWebhookRoutesOptions(options.routes)
+      ? createSlackWebhookProcessor(options.routes)
+      : undefined;
   if (options.routes && hasSlackInstallationRoutesOptions(options.routes)) {
     const {
       tokenStore,
       getExistingSlackConnection,
       connectSlackInstallation,
       disconnectSlackInstallation,
+      requireActiveWorkspaceMembership,
     } = options.routes;
     routes.push(
       createSlackIntegrationRoutes({
@@ -162,11 +174,12 @@ export function createSlackIntegrationProvider(
         getExistingSlackConnection,
         connectSlackInstallation,
         disconnectSlackInstallation,
+        ...(requireActiveWorkspaceMembership ? {requireActiveWorkspaceMembership} : {}),
       }),
     );
   }
-  if (options.routes && hasSlackWebhookRoutesOptions(options.routes)) {
-    routes.push(...createSlackWebhookRoutes(options.routes));
+  if (options.routes && hasSlackWebhookRoutesOptions(options.routes) && webhookProcessor) {
+    routes.push(...createSlackWebhookRoutes({...options.routes, processor: webhookProcessor}));
   }
 
   return {
@@ -180,6 +193,9 @@ export function createSlackIntegrationProvider(
     },
     ...options.cleanup,
     routes,
+    webhookProcessors: webhookProcessor
+      ? [{routeIds: ['slack.event', 'slack.command'] as const, processor: webhookProcessor}]
+      : undefined,
   };
 }
 

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

@@ -0,0 +1,25 @@
+import {workspacesInterModuleContract} from '@shipfox/api-workspaces-dto/inter-module';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
+import {ClientError} from '@shipfox/node-fastify';
+import {slackRouteErrorHandler} from './errors.js';
+
+describe('slackRouteErrorHandler workspace access errors', () => {
+  it.each([
+    ['workspace-not-found', 'not-found', 404],
+    ['membership-required', 'forbidden', 403],
+    ['workspace-inactive', 'workspace-inactive', 403],
+  ] as const)('translates %s into %s', (error, code, status) => {
+    const knownError = createInterModuleKnownError(
+      workspacesInterModuleContract.methods.requireActiveMembership,
+      error,
+      {workspaceId: crypto.randomUUID()},
+    );
+
+    expect(() => slackRouteErrorHandler(knownError)).toThrow(ClientError);
+    try {
+      slackRouteErrorHandler(knownError);
+    } catch (result) {
+      expect(result).toMatchObject({code, status});
+    }
+  });
+});

package/src/presentation/routes/errors.ts

@@ -2,6 +2,8 @@ import {
   ConnectionSlugConflictError,
   type IntegrationProviderErrorReason,
 } from '@shipfox/api-integration-core-dto';
+import {workspacesInterModuleContract} from '@shipfox/api-workspaces-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
 import {ClientError} from '@shipfox/node-fastify';
 import {
   SlackAuthorizationScopeMismatchError,
@@ -22,6 +24,24 @@ function providerStatus(reason: IntegrationProviderErrorReason): number {
 }
 
 export function slackRouteErrorHandler(error: unknown): never {
+  if (
+    isInterModuleKnownError(workspacesInterModuleContract.methods.requireActiveMembership, error)
+  ) {
+    if (error.code === 'workspace-not-found')
+      throw new ClientError('Workspace not found', 'not-found', {
+        status: 404,
+        details: {workspace_id: error.details.workspaceId},
+      });
+    if (error.code === 'membership-required')
+      throw new ClientError('Workspace membership required', 'forbidden', {
+        status: 403,
+        details: {workspace_id: error.details.workspaceId},
+      });
+    throw new ClientError('Workspace is inactive', 'workspace-inactive', {
+      status: 403,
+      details: {workspace_id: error.details.workspaceId},
+    });
+  }
   if (error instanceof SlackInstallStateError) {
     throw new ClientError(error.message, 'invalid-slack-install-state', {status: 400});
   }

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

@@ -14,10 +14,7 @@ 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()),
-}));
-
+const requireWorkspaceMembershipMock = vi.fn(() => Promise.resolve());
 let authenticatedMemberships: UserContextMembership[] = [];
 
 const fakeUserAuth: AuthMethod = {
@@ -105,6 +102,7 @@ async function createTestApp(
           Promise.resolve(connection({workspaceId: input.workspaceId})),
         ),
       disconnectSlackInstallation: vi.fn(() => Promise.resolve()),
+      requireActiveWorkspaceMembership: requireWorkspaceMembershipMock,
     },
   });
   const app = await createApp({auth: [fakeUserAuth], routes: provider.routes, swagger: false});