@shipfox/api-integration-sentry 2.0.0

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

@@ -0,0 +1,325 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+  type UserContextMembership,
+} from '@shipfox/api-auth-context';
+import {
+  ConnectionSlugConflictError,
+  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 {SentryApiClient} from '#api/client.js';
+import {SentryIntegrationProviderError} from '#core/errors.js';
+import type {ConnectSentryInstallationInput} from '#core/install.js';
+import type {SentryInstallation} from '#db/installations.js';
+import {createSentryIntegrationProvider} from '#index.js';
+
+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 sentryClient(overrides: Partial<SentryApiClient> = {}): SentryApiClient {
+  return {
+    exchangeAuthorizationCode: vi.fn(() =>
+      Promise.resolve({token: 'tok', refreshToken: 'refresh', expiresAt: 'x'}),
+    ),
+    getInstallation: vi.fn(() => Promise.resolve({orgSlug: 'acme'})),
+    verifyInstallation: vi.fn(() => Promise.resolve()),
+    ...overrides,
+  };
+}
+
+function unclaimedInstallation(overrides: Partial<SentryInstallation> = {}): SentryInstallation {
+  return {
+    id: 'row-1',
+    connectionId: null,
+    installationUuid: 'install-uuid-1',
+    orgSlug: 'acme',
+    status: 'installed',
+    codeHash: null,
+    installerUserId: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+interface CreateTestAppOptions {
+  sentry?: SentryApiClient;
+  installation?: SentryInstallation | undefined;
+  existingConnection?: IntegrationConnection<'sentry'> | undefined;
+  connectSentryInstallation?:
+    | ((input: ConnectSentryInstallationInput) => Promise<IntegrationConnection<'sentry'>>)
+    | undefined;
+}
+
+async function createTestApp(options: CreateTestAppOptions = {}): Promise<FastifyInstance> {
+  const provider = createSentryIntegrationProvider({
+    sentry: options.sentry ?? sentryClient(),
+    getSentryInstallation: vi.fn(() => Promise.resolve(options.installation)),
+    getConnectionById: vi.fn(() => Promise.resolve(options.existingConnection)),
+    persistVerifiedUnclaimedInstallation: vi.fn((input) =>
+      Promise.resolve(unclaimedInstallation({...input})),
+    ),
+    connectSentryInstallation:
+      options.connectSentryInstallation ??
+      vi.fn((input) =>
+        Promise.resolve({
+          id: crypto.randomUUID(),
+          workspaceId: input.workspaceId,
+          provider: 'sentry' as const,
+          externalAccountId: input.installationUuid,
+          slug: 'sentry_acme',
+          displayName: input.displayName,
+          lifecycleStatus: 'active' as const,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        }),
+      ),
+    // Webhook receiver dependencies — install/connect tests don't exercise them.
+    coreDb: vi.fn() as never,
+    publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: false})),
+    recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+    getIntegrationConnectionById: vi.fn(() => Promise.resolve(undefined)),
+    updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+  });
+  const app = await createApp({auth: [fakeUserAuth], routes: provider.routes, swagger: false});
+  await app.ready();
+  return app;
+}
+
+function connectPayload(options: {authorize?: boolean} = {}) {
+  const workspaceId = crypto.randomUUID();
+  if (options.authorize !== false) {
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+  }
+  return {
+    workspace_id: workspaceId,
+    code: 'the-code',
+    installation_id: 'install-uuid-1',
+  };
+}
+
+describe('Sentry integration routes', () => {
+  beforeEach(async () => {
+    authenticatedMemberships = [];
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('requires auth for the install URL', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/install',
+      payload: {workspace_id: crypto.randomUUID()},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('returns the external-install URL for a member', async () => {
+    const app = await createTestApp();
+    const workspaceId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/install',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().install_url).toBe(
+      'https://sentry.io/sentry-apps/shipfox-test/external-install/',
+    );
+  });
+
+  it('requires auth for connect', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('connects an installation and returns a connection DTO with no capabilities', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().provider).toBe('sentry');
+    expect(res.json().external_account_id).toBe('install-uuid-1');
+    expect(res.json().display_name).toBe('Sentry acme');
+    expect(res.json().capabilities).toEqual([]);
+  });
+
+  it('returns 403 when the caller is not a workspace member', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload({authorize: false}),
+    });
+
+    expect(res.statusCode).toBe(403);
+  });
+
+  it('returns 409 when the installation is already linked to another workspace', async () => {
+    const connectionId = crypto.randomUUID();
+    const app = await createTestApp({
+      installation: unclaimedInstallation({connectionId}),
+      existingConnection: {
+        id: connectionId,
+        workspaceId: crypto.randomUUID(),
+        provider: 'sentry',
+        externalAccountId: 'install-uuid-1',
+        slug: 'sentry_acme',
+        displayName: 'Sentry acme',
+        lifecycleStatus: 'active',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('sentry-installation-already-linked');
+  });
+
+  it('returns 409 when connection slug allocation conflicts repeatedly', async () => {
+    const app = await createTestApp({
+      connectSentryInstallation: vi.fn(() =>
+        Promise.reject(new ConnectionSlugConflictError(new Error('duplicate slug'))),
+      ),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('slug-conflict');
+  });
+
+  it('maps a non-access-denied provider error to its status', async () => {
+    const app = await createTestApp({
+      sentry: sentryClient({
+        exchangeAuthorizationCode: vi.fn(() =>
+          Promise.reject(new SentryIntegrationProviderError('rate-limited', 'slow down')),
+        ),
+      }),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(429);
+    expect(res.json().code).toBe('rate-limited');
+  });
+
+  it('returns a retryable 503 when a concurrent webhook is still verifying the install', async () => {
+    const app = await createTestApp({
+      sentry: sentryClient({
+        exchangeAuthorizationCode: vi.fn(() =>
+          Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+        ),
+      }),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json().code).toBe('sentry-verification-in-progress');
+  });
+
+  it('returns 403 when the presented code cannot prove control of a verified install', async () => {
+    const app = await createTestApp({
+      installation: unclaimedInstallation({codeHash: 'a-different-hash'}),
+      sentry: sentryClient({
+        exchangeAuthorizationCode: vi.fn(() =>
+          Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+        ),
+      }),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('sentry-claim-proof-mismatch');
+  });
+
+  it('returns 409 when the installation is tombstoned', async () => {
+    const app = await createTestApp({
+      installation: unclaimedInstallation({status: 'deleted'}),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/sentry/connect',
+      headers: {authorization: 'Bearer user'},
+      payload: connectPayload(),
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('sentry-installation-deleted');
+  });
+});

package/src/presentation/routes/install.ts

@@ -0,0 +1,102 @@
+import {AUTH_USER, requireUserContext, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {
+  createSentryInstallBodySchema,
+  createSentryInstallResponseSchema,
+  sentryConnectBodySchema,
+  sentryConnectResponseSchema,
+} from '@shipfox/api-integration-sentry-dto';
+import {defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {SentryApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {type ConnectSentryInstallationInput, handleSentryConnect} from '#core/install.js';
+import type {
+  PersistVerifiedUnclaimedInstallationParams,
+  SentryInstallation,
+} from '#db/installations.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+import {sentryRouteErrorHandler} from './errors.js';
+
+export interface CreateSentryIntegrationRoutesOptions {
+  sentry: SentryApiClient;
+  getSentryInstallation: (input: {
+    installationUuid: string;
+  }) => Promise<SentryInstallation | undefined>;
+  getConnectionById: (id: string) => Promise<IntegrationConnection<'sentry'> | undefined>;
+  connectSentryInstallation: (
+    input: ConnectSentryInstallationInput,
+  ) => Promise<IntegrationConnection<'sentry'>>;
+  persistVerifiedUnclaimedInstallation: (
+    input: PersistVerifiedUnclaimedInstallationParams,
+  ) => Promise<SentryInstallation>;
+}
+
+export function createSentryIntegrationRoutes({
+  sentry,
+  getSentryInstallation,
+  getConnectionById,
+  connectSentryInstallation,
+  persistVerifiedUnclaimedInstallation,
+}: CreateSentryIntegrationRoutesOptions): RouteGroup {
+  const createInstallRoute = defineRoute({
+    method: 'POST',
+    path: '/install',
+    auth: AUTH_USER,
+    description: 'Create a Sentry app external-install URL for a workspace.',
+    schema: {
+      body: createSentryInstallBodySchema,
+      response: {
+        200: createSentryInstallResponseSchema,
+      },
+    },
+    handler: (request) => {
+      const {workspace_id: workspaceId} = request.body;
+
+      requireWorkspaceAccess({request, workspaceId});
+
+      // Sentry has no state param to embed; the server owns the slug.
+      const installUrl = `https://sentry.io/sentry-apps/${config.SENTRY_APP_SLUG}/external-install/`;
+      return {install_url: installUrl};
+    },
+  });
+
+  const connectRoute = defineRoute({
+    method: 'POST',
+    path: '/connect',
+    auth: AUTH_USER,
+    description: 'Link a Sentry installation to a workspace after the install redirect.',
+    schema: {
+      body: sentryConnectBodySchema,
+      response: {
+        200: sentryConnectResponseSchema,
+      },
+    },
+    errorHandler: sentryRouteErrorHandler,
+    handler: async (request) => {
+      const {workspace_id: workspaceId, code, installation_id: installationUuid} = request.body;
+      const actor = requireUserContext(request);
+
+      requireWorkspaceAccess({request, workspaceId});
+
+      const connection = await handleSentryConnect({
+        sentry,
+        workspaceId,
+        code,
+        installationUuid,
+        installerUserId: actor.userId,
+        verifyInstall: config.SENTRY_APP_VERIFY_INSTALL,
+        getSentryInstallation,
+        getConnectionById,
+        connectSentryInstallation,
+        persistVerifiedUnclaimedInstallation,
+      });
+
+      return toIntegrationConnectionDto(connection);
+    },
+  });
+
+  return {
+    prefix: '/integrations/sentry',
+    routes: [createInstallRoute, connectRoute],
+  };
+}

package/src/presentation/routes/installation-handler.ts

@@ -0,0 +1,76 @@
+import {sentryInstallationWebhookSchema} from '@shipfox/api-integration-sentry-dto';
+import type {FastifyReply} from 'fastify';
+import {config} from '#config.js';
+import {handleSentryInstallationCreated, handleSentryInstallationDeleted} from '#core/webhook.js';
+import {
+  getSentryInstallationByInstallationUuid,
+  persistVerifiedUnclaimedInstallation,
+} from '#db/installations.js';
+import type {SentryWebhookContext} from './webhook-context.js';
+import {parseAndValidateOrDrop, SENTRY_PROVIDER} from './webhook-delivery.js';
+
+// Validates an installation lifecycle delivery, then applies it. `created` is the
+// authoritative install signal: it exchanges the single-use code and persists a
+// verified-unclaimed row (exchange outside any transaction; persist + delivery
+// record in one short transaction). `deleted` tombstones the install and disables
+// the connection in a single transaction.
+export async function handleInstallationResource(args: {
+  context: SentryWebhookContext;
+  reply: FastifyReply;
+  deliveryId: string;
+  rawBody: string;
+}): Promise<null> {
+  const {context, reply, deliveryId, rawBody} = args;
+
+  const payload = await parseAndValidateOrDrop({
+    schema: sentryInstallationWebhookSchema,
+    rawBody,
+    deliveryId,
+    context,
+    reply,
+  });
+  if (!payload) return null;
+
+  const installation = payload.data.installation;
+
+  if (payload.action === 'deleted') {
+    await context.coreDb().transaction(async (tx) => {
+      await handleSentryInstallationDeleted({
+        tx,
+        deliveryId,
+        installationUuid: installation.uuid,
+        recordDeliveryOnly: context.recordDeliveryOnly,
+        updateConnectionLifecycleStatus: context.updateConnectionLifecycleStatus,
+      });
+    });
+    reply.code(204);
+    return null;
+  }
+
+  await handleSentryInstallationCreated({
+    deliveryId,
+    installationUuid: installation.uuid,
+    orgSlug: installation.organization?.slug,
+    code: installation.code,
+    sentry: context.sentry,
+    verifyInstall: config.SENTRY_APP_VERIFY_INSTALL,
+    getSentryInstallation: ({installationUuid}) =>
+      getSentryInstallationByInstallationUuid(installationUuid),
+    persistUnclaimedAndRecordDelivery: ({installationUuid, orgSlug, codeHash, deliveryId: id}) =>
+      context.coreDb().transaction(async (tx) => {
+        const persisted = await persistVerifiedUnclaimedInstallation(
+          {installationUuid, orgSlug, codeHash},
+          {tx},
+        );
+        await context.recordDeliveryOnly({tx, provider: SENTRY_PROVIDER, deliveryId: id});
+        return persisted;
+      }),
+    recordDelivery: (id) =>
+      context.coreDb().transaction(async (tx) => {
+        await context.recordDeliveryOnly({tx, provider: SENTRY_PROVIDER, deliveryId: id});
+      }),
+  });
+
+  reply.code(204);
+  return null;
+}

package/src/presentation/routes/issue-handler.ts

@@ -0,0 +1,52 @@
+import {sentryIssueWebhookSchema} from '@shipfox/api-integration-sentry-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {FastifyReply} from 'fastify';
+import {SentryIssueDroppedError} from '#core/errors.js';
+import {handleSentryIssueEvent, normalizeSentryIssueAction} from '#core/webhook.js';
+import type {SentryWebhookContext} from './webhook-context.js';
+import {parseAndValidateOrDrop, recordAndDrop} from './webhook-delivery.js';
+
+// Validates an issue delivery, then publishes the mapped event in a transaction.
+// A malformed or unknown-action payload is recorded-and-dropped (204) before we
+// reach core. Core throws a SentryIssueDroppedError when the delivery references
+// state we cannot publish against (unknown/deleted installation, missing
+// connection); we record-and-drop those too. Any other error bubbles up.
+export async function handleIssueResource(args: {
+  context: SentryWebhookContext;
+  reply: FastifyReply;
+  deliveryId: string;
+  rawBody: string;
+}): Promise<null> {
+  const {context, reply, deliveryId, rawBody} = args;
+
+  const payload = await parseAndValidateOrDrop({
+    schema: sentryIssueWebhookSchema,
+    normalize: normalizeSentryIssueAction,
+    rawBody,
+    deliveryId,
+    context,
+    reply,
+  });
+  if (!payload) return null;
+
+  try {
+    await context.coreDb().transaction(async (tx) => {
+      await handleSentryIssueEvent({
+        tx,
+        deliveryId,
+        payload,
+        publishIntegrationEventReceived: context.publishIntegrationEventReceived,
+        getIntegrationConnectionById: context.getIntegrationConnectionById,
+      });
+    });
+  } catch (error) {
+    if (error instanceof SentryIssueDroppedError) {
+      logger().warn({deliveryId, err: error}, `sentry webhook: ${error.message}, dropping`);
+      return recordAndDrop({context, reply, deliveryId});
+    }
+    throw error;
+  }
+
+  reply.code(204);
+  return null;
+}

package/src/presentation/routes/webhook-context.ts

@@ -0,0 +1,25 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+  UpdateIntegrationConnectionLifecycleStatusFn,
+} from '@shipfox/api-integration-core-dto';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import type {SentryApiClient} from '#api/client.js';
+
+/**
+ * The capabilities a Sentry webhook handler needs from the rest of the system.
+ * `@shipfox/api-integration-core` owns and wires the core persistence in
+ * production; tests fake them with spies. Passing them in keeps the route
+ * decoupled from core's persistence and avoids a package dependency cycle. The
+ * Sentry client is injected too so the authoritative `installation.created` path
+ * can exchange the code, and tests can fake the exchange.
+ */
+export interface SentryWebhookContext {
+  sentry: SentryApiClient;
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  updateConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+}

package/src/presentation/routes/webhook-delivery.ts

@@ -0,0 +1,61 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import type {FastifyReply} from 'fastify';
+import type {z} from 'zod';
+import type {SentryWebhookContext} from './webhook-context.js';
+
+export const SENTRY_PROVIDER = 'sentry';
+
+/**
+ * Parses and validates a delivery body, recording-and-dropping it (HTTP 204) when
+ * the JSON is malformed or fails the schema (an unknown action falls here too).
+ * Returns the validated payload, or null when the delivery was dropped.
+ */
+export async function parseAndValidateOrDrop<TSchema extends z.ZodType>(args: {
+  schema: TSchema;
+  rawBody: string;
+  deliveryId: string;
+  context: SentryWebhookContext;
+  reply: FastifyReply;
+  normalize?: (parsedJson: unknown) => unknown;
+}): Promise<z.infer<TSchema> | null> {
+  const {schema, rawBody, deliveryId, context, reply, normalize} = args;
+
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(rawBody);
+  } catch (error) {
+    logger().warn({deliveryId, err: error}, 'sentry webhook: payload JSON parse failed, dropping');
+    await recordAndDrop({context, reply, deliveryId});
+    return null;
+  }
+
+  const validated = schema.safeParse(normalize ? normalize(parsedJson) : parsedJson);
+  if (!validated.success) {
+    logger().warn(
+      {deliveryId, issues: validated.error.issues},
+      'sentry webhook: payload failed validation (or unknown action), dropping',
+    );
+    await recordAndDrop({context, reply, deliveryId});
+    return null;
+  }
+
+  return validated.data;
+}
+
+/**
+ * Records the delivery for dedup and replies 204 without acting on it. A sustained
+ * non-2xx can degrade or disable the webhook on Sentry's side (a deliberate
+ * deviation from GitHub's 400), so deliveries we cannot use are acknowledged.
+ */
+export async function recordAndDrop(args: {
+  context: SentryWebhookContext;
+  reply: FastifyReply;
+  deliveryId: string;
+}): Promise<null> {
+  const {context, reply, deliveryId} = args;
+  await context.coreDb().transaction(async (tx) => {
+    await context.recordDeliveryOnly({tx, provider: SENTRY_PROVIDER, deliveryId});
+  });
+  reply.code(204);
+  return null;
+}