@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/slack/upload.ts

@@ -1,137 +0,0 @@
-import { constants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
-import { extname, sep } from "node:path";
-import { callSlackApiSoft } from "./api.js";
-import type { SlackBotToken } from "./types.js";
-
-const ALLOWED = new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".svg",
-  ".pdf",
-  ".html",
-  ".txt",
-  ".log",
-  ".json",
-  ".csv",
-  ".md",
-  ".mp4",
-  ".mov",
-  ".webm",
-]);
-
-const MAX_BYTES = 50 * 1024 * 1024;
-
-export interface ThreadFile {
-  path: string;
-  name: string;
-  workspace: string;
-}
-
-async function readJailed(file: ThreadFile): Promise<Buffer | string> {
-  if (file.workspace === "") {
-    return `${file.name}: missing workspace`;
-  }
-  const info = await lstat(file.path);
-  if (info.isSymbolicLink() || !info.isFile()) {
-    return `${file.name}: not a regular file`;
-  }
-  const real = await realpath(file.path);
-  const root = await realpath(file.workspace);
-  if (real !== root && !real.startsWith(`${root}${sep}`)) {
-    return `${file.name}: outside workspace`;
-  }
-  const nofollow = constants.O_NOFOLLOW;
-  const flags = nofollow === undefined ? constants.O_RDONLY : constants.O_RDONLY | nofollow;
-  const handle = await open(file.path, flags);
-  try {
-    const bytes = await handle.readFile();
-    if (bytes.byteLength > MAX_BYTES) {
-      return `${file.name}: over the upload cap`;
-    }
-    const extension = extname(file.path).toLowerCase();
-    if (!ALLOWED.has(extension)) {
-      return `${file.name}: type Slack does not render`;
-    }
-    return bytes;
-  } finally {
-    await handle.close();
-  }
-}
-
-export async function uploadThreadFiles(args: {
-  botToken: SlackBotToken | undefined;
-  channelId: string;
-  threadTs?: string;
-  files: readonly ThreadFile[];
-}): Promise<string[]> {
-  if (args.files.length === 0) {
-    return [];
-  }
-
-  const failures: string[] = [];
-  const uploaded: Array<{ id: string; title: string }> = [];
-  for (const file of args.files) {
-    let bytes: Buffer;
-    try {
-      const read = await readJailed(file);
-      if (typeof read === "string") {
-        failures.push(read);
-        continue;
-      }
-      bytes = read;
-    } catch (error) {
-      failures.push(`${file.name}: gone before upload (${String(error)})`);
-      continue;
-    }
-    const reserved = await callSlackApiSoft({
-      botToken: args.botToken,
-      operation: "files.getUploadURLExternal",
-      body: { filename: file.name, length: bytes.byteLength },
-    });
-    if (!reserved.ok) {
-      failures.push(`${file.name}: could not reserve upload (${reserved.error})`);
-      continue;
-    }
-    const uploadUrl = reserved.upload_url;
-    const fileId = reserved.file_id;
-    if (typeof uploadUrl !== "string" || typeof fileId !== "string") {
-      failures.push(`${file.name}: could not reserve upload (malformed reserve response)`);
-      continue;
-    }
-    try {
-      const put = await fetch(uploadUrl, {
-        method: "POST",
-        body: bytes as unknown as BodyInit,
-      });
-      if (!put.ok) {
-        failures.push(`${file.name}: upload returned ${put.status}`);
-        continue;
-      }
-    } catch (error) {
-      failures.push(`${file.name}: upload failed (${String(error)})`);
-      continue;
-    }
-    uploaded.push({ id: fileId, title: file.name });
-  }
-
-  if (uploaded.length === 0) {
-    return failures;
-  }
-  const shared = await callSlackApiSoft({
-    botToken: args.botToken,
-    operation: "files.completeUploadExternal",
-    body: {
-      files: uploaded,
-      channel_id: args.channelId,
-      thread_ts: args.threadTs,
-    },
-  });
-  if (!shared.ok) {
-    failures.push(`${uploaded.length} file(s): ${String(shared.error)}`);
-  }
-  return failures;
-}

package/src/channels.ts

@@ -1,543 +0,0 @@
-/**
- * `defineChannel` — authored at `agent/channels/<name>.ts`.
- *
- * A channel is the surface an agent lives on. The built-in HTTP session
- * channel (session create / follow-up / NDJSON stream routes under
- * `/v1/session*`) is always mounted. Custom channels declare their own
- * routes and are mounted under `/v1/channels/<name>`:
- *
- * ```ts
- * import { defineChannel, POST } from "@cursor/bdk/channels";
- * import { z } from "zod";
- *
- * export default defineChannel({
- *   routes: [
- *     POST("/message", {
- *       bodySchema: z.object({
- *         message: z.string(),
- *         token: z.string().optional(),
- *       }),
- *       handler: async (_req, { send, body }) => {
- *         const { message, token } = body as {
- *           message: string;
- *           token?: string;
- *         };
- *         const session = await send(message, {
- *           continuationToken: token,
- *         });
- *         return Response.json({ sessionId: session.id });
- *       },
- *     }),
- *   ],
- *   events: {
- *     "message.completed"(event, channel, ctx) {
- *       // deliver completed messages back to the surface that owns this
- *       // channel (post to a webhook, reply in a thread, ...)
- *     },
- *   },
- * });
- * ```
- *
- * Route helpers are typed so HTTP channels must declare **Zod** schemas at
- * compile time: `GET` requires `querySchema`, `POST`/`PUT`/`PATCH` require
- * `bodySchema`. Plain JSON Schema objects will not type-check. Use
- * `z.object({})` / `z.unknown()` when the surface is intentionally open.
- * Handlers receive `args.body` / `args.query` inferred from those schemas.
- */
-
-export {
-  type CiCheck,
-  type CiCheckConcludeInput,
-  type CiCheckConclusion,
-  type CiCheckCreateInput,
-  type CiCheckOutput,
-  type CiCheckRef,
-  type CiCheckStatus,
-  type CiChecksClient,
-  type CiCheckUpdateInput,
-  type CiCheckWrite,
-  type CiCheckWriter,
-  openCiCheck,
-  resumeCiCheck,
-} from "./channels/checks.js";
-
-import { Buffer } from "node:buffer";
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { brandDefinition } from "./internal/brand.js";
-import { attachCatchAdmission } from "./internal/hosted-catch.js";
-import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
-import type {
-  AuthContext,
-  AuthPolicy,
-  ChannelBodyRouteSpec,
-  ChannelConfig,
-  ChannelDefinition,
-  ChannelDeleteRouteSpec,
-  ChannelGetRouteSpec,
-  ChannelRoute,
-  ChannelRouteHandler,
-  ChannelRouteSchema,
-  HttpChannelConfig,
-  HttpChannelDefinition,
-  JsonValue,
-  RouteMethod,
-} from "./types.js";
-
-/** Configure the built-in HTTP session channel at `agent/channels/http.ts`. */
-export { httpChannel } from "./internal/http-channel-define.js";
-export type {
-  AuthContext,
-  AuthPolicy,
-  ChannelBodyRouteSpec,
-  ChannelConfig,
-  ChannelDefinition,
-  ChannelDeleteRouteSpec,
-  ChannelEventContext,
-  ChannelEventHandler,
-  ChannelEventHandlers,
-  ChannelGetRouteSpec,
-  ChannelHandlerArgs,
-  ChannelHandlerArgsWithBody,
-  ChannelHandlerArgsWithBodyAndQuery,
-  ChannelHandlerArgsWithQuery,
-  ChannelRoute,
-  ChannelRouteHandler,
-  ChannelRouteSchema,
-  ChannelSession,
-  ChannelStartArgs,
-  HttpChannelConfig,
-  HttpChannelDefinition,
-  HttpSessionAdmitInfo,
-  ReceiveInput,
-  RouteMethod,
-  SendMessageFn,
-  SendMessageOptions,
-} from "./types.js";
-export { HttpSessionAdmitError } from "./types.js";
-
-/** Define a custom channel. */
-export function defineChannel<TState = JsonValue>(
-  config: ChannelConfig<TState>,
-): ChannelDefinition<TState> {
-  const definition = brandDefinition("channel", config);
-  if (config.routes !== undefined && config.routes.length > 0) {
-    // Hosted: the control plane catches declared routes and replays them
-    // here. Provider packs attach their own admission afterwards.
-    attachCatchAdmission(definition as ChannelDefinition<unknown>, config.routes);
-  }
-  return definition;
-}
-
-// ============================================================================
-// Route verbs
-// ============================================================================
-
-function route(
-  method: RouteMethod,
-  path: string,
-  spec: {
-    description?: string;
-    bodySchema?: ChannelRouteSchema;
-    querySchema?: ChannelRouteSchema;
-    handler: ChannelRouteHandler;
-  },
-): ChannelRoute {
-  if (!path.startsWith("/")) {
-    throw new Error(`Channel route path must start with "/": ${path}`);
-  }
-  const result: ChannelRoute = {
-    method,
-    path,
-    handler: spec.handler,
-  };
-  if (spec.description !== undefined) {
-    result.description = spec.description;
-  }
-  if (spec.bodySchema !== undefined) {
-    result.bodySchema = spec.bodySchema;
-  }
-  if (spec.querySchema !== undefined) {
-    result.querySchema = spec.querySchema;
-  }
-  return result;
-}
-
-/** GET — Zod `querySchema` is required (use `z.object({})` when unused). */
-export function GET<TQuery extends ChannelRouteSchema>(
-  path: string,
-  spec: ChannelGetRouteSpec<TQuery>,
-): ChannelRoute {
-  return route("GET", path, {
-    description: spec.description,
-    querySchema: spec.querySchema,
-    handler: spec.handler as ChannelRouteHandler,
-  });
-}
-
-/** POST — Zod `bodySchema` is required. */
-export function POST<
-  TBody extends ChannelRouteSchema,
-  TQuery extends ChannelRouteSchema | undefined = undefined,
->(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
-  return route("POST", path, {
-    description: spec.description,
-    bodySchema: spec.bodySchema,
-    querySchema: spec.querySchema,
-    handler: spec.handler as ChannelRouteHandler,
-  });
-}
-
-/** PUT — Zod `bodySchema` is required. */
-export function PUT<
-  TBody extends ChannelRouteSchema,
-  TQuery extends ChannelRouteSchema | undefined = undefined,
->(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
-  return route("PUT", path, {
-    description: spec.description,
-    bodySchema: spec.bodySchema,
-    querySchema: spec.querySchema,
-    handler: spec.handler as ChannelRouteHandler,
-  });
-}
-
-/** PATCH — Zod `bodySchema` is required. */
-export function PATCH<
-  TBody extends ChannelRouteSchema,
-  TQuery extends ChannelRouteSchema | undefined = undefined,
->(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
-  return route("PATCH", path, {
-    description: spec.description,
-    bodySchema: spec.bodySchema,
-    querySchema: spec.querySchema,
-    handler: spec.handler as ChannelRouteHandler,
-  });
-}
-
-/** DELETE — Zod schemas optional. */
-export function DELETE<
-  TBody extends ChannelRouteSchema | undefined = undefined,
-  TQuery extends ChannelRouteSchema | undefined = undefined,
->(path: string, spec: ChannelDeleteRouteSpec<TBody, TQuery>): ChannelRoute {
-  return route("DELETE", path, {
-    description: spec.description,
-    bodySchema: spec.bodySchema,
-    querySchema: spec.querySchema,
-    handler: spec.handler,
-  });
-}
-
-// ============================================================================
-// Auth policies
-// ============================================================================
-
-/**
- * Admit requests that arrive over the loopback interface with no proxy
- * forwarding headers. The default route policy: local tooling works out of
- * the box while remote (or reverse-proxied) callers are rejected until you
- * wire real auth (e.g. {@link bearerAuth}).
- *
- * Requests carrying `X-Forwarded-For`, `X-Real-IP`, `Forwarded`, or
- * `X-Forwarded-Host` are denied even when the TCP peer is 127.0.0.1 — that
- * pattern is how tunnels and same-host reverse proxies re-expose loopback.
- */
-export function localDev(): AuthPolicy {
-  return (request, info) => {
-    if (hasProxyForwardingHeaders(request)) {
-      return null;
-    }
-    if (info.requestIp !== null && isLoopbackAddress(info.requestIp)) {
-      return {
-        authenticator: "local-dev",
-        principalId: "local",
-        principalType: "user",
-      };
-    }
-    return null;
-  };
-}
-
-/**
- * Like {@link localDev} but also requires the request URL hostname to be
- * loopback. Rejects DNS-rebinding callers that reach 127.0.0.1 with a remote
- * `Host` header (e.g. attacker.example after rebinding to localhost).
- */
-export function localDevStrict(): AuthPolicy {
-  return (request, info) => {
-    if (localDev()(request, info) === null) {
-      return null;
-    }
-    let hostname: string;
-    try {
-      hostname = new URL(request.url).hostname;
-    } catch {
-      return null;
-    }
-    if (!isLoopbackHostname(hostname)) {
-      return null;
-    }
-    return {
-      authenticator: "local-dev-strict",
-      principalId: "local",
-      principalType: "user",
-    };
-  };
-}
-
-/**
- * Admit requests whose TCP peer is loopback, ignoring `Host` and
- * proxy-forwarding headers. The peer address (`req.socket.remoteAddress`) is
- * the real boundary: a loopback-bound server only accepts local processes, and
- * a LAN caller's peer IP is non-loopback and rejected. Unlike {@link localDev},
- * this does not veto on `X-Forwarded-*` headers — so it admits loopback clients
- * that legitimately relay them, e.g. `gh webhook forward`, which forwards
- * GitHub's edge `X-Forwarded-For` / `X-Real-Ip`. Intended for dev-only relaxed
- * auth where remote exposure is still refused.
- */
-export function loopbackOnly(): AuthPolicy {
-  return (_request, info) => {
-    if (info.requestIp !== null && isLoopbackAddress(info.requestIp)) {
-      return {
-        authenticator: "loopback-only",
-        principalId: "local",
-        principalType: "user",
-      };
-    }
-    return null;
-  };
-}
-
-function hasGitHubWebhookDeliveryHeaders(request: Request): boolean {
-  const event = request.headers.get("x-github-event");
-  return event !== null && event.trim() !== "";
-}
-
-/**
- * Dev-only GitHub channel auth without a webhook secret: loopback peer
- * required. Plain local fixtures (no proxy headers) are admitted; deliveries
- * relayed through `gh webhook forward` carry GitHub's `X-Forwarded-*` headers
- * and are admitted only when `X-GitHub-Event` is present (GitHub deliveries
- * always include it). Loopback tunnels that relay arbitrary remote traffic
- * without those delivery headers stay rejected.
- */
-export function loopbackGitHubDev(): AuthPolicy {
-  return (request, info) => {
-    if (info.requestIp === null || !isLoopbackAddress(info.requestIp)) {
-      return null;
-    }
-    if (hasProxyForwardingHeaders(request) && !hasGitHubWebhookDeliveryHeaders(request)) {
-      return null;
-    }
-    return {
-      authenticator: "loopback-github-dev",
-      principalId: "local",
-      principalType: "user",
-    };
-  };
-}
-
-function hasProxyForwardingHeaders(request: Request): boolean {
-  return (
-    request.headers.has("x-forwarded-for") ||
-    request.headers.has("x-forwarded-host") ||
-    request.headers.has("x-real-ip") ||
-    request.headers.has("forwarded")
-  );
-}
-
-/**
- * Admit requests carrying `Authorization: Bearer <token>`. Pass the expected
- * token (compared in constant time) or a verifier that maps a presented
- * token to an {@link AuthContext}.
- */
-export function bearerAuth(
-  tokenOrVerify: string | ((token: string) => AuthContext | null | Promise<AuthContext | null>),
-): AuthPolicy {
-  return async request => {
-    const header = request.headers.get("authorization");
-    if (header === null || !header.toLowerCase().startsWith("bearer ")) {
-      return null;
-    }
-    const presented = header.slice("bearer ".length).trim();
-    if (typeof tokenOrVerify === "function") {
-      return await tokenOrVerify(presented);
-    }
-    if (tokenOrVerify !== "" && constantTimeEquals(presented, tokenOrVerify)) {
-      return {
-        authenticator: "bearer",
-        principalId: "bearer",
-        principalType: "service",
-      };
-    }
-    return null;
-  };
-}
-
-function constantTimeEquals(a: string, b: string): boolean {
-  const aBytes = Buffer.from(a);
-  const bBytes = Buffer.from(b);
-  if (aBytes.length !== bBytes.length) {
-    return false;
-  }
-  return timingSafeEqual(aBytes, bBytes);
-}
-
-/**
- * Admit every request as an anonymous principal. Only for surfaces that are
- * intentionally public or protected upstream.
- */
-export function allowAll(): AuthPolicy {
-  return () => ({
-    authenticator: "allow-all",
-    principalId: "anonymous",
-    principalType: "user",
-  });
-}
-
-/**
- * `Symbol.for` so the marker survives duplicated copies of the framework in
- * one process (e.g. a monorepo agent resolving its own `@cursor/bdk`).
- */
-const PUBLIC_ENDPOINT_MARKER = Symbol.for("agent-serve.public-endpoint");
-
-/**
- * Like {@link allowAll}, but ALSO declares the channel publicly reachable on
- * Cursor's managed hosting: `deploy` collects every channel whose auth chain
- * contains this policy and the platform serves that channel's routes
- * (`/v1/channels/<id>/…`) through the stable alias WITHOUT
- * `X-Agent-Alias-Token`.
- *
- * Use it for webhook senders that cannot attach custom headers (Linear,
- * Stripe, …) — **the handler must authenticate deliveries itself**, e.g. by
- * verifying the provider's HMAC signature over the raw body. Everything
- * else (sessions, MCP, playground) stays behind platform auth.
- *
- * Locally this admits every caller, exactly like `allowAll()`.
- */
-export function publicEndpoint(): AuthPolicy {
-  const policy: AuthPolicy = () => ({
-    authenticator: "public-endpoint",
-    principalId: "anonymous",
-    principalType: "user",
-  });
-  // On the v2 control plane this also makes the channel's routes catchable
-  // with handler-side verification (the v1 alias posture): the CP admits
-  // every request on a declared route and the handler rejects bad ones.
-  return markCatchAuth(Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const }), {
-    kind: "public",
-  });
-}
-
-/** True when a policy was created by {@link publicEndpoint}. */
-export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
-  return (policy as { [PUBLIC_ENDPOINT_MARKER]?: unknown })[PUBLIC_ENDPOINT_MARKER] === true;
-}
-
-const CATCH_AUTH_MARKER = Symbol.for("agent-serve.catch-auth");
-
-/**
- * What `deploy` extracts from a {@link sharedSecretAuth} /
- * {@link hmacSignatureAuth} policy into the manifest: the control plane runs
- * the same check with the deployment secret of the same name before any
- * compute starts. `secret` is a name, never a value.
- */
-export type CatchAuthDeclaration =
-  | { kind: "header"; header: string; secret: string }
-  | { kind: "hmac-sha256"; header: string; secret: string; prefix?: string }
-  /** `publicEndpoint()`: the handler verifies; the control plane only rate limits. */
-  | { kind: "public" };
-
-function markCatchAuth(policy: AuthPolicy, declaration: CatchAuthDeclaration): AuthPolicy {
-  return Object.assign(policy, { [CATCH_AUTH_MARKER]: declaration });
-}
-
-/** The catch declaration a policy carries, if it is a catch-capable policy. */
-export function catchAuthDeclaration(policy: AuthPolicy): CatchAuthDeclaration | undefined {
-  const declaration = (policy as { [CATCH_AUTH_MARKER]?: unknown })[CATCH_AUTH_MARKER];
-  return typeof declaration === "object" && declaration !== null
-    ? (declaration as CatchAuthDeclaration)
-    : undefined;
-}
-
-function presentedHeaderSecret(headerName: string, value: string): string {
-  if (headerName === "authorization" && value.toLowerCase().startsWith("bearer ")) {
-    return value.slice("bearer ".length).trim();
-  }
-  return value.trim();
-}
-
-/**
- * Admit requests whose `header` equals the secret named `secret` (an
- * `Authorization: Bearer <secret>` header also matches). Locally the value
- * is `process.env[secret]`; hosted, the deployment secret of that name. On
- * Cursor hosting this ALSO declares the channel's routes reachable through
- * the control-plane catch API, which runs the same comparison before any
- * compute exists. An unset secret admits nothing.
- */
-export function sharedSecretAuth(options: { header: string; secret: string }): AuthPolicy {
-  const header = options.header.toLowerCase();
-  const policy: AuthPolicy = request => {
-    const expected = process.env[options.secret];
-    const presented = request.headers.get(header);
-    if (
-      expected === undefined ||
-      expected.length === 0 ||
-      presented === null ||
-      !constantTimeEquals(presentedHeaderSecret(header, presented), expected)
-    ) {
-      return null;
-    }
-    return {
-      authenticator: "shared-secret",
-      principalId: "webhook",
-      principalType: "service",
-    };
-  };
-  return markCatchAuth(policy, {
-    kind: "header",
-    header,
-    secret: options.secret,
-  });
-}
-
-/**
- * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
- * under the secret named `secret` (optionally behind a literal `prefix`
- * such as `sha256=`). Same local / hosted / catch semantics as
- * {@link sharedSecretAuth}.
- */
-export function hmacSignatureAuth(options: {
-  header: string;
-  secret: string;
-  prefix?: string;
-}): AuthPolicy {
-  const header = options.header.toLowerCase();
-  const prefix = options.prefix ?? "";
-  const policy: AuthPolicy = async request => {
-    const secret = process.env[options.secret];
-    const presented = request.headers.get(header)?.trim();
-    if (
-      secret === undefined ||
-      secret.length === 0 ||
-      presented === undefined ||
-      !presented.startsWith(prefix)
-    ) {
-      return null;
-    }
-    const body = Buffer.from(await request.clone().arrayBuffer());
-    const expected = createHmac("sha256", secret).update(body).digest("hex");
-    if (!constantTimeEquals(presented.slice(prefix.length).toLowerCase(), expected)) {
-      return null;
-    }
-    return {
-      authenticator: "hmac-signature",
-      principalId: "webhook",
-      principalType: "service",
-    };
-  };
-  return markCatchAuth(policy, {
-    kind: "hmac-sha256",
-    header,
-    secret: options.secret,
-    prefix: options.prefix,
-  });
-}