@zackbart/connecta 0.7.9 → 0.8.1

package/src/routes/shared.ts

@@ -0,0 +1,240 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity.js";
+import type { CredentialVault } from "../credentials.js";
+import type { DeferredWork } from "../connector-scope.js";
+import type { AdmissionController } from "../executor-admission.js";
+import type { Registry } from "../registry.js";
+import type {
+  ConnectaBranding,
+  Executor,
+  InboundAuth,
+  Logger,
+} from "../types.js";
+import { operatorPageForPath } from "../ui.js";
+
+export interface ServerOptions {
+  registry: Registry;
+  auth: InboundAuth[];
+  publicUrl?: string;
+  // The SDK's Implementation shape: name/version plus optional title,
+  // websiteUrl, and icons (MCP icons spec) that clients may render.
+  serverInfo: ConstructorParameters<typeof McpServer>[0];
+  logger: Logger;
+  activity?: ActivityStore;
+  activityReadGate?: ActivityReadGate;
+  activityDeploymentId?: string;
+  deploymentInfo?: Record<string, unknown>;
+  /** Deadline for call_tool/batch_call calls that pass no timeoutMs. Off when unset. */
+  defaultToolTimeoutMs?: number;
+  /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+  probeTimeoutMs?: number;
+  /** Maximum simultaneous connector discovery operations. Default 4. */
+  discoveryConcurrency?: number;
+  /** When set, the execute_code meta-tool is registered on top of the nine. */
+  executor?: Executor;
+  /** Global FIFO boundary for all non-preflight `/mcp` requests. */
+  requestAdmission: AdmissionController;
+  /** Encrypted connector-credential storage backing the Credentials page. */
+  credentialVault?: CredentialVault;
+  /** Optional browser UI and OAuth result-page labels. */
+  branding?: ConnectaBranding;
+}
+
+export interface RuntimeExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+export interface RouteContext {
+  request: Request;
+  url: URL;
+  path: string;
+  baseUrl: string;
+  opts: ServerOptions;
+  defer: DeferredWork | undefined;
+  runtimeContext: RuntimeExecutionContext | undefined;
+}
+
+export function msg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function privateJson(
+  body: unknown,
+  init: ResponseInit = {},
+): Response {
+  const headers = new Headers(init.headers);
+  headers.set("Content-Type", "application/json");
+  headers.set("Cache-Control", "no-store");
+  headers.set("Referrer-Policy", "no-referrer");
+  return new Response(JSON.stringify(body), { ...init, headers });
+}
+
+const MAX_LOGGED_VALUE_LENGTH = 64;
+
+/**
+ * Bounded, escaped form of a caller-influenced value (an identity id or OAuth
+ * callback connector id) for the operator log. Goes
+ * through JSON.stringify so a caller-controlled newline or control character
+ * cannot forge a log line, plus a hand-rolled escape for U+2028/U+2029, which
+ * JSON.stringify leaves raw even though a log reader treats them as line
+ * terminators. Truncated to a small shared cap so an oversized value cannot
+ * flood the log either.
+ */
+export function loggableValue(requested: string): string {
+  const bounded = requested.slice(0, MAX_LOGGED_VALUE_LENGTH);
+  const escaped = JSON.stringify(bounded).replace(
+    /[\u2028\u2029]/g,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16)}`,
+  );
+  return escaped + (bounded.length < requested.length ? " (truncated)" : "");
+}
+
+const ACTIVITY_ACTOR_NAMESPACE_RE = /^[\x21-\x7e]{1,256}$/;
+
+export function activityActorNamespace(
+  provider: InboundAuth,
+): string | undefined {
+  return typeof provider.activityActorNamespace === "string" &&
+    ACTIVITY_ACTOR_NAMESPACE_RE.test(provider.activityActorNamespace)
+    ? provider.activityActorNamespace
+    : undefined;
+}
+
+export async function authorize(
+  request: Request,
+  baseUrl: string,
+  auth: InboundAuth[],
+): Promise<
+  | {
+      ok: true;
+      actor: ActivityActor;
+      /** True only when the admitting provider can also authorize UI mutation. */
+      uiAdminEligible?: boolean;
+    }
+  | { ok: false; response: Response }
+> {
+  if (auth.length === 0) {
+    return { ok: true, actor: { kind: "anonymous" } };
+  }
+  let lastResponse: Response | null = null;
+  for (const provider of auth) {
+    const result = await provider.authorize(request, baseUrl);
+    if (result.ok) {
+      const subjectId = result.subjectId ?? result.userId;
+      const actorNamespace = activityActorNamespace(provider);
+      return {
+        ok: true,
+        actor: {
+          kind: provider.kind,
+          ...(subjectId ? { id: subjectId } : {}),
+          ...(subjectId && actorNamespace
+            ? { namespace: actorNamespace }
+            : {}),
+        },
+        ...(result.userId && provider.uiAuth?.kind === "clerk"
+          ? { uiAdminEligible: true }
+          : {}),
+      };
+    }
+    lastResponse = result.response;
+  }
+  return {
+    ok: false,
+    response:
+      lastResponse ??
+      new Response(JSON.stringify({ error: "unauthorized" }), {
+        status: 401,
+        headers: {
+          "Content-Type": "application/json",
+          "WWW-Authenticate": "Bearer",
+        },
+      }),
+  };
+}
+
+export async function authorizeUiAdmin(
+  request: Request,
+  baseUrl: string,
+  auth: InboundAuth[],
+  purpose = "credential management",
+): Promise<{ ok: true; userId: string } | { ok: false; response: Response }> {
+  // Operator mutation is intentionally narrower than /mcp and /ui/data: only
+  // an interactive Clerk provider may admit it. A static bearer token is useful
+  // for headless tool calls but must not become a deployment-admin key.
+  //
+  // Every Clerk provider gets a turn, the way the /mcp gate does. Stopping at
+  // the first would make admission depend on config order: a failed gate or
+  // missing user may simply mean a later provider is the one meant to admit.
+  // The last refusal is returned if none do.
+  const providers = auth.filter(
+    (candidate) => candidate.uiAuth?.kind === "clerk",
+  );
+  if (providers.length === 0) {
+    return {
+      ok: false,
+      response: privateJson(
+        { error: `${purpose} requires Clerk authentication` },
+        { status: 403 },
+      ),
+    };
+  }
+  let lastResponse: Response | null = null;
+  for (const provider of providers) {
+    const result = await provider.authorize(request, baseUrl);
+    if (!result.ok) {
+      lastResponse = result.response;
+      continue;
+    }
+    if (!result.userId) {
+      lastResponse = privateJson(
+        { error: "authenticated user required" },
+        { status: 403 },
+      );
+      continue;
+    }
+    return { ok: true, userId: result.userId };
+  }
+  return {
+    ok: false,
+    response:
+      lastResponse ??
+      privateJson({ error: "forbidden" }, { status: 403 }),
+  };
+}
+
+export function isSameOrigin(request: Request, baseUrl: string): boolean {
+  const origin = request.headers.get("origin");
+  if (!origin) return false;
+  try {
+    return new URL(origin).origin === new URL(baseUrl).origin;
+  } catch {
+    return false;
+  }
+}
+
+export function withSecurityHeaders(
+  response: Response,
+  requestUrl: URL,
+  path: string,
+): Response {
+  const headers = new Headers(response.headers);
+  headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("Referrer-Policy", "no-referrer");
+  if (requestUrl.protocol === "https:") {
+    headers.set("Strict-Transport-Security", "max-age=31536000");
+  }
+  if (operatorPageForPath(path) || path === "/ui") {
+    // Operator HTML responses ship their own nonce-based script CSP (which
+    // already includes frame-ancestors 'none'); only fall back to the
+    // framing-only directive when no CSP is present (for example redirects).
+    if (!headers.has("Content-Security-Policy")) {
+      headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+    }
+    headers.set("X-Frame-Options", "DENY");
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/routes/ui.ts

@@ -0,0 +1,143 @@
+import { CONNECTA_FAVICON_ICO } from "../favicon.js";
+import {
+  buildUiData,
+  CONNECTA_FAVICON_SVG,
+  credentialManagementCapability,
+  operatorPageForPath,
+  renderUiHtml,
+} from "../ui.js";
+import {
+  authorize,
+  privateJson,
+  type RouteContext,
+} from "./shared.js";
+
+/**
+ * Headers that make an operator-supplied favicon body inert on this origin.
+ * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
+ * so a `<script>` inside a branding SVG would run on the deployment origin the
+ * moment anyone navigated straight to `/favicon.svg` — strictly more powerful
+ * than the `favicon.href` vector the branding gates close, because the payload
+ * is same-origin. Neutralizing the response rather than inspecting the body
+ * keeps every valid static SVG (the built-in mark included) byte-identical:
+ *
+ * - `sandbox` (no tokens ⇒ every restriction) drops the document into an opaque
+ *   origin with scripting off, so even a script that ran would have nothing to
+ *   reach.
+ * - `default-src 'none'` denies script, network, and framing outright.
+ * - `style-src 'unsafe-inline'` is the single allowance: the default mark styles
+ *   itself inline to follow the OS colour scheme, and CSS cannot script.
+ * - `nosniff` keeps the declared type authoritative in both directions — an SVG
+ *   can never be re-read as HTML, and `.ico` bytes can never be re-read as SVG.
+ *
+ * `.ico` bodies are deliberately in scope: they are inert bytes rather than
+ * active content, so they are still served verbatim, but they carry the same
+ * headers so the invariant is "every favicon route is neutralized" rather than
+ * "whichever route got attention".
+ */
+const INERT_ICON_HEADERS = {
+  "Content-Security-Policy":
+    "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+  "X-Content-Type-Options": "nosniff",
+};
+
+/** Per-request base64 nonce for an operator shell's scripts (Node 20+ and Workers). */
+function uiScriptNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export async function routeUi(
+  context: RouteContext,
+): Promise<Response | null> {
+  const { request, url, path, baseUrl, opts, defer } = context;
+  if (request.method === "GET" && path === "/favicon.svg") {
+    return new Response(opts.branding?.favicon?.svg ?? CONNECTA_FAVICON_SVG, {
+      headers: {
+        "Content-Type": "image/svg+xml",
+        "Cache-Control": "public, max-age=86400",
+        ...INERT_ICON_HEADERS,
+      },
+    });
+  }
+  if (request.method === "GET" && path === "/favicon.ico") {
+    return new Response(opts.branding?.favicon?.ico ?? CONNECTA_FAVICON_ICO, {
+      headers: {
+        "Content-Type": "image/x-icon",
+        "Cache-Control": "public, max-age=86400",
+        ...INERT_ICON_HEADERS,
+      },
+    });
+  }
+  if (path === "/ui") {
+    if (request.method !== "GET") {
+      return privateJson({ error: "method not allowed" }, { status: 405 });
+    }
+    const target = new URL(`/${url.search}`, baseUrl);
+    return new Response(null, {
+      status: 308,
+      headers: { Location: target.toString() },
+    });
+  }
+
+  const operatorPage = operatorPageForPath(path);
+  if (operatorPage) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return privateJson({ error: "method not allowed" }, { status: 405 });
+    }
+    // Open shell — carries no operator data; everything comes from the
+    // authenticated /ui/* APIs after the browser establishes a session.
+    const uiAuth = opts.auth.find((provider) => provider.uiAuth)?.uiAuth;
+    const mcpUrl = new URL("/mcp", baseUrl).toString();
+    // Nonce the page's inline script (and the Clerk loader). 'strict-dynamic'
+    // lets scripts the nonced Clerk loader injects at runtime execute; the
+    // https:/'unsafe-inline' fallbacks are ignored by CSP3 browsers that
+    // honour the nonce and only cover legacy ones. No default-src, so Clerk's
+    // style/font/network needs and the page's inline <style> stay unrestricted
+    // — only script execution, the XSS sink, is gated.
+    const nonce = uiScriptNonce();
+    return new Response(
+      request.method === "HEAD"
+        ? null
+        : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
+      {
+        status: 200,
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+          "Content-Security-Policy":
+            `script-src 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'; ` +
+            "object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+          "X-Content-Type-Options": "nosniff",
+        },
+      },
+    );
+  }
+  if (path !== "/ui/data") return null;
+
+  const authz = await authorize(request, baseUrl, opts.auth);
+  if (!authz.ok) return authz.response;
+  const eligibleClerkOperator = authz.uiAdminEligible === true;
+  const credentialManagement = credentialManagementCapability({
+    eligibleClerkOperator,
+    hasCredentialSlots: opts.registry
+      .listConnectors()
+      .some((connector) => Boolean(connector.credential)),
+    hasCredentialVault: Boolean(opts.credentialVault),
+  });
+  const data = await buildUiData(
+    opts.registry,
+    baseUrl,
+    opts.serverInfo,
+    // The static headless bearer may read connector health, but only a
+    // Clerk-authenticated operator receives credential metadata.
+    eligibleClerkOperator ? opts.credentialVault : undefined,
+    Boolean(opts.activity?.list),
+    credentialManagement,
+    defer,
+    eligibleClerkOperator,
+    opts.discoveryConcurrency,
+  );
+  return privateJson(data);
+}