@zackbart/connecta 0.7.9 → 0.8.0

package/src/routes/oauth.ts

@@ -0,0 +1,328 @@
+import { oauthValueStorageKey } from "../auth/downstream-oauth.js";
+import { closeConnectorScope } from "../connector-scope.js";
+import type {
+  ConnectorContext,
+  ConnectorStatus,
+  ConnectaBranding,
+} from "../types.js";
+import { isSafeHttpUrl, resolveBranding } from "../ui.js";
+import {
+  authorizeUiAdmin,
+  isSameOrigin,
+  loggableValue,
+  msg,
+  privateJson,
+  type RouteContext,
+} from "./shared.js";
+
+async function handleOAuthManagementRequest(
+  context: RouteContext,
+  connectorId: string,
+): Promise<Response> {
+  const { request, baseUrl, opts, defer } = context;
+  if (!isSameOrigin(request, baseUrl)) {
+    return privateJson(
+      { error: "same-origin request required" },
+      { status: 403 },
+    );
+  }
+  const admin = await authorizeUiAdmin(
+    request,
+    baseUrl,
+    opts.auth,
+    opts.logger,
+    "OAuth management",
+  );
+  if (!admin.ok) return admin.response;
+
+  const connector = opts.registry.getConnector(connectorId);
+  if (!connector?.disconnectAuth || !connector.startAuth) {
+    return privateJson(
+      { error: "unknown OAuth connector" },
+      { status: 404 },
+    );
+  }
+  if (request.method !== "DELETE" && request.method !== "POST") {
+    return privateJson({ error: "method not allowed" }, { status: 405 });
+  }
+
+  const requestScope = {};
+  const ctx = opts.registry.contextFor(connectorId, baseUrl, requestScope);
+  try {
+    let result: ConnectorStatus | undefined;
+    let operationError: unknown;
+    try {
+      if (request.method === "DELETE") {
+        await connector.disconnectAuth(ctx);
+      } else {
+        result = await connector.startAuth(ctx, { force: true });
+      }
+    } catch (error) {
+      operationError = error;
+    }
+
+    // The old grant and its catalog verdict are invalid after either operation,
+    // including a partially failed physical cleanup whose epoch fence succeeded.
+    try {
+      await opts.registry.invalidateStored(connectorId);
+      await opts.registry.clearCredentialHealth(connectorId);
+    } catch (error) {
+      operationError ??= error;
+    }
+    if (operationError) {
+      return privateJson({ error: msg(operationError) }, { status: 400 });
+    }
+    if (request.method === "DELETE") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          "Cache-Control": "no-store",
+          "Referrer-Policy": "no-referrer",
+        },
+      });
+    }
+
+    const authorizationUrl = isSafeHttpUrl(result!.authorizationUrl)
+      ? result!.authorizationUrl
+      : undefined;
+    if (result!.state === "error") {
+      return privateJson(
+        { error: result!.message || "OAuth authorization could not start" },
+        { status: 502 },
+      );
+    }
+    if (result!.state === "auth_required" && !authorizationUrl) {
+      return privateJson(
+        {
+          error:
+            result!.message ||
+            "OAuth authorization requires consent but no safe URL is available",
+        },
+        { status: 502 },
+      );
+    }
+    return privateJson({
+      state: result!.state,
+      ...(result!.message ? { message: result!.message } : {}),
+      ...(authorizationUrl ? { authorizationUrl } : {}),
+    });
+  } finally {
+    await closeConnectorScope(connector, ctx, defer);
+  }
+}
+
+export async function routeOAuthManagement(
+  context: RouteContext,
+): Promise<Response | null> {
+  const match = /^\/ui\/oauth\/([a-z0-9_-]+)$/.exec(context.path);
+  if (!match) return null;
+  const connectorId = match[1];
+  if (!connectorId) return null;
+  if (context.request.method === "OPTIONS") {
+    return privateJson({ error: "method not allowed" }, { status: 405 });
+  }
+  return handleOAuthManagementRequest(context, connectorId);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/** `body` is escaped — callback params and error messages are attacker-influenced. */
+function html(
+  body: string,
+  status = 200,
+  branding?: ConnectaBranding,
+): Response {
+  const brand = resolveBranding(branding);
+  const title = brand.pageTitle;
+  const owner = brand.ownerName
+    ? brand.ownerUrl
+      ? `<a class="brand" href="${escapeHtml(brand.ownerUrl)}">${escapeHtml(brand.ownerName)}</a>`
+      : `<span class="brand">${escapeHtml(brand.ownerName)}</span>`
+    : brand.productUrl
+      ? `<a class="brand" href="${escapeHtml(brand.productUrl)}">${escapeHtml(brand.productName)}</a>`
+      : `<span class="brand">${escapeHtml(brand.productName)}</span>`;
+  const product = brand.ownerName
+    ? brand.productUrl
+      ? `<a class="product" href="${escapeHtml(brand.productUrl)}">${escapeHtml(brand.productName)}</a>`
+      : `<span class="product">${escapeHtml(brand.productName)}</span>`
+    : "";
+  return new Response(
+    `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="theme-color" content="${escapeHtml(brand.themeColor)}">
+<link rel="icon" href="${escapeHtml(brand.faviconHref)}" type="image/svg+xml">
+<link rel="shortcut icon" href="/favicon.ico">
+<title>${escapeHtml(title)}</title>
+<style>
+  * { border-radius: 0; box-sizing: border-box; }
+  html { color: #000; background: #fff; font: 16px/1.5 "Helvetica Neue",
+    Helvetica, Arial, sans-serif; -webkit-font-smoothing: antialiased; }
+  body { margin: 0; min-height: 100vh; }
+  ::selection { color: #fff; background: #000; }
+  .shell { margin: 0 auto; max-width: 70rem; padding: 1rem; }
+  .grid { display: grid; gap: 1rem 1.5rem;
+    grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  .brand { font-weight: 500; grid-column: 1; text-decoration: none; }
+  .product { grid-column: 2 / -1; }
+  main { margin-top: 5rem; }
+  h1, p { font: inherit; margin: 0; }
+  h1 { grid-column: 1; }
+  .copy { grid-column: 2 / -1; max-width: 34em; }
+  .copy > * + * { margin-top: 1.5rem; }
+  a { color: inherit; text-decoration: underline; text-decoration-thickness: 1.5px;
+    text-underline-offset: .22em; }
+  a:hover { text-decoration-color: transparent; }
+  a:focus-visible { outline: 1px solid #000; outline-offset: 2px; }
+  @media (max-width: 36.99rem) {
+    .grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .product { grid-column: 2; }
+    main { margin-top: 3rem; }
+    h1, .copy { grid-column: 1 / -1; }
+  }
+</style>
+</head>
+<body>
+  <header class="shell grid">
+    ${owner}
+    ${product}
+  </header>
+  <main class="shell grid">
+    <h1>Connection status</h1>
+    <div class="copy">
+      <p>${escapeHtml(body)}</p>
+      <p><a href="/">Return to ${escapeHtml(brand.productName)}</a></p>
+    </div>
+  </main>
+</body>
+</html>`,
+    { status, headers: { "Content-Type": "text/html; charset=utf-8" } },
+  );
+}
+
+/**
+ * Pay the storage read a real downstream-OAuth refusal pays, on the refusal
+ * paths that would otherwise pay nothing.
+ *
+ * Identical bodies do not hide a connector id if the clock still sorts them.
+ * `KvOAuthProvider.verifyState` reads `oauth:state` and its generation before
+ * it can reject a mismatched value, so a configured id costs two storage round
+ * trips on the ordinary path while an id naming nothing used to touch no I/O.
+ * That gap is an oracle: sample the two and a wordlist recovers the connector
+ * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
+ * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
+ *
+ * This is deliberately *not* a constant-time claim, and documentation/connectors.md says
+ * so in prose: a hit and a miss are not identical in a KV store, and a connector
+ * shipping its own `verifyState` may do more or less work. What it
+ * removes is the order-of-magnitude "no I/O versus a round trip" difference,
+ * which is the only part of the signal that makes enumeration cheap.
+ *
+ * A throwing read is swallowed: the refusal is the answer either way, and
+ * turning it into a 500 would hand back exactly the distinguishable response
+ * this whole path exists to deny.
+ */
+async function equalizeRefusalCost(
+  context: ConnectorContext,
+): Promise<void> {
+  try {
+    const generation = await context.storage.get("oauth:generation");
+    await context.storage.get(
+      oauthValueStorageKey("oauth:state", generation),
+    );
+  } catch {
+    // Deliberately ignored — see above.
+  }
+}
+
+export async function routeOAuthCallback(
+  context: RouteContext,
+): Promise<Response | null> {
+  const { path, url, baseUrl, opts } = context;
+  if (!path.startsWith("/oauth/callback/")) return null;
+  const error = url.searchParams.get("error");
+  if (error) return html(`Authorization denied: ${error}`, 400, opts.branding);
+  const code = url.searchParams.get("code");
+  if (!code) return html("Missing authorization code.", 400, opts.branding);
+  const id = path.slice("/oauth/callback/".length);
+  const connector = opts.registry.getConnector(id);
+  // Safe to build before we know the id names anything: `contextFor` is a pure
+  // constructor — a namespaced storage view over `conn:<id>:` and, only for a
+  // connector that declares one, a lazy credential accessor. It neither throws
+  // nor touches storage for an unknown id, which is what lets the refusals
+  // below borrow it to equalize their cost.
+  const connectorContext = opts.registry.contextFor(id, baseUrl);
+  const refused = () =>
+    html(
+      "Authorization could not be completed. Re-run authorization from " +
+        "connecta and try again.",
+      400,
+      opts.branding,
+    );
+  if (!connector || !connector.finishAuth) {
+    await equalizeRefusalCost(connectorContext);
+    return refused();
+  }
+  // CSRF / login-fixation guard: this route is intentionally public, so verify
+  // the `state` matches the flow connecta started BEFORE exchanging the code.
+  if (!connector.verifyState) {
+    await equalizeRefusalCost(connectorContext);
+    opts.logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: it implements finishAuth but no ` +
+        "verifyState, so connecta cannot establish that it started this flow. " +
+        "No authorization code was exchanged. Implement verifyState before " +
+        "trying again.",
+    );
+    return refused();
+  }
+  const state = url.searchParams.get("state");
+  let stateMatches: boolean;
+  try {
+    stateMatches = await connector.verifyState(state, connectorContext);
+  } catch (err) {
+    opts.logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: verifyState threw ` +
+        `${loggableValue(msg(err))}. No authorization code was exchanged. ` +
+        "Re-run authorization from connecta and check the verifier if it " +
+        "fails again.",
+    );
+    return refused();
+  }
+  if (!stateMatches) {
+    opts.logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: ` +
+        (state === null
+          ? "the state parameter was missing"
+          : "the state did not match the pending authorization flow") +
+        ". No authorization code was exchanged. Re-run authorization from " +
+        "connecta and try again.",
+    );
+    return refused();
+  }
+  try {
+    await connector.finishAuth(code, connectorContext);
+    await opts.registry.invalidateStored(id);
+    // Recovery, without a restart: the grant this connector was reported dead
+    // for has just been replaced, so drop the verdict rather than let a stale
+    // `auth_required` survive until the next scheduled check.
+    await opts.registry.clearCredentialHealth(id);
+    return html(
+      `Connected "${id}". You can close this window.`,
+      200,
+      opts.branding,
+    );
+  } catch (err) {
+    return html(`Authorization failed: ${msg(err)}`, 500, opts.branding);
+  }
+}

package/src/routes/shared.ts

@@ -0,0 +1,330 @@
+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 { resolveIdentityBinding, type Toolkit } from "../toolkits.js";
+import type {
+  ConnectaBranding,
+  Executor,
+  InboundAuth,
+  Logger,
+  ToolkitBinding,
+} 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;
+  /**
+   * Validated named scopes, selected per connection with `?toolkit=<name>` on
+   * `/mcp`. Omit (or leave empty) and every connection sees the full registry.
+   */
+  toolkits?: ReadonlyMap<string, Toolkit>;
+}
+
+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;
+  sweepCredentials(): void;
+}
+
+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 (a rejected toolkit name,
+ * 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 (also the toolkit response's echo
+ * limit), 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)" : "");
+}
+
+/** Length beyond which a rejected toolkit name is not echoed back. */
+export const MAX_ECHOED_TOOLKIT_NAME = MAX_LOGGED_VALUE_LENGTH;
+
+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;
+}
+
+/**
+ * Refusal for an identity whose toolkit binding cannot be trusted — a malformed
+ * declaration, or a malformed per-identity binding out of `authorize`. The
+ * caller is authenticated, so this is a 403, and it is deliberately opaque: the
+ * cause is an operator bug, and the operator reads it in the log, not the client.
+ */
+function unusableBinding(): Response {
+  return privateJson({ error: "forbidden" }, { status: 403 });
+}
+
+export async function authorize(
+  request: Request,
+  baseUrl: string,
+  auth: InboundAuth[],
+  logger: Logger,
+): Promise<
+  | {
+      ok: true;
+      actor: ActivityActor;
+      /** True only when the admitting provider can also authorize UI mutation. */
+      uiAdminEligible?: boolean;
+      /** The admitting identity's toolkit binding (documentation/toolkits.md). */
+      toolkitBinding?: ToolkitBinding;
+    }
+  | { 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;
+      // Re-validate both halves and cap the per-identity one by the provider's
+      // declaration (see resolveIdentityBinding). A binding that does not
+      // type-check at runtime refuses the request rather than evaporating:
+      // dropping it would hand the caller the full registry, which is the one
+      // outcome a binding exists to prevent.
+      const binding = resolveIdentityBinding(
+        provider.toolkitBinding,
+        result.toolkitBinding,
+      );
+      if (!binding.ok) {
+        logger.warn(
+          `[connecta] refused a request admitted by inbound auth provider ` +
+            `"${provider.kind}" with 403: ${binding.reason}. Until it is fixed ` +
+            "this provider cannot admit anyone, because connecta cannot tell " +
+            "which toolkits the identity may use.",
+        );
+        return { ok: false, response: unusableBinding() };
+      }
+      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 }
+          : {}),
+        ...(binding.binding ? { toolkitBinding: binding.binding } : {}),
+      };
+    }
+    lastResponse = result.response;
+  }
+  return {
+    ok: false,
+    response:
+      lastResponse ??
+      new Response(JSON.stringify({ error: "unauthorized" }), {
+        status: 401,
+        headers: {
+          "Content-Type": "application/json",
+          "WWW-Authenticate": "Bearer",
+        },
+      }),
+  };
+}
+
+/**
+ * True when this identity is confined to one or more toolkits — bound, without
+ * `unscoped`. Such a credential belongs to a team's agent, not to the operator
+ * running the deployment, so the deployment-wide operator surfaces (`/ui/data`,
+ * `/ui/activity`, the credential API) refuse it: their payloads describe every
+ * connector in the org, which is exactly what the binding exists to withhold.
+ */
+export function isToolkitRestricted(
+  binding: ToolkitBinding | undefined,
+): boolean {
+  return Boolean(binding && !binding.unscoped);
+}
+
+/** The refusal the deployment-wide operator surfaces give a bound identity. */
+export function restrictedOperatorSurface(): Response {
+  return privateJson(
+    {
+      error:
+        "this credential is bound to a toolkit and may not read " +
+        "deployment-wide operator data",
+    },
+    { status: 403 },
+  );
+}
+
+export async function authorizeUiAdmin(
+  request: Request,
+  baseUrl: string,
+  auth: InboundAuth[],
+  logger: Logger,
+  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, because the
+  // documented per-team pattern is several `clerkAuth(...)`s that differ only in
+  // `gate` and `toolkits` (documentation/toolkits.md). Stopping at the first would make
+  // admission depend on config order: the team-bound provider listed first
+  // would refuse the operator outright, and a refusal here — a failed gate, a
+  // missing user, a toolkit-bound identity — is exactly the case where 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;
+    }
+    const binding = resolveIdentityBinding(
+      provider.toolkitBinding,
+      result.toolkitBinding,
+    );
+    if (!binding.ok) {
+      logger.warn(
+        `[connecta] refused an operator-mutation request admitted by inbound auth ` +
+          `provider "${provider.kind}" with 403: ${binding.reason}.`,
+      );
+      lastResponse = unusableBinding();
+      continue;
+    }
+    // A toolkit-bound identity is a team's credential, not a vault admin key:
+    // credentials are deployment-wide, so writing one reaches every toolkit.
+    if (isToolkitRestricted(binding.binding)) {
+      lastResponse = restrictedOperatorSurface();
+      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,
+  });
+}