@cursor/bdk 0.2.24 → 0.2.26

package/dist/channels/pagerduty/pagerduty-channel.d.ts

@@ -0,0 +1,64 @@
+import { type AuthPolicy, type ChannelDefinition } from "../../types.js";
+import type { SecretAlternatives } from "../../internal/secret-alternatives.js";
+import { type PagerDutyChannelState } from "./state.js";
+import type { PagerDutyChannelOptions } from "./types.js";
+export declare function getPagerDutyChannelOptions(definition: object): PagerDutyChannelOptions | undefined;
+/**
+ * Deployment secrets the channel reads in the guest that must each be set:
+ * a named `selfUserIds`, `token`, or `from` secret. `deploy` declares them
+ * so an unset one is flagged instead of the agent waking on its own echoes
+ * or failing its write-backs.
+ */
+export declare function pagerDutyChannelCredentialSecretNames(definition: object): string[];
+/**
+ * Deployment secrets of which at least one must be set: with `selfUserIds`
+ * omitted, the agent's user comes from `PAGERDUTY_USER_ID` or is inferred
+ * from the channel's token. `deploy` warns when neither is set. A token
+ * authored in code always infers, so it needs no warning.
+ */
+export declare function pagerDutyChannelSecretAlternatives(definition: object): SecretAlternatives[];
+/**
+ * Why a `pagerdutyChannel` cannot deploy onto architecture v2 as authored,
+ * or `undefined` when it can: v2 needs a named `webhookSecret` so the
+ * control plane can verify `X-PagerDuty-Signature` before any compute starts.
+ */
+export declare function pagerDutyChannelArchitectureError(definition: object): string | undefined;
+/**
+ * The route policy for a PagerDuty v3 webhook whose secret is named: any
+ * `v1=` entry of `X-PagerDuty-Signature` must be the body's HMAC under the
+ * env var / deployment secret `secretName`, so both of a rotating pair of
+ * secrets verify. Being an {@link hmacSignatureAuth} policy, `deploy`
+ * writes it into the manifest and the control plane runs the same check
+ * at ingestion.
+ */
+export declare function pagerDutyWebhookSignatureAuth(secretName: string): AuthPolicy;
+export declare function pagerdutyChannel(options?: PagerDutyChannelOptions): ChannelDefinition<PagerDutyChannelState>;
+/** The slice of a discovered agent mount that {@link findPagerDutyChannelTargets} reads. */
+export interface PagerDutyAgentMountLike {
+    slug: string;
+    project: {
+        channels: Array<{
+            id: string;
+            definition: {
+                meta?: {
+                    kind?: string;
+                    pagerdutyWebhookEvents?: readonly string[];
+                };
+                routes?: ReadonlyArray<{
+                    method: string;
+                    path: string;
+                }>;
+            };
+        }>;
+    };
+}
+export interface PagerDutyChannelTarget {
+    slug: string;
+    channelId: string;
+    /** Route path under the channel (default `/`). */
+    routePath: string;
+    events: string[];
+}
+/** Every mounted `pagerdutyChannel()`, for `bdk pagerduty replay` and `events`. */
+export declare function findPagerDutyChannelTargets(mounts: ReadonlyArray<PagerDutyAgentMountLike>): PagerDutyChannelTarget[];
+//# sourceMappingURL=pagerduty-channel.d.ts.map

package/dist/channels/pagerduty/pagerduty-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagerduty-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/pagerduty-channel.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAe,MAAM,gBAAgB,CAAC;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAahF,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAI1D,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GACjB,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAUlF;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAe3F;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWxF;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAO5E;AAmCD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,CAAC,qBAAqB,CAAC,CA4D1C;AAED,4FAA4F;AAC5F,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QACP,QAAQ,EAAE,KAAK,CAAC;YACd,EAAE,EAAE,MAAM,CAAC;YACX,UAAU,EAAE;gBACV,IAAI,CAAC,EAAE;oBAAE,IAAI,CAAC,EAAE,MAAM,CAAC;oBAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;iBAAE,CAAC;gBACrE,MAAM,CAAC,EAAE,aAAa,CAAC;oBAAE,MAAM,EAAE,MAAM,CAAC;oBAAC,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAC,CAAC;aAC1D,CAAC;SACH,CAAC,CAAC;KACJ,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC7C,sBAAsB,EAAE,CAkB1B"}

package/dist/channels/pagerduty/pagerduty-channel.js

@@ -0,0 +1,195 @@
+import * as z from "zod/v4";
+import { allowAll, defineChannel, hmacSignatureAuth, localDevStrict, loopbackOnly, POST, } from "../../channels.js";
+import { withPropagatingBackgroundErrors } from "../../internal/channel-dispatch.js";
+import { normalizeIdentity } from "../../internal/continuation-identity.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import { replayCatchRequest } from "../../internal/hosted-catch.js";
+import { AGENT_SDK_CATCH_EVENT_TYPE } from "../../internal/hosted-catch-protocol.js";
+import { namedWebhookSecretArchitectureError } from "../../internal/named-webhook-secret.js";
+import { isSecretRef } from "../../types.js";
+import { buildDefaultPagerDutyEvents } from "./defaults.js";
+import { derivePagerDutyWebhookEvents, PAGERDUTY_CHANNEL_KIND } from "./events.js";
+import { handlePagerDutyWebhookRequest, PAGERDUTY_SIGNATURE_HEADER, PAGERDUTY_SIGNATURE_PREFIX, PAGERDUTY_SIGNATURE_SEPARATOR, PAGERDUTY_WEBHOOK_SECRET_ENV, } from "./pagerduty-webhook.js";
+import { PAGERDUTY_TOKEN_ENV } from "./api.js";
+import { PAGERDUTY_USER_ID_ENV, pagerDutySelfUserIdSecretName } from "./self-user.js";
+import { pagerDutySecretName, resolvePagerDutySecret } from "./secrets.js";
+import { emptyPagerDutyChannelState } from "./state.js";
+const pagerDutyChannelOptionsByDefinition = new WeakMap();
+export function getPagerDutyChannelOptions(definition) {
+    return pagerDutyChannelOptionsByDefinition.get(definition);
+}
+/**
+ * Deployment secrets the channel reads in the guest that must each be set:
+ * a named `selfUserIds`, `token`, or `from` secret. `deploy` declares them
+ * so an unset one is flagged instead of the agent waking on its own echoes
+ * or failing its write-backs.
+ */
+export function pagerDutyChannelCredentialSecretNames(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined) {
+        return [];
+    }
+    return [
+        ...(options.selfUserIds === undefined ? [] : [pagerDutySelfUserIdSecretName(options)]),
+        ...(isSecretRef(options.token) ? [options.token.secretName] : []),
+        ...(isSecretRef(options.from) ? [options.from.secretName] : []),
+    ].filter((name) => name !== undefined);
+}
+/**
+ * Deployment secrets of which at least one must be set: with `selfUserIds`
+ * omitted, the agent's user comes from `PAGERDUTY_USER_ID` or is inferred
+ * from the channel's token. `deploy` warns when neither is set. A token
+ * authored in code always infers, so it needs no warning.
+ */
+export function pagerDutyChannelSecretAlternatives(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined || options.selfUserIds !== undefined) {
+        return [];
+    }
+    const tokenName = pagerDutySecretName(options.token, PAGERDUTY_TOKEN_ENV);
+    if (tokenName === undefined) {
+        return [];
+    }
+    return [
+        {
+            names: [PAGERDUTY_USER_ID_ENV, tokenName],
+            unsetEffect: `the PagerDuty channel cannot tell the agent's own actions apart, so echo skip is off (set ${PAGERDUTY_USER_ID_ENV}, or ${tokenName} to infer it)`,
+        },
+    ];
+}
+/**
+ * Why a `pagerdutyChannel` cannot deploy onto architecture v2 as authored,
+ * or `undefined` when it can: v2 needs a named `webhookSecret` so the
+ * control plane can verify `X-PagerDuty-Signature` before any compute starts.
+ */
+export function pagerDutyChannelArchitectureError(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined) {
+        return undefined;
+    }
+    return namedWebhookSecretArchitectureError({
+        option: "pagerdutyChannel webhookSecret",
+        webhookSecret: options.webhookSecret,
+        envName: PAGERDUTY_WEBHOOK_SECRET_ENV,
+        verifies: "X-PagerDuty-Signature",
+    });
+}
+/**
+ * The route policy for a PagerDuty v3 webhook whose secret is named: any
+ * `v1=` entry of `X-PagerDuty-Signature` must be the body's HMAC under the
+ * env var / deployment secret `secretName`, so both of a rotating pair of
+ * secrets verify. Being an {@link hmacSignatureAuth} policy, `deploy`
+ * writes it into the manifest and the control plane runs the same check
+ * at ingestion.
+ */
+export function pagerDutyWebhookSignatureAuth(secretName) {
+    return hmacSignatureAuth({
+        header: PAGERDUTY_SIGNATURE_HEADER,
+        secret: secretName,
+        prefix: PAGERDUTY_SIGNATURE_PREFIX,
+        separator: PAGERDUTY_SIGNATURE_SEPARATOR,
+    });
+}
+/**
+ * Default route auth for the resolved webhook secret, the same postures as
+ * the SCM channels: a named secret is the route policy (and the control
+ * plane's catch check); a literal or getter keeps the check in the handler
+ * behind `allowAll()`.
+ *
+ * An omitted `webhookSecret` names `PAGERDUTY_WEBHOOK_SECRET`, so a
+ * zero-config channel deploys with the control plane verifying against
+ * that deployment secret. While it is unset (a fresh local checkout), the
+ * route keeps the no-secret posture: loopback-strict, and `--dev` admits
+ * loopback. Both are read per request: channel modules construct at import,
+ * and a hosted deployment receives its secrets per request.
+ */
+function defaultPagerDutyRouteAuth(webhookSecret, usesDefaultSecret) {
+    if (isSecretRef(webhookSecret)) {
+        const signature = pagerDutyWebhookSignatureAuth(webhookSecret.secretName);
+        if (!usesDefaultSecret) {
+            return [signature];
+        }
+        const whileUnset = (request, info) => {
+            if (resolvePagerDutySecret(webhookSecret, PAGERDUTY_WEBHOOK_SECRET_ENV) !== undefined) {
+                return null;
+            }
+            return (isDevMode() ? loopbackOnly() : localDevStrict())(request, info);
+        };
+        return [signature, whileUnset];
+    }
+    return [allowAll()];
+}
+export function pagerdutyChannel(options = {}) {
+    const routePath = options.path ?? "/";
+    // Always named, never read here: it deploys like an authored
+    // `{ secretName: "PAGERDUTY_WEBHOOK_SECRET" }` whether or not the shell
+    // that runs `deploy` has the value.
+    const usesDefaultSecret = options.webhookSecret === undefined;
+    const webhookSecret = options.webhookSecret ?? { secretName: PAGERDUTY_WEBHOOK_SECRET_ENV };
+    const auth = options.auth ?? defaultPagerDutyRouteAuth(webhookSecret, usesDefaultSecret);
+    const channelOptions = { ...options, webhookSecret };
+    if (channelOptions.continuation !== undefined) {
+        channelOptions.continuation = normalizeIdentity(channelOptions.continuation, PAGERDUTY_CHANNEL_KIND);
+    }
+    const definition = defineChannel({
+        auth,
+        state: emptyPagerDutyChannelState(),
+        events: { ...buildDefaultPagerDutyEvents(channelOptions), ...options.events },
+        onStart: options.onStart,
+        onStop: options.onStop,
+        meta: {
+            kind: PAGERDUTY_CHANNEL_KIND,
+            pagerdutyWebhookEvents: derivePagerDutyWebhookEvents(channelOptions),
+        },
+        routes: [
+            POST(routePath, {
+                bodySchema: z.unknown(),
+                description: "PagerDuty v3 webhook ingress",
+                handler: async (request, args) => handlePagerDutyWebhookRequest({ options: channelOptions, request, args }),
+            }),
+        ],
+    });
+    pagerDutyChannelOptionsByDefinition.set(definition, channelOptions);
+    attachHostedAdmissionAdapter(definition, {
+        kind: PAGERDUTY_CHANNEL_KIND,
+        prepareArgs: withPropagatingBackgroundErrors,
+        dispatch: async ({ channelId, eventType, payload, deliveryId, args }) => {
+            // Hosted deliveries are http.request envelopes the control plane
+            // already verified with the deployment secret and stamped with the
+            // incident's key. Replay into the route handler, which verifies
+            // X-PagerDuty-Signature again and runs the echo skip.
+            if (eventType !== AGENT_SDK_CATCH_EVENT_TYPE) {
+                return Response.json({ ok: false, error: "unsupported_pagerduty_delivery" }, { status: 400 });
+            }
+            return replayCatchRequest({
+                channelId: channelId ?? PAGERDUTY_CHANNEL_KIND,
+                deliveryId,
+                routes: definition.routes ?? [],
+                payload,
+                args,
+            });
+        },
+    });
+    return definition;
+}
+/** Every mounted `pagerdutyChannel()`, for `bdk pagerduty replay` and `events`. */
+export function findPagerDutyChannelTargets(mounts) {
+    const targets = [];
+    for (const { slug, project } of mounts) {
+        for (const channel of project.channels) {
+            const meta = channel.definition.meta;
+            if (meta?.kind !== PAGERDUTY_CHANNEL_KIND) {
+                continue;
+            }
+            const postRoute = (channel.definition.routes ?? []).find((route) => route.method === "POST");
+            targets.push({
+                slug,
+                channelId: channel.id,
+                routePath: postRoute?.path ?? "/",
+                events: [...(meta.pagerdutyWebhookEvents ?? [])],
+            });
+        }
+    }
+    return targets;
+}

package/dist/channels/pagerduty/pagerduty-webhook.d.ts

@@ -0,0 +1,70 @@
+import type { ChannelHandlerArgs } from "../../types.js";
+import type { PagerDutyChannelOptions, PagerDutyEventContext, PagerDutyWebhookDelivery } from "./types.js";
+/** Env var / deployment secret an omitted `webhookSecret` falls back to. */
+export declare const PAGERDUTY_WEBHOOK_SECRET_ENV = "PAGERDUTY_WEBHOOK_SECRET";
+/** Header PagerDuty signs v3 deliveries with: `v1=<hex>[,v1=<hex>…]`. */
+export declare const PAGERDUTY_SIGNATURE_HEADER = "x-pagerduty-signature";
+export declare const PAGERDUTY_SIGNATURE_PREFIX = "v1=";
+/** Separator between signatures while a subscription's secret rotates. */
+export declare const PAGERDUTY_SIGNATURE_SEPARATOR = ",";
+/**
+ * The secret's value for the handler's own signature check, read now: an
+ * omitted field names `PAGERDUTY_WEBHOOK_SECRET` (hosted, the addressed
+ * installation's secret), and an authored name never falls back to it.
+ */
+export declare function resolvePagerDutyWebhookSecret(options: Pick<PagerDutyChannelOptions, "webhookSecret">): string | undefined;
+/** One `X-PagerDuty-Signature` entry for a raw body: `v1=<hex>`. */
+export declare function signPagerDutyWebhookBody(input: {
+    rawBody: string | Uint8Array;
+    secret: string;
+}): string;
+/**
+ * True when any `v1=` entry in the header is the body's HMAC-SHA256 under
+ * any secret `secret` holds. `secret` is the named secret's value: one
+ * signing secret, or one per line when several subscriptions sign the
+ * route. Every (secret, entry) pair is compared in constant time with no
+ * early exit; malformed entries never match, and a missing header is a
+ * plain `false`.
+ */
+export declare function verifyPagerDutyWebhookSignature(input: {
+    rawBody: string | Uint8Array;
+    signatureHeader: string | null | undefined;
+    secret: string;
+}): boolean;
+/**
+ * True when the event is the agent's own action echoed back: its `agent`
+ * is a PagerDuty user the agent acts as. Service integrations and
+ * PagerDuty itself never count, so an alert the agent's own monitor opened
+ * still dispatches.
+ */
+export declare function isPagerDutySelfEcho(ctx: Pick<PagerDutyEventContext, "agent">, selfUserIds: ReadonlySet<string>): boolean;
+/**
+ * Accept a raw v3 body. The event type comes from the signed body's
+ * `event.event_type`, never from a header, so a captured delivery cannot be
+ * re-dispatched as another event.
+ */
+export declare function parsePagerDutyWebhookPayload(payload: unknown): PagerDutyWebhookDelivery | null;
+export declare function parsePagerDutyEventContext(delivery: PagerDutyWebhookDelivery): Omit<PagerDutyEventContext, "host" | "artifacts" | "send" | "pagerduty"> | null;
+/**
+ * Run the authored hooks for one verified PagerDuty delivery and `send()`
+ * the turn. Callers own delivery auth: the HTTP route verifies
+ * `X-PagerDuty-Signature`; hosted admission arrives verified. The v2
+ * mailbox is stamped upstream (local CP or hosted ingress), never here.
+ */
+export declare function dispatchPagerDutyWebhook(input: {
+    options: PagerDutyChannelOptions;
+    delivery: PagerDutyWebhookDelivery;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+/**
+ * HTTP entry for one agent's PagerDuty channel: the `X-PagerDuty-Signature`
+ * check when a secret is configured, then {@link dispatchPagerDutyWebhook}.
+ * Without a secret the route auth owns admission (`serve --dev` admits
+ * loopback only; production stays loopback-strict).
+ */
+export declare function handlePagerDutyWebhookRequest(input: {
+    options: PagerDutyChannelOptions;
+    request: Request;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+//# sourceMappingURL=pagerduty-webhook.d.ts.map

package/dist/channels/pagerduty/pagerduty-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagerduty-webhook.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/pagerduty-webhook.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAiC,MAAM,gBAAgB,CAAC;AA0BxF,OAAO,KAAK,EACV,uBAAuB,EAEvB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAChD,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,eAAe,CAAC,GACtD,MAAM,GAAG,SAAS,CAEpB;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAYV;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,EACzC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,wBAAwB,GAAG,IAAI,CAO9F;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,wBAAwB,GACjC,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,IAAI,CAmBjF;AA+DD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,OAAO,EAAE,uBAAuB,CAAC;IACjC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2FpB;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,KAAK,EAAE;IACzD,OAAO,EAAE,uBAAuB,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkCpB"}

package/dist/channels/pagerduty/pagerduty-webhook.js

@@ -0,0 +1,280 @@
+import { createHmac } from "node:crypto";
+import { acknowledgeTask, isTaskDispatch, skipped, turnStarted, } from "../../internal/channel-dispatch.js";
+import { continuationSource, mintClaim } from "../../internal/continuation-identity.js";
+import { hmacSignatureMatchesAny, parseHmacSecrets } from "../../internal/hmac-secret-values.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
+import { defaultPagerDutyIncidentDispatch, defaultPagerDutyIncidentMessage, defaultPagerDutyTitle, } from "./defaults.js";
+import { isPagerDutyIncidentLifecycleEvent, PAGERDUTY_CHANNEL_KIND, PAGERDUTY_NOTE_EVENTS, PAGERDUTY_RESPONDER_EVENTS, } from "./events.js";
+import { asNonEmptyString, pagerDutyAccountSubdomain, pagerDutyEventIncident, pagerDutyEventRecord, pagerDutyIncidentFromData, pagerDutyNoteFromData, pagerDutyReference, pagerDutyResponderFromData, } from "./payload.js";
+import { pagerDutyChannelClient } from "./api.js";
+import { resolvePagerDutySecret } from "./secrets.js";
+import { resolvePagerDutySelfUserIds } from "./self-user.js";
+import { pagerDutyChannelStateForEvent } from "./state.js";
+/** Env var / deployment secret an omitted `webhookSecret` falls back to. */
+export const PAGERDUTY_WEBHOOK_SECRET_ENV = "PAGERDUTY_WEBHOOK_SECRET";
+/** Header PagerDuty signs v3 deliveries with: `v1=<hex>[,v1=<hex>…]`. */
+export const PAGERDUTY_SIGNATURE_HEADER = "x-pagerduty-signature";
+export const PAGERDUTY_SIGNATURE_PREFIX = "v1=";
+/** Separator between signatures while a subscription's secret rotates. */
+export const PAGERDUTY_SIGNATURE_SEPARATOR = ",";
+/**
+ * The secret's value for the handler's own signature check, read now: an
+ * omitted field names `PAGERDUTY_WEBHOOK_SECRET` (hosted, the addressed
+ * installation's secret), and an authored name never falls back to it.
+ */
+export function resolvePagerDutyWebhookSecret(options) {
+    return resolvePagerDutySecret(options.webhookSecret, PAGERDUTY_WEBHOOK_SECRET_ENV);
+}
+/** One `X-PagerDuty-Signature` entry for a raw body: `v1=<hex>`. */
+export function signPagerDutyWebhookBody(input) {
+    return `${PAGERDUTY_SIGNATURE_PREFIX}${createHmac("sha256", input.secret).update(input.rawBody).digest("hex")}`;
+}
+/**
+ * True when any `v1=` entry in the header is the body's HMAC-SHA256 under
+ * any secret `secret` holds. `secret` is the named secret's value: one
+ * signing secret, or one per line when several subscriptions sign the
+ * route. Every (secret, entry) pair is compared in constant time with no
+ * early exit; malformed entries never match, and a missing header is a
+ * plain `false`.
+ */
+export function verifyPagerDutyWebhookSignature(input) {
+    const parsed = parseHmacSecrets(input.secret);
+    if (input.signatureHeader === null || input.signatureHeader === undefined || !parsed.ok) {
+        return false;
+    }
+    return hmacSignatureMatchesAny({
+        body: input.rawBody,
+        presented: input.signatureHeader,
+        secrets: parsed.secrets,
+        prefix: PAGERDUTY_SIGNATURE_PREFIX,
+        separator: PAGERDUTY_SIGNATURE_SEPARATOR,
+    });
+}
+/**
+ * True when the event is the agent's own action echoed back: its `agent`
+ * is a PagerDuty user the agent acts as. Service integrations and
+ * PagerDuty itself never count, so an alert the agent's own monitor opened
+ * still dispatches.
+ */
+export function isPagerDutySelfEcho(ctx, selfUserIds) {
+    const agent = ctx.agent;
+    if (agent === undefined || selfUserIds.size === 0) {
+        return false;
+    }
+    if (agent.type !== undefined && agent.type !== "user_reference" && agent.type !== "user") {
+        return false;
+    }
+    return selfUserIds.has(agent.id);
+}
+/**
+ * Accept a raw v3 body. The event type comes from the signed body's
+ * `event.event_type`, never from a header, so a captured delivery cannot be
+ * re-dispatched as another event.
+ */
+export function parsePagerDutyWebhookPayload(payload) {
+    const event = pagerDutyEventRecord(payload);
+    const eventType = asNonEmptyString(event?.event_type);
+    if (event === undefined || eventType === undefined) {
+        return null;
+    }
+    return { eventType, payload: payload };
+}
+export function parsePagerDutyEventContext(delivery) {
+    const event = pagerDutyEventRecord(delivery.payload);
+    const eventId = asNonEmptyString(event?.id);
+    if (event === undefined || eventId === undefined) {
+        return null;
+    }
+    const incident = pagerDutyEventIncident(event);
+    return {
+        deliveryId: delivery.deliveryId,
+        eventId,
+        eventType: delivery.eventType,
+        resourceType: asNonEmptyString(event.resource_type),
+        occurredAt: asNonEmptyString(event.occurred_at),
+        agent: pagerDutyReference(event.agent),
+        incidentId: incident?.id,
+        incidentKey: incident?.incidentKey,
+        accountSubdomain: pagerDutyAccountSubdomain(event),
+        payload: event,
+    };
+}
+function invalidPayload(error) {
+    return Response.json({ ok: false, error }, { status: 400 });
+}
+async function applyDispatch(input) {
+    const extra = { event: input.ctx.eventType };
+    if (input.dispatch === null) {
+        return skipped("not_dispatched", extra);
+    }
+    if (isTaskDispatch(input.dispatch)) {
+        return acknowledgeTask(input.args, PAGERDUTY_CHANNEL_KIND, input.dispatch, extra);
+    }
+    const ctx = input.ctx;
+    const state = pagerDutyChannelStateForEvent({
+        eventType: ctx.eventType,
+        eventId: ctx.eventId,
+        incidentId: ctx.incidentId,
+        incidentNumber: input.incidentNumber,
+        incidentKey: ctx.incidentKey,
+        serviceId: input.serviceId,
+        deliveryId: ctx.deliveryId,
+        occurredAt: ctx.occurredAt,
+    });
+    // v1 agents (omitted continuation resolves to `none/v1`) keep one
+    // engine-minted conversation per incident; v2 takes the CP stamp.
+    const engineToken = continuationSource(input.options.continuation, PAGERDUTY_CHANNEL_KIND) === "engine" &&
+        ctx.incidentId !== undefined
+        ? mintClaim({
+            type: "pagerduty-incident",
+            resource: { incidentId: ctx.incidentId },
+        }).slice("cont:".length)
+        : undefined;
+    const turn = {
+        auth: input.dispatch.auth,
+        title: input.dispatch.title ?? input.title,
+        state: state,
+        refreshState: state,
+    };
+    if (engineToken !== undefined) {
+        turn.continuationToken = engineToken;
+    }
+    if (input.options.cloud !== undefined) {
+        turn.cloud = input.options.cloud;
+    }
+    const session = await input.args.send([input.dispatch.message ?? input.message, ...(input.dispatch.context ?? [])].join("\n"), turn);
+    return turnStarted(session);
+}
+/**
+ * Run the authored hooks for one verified PagerDuty delivery and `send()`
+ * the turn. Callers own delivery auth: the HTTP route verifies
+ * `X-PagerDuty-Signature`; hosted admission arrives verified. The v2
+ * mailbox is stamped upstream (local CP or hosted ingress), never here.
+ */
+export async function dispatchPagerDutyWebhook(input) {
+    const parsed = parsePagerDutyEventContext(input.delivery);
+    if (parsed === null) {
+        return invalidPayload("invalid_pagerduty_payload");
+    }
+    const args = input.args;
+    const ctx = {
+        ...parsed,
+        pagerduty: pagerDutyChannelClient(input.options),
+        host: args.host,
+        artifacts: args.artifacts,
+        send: args.send,
+    };
+    const eventType = ctx.eventType;
+    if (eventType === "pagey.ping") {
+        return skipped("ping");
+    }
+    if (isPagerDutySelfEcho(ctx, await resolvePagerDutySelfUserIds({ options: input.options }))) {
+        return skipped("self_echo", { event: eventType, agent: ctx.agent?.id });
+    }
+    const data = ctx.payload.data;
+    if (isPagerDutyIncidentLifecycleEvent(eventType)) {
+        const incident = pagerDutyIncidentFromData(data);
+        if (incident === undefined) {
+            return invalidPayload("invalid_pagerduty_incident_payload");
+        }
+        const event = { eventType, action: eventType.slice("incident.".length), incident };
+        const dispatch = input.options.onIncident === undefined
+            ? defaultPagerDutyIncidentDispatch(ctx, event)
+            : await input.options.onIncident(ctx, event);
+        return applyDispatch({
+            options: input.options,
+            args,
+            ctx,
+            dispatch,
+            message: defaultPagerDutyIncidentMessage(ctx, event),
+            title: defaultPagerDutyTitle(ctx, incident),
+            incidentNumber: incident.number,
+            serviceId: incident.service?.id,
+        });
+    }
+    if (PAGERDUTY_NOTE_EVENTS.includes(eventType)) {
+        if (input.options.onNote === undefined) {
+            return skipped("no_handler", { event: eventType });
+        }
+        const note = pagerDutyNoteFromData(data);
+        if (note === undefined) {
+            return invalidPayload("invalid_pagerduty_note_payload");
+        }
+        return applyDispatch({
+            options: input.options,
+            args,
+            ctx,
+            dispatch: await input.options.onNote(ctx, note),
+            message: `PagerDuty note on incident ${note.incident.id}:\n${note.content}`,
+            title: defaultPagerDutyTitle(ctx),
+        });
+    }
+    if (PAGERDUTY_RESPONDER_EVENTS.includes(eventType)) {
+        if (input.options.onResponder === undefined) {
+            return skipped("no_handler", { event: eventType });
+        }
+        const responder = pagerDutyResponderFromData(eventType, data);
+        if (responder === undefined) {
+            return invalidPayload("invalid_pagerduty_responder_payload");
+        }
+        return applyDispatch({
+            options: input.options,
+            args,
+            ctx,
+            dispatch: await input.options.onResponder(ctx, responder),
+            message: `PagerDuty ${eventType} on incident ${responder.incident.id}`,
+            title: defaultPagerDutyTitle(ctx),
+        });
+    }
+    if (input.options.onEvent === undefined) {
+        return skipped("unsupported_event", { event: eventType });
+    }
+    return applyDispatch({
+        options: input.options,
+        args,
+        ctx,
+        dispatch: await input.options.onEvent(ctx, { eventType, data }),
+        message: `PagerDuty ${eventType} event`,
+        title: defaultPagerDutyTitle(ctx),
+    });
+}
+/**
+ * HTTP entry for one agent's PagerDuty channel: the `X-PagerDuty-Signature`
+ * check when a secret is configured, then {@link dispatchPagerDutyWebhook}.
+ * Without a secret the route auth owns admission (`serve --dev` admits
+ * loopback only; production stays loopback-strict).
+ */
+export async function handlePagerDutyWebhookRequest(input) {
+    const bodyText = await input.request.text();
+    const secret = resolvePagerDutyWebhookSecret(input.options);
+    if (secret !== undefined &&
+        !verifyPagerDutyWebhookSignature({
+            rawBody: bodyText,
+            signatureHeader: input.request.headers.get(PAGERDUTY_SIGNATURE_HEADER),
+            secret,
+        })) {
+        return Response.json({ ok: false, error: "invalid_signature" }, { status: 401 });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(bodyText);
+    }
+    catch {
+        return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+    }
+    const delivery = parsePagerDutyWebhookPayload(payload);
+    if (delivery === null) {
+        return invalidPayload("invalid_pagerduty_payload");
+    }
+    delivery.deliveryId = input.request.headers.get("x-webhook-id") ?? undefined;
+    return dispatchPagerDutyWebhook({
+        options: input.options,
+        delivery,
+        args: bindLocalIngressSend(input.args, {
+            identity: input.options.continuation,
+            kind: PAGERDUTY_CHANNEL_KIND,
+            eventType: delivery.eventType,
+            payload: delivery.payload,
+        }),
+    });
+}

package/dist/channels/pagerduty/payload.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Typed views over a PagerDuty v3 webhook body. Every reader tolerates
+ * missing optional fields and returns `undefined` for a shape it does not
+ * recognize, so a new PagerDuty field never fails a delivery.
+ */
+import type { PagerDutyIncident, PagerDutyIncidentNote, PagerDutyReference, PagerDutyResponderEvent } from "./types.js";
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function asNonEmptyString(value: unknown): string | undefined;
+/** The delivery's `event` record, or `undefined` when the body is not a v3 event. */
+export declare function pagerDutyEventRecord(payload: unknown): Record<string, unknown> | undefined;
+export declare function pagerDutyReference(value: unknown): PagerDutyReference | undefined;
+/** `data` of a lifecycle event: the full incident. */
+export declare function pagerDutyIncidentFromData(data: unknown): PagerDutyIncident | undefined;
+/** `data` of `incident.annotated`. */
+export declare function pagerDutyNoteFromData(data: unknown): PagerDutyIncidentNote | undefined;
+/** `data` of `incident.responder.added` / `.replied`. */
+export declare function pagerDutyResponderFromData(eventType: string, data: unknown): PagerDutyResponderEvent | undefined;
+/**
+ * The incident any incident event names: `data` itself for lifecycle
+ * events, `data.incident` for sub-resources. Mirrors the continuation
+ * selector, so a hook's `ctx.incidentId` names the session's incident.
+ */
+export declare function pagerDutyEventIncident(event: Record<string, unknown>): {
+    id: string;
+    incidentKey?: string;
+} | undefined;
+/**
+ * The account subdomain (`acme` for `acme.pagerduty.com` or
+ * `acme.eu.pagerduty.com`) from the first PagerDuty web URL the event
+ * carries: the incident's, the agent's, or the data's own.
+ */
+export declare function pagerDutyAccountSubdomain(event: Record<string, unknown>): string | undefined;
+//# sourceMappingURL=payload.d.ts.map

package/dist/channels/pagerduty/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/payload.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAErB,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAI5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEnE;AAMD,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAG1F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAYjF;AAYD,sDAAsD;AACtD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAsBtF;AAUD,sCAAsC;AACtC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAYtF;AAED,yDAAyD;AACzD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,GACZ,uBAAuB,GAAG,SAAS,CAcrC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAUlD;AAID;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAuB5F"}