@cursor/bdk 0.2.3 → 0.2.5

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

@@ -1,509 +0,0 @@
-import { 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 { GitLabProxyTransport } from "./api.js";
-import {
-  asNonEmptyString,
-  asPositiveInt,
-  asRecord,
-  buildGitLabBinding,
-  gitlabMergeRequestFromRecord,
-  gitlabMergeRequestUrl,
-  gitlabProjectFromPayload,
-  gitlabSender,
-  gitlabUser,
-  normalizeGitLabNoteableType,
-} from "./binding.js";
-import {
-  defaultGitLabMergeRequestDispatch,
-  defaultGitLabMergeRequestMessage,
-  defaultGitLabTitle,
-} from "./defaults.js";
-import { GITLAB_CHANNEL_KIND } from "./events.js";
-import { type GitLabChannelState, gitlabChannelStateForEvent } from "./state.js";
-import type {
-  GitLabChannelOptions,
-  GitLabDispatch,
-  GitLabEventContext,
-  GitLabMergeRequestEvent,
-  GitLabNote,
-  GitLabNoteableType,
-  GitLabPipeline,
-  GitLabPush,
-  GitLabTurnDispatch,
-  GitLabWebhookDelivery,
-} from "./types.js";
-
-/** `GITLAB_WEBHOOK_SECRET` fallback for {@link GitLabChannelOptions.webhookSecret}. */
-export function envGitLabWebhookSecret(): string | undefined {
-  const value = process.env.GITLAB_WEBHOOK_SECRET?.trim();
-  return value === undefined || value === "" ? undefined : value;
-}
-
-export function resolveGitLabWebhookSecret(
-  options: Pick<GitLabChannelOptions, "webhookSecret">,
-): string | undefined {
-  const authored =
-    typeof options.webhookSecret === "function" ? options.webhookSecret() : options.webhookSecret;
-  const trimmed = authored?.trim();
-  return trimmed === undefined || trimmed === "" ? envGitLabWebhookSecret() : trimmed;
-}
-
-/**
- * GitLab sends the hook's secret verbatim in `X-Gitlab-Token` (no HMAC).
- * Constant-time compare so a reachable URL leaks nothing about the secret.
- */
-export function verifyGitLabWebhookToken(
-  headerValue: string | null | undefined,
-  secret: string,
-): boolean {
-  if (headerValue === null || headerValue === undefined) {
-    return false;
-  }
-  const received = Buffer.from(headerValue, "utf8");
-  const expected = Buffer.from(secret, "utf8");
-  return received.length === expected.length && timingSafeEqual(received, expected);
-}
-
-/**
- * Accept a raw GitLab payload. `object_kind` is the event discriminator;
- * hosted admission passes the envelope's event type, which wins when set.
- */
-export function parseGitLabWebhookPayload(
-  payload: unknown,
-  eventType?: string,
-): GitLabWebhookDelivery | null {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return null;
-  }
-  const kind = eventType?.trim() || asNonEmptyString(record.object_kind);
-  if (kind === undefined || kind === "") {
-    return null;
-  }
-  return { eventType: kind, payload: record };
-}
-
-function configuredProjectAllowlist(
-  options: GitLabChannelOptions,
-): ReadonlySet<string> | undefined {
-  const projects: string[] = [];
-  if (options.projects !== undefined) {
-    projects.push(...options.projects);
-  }
-  if (typeof options.cursorAccount === "object") {
-    projects.push(...options.cursorAccount.projects);
-  }
-  const normalized = projects
-    .map(project =>
-      project
-        .trim()
-        .replace(/^\/+|\/+$/g, "")
-        .toLowerCase(),
-    )
-    .filter(Boolean);
-  return normalized.length === 0 ? undefined : new Set(normalized);
-}
-
-function mergeRequestIidForEvent(
-  eventType: string,
-  payload: Record<string, unknown>,
-): number | undefined {
-  switch (eventType) {
-    case "merge_request":
-      return asPositiveInt(asRecord(payload.object_attributes)?.iid);
-    case "note":
-      return normalizeGitLabNoteableType(asRecord(payload.object_attributes)?.noteable_type) ===
-        "merge_request"
-        ? asPositiveInt(asRecord(payload.merge_request)?.iid)
-        : undefined;
-    case "pipeline":
-      return asPositiveInt(asRecord(payload.merge_request)?.iid);
-    default:
-      return undefined;
-  }
-}
-
-export function parseGitLabEventContext(
-  delivery: GitLabWebhookDelivery,
-): Omit<GitLabEventContext, "host" | "artifacts" | "gitlab" | "send"> | null {
-  const project = gitlabProjectFromPayload(delivery.payload);
-  if (project === undefined) {
-    return null;
-  }
-  const mergeRequestIid = mergeRequestIidForEvent(delivery.eventType, delivery.payload);
-  const mergeRequestRecord =
-    asRecord(delivery.payload.merge_request) ??
-    (delivery.eventType === "merge_request"
-      ? asRecord(delivery.payload.object_attributes)
-      : undefined);
-  return {
-    deliveryId: delivery.deliveryId,
-    eventType: delivery.eventType,
-    project,
-    ...(mergeRequestIid === undefined
-      ? {}
-      : {
-          mergeRequestIid,
-          mergeRequestUrl: gitlabMergeRequestUrl(
-            project,
-            mergeRequestIid,
-            asNonEmptyString(mergeRequestRecord?.url),
-          ),
-        }),
-    payload: delivery.payload,
-    sender: gitlabSender(delivery.payload),
-  };
-}
-
-function parseNote(payload: Record<string, unknown>): GitLabNote | undefined {
-  const attributes = asRecord(payload.object_attributes);
-  const id = asPositiveInt(attributes?.id);
-  const body = typeof attributes?.note === "string" ? attributes.note : undefined;
-  const noteableType = normalizeGitLabNoteableType(attributes?.noteable_type);
-  if (id === undefined || body === undefined || noteableType === undefined) {
-    return undefined;
-  }
-  return {
-    id,
-    body,
-    noteableType,
-    noteableId: asPositiveInt(attributes?.noteable_id),
-    url: asNonEmptyString(attributes?.url),
-    author: gitlabUser(payload.user),
-    mergeRequestIid: asPositiveInt(asRecord(payload.merge_request)?.iid),
-  };
-}
-
-function parsePush(payload: Record<string, unknown>): GitLabPush | undefined {
-  const ref = asNonEmptyString(payload.ref);
-  if (ref === undefined) {
-    return undefined;
-  }
-  const commitCount =
-    typeof payload.total_commits_count === "number" ? payload.total_commits_count : undefined;
-  return {
-    ref,
-    before: asNonEmptyString(payload.before),
-    after: asNonEmptyString(payload.after),
-    checkoutSha: asNonEmptyString(payload.checkout_sha),
-    ...(commitCount === undefined ? {} : { commitCount }),
-  };
-}
-
-function parsePipeline(payload: Record<string, unknown>): GitLabPipeline | undefined {
-  const attributes = asRecord(payload.object_attributes);
-  const id = asPositiveInt(attributes?.id);
-  if (id === undefined) {
-    return undefined;
-  }
-  return {
-    id,
-    status: asNonEmptyString(attributes?.status),
-    sha: asNonEmptyString(attributes?.sha),
-    ref: asNonEmptyString(attributes?.ref),
-    source: asNonEmptyString(attributes?.source),
-    url: asNonEmptyString(attributes?.url),
-    mergeRequestIid: asPositiveInt(asRecord(payload.merge_request)?.iid),
-  };
-}
-
-function invalidPayload(error: string): Response {
-  return Response.json({ ok: false, error }, { status: 400 });
-}
-
-async function startTurn(input: {
-  options: GitLabChannelOptions;
-  args: ChannelHandlerArgs;
-  ctx: GitLabEventContext;
-  message: string;
-  dispatch: GitLabTurnDispatch;
-  cloud?: AgentCloudOptions;
-  state: GitLabChannelState;
-}): Promise<Response> {
-  const source = continuationSource(input.options.continuation, "gitlab");
-  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 merge request; v2 takes the CP stamp.
-    ...(source === "engine" && input.ctx.mergeRequestIid !== undefined
-      ? {
-          continuationToken: `gitlab-mr:${input.ctx.project.pathWithNamespace.toLowerCase()}!${input.ctx.mergeRequestIid}`,
-        }
-      : {}),
-    title: input.dispatch.title ?? defaultGitLabTitle(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: GitLabChannelOptions["cloud"],
-  ctx: GitLabEventContext,
-  mergeRequest: GitLabMergeRequestEvent,
-): Promise<AgentCloudOptions | undefined> {
-  if (cloud === undefined || cloud === false) {
-    return undefined;
-  }
-  if (cloud === true) {
-    return {
-      repos: [
-        {
-          url: ctx.project.webUrl,
-          prUrl: mergeRequest.url,
-          startingRef: mergeRequest.headSha,
-        },
-      ],
-    };
-  }
-  if (typeof cloud === "function") {
-    return await cloud(ctx, mergeRequest);
-  }
-  return cloud;
-}
-
-async function applyDispatch(input: {
-  options: GitLabChannelOptions;
-  args: ChannelHandlerArgs;
-  ctx: GitLabEventContext;
-  dispatch: GitLabDispatch | null;
-  extra: Record<string, unknown>;
-  message: string;
-  cloud?: AgentCloudOptions;
-  headSha?: string;
-  triggeringNoteId?: number;
-}): Promise<Response> {
-  if (input.dispatch === null) {
-    return skipped("not_dispatched", input.extra);
-  }
-  if (isTaskDispatch(input.dispatch)) {
-    return acknowledgeTask(input.args, GITLAB_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: gitlabChannelStateForEvent({
-      project: input.ctx.project,
-      mergeRequestIid: input.ctx.mergeRequestIid,
-      headSha: input.headSha,
-      deliveryId: input.ctx.deliveryId,
-      eventType: input.ctx.eventType,
-      triggeringNoteId: input.triggeringNoteId,
-    }),
-  });
-}
-
-const DEFAULT_NOTEABLES: readonly GitLabNoteableType[] = ["merge_request"];
-
-/**
- * Run the authored hooks for one GitLab delivery and `send()` the turn.
- * Callers own delivery auth: the HTTP route compares `X-Gitlab-Token`;
- * hosted admission arrives verified. The v2 mailbox is stamped upstream
- * (local CP or hosted ingress), never here.
- */
-export async function dispatchGitLabWebhook(input: {
-  options: GitLabChannelOptions;
-  delivery: GitLabWebhookDelivery;
-  args: ChannelHandlerArgs;
-  /** Host-bound SCM-proxy transport (`cursorAccount` + `--cursor-scm-proxy`). */
-  proxy?: () => GitLabProxyTransport | undefined;
-}): Promise<Response> {
-  const { eventType, payload } = input.delivery;
-  const parsed = parseGitLabEventContext(input.delivery);
-  if (parsed === null) {
-    return invalidPayload("invalid_gitlab_payload");
-  }
-  const args = input.args;
-  const ctx: GitLabEventContext = {
-    ...parsed,
-    gitlab: buildGitLabBinding({
-      project: parsed.project,
-      proxy: input.proxy?.(),
-      token: input.options.token,
-      apiBaseUrl: input.options.apiBaseUrl,
-    }),
-    host: args.host,
-    artifacts: args.artifacts,
-    send: args.send,
-  };
-  const allowlist = configuredProjectAllowlist(input.options);
-  if (allowlist !== undefined && !allowlist.has(ctx.project.pathWithNamespace.toLowerCase())) {
-    return skipped("project_not_allowed", {
-      project: ctx.project.pathWithNamespace,
-    });
-  }
-  const extra = { event: eventType };
-
-  switch (eventType) {
-    case "merge_request": {
-      const mergeRequest = gitlabMergeRequestFromRecord(
-        ctx.project,
-        asRecord(payload.object_attributes),
-      );
-      if (mergeRequest === undefined) {
-        return invalidPayload("invalid_gitlab_merge_request_payload");
-      }
-      const dispatch =
-        input.options.onMergeRequest === undefined
-          ? defaultGitLabMergeRequestDispatch(ctx, mergeRequest)
-          : await input.options.onMergeRequest(ctx, mergeRequest);
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra: { ...extra, action: mergeRequest.action },
-        message: defaultGitLabMergeRequestMessage(ctx, mergeRequest),
-        cloud: await resolveCloudOptions(input.options.cloud, ctx, mergeRequest),
-        headSha: mergeRequest.headSha,
-      });
-    }
-    case "note": {
-      if (input.options.onNote === undefined) {
-        return skipped("no_handler", extra);
-      }
-      const note = parseNote(payload);
-      if (note === undefined) {
-        return invalidPayload("invalid_gitlab_note_payload");
-      }
-      const noteables = input.options.noteables ?? DEFAULT_NOTEABLES;
-      if (!(noteables as readonly string[]).includes(note.noteableType)) {
-        return skipped("noteable_not_subscribed", {
-          ...extra,
-          noteable: note.noteableType,
-        });
-      }
-      const dispatch = await input.options.onNote(ctx, note);
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message:
-          ctx.mergeRequestIid === undefined
-            ? `GitLab ${note.noteableType} note on ${ctx.project.pathWithNamespace}`
-            : `GitLab note on ${ctx.project.pathWithNamespace}!${ctx.mergeRequestIid}`,
-        headSha: asNonEmptyString(asRecord(asRecord(payload.merge_request)?.last_commit)?.id),
-        triggeringNoteId: note.id,
-      });
-    }
-    case "push": {
-      if (input.options.onPush === undefined) {
-        return skipped("no_handler", extra);
-      }
-      const push = parsePush(payload);
-      if (push === undefined) {
-        return invalidPayload("invalid_gitlab_push_payload");
-      }
-      const dispatch = await input.options.onPush(ctx, push);
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message: `GitLab push to ${ctx.project.pathWithNamespace} ${push.ref}`,
-        headSha: push.after,
-      });
-    }
-    case "pipeline": {
-      if (input.options.onPipeline === undefined) {
-        return skipped("no_handler", extra);
-      }
-      const pipeline = parsePipeline(payload);
-      if (pipeline === undefined) {
-        return invalidPayload("invalid_gitlab_pipeline_payload");
-      }
-      const dispatch = await input.options.onPipeline(ctx, pipeline);
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra: { ...extra, status: pipeline.status },
-        message: `GitLab pipeline ${pipeline.status ?? "event"} on ${ctx.project.pathWithNamespace}`,
-        headSha: pipeline.sha,
-      });
-    }
-    default: {
-      if (input.options.onEvent === undefined) {
-        return skipped("unsupported_event", extra);
-      }
-      const dispatch = await input.options.onEvent(ctx, {
-        eventType,
-        payload,
-      });
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message: `GitLab ${eventType} event on ${ctx.project.pathWithNamespace}`,
-      });
-    }
-  }
-}
-
-/**
- * HTTP entry for a single agent's GitLab channel: `X-Gitlab-Token` compare
- * when a secret is configured, then {@link dispatchGitLabWebhook}. Without
- * a secret the route auth owns admission (`serve --dev` admits loopback
- * only; production stays loopback-strict).
- */
-export async function handleGitLabWebhookRequest(input: {
-  options: GitLabChannelOptions;
-  request: Request;
-  args: ChannelHandlerArgs;
-  /** When true, skip the token compare even if a secret is configured. */
-  skipSignatureVerification?: boolean;
-  proxy?: () => GitLabProxyTransport | undefined;
-}): Promise<Response> {
-  const bodyText = await input.request.text();
-  const secret = resolveGitLabWebhookSecret(input.options);
-  if (secret !== undefined && input.skipSignatureVerification !== true) {
-    if (!verifyGitLabWebhookToken(input.request.headers.get("x-gitlab-token"), secret)) {
-      return Response.json({ ok: false, error: "invalid_token" }, { 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 = parseGitLabWebhookPayload(payload);
-  if (delivery === null) {
-    return invalidPayload("invalid_gitlab_payload");
-  }
-  delivery.deliveryId = input.request.headers.get("x-gitlab-event-uuid") ?? undefined;
-  return dispatchGitLabWebhook({
-    options: input.options,
-    delivery,
-    proxy: input.proxy,
-    args: bindLocalIngressSend(input.args, {
-      identity: input.options.continuation,
-      kind: GITLAB_CHANNEL_KIND,
-      eventType: delivery.eventType,
-      payload: delivery.payload,
-    }),
-  });
-}

package/src/channels/gitlab/index.ts

@@ -1,44 +0,0 @@
-/**
- * GitLab webhook channel pack for agent-serve.
- *
- * ```ts
- * import { defaultGitLabAuth, gitlabChannel } from "@cursor/bdk/channels/gitlab";
- *
- * export default gitlabChannel({
- *   webhookSecret: () => process.env.GITLAB_WEBHOOK_SECRET,
- *   onMergeRequest: (ctx) => ({ auth: defaultGitLabAuth(ctx) }),
- *   onNote: (ctx) => ({ auth: defaultGitLabAuth(ctx) }),
- * });
- * ```
- *
- * Direct webhook mode compares the project hook's `X-Gitlab-Token` against
- * {@link GitLabChannelOptions.webhookSecret} (or `GITLAB_WEBHOOK_SECRET`).
- * Hosted deployments receive deliveries the Cursor backend already
- * verified. The turn principal is `gitlab-webhook` plus the GitLab actor —
- * not the Cursor subscriber — matching GitHub's `github-webhook` pattern.
- */
-
-export * from "./api.js";
-export {
-  buildGitLabBinding,
-  type GitLabHandle,
-  gitlabDraftMarkedReady,
-  gitlabMergeRequestFromRecord,
-  gitlabMergeRequestUrl,
-  gitlabProjectFromPayload,
-  normalizeGitLabNoteableType,
-} from "./binding.js";
-export * from "./checks.js";
-export {
-  CURSOR_GITLAB_MAX_PROJECTS,
-  type CursorGitLabProjectScope,
-  parseCursorGitLabProjectScope,
-  resolveCursorGitLabProxyUrl,
-} from "./cursor-account.js";
-export * from "./defaults.js";
-export * from "./events.js";
-export * from "./gitlab-channel.js";
-export * from "./gitlab-webhook.js";
-export * from "./replay.js";
-export * from "./state.js";
-export * from "./types.js";