@shipfox/api-integration-sentry 2.0.0

package/dist/core/errors.js

@@ -0,0 +1,67 @@
+import { IntegrationProviderError } from '@shipfox/api-integration-core-dto';
+export class SentryIntegrationProviderError extends IntegrationProviderError {
+}
+export class SentryInstallationAlreadyLinkedError extends Error {
+    constructor(installationUuid){
+        super(`Sentry installation is already linked to another Shipfox workspace: ${installationUuid}`), this.installationUuid = 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(installationUuid){
+        super(`Sentry claim could not be verified for installation: ${installationUuid}`), this.installationUuid = 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(installationUuid, retryAfterSeconds = 2){
+        super(`Sentry installation verification is still in progress: ${installationUuid}`), this.installationUuid = installationUuid, this.retryAfterSeconds = retryAfterSeconds;
+        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(installationUuid){
+        super(`Sentry installation not found: ${installationUuid}`), this.installationUuid = installationUuid;
+        this.name = 'SentryInstallationNotFoundError';
+    }
+}
+export class SentryInstallationDeletedError extends SentryIssueDroppedError {
+    constructor(installationUuid){
+        super(`Sentry installation is deleted: ${installationUuid}`), this.installationUuid = installationUuid;
+        this.name = 'SentryInstallationDeletedError';
+    }
+}
+export class SentryConnectionNotFoundError extends SentryIssueDroppedError {
+    constructor(connectionId){
+        super(`Sentry installation has no connection: ${connectionId}`), this.connectionId = 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(installationUuid){
+        super(`Sentry installation is verified but not yet claimed: ${installationUuid}`), this.installationUuid = installationUuid;
+        this.name = 'SentryInstallationUnclaimedError';
+    }
+}
+
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/errors.ts"],"sourcesContent":["import {IntegrationProviderError} from '@shipfox/api-integration-core-dto';\n\nexport class SentryIntegrationProviderError extends IntegrationProviderError {}\n\nexport class SentryInstallationAlreadyLinkedError extends Error {\n  constructor(public readonly installationUuid: string) {\n    super(\n      `Sentry installation is already linked to another Shipfox workspace: ${installationUuid}`,\n    );\n    this.name = 'SentryInstallationAlreadyLinkedError';\n  }\n}\n\n/**\n * The claim could not prove control of the named install: the presented code\n * neither exchanged successfully nor matched the stored `code_hash`. Surfaced as\n * a 403 so a forged or leaked bare uuid cannot bind someone else's install.\n */\nexport class SentryClaimProofMismatchError extends Error {\n  constructor(public readonly installationUuid: string) {\n    super(`Sentry claim could not be verified for installation: ${installationUuid}`);\n    this.name = 'SentryClaimProofMismatchError';\n  }\n}\n\n/**\n * A concurrent path (the signed webhook) is mid-exchange for this install, so the\n * verified row is not visible to the claim yet. Retryable: the existing client\n * backoff re-calls and finds the now-persisted row.\n */\nexport class SentryVerificationInProgressError extends Error {\n  constructor(\n    public readonly installationUuid: string,\n    public readonly retryAfterSeconds = 2,\n  ) {\n    super(`Sentry installation verification is still in progress: ${installationUuid}`);\n    this.name = 'SentryVerificationInProgressError';\n  }\n}\n\n/**\n * Base for issue deliveries we received and authenticated but deliberately do\n * not publish. The webhook layer records them for dedup and acknowledges with a\n * 204 rather than treating them as failures — a sustained non-2xx can make Sentry\n * disable the webhook. Carries no HTTP concerns so workers/jobs can reuse it.\n */\nexport class SentryIssueDroppedError extends Error {}\n\nexport class SentryInstallationNotFoundError extends SentryIssueDroppedError {\n  constructor(public readonly installationUuid: string) {\n    super(`Sentry installation not found: ${installationUuid}`);\n    this.name = 'SentryInstallationNotFoundError';\n  }\n}\n\nexport class SentryInstallationDeletedError extends SentryIssueDroppedError {\n  constructor(public readonly installationUuid: string) {\n    super(`Sentry installation is deleted: ${installationUuid}`);\n    this.name = 'SentryInstallationDeletedError';\n  }\n}\n\nexport class SentryConnectionNotFoundError extends SentryIssueDroppedError {\n  constructor(public readonly connectionId: string) {\n    super(`Sentry installation has no connection: ${connectionId}`);\n    this.name = 'SentryConnectionNotFoundError';\n  }\n}\n\n/**\n * A verified install that no workspace has claimed yet (`connection_id IS NULL`),\n * so an issue delivery has no workspace to publish against. Dropped (204) like the\n * other pre-publish cases; kept distinct from SentryConnectionNotFoundError so the\n * carried identifier is unambiguously an installation uuid, not a connection id.\n */\nexport class SentryInstallationUnclaimedError extends SentryIssueDroppedError {\n  constructor(public readonly installationUuid: string) {\n    super(`Sentry installation is verified but not yet claimed: ${installationUuid}`);\n    this.name = 'SentryInstallationUnclaimedError';\n  }\n}\n"],"names":["IntegrationProviderError","SentryIntegrationProviderError","SentryInstallationAlreadyLinkedError","Error","installationUuid","name","SentryClaimProofMismatchError","SentryVerificationInProgressError","retryAfterSeconds","SentryIssueDroppedError","SentryInstallationNotFoundError","SentryInstallationDeletedError","SentryConnectionNotFoundError","connectionId","SentryInstallationUnclaimedError"],"mappings":"AAAA,SAAQA,wBAAwB,QAAO,oCAAoC;AAE3E,OAAO,MAAMC,uCAAuCD;AAA0B;AAE9E,OAAO,MAAME,6CAA6CC;IACxD,YAAY,AAAgBC,gBAAwB,CAAE;QACpD,KAAK,CACH,CAAC,oEAAoE,EAAEA,kBAAkB,QAFjEA,mBAAAA;QAI1B,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAEA;;;;CAIC,GACD,OAAO,MAAMC,sCAAsCH;IACjD,YAAY,AAAgBC,gBAAwB,CAAE;QACpD,KAAK,CAAC,CAAC,qDAAqD,EAAEA,kBAAkB,QADtDA,mBAAAA;QAE1B,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAEA;;;;CAIC,GACD,OAAO,MAAME,0CAA0CJ;IACrD,YACE,AAAgBC,gBAAwB,EACxC,AAAgBI,oBAAoB,CAAC,CACrC;QACA,KAAK,CAAC,CAAC,uDAAuD,EAAEJ,kBAAkB,QAHlEA,mBAAAA,uBACAI,oBAAAA;QAGhB,IAAI,CAACH,IAAI,GAAG;IACd;AACF;AAEA;;;;;CAKC,GACD,OAAO,MAAMI,gCAAgCN;AAAO;AAEpD,OAAO,MAAMO,wCAAwCD;IACnD,YAAY,AAAgBL,gBAAwB,CAAE;QACpD,KAAK,CAAC,CAAC,+BAA+B,EAAEA,kBAAkB,QADhCA,mBAAAA;QAE1B,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAEA,OAAO,MAAMM,uCAAuCF;IAClD,YAAY,AAAgBL,gBAAwB,CAAE;QACpD,KAAK,CAAC,CAAC,gCAAgC,EAAEA,kBAAkB,QADjCA,mBAAAA;QAE1B,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAEA,OAAO,MAAMO,sCAAsCH;IACjD,YAAY,AAAgBI,YAAoB,CAAE;QAChD,KAAK,CAAC,CAAC,uCAAuC,EAAEA,cAAc,QADpCA,eAAAA;QAE1B,IAAI,CAACR,IAAI,GAAG;IACd;AACF;AAEA;;;;;CAKC,GACD,OAAO,MAAMS,yCAAyCL;IACpD,YAAY,AAAgBL,gBAAwB,CAAE;QACpD,KAAK,CAAC,CAAC,qDAAqD,EAAEA,kBAAkB,QADtDA,mBAAAA;QAE1B,IAAI,CAACC,IAAI,GAAG;IACd;AACF"}

package/dist/core/install.d.ts

@@ -0,0 +1,63 @@
+import type { IntegrationConnection } from '@shipfox/api-integration-core-dto';
+import type { SentryApiClient, SentryAuthorization } from '#api/client.js';
+import type { PersistVerifiedUnclaimedInstallationParams, SentryInstallation } from '#db/installations.js';
+export interface ConnectSentryInstallationInput {
+    workspaceId: string;
+    installationUuid: string;
+    orgSlug: string;
+    displayName: string;
+    installerUserId: string;
+    codeHash: string;
+}
+export declare function hashAuthorizationCode(code: string): string;
+export interface VerifyAndPersistUnclaimedInstallationParams {
+    sentry: SentryApiClient;
+    installationUuid: string;
+    code: string;
+    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 declare function verifyAndPersistUnclaimedInstallation(params: VerifyAndPersistUnclaimedInstallationParams): Promise<VerifyAndPersistUnclaimedInstallationResult>;
+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 declare function handleSentryConnect(params: HandleSentryConnectParams): Promise<IntegrationConnection<'sentry'>>;
+//# sourceMappingURL=install.d.ts.map

package/dist/core/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/core/install.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,mCAAmC,CAAC;AAE7E,OAAO,KAAK,EAAC,eAAe,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAQzE,OAAO,KAAK,EACV,0CAA0C,EAC1C,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,8BAA8B;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAUD,MAAM,WAAW,2CAA2C;IAC1D,MAAM,EAAE,eAAe,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IAGb,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,oCAAoC,EAAE,CACpC,KAAK,EAAE,0CAA0C,KAC9C,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,2CAA2C;IAC1D,YAAY,EAAE,kBAAkB,CAAC;IACjC,aAAa,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,qCAAqC,CACzD,MAAM,EAAE,2CAA2C,GAClD,OAAO,CAAC,2CAA2C,CAAC,CA8BtD;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB,EAAE,CAAC,KAAK,EAAE;QAC7B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,CAAC;IACxF,yBAAyB,EAAE,CACzB,KAAK,EAAE,8BAA8B,KAClC,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9C,oCAAoC,EAAE,CACpC,KAAK,EAAE,0CAA0C,KAC9C,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAc1C"}

package/dist/core/install.js

@@ -0,0 +1,209 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { logger } from '@shipfox/node-opentelemetry';
+import { SentryClaimProofMismatchError, SentryInstallationAlreadyLinkedError, SentryInstallationDeletedError, SentryIntegrationProviderError, SentryVerificationInProgressError } from '#core/errors.js';
+// 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) {
+    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, stored) {
+    if (presented.length !== stored.length) return false;
+    return timingSafeEqual(Buffer.from(presented), Buffer.from(stored));
+}
+/**
+ * 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) {
+    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
+    };
+}
+/**
+ * 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) {
+    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, connectionId) {
+    const connection = await params.getConnectionById(connectionId);
+    if (connection && connection.workspaceId === params.workspaceId) {
+        return connection;
+    }
+    throw new SentryInstallationAlreadyLinkedError(params.installationUuid);
+}
+async function claimVerifiedInstall(params, install) {
+    let authorization;
+    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) {
+    let result;
+    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) {
+    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) {
+    return install.connectionId === null && install.status === 'installed';
+}
+function bindClaim(params, binding) {
+    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) {
+    // 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) {
+    return error instanceof SentryIntegrationProviderError && error.reason === 'access-denied';
+}
+
+//# sourceMappingURL=install.js.map

package/dist/core/install.js.map

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

package/dist/core/signature.d.ts

@@ -0,0 +1,7 @@
+export interface VerifySentrySignatureParams {
+    rawBody: string;
+    signature: string;
+    secret: string;
+}
+export declare function verifySentrySignature(params: VerifySentrySignatureParams): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/core/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/core/signature.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAElF"}

package/dist/core/signature.js

@@ -0,0 +1,6 @@
+import { verifyHexHmacSignature } from '@shipfox/node-fastify';
+export function verifySentrySignature(params) {
+    return verifyHexHmacSignature(params);
+}
+
+//# sourceMappingURL=signature.js.map

package/dist/core/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/signature.ts"],"sourcesContent":["import {verifyHexHmacSignature} from '@shipfox/node-fastify';\n\nexport interface VerifySentrySignatureParams {\n  rawBody: string;\n  signature: string;\n  secret: string;\n}\n\nexport function verifySentrySignature(params: VerifySentrySignatureParams): boolean {\n  return verifyHexHmacSignature(params);\n}\n"],"names":["verifyHexHmacSignature","verifySentrySignature","params"],"mappings":"AAAA,SAAQA,sBAAsB,QAAO,wBAAwB;AAQ7D,OAAO,SAASC,sBAAsBC,MAAmC;IACvE,OAAOF,uBAAuBE;AAChC"}

package/dist/core/webhook.d.ts

@@ -0,0 +1,49 @@
+import type { GetIntegrationConnectionByIdFn, IntegrationTx, PublishIntegrationEventReceivedFn, RecordDeliveryOnlyFn, UpdateIntegrationConnectionLifecycleStatusFn } from '@shipfox/api-integration-core-dto';
+import type { SentryIssueWebhookDto } from '@shipfox/api-integration-sentry-dto';
+import type { SentryApiClient } from '#api/client.js';
+import { type SentryInstallation } from '#db/installations.js';
+export interface HandleSentryIssueEventParams {
+    tx: IntegrationTx;
+    deliveryId: string;
+    payload: SentryIssueWebhookDto;
+    publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+    getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+export declare function handleSentryIssueEvent(params: HandleSentryIssueEventParams): Promise<void>;
+export interface HandleSentryInstallationCreatedParams {
+    deliveryId: string;
+    installationUuid: string;
+    orgSlug: string | undefined;
+    code: string | undefined;
+    sentry: SentryApiClient;
+    verifyInstall: boolean;
+    getSentryInstallation: (input: {
+        installationUuid: string;
+    }) => Promise<SentryInstallation | undefined>;
+    persistUnclaimedAndRecordDelivery: (input: {
+        installationUuid: string;
+        orgSlug: string;
+        codeHash: string;
+        deliveryId: string;
+    }) => Promise<SentryInstallation>;
+    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 declare function handleSentryInstallationCreated(params: HandleSentryInstallationCreatedParams): Promise<void>;
+export interface HandleSentryInstallationDeletedParams {
+    tx: IntegrationTx;
+    deliveryId: string;
+    installationUuid: string;
+    recordDeliveryOnly: RecordDeliveryOnlyFn;
+    updateConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+}
+export declare function handleSentryInstallationDeleted(params: HandleSentryInstallationDeletedParams): Promise<void>;
+export declare function normalizeSentryIssueAction(parsedJson: unknown): unknown;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/core/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/core/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,aAAa,EACb,iCAAiC,EACjC,oBAAoB,EAEpB,4CAA4C,EAC7C,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,qCAAqC,CAAC;AAE/E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AASpD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,aAAa,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+BAA+B,EAAE,iCAAiC,CAAC;IACnE,4BAA4B,EAAE,8BAA8B,CAAC;CAC9D;AAOD,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChG;AAED,MAAM,WAAW,qCAAqC;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB,EAAE,CAAC,KAAK,EAAE;QAC7B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAG9C,iCAAiC,EAAE,CAAC,KAAK,EAAE;QACzC,gBAAgB,EAAE,MAAM,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAGlC,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,qCAAqC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAgEf;AAED,MAAM,WAAW,qCAAqC;IACpD,EAAE,EAAE,aAAa,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,oBAAoB,CAAC;IACzC,+BAA+B,EAAE,4CAA4C,CAAC;CAC/E;AAMD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,qCAAqC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAiBf;AAID,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAOvE"}

package/dist/core/webhook.js

@@ -0,0 +1,175 @@
+import { logger } from '@shipfox/node-opentelemetry';
+import { SentryConnectionNotFoundError, SentryInstallationDeletedError, SentryInstallationNotFoundError, SentryInstallationUnclaimedError, SentryIntegrationProviderError } from '#core/errors.js';
+import { verifyAndPersistUnclaimedInstallation } from '#core/install.js';
+import { getSentryInstallationByInstallationUuid, markSentryInstallationDeleted } from '#db/installations.js';
+const SENTRY_SOURCE = 'sentry';
+const DEFAULT_ISSUE_TITLE = 'Sentry issue';
+const DELETED_STATUS = 'deleted';
+// 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) {
+    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)
+        }
+    });
+}
+/**
+ * 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) {
+    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);
+    }
+}
+// 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) {
+    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) {
+    if (typeof parsedJson !== 'object' || parsedJson === null) return parsedJson;
+    const obj = parsedJson;
+    if (obj.action === 'ignored') {
+        return {
+            ...obj,
+            action: 'archived'
+        };
+    }
+    return parsedJson;
+}
+function normalizeIssuePayload(payload) {
+    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
+    };
+}
+
+//# sourceMappingURL=webhook.js.map