@shipfox/api-integration-slack 4.0.0

package/src/core/install.ts

@@ -0,0 +1,137 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {SlackApiClient} from '#api/client.js';
+import type {SlackTokenStore} from '#core/tokens.js';
+import {
+  SlackInstallationAlreadyLinkedError,
+  SlackInstallStateActorMismatchError,
+  SlackOAuthCallbackError,
+} from './errors.js';
+import {assertSlackAuthorizationScopes} from './scopes.js';
+import {verifySlackInstallState} from './state.js';
+
+export interface ConnectSlackInstallationInput {
+  workspaceId: string;
+  teamId: string;
+  teamName: string;
+  appId: string;
+  botUserId: string;
+  scopes: string[];
+  tokenExpiresAt: Date | null;
+  displayName: string;
+}
+
+export interface HandleSlackCallbackParams {
+  slack: SlackApiClient;
+  tokenStore: Pick<SlackTokenStore, 'storeTokens'>;
+  code: string;
+  state: string;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership: (params: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }) => Promise<unknown>;
+  getExistingSlackConnection: (input: {
+    teamId: string;
+  }) => Promise<IntegrationConnection<'slack'> | undefined>;
+  connectSlackInstallation: (
+    input: ConnectSlackInstallationInput,
+  ) => Promise<IntegrationConnection<'slack'>>;
+  disconnectSlackInstallation: (input: {connectionId: string}) => Promise<void>;
+}
+
+export async function handleSlackCallback(
+  params: HandleSlackCallbackParams,
+): Promise<IntegrationConnection<'slack'>> {
+  const claims = verifySlackInstallState(params.state);
+  if (claims.userId !== params.sessionUserId) throw new SlackInstallStateActorMismatchError();
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+
+  const authorization = await params.slack.exchangeAuthorizationCode({code: params.code});
+  let connectedConnectionId: string | undefined;
+  let shouldDisconnectConnection = false;
+  let shouldRevokeToken = false;
+  try {
+    const existing = await params.getExistingSlackConnection({teamId: authorization.teamId});
+    if (existing && existing.workspaceId !== claims.workspaceId) {
+      throw new SlackInstallationAlreadyLinkedError(authorization.teamId);
+    }
+    shouldRevokeToken = !existing;
+    assertSlackAuthorizationScopes(authorization.scopes);
+    const connection = await params.connectSlackInstallation({
+      workspaceId: claims.workspaceId,
+      teamId: authorization.teamId,
+      teamName: authorization.teamName,
+      appId: authorization.appId,
+      botUserId: authorization.botUserId,
+      scopes: authorization.scopes,
+      tokenExpiresAt: null,
+      displayName: `Slack ${authorization.teamName}`,
+    });
+    connectedConnectionId = connection.id;
+    shouldDisconnectConnection = !existing;
+    await params.tokenStore.storeTokens({
+      connectionId: connection.id,
+      botToken: authorization.accessToken,
+      editedBy: claims.userId,
+    });
+    return connection;
+  } catch (error) {
+    if (shouldRevokeToken) await bestEffortRevokeToken(params.slack, authorization.accessToken);
+    if (connectedConnectionId && shouldDisconnectConnection) {
+      await bestEffortDisconnectSlackInstallation(params, connectedConnectionId);
+    }
+    throw error;
+  }
+}
+
+export async function handleSlackOAuthCallbackError(params: {
+  state: string;
+  error: string;
+  errorDescription?: string | undefined;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership: (input: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }) => Promise<unknown>;
+}): Promise<never> {
+  const claims = verifySlackInstallState(params.state);
+  if (claims.userId !== params.sessionUserId) throw new SlackInstallStateActorMismatchError();
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+  throw new SlackOAuthCallbackError(params.error, params.errorDescription);
+}
+
+async function bestEffortRevokeToken(slack: SlackApiClient, token: string): Promise<void> {
+  try {
+    await slack.revokeToken({token});
+  } catch (error) {
+    logger().warn({err: error}, 'Slack OAuth token revocation failed');
+  }
+}
+
+async function bestEffortDisconnectSlackInstallation(
+  params: HandleSlackCallbackParams,
+  connectionId: string,
+): Promise<void> {
+  try {
+    await params.disconnectSlackInstallation({connectionId});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Slack connect compensation failed after token storage rejection',
+    );
+  }
+}

package/src/core/scopes.test.ts

@@ -0,0 +1,22 @@
+import {SlackAuthorizationScopeMismatchError} from './errors.js';
+import {assertSlackAuthorizationScopes, formatSlackBotScopes, SLACK_BOT_SCOPES} from './scopes.js';
+
+describe('Slack bot scopes', () => {
+  it('formats and accepts the complete required scope set', () => {
+    const result = () => assertSlackAuthorizationScopes([...SLACK_BOT_SCOPES]);
+
+    expect(formatSlackBotScopes()).toBe(SLACK_BOT_SCOPES.join(','));
+    expect(result).not.toThrow();
+  });
+
+  it('reports every missing scope', () => {
+    const result = () => assertSlackAuthorizationScopes(['chat:write']);
+
+    expect(result).toThrow(SlackAuthorizationScopeMismatchError);
+    try {
+      result();
+    } catch (error) {
+      expect(error).toMatchObject({missingScopes: expect.arrayContaining(['app_mentions:read'])});
+    }
+  });
+});

package/src/core/scopes.ts

@@ -0,0 +1,25 @@
+import {SlackAuthorizationScopeMismatchError} from './errors.js';
+
+export const SLACK_BOT_SCOPES = Object.freeze([
+  'app_mentions:read',
+  'im:history',
+  'chat:write',
+  'channels:history',
+  'groups:history',
+  'channels:read',
+  'groups:read',
+  'users:read',
+  'reactions:read',
+  'reactions:write',
+  'commands',
+]);
+
+export function formatSlackBotScopes(scopes = SLACK_BOT_SCOPES): string {
+  return scopes.join(',');
+}
+
+export function assertSlackAuthorizationScopes(scopes: string[]): void {
+  const grantedScopes = new Set(scopes);
+  const missingScopes = SLACK_BOT_SCOPES.filter((scope) => !grantedScopes.has(scope));
+  if (missingScopes.length > 0) throw new SlackAuthorizationScopeMismatchError(missingScopes);
+}

package/src/core/signature.test.ts

@@ -0,0 +1,45 @@
+import {createHmac} from 'node:crypto';
+import {verifySlackSignature} from './signature.js';
+
+const secret = 'test-signing-secret';
+const timestamp = '1721300000';
+const rawBody = '{"type":"event_callback"}';
+const now = Number(timestamp) * 1000;
+
+function signature(body = rawBody): string {
+  return `v0=${createHmac('sha256', secret).update(`v0:${timestamp}:${body}`).digest('hex')}`;
+}
+
+describe('verifySlackSignature', () => {
+  it('accepts a valid current Slack v0 signature', () => {
+    const result = verifySlackSignature({
+      signingSecret: secret,
+      signature: signature(),
+      timestamp,
+      rawBody,
+      now,
+    });
+
+    expect(result).toBe(true);
+  });
+
+  it.each([
+    ['a tampered body', {rawBody: '{"type":"tampered"}'}],
+    ['a missing signature', {signature: undefined}],
+    ['an empty signing secret', {signingSecret: ''}],
+    ['a missing timestamp', {timestamp: undefined}],
+    ['a malformed timestamp', {timestamp: 'not-a-timestamp'}],
+    ['a stale timestamp', {now: now + 300_001}],
+  ])('rejects %s', (_description, overrides) => {
+    const result = verifySlackSignature({
+      signingSecret: secret,
+      signature: signature(),
+      timestamp,
+      rawBody,
+      now,
+      ...overrides,
+    });
+
+    expect(result).toBe(false);
+  });
+});

package/src/core/signature.ts

@@ -0,0 +1,41 @@
+import {createHmac, timingSafeEqual} from 'node:crypto';
+
+const unixTimestampPattern = /^\d+$/;
+
+export interface VerifySlackSignatureParams {
+  signingSecret: string;
+  signature: string | undefined;
+  timestamp: string | undefined;
+  rawBody: string;
+  now?: number | undefined;
+  replayWindowMs?: number | undefined;
+}
+
+export function verifySlackSignature({
+  signingSecret,
+  signature,
+  timestamp,
+  rawBody,
+  now = Date.now(),
+  replayWindowMs = 300_000,
+}: VerifySlackSignatureParams): boolean {
+  if (!signingSecret || !signature || !timestamp || !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;
+  if (Math.abs(now - timestampMilliseconds) > replayWindowMs) return false;
+
+  const expected = `v0=${createHmac('sha256', signingSecret)
+    .update(`v0:${timestamp}:${rawBody}`)
+    .digest('hex')}`;
+  const expectedBuffer = Buffer.from(expected, 'utf8');
+  const receivedBuffer = Buffer.from(signature, 'utf8');
+  return (
+    expectedBuffer.length === receivedBuffer.length &&
+    timingSafeEqual(expectedBuffer, receivedBuffer)
+  );
+}

package/src/core/state.test.ts

@@ -0,0 +1,48 @@
+import {createHmac} from 'node:crypto';
+import {SlackInstallStateError} from './errors.js';
+import {signSlackInstallState, verifySlackInstallState} from './state.js';
+
+describe('Slack install state', () => {
+  it('round-trips signed workspace and user claims', () => {
+    const state = signSlackInstallState({
+      workspaceId: 'workspace-1',
+      userId: 'user-1',
+      nonce: 'nonce-1',
+      now: new Date('2026-07-07T12:00:00.000Z'),
+    });
+
+    const result = verifySlackInstallState(state, new Date('2026-07-07T12:05:00.000Z'));
+
+    expect(result).toEqual({workspaceId: 'workspace-1', userId: 'user-1'});
+  });
+
+  it.each(['tampered signature', 'expired state'])('rejects a %s', (kind) => {
+    const state = signSlackInstallState({
+      workspaceId: 'workspace-1',
+      userId: 'user-1',
+      nonce: 'nonce-1',
+      now: new Date('2026-07-07T12:00:00.000Z'),
+    });
+    const [payload] = state.split('.');
+    const input = kind === 'tampered signature' ? `${payload}.tampered` : state;
+    const now =
+      kind === 'expired state'
+        ? new Date('2026-07-07T12:31:00.000Z')
+        : new Date('2026-07-07T12:05:00.000Z');
+
+    const result = () => verifySlackInstallState(input, now);
+
+    expect(result).toThrow(SlackInstallStateError);
+  });
+
+  it('rejects a validly signed malformed payload', () => {
+    const payload = Buffer.from('not-json').toString('base64url');
+    const signature = createHmac('sha256', 'test-client-secret')
+      .update(payload)
+      .digest('base64url');
+
+    const result = () => verifySlackInstallState(`${payload}.${signature}`);
+
+    expect(result).toThrow('Invalid Slack install state payload');
+  });
+});

package/src/core/state.ts

@@ -0,0 +1,82 @@
+import {createHmac, randomUUID, timingSafeEqual} from 'node:crypto';
+import {config} from '#config.js';
+import {SlackInstallStateError} from './errors.js';
+
+const STATE_TTL_SECONDS = 30 * 60;
+
+interface SlackInstallStatePayload {
+  workspaceId: string;
+  userId: string;
+  nonce: string;
+  expiresAt: number;
+}
+
+export interface SlackInstallStateClaims {
+  workspaceId: string;
+  userId: string;
+}
+
+export function signSlackInstallState(params: {
+  workspaceId: string;
+  userId: string;
+  nonce?: string | undefined;
+  now?: Date | undefined;
+}): string {
+  const now = params.now ?? new Date();
+  const payload: SlackInstallStatePayload = {
+    workspaceId: params.workspaceId,
+    userId: params.userId,
+    nonce: params.nonce ?? randomUUID(),
+    expiresAt: Math.floor(now.getTime() / 1000) + STATE_TTL_SECONDS,
+  };
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${encodedPayload}.${sign(encodedPayload)}`;
+}
+
+export function verifySlackInstallState(
+  state: string,
+  now: Date = new Date(),
+): SlackInstallStateClaims {
+  const [encodedPayload, signature, extra] = state.split('.');
+  if (!encodedPayload || !signature || extra !== undefined) {
+    throw new SlackInstallStateError('Invalid Slack install state');
+  }
+  if (!constantTimeEqual(signature, sign(encodedPayload))) {
+    throw new SlackInstallStateError('Invalid Slack install state signature');
+  }
+  const payload = parsePayload(encodedPayload);
+  if (payload.expiresAt < Math.floor(now.getTime() / 1000)) {
+    throw new SlackInstallStateError('Expired Slack install state');
+  }
+  return {workspaceId: payload.workspaceId, userId: payload.userId};
+}
+
+function sign(encodedPayload: string): string {
+  return createHmac('sha256', config.SLACK_OAUTH_CLIENT_SECRET)
+    .update(encodedPayload)
+    .digest('base64url');
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+function parsePayload(encodedPayload: string): SlackInstallStatePayload {
+  try {
+    const parsed = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf8'));
+    if (
+      typeof parsed.workspaceId !== 'string' ||
+      typeof parsed.userId !== 'string' ||
+      typeof parsed.nonce !== 'string' ||
+      typeof parsed.expiresAt !== 'number'
+    ) {
+      throw new Error('Invalid payload shape');
+    }
+    return parsed;
+  } catch (_error) {
+    throw new SlackInstallStateError('Invalid Slack install state payload');
+  }
+}

package/src/core/tokens.test.ts

@@ -0,0 +1,163 @@
+import {SlackBotTokenMissingError, SlackConnectionNotFoundError} from '#core/errors.js';
+import {upsertSlackInstallation} from '#db/installations.js';
+import {
+  createSlackTokenStore,
+  type SlackConnectionResolverResult,
+  type SlackSecretsStore,
+  slackSecretsNamespace,
+} from './tokens.js';
+
+let slackSecrets: SlackSecretsStore;
+
+beforeAll(async () => {
+  slackSecrets = await import('@shipfox/api-secrets');
+});
+
+function createConnectionContext() {
+  const workspaceId = crypto.randomUUID();
+  const connectionId = crypto.randomUUID();
+  const resolveConnection = vi
+    .fn<(connectionId: string) => Promise<SlackConnectionResolverResult | undefined>>()
+    .mockResolvedValue({workspaceId});
+  const getSecret = vi.fn<SlackSecretsStore['getSecret']>((params) =>
+    slackSecrets.getSecret(params),
+  );
+  const secrets = {getSecret, setSecrets: slackSecrets.setSecrets};
+  const store = createSlackTokenStore({resolveConnection, secrets});
+
+  return {workspaceId, connectionId, getSecret, resolveConnection, store};
+}
+
+async function arrangeSlackInstallation({
+  connectionId,
+  status = 'installed',
+  tokenExpiresAt = null,
+}: {
+  connectionId: string;
+  status?: 'installed' | 'revoked';
+  tokenExpiresAt?: Date | null;
+}): Promise<void> {
+  await upsertSlackInstallation({
+    connectionId,
+    teamId: `T${crypto.randomUUID()}`,
+    teamName: 'Acme',
+    appId: 'A123',
+    botUserId: 'U123',
+    scopes: ['app_mentions:read'],
+    status,
+    tokenExpiresAt,
+  });
+}
+
+describe('createSlackTokenStore', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('stores and reads a bot token in the Slack system namespace', async () => {
+    const {workspaceId, connectionId, store} = createConnectionContext();
+
+    await store.storeTokens({
+      connectionId,
+      botToken: 'xoxb-test-token',
+      editedBy: crypto.randomUUID(),
+    });
+    await arrangeSlackInstallation({connectionId});
+
+    const result = await store.getAccessToken({connectionId});
+
+    await expect(
+      slackSecrets.getSecret({
+        workspaceId,
+        namespace: slackSecretsNamespace(connectionId),
+        key: 'BOT_TOKEN',
+      }),
+    ).resolves.toBe('xoxb-test-token');
+    expect(result).toBe('xoxb-test-token');
+  });
+
+  it('reads an installed bot token with a future expiry', async () => {
+    const {connectionId, store} = createConnectionContext();
+    await store.storeTokens({connectionId, botToken: 'xoxb-test-token'});
+    await arrangeSlackInstallation({
+      connectionId,
+      tokenExpiresAt: new Date(Date.now() + 60_000),
+    });
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('xoxb-test-token');
+  });
+
+  it('rejects a token whose expiry is exactly now', async () => {
+    vi.useFakeTimers();
+    const now = new Date('2026-07-18T15:00:00.000Z');
+    vi.setSystemTime(now);
+    const {connectionId, getSecret, store} = createConnectionContext();
+    await arrangeSlackInstallation({connectionId, tokenExpiresAt: now});
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'expired',
+      expiresAt: now,
+    });
+    expect(getSecret).not.toHaveBeenCalled();
+  });
+
+  it('rejects a token whose expiry is in the past', async () => {
+    const {connectionId, getSecret, store} = createConnectionContext();
+    await arrangeSlackInstallation({
+      connectionId,
+      tokenExpiresAt: new Date(Date.now() - 60_000),
+    });
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'expired',
+    });
+    expect(getSecret).not.toHaveBeenCalled();
+  });
+
+  it('rejects a revoked installation before reading the bot token', async () => {
+    const {connectionId, getSecret, store} = createConnectionContext();
+    await arrangeSlackInstallation({connectionId, status: 'revoked'});
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'not-installed',
+    });
+    expect(getSecret).not.toHaveBeenCalled();
+  });
+
+  it('rejects a missing installation before reading the bot token', async () => {
+    const {connectionId, getSecret, store} = createConnectionContext();
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'installation-not-found',
+    });
+    expect(getSecret).not.toHaveBeenCalled();
+  });
+
+  it('throws a typed error when the bot token is missing', async () => {
+    const {connectionId, store} = createConnectionContext();
+    await arrangeSlackInstallation({connectionId});
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(SlackBotTokenMissingError);
+  });
+
+  it('throws a typed error when the connection cannot be resolved', async () => {
+    const {connectionId, resolveConnection, store} = createConnectionContext();
+    resolveConnection.mockResolvedValue(undefined);
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(SlackConnectionNotFoundError);
+  });
+});

package/src/core/tokens.ts

@@ -0,0 +1,98 @@
+import {
+  SlackAccessTokenUnavailableError,
+  SlackBotTokenMissingError,
+  SlackConnectionNotFoundError,
+} from '#core/errors.js';
+import {getSlackInstallationByConnectionId, type SlackInstallation} from '#db/installations.js';
+
+const BOT_TOKEN_KEY = 'BOT_TOKEN';
+
+export interface SlackConnectionResolverResult {
+  workspaceId: string;
+}
+
+export interface SlackSecretsStore {
+  getSecret(params: {workspaceId: string; namespace: string; key: string}): Promise<string | null>;
+  setSecrets(params: {
+    workspaceId: string;
+    namespace: string;
+    values: Record<string, string>;
+    editedBy?: string | null | undefined;
+  }): Promise<void>;
+}
+
+export interface CreateSlackTokenStoreParams {
+  resolveConnection(connectionId: string): Promise<SlackConnectionResolverResult | undefined>;
+  secrets: SlackSecretsStore;
+}
+
+export interface StoreSlackTokensParams {
+  connectionId: string;
+  botToken: string;
+  editedBy?: string | null | undefined;
+}
+
+export interface GetSlackAccessTokenParams {
+  connectionId: string;
+}
+
+export interface SlackTokenStore {
+  storeTokens(params: StoreSlackTokensParams): Promise<void>;
+  getAccessToken(params: GetSlackAccessTokenParams): Promise<string>;
+}
+
+export function slackSecretsNamespace(connectionId: string): string {
+  return `system/integrations/slack/${connectionId}`;
+}
+
+function assertSlackInstallationServesToken(
+  connectionId: string,
+  installation: SlackInstallation | undefined,
+): asserts installation is SlackInstallation {
+  if (!installation) {
+    throw new SlackAccessTokenUnavailableError(connectionId, 'installation-not-found');
+  }
+  if (installation.status !== 'installed') {
+    throw new SlackAccessTokenUnavailableError(connectionId, 'not-installed');
+  }
+  if (installation.tokenExpiresAt !== null && installation.tokenExpiresAt.getTime() <= Date.now()) {
+    throw new SlackAccessTokenUnavailableError(
+      connectionId,
+      'expired',
+      installation.tokenExpiresAt,
+    );
+  }
+}
+
+export function createSlackTokenStore(params: CreateSlackTokenStoreParams): SlackTokenStore {
+  async function resolveWorkspaceId(connectionId: string): Promise<string> {
+    const connection = await params.resolveConnection(connectionId);
+    if (!connection) throw new SlackConnectionNotFoundError(connectionId);
+    return connection.workspaceId;
+  }
+
+  return {
+    async storeTokens(input) {
+      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      await params.secrets.setSecrets({
+        workspaceId,
+        namespace: slackSecretsNamespace(input.connectionId),
+        values: {[BOT_TOKEN_KEY]: input.botToken},
+        editedBy: input.editedBy,
+      });
+    },
+
+    async getAccessToken(input) {
+      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      const installation = await getSlackInstallationByConnectionId(input.connectionId);
+      assertSlackInstallationServesToken(input.connectionId, installation);
+      const token = await params.secrets.getSecret({
+        workspaceId,
+        namespace: slackSecretsNamespace(input.connectionId),
+        key: BOT_TOKEN_KEY,
+      });
+      if (!token) throw new SlackBotTokenMissingError(input.connectionId);
+      return token;
+    },
+  };
+}