@shipfox/api-integration-sentry 2.0.0

package/src/core/signature.ts

@@ -0,0 +1,11 @@
+import {verifyHexHmacSignature} from '@shipfox/node-fastify';
+
+export interface VerifySentrySignatureParams {
+  rawBody: string;
+  signature: string;
+  secret: string;
+}
+
+export function verifySentrySignature(params: VerifySentrySignatureParams): boolean {
+  return verifyHexHmacSignature(params);
+}

package/src/core/webhook.test.ts

@@ -0,0 +1,118 @@
+import {randomUUID} from 'node:crypto';
+import type {SentryIssueWebhookDto} from '@shipfox/api-integration-sentry-dto';
+import {db} from '#db/db.js';
+import {sentryInstallations} from '#db/schema/installations.js';
+import {sentryInstallationFactory} from '#test/index.js';
+import {
+  SentryConnectionNotFoundError,
+  SentryInstallationDeletedError,
+  SentryInstallationNotFoundError,
+  SentryInstallationUnclaimedError,
+} from './errors.js';
+import {handleSentryIssueEvent, normalizeSentryIssueAction} from './webhook.js';
+
+function issuePayload(installationUuid: string): SentryIssueWebhookDto {
+  return {
+    action: 'created',
+    installation: {uuid: installationUuid},
+    data: {issue: {id: 'issue-1'}},
+  };
+}
+
+describe('handleSentryIssueEvent', () => {
+  beforeEach(async () => {
+    await db().delete(sentryInstallations);
+  });
+
+  test('throws SentryInstallationNotFoundError for an unknown installation', async () => {
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const getIntegrationConnectionById = vi.fn();
+
+    const run = handleSentryIssueEvent({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: issuePayload('unknown-uuid'),
+      publishIntegrationEventReceived,
+      getIntegrationConnectionById,
+    });
+
+    await expect(run).rejects.toBeInstanceOf(SentryInstallationNotFoundError);
+    expect(getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  test('throws SentryInstallationDeletedError for a deleted installation', async () => {
+    const installationUuid = randomUUID();
+    await sentryInstallationFactory.create({installationUuid, status: 'deleted'});
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const getIntegrationConnectionById = vi.fn();
+
+    const run = handleSentryIssueEvent({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: issuePayload(installationUuid),
+      publishIntegrationEventReceived,
+      getIntegrationConnectionById,
+    });
+
+    await expect(run).rejects.toBeInstanceOf(SentryInstallationDeletedError);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  test('throws SentryInstallationUnclaimedError for a verified-but-unclaimed installation', async () => {
+    const installationUuid = randomUUID();
+    await sentryInstallationFactory.create({installationUuid, connectionId: null});
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const getIntegrationConnectionById = vi.fn();
+
+    const run = handleSentryIssueEvent({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: issuePayload(installationUuid),
+      publishIntegrationEventReceived,
+      getIntegrationConnectionById,
+    });
+
+    await expect(run).rejects.toBeInstanceOf(SentryInstallationUnclaimedError);
+    expect(getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  test('throws SentryConnectionNotFoundError when the installation has no connection', async () => {
+    const installationUuid = randomUUID();
+    await sentryInstallationFactory.create({installationUuid});
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const getIntegrationConnectionById = vi.fn(() => Promise.resolve(undefined));
+
+    const run = handleSentryIssueEvent({
+      tx: db(),
+      deliveryId: randomUUID(),
+      payload: issuePayload(installationUuid),
+      publishIntegrationEventReceived,
+      getIntegrationConnectionById,
+    });
+
+    await expect(run).rejects.toBeInstanceOf(SentryConnectionNotFoundError);
+    expect(getIntegrationConnectionById).toHaveBeenCalledTimes(1);
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+});
+
+describe('normalizeSentryIssueAction', () => {
+  test('rewrites a legacy "ignored" action to "archived"', () => {
+    const result = normalizeSentryIssueAction({action: 'ignored', data: {issue: {id: '1'}}});
+
+    expect(result).toMatchObject({action: 'archived', data: {issue: {id: '1'}}});
+  });
+
+  test('leaves a known action untouched', () => {
+    const result = normalizeSentryIssueAction({action: 'resolved'});
+
+    expect(result).toMatchObject({action: 'resolved'});
+  });
+
+  test('passes through a non-object payload unchanged', () => {
+    expect(normalizeSentryIssueAction(null)).toBeNull();
+    expect(normalizeSentryIssueAction('nope')).toBe('nope');
+  });
+});

package/src/core/webhook.ts

@@ -0,0 +1,246 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+  SentryIssuePayload,
+  UpdateIntegrationConnectionLifecycleStatusFn,
+} from '@shipfox/api-integration-core-dto';
+import type {SentryIssueWebhookDto} from '@shipfox/api-integration-sentry-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {SentryApiClient} from '#api/client.js';
+import {
+  SentryConnectionNotFoundError,
+  SentryInstallationDeletedError,
+  SentryInstallationNotFoundError,
+  SentryInstallationUnclaimedError,
+  SentryIntegrationProviderError,
+} from '#core/errors.js';
+import {verifyAndPersistUnclaimedInstallation} from '#core/install.js';
+import {
+  getSentryInstallationByInstallationUuid,
+  markSentryInstallationDeleted,
+  type SentryInstallation,
+} from '#db/installations.js';
+
+const SENTRY_SOURCE = 'sentry';
+const DEFAULT_ISSUE_TITLE = 'Sentry issue';
+const DELETED_STATUS = 'deleted';
+
+export interface HandleSentryIssueEventParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  payload: SentryIssueWebhookDto;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+// Publishes the mapped event for a verified issue delivery. Throws a typed
+// SentryIssueDroppedError subclass when the delivery references state we cannot
+// publish against (unknown/deleted installation, or an install not yet claimed
+// into a workspace); the webhook layer records-and-drops those. Dedup of an
+// already-seen delivery is handled inside publishIntegrationEventReceived.
+export async function handleSentryIssueEvent(params: HandleSentryIssueEventParams): Promise<void> {
+  const installationUuid = params.payload.installation.uuid;
+
+  const installation = await getSentryInstallationByInstallationUuid(installationUuid, {
+    tx: params.tx,
+  });
+  if (!installation) {
+    throw new SentryInstallationNotFoundError(installationUuid);
+  }
+  if (installation.status === DELETED_STATUS) {
+    throw new SentryInstallationDeletedError(installationUuid);
+  }
+  // A verified-but-unclaimed install has no workspace yet, so there is nothing to
+  // publish an event against. This is the pre-claim drop window (counted/logged).
+  if (!installation.connectionId) {
+    throw new SentryInstallationUnclaimedError(installationUuid);
+  }
+
+  const connection = await params.getIntegrationConnectionById(installation.connectionId, {
+    tx: params.tx,
+  });
+  if (!connection) {
+    throw new SentryConnectionNotFoundError(installation.connectionId);
+  }
+
+  await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: SENTRY_SOURCE,
+      source: connection.slug,
+      event: `issue.${params.payload.action}`,
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      connectionName: connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: new Date().toISOString(),
+      payload: normalizeIssuePayload(params.payload),
+    },
+  });
+}
+
+export interface HandleSentryInstallationCreatedParams {
+  deliveryId: string;
+  installationUuid: string;
+  // From the signed payload; the webhook is authoritative so the slug is trusted
+  // without a getInstallation round-trip. The code is the single-use grant.
+  orgSlug: string | undefined;
+  code: string | undefined;
+  sentry: SentryApiClient;
+  verifyInstall: boolean;
+  getSentryInstallation: (input: {
+    installationUuid: string;
+  }) => Promise<SentryInstallation | undefined>;
+  // Persists the verified-unclaimed row and records the delivery in one short
+  // transaction, returning the persisted row.
+  persistUnclaimedAndRecordDelivery: (input: {
+    installationUuid: string;
+    orgSlug: string;
+    codeHash: string;
+    deliveryId: string;
+  }) => Promise<SentryInstallation>;
+  // Records the delivery for dedup without persisting an install (reconcile/no-op,
+  // missing code, or exchange failure → record-and-drop).
+  recordDelivery: (deliveryId: string) => Promise<void>;
+}
+
+/**
+ * The authoritative `installation.created` path. Whichever of webhook or browser
+ * arrives first exchanges the single-use code and persists a verified-unclaimed
+ * row; the other reconciles. Idempotent on the installation uuid. The exchange
+ * runs outside any DB transaction; a short transaction wraps only persist +
+ * delivery record. On an exchange failure the delivery is record-and-dropped
+ * (204) — the browser may still win, or the code expired. Never logs the raw code.
+ */
+export async function handleSentryInstallationCreated(
+  params: HandleSentryInstallationCreatedParams,
+): Promise<void> {
+  const existing = await params.getSentryInstallation({installationUuid: params.installationUuid});
+  if (existing) {
+    logger().debug(
+      {deliveryId: params.deliveryId, installationUuid: params.installationUuid},
+      'sentry webhook: installation.created for an existing row, reconciling',
+    );
+    await params.recordDelivery(params.deliveryId);
+    return;
+  }
+
+  if (!params.code) {
+    logger().warn(
+      {deliveryId: params.deliveryId, installationUuid: params.installationUuid},
+      'sentry webhook: installation.created without an authorization code, dropping',
+    );
+    await params.recordDelivery(params.deliveryId);
+    return;
+  }
+
+  try {
+    await verifyAndPersistUnclaimedInstallation({
+      sentry: params.sentry,
+      installationUuid: params.installationUuid,
+      code: params.code,
+      orgSlug: params.orgSlug,
+      verifyInstall: params.verifyInstall,
+      persistVerifiedUnclaimedInstallation: ({installationUuid, orgSlug, codeHash}) =>
+        params.persistUnclaimedAndRecordDelivery({
+          installationUuid,
+          orgSlug,
+          codeHash,
+          deliveryId: params.deliveryId,
+        }),
+    });
+  } catch (error) {
+    if (error instanceof SentryIntegrationProviderError) {
+      // The Sentry exchange (or org-slug lookup) failed, so we never durably
+      // spent the code on a row we own. `reason` distinguishes a transient/expected
+      // drop (access-denied: the code was already spent, e.g. the browser won) from
+      // a likely misconfiguration (a bad client id/secret/slug fails every install)
+      // so log-based alerting can fire on the sustained case. Never logs the raw code.
+      logger().warn(
+        {
+          deliveryId: params.deliveryId,
+          installationUuid: params.installationUuid,
+          reason: error.reason,
+          err: error,
+        },
+        'sentry webhook: installation.created exchange failed, dropping',
+      );
+    } else {
+      // The exchange succeeded (the single-use code is now spent) but the persist
+      // transaction failed, so no row exists and Sentry will not usefully
+      // re-deliver — the install is stranded until a reinstall mints a fresh uuid.
+      // Log at error so alerting catches it; still record-and-drop because retrying
+      // a spent code cannot recover the row. Never logs the raw code.
+      logger().error(
+        {deliveryId: params.deliveryId, installationUuid: params.installationUuid, err: error},
+        'sentry webhook: installation.created persisted nothing after a successful exchange, install stranded until reinstall',
+      );
+    }
+    await params.recordDelivery(params.deliveryId);
+  }
+}
+
+export interface HandleSentryInstallationDeletedParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  installationUuid: string;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  updateConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+}
+
+// Tombstones the install and disables its connection if one exists. An unknown
+// uuid (never installed, or reinstall mints a fresh uuid) only records the
+// delivery: there is no tombstone row to write. Runs entirely in the caller's
+// transaction — no exchange is needed.
+export async function handleSentryInstallationDeleted(
+  params: HandleSentryInstallationDeletedParams,
+): Promise<void> {
+  const installation = await markSentryInstallationDeleted(
+    {installationUuid: params.installationUuid},
+    {tx: params.tx},
+  );
+  if (installation?.connectionId) {
+    await params.updateConnectionLifecycleStatus(
+      {id: installation.connectionId, lifecycleStatus: 'disabled'},
+      {tx: params.tx},
+    );
+  }
+
+  await params.recordDeliveryOnly({
+    tx: params.tx,
+    provider: SENTRY_SOURCE,
+    deliveryId: params.deliveryId,
+  });
+}
+
+// A raw Sentry `ignored` action is normalized to `archived` before validation,
+// so legacy ignore events still fire `issue.archived` workflows.
+export function normalizeSentryIssueAction(parsedJson: unknown): unknown {
+  if (typeof parsedJson !== 'object' || parsedJson === null) return parsedJson;
+  const obj = parsedJson as {action?: unknown};
+  if (obj.action === 'ignored') {
+    return {...obj, action: 'archived'};
+  }
+  return parsedJson;
+}
+
+function normalizeIssuePayload(payload: SentryIssueWebhookDto): SentryIssuePayload {
+  const issue = payload.data.issue;
+  return {
+    action: payload.action,
+    issueId: issue.id,
+    shortId: issue.shortId ?? null,
+    title: issue.title ?? DEFAULT_ISSUE_TITLE,
+    culprit: issue.culprit ?? null,
+    level: issue.level ?? null,
+    status: issue.status ?? null,
+    platform: issue.platform ?? null,
+    webUrl: issue.web_url ?? null,
+    issueUrl: issue.url ?? null,
+    projectUrl: issue.project_url ?? null,
+    firstSeenAt: issue.firstSeen ?? null,
+    lastSeenAt: issue.lastSeen ?? null,
+  };
+}

package/src/db/db.ts

@@ -0,0 +1,18 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {sentryInstallations} from './schema/installations.js';
+
+export const schema = {
+  sentryInstallations,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/installations.test.ts

@@ -0,0 +1,224 @@
+import {randomUUID} from 'node:crypto';
+import {SentryInstallationAlreadyLinkedError} from '#core/errors.js';
+import {db} from './db.js';
+import {
+  getSentryInstallationByInstallationUuid,
+  listUnclaimedSentryInstallations,
+  markSentryInstallationDeleted,
+  persistVerifiedUnclaimedInstallation,
+  pruneUnclaimedSentryInstallations,
+  upsertSentryInstallation,
+} from './installations.js';
+import {sentryInstallations} from './schema/installations.js';
+
+describe('sentry installations persistence', () => {
+  beforeEach(async () => {
+    await db().delete(sentryInstallations);
+  });
+
+  test('upsert updates in place when the same connection reconnects, without duplicating', async () => {
+    const installationUuid = randomUUID();
+    const connectionId = randomUUID();
+
+    await upsertSentryInstallation({
+      connectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+    const updated = await upsertSentryInstallation({
+      connectionId,
+      installationUuid,
+      orgSlug: 'acme-renamed',
+      status: 'installed',
+    });
+
+    expect(updated.connectionId).toBe(connectionId);
+    expect(updated.orgSlug).toBe('acme-renamed');
+    const fetched = await getSentryInstallationByInstallationUuid(installationUuid);
+    expect(fetched?.orgSlug).toBe('acme-renamed');
+  });
+
+  test('upsert rejects repointing an installation to a different connection (TOCTOU guard)', async () => {
+    const installationUuid = randomUUID();
+    const firstConnectionId = randomUUID();
+    const secondConnectionId = randomUUID();
+    await upsertSentryInstallation({
+      connectionId: firstConnectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+
+    const repoint = upsertSentryInstallation({
+      connectionId: secondConnectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+
+    await expect(repoint).rejects.toBeInstanceOf(SentryInstallationAlreadyLinkedError);
+    const fetched = await getSentryInstallationByInstallationUuid(installationUuid);
+    expect(fetched?.connectionId).toBe(firstConnectionId);
+  });
+
+  test('upsert claims a verified-unclaimed row by setting connection_id (first claim)', async () => {
+    const installationUuid = randomUUID();
+    const connectionId = randomUUID();
+    await persistVerifiedUnclaimedInstallation({
+      installationUuid,
+      orgSlug: 'acme',
+      codeHash: 'webhook-hash',
+    });
+
+    const claimed = await upsertSentryInstallation({
+      connectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+
+    expect(claimed.connectionId).toBe(connectionId);
+    const fetched = await getSentryInstallationByInstallationUuid(installationUuid);
+    expect(fetched?.connectionId).toBe(connectionId);
+  });
+
+  test('markSentryInstallationDeleted sets status and returns the updated row', async () => {
+    const installationUuid = randomUUID();
+    const connectionId = randomUUID();
+    await upsertSentryInstallation({
+      connectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+
+    const deleted = await markSentryInstallationDeleted({installationUuid});
+
+    expect(deleted?.status).toBe('deleted');
+    expect(deleted?.connectionId).toBe(connectionId);
+  });
+
+  test('markSentryInstallationDeleted returns undefined when no row matches', async () => {
+    const result = await markSentryInstallationDeleted({installationUuid: 'never-installed'});
+
+    expect(result).toBeUndefined();
+  });
+
+  test('getSentryInstallationByInstallationUuid returns undefined for a miss', async () => {
+    const result = await getSentryInstallationByInstallationUuid('missing');
+
+    expect(result).toBeUndefined();
+  });
+
+  test('persistVerifiedUnclaimedInstallation inserts an unclaimed row with a code hash', async () => {
+    const installationUuid = randomUUID();
+
+    const persisted = await persistVerifiedUnclaimedInstallation({
+      installationUuid,
+      orgSlug: 'acme',
+      codeHash: 'hash-1',
+    });
+
+    expect(persisted.connectionId).toBeNull();
+    expect(persisted.status).toBe('installed');
+    expect(persisted.codeHash).toBe('hash-1');
+  });
+
+  test('persistVerifiedUnclaimedInstallation never clobbers a claimed connection or downgrades status', async () => {
+    const installationUuid = randomUUID();
+    const connectionId = randomUUID();
+    await upsertSentryInstallation({
+      connectionId,
+      installationUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+      codeHash: 'claimed-hash',
+    });
+
+    const reconciled = await persistVerifiedUnclaimedInstallation({
+      installationUuid,
+      orgSlug: 'acme-renamed',
+      codeHash: 'webhook-hash',
+    });
+
+    // A late webhook refreshes the slug/hash but leaves the claim intact.
+    expect(reconciled.connectionId).toBe(connectionId);
+    expect(reconciled.status).toBe('installed');
+    expect(reconciled.orgSlug).toBe('acme-renamed');
+    expect(reconciled.codeHash).toBe('webhook-hash');
+  });
+
+  test('listUnclaimedSentryInstallations returns only rows with no connection', async () => {
+    const claimedUuid = randomUUID();
+    const unclaimedUuid = randomUUID();
+    await upsertSentryInstallation({
+      connectionId: randomUUID(),
+      installationUuid: claimedUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+    await persistVerifiedUnclaimedInstallation({
+      installationUuid: unclaimedUuid,
+      orgSlug: 'acme',
+      codeHash: 'hash',
+    });
+
+    const unclaimed = await listUnclaimedSentryInstallations();
+
+    expect(unclaimed.map((row) => row.installationUuid)).toEqual([unclaimedUuid]);
+  });
+
+  test('listUnclaimedSentryInstallations filters by age when olderThan is given', async () => {
+    const unclaimedUuid = randomUUID();
+    await persistVerifiedUnclaimedInstallation({
+      installationUuid: unclaimedUuid,
+      orgSlug: 'acme',
+      codeHash: 'hash',
+    });
+
+    const future = new Date(Date.now() + 60_000);
+    const past = new Date(Date.now() - 60_000);
+
+    expect(await listUnclaimedSentryInstallations({olderThan: future})).toHaveLength(1);
+    expect(await listUnclaimedSentryInstallations({olderThan: past})).toHaveLength(0);
+  });
+
+  test('pruneUnclaimedSentryInstallations tombstones stale unclaimed rows and leaves fresh ones', async () => {
+    const staleUuid = randomUUID();
+    await persistVerifiedUnclaimedInstallation({
+      installationUuid: staleUuid,
+      orgSlug: 'acme',
+      codeHash: 'hash',
+    });
+
+    const youngResult = await pruneUnclaimedSentryInstallations({
+      olderThan: new Date(Date.now() - 60_000),
+    });
+    expect(youngResult.tombstoned).toBe(0);
+
+    const staleResult = await pruneUnclaimedSentryInstallations({
+      olderThan: new Date(Date.now() + 60_000),
+    });
+    expect(staleResult.tombstoned).toBe(1);
+    expect((await getSentryInstallationByInstallationUuid(staleUuid))?.status).toBe('deleted');
+    expect(await listUnclaimedSentryInstallations()).toHaveLength(0);
+  });
+
+  test('pruneUnclaimedSentryInstallations never tombstones a claimed install', async () => {
+    const claimedUuid = randomUUID();
+    await upsertSentryInstallation({
+      connectionId: randomUUID(),
+      installationUuid: claimedUuid,
+      orgSlug: 'acme',
+      status: 'installed',
+    });
+
+    const result = await pruneUnclaimedSentryInstallations({
+      olderThan: new Date(Date.now() + 60_000),
+    });
+
+    expect(result.tombstoned).toBe(0);
+    expect((await getSentryInstallationByInstallationUuid(claimedUuid))?.status).toBe('installed');
+  });
+});