@cursor/july 0.1.102 → 0.1.104

package/src/channels/bitbucket/bitbucket-webhook.ts

@@ -0,0 +1,576 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  acknowledgeTask,
+  isTaskDispatch,
+  skipped,
+  turnStarted,
+} from "../../internal/channel-dispatch.js";
+import { continuationSource } from "../../internal/continuation-identity.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
+import type {
+  AgentCloudOptions,
+  ChannelHandlerArgs,
+  JsonValue,
+} from "../../types.js";
+import type { BitbucketProxyTransport } from "./api.js";
+import {
+  asNonEmptyString,
+  asPositiveInt,
+  asRecord,
+  bitbucketCommentFromPayload,
+  bitbucketPullRequestFromPayload,
+  bitbucketPullRequestRecord,
+  bitbucketPullRequestUrl,
+  bitbucketPushFromPayload,
+  bitbucketRepositoryFromPayload,
+  bitbucketUser,
+  buildBitbucketBinding,
+} from "./binding.js";
+import {
+  defaultBitbucketPullRequestDispatch,
+  defaultBitbucketPullRequestMessage,
+  defaultBitbucketTitle,
+} from "./defaults.js";
+import {
+  BITBUCKET_CHANNEL_KIND,
+  BITBUCKET_PULL_REQUEST_EVENTS,
+  normalizeBitbucketEventKey,
+} from "./events.js";
+import {
+  type BitbucketChannelState,
+  bitbucketChannelStateForEvent,
+} from "./state.js";
+import type {
+  BitbucketChannelOptions,
+  BitbucketDispatch,
+  BitbucketEventContext,
+  BitbucketPullRequestEvent,
+  BitbucketTurnDispatch,
+  BitbucketWebhookDelivery,
+} from "./types.js";
+
+/** `BITBUCKET_WEBHOOK_SECRET` fallback for {@link BitbucketChannelOptions.webhookSecret}. */
+export function envBitbucketWebhookSecret(): string | undefined {
+  const value = process.env.BITBUCKET_WEBHOOK_SECRET?.trim();
+  return value === undefined || value === "" ? undefined : value;
+}
+
+export function resolveBitbucketWebhookSecret(
+  options: Pick<BitbucketChannelOptions, "webhookSecret">
+): string | undefined {
+  const authored =
+    typeof options.webhookSecret === "function"
+      ? options.webhookSecret()
+      : options.webhookSecret;
+  const trimmed = authored?.trim();
+  return trimmed === undefined || trimmed === ""
+    ? envBitbucketWebhookSecret()
+    : trimmed;
+}
+
+const SIGNATURE_PREFIX = "sha256=";
+
+/** The `X-Hub-Signature` value Bitbucket sends for a raw body. */
+export function signBitbucketWebhookBody(
+  rawBody: string | Buffer,
+  secret: string
+): string {
+  return `${SIGNATURE_PREFIX}${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+}
+
+/**
+ * Both dialects sign the raw body with HMAC-SHA256 in `X-Hub-Signature`
+ * (`sha256=<hex>`, GitHub-shaped). Constant-time compare; a missing or
+ * malformed header is a plain `false`.
+ */
+export function verifyBitbucketWebhookSignature(
+  rawBody: string | Buffer,
+  signatureHeader: string | null | undefined,
+  secret: string
+): boolean {
+  if (
+    signatureHeader === null ||
+    signatureHeader === undefined ||
+    !signatureHeader.startsWith(SIGNATURE_PREFIX)
+  ) {
+    return false;
+  }
+  const provided = Buffer.from(signatureHeader, "utf8");
+  const computed = Buffer.from(
+    signBitbucketWebhookBody(rawBody, secret),
+    "utf8"
+  );
+  return (
+    provided.length === computed.length && timingSafeEqual(provided, computed)
+  );
+}
+
+/**
+ * Accept a raw Bitbucket payload plus the event key. The key comes from
+ * `X-Event-Key` (HTTP) or the hosted envelope; Data Center bodies also carry
+ * it as `eventKey`. Data Center keys are normalized to the Cloud vocabulary.
+ *
+ * The body's `eventKey` is authoritative when present: `X-Hub-Signature`
+ * covers the body but not the header, so a captured signed Data Center
+ * delivery must not be re-dispatched as a different event by rewriting the
+ * header. A header that disagrees with the signed body rejects the delivery.
+ *
+ * Cloud bodies carry no `eventKey`, but each event family has a signed
+ * discriminator object (`comment`, `approval`, `changes_request`, `push`).
+ * A header naming a family the body does not match — e.g. a signed
+ * `pullrequest:comment_created` body replayed as `pullrequest:created` —
+ * is rejected the same way. `created` vs `updated` bodies are shape-identical
+ * and cannot be told apart without the key.
+ */
+export function parseBitbucketWebhookPayload(
+  payload: unknown,
+  eventKey?: string | null
+): BitbucketWebhookDelivery | null {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return null;
+  }
+  const fromBody = asNonEmptyString(record.eventKey);
+  const fromHeader = eventKey?.trim() || undefined;
+  if (
+    fromBody !== undefined &&
+    fromHeader !== undefined &&
+    normalizeBitbucketEventKey(fromBody) !==
+      normalizeBitbucketEventKey(fromHeader)
+  ) {
+    return null;
+  }
+  const raw = fromBody ?? fromHeader;
+  if (raw === undefined) {
+    return null;
+  }
+  const eventType = normalizeBitbucketEventKey(raw);
+  if (
+    fromBody === undefined &&
+    bitbucketCloudEventFamily(eventType) !== cloudBodyFamily(record)
+  ) {
+    return null;
+  }
+  return {
+    eventType,
+    rawEventType: raw,
+    payload: record,
+  };
+}
+
+type BitbucketCloudEventFamily =
+  | "approval"
+  | "changes_request"
+  | "comment"
+  | "other"
+  | "pull_request"
+  | "push";
+
+/** Event family a Cloud key belongs to, by its signed body discriminator. */
+function bitbucketCloudEventFamily(
+  eventType: string
+): BitbucketCloudEventFamily {
+  if (eventType.startsWith("repo:")) {
+    return eventType === "repo:push" ? "push" : "other";
+  }
+  if (!eventType.startsWith("pullrequest:")) {
+    return "other";
+  }
+  const action = eventType.slice("pullrequest:".length);
+  if (action.startsWith("comment_")) {
+    return "comment";
+  }
+  if (action === "approved" || action === "unapproved") {
+    return "approval";
+  }
+  if (action.startsWith("changes_request_")) {
+    return "changes_request";
+  }
+  return "pull_request";
+}
+
+/** Event family a Cloud body proves by the discriminator object it carries. */
+function cloudBodyFamily(
+  record: Record<string, unknown>
+): BitbucketCloudEventFamily {
+  if (asRecord(record.comment) !== undefined) {
+    return "comment";
+  }
+  if (asRecord(record.approval) !== undefined) {
+    return "approval";
+  }
+  if (asRecord(record.changes_request) !== undefined) {
+    return "changes_request";
+  }
+  if (asRecord(record.push) !== undefined) {
+    return "push";
+  }
+  return asRecord(record.pullrequest) !== undefined ? "pull_request" : "other";
+}
+
+function configuredRepoAllowlist(
+  options: BitbucketChannelOptions
+): ReadonlySet<string> | undefined {
+  const repos: string[] = [];
+  if (options.repos !== undefined) {
+    repos.push(...options.repos);
+  }
+  if (typeof options.cursorAccount === "object") {
+    repos.push(...options.cursorAccount.repos);
+  }
+  const normalized = repos
+    .map((repo) =>
+      repo
+        .trim()
+        .replace(/^\/+|\/+$/g, "")
+        .toLowerCase()
+    )
+    .filter(Boolean);
+  return normalized.length === 0 ? undefined : new Set(normalized);
+}
+
+function isPullRequestEvent(eventType: string): boolean {
+  return (BITBUCKET_PULL_REQUEST_EVENTS as readonly string[]).includes(
+    eventType
+  );
+}
+
+export function parseBitbucketEventContext(
+  delivery: BitbucketWebhookDelivery
+): Omit<
+  BitbucketEventContext,
+  "host" | "artifacts" | "bitbucket" | "send"
+> | null {
+  const repository = bitbucketRepositoryFromPayload(delivery.payload);
+  if (repository === undefined) {
+    return null;
+  }
+  const pullRequestRecord = bitbucketPullRequestRecord(delivery.payload);
+  const pullRequestId = asPositiveInt(pullRequestRecord?.id);
+  return {
+    deliveryId: delivery.deliveryId,
+    eventType: delivery.eventType,
+    rawEventType: delivery.rawEventType ?? delivery.eventType,
+    repository,
+    ...(pullRequestId === undefined
+      ? {}
+      : {
+          pullRequestId,
+          pullRequestUrl: bitbucketPullRequestUrl(
+            repository,
+            pullRequestId,
+            asNonEmptyString(
+              asRecord(asRecord(pullRequestRecord?.links)?.html)?.href
+            )
+          ),
+        }),
+    payload: delivery.payload,
+    sender: bitbucketUser(delivery.payload.actor),
+  };
+}
+
+function invalidPayload(error: string): Response {
+  return Response.json({ ok: false, error }, { status: 400 });
+}
+
+async function startTurn(input: {
+  options: BitbucketChannelOptions;
+  args: ChannelHandlerArgs;
+  ctx: BitbucketEventContext;
+  message: string;
+  dispatch: BitbucketTurnDispatch;
+  cloud?: AgentCloudOptions;
+  state: BitbucketChannelState;
+}): Promise<Response> {
+  const source = continuationSource(input.options.continuation, "bitbucket");
+  const session = await input.args.send(input.message, {
+    auth: input.dispatch.auth,
+    // v1 agents (omitted continuation resolves to `none/v1`) keep one
+    // engine-minted conversation per pull request; v2 takes the CP stamp.
+    ...(source === "engine" && input.ctx.pullRequestId !== undefined
+      ? {
+          continuationToken: `bitbucket-pr:${input.ctx.repository.fullName.toLowerCase()}#${input.ctx.pullRequestId}`,
+        }
+      : {}),
+    title: input.dispatch.title ?? defaultBitbucketTitle(input.ctx),
+    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+    state: input.state as unknown as JsonValue,
+    refreshState: input.state as unknown as JsonValue,
+  });
+  return turnStarted(session);
+}
+
+async function resolveCloudOptions(
+  cloud: BitbucketChannelOptions["cloud"],
+  ctx: BitbucketEventContext,
+  pullRequest: BitbucketPullRequestEvent
+): Promise<AgentCloudOptions | undefined> {
+  if (cloud === undefined || cloud === false) {
+    return undefined;
+  }
+  if (cloud === true) {
+    const url =
+      ctx.repository.htmlUrl ??
+      (ctx.repository.dialect === "cloud"
+        ? `https://bitbucket.org/${ctx.repository.fullName}`
+        : undefined);
+    if (url === undefined) {
+      return undefined;
+    }
+    return {
+      repos: [
+        {
+          url,
+          prUrl: pullRequest.htmlUrl,
+          startingRef: pullRequest.headSha,
+        },
+      ],
+    };
+  }
+  if (typeof cloud === "function") {
+    return await cloud(ctx, pullRequest);
+  }
+  return cloud;
+}
+
+async function applyDispatch(input: {
+  options: BitbucketChannelOptions;
+  args: ChannelHandlerArgs;
+  ctx: BitbucketEventContext;
+  dispatch: BitbucketDispatch | null;
+  extra: Record<string, unknown>;
+  message: string;
+  cloud?: AgentCloudOptions;
+  headSha?: string;
+  triggeringCommentId?: number;
+}): Promise<Response> {
+  if (input.dispatch === null) {
+    return skipped("not_dispatched", input.extra);
+  }
+  if (isTaskDispatch(input.dispatch)) {
+    return acknowledgeTask(
+      input.args,
+      BITBUCKET_CHANNEL_KIND,
+      input.dispatch,
+      input.extra
+    );
+  }
+  const message = [
+    input.dispatch.message ?? input.message,
+    ...(input.dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    options: input.options,
+    args: input.args,
+    ctx: input.ctx,
+    message,
+    dispatch: input.dispatch,
+    cloud: input.cloud,
+    state: bitbucketChannelStateForEvent({
+      repository: input.ctx.repository,
+      pullRequestId: input.ctx.pullRequestId,
+      headSha: input.headSha,
+      deliveryId: input.ctx.deliveryId,
+      eventType: input.ctx.eventType,
+      triggeringCommentId: input.triggeringCommentId,
+    }),
+  });
+}
+
+/**
+ * Run the authored hooks for one Bitbucket delivery and `send()` the turn.
+ * Callers own delivery auth: the HTTP route verifies `X-Hub-Signature`;
+ * hosted admission arrives verified. The v2 mailbox is stamped upstream
+ * (local CP or hosted ingress), never here.
+ */
+export async function dispatchBitbucketWebhook(input: {
+  options: BitbucketChannelOptions;
+  delivery: BitbucketWebhookDelivery;
+  args: ChannelHandlerArgs;
+  /** Host-bound SCM-proxy transport (`cursorAccount` + `--cursor-scm-proxy`). */
+  proxy?: () => BitbucketProxyTransport | undefined;
+}): Promise<Response> {
+  const { eventType, payload } = input.delivery;
+  const parsed = parseBitbucketEventContext(input.delivery);
+  if (parsed === null) {
+    return invalidPayload("invalid_bitbucket_payload");
+  }
+  const args = input.args;
+  const ctx: BitbucketEventContext = {
+    ...parsed,
+    bitbucket: buildBitbucketBinding({
+      repository: parsed.repository,
+      proxy: input.proxy?.(),
+      token: input.options.token,
+      apiBaseUrl: input.options.apiBaseUrl,
+    }),
+    host: args.host,
+    artifacts: args.artifacts,
+    send: args.send,
+  };
+  const allowlist = configuredRepoAllowlist(input.options);
+  if (
+    allowlist !== undefined &&
+    !allowlist.has(ctx.repository.fullName.toLowerCase())
+  ) {
+    return skipped("repo_not_allowed", { repo: ctx.repository.fullName });
+  }
+  const extra = { event: eventType, rawEvent: ctx.rawEventType };
+
+  if (isPullRequestEvent(eventType)) {
+    const action = eventType.slice("pullrequest:".length);
+    const pullRequest = bitbucketPullRequestFromPayload(
+      ctx.repository,
+      payload,
+      action
+    );
+    if (pullRequest === undefined) {
+      return invalidPayload("invalid_bitbucket_pull_request_payload");
+    }
+    const dispatch =
+      input.options.onPullRequest === undefined
+        ? defaultBitbucketPullRequestDispatch(ctx, pullRequest)
+        : await input.options.onPullRequest(ctx, pullRequest);
+    return applyDispatch({
+      options: input.options,
+      args,
+      ctx,
+      dispatch,
+      extra: { ...extra, action },
+      message: defaultBitbucketPullRequestMessage(ctx, pullRequest),
+      cloud: await resolveCloudOptions(input.options.cloud, ctx, pullRequest),
+      headSha: pullRequest.headSha,
+    });
+  }
+
+  switch (eventType) {
+    case "pullrequest:comment_created": {
+      if (input.options.onPullRequestComment === undefined) {
+        return skipped("no_handler", extra);
+      }
+      const comment = bitbucketCommentFromPayload(payload);
+      const pullRequest = bitbucketPullRequestFromPayload(
+        ctx.repository,
+        payload,
+        "comment_created"
+      );
+      if (comment === undefined || pullRequest === undefined) {
+        return invalidPayload("invalid_bitbucket_comment_payload");
+      }
+      const dispatch = await input.options.onPullRequestComment(
+        ctx,
+        comment,
+        pullRequest
+      );
+      return applyDispatch({
+        options: input.options,
+        args,
+        ctx,
+        dispatch,
+        extra,
+        message: `Bitbucket comment on ${ctx.repository.fullName}#${pullRequest.id}`,
+        headSha: pullRequest.headSha,
+        triggeringCommentId: comment.id,
+      });
+    }
+    case "repo:push": {
+      if (input.options.onPush === undefined) {
+        return skipped("no_handler", extra);
+      }
+      const push = bitbucketPushFromPayload(payload);
+      if (push === undefined) {
+        return invalidPayload("invalid_bitbucket_push_payload");
+      }
+      const dispatch = await input.options.onPush(ctx, push);
+      const first = push.changes[0];
+      return applyDispatch({
+        options: input.options,
+        args,
+        ctx,
+        dispatch,
+        extra,
+        message: `Bitbucket push to ${ctx.repository.fullName}${first?.name === undefined ? "" : ` ${first.name}`}`,
+        headSha: first?.after,
+      });
+    }
+    default: {
+      if (input.options.onEvent === undefined) {
+        return skipped("unsupported_event", extra);
+      }
+      const dispatch = await input.options.onEvent(ctx, {
+        eventType,
+        rawEventType: ctx.rawEventType,
+        payload,
+      });
+      return applyDispatch({
+        options: input.options,
+        args,
+        ctx,
+        dispatch,
+        extra,
+        message: `Bitbucket ${eventType} event on ${ctx.repository.fullName}`,
+      });
+    }
+  }
+}
+
+/**
+ * HTTP entry for a single agent's Bitbucket channel: `X-Hub-Signature` HMAC
+ * when a secret is configured, then {@link dispatchBitbucketWebhook}.
+ * Without a secret the route auth owns admission (`serve --dev` admits
+ * loopback only; production stays loopback-strict).
+ */
+export async function handleBitbucketWebhookRequest(input: {
+  options: BitbucketChannelOptions;
+  request: Request;
+  args: ChannelHandlerArgs;
+  /** When true, skip the HMAC check even if a secret is configured. */
+  skipSignatureVerification?: boolean;
+  proxy?: () => BitbucketProxyTransport | undefined;
+}): Promise<Response> {
+  const bodyText = await input.request.text();
+  const secret = resolveBitbucketWebhookSecret(input.options);
+  if (secret !== undefined && input.skipSignatureVerification !== true) {
+    if (
+      !verifyBitbucketWebhookSignature(
+        bodyText,
+        input.request.headers.get("x-hub-signature"),
+        secret
+      )
+    ) {
+      return Response.json(
+        { ok: false, error: "invalid_signature" },
+        { status: 401 }
+      );
+    }
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(bodyText) as unknown;
+  } catch {
+    return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+  }
+  const delivery = parseBitbucketWebhookPayload(
+    payload,
+    input.request.headers.get("x-event-key")
+  );
+  if (delivery === null) {
+    return invalidPayload("invalid_bitbucket_payload");
+  }
+  delivery.deliveryId =
+    input.request.headers.get("x-request-uuid") ??
+    input.request.headers.get("x-request-id") ??
+    undefined;
+  return dispatchBitbucketWebhook({
+    options: input.options,
+    delivery,
+    proxy: input.proxy,
+    args: bindLocalIngressSend(input.args, {
+      identity: input.options.continuation,
+      kind: BITBUCKET_CHANNEL_KIND,
+      eventType: delivery.eventType,
+      payload: delivery.payload,
+    }),
+  });
+}