@shipfox/api-integration-sentry 2.0.0

package/drizzle/0000_initial.sql

@@ -0,0 +1,14 @@
+CREATE TABLE "integrations_sentry_installations" (
+	"id" uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL,
+	"connection_id" uuid,
+	"installation_uuid" text NOT NULL,
+	"org_slug" text NOT NULL,
+	"status" text NOT NULL,
+	"code_hash" text,
+	"installer_user_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "integrations_sentry_installations_connection_unique" ON "integrations_sentry_installations" USING btree ("connection_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "integrations_sentry_installations_installation_unique" ON "integrations_sentry_installations" USING btree ("installation_uuid");

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1777541400000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig} from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './src/db/schema/*.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@shipfox/api-integration-sentry",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/integration/sentry"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@temporalio/workflow": "^1.16.1",
+    "drizzle-orm": "^0.45.2",
+    "ky": "^2.0.0",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/api-integration-core-dto": "2.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/api-integration-sentry-dto": "2.0.0",
+    "@shipfox/node-drizzle": "0.2.1",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/node-postgres": "0.4.1",
+    "@shipfox/node-opentelemetry": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "fastify-type-provider-zod": "^6.0.0",
+    "fishery": "^2.2.2",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/vitest": "1.2.2"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/api/client.test.ts

@@ -0,0 +1,147 @@
+import {HTTPError, TimeoutError} from 'ky';
+import {SentryIntegrationProviderError} from '#core/errors.js';
+import {createSentryApiClient} from './client.js';
+
+const {postMock, getMock, putMock} = vi.hoisted(() => ({
+  postMock: vi.fn(),
+  getMock: vi.fn(),
+  putMock: vi.fn(),
+}));
+
+vi.mock('ky', () => {
+  class HTTPError extends Error {
+    constructor(public response: {status: number; headers: Headers}) {
+      super('http');
+      this.name = 'HTTPError';
+    }
+  }
+  class TimeoutError extends Error {
+    constructor() {
+      super('timeout');
+      this.name = 'TimeoutError';
+    }
+  }
+  return {default: {post: postMock, get: getMock, put: putMock}, HTTPError, TimeoutError};
+});
+
+function resolves(data: unknown) {
+  return {json: () => Promise.resolve(data)};
+}
+
+function rejects(error: unknown) {
+  return {json: () => Promise.reject(error)};
+}
+
+function httpError(status: number, headers: Record<string, string> = {}): HTTPError {
+  return new HTTPError({status, headers: new Headers(headers)} as never, {} as never, {} as never);
+}
+
+describe('createSentryApiClient.exchangeAuthorizationCode', () => {
+  beforeEach(() => {
+    postMock.mockReset();
+    getMock.mockReset();
+    putMock.mockReset();
+  });
+
+  it('returns the token, refresh token, and expiry', async () => {
+    postMock.mockReturnValue(
+      resolves({token: 'tok', refreshToken: 'refresh', expiresAt: '2026-06-11T12:00:00.000Z'}),
+    );
+    const client = createSentryApiClient();
+
+    const result = await client.exchangeAuthorizationCode({
+      installationUuid: 'uuid-1',
+      code: 'the-code',
+    });
+
+    expect(result).toEqual({
+      token: 'tok',
+      refreshToken: 'refresh',
+      expiresAt: '2026-06-11T12:00:00.000Z',
+    });
+  });
+
+  it('maps a 429 to rate-limited with retry-after seconds', async () => {
+    postMock.mockReturnValue(rejects(httpError(429, {'retry-after': '30'})));
+    const client = createSentryApiClient();
+
+    const result = client.exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'c'});
+
+    await expect(result).rejects.toMatchObject({reason: 'rate-limited', retryAfterSeconds: 30});
+    await expect(result).rejects.toBeInstanceOf(SentryIntegrationProviderError);
+  });
+
+  it('maps a 5xx to provider-unavailable', async () => {
+    postMock.mockReturnValue(rejects(httpError(503)));
+    const client = createSentryApiClient();
+
+    const result = client.exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'c'});
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-unavailable'});
+  });
+
+  it('maps a forged-code 4xx to access-denied', async () => {
+    postMock.mockReturnValue(rejects(httpError(403)));
+    const client = createSentryApiClient();
+
+    const result = client.exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'c'});
+
+    await expect(result).rejects.toMatchObject({reason: 'access-denied'});
+  });
+
+  it('maps a timeout to timeout', async () => {
+    postMock.mockReturnValue(rejects(new TimeoutError({} as never)));
+    const client = createSentryApiClient();
+
+    const result = client.exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'c'});
+
+    await expect(result).rejects.toMatchObject({reason: 'timeout'});
+  });
+
+  it('maps a response without a token to malformed-provider-response', async () => {
+    postMock.mockReturnValue(resolves({refreshToken: 'r', expiresAt: 'x'}));
+    const client = createSentryApiClient();
+
+    const result = client.exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'c'});
+
+    await expect(result).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+
+  it('never leaks the code or client secret into the thrown error', async () => {
+    postMock.mockReturnValue(rejects(httpError(403)));
+    const client = createSentryApiClient();
+
+    const error = await client
+      .exchangeAuthorizationCode({installationUuid: 'uuid-1', code: 'super-secret-code'})
+      .catch((thrown: unknown) => thrown);
+
+    const serialized = `${(error as Error).message} ${JSON.stringify(error)} ${String((error as {cause?: unknown}).cause)}`;
+    expect(serialized).not.toContain('super-secret-code');
+    expect(serialized).not.toContain('test-client-secret');
+    expect((error as {cause?: unknown}).cause).toBeUndefined();
+  });
+});
+
+describe('createSentryApiClient.getInstallation', () => {
+  beforeEach(() => {
+    getMock.mockReset();
+  });
+
+  it('derives the organization slug', async () => {
+    getMock.mockReturnValue(resolves({organization: {slug: 'acme'}}));
+    const client = createSentryApiClient();
+
+    const result = await client.getInstallation({installationUuid: 'uuid-1', token: 'tok'});
+
+    expect(result).toEqual({orgSlug: 'acme'});
+  });
+
+  it('maps a response without an organization slug to malformed-provider-response', async () => {
+    getMock.mockReturnValue(resolves({organization: {}}));
+    const client = createSentryApiClient();
+
+    const result = client.getInstallation({installationUuid: 'uuid-1', token: 'tok'});
+
+    await expect(result).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+});

package/src/api/client.ts

@@ -0,0 +1,147 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import ky, {HTTPError, TimeoutError} from 'ky';
+import {config} from '#config.js';
+import {SentryIntegrationProviderError} from '#core/errors.js';
+
+const SENTRY_API_BASE = 'https://sentry.io/api/0';
+
+export interface SentryAuthorization {
+  token: string;
+  refreshToken: string;
+  expiresAt: string;
+}
+
+export interface SentryInstallationDetails {
+  orgSlug: string;
+}
+
+export interface SentryApiClient {
+  exchangeAuthorizationCode(input: {
+    installationUuid: string;
+    code: string;
+  }): Promise<SentryAuthorization>;
+  // Derived from Sentry so the org slug is never trusted from the client body.
+  getInstallation(input: {
+    installationUuid: string;
+    token: string;
+  }): Promise<SentryInstallationDetails>;
+  verifyInstallation(input: {installationUuid: string; token: string}): Promise<void>;
+}
+
+export function createSentryApiClient(): SentryApiClient {
+  return {
+    async exchangeAuthorizationCode(input) {
+      // Encode the uuid: it originates from the request body / webhook payload, so
+      // a path separator in it must not be able to alter the request path (the host
+      // is already pinned to SENTRY_API_BASE).
+      const body = await mapSentryError('exchange-authorization-code', () =>
+        ky
+          .post(
+            `${SENTRY_API_BASE}/sentry-app-installations/${encodeURIComponent(input.installationUuid)}/authorizations/`,
+            {
+              json: {
+                grant_type: 'authorization_code',
+                client_id: config.SENTRY_APP_CLIENT_ID,
+                client_secret: config.SENTRY_APP_CLIENT_SECRET,
+                code: input.code,
+              },
+            },
+          )
+          .json<{token?: unknown; refreshToken?: unknown; expiresAt?: unknown}>(),
+      );
+
+      if (
+        typeof body.token !== 'string' ||
+        typeof body.refreshToken !== 'string' ||
+        typeof body.expiresAt !== 'string'
+      ) {
+        throw new SentryIntegrationProviderError(
+          'malformed-provider-response',
+          'Sentry authorization response did not include a token',
+        );
+      }
+      return {token: body.token, refreshToken: body.refreshToken, expiresAt: body.expiresAt};
+    },
+
+    async getInstallation(input) {
+      const body = await mapSentryError('get-installation', () =>
+        ky
+          .get(
+            `${SENTRY_API_BASE}/sentry-app-installations/${encodeURIComponent(input.installationUuid)}/`,
+            {
+              headers: {authorization: `Bearer ${input.token}`},
+            },
+          )
+          .json<{organization?: {slug?: unknown}}>(),
+      );
+
+      const slug = body.organization?.slug;
+      if (typeof slug !== 'string' || slug.length === 0) {
+        throw new SentryIntegrationProviderError(
+          'malformed-provider-response',
+          'Sentry installation response did not include an organization slug',
+        );
+      }
+      return {orgSlug: slug};
+    },
+
+    async verifyInstallation(input) {
+      await mapSentryError('verify-installation', () =>
+        ky
+          .put(
+            `${SENTRY_API_BASE}/sentry-app-installations/${encodeURIComponent(input.installationUuid)}/`,
+            {
+              headers: {authorization: `Bearer ${input.token}`},
+              json: {status: 'installed'},
+            },
+          )
+          .json<unknown>(),
+      );
+    },
+  };
+}
+
+// The typed error deliberately drops Sentry's status and body so no token, code,
+// or client secret can leak to the client or the logged error chain. That also
+// strips the one detail a self-hoster needs to fix a misconfigured Sentry app —
+// e.g. a 403 on `get-installation` means the app is missing "Organization: Read"
+// (see README "Required permissions"). So we log the upstream status
+// here, the only place it survives, keyed by the operation that failed.
+async function mapSentryError<T>(operation: string, request: () => Promise<T>): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    if (error instanceof SentryIntegrationProviderError) throw error;
+    if (error instanceof HTTPError) {
+      const {status, statusText, headers} = error.response;
+      logger().warn({operation, status, statusText}, 'Sentry API request rejected');
+      if (status === 429) {
+        throw new SentryIntegrationProviderError(
+          'rate-limited',
+          'Sentry request was rate limited',
+          retryAfterSeconds(headers),
+        );
+      }
+      if (status >= 500) {
+        throw new SentryIntegrationProviderError('provider-unavailable', 'Sentry request failed');
+      }
+      throw new SentryIntegrationProviderError('access-denied', 'Sentry request was rejected');
+    }
+    if (error instanceof TimeoutError) {
+      logger().warn({operation}, 'Sentry API request timed out');
+      throw new SentryIntegrationProviderError('timeout', 'Sentry request timed out');
+    }
+    logger().warn(
+      {operation, errName: error instanceof Error ? error.name : typeof error},
+      'Sentry API request failed',
+    );
+    throw new SentryIntegrationProviderError('provider-unavailable', 'Sentry request failed');
+  }
+}
+
+function retryAfterSeconds(headers: Headers): number | undefined {
+  const retryAfter = headers.get('retry-after');
+  if (!retryAfter) return undefined;
+  const parsed = Number.parseInt(retryAfter, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}

package/src/config.test.ts

@@ -0,0 +1,16 @@
+import {assertRetentionDaysWithinBounds} from './config.js';
+
+describe('assertRetentionDaysWithinBounds', () => {
+  test('accepts a retention window of at least one day', () => {
+    expect(() => assertRetentionDaysWithinBounds(7)).not.toThrow();
+    expect(() => assertRetentionDaysWithinBounds(1)).not.toThrow();
+  });
+
+  test('rejects a zero window that would tombstone freshly created installs', () => {
+    expect(() => assertRetentionDaysWithinBounds(0)).toThrow();
+  });
+
+  test('rejects a negative window that pushes the cutoff into the future', () => {
+    expect(() => assertRetentionDaysWithinBounds(-7)).toThrow();
+  });
+});

package/src/config.ts

@@ -0,0 +1,35 @@
+import {bool, createConfig, num, str} from '@shipfox/config';
+
+export const config = createConfig({
+  SENTRY_APP_CLIENT_ID: str({
+    desc: 'OAuth client ID of the Sentry app. Reserved for the install and app-token-exchange flow; the webhook receiver does not read it yet. Required.',
+  }),
+  SENTRY_APP_CLIENT_SECRET: str({
+    desc: 'Shared secret used to verify the HMAC-SHA256 signature on inbound Sentry webhooks. Must match the value set on the Sentry app. Required.',
+  }),
+  SENTRY_APP_SLUG: str({
+    desc: 'URL slug of the Sentry app, used to build install and callback links. Required.',
+  }),
+  SENTRY_APP_VERIFY_INSTALL: bool({
+    desc: 'Verifies the signature on Sentry app installation requests. Keep it true; turn it off only for local testing.',
+    default: true,
+  }),
+  SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS: num({
+    desc: 'How many days a verified-but-unclaimed Sentry installation may sit before the daily cleanup cron tombstones it. Must be at least 1; a smaller value moves the cutoff to now or the future and would tombstone freshly created, still-unclaimed installs. A reinstall always mints a fresh uuid, so a tombstone is never revived. Defaults to 7.',
+    default: 7,
+  }),
+});
+
+// The daily cleanup cron tombstones every unclaimed install older than
+// `now - SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS`. A value below 1 moves that
+// cutoff to now or the future, which would wipe freshly created installs nobody has
+// claimed yet. Reject it at startup rather than let the 04:00 cron fail silently.
+export function assertRetentionDaysWithinBounds(days: number): void {
+  if (!Number.isFinite(days) || days < 1) {
+    throw new Error(
+      `SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS must be a finite number of at least 1, received ${days}.`,
+    );
+  }
+}
+
+assertRetentionDaysWithinBounds(config.SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS);

package/src/connection-external-url.test.ts

@@ -0,0 +1,79 @@
+import type {SentryApiClient} from '#api/client.js';
+import type {SentryInstallation} from '#db/installations.js';
+import {createSentryIntegrationProvider} from '#index.js';
+
+function sentryClient(): 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()),
+  };
+}
+
+function installation(overrides: Partial<SentryInstallation> = {}): SentryInstallation {
+  return {
+    id: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    installationUuid: 'install-1',
+    orgSlug: 'acme',
+    status: 'installed',
+    codeHash: null,
+    installerUserId: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function createProvider(lookup: (connectionId: string) => Promise<SentryInstallation | undefined>) {
+  return createSentryIntegrationProvider({
+    sentry: sentryClient(),
+    getSentryInstallation: vi.fn(() => Promise.resolve(undefined)),
+    getConnectionById: vi.fn(() => Promise.resolve(undefined)),
+    connectSentryInstallation: vi.fn() as never,
+    persistVerifiedUnclaimedInstallation: vi.fn() as never,
+    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)),
+    getSentryInstallationByConnectionId: lookup,
+  });
+}
+
+describe('sentry connectionExternalUrl', () => {
+  it('resolves the org URL from the installation row', async () => {
+    const connectionId = crypto.randomUUID();
+    const provider = createProvider(() => Promise.resolve(installation({orgSlug: 'acme-corp'})));
+
+    const url = await provider.connectionExternalUrl({id: connectionId});
+
+    expect(url).toBe('https://sentry.io/organizations/acme-corp/');
+  });
+
+  it('URL-encodes the org slug', async () => {
+    const provider = createProvider(() => Promise.resolve(installation({orgSlug: 'a/b c'})));
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBe('https://sentry.io/organizations/a%2Fb%20c/');
+  });
+
+  it('returns undefined when the installation row is missing', async () => {
+    const provider = createProvider(() => Promise.resolve(undefined));
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBeUndefined();
+  });
+
+  it('returns undefined when the org slug is absent', async () => {
+    const provider = createProvider(() => Promise.resolve(installation({orgSlug: ''})));
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBeUndefined();
+  });
+});

package/src/core/errors.ts

@@ -0,0 +1,81 @@
+import {IntegrationProviderError} from '@shipfox/api-integration-core-dto';
+
+export class SentryIntegrationProviderError extends IntegrationProviderError {}
+
+export class SentryInstallationAlreadyLinkedError extends Error {
+  constructor(public readonly installationUuid: string) {
+    super(
+      `Sentry installation is already linked to another Shipfox workspace: ${installationUuid}`,
+    );
+    this.name = 'SentryInstallationAlreadyLinkedError';
+  }
+}
+
+/**
+ * The claim could not prove control of the named install: the presented code
+ * neither exchanged successfully nor matched the stored `code_hash`. Surfaced as
+ * a 403 so a forged or leaked bare uuid cannot bind someone else's install.
+ */
+export class SentryClaimProofMismatchError extends Error {
+  constructor(public readonly installationUuid: string) {
+    super(`Sentry claim could not be verified for installation: ${installationUuid}`);
+    this.name = 'SentryClaimProofMismatchError';
+  }
+}
+
+/**
+ * A concurrent path (the signed webhook) is mid-exchange for this install, so the
+ * verified row is not visible to the claim yet. Retryable: the existing client
+ * backoff re-calls and finds the now-persisted row.
+ */
+export class SentryVerificationInProgressError extends Error {
+  constructor(
+    public readonly installationUuid: string,
+    public readonly retryAfterSeconds = 2,
+  ) {
+    super(`Sentry installation verification is still in progress: ${installationUuid}`);
+    this.name = 'SentryVerificationInProgressError';
+  }
+}
+
+/**
+ * Base for issue deliveries we received and authenticated but deliberately do
+ * not publish. The webhook layer records them for dedup and acknowledges with a
+ * 204 rather than treating them as failures — a sustained non-2xx can make Sentry
+ * disable the webhook. Carries no HTTP concerns so workers/jobs can reuse it.
+ */
+export class SentryIssueDroppedError extends Error {}
+
+export class SentryInstallationNotFoundError extends SentryIssueDroppedError {
+  constructor(public readonly installationUuid: string) {
+    super(`Sentry installation not found: ${installationUuid}`);
+    this.name = 'SentryInstallationNotFoundError';
+  }
+}
+
+export class SentryInstallationDeletedError extends SentryIssueDroppedError {
+  constructor(public readonly installationUuid: string) {
+    super(`Sentry installation is deleted: ${installationUuid}`);
+    this.name = 'SentryInstallationDeletedError';
+  }
+}
+
+export class SentryConnectionNotFoundError extends SentryIssueDroppedError {
+  constructor(public readonly connectionId: string) {
+    super(`Sentry installation has no connection: ${connectionId}`);
+    this.name = 'SentryConnectionNotFoundError';
+  }
+}
+
+/**
+ * A verified install that no workspace has claimed yet (`connection_id IS NULL`),
+ * so an issue delivery has no workspace to publish against. Dropped (204) like the
+ * other pre-publish cases; kept distinct from SentryConnectionNotFoundError so the
+ * carried identifier is unambiguously an installation uuid, not a connection id.
+ */
+export class SentryInstallationUnclaimedError extends SentryIssueDroppedError {
+  constructor(public readonly installationUuid: string) {
+    super(`Sentry installation is verified but not yet claimed: ${installationUuid}`);
+    this.name = 'SentryInstallationUnclaimedError';
+  }
+}