@shipfox/api-integration-sentry 2.0.0

package/src/core/install.test.ts

@@ -0,0 +1,343 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {SentryApiClient} from '#api/client.js';
+import {
+  SentryClaimProofMismatchError,
+  SentryInstallationAlreadyLinkedError,
+  SentryInstallationDeletedError,
+  SentryIntegrationProviderError,
+  SentryVerificationInProgressError,
+} from '#core/errors.js';
+import type {SentryInstallation} from '#db/installations.js';
+import {
+  type ConnectSentryInstallationInput,
+  handleSentryConnect,
+  hashAuthorizationCode,
+} from './install.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+const OTHER_WORKSPACE_ID = '22222222-2222-4222-8222-222222222222';
+const INSTALL_UUID = 'install-uuid-1';
+const CODE = 'the-code';
+const CODE_HASH = hashAuthorizationCode(CODE);
+const CONNECTION_ID = '33333333-3333-4333-8333-333333333333';
+
+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 connection(
+  overrides: Partial<IntegrationConnection<'sentry'>> = {},
+): IntegrationConnection<'sentry'> {
+  return {
+    id: CONNECTION_ID,
+    workspaceId: WORKSPACE_ID,
+    provider: 'sentry',
+    externalAccountId: INSTALL_UUID,
+    slug: 'sentry_acme',
+    displayName: 'Sentry acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function installation(overrides: Partial<SentryInstallation> = {}): SentryInstallation {
+  return {
+    id: 'row-1',
+    connectionId: null,
+    installationUuid: INSTALL_UUID,
+    orgSlug: 'acme',
+    status: 'installed',
+    codeHash: CODE_HASH,
+    installerUserId: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+interface RunOptions {
+  sentry?: SentryApiClient;
+  verifyInstall?: boolean;
+  code?: string;
+  install?: SentryInstallation | undefined;
+  installSequence?: (SentryInstallation | undefined)[];
+  connection?: IntegrationConnection<'sentry'> | undefined;
+}
+
+function run(options: RunOptions = {}) {
+  const sentry = options.sentry ?? sentryClient();
+  const sequence = options.installSequence ?? [options.install];
+  let call = 0;
+  const getSentryInstallation = vi.fn(() => {
+    const value = sequence[Math.min(call, sequence.length - 1)];
+    call += 1;
+    return Promise.resolve(value);
+  });
+  const getConnectionById = vi.fn(() => Promise.resolve(options.connection));
+  const connectSentryInstallation = vi.fn((input: ConnectSentryInstallationInput) =>
+    Promise.resolve(
+      connection({
+        workspaceId: input.workspaceId,
+        externalAccountId: input.installationUuid,
+        slug: 'sentry_acme',
+        displayName: input.displayName,
+      }),
+    ),
+  );
+  const persistVerifiedUnclaimedInstallation = vi.fn(
+    (input: {installationUuid: string; orgSlug: string; codeHash: string}) =>
+      Promise.resolve(installation({connectionId: null, ...input})),
+  );
+
+  const result = handleSentryConnect({
+    sentry,
+    workspaceId: WORKSPACE_ID,
+    code: options.code ?? CODE,
+    installationUuid: INSTALL_UUID,
+    installerUserId: 'user-1',
+    verifyInstall: options.verifyInstall ?? true,
+    getSentryInstallation,
+    getConnectionById,
+    connectSentryInstallation,
+    persistVerifiedUnclaimedInstallation,
+  });
+
+  return {
+    sentry,
+    getSentryInstallation,
+    getConnectionById,
+    connectSentryInstallation,
+    persistVerifiedUnclaimedInstallation,
+    result,
+  };
+}
+
+describe('handleSentryConnect — browser-first (no row)', () => {
+  it('exchanges, persists the unclaimed row, then binds and verifies last', async () => {
+    const sentry = sentryClient();
+    const {connectSentryInstallation, persistVerifiedUnclaimedInstallation, result} = run({sentry});
+
+    const connected = await result;
+
+    expect(sentry.exchangeAuthorizationCode).toHaveBeenCalledWith({
+      installationUuid: INSTALL_UUID,
+      code: CODE,
+    });
+    expect(persistVerifiedUnclaimedInstallation).toHaveBeenCalledWith({
+      installationUuid: INSTALL_UUID,
+      orgSlug: 'acme',
+      codeHash: CODE_HASH,
+    });
+    expect(connectSentryInstallation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceId: WORKSPACE_ID,
+        installationUuid: INSTALL_UUID,
+        orgSlug: 'acme',
+        codeHash: CODE_HASH,
+        installerUserId: 'user-1',
+      }),
+    );
+    expect(connected.provider).toBe('sentry');
+
+    const persistOrder = persistVerifiedUnclaimedInstallation.mock.invocationCallOrder[0];
+    const verifyOrder = vi.mocked(sentry.verifyInstallation).mock.invocationCallOrder[0];
+    expect(persistOrder).toBeLessThan(verifyOrder ?? 0);
+  });
+
+  it('binds even when the best-effort verify fails (non-fatal)', async () => {
+    const sentry = sentryClient({
+      verifyInstallation: vi.fn(() => Promise.reject(new Error('verify failed'))),
+    });
+    const {connectSentryInstallation, result} = run({sentry});
+
+    const connected = await result;
+
+    expect(connectSentryInstallation).toHaveBeenCalled();
+    expect(connected.lifecycleStatus).toBe('active');
+  });
+
+  it('persists nothing when the code exchange fails outright', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('timeout', 'slow')),
+      ),
+    });
+    const {connectSentryInstallation, persistVerifiedUnclaimedInstallation, result} = run({sentry});
+
+    await expect(result).rejects.toBeInstanceOf(SentryIntegrationProviderError);
+    expect(persistVerifiedUnclaimedInstallation).not.toHaveBeenCalled();
+    expect(connectSentryInstallation).not.toHaveBeenCalled();
+  });
+});
+
+describe('handleSentryConnect — verified, unclaimed row exists (webhook-first)', () => {
+  it('binds via same-code race when the exchange is already used and the hash matches', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+      ),
+    });
+    const {connectSentryInstallation, persistVerifiedUnclaimedInstallation, result} = run({
+      sentry,
+      install: installation({connectionId: null, codeHash: CODE_HASH}),
+    });
+
+    const connected = await result;
+
+    expect(persistVerifiedUnclaimedInstallation).not.toHaveBeenCalled();
+    expect(connectSentryInstallation).toHaveBeenCalledWith(
+      expect.objectContaining({installationUuid: INSTALL_UUID, codeHash: CODE_HASH}),
+    );
+    expect(connected.provider).toBe('sentry');
+  });
+
+  it('binds via a fresh successful exchange (re-entry with a new code), updating the hash', async () => {
+    const freshCode = 'fresh-code';
+    const sentry = sentryClient();
+    const {connectSentryInstallation, result} = run({
+      sentry,
+      code: freshCode,
+      install: installation({connectionId: null, codeHash: hashAuthorizationCode('old-code')}),
+    });
+
+    await result;
+
+    expect(sentry.exchangeAuthorizationCode).toHaveBeenCalledWith({
+      installationUuid: INSTALL_UUID,
+      code: freshCode,
+    });
+    expect(connectSentryInstallation).toHaveBeenCalledWith(
+      expect.objectContaining({codeHash: hashAuthorizationCode(freshCode)}),
+    );
+  });
+
+  it('rejects with proof mismatch (IDOR) when the code is already used and the hash differs', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+      ),
+    });
+    const {connectSentryInstallation, result} = run({
+      sentry,
+      code: 'forged-code',
+      install: installation({connectionId: null, codeHash: CODE_HASH}),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(SentryClaimProofMismatchError);
+    expect(connectSentryInstallation).not.toHaveBeenCalled();
+  });
+});
+
+describe('handleSentryConnect — already claimed / tombstoned', () => {
+  it('is idempotent for an install already claimed to the same workspace', async () => {
+    const existing = connection({workspaceId: WORKSPACE_ID});
+    const {sentry, connectSentryInstallation, result} = run({
+      install: installation({connectionId: CONNECTION_ID}),
+      connection: existing,
+    });
+
+    const connected = await result;
+
+    expect(connected).toBe(existing);
+    expect(sentry.exchangeAuthorizationCode).not.toHaveBeenCalled();
+    expect(connectSentryInstallation).not.toHaveBeenCalled();
+  });
+
+  it('throws when the install is claimed to a different workspace', async () => {
+    const {sentry, result} = run({
+      install: installation({connectionId: CONNECTION_ID}),
+      connection: connection({workspaceId: OTHER_WORKSPACE_ID}),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(SentryInstallationAlreadyLinkedError);
+    expect(sentry.exchangeAuthorizationCode).not.toHaveBeenCalled();
+  });
+
+  it('throws when the install is tombstoned', async () => {
+    const {sentry, result} = run({
+      install: installation({status: 'deleted'}),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(SentryInstallationDeletedError);
+    expect(sentry.exchangeAuthorizationCode).not.toHaveBeenCalled();
+  });
+});
+
+describe('handleSentryConnect — simultaneous race', () => {
+  it('returns a retryable error when the code is already used and no row is visible yet', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+      ),
+    });
+    const {result} = run({sentry, installSequence: [undefined, undefined]});
+
+    await expect(result).rejects.toBeInstanceOf(SentryVerificationInProgressError);
+  });
+
+  it('reconciles when the concurrent webhook persisted the row between lookups', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi
+        .fn()
+        // First (browser) exchange loses the race; on re-read we find the row and
+        // the second exchange is "already used" with a matching hash → bind.
+        .mockRejectedValueOnce(new SentryIntegrationProviderError('access-denied', 'already used'))
+        .mockRejectedValueOnce(new SentryIntegrationProviderError('access-denied', 'already used')),
+    });
+    const {connectSentryInstallation, result} = run({
+      sentry,
+      installSequence: [undefined, installation({connectionId: null, codeHash: CODE_HASH})],
+    });
+
+    const connected = await result;
+
+    expect(connected.provider).toBe('sentry');
+    expect(connectSentryInstallation).toHaveBeenCalledWith(
+      expect.objectContaining({codeHash: CODE_HASH}),
+    );
+  });
+
+  it('resolves idempotently when the concurrent webhook claimed the row between lookups', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+      ),
+    });
+    const existing = connection({workspaceId: WORKSPACE_ID});
+    const {connectSentryInstallation, result} = run({
+      sentry,
+      // First lookup sees no row; the re-read finds it already claimed.
+      installSequence: [undefined, installation({connectionId: CONNECTION_ID})],
+      connection: existing,
+    });
+
+    const connected = await result;
+
+    expect(connected).toBe(existing);
+    expect(connectSentryInstallation).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a terminal deleted error when the row is tombstoned between lookups', async () => {
+    const sentry = sentryClient({
+      exchangeAuthorizationCode: vi.fn(() =>
+        Promise.reject(new SentryIntegrationProviderError('access-denied', 'already used')),
+      ),
+    });
+    const {result} = run({
+      sentry,
+      // First lookup sees no row; the re-read finds it tombstoned.
+      installSequence: [undefined, installation({status: 'deleted'})],
+    });
+
+    await expect(result).rejects.toBeInstanceOf(SentryInstallationDeletedError);
+  });
+});

package/src/core/install.ts

@@ -0,0 +1,305 @@
+import {createHash, timingSafeEqual} from 'node:crypto';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {SentryApiClient, SentryAuthorization} from '#api/client.js';
+import {
+  SentryClaimProofMismatchError,
+  SentryInstallationAlreadyLinkedError,
+  SentryInstallationDeletedError,
+  SentryIntegrationProviderError,
+  SentryVerificationInProgressError,
+} from '#core/errors.js';
+import type {
+  PersistVerifiedUnclaimedInstallationParams,
+  SentryInstallation,
+} from '#db/installations.js';
+
+export interface ConnectSentryInstallationInput {
+  workspaceId: string;
+  installationUuid: string;
+  orgSlug: string;
+  displayName: string;
+  installerUserId: string;
+  codeHash: string;
+}
+
+// sha256 of the single-use authorization code. Stored on the install row so the
+// claim can prove the claimant holds the same code Sentry issued, without ever
+// persisting a live credential (the code is dead once exchanged).
+export function hashAuthorizationCode(code: string): string {
+  return createHash('sha256').update(code).digest('hex');
+}
+
+// Constant-time compare of two sha256 hex digests, matching the HMAC check in
+// signature.ts. The length guard runs first because timingSafeEqual throws on a
+// length mismatch, and a digest's length is not secret.
+function codeHashesEqual(presented: string, stored: string): boolean {
+  if (presented.length !== stored.length) return false;
+  return timingSafeEqual(Buffer.from(presented), Buffer.from(stored));
+}
+
+export interface VerifyAndPersistUnclaimedInstallationParams {
+  sentry: SentryApiClient;
+  installationUuid: string;
+  code: string;
+  // Known from the signed webhook payload; omit to derive it from Sentry after
+  // the exchange (the browser-first claim carries no payload).
+  orgSlug?: string | undefined;
+  verifyInstall: boolean;
+  persistVerifiedUnclaimedInstallation: (
+    input: PersistVerifiedUnclaimedInstallationParams,
+  ) => Promise<SentryInstallation>;
+}
+
+export interface VerifyAndPersistUnclaimedInstallationResult {
+  installation: SentryInstallation;
+  authorization: SentryAuthorization;
+}
+
+/**
+ * Security-critical exchange → persist → best-effort verify, shared by the signed
+ * webhook and the browser-first claim. The exchange is the authenticity check and
+ * spends the single-use code, so it runs OUTSIDE any DB transaction; the caller's
+ * `persistVerifiedUnclaimedInstallation` owns the short transaction. The verify
+ * runs AFTER the row is durably persisted, so a verify failure leaves a claimable
+ * row rather than a Sentry-side "installed" state pointing at a row that was never
+ * written. Never logs the raw code.
+ */
+export async function verifyAndPersistUnclaimedInstallation(
+  params: VerifyAndPersistUnclaimedInstallationParams,
+): Promise<VerifyAndPersistUnclaimedInstallationResult> {
+  const authorization = await params.sentry.exchangeAuthorizationCode({
+    installationUuid: params.installationUuid,
+    code: params.code,
+  });
+
+  const orgSlug =
+    params.orgSlug ??
+    (
+      await params.sentry.getInstallation({
+        installationUuid: params.installationUuid,
+        token: authorization.token,
+      })
+    ).orgSlug;
+
+  const installation = await params.persistVerifiedUnclaimedInstallation({
+    installationUuid: params.installationUuid,
+    orgSlug,
+    codeHash: hashAuthorizationCode(params.code),
+  });
+
+  if (params.verifyInstall) {
+    await bestEffortVerifyInstallation({
+      sentry: params.sentry,
+      installationUuid: params.installationUuid,
+      token: authorization.token,
+    });
+  }
+
+  return {installation, authorization};
+}
+
+export interface HandleSentryConnectParams {
+  sentry: SentryApiClient;
+  workspaceId: string;
+  code: string;
+  installationUuid: string;
+  installerUserId: string;
+  verifyInstall: boolean;
+  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>;
+}
+
+/**
+ * Binds a verified Sentry installation to a workspace (the claim half of the
+ * webhook-authoritative flow). The webhook persists the verified-unclaimed row;
+ * this proves the claimant controls the install and sets `connection_id`.
+ *
+ * Proof rules (unified claim auth):
+ * - exchange succeeds → browser-first winner or a re-entry with a fresh code.
+ * - exchange "already used" + the presented code hashes to the stored hash →
+ *   the same code the webhook spent, so the claimant holds it (same-code race).
+ * - exchange "already used" + the verified row is not visible yet → a concurrent
+ *   webhook is mid-exchange; retryable so the client backoff reconciles.
+ * - anything else on an existing unclaimed row → proof mismatch (403, IDOR gate).
+ */
+export async function handleSentryConnect(
+  params: HandleSentryConnectParams,
+): Promise<IntegrationConnection<'sentry'>> {
+  const install = await params.getSentryInstallation({installationUuid: params.installationUuid});
+
+  if (install) {
+    if (install.status === 'deleted') {
+      throw new SentryInstallationDeletedError(params.installationUuid);
+    }
+    if (install.connectionId) {
+      return resolveClaimedInstall(params, install.connectionId);
+    }
+    return claimVerifiedInstall(params, install);
+  }
+
+  return claimBrowserFirst(params);
+}
+
+async function resolveClaimedInstall(
+  params: HandleSentryConnectParams,
+  connectionId: string,
+): Promise<IntegrationConnection<'sentry'>> {
+  const connection = await params.getConnectionById(connectionId);
+  if (connection && connection.workspaceId === params.workspaceId) {
+    return connection;
+  }
+  throw new SentryInstallationAlreadyLinkedError(params.installationUuid);
+}
+
+async function claimVerifiedInstall(
+  params: HandleSentryConnectParams,
+  install: SentryInstallation,
+): Promise<IntegrationConnection<'sentry'>> {
+  let authorization: SentryAuthorization;
+  try {
+    authorization = await params.sentry.exchangeAuthorizationCode({
+      installationUuid: params.installationUuid,
+      code: params.code,
+    });
+  } catch (error) {
+    if (isCodeAlreadyUsed(error)) {
+      if (
+        install.codeHash &&
+        codeHashesEqual(hashAuthorizationCode(params.code), install.codeHash)
+      ) {
+        return bindClaim(params, {orgSlug: install.orgSlug, codeHash: install.codeHash});
+      }
+      throw new SentryClaimProofMismatchError(params.installationUuid);
+    }
+    throw error;
+  }
+
+  const connection = await bindClaim(params, {
+    orgSlug: install.orgSlug,
+    codeHash: hashAuthorizationCode(params.code),
+  });
+  if (params.verifyInstall) {
+    await bestEffortVerifyInstallation({
+      sentry: params.sentry,
+      installationUuid: params.installationUuid,
+      token: authorization.token,
+      connectionId: connection.id,
+    });
+  }
+  return connection;
+}
+
+async function claimBrowserFirst(
+  params: HandleSentryConnectParams,
+): Promise<IntegrationConnection<'sentry'>> {
+  let result: VerifyAndPersistUnclaimedInstallationResult;
+  try {
+    result = await verifyAndPersistUnclaimedInstallation({
+      sentry: params.sentry,
+      installationUuid: params.installationUuid,
+      code: params.code,
+      verifyInstall: false,
+      persistVerifiedUnclaimedInstallation: params.persistVerifiedUnclaimedInstallation,
+    });
+  } catch (error) {
+    if (isCodeAlreadyUsed(error)) {
+      return reconcileConcurrentClaim(params);
+    }
+    throw error;
+  }
+
+  const connection = await bindClaim(params, {
+    orgSlug: result.installation.orgSlug,
+    codeHash: hashAuthorizationCode(params.code),
+  });
+  if (params.verifyInstall) {
+    await bestEffortVerifyInstallation({
+      sentry: params.sentry,
+      installationUuid: params.installationUuid,
+      token: result.authorization.token,
+      connectionId: connection.id,
+    });
+  }
+  return connection;
+}
+
+// The browser-first exchange got "already used" with no row visible at lookup: a
+// concurrent webhook won the exchange. Re-read once — if its verified row is now
+// visible we reconcile through the same proof rules; if it got claimed we resolve
+// it; if it was tombstoned we surface that terminally (matching the top-level
+// check); otherwise it is still mid-flight, so the claim is retryable.
+async function reconcileConcurrentClaim(
+  params: HandleSentryConnectParams,
+): Promise<IntegrationConnection<'sentry'>> {
+  const reread = await params.getSentryInstallation({installationUuid: params.installationUuid});
+  if (reread?.status === 'deleted') {
+    throw new SentryInstallationDeletedError(params.installationUuid);
+  }
+  if (reread) {
+    if (reread.connectionId) {
+      return resolveClaimedInstall(params, reread.connectionId);
+    }
+    if (isVerifiedUnclaimed(reread)) {
+      return claimVerifiedInstall(params, reread);
+    }
+  }
+  throw new SentryVerificationInProgressError(params.installationUuid);
+}
+
+function isVerifiedUnclaimed(install: SentryInstallation): boolean {
+  return install.connectionId === null && install.status === 'installed';
+}
+
+function bindClaim(
+  params: HandleSentryConnectParams,
+  binding: {orgSlug: string; codeHash: string},
+): Promise<IntegrationConnection<'sentry'>> {
+  return params.connectSentryInstallation({
+    workspaceId: params.workspaceId,
+    installationUuid: params.installationUuid,
+    orgSlug: binding.orgSlug,
+    displayName: `Sentry ${binding.orgSlug}`,
+    installerUserId: params.installerUserId,
+    codeHash: binding.codeHash,
+  });
+}
+
+async function bestEffortVerifyInstallation(input: {
+  sentry: SentryApiClient;
+  installationUuid: string;
+  token: string;
+  connectionId?: string;
+}): Promise<void> {
+  // The row is already persisted and receiving webhooks, so a verify failure only
+  // leaves the install pending on Sentry's side (re-verifying needs a fresh token
+  // we cannot mint here). Log it rather than failing a working claim.
+  try {
+    await input.sentry.verifyInstallation({
+      installationUuid: input.installationUuid,
+      token: input.token,
+    });
+  } catch (error) {
+    logger().warn(
+      {installationUuid: input.installationUuid, connectionId: input.connectionId, err: error},
+      'sentry connect: verify-install failed after persistence',
+    );
+  }
+}
+
+// The Sentry client collapses a reused, expired, or forged code to a single
+// `access-denied` provider error; we cannot tell them apart from the response.
+// On an install we already know was verified, the most likely cause is the code
+// having been spent already, so the hash check disambiguates rather than the
+// error itself.
+function isCodeAlreadyUsed(error: unknown): boolean {
+  return error instanceof SentryIntegrationProviderError && error.reason === 'access-denied';
+}

package/src/core/signature.test.ts

@@ -0,0 +1,50 @@
+import {createHmac} from 'node:crypto';
+import {verifySentrySignature} from './signature.js';
+
+const SECRET = 'test-client-secret';
+
+function sign(rawBody: string, secret = SECRET): string {
+  return createHmac('sha256', secret).update(rawBody).digest('hex');
+}
+
+describe('verifySentrySignature', () => {
+  test('accepts a signature computed with the matching secret', () => {
+    const rawBody = JSON.stringify({action: 'created'});
+
+    const result = verifySentrySignature({rawBody, signature: sign(rawBody), secret: SECRET});
+
+    expect(result).toBe(true);
+  });
+
+  test('rejects a signature for a tampered body', () => {
+    const rawBody = JSON.stringify({action: 'created'});
+
+    const result = verifySentrySignature({
+      rawBody,
+      signature: sign(`${rawBody}tampered`),
+      secret: SECRET,
+    });
+
+    expect(result).toBe(false);
+  });
+
+  test('rejects a signature computed with a different secret', () => {
+    const rawBody = JSON.stringify({action: 'created'});
+
+    const result = verifySentrySignature({
+      rawBody,
+      signature: sign(rawBody, 'other-secret'),
+      secret: SECRET,
+    });
+
+    expect(result).toBe(false);
+  });
+
+  test('rejects a garbage signature whose length differs from the digest without throwing', () => {
+    const rawBody = JSON.stringify({action: 'created'});
+
+    const result = verifySentrySignature({rawBody, signature: 'deadbeef', secret: SECRET});
+
+    expect(result).toBe(false);
+  });
+});