@cursor/bdk 0.2.2 → 0.2.4

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

@@ -1,296 +0,0 @@
-/**
- * Origin webhook verification (Standard Webhooks `v1ed`).
- *
- * Direct Origin HTTP deliveries must verify the Ed25519 signature
- * (`webhook-id`, `webhook-timestamp`, `webhook-signature`) against Origin's
- * JWKS. Cursor-events relay deliveries skip this — the platform already
- * verified the webhook before enqueueing.
- *
- * The signed content matches the Standard Webhooks `v1` scheme
- * (`${webhook-id}.${webhook-timestamp}.${body}`) but is hashed to a lowercase
- * hex SHA-256 before signing. Lifted from
- * `factory/agentic-owners/agent/lib/origin-webhook.ts` /
- * `backend/server/src/origin/webhooks/asymmetricWebhookSignature.ts`.
- */
-import {
-  createHash,
-  createPublicKey,
-  type JsonWebKeyInput,
-  type KeyObject,
-  verify as verifyEd25519,
-} from "node:crypto";
-
-export const V1ED_SIGNATURE_VERSION = "v1ed";
-export const DEFAULT_ORIGIN_API_BASE_URL = "https://origin.cursor.com";
-
-/** ±5 minutes, the Standard Webhooks replay-window convention. */
-const V1ED_TIMESTAMP_TOLERANCE_SECONDS = 5 * 60;
-
-/**
- * The sender emits exactly one v1ed entry; key rotation is handled by trying
- * multiple public keys, never multiple signatures.
- */
-const MAX_V1ED_CANDIDATE_SIGNATURES = 1;
-
-export type OriginJwk = Record<string, unknown>;
-
-export type OriginWebhookHeaders = {
-  "webhook-id"?: string;
-  "webhook-timestamp"?: string;
-  "webhook-signature"?: string;
-};
-
-export function buildV1edSignedContentDigest(args: {
-  webhookId: string;
-  timestampSeconds: number;
-  body: string | Buffer;
-}): string {
-  const prefix = Buffer.from(`${args.webhookId}.${args.timestampSeconds}.`, "utf8");
-  const body = typeof args.body === "string" ? Buffer.from(args.body, "utf8") : args.body;
-  return createHash("sha256")
-    .update(Buffer.concat([prefix, body]))
-    .digest("hex");
-}
-
-/**
- * Verify a delivery's Standard Webhooks headers against the Origin signing
- * JWKS. Owns the whole check: header presence, timestamp parsing, the replay
- * window, and Ed25519 verification against any provided key.
- */
-export function verifyV1edWebhookPayload(args: {
-  publicJwks: readonly OriginJwk[];
-  body: string | Buffer;
-  headers: OriginWebhookHeaders;
-  nowMs?: number;
-}): boolean {
-  const webhookId = args.headers["webhook-id"];
-  const webhookTimestamp = args.headers["webhook-timestamp"];
-  const signatureHeader = args.headers["webhook-signature"];
-  if (webhookId === undefined || webhookTimestamp === undefined || signatureHeader === undefined) {
-    return false;
-  }
-  const timestampSeconds = Number.parseInt(webhookTimestamp, 10);
-  if (Number.isNaN(timestampSeconds)) {
-    return false;
-  }
-  const nowSeconds = Math.floor((args.nowMs ?? Date.now()) / 1000);
-  if (Math.abs(nowSeconds - timestampSeconds) > V1ED_TIMESTAMP_TOLERANCE_SECONDS) {
-    return false;
-  }
-
-  const digestBytes = Buffer.from(
-    buildV1edSignedContentDigest({
-      webhookId,
-      timestampSeconds,
-      body: args.body,
-    }),
-    "utf8",
-  );
-  const candidateSignatures = signatureHeader
-    .split(/\s+/)
-    .filter(entry => entry.startsWith(`${V1ED_SIGNATURE_VERSION},`))
-    .map(entry => entry.slice(V1ED_SIGNATURE_VERSION.length + 1))
-    .slice(0, MAX_V1ED_CANDIDATE_SIGNATURES);
-  if (candidateSignatures.length === 0) {
-    return false;
-  }
-
-  for (const jwk of args.publicJwks) {
-    let publicKey: KeyObject;
-    try {
-      publicKey = createPublicKey({
-        key: jwk,
-        format: "jwk",
-      } as JsonWebKeyInput);
-    } catch {
-      continue;
-    }
-    for (const candidate of candidateSignatures) {
-      const signature = Buffer.from(candidate, "base64");
-      try {
-        if (verifyEd25519(null, digestBytes, publicKey, signature)) {
-          return true;
-        }
-      } catch {
-        // Malformed signature bytes or a non-Ed25519 key: try the next pair.
-      }
-    }
-  }
-  return false;
-}
-
-function cacheControlDeltaMs(
-  cacheControl: string | null | undefined,
-  directive: "max-age" | "stale-if-error",
-): number | undefined {
-  if (cacheControl == null || cacheControl === "") {
-    return undefined;
-  }
-  const match = new RegExp(`(?:^|,)\\s*${directive}\\s*=\\s*(\\d+)`, "i").exec(cacheControl);
-  if (match === null) {
-    return undefined;
-  }
-  return Number(match[1]) * 1000;
-}
-
-/**
- * RFC 9111 `max-age` (seconds → ms) from a Cache-Control header.
- * Does not read `s-maxage`. Missing or unparsable → `undefined`.
- */
-export function cacheControlMaxAgeMs(cacheControl: string | null | undefined): number | undefined {
-  return cacheControlDeltaMs(cacheControl, "max-age");
-}
-
-/**
- * RFC 5861 `stale-if-error` (seconds → ms). Missing → `undefined` (no
- * fail-open after `max-age`).
- */
-export function cacheControlStaleIfErrorMs(
-  cacheControl: string | null | undefined,
-): number | undefined {
-  return cacheControlDeltaMs(cacheControl, "stale-if-error");
-}
-
-let jwksCache:
-  | {
-      apiBaseUrl: string;
-      keys: OriginJwk[];
-      freshUntilMs: number;
-      staleUntilMs: number;
-    }
-  | undefined;
-
-export type FetchOriginJwksOptions = {
-  /** Skip the in-memory hit and call `/v1/origin/keys` (used after a verify miss). */
-  force?: boolean;
-};
-
-/**
- * Return the in-memory Origin signing JWKS.
- *
- * Freshness is the JWKS response `Cache-Control: max-age`. After that, or
- * when `force` is set, refetch. A failed refetch returns the last keys only
- * while `stale-if-error` still applies; otherwise it throws (including a
- * cold-cache miss).
- */
-export async function fetchOriginJwks(
-  apiBaseUrl: string,
-  fetchImpl: typeof fetch = fetch,
-  options?: FetchOriginJwksOptions,
-): Promise<readonly OriginJwk[]> {
-  const now = Date.now();
-  if (
-    options?.force !== true &&
-    jwksCache !== undefined &&
-    jwksCache.apiBaseUrl === apiBaseUrl &&
-    now < jwksCache.freshUntilMs
-  ) {
-    return jwksCache.keys;
-  }
-  try {
-    const response = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`);
-    if (!response.ok) {
-      throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
-    }
-    const body: unknown = await response.json().catch(() => undefined);
-    const keys =
-      typeof body === "object" &&
-      body !== null &&
-      Array.isArray((body as Record<string, unknown>).keys)
-        ? ((body as Record<string, unknown>).keys as OriginJwk[])
-        : [];
-    if (keys.length === 0) {
-      throw new Error("Origin JWKS fetch returned no keys");
-    }
-    const cacheControl = response.headers.get("cache-control");
-    const maxAgeMs = cacheControlMaxAgeMs(cacheControl) ?? 0;
-    const staleIfErrorMs = cacheControlStaleIfErrorMs(cacheControl) ?? 0;
-    jwksCache = {
-      apiBaseUrl,
-      keys,
-      freshUntilMs: now + maxAgeMs,
-      staleUntilMs: now + maxAgeMs + staleIfErrorMs,
-    };
-    return keys;
-  } catch (error) {
-    if (
-      jwksCache !== undefined &&
-      jwksCache.apiBaseUrl === apiBaseUrl &&
-      now < jwksCache.staleUntilMs
-    ) {
-      return jwksCache.keys;
-    }
-    throw error;
-  }
-}
-
-export interface VerifyOriginWebhookOptions {
-  apiBaseUrl?: string;
-  fetchImpl?: typeof fetch;
-  nowMs?: number;
-}
-
-/**
- * The signing JWKS could not be fetched (and no cached copy applies), so
- * the delivery was never actually checked. Callers must answer retryably
- * (5xx) — a 401 would make Origin's delivery worker drop the wake as
- * terminal on what is only a transient outage.
- */
-export class OriginJwksUnavailableError extends Error {}
-
-async function fetchJwksOrUnavailable(
-  apiBaseUrl: string,
-  fetchImpl: typeof fetch,
-  options?: FetchOriginJwksOptions,
-): Promise<readonly OriginJwk[]> {
-  try {
-    return await fetchOriginJwks(apiBaseUrl, fetchImpl, options);
-  } catch (error) {
-    throw new OriginJwksUnavailableError(
-      `Origin JWKS unavailable: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-}
-
-/**
- * Verify a Standard-Webhooks v1ed Origin payload. Throws
- * {@link OriginJwksUnavailableError} when the keys cannot be fetched, and a
- * plain error when the signature does not verify against them.
- */
-export async function verifyOriginWebhook(
-  body: string | Buffer,
-  headers: OriginWebhookHeaders,
-  options?: VerifyOriginWebhookOptions,
-): Promise<void> {
-  const apiBaseUrl = options?.apiBaseUrl ?? DEFAULT_ORIGIN_API_BASE_URL;
-  const fetchImpl = options?.fetchImpl ?? fetch;
-  const keys = await fetchJwksOrUnavailable(apiBaseUrl, fetchImpl);
-  if (
-    verifyV1edWebhookPayload({
-      publicJwks: keys,
-      body,
-      headers,
-      nowMs: options?.nowMs,
-    })
-  ) {
-    return;
-  }
-  const refreshed = await fetchJwksOrUnavailable(apiBaseUrl, fetchImpl, {
-    force: true,
-  });
-  if (
-    !verifyV1edWebhookPayload({
-      publicJwks: refreshed,
-      body,
-      headers,
-      nowMs: options?.nowMs,
-    })
-  ) {
-    throw new Error("Origin webhook signature verification failed");
-  }
-}
-
-/** Test helper: drop the in-process JWKS cache. */
-export function resetOriginWebhookKeysCache(): void {
-  jwksCache = undefined;
-}

package/src/channels/origin/reactions.ts

@@ -1,72 +0,0 @@
-/**
- * Origin PR comment reactions — the Origin analogue of the GitHub channel's
- * `thread.react("eyes")`.
- *
- * Unlike checks and comments, reactions have no `/v1/origin/...` REST
- * binding. The only write is Connect unary JSON against Origin's first-party
- * service (`origin.v1.OriginService/SetCommentReaction`), which lives on a
- * different host than the public REST API — {@link originRpcBaseUrl}, not
- * {@link originPublicApiBaseUrl}. `ctx.origin.reactToComment` already points
- * at the right one; a hand-built client must too.
- *
- * Writing needs `repository:pull_requests:reviews:write`: an `oit_…`
- * installation token for app channels, or a deployment service-account
- * session (hosted v2 forks). Origin rejects reactions on comments that
- * belong to an unsubmitted review. API failures throw `OriginApiError`.
- */
-
-import type { OriginApiMethod } from "./api.js";
-
-/** Any client that can call Origin's ConnectRPC host. */
-export interface OriginReactionClient {
-  request<T = unknown>(input: {
-    method: OriginApiMethod;
-    path: string;
-    body?: unknown;
-  }): Promise<T>;
-}
-
-/** Connect unary route backing {@link setOriginCommentReaction}. */
-export const SET_ORIGIN_COMMENT_REACTION_PATH = "/origin.v1.OriginService/SetCommentReaction";
-
-/**
- * The eight reactions Origin accepts. Anything else is rejected with
- * `invalid_argument`, so channels get a compile error instead of a 400.
- */
-export const ORIGIN_COMMENT_REACTIONS = ["👍", "👎", "😄", "🎉", "😕", "❤️", "🚀", "👀"] as const;
-
-export type OriginCommentReaction = (typeof ORIGIN_COMMENT_REACTIONS)[number];
-
-export interface OriginCommentReactionInput {
-  /** Origin comment TypeID (`cmt_…`), i.e. `comment.id` on a comment hook. */
-  commentId: string;
-  emoji: OriginCommentReaction;
-  /** `false` removes the reaction. Removing one that is absent is a no-op. */
-  active?: boolean;
-}
-
-/**
- * Add (or, with `active: false`, remove) one reaction on an Origin PR
- * comment as the client's own principal.
- *
- * ```ts
- * await setOriginCommentReaction({
- *   origin: createOriginClient({ apiBaseUrl: originRpcBaseUrl() }),
- *   commentId: comment.id,
- *   emoji: "👀",
- * });
- * ```
- */
-export async function setOriginCommentReaction(
-  input: OriginCommentReactionInput & { origin: OriginReactionClient },
-): Promise<void> {
-  await input.origin.request({
-    method: "POST",
-    path: SET_ORIGIN_COMMENT_REACTION_PATH,
-    body: {
-      commentId: input.commentId,
-      emoji: input.emoji,
-      active: input.active ?? true,
-    },
-  });
-}

package/src/channels/origin/state.ts

@@ -1,54 +0,0 @@
-/**
- * Durable per-session Origin channel state.
- *
- * Persisted with the turn (same mechanism as `GitHubChannelState`) so
- * channel stream-event handlers — reply delivery in ./defaults.ts — can
- * rebuild a repo-bound Origin handle without re-parsing the webhook.
- */
-
-export interface OriginChannelState {
-  owner: string;
-  repo: string;
-  pullRequestNumber: number | null;
-  /** Origin app installation id from the delivery envelope, when present. */
-  installationId: string | null;
-  /** Comment id that woke the turn (comment events only). */
-  triggeringCommentId: string | null;
-  deliveryId: string | null;
-  eventType: string | null;
-}
-
-export function emptyOriginChannelState(
-  overrides: Partial<OriginChannelState> = {},
-): OriginChannelState {
-  return {
-    owner: "",
-    repo: "",
-    pullRequestNumber: null,
-    installationId: null,
-    triggeringCommentId: null,
-    deliveryId: null,
-    eventType: null,
-    ...overrides,
-  };
-}
-
-/** Build the per-turn channel state from a dispatched event's context. */
-export function originChannelStateForEvent(input: {
-  repository: { owner: string; name: string };
-  pullRequestNumber: number;
-  installationId?: string;
-  deliveryId?: string;
-  eventType: string;
-  triggeringCommentId?: string;
-}): OriginChannelState {
-  return emptyOriginChannelState({
-    owner: input.repository.owner,
-    repo: input.repository.name,
-    pullRequestNumber: input.pullRequestNumber,
-    installationId: input.installationId ?? null,
-    triggeringCommentId: input.triggeringCommentId ?? null,
-    deliveryId: input.deliveryId ?? null,
-    eventType: input.eventType,
-  });
-}