@cursor/july 0.1.74 → 0.1.76

package/src/channels/github/checks.ts

@@ -1,81 +1,115 @@
 /**
- * Generic CI checks (GitHub Checks API) for agent authors.
+ * GitHub CI checks (Checks API) — the GitHub {@link CiCheckWriter} behind the
+ * shared check lifecycle in `../checks.js`.
  *
- * `createGitHubCheck` opens a merge-box check run on a commit and returns a
- * handle for updating and concluding it, so an agent can report its own CI
- * result (name, summary, and a "Details" link — e.g. the agent session run).
- * Works with any client exposing `getOctokit()` (`ctx.github`,
+ * `createGitHubCheck` opens a merge-box check run on a commit and returns the
+ * shared `CiCheck` handle; `resumeGitHubCheck` rebuilds one from a stored
+ * check-run id. Works with any client exposing `getOctokit()` (`ctx.github`,
  * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
  *
  * Posting checks needs `checks:write`. With `cursorAccount`, declare
  * `githubChannel({ checks: true })` so the hosted lease is minted on the
  * `contents-write` tier; GitHub App / PAT credentials need the equivalent
- * permission.
+ * permission. API failures are normalized into `GitHubApiError`.
  */
 
 import type { Octokit } from "@octokit/rest";
 import {
-  type GitHubCheckRunConclusion,
-  type GitHubCheckRunStatus,
-  wrapOctokitError,
-} from "./api.js";
+  type CiCheck,
+  type CiCheckConcludeInput,
+  type CiCheckCreateInput,
+  type CiCheckOutput,
+  type CiCheckRef,
+  type CiCheckUpdateInput,
+  type CiCheckWriter,
+  openCiCheck,
+  resumeCiCheck,
+} from "../checks.js";
+import { wrapOctokitError } from "./api.js";
 
 /** Any client that can hand out an authenticated Octokit. */
 export interface GitHubCheckClient {
   getOctokit(): Promise<Octokit>;
 }
 
-/** Output shown on the check page (both fields required by GitHub). */
-export interface GitHubCheckOutput {
-  /** Heading on the check page. */
-  title: string;
-  /** Markdown body (supports links, e.g. `[View session](…)`). */
-  summary: string;
-}
+export type GitHubCheckOutput = CiCheckOutput;
+export type GitHubCheckUpdateInput = CiCheckUpdateInput;
+export type GitHubCheckConcludeInput = CiCheckConcludeInput;
+
+/** A created check run. All methods throw `GitHubApiError` on API failure. */
+export type GitHubCheck = CiCheck & CiCheckRef;
 
-export interface GitHubCheckCreateInput {
+export interface GitHubCheckCreateInput extends CiCheckCreateInput {
   /** Client used for every API call on the returned handle. */
   github: GitHubCheckClient;
   /** Repository owner login, e.g. `"acme"`. */
   owner: string;
   /** Repository name, e.g. `"widgets"`. */
   repo: string;
-  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
-  name: string;
-  /** Commit the check attaches to (usually the PR head SHA). */
-  sha: string;
-  /** Initial status. Defaults to `"in_progress"`. */
-  status?: "queued" | "in_progress";
-  /** "Details" link on the check, e.g. the agent session run URL. */
-  detailsUrl?: string;
-  /** Title + markdown summary shown on the check page. */
-  output?: GitHubCheckOutput;
-}
-
-export interface GitHubCheckUpdateInput {
-  status?: GitHubCheckRunStatus;
-  conclusion?: GitHubCheckRunConclusion;
-  detailsUrl?: string;
-  output?: GitHubCheckOutput;
 }
 
-export interface GitHubCheckConcludeInput {
-  /** Final result shown in the merge box. */
-  conclusion: GitHubCheckRunConclusion;
-  detailsUrl?: string;
-  output?: GitHubCheckOutput;
-}
-
-/** A created check run. All methods throw `GitHubApiError` on API failure. */
-export interface GitHubCheck {
-  /** Check run id (for reuse across process restarts). */
-  readonly id: number;
-  /** GitHub web URL of the check run page, when returned by the API. */
-  readonly url: string | undefined;
-  /** Patch status / output / details link while the check is running. */
-  update(input: GitHubCheckUpdateInput): Promise<void>;
-  /** Complete the check with a conclusion (sets `completed_at`). */
-  conclude(input: GitHubCheckConcludeInput): Promise<void>;
+/**
+ * GitHub writer: first write creates the check run (capturing its id), later
+ * writes patch it.
+ */
+function githubCheckWriter(input: {
+  github: GitHubCheckClient;
+  owner: string;
+  repo: string;
+  name: string;
+  sha?: string;
+  checkRunId?: number;
+}): CiCheckWriter {
+  let checkRunId = input.checkRunId;
+  return async (write) => {
+    const octokit = await input.github.getOctokit();
+    const base = {
+      owner: input.owner,
+      repo: input.repo,
+      name: input.name,
+      status: write.status,
+      conclusion: write.conclusion,
+      completed_at: write.completedAt,
+      details_url: write.detailsUrl,
+      output: write.output,
+    };
+    if (checkRunId === undefined) {
+      if (input.sha === undefined) {
+        throw new Error("githubChannel: cannot create a check without a sha.");
+      }
+      try {
+        const response = await octokit.rest.checks.create({
+          ...base,
+          head_sha: input.sha,
+          started_at: write.startedAt,
+        });
+        checkRunId = response.data.id;
+        return {
+          id: response.data.id,
+          url:
+            typeof response.data.html_url === "string"
+              ? response.data.html_url
+              : undefined,
+        };
+      } catch (error) {
+        throw wrapOctokitError(
+          error,
+          "POST",
+          `/repos/${input.owner}/${input.repo}/check-runs`
+        );
+      }
+    }
+    try {
+      await octokit.rest.checks.update({ ...base, check_run_id: checkRunId });
+      return undefined;
+    } catch (error) {
+      throw wrapOctokitError(
+        error,
+        "PATCH",
+        `/repos/${input.owner}/${input.repo}/check-runs/${checkRunId}`
+      );
+    }
+  };
 }
 
 /**
@@ -95,38 +129,10 @@ export interface GitHubCheck {
  * await check.conclude({ conclusion: "success", output: { … } });
  * ```
  */
-export async function createGitHubCheck(
+export function createGitHubCheck(
   input: GitHubCheckCreateInput
 ): Promise<GitHubCheck> {
-  const octokit = await input.github.getOctokit();
-  let created: { id: number; html_url?: string | null };
-  try {
-    const response = await octokit.rest.checks.create({
-      owner: input.owner,
-      repo: input.repo,
-      name: input.name,
-      head_sha: input.sha,
-      status: input.status ?? "in_progress",
-      started_at: new Date().toISOString(),
-      details_url: input.detailsUrl,
-      output: input.output,
-    });
-    created = response.data;
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "POST",
-      `/repos/${input.owner}/${input.repo}/check-runs`
-    );
-  }
-  return resumeGitHubCheck({
-    github: input.github,
-    owner: input.owner,
-    repo: input.repo,
-    name: input.name,
-    checkRunId: created.id,
-    url: typeof created.html_url === "string" ? created.html_url : undefined,
-  });
+  return openCiCheck(githubCheckWriter(input), input);
 }
 
 /**
@@ -141,39 +147,8 @@ export function resumeGitHubCheck(input: {
   checkRunId: number;
   url?: string;
 }): GitHubCheck {
-  const patch = async (update: GitHubCheckUpdateInput): Promise<void> => {
-    const octokit = await input.github.getOctokit();
-    try {
-      await octokit.rest.checks.update({
-        owner: input.owner,
-        repo: input.repo,
-        check_run_id: input.checkRunId,
-        name: input.name,
-        status: update.status,
-        conclusion: update.conclusion,
-        completed_at:
-          update.status === "completed" ? new Date().toISOString() : undefined,
-        details_url: update.detailsUrl,
-        output: update.output,
-      });
-    } catch (error) {
-      throw wrapOctokitError(
-        error,
-        "PATCH",
-        `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`
-      );
-    }
-  };
-  return {
+  return resumeCiCheck(githubCheckWriter(input), {
     id: input.checkRunId,
     url: input.url,
-    update: patch,
-    conclude: (conclude) =>
-      patch({
-        status: "completed",
-        conclusion: conclude.conclusion,
-        detailsUrl: conclude.detailsUrl,
-        output: conclude.output,
-      }),
-  };
+  });
 }

package/src/channels/origin/api.ts

@@ -0,0 +1,318 @@
+/**
+ * Origin public REST helpers (`https://api.cursor.com/v1/origin/...`).
+ *
+ * Origin writes such as CI check runs are installation-only: they need an
+ * `oit_…` installation token minted from Origin app credentials (EdDSA app
+ * JWT → `/v1/origin/app/installations/{id}/access_tokens`). This module
+ * consolidates that flow so agents configure credentials once and call
+ * {@link createOriginClient} — the GitHub-channel analogue of
+ * `createGitHubOctokit`.
+ *
+ * Credentials resolve from options first, then the environment:
+ * `ORIGIN_APP_ID` (or `AGENT_SERVE_ORIGIN_APP_ID`),
+ * `ORIGIN_APP_INSTALLATION_ID`, `ORIGIN_APP_PRIVATE_KEY` (PKCS8 PEM for the
+ * app's Ed25519 key; literal `\n` sequences are normalized), and
+ * `ORIGIN_API_BASE_URL` for the public REST base.
+ */
+
+import { Buffer } from "node:buffer";
+import { createPrivateKey, sign } from "node:crypto";
+
+/**
+ * Public Origin REST base (check runs, installation tokens). Distinct from
+ * the webhook JWKS base (`DEFAULT_ORIGIN_API_BASE_URL` in
+ * `origin-webhook.ts`).
+ */
+export const DEFAULT_ORIGIN_PUBLIC_API_BASE_URL = "https://api.cursor.com";
+
+/** Fixed audience for Origin app JWTs (`APP_TOKEN_AUDIENCE` backend-side). */
+const ORIGIN_APP_TOKEN_AUDIENCE = "origin-apps";
+const APP_JWT_TTL_SECONDS = 5 * 60;
+/** Re-mint the `oit_` token after this long; tokens outlive it comfortably. */
+const TOKEN_REUSE_MS = 4 * 60 * 1000;
+const TOKEN_EXCHANGE_TIMEOUT_MS = 30_000;
+
+export type OriginApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+
+/** Normalized Origin REST failure — the `GitHubApiError` analogue. */
+export class OriginApiError extends Error {
+  readonly body: unknown;
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+
+  constructor(input: {
+    body: unknown;
+    method: string;
+    path: string;
+    status: number;
+  }) {
+    super(
+      `Origin ${input.method} ${input.path} failed with HTTP ${input.status}.`
+    );
+    this.name = "OriginApiError";
+    this.body = input.body;
+    this.method = input.method;
+    this.path = input.path;
+    this.status = input.status;
+  }
+}
+
+/** Yields a bearer for Origin REST calls (usually a short-lived `oit_…`). */
+export type OriginTokenProvider = () => Promise<string>;
+
+export interface OriginAppCredentials {
+  /** Origin app id (`app_<typeid>`). */
+  appId: string;
+  /** Installation the token is minted for. */
+  installationId: string;
+  /** PKCS8 PEM for the app's EdDSA (Ed25519) private key. */
+  privateKey: string;
+}
+
+/** Vault/env round-trip: literal `\n` sequences appear in practice. */
+function normalizePrivateKeyPem(raw: string | undefined): string | undefined {
+  const pem = raw?.trim().replace(/\\n/g, "\n");
+  return pem === undefined || pem === "" ? undefined : pem;
+}
+
+function envValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+
+/** Each Origin app credential field found in the environment, when set. */
+export function resolveOriginAppCredentialParts(
+  env: NodeJS.ProcessEnv = process.env
+): Partial<OriginAppCredentials> {
+  return {
+    appId:
+      envValue(env.ORIGIN_APP_ID) ?? envValue(env.AGENT_SERVE_ORIGIN_APP_ID),
+    installationId: envValue(env.ORIGIN_APP_INSTALLATION_ID),
+    privateKey: normalizePrivateKeyPem(env.ORIGIN_APP_PRIVATE_KEY),
+  };
+}
+
+/**
+ * Read Origin app credentials from the environment. Returns `undefined` when
+ * incomplete so callers can fail with a clear message at use time instead of
+ * at startup.
+ */
+export function resolveOriginAppCredentials(
+  env: NodeJS.ProcessEnv = process.env
+): OriginAppCredentials | undefined {
+  const { appId, installationId, privateKey } =
+    resolveOriginAppCredentialParts(env);
+  if (
+    appId === undefined ||
+    installationId === undefined ||
+    privateKey === undefined
+  ) {
+    return undefined;
+  }
+  return { appId, installationId, privateKey };
+}
+
+/** Public Origin REST base. Trailing slashes are stripped for path joins. */
+export function originPublicApiBaseUrl(
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const fromEnv = envValue(env.ORIGIN_API_BASE_URL)?.replace(/\/+$/, "");
+  return fromEnv ?? DEFAULT_ORIGIN_PUBLIC_API_BASE_URL;
+}
+
+function base64UrlJson(value: unknown): string {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+function mintOriginAppJwt(
+  credentials: OriginAppCredentials,
+  nowMs: number
+): string {
+  const now = Math.floor(nowMs / 1000);
+  const header = base64UrlJson({
+    alg: "EdDSA",
+    kid: credentials.appId,
+    typ: "JWT",
+  });
+  const payload = base64UrlJson({
+    iss: credentials.appId,
+    aud: ORIGIN_APP_TOKEN_AUDIENCE,
+    iat: now,
+    exp: now + APP_JWT_TTL_SECONDS,
+  });
+  const signingInput = `${header}.${payload}`;
+  const key = createPrivateKey(credentials.privateKey);
+  const signature = sign(null, Buffer.from(signingInput), key).toString(
+    "base64url"
+  );
+  return `${signingInput}.${signature}`;
+}
+
+async function mintOriginInstallationToken(input: {
+  credentials: OriginAppCredentials;
+  apiBaseUrl: string;
+  fetchImpl: typeof fetch;
+  nowMs: number;
+}): Promise<string> {
+  const jwt = mintOriginAppJwt(input.credentials, input.nowMs);
+  const path = `/v1/origin/app/installations/${encodeURIComponent(
+    input.credentials.installationId
+  )}/access_tokens`;
+  const response = await input.fetchImpl(`${input.apiBaseUrl}${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${jwt}` },
+    signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
+  });
+  const body: unknown = await response.json().catch(() => undefined);
+  const token =
+    typeof body === "object" && body !== null && !Array.isArray(body)
+      ? (body as Record<string, unknown>).token
+      : undefined;
+  if (!response.ok || typeof token !== "string" || token === "") {
+    // Never echo the body: on success it contains the installation token.
+    throw new OriginApiError({
+      body: undefined,
+      method: "POST",
+      path,
+      status: response.status,
+    });
+  }
+  return token;
+}
+
+/**
+ * A cached per-use token provider for one set of app credentials. Every call
+ * inside the reuse window returns the same `oit_…`; the first call after it
+ * re-mints.
+ */
+export function originAppTokenProvider(input: {
+  credentials: OriginAppCredentials;
+  apiBaseUrl?: string;
+  fetch?: typeof fetch;
+  now?: () => number;
+}): OriginTokenProvider {
+  const apiBaseUrl = input.apiBaseUrl ?? originPublicApiBaseUrl();
+  const fetchImpl = input.fetch ?? fetch;
+  const now = input.now ?? Date.now;
+  let cached: { token: string; mintedAtMs: number } | undefined;
+  return async () => {
+    const nowMs = now();
+    if (cached !== undefined && nowMs - cached.mintedAtMs < TOKEN_REUSE_MS) {
+      return cached.token;
+    }
+    const token = await mintOriginInstallationToken({
+      credentials: input.credentials,
+      apiBaseUrl,
+      fetchImpl,
+      nowMs,
+    });
+    cached = { token, mintedAtMs: nowMs };
+    return token;
+  };
+}
+
+export interface OriginClientOptions {
+  /** Static bearer (`oit_…`) or refreshing provider used for every call. */
+  token?: string | OriginTokenProvider;
+  /**
+   * App credentials to mint installation tokens from. Defaults to the
+   * environment ({@link resolveOriginAppCredentials}).
+   */
+  credentials?: OriginAppCredentials;
+  /** Public Origin REST base. Defaults to `ORIGIN_API_BASE_URL` / prod. */
+  apiBaseUrl?: string;
+  /** Injectable fetch for tests. */
+  fetch?: typeof fetch;
+}
+
+/** Minimal authenticated Origin REST client (the `Octokit` analogue). */
+export interface OriginClient {
+  readonly apiBaseUrl: string;
+  /**
+   * Call an Origin public REST path (e.g. `/v1/origin/repos/o/r/check-runs`).
+   * Throws {@link OriginApiError} on non-2xx responses.
+   */
+  request<T = unknown>(input: {
+    method: OriginApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+}
+
+/**
+ * Build an authenticated Origin REST client. Auth resolution: explicit
+ * token/provider, then app credentials (options or environment). Missing
+ * auth fails at the first request with a clear message.
+ */
+export function createOriginClient(
+  options: OriginClientOptions = {}
+): OriginClient {
+  const apiBaseUrl = (options.apiBaseUrl ?? originPublicApiBaseUrl()).replace(
+    /\/+$/,
+    ""
+  );
+  const fetchImpl = options.fetch ?? fetch;
+
+  let tokenProvider: OriginTokenProvider | undefined;
+  const getToken = async (): Promise<string> => {
+    if (typeof options.token === "string") {
+      return options.token;
+    }
+    if (typeof options.token === "function") {
+      return await options.token();
+    }
+    if (tokenProvider === undefined) {
+      const credentials = options.credentials ?? resolveOriginAppCredentials();
+      if (credentials === undefined) {
+        throw new Error(
+          "originClient: no Origin credential available (pass token / credentials, or set ORIGIN_APP_ID + ORIGIN_APP_INSTALLATION_ID + ORIGIN_APP_PRIVATE_KEY)."
+        );
+      }
+      tokenProvider = originAppTokenProvider({
+        credentials,
+        apiBaseUrl,
+        fetch: fetchImpl,
+      });
+    }
+    return await tokenProvider();
+  };
+
+  return {
+    apiBaseUrl,
+    async request<T = unknown>(input: {
+      method: OriginApiMethod;
+      path: string;
+      body?: unknown;
+    }): Promise<T> {
+      const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+      const token = await getToken();
+      const response = await fetchImpl(`${apiBaseUrl}${path}`, {
+        method: input.method,
+        headers: {
+          authorization: `Bearer ${token}`,
+          ...(input.body === undefined
+            ? {}
+            : { "content-type": "application/json" }),
+        },
+        body: input.body === undefined ? undefined : JSON.stringify(input.body),
+      });
+      const text = await response.text();
+      let parsed: unknown;
+      try {
+        parsed = text === "" ? undefined : JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+      if (!response.ok) {
+        throw new OriginApiError({
+          body: parsed,
+          method: input.method,
+          path,
+          status: response.status,
+        });
+      }
+      return parsed as T;
+    },
+  };
+}

package/src/channels/origin/binding.ts

@@ -0,0 +1,96 @@
+/**
+ * Rebuild the Origin API handle (`ctx.origin`) for inbound hooks.
+ *
+ * The handle is repo-bound and lazy: no credential is resolved until the
+ * first call, so channels without outbound Origin credentials still dispatch
+ * normally. Credential resolution combines the channel's `app` option with
+ * the environment (`ORIGIN_APP_ID` / `ORIGIN_APP_INSTALLATION_ID` /
+ * `ORIGIN_APP_PRIVATE_KEY`); the delivery's installation id fills in when
+ * neither pins one — the GitHub webhook `installation.id` analogue.
+ */
+
+import {
+  createOriginClient,
+  type OriginApiMethod,
+  type OriginClient,
+  resolveOriginAppCredentialParts,
+} from "./api.js";
+import {
+  createOriginCheck,
+  type OriginCheck,
+  type OriginCheckCreateInput,
+} from "./checks.js";
+import type { OriginAppOptions, OriginRepositoryRef } from "./types.js";
+
+/** Origin operations exposed to hooks (`ctx.origin`). */
+export interface OriginHandle {
+  /** Installation id the outbound credential is minted for, when known. */
+  installationId: string | undefined;
+  repository: OriginRepositoryRef;
+  /**
+   * Call an Origin public REST path with the channel's app credential.
+   * Throws `OriginApiError` on API failure.
+   */
+  request<T = unknown>(input: {
+    method: OriginApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+  /**
+   * Open a CI check run on `sha` and get a handle for updating and
+   * concluding it. Needs an app installation with
+   * `repository:checks:write` — Origin check writes are installation-only.
+   */
+  createCheck(
+    input: Omit<OriginCheckCreateInput, "origin" | "owner" | "repo">
+  ): Promise<OriginCheck>;
+}
+
+export function buildOriginBinding(input: {
+  repository: OriginRepositoryRef;
+  /** Installation id from the delivery envelope, when present. */
+  installationId?: string;
+  /** Channel-authored outbound app credentials / API base. */
+  app?: OriginAppOptions;
+  /** Injectable fetch for tests. */
+  fetch?: typeof fetch;
+}): OriginHandle {
+  let client: OriginClient | undefined;
+  const getClient = (): OriginClient => {
+    if (client === undefined) {
+      const fromEnv = resolveOriginAppCredentialParts();
+      const appId = input.app?.appId ?? fromEnv.appId;
+      const installationId =
+        input.app?.installationId ??
+        input.installationId ??
+        fromEnv.installationId;
+      const privateKey = input.app?.privateKey ?? fromEnv.privateKey;
+      const credentials =
+        appId !== undefined &&
+        installationId !== undefined &&
+        privateKey !== undefined
+          ? { appId, installationId, privateKey }
+          : undefined;
+      client = createOriginClient({
+        token: input.app?.token,
+        credentials,
+        apiBaseUrl: input.app?.apiBaseUrl,
+        fetch: input.fetch,
+      });
+    }
+    return client;
+  };
+
+  return {
+    installationId: input.app?.installationId ?? input.installationId,
+    repository: input.repository,
+    request: (request) => getClient().request(request),
+    createCheck: (check) =>
+      createOriginCheck({
+        ...check,
+        origin: getClient(),
+        owner: input.repository.owner,
+        repo: input.repository.name,
+      }),
+  };
+}