@cursor/july 0.1.55 → 0.1.61

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

@@ -0,0 +1,202 @@
+/**
+ * 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;
+
+const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
+
+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;
+}
+
+let jwksCache:
+  | { apiBaseUrl: string; keys: OriginJwk[]; fetchedAtMs: number }
+  | undefined;
+
+/** Fetch (and cache for 5 minutes) the Origin signing JWKS. */
+export async function fetchOriginJwks(
+  apiBaseUrl: string,
+  fetchImpl: typeof fetch = fetch
+): Promise<readonly OriginJwk[]> {
+  const now = Date.now();
+  if (
+    jwksCache !== undefined &&
+    jwksCache.apiBaseUrl === apiBaseUrl &&
+    now - jwksCache.fetchedAtMs < JWKS_CACHE_TTL_MS
+  ) {
+    return jwksCache.keys;
+  }
+  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");
+  }
+  jwksCache = { apiBaseUrl, keys, fetchedAtMs: now };
+  return keys;
+}
+
+export interface VerifyOriginWebhookOptions {
+  apiBaseUrl?: string;
+  fetchImpl?: typeof fetch;
+  nowMs?: number;
+}
+
+/**
+ * Verify a Standard-Webhooks v1ed Origin payload. Throws on failure.
+ */
+export async function verifyOriginWebhook(
+  body: string | Buffer,
+  headers: OriginWebhookHeaders,
+  options?: VerifyOriginWebhookOptions
+): Promise<void> {
+  const apiBaseUrl = options?.apiBaseUrl ?? DEFAULT_ORIGIN_API_BASE_URL;
+  const keys = await fetchOriginJwks(apiBaseUrl, options?.fetchImpl ?? fetch);
+  if (
+    !verifyV1edWebhookPayload({
+      publicJwks: keys,
+      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/types.ts

@@ -0,0 +1,186 @@
+import type {
+  AgentCloudOptions,
+  ArtifactsApi,
+  AuthContext,
+  AuthPolicy,
+  ChannelStartArgs,
+  HostContext,
+} from "../../types.js";
+
+export interface OriginActor {
+  id: string;
+  kind?: string;
+}
+
+export interface OriginRepositoryRef {
+  owner: string;
+  name: string;
+  fullName: string;
+}
+
+export interface OriginPullRequestEvent {
+  type: string;
+  number: number;
+  url: string;
+  title?: string;
+  body?: string | null;
+  draft?: boolean;
+  merged?: boolean;
+  authorId?: string;
+  headRef?: string;
+  headSha?: string;
+  baseRef?: string;
+  baseSha?: string;
+}
+
+export interface OriginComment {
+  id: string;
+  body: string;
+  author?: OriginActor;
+}
+
+export interface OriginReview {
+  id?: string;
+  verdict?: string;
+  author?: OriginActor;
+}
+
+export interface OriginEventContext {
+  deliveryId?: string;
+  eventType: string;
+  repository: OriginRepositoryRef;
+  pullRequestNumber: number;
+  pullRequestUrl: string;
+  sender?: OriginActor;
+  host: HostContext;
+  artifacts: ArtifactsApi;
+}
+
+export type OriginTurnDispatch = {
+  auth: AuthContext;
+  message?: string;
+  title?: string;
+  context?: readonly string[];
+};
+
+export type OriginTaskDispatch = { task: () => Promise<void> };
+
+export type OriginDispatch = OriginTurnDispatch | OriginTaskDispatch;
+
+export type OriginDispatchResult =
+  | OriginDispatch
+  | null
+  | Promise<OriginDispatch | null>;
+
+export type OriginPullRequestHook = (
+  ctx: OriginEventContext,
+  pullRequest: OriginPullRequestEvent
+) => OriginDispatchResult;
+
+export type OriginCommentHook = (
+  ctx: OriginEventContext,
+  comment: OriginComment
+) => OriginDispatchResult;
+
+export type OriginReviewHook = (
+  ctx: OriginEventContext,
+  review: OriginReview
+) => OriginDispatchResult;
+
+export type OriginEventHook = (
+  ctx: OriginEventContext,
+  event: { eventType: string; payload: unknown }
+) => OriginDispatchResult;
+
+export type OriginCloudOptionsResolver = (
+  ctx: OriginEventContext,
+  pullRequest: OriginPullRequestEvent
+) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
+
+/**
+ * Origin delivery envelope. Public payloads are proto3 camelCase
+ * (`pullRequest`, `repository.owner.slug`).
+ */
+export interface OriginWebhookEnvelope {
+  deliveryId?: string;
+  appId?: string;
+  installationId?: string;
+  sender?: OriginActor;
+  event: {
+    id?: string;
+    type: string;
+    eventTime?: string;
+    payload?: unknown;
+  };
+}
+
+export interface OriginChannelOptions {
+  /**
+   * Use the signed-in Cursor account for inbound Origin events via
+   * `/v0/scm-events` (`provider: "origin"`). `true` takes repository scope
+   * from `serve --cursor-events --repo`; `{ repos }` makes the channel
+   * self-contained. Origin identity is the Cursor user — there is no
+   * separate OAuth principal, and this does not mint a GitHub token.
+   */
+  cursorAccount?: boolean | { repos: readonly string[] };
+  /**
+   * Origin app id this channel accepts (`envelope.appId`). v1ed only proves
+   * Origin signed the body with the platform JWKS; it does not bind the
+   * delivery to one app (any Origin app can aim signed POSTs at a public
+   * URL). Required for non-loopback HTTP, same role as GitHub's per-channel
+   * webhook secret. Falls back to `AGENT_SERVE_ORIGIN_APP_ID`.
+   */
+  appId?: string | readonly string[];
+  /**
+   * Optional Origin installation id bind (`envelope.installationId`). When
+   * set, HTTP deliveries for any other installation are rejected.
+   */
+  installationId?: string | readonly string[];
+  /**
+   * Optional HTTP/dispatch repo allowlist (`owner/name`). `{ cursorAccount:
+   * { repos } }` is also an allowlist. Events outside the set are acked
+   * without starting a turn. Omit to accept every repo the bound app sends.
+   */
+  repos?: readonly string[];
+  /**
+   * Route auth chain. Defaults to allow-all when {@link appId} (or
+   * `AGENT_SERVE_ORIGIN_APP_ID`) is set, because v1ed plus that app-id bind
+   * is the request auth. Without an app id, production stays loopback-strict
+   * (GitHub's no-secret posture); `--dev` / skip-verify admits loopback only.
+   */
+  auth?: AuthPolicy[];
+  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
+  path?: string;
+  /** Origin API base used to fetch `/v1/origin/keys` for v1ed verify. */
+  apiBaseUrl?: string | (() => string | undefined);
+  /**
+   * Pin the Origin event types this channel dispatches on (published as
+   * `meta.originWebhookEvents`). Defaults to the set derived from hooks.
+   */
+  webhookEvents?: readonly string[];
+  /**
+   * Decide whether an inbound pull-request event starts a turn. Return
+   * `{ auth: defaultOriginAuth(ctx) }` to dispatch, `null` to ignore.
+   * Without this hook the channel dispatches on created / published /
+   * head_ref.pushed / base_ref.updated.
+   */
+  onPullRequest?: OriginPullRequestHook;
+  /** Opt-in `pull_request.comment.*` handler. No default dispatch. */
+  onComment?: OriginCommentHook;
+  /** Opt-in `pull_request.review.*` handler. No default dispatch. */
+  onReview?: OriginReviewHook;
+  /**
+   * Catch-all for Origin event types without a typed hook. NOT a fallback:
+   * events with a typed hook never reach this one.
+   */
+  onEvent?: OriginEventHook;
+  /**
+   * Per-session cloud options. Pass `true` to attach the PR repo using the
+   * pull request URL, or a resolver for custom cloud options.
+   */
+  cloud?: boolean | AgentCloudOptions | OriginCloudOptionsResolver;
+  /** Called once when the server mounts this channel. */
+  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+  /** Called when the server shuts down. */
+  onStop?: () => void | Promise<void>;
+}

package/src/channels/slack/doctor.ts

@@ -1,5 +1,7 @@
 /**
- * Slack channel doctor — verify env, Socket Mode app token, auth.test.
+ * Slack channel doctor — verify env, Socket Mode app token, auth.test, and
+ * (when watched channels are supplied) that the bot token's workspace can
+ * actually see, join, and read those channels.
  */
 
 import { callSlackApi, resolveAppToken, resolveBotToken } from "./api.js";
@@ -16,12 +18,163 @@ export interface SlackDoctorResult {
   ok: boolean;
   checks: SlackDoctorCheck[];
   envKeys: { bot: string; app: string };
+  /**
+   * Things a bot token cannot prove. Event subscriptions are app-level
+   * config, so a fully green doctor can still be a silent agent.
+   */
+  notes?: string[];
 }
 
 export interface SlackDoctorOptions {
   credentials?: SlackCredentials;
   /** Per-agent env prefix (e.g. `MY_AGENT`). */
   envPrefix?: string;
+  /**
+   * Watched channel ids (`engagement.channelPosts.allow`). Each is checked
+   * for visibility, bot membership, and history scope.
+   */
+  channels?: readonly string[];
+  /** Test seams. */
+  callImpl?: typeof callSlackApi;
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Socket Mode only delivers bot events the app subscribes to. Missing
+ * subscriptions produce total silence with valid tokens, and cannot be read
+ * back from a bot token.
+ */
+const REQUIRED_BOT_EVENTS: Readonly<Record<string, string>> = {
+  app_mention: "@mentions of the bot",
+  "message.im": "direct messages",
+  "message.channels": "public channel posts",
+  "message.groups": "private channel posts",
+  reaction_added: "reaction handlers (onReactionAdded)",
+};
+
+function eventSubscriptionNote(): string {
+  const lines = Object.entries(REQUIRED_BOT_EVENTS).map(
+    ([event, purpose]) => `    ${event} — ${purpose}`
+  );
+  return [
+    "A bot token cannot read Event Subscriptions. If every check above passes",
+    "but the bot is silent, verify these bot events are subscribed on the app",
+    "(Slack app config -> Event Subscriptions -> Subscribe to bot events):",
+    ...lines,
+  ].join("\n");
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function errorOf(response: Record<string, unknown>): string {
+  return typeof response.error === "string" ? response.error : "unknown";
+}
+
+/**
+ * Visibility, membership, and history-scope checks for one watched channel.
+ * `channel_not_found` here is the classic wrong-workspace bot token: the
+ * token authenticates fine, it just belongs to a different installation.
+ */
+async function checkChannel(args: {
+  call: typeof callSlackApi;
+  botToken: string;
+  channelId: string;
+}): Promise<SlackDoctorCheck[]> {
+  const { call, botToken, channelId } = args;
+  const checks: SlackDoctorCheck[] = [];
+
+  let info: Record<string, unknown>;
+  try {
+    info = await call({
+      botToken,
+      operation: "conversations.info",
+      body: { channel: channelId },
+    });
+  } catch (error) {
+    checks.push({
+      id: `channel_visible:${channelId}`,
+      ok: false,
+      message: `conversations.info threw: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    });
+    return checks;
+  }
+
+  if (info.ok !== true) {
+    const error = errorOf(info);
+    checks.push({
+      id: `channel_visible:${channelId}`,
+      ok: false,
+      message:
+        error === "channel_not_found"
+          ? `${channelId} not found by this bot token — the token is probably installed on a different workspace, or the channel id is wrong`
+          : `conversations.info failed: ${error}`,
+    });
+    return checks;
+  }
+
+  const channel = asRecord(info.channel);
+  const name = typeof channel?.name === "string" ? channel.name : "?";
+  checks.push({
+    id: `channel_visible:${channelId}`,
+    ok: true,
+    message: `${channelId} visible (#${name})`,
+  });
+
+  const isMember = channel?.is_member === true;
+  checks.push({
+    id: `channel_member:${channelId}`,
+    ok: isMember,
+    message: isMember
+      ? `bot is a member of ${channelId}`
+      : `bot is NOT a member of ${channelId} — invite it to the channel`,
+  });
+
+  let history: Record<string, unknown>;
+  try {
+    history = await call({
+      botToken,
+      operation: "conversations.history",
+      body: { channel: channelId, limit: 1 },
+    });
+  } catch (error) {
+    checks.push({
+      id: `channel_history:${channelId}`,
+      ok: false,
+      message: `conversations.history threw: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    });
+    return checks;
+  }
+
+  if (history.ok === true) {
+    checks.push({
+      id: `channel_history:${channelId}`,
+      ok: true,
+      message: `conversations.history ok for ${channelId}`,
+    });
+    return checks;
+  }
+
+  const error = errorOf(history);
+  const needed =
+    typeof history.needed === "string" ? history.needed : undefined;
+  checks.push({
+    id: `channel_history:${channelId}`,
+    ok: false,
+    message:
+      error === "missing_scope"
+        ? `conversations.history missing scope${needed === undefined ? "" : ` ${needed}`} — add it and reinstall the app`
+        : `conversations.history failed: ${error}`,
+  });
+  return checks;
 }
 
 export async function runSlackDoctor(
@@ -31,6 +184,8 @@ export async function runSlackDoctor(
     options.credentials ?? credentialsFromEnv(options.envPrefix);
   const envKeys = slackEnvKeys(options.envPrefix);
   const checks: SlackDoctorCheck[] = [];
+  const call = options.callImpl ?? callSlackApi;
+  const fetchImpl = options.fetchImpl ?? fetch;
 
   let appTokenRaw: string | undefined;
   try {
@@ -48,7 +203,7 @@ export async function runSlackDoctor(
   });
   if (hasApp && appTokenRaw !== undefined) {
     try {
-      const response = await fetch(
+      const response = await fetchImpl(
         "https://slack.com/api/apps.connections.open",
         {
           method: "POST",
@@ -100,18 +255,25 @@ export async function runSlackDoctor(
     message: hasToken ? `${envKeys.bot} present` : `${envKeys.bot} is missing`,
   });
 
+  let authOk = false;
+  let botUserId = "";
   if (hasToken) {
     try {
-      const auth = await callSlackApi({
+      const auth = await call({
         botToken,
         operation: "auth.test",
         body: {},
       });
       if (auth.ok === true) {
+        authOk = true;
+        botUserId = typeof auth.user_id === "string" ? auth.user_id : "";
         checks.push({
           id: "auth_test",
           ok: true,
-          message: `auth.test ok (team=${String(auth.team ?? "?")}, user=${String(auth.user ?? "?")})`,
+          message:
+            `auth.test ok (team=${String(auth.team ?? "?")}` +
+            `, team_id=${String(auth.team_id ?? "?")}` +
+            `, user=${String(auth.user ?? "?")})`,
         });
       } else {
         checks.push({
@@ -131,5 +293,56 @@ export async function runSlackDoctor(
     }
   }
 
-  return { ok: checks.every((check) => check.ok), checks, envKeys };
+  // The external-sender policy (`blockExternals`, on by default) classifies a
+  // sender as external whenever `users.info` fails — so a token that cannot
+  // look up users silently drops EVERY inbound event while all other checks
+  // stay green. Probe with the bot's own user id from auth.test.
+  if (authOk && botToken !== undefined && botUserId !== "") {
+    let info: Record<string, unknown> | undefined;
+    let threw: string | undefined;
+    try {
+      info = await call({
+        botToken,
+        operation: "users.info",
+        body: { user: botUserId },
+      });
+    } catch (error) {
+      threw = error instanceof Error ? error.message : String(error);
+    }
+    if (info?.ok === true) {
+      checks.push({
+        id: "users_read",
+        ok: true,
+        message:
+          "users.info ok (users:read granted; external-sender policy can classify senders)",
+      });
+    } else {
+      const error = threw ?? (info === undefined ? "unknown" : errorOf(info));
+      const hint =
+        error === "missing_scope"
+          ? "add the users:read scope and reinstall the app"
+          : error === "user_not_found"
+            ? "the token cannot see its own workspace's users — probably a token from a different installation"
+            : "fix the token";
+      checks.push({
+        id: "users_read",
+        ok: false,
+        message: `users.info failed: ${error} — ${hint}. The external-sender policy fails open to "external" on users.info errors, so every inbound event is silently dropped.`,
+      });
+    }
+  }
+
+  const channels = options.channels ?? [];
+  if (authOk && botToken !== undefined && channels.length > 0) {
+    for (const channelId of channels) {
+      checks.push(...(await checkChannel({ call, botToken, channelId })));
+    }
+  }
+
+  return {
+    ok: checks.every((check) => check.ok),
+    checks,
+    envKeys,
+    notes: [eventSubscriptionNote()],
+  };
 }

package/src/index.ts

@@ -65,12 +65,15 @@ export {
 export type {
   AgentServeGitHubTriggerEvent,
   AgentServeGitHubTriggerTarget,
+  AgentServeOriginTriggerEvent,
+  AgentServeOriginTriggerTarget,
   AgentServeTriggerEvent,
   AgentServeTriggerResult,
   AgentServeTriggerTargetResult,
 } from "./internal/handleAgentServeTrigger.js";
 export {
   collectGitHubTriggerTargets,
+  collectOriginTriggerTargets,
   handleAgentServeTrigger,
 } from "./internal/handleAgentServeTrigger.js";
 export {
@@ -94,7 +97,6 @@ export {
 } from "./internal/session-engine.js";
 export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
 export {
-  createLedgerJanitor,
   LedgerCasExhaustedError,
   LedgerFencedError,
   SessionLedger,