@cursor/july 0.1.101 → 0.1.103

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

@@ -0,0 +1,555 @@
+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

@@ -0,0 +1,43 @@
+/**
+ * GitLab webhook channel pack for agent-serve.
+ *
+ * ```ts
+ * import { defaultGitLabAuth, gitlabChannel } from "@cursor/july/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,
+  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";