Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

24.6 KB
Raw Blame
import { requireAdmin } from "../../auth/guards";
import { reasonWithoutStatement } from "../../db/query-failure";
import { brokerSentence, schemeKind } from "../broker";
import { CATALOGUE } from "../catalogue";
import { vendorSentence } from "../composio";
import { redirectUriFor } from "../oauth";
import { asAccountMode } from "../shared-accounts";
import { asSharedUseApproval, type SharedUseApproval } from "../shared-use";
import {
  CatalogueEntryUnknownError,
  CustomServerRefusedError,
  deploymentFaultSentence,
  isDeploymentFault,
} from "../store";
import { brokerRefusal, type PluginRouteContext } from "./context";

/** Adding, removing and refreshing MCP servers, and an app's account mode. */
export function mountServerRoutes({
  routes,
  store,
  requireUser,
  connect,
  composio,
  shared,
  activeProvider,
  activeVendor,
  appOfUrl,
  actorEmail,
  skillActor,
}: PluginRouteContext) {
  /** Everything the Plugins page draws: the catalogue, what is added, and the skills. */
  routes.get("/", requireUser, async (context) =>
    context.json({
      catalogue: CATALOGUE.map((entry) => ({
        key: entry.key,
        title: entry.title,
        vendor: entry.vendor,
        summary: entry.summary,
        docsUrl: entry.docsUrl,
        /*
         * The kind, not the whole thing. The page needs to know what to ask an administrator for;
         * it has no use for the vendor's OAuth addresses, and a URL this deployment sends an
         * authorization code to is not improved by also existing in every browser that opens the
         * Plugins page.
         */
        auth: entry.auth.kind,
        perInstance: entry.host === null,
      })),
      /*
       * Whether a Bot with no credential of its own can still call a tool back.
       *
       * The grant switch decides whether a tool is offered to a model; this decides whether any
       * call it makes can be authenticated at all. They are different questions and the screen used
       * to answer only the first, so a grant could read "May call this tool" on a deployment where
       * every call was refused before it reached the boundary.
       */
      botsMayCallBack: connect?.botsMayCallBack === true,
      /*
       * Whether this deployment has a broker at all, so the page knows whether brokered apps are
       * on offer.
       *
       * A boolean about configuration, never the key. The API key that builds the broker is a
       * deployment credential and the Plugins page is reachable by any signed-in person; what the
       * screen needs is whether to draw the app directory, which is a yes or a no.
       */
      composioConfigured: Boolean(composio),
      /*
       * Whether this deployment's broker authorizes ONE ACTION AT A TIME, as a declared capability.
       *
       * A PRESENCE TEST ON A VALUE THE BROKER DECLARED, computed from the same expression the two
       * routes that run that flow gate on — `/servers/:id/authorize` and the `/arcade/verify`
       * return leg both read `composio.broker.authorizations`. The screen that draws the per-action
       * grant list used to gate on `provider === "arcade"` instead, so the screen and the routes
       * keyed on different facts: a broker named arcade reached with `authorizations` null would
       * have drawn the list and 503'd every Authorize press. See {@link
       * ConnectedAppBroker.authorizations} and `store.ts`'s gate comment, which records a defect of
       * exactly that shape.
       *
       * A capability, never a name: what the screen asks is what the broker can DO, and two
       * providers are free to share an answer. `provider` beside it stays a NAME and answers a
       * different question — which vendor to put in copy.
       *
       * False on Composio, whose auth config fixes one state for a whole toolkit, so every Composio
       * render is unchanged.
       */
      authorizesPerAction: Boolean(composio?.broker.authorizations),
      /*
       * WHICH vendor brokers this deployment's apps, as a name.
       *
       * Handed in with the broker, never read off it: the broker declares what it can do, not who
       * it is, and a name sniffed from it would be the comparison the store argues against.
       *
       * A screen that FILTERS by brokered-ness needs no provider name. One provider holds rows at a
       * time, so a predicate over a row's provenance is enough. A screen that NAMES a vendor
       * ("Browse Composio", the `/admin/plugins/composio` route, the key's setting, "Reached
       * through Composio") cannot derive that name from a row, and this is the only thing that
       * answers it. It is separate from `composioConfigured`, which asks whether the directory can
       * be browsed at all.
       *
       * A NAME, never a key and never a capability. The Plugins page is reachable by any signed-in
       * person, so nothing about the vendor key (its presence, shape or anything derived from it)
       * travels with this. Composio when no broker is configured, so that deployment is unchanged —
       * read from {@link activeProvider}, which is also what the brokered reads below parse with, so
       * the name this page shows and the parser those routes use cannot come apart.
       */
      provider: activeProvider,
      servers: await store.listServers(),
      // Scoped: the deployment's skills plus this person's own. An administrator sees them all.
      skills: await store.listSkills(skillActor(context)),
      /*
       * What an administrator has to register with the vendor, character for character.
       *
       * Served rather than assembled in the browser, so what is displayed is exactly what the
       * callback will present. A mismatch here fails at the vendor with a message that does not name
       * us, which is a bad afternoon for whoever is setting it up.
       *
       * Null means this deployment has no public URL, so it cannot complete a consent flow at all.
       */
      redirectUri: connect?.publicUrl
        ? redirectUriFor(connect.publicUrl)
        : null,
    }),
  );

  /** Add a curated server. The URL comes from the catalogue, never from the request. */
  routes.post("/servers", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const body = (await context.req.json().catch(() => null)) as {
      key?: unknown;
      instanceHost?: unknown;
      credentialId?: unknown;
    } | null;
    const key = typeof body?.key === "string" ? body.key.trim() : "";
    if (!key) {
      return context.json({ error: "A catalogue key is required." }, 400);
    }
    // Optional fields travel to `input.credentialId?.trim()` in the store, where a number or
    // object throws a TypeError that escapes as a 500. A string that is only whitespace would
    // silently become `undefined` there, so it is refused here instead of being coerced.
    if (
      body?.instanceHost !== undefined &&
      (typeof body.instanceHost !== "string" || !body.instanceHost.trim())
    ) {
      return context.json(
        { error: "An instance host must be a non-empty string." },
        400,
      );
    }
    if (
      body?.credentialId !== undefined &&
      (typeof body.credentialId !== "string" || !body.credentialId.trim())
    ) {
      return context.json(
        { error: "A credential id must be a non-empty string." },
        400,
      );
    }

    try {
      const server = await store.addServer({
        key,
        instanceHost:
          typeof body?.instanceHost === "string"
            ? body.instanceHost.trim()
            : undefined,
        credentialId:
          typeof body?.credentialId === "string"
            ? body.credentialId.trim()
            : undefined,
        by: actorEmail(context),
      });
      return context.json({ server });
    } catch (error) {
      // A refused credential is the administrator's mistake to correct, so it comes back as a
      // refusal with its reason rather than as a 500 the way an unmapped throw would.
      if (
        error instanceof CatalogueEntryUnknownError ||
        error instanceof CustomServerRefusedError
      ) {
        return context.json({ error: error.message }, 400);
      }
      /*
       * The same mapping the refresh route makes, on the routes that call the same method.
       *
       * CRITERION. Every admin route whose store call can reach a fault on the
       * `isDeploymentFault` shelf answers with the sentence rather than leaving it to the default
       * handler.
       *
       * REASON. Adding a server REFRESHES it before answering — deliberately, so a bad credential
       * is reported now rather than the first time a Bot uses it — so every fault `refreshTools`
       * raises arrives here too, and a vendor listing one action twice or a query of ours failing
       * is exactly that. Mapped on one route and not on its siblings, the same fault is a named
       * sentence or "That did not work" depending on which button was pressed, which is the shape
       * that made this class hard to see the first time.
       */
      if (isDeploymentFault(error)) {
        return context.json({ error: deploymentFaultSentence(error) }, 409);
      }
      throw error;
    }
  });

  /**
   * Add a server by URL.
   *
   * Its own endpoint rather than a flag on the one above, so that "an administrator pointed this
   * deployment at an address of their own" is a distinct act in the code, in the audit trail and in
   * anything that reads either.
   */
  routes.post("/servers/custom", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const body = (await context.req.json().catch(() => null)) as {
      id?: unknown;
      title?: unknown;
      url?: unknown;
      credentialId?: unknown;
    } | null;
    if (
      typeof body?.id !== "string" ||
      !body.id.trim() ||
      typeof body?.title !== "string" ||
      !body.title.trim() ||
      typeof body?.url !== "string" ||
      !body.url.trim()
    ) {
      return context.json(
        { error: "A name, a title and a URL are required." },
        400,
      );
    }
    // `addCustomServer` dereferences `input.credentialId?.trim()`, so a number or object here
    // throws a TypeError that escapes as a 500 instead of a 400.
    if (
      body.credentialId !== undefined &&
      (typeof body.credentialId !== "string" || !body.credentialId.trim())
    ) {
      return context.json(
        { error: "A credential id must be a non-empty string." },
        400,
      );
    }

    try {
      const server = await store.addCustomServer({
        id: body.id.trim(),
        title: body.title.trim(),
        url: body.url.trim(),
        credentialId:
          typeof body.credentialId === "string"
            ? body.credentialId.trim()
            : undefined,
        by: actorEmail(context),
      });
      return context.json({ server });
    } catch (error) {
      if (
        error instanceof CustomServerRefusedError ||
        error instanceof CatalogueEntryUnknownError
      ) {
        return context.json({ error: error.message }, 400);
      }
      // As on the curated add above, and for the same reason: this path refreshes before it
      // answers.
      if (isDeploymentFault(error)) {
        return context.json({ error: deploymentFaultSentence(error) }, 409);
      }
      throw error;
    }
  });

  /**
   * Register this deployment's OAuth client for a server reached as the person asking.
   *
   * Its own endpoint rather than a field on `POST /servers`, because it is a separate act with a
   * separate lifetime: a client is rotated without the server being re-added, and re-adding a server
   * should not require re-typing a client. An administrator's, like everything else that decides what
   * a Bot can reach.
   */
  routes.post("/servers/:id/oauth-client", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const body = (await context.req.json().catch(() => null)) as {
      clientId?: unknown;
      clientSecret?: unknown;
    } | null;
    /*
     * `typeof` before `.trim()`, as `POST /servers` and `/servers/custom` do: the body is JSON, so
     * `{"clientId": 12345}` or a secret of `{}` used to reach `.trim()` here, outside the try, and
     * answer 500 for what is a person's malformed request.
     */
    if (
      typeof body?.clientId !== "string" ||
      typeof body.clientSecret !== "string" ||
      !body.clientId.trim() ||
      !body.clientSecret.trim()
    ) {
      return context.json(
        { error: "A client id and a client secret are both required." },
        400,
      );
    }

    try {
      await store.registerOAuthClient({
        serverId: context.req.param("id"),
        client: {
          clientId: body.clientId.trim(),
          clientSecret: body.clientSecret.trim(),
        },
        by: actorEmail(context),
      });
      return context.json({ ok: true });
    } catch (error) {
      if (
        error instanceof CatalogueEntryUnknownError ||
        error instanceof CustomServerRefusedError
      ) {
        return context.json({ error: error.message }, 400);
      }
      // Registering a client resolves the row first, so a row this deployment cannot say how to
      // reach refuses here as well.
      if (isDeploymentFault(error)) {
        return context.json({ error: deploymentFaultSentence(error) }, 409);
      }
      throw error;
    }
  });

  /**
   * Take a server away, and answer for a removal that did not finish.
   *
   * CRITERION. The same one the add routes above state, on the route that needed it most: every
   * refusal `removeServer` can raise comes back as a body naming what was left standing, rather
   * than reaching the framework's default handler.
   *
   * REASON. THIS MAPPED NOTHING AT ALL, and what it calls is the loudest method in the store.
   * `removeServer` withdraws every person's brokered account at Composio and drops this
   * deployment's auth configs BEFORE it deletes the row, deliberately — the argument is made
   * there, and it ends "WHICH MAKES THE FAILURE LOUD. Nothing is caught around the revokes". The
   * refusals it raises are written for exactly this reader: how many of this deployment's configs
   * went and how many are still standing, or a config row Composio described with no id and no
   * name. All of it reached Hono's default handler, which answers a bodyless 500, so an
   * administrator who had just half-withdrawn an app from everybody was told nothing whatever —
   * on the one act in this file whose half-done state somebody has to go and finish by hand.
   * `PluginInvariantError` out of `accessFor` arrived the same way, and it is the one that names
   * which of this deployment's own rows is wrong.
   *
   * THE SHELF FIRST, THEN THE BROKER, which is the order the enable route below pins and for its
   * reason: a contradiction between two of this deployment's columns is not Composio being down,
   * and answering it through the broker mapping would send an operator to check a key that is
   * fine. This route is `requireAdmin`, which is what makes showing that sentence here safe.
   *
   * AND THE GENERIC SENTENCE BLAMES NEITHER SIDE. Half of what this call path does is local — the
   * vault revokes, the trail writes, the deletes — and half of it is the broker, so a failure that
   * neither `brokerSentence` nor `vendorSentence` put words to is one where which half failed is
   * precisely what nobody said. What a reader needs is the button, and the store's own order is
   * what makes pressing it safe: nothing here is deleted until the withdrawals have been asked
   * for, so a second press asks only for what is left.
   */
  routes.delete("/servers/:id", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const serverId = context.req.param("id");
    /*
     * READ BEFORE THE ROW GOES. The ask-before-write rule a Shared app was given lives in the
     * approval policy, not on the row, so nothing cascades it away; asked afterwards, the mode is
     * gone with the row and the rule would outlive the account it guarded.
     */
    const wasShared =
      shared !== undefined &&
      (await store.serverAddress(serverId))?.accountMode === "shared";
    try {
      await store.removeServer(serverId, actorEmail(context));
    } catch (error) {
      if (isDeploymentFault(error)) {
        return context.json({ error: deploymentFaultSentence(error) }, 409);
      }
      /*
       * WHAT THE MAPPING COST, PUT BACK, exactly as the enable route below does it. An unhandled
       * throw was a bad answer and a good log: the administrator got nothing, but the stack was
       * printed where an operator could find it. Catching everything fixes the answer and would
       * silence that, and the failure that needs the log most is the one left here — neither a
       * refusal this deployment authored, which `brokerSentence` names, nor a sentence Composio
       * wrote, which `vendorSentence` reaches for. The row, because it is the app an operator is
       * about to be asked about, and the error read through {@link reasonWithoutStatement}, never
       * spread, logged as an object or reached into.
       *
       * AND THAT DOOR RATHER THAN `String(error)`, BECAUSE THE TWO SENTENCE TESTS ARE NOT A GUARD
       * AGAINST THIS. A `DrizzleQueryError` has neither a broker sentence nor a vendor one, so it
       * lands in exactly this branch — which is what removing a server raises when a delete fails
       * mid-way — and its own message is the statement plus every value bound to it.
       */
      if (brokerSentence(error) === null && vendorSentence(error) === null) {
        console.error(
          JSON.stringify({
            type: "mcp-server-not-removed",
            server: serverId,
            note: `Removing a server failed for a reason neither this deployment nor ${activeVendor} put a sentence to. The administrator was answered 502 with the generic sentence, and the server row is still there.`,
            error: reasonWithoutStatement(error),
          }),
        );
      }

      const refusal = brokerRefusal(
        error,
        `Removing this app did not finish, and neither this deployment nor ${activeVendor} said why, so the app is still here rather than gone with grants of its own left live at the vendor. Press Remove again: every account is withdrawn at ${activeVendor} before anything here is deleted, so repeating it is safe and asks only for what is left. Check this deployment's ${activeVendor} key if it persists.`,
      );
      return context.json({ error: refusal.error }, refusal.status);
    }
    /*
     * THE SAME SHAPE AS THE MINT'S RECORD-AFTER-THE-FACT BELOW, AND GUARDED FOR THE SAME REASON.
     * `removeServer` has already returned, which means every account was withdrawn AT THE VENDOR
     * and every row here is gone — none of it undoable, and none of it repeatable either: a second
     * Remove finds no app. Unhandled, a fault tidying up the one leftover ask-before-write rule
     * answered that completed removal with a bodyless 500, so the administrator was told the
     * removal failed and had no press left to make.
     *
     * SO THE ANSWER STAYS `ok`, BECAUSE THE REMOVAL REALLY DID HAPPEN, and the leftover is named on
     * the console instead: a revoked-rule row that outlives the app it guarded, which an
     * administrator can retire from the rules screen and which grants nobody anything meanwhile.
     */
    if (wasShared) {
      try {
        await shared?.modes.forgetRule(serverId, context.var.actor.id);
      } catch (error) {
        console.error(
          JSON.stringify({
            type: "shared-rule-not-forgotten",
            server: serverId,
            note: "An app was removed, at the vendor and here, and its ask-before-write rule could not be retired afterwards. The administrator was answered ok, because the removal is done and cannot be repeated; the rule is still standing.",
            error: reasonWithoutStatement(error),
          }),
        );
      }
    }
    return context.json({ ok: true });
  });

  /**
   * Personal ⇄ Shared. Without `confirm`, a preview of what the switch would end and approve; with
   * it, the switch itself, which changes nothing unless every old account was ended at the vendor.
   */
  routes.put("/servers/:id/account-mode", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;
    if (!shared) {
      return context.json(
        { error: "Shared accounts are not available on this deployment." },
        503,
      );
    }
    const body = (await context.req.json().catch(() => null)) as {
      mode?: unknown;
      confirm?: unknown;
      approvals?: unknown;
    } | null;
    const mode = asAccountMode(body?.mode);
    if (!mode)
      return context.json({ error: "Choose personal or shared." }, 400);
    const serverId = context.req.param("id");
    const row = await store.serverAddress(serverId);
    if (!row || !appOfUrl(row.url)) {
      return context.json(
        { error: "That app is not reached through a broker." },
        400,
      );
    }
    if (schemeKind(row.authScheme) === "none") {
      return context.json(
        {
          error: `${row.title} needs no account, so there is nothing to share.`,
        },
        400,
      );
    }
    const approvals: Record<string, SharedUseApproval> = {};
    if (body?.approvals && typeof body.approvals === "object") {
      for (const [botId, value] of Object.entries(
        body.approvals as Record<string, unknown>,
      )) {
        const approval = asSharedUseApproval(value);
        if (!approval) {
          return context.json(
            {
              error: `The approval for ${botId} is not one this deployment can read.`,
            },
            400,
          );
        }
        approvals[botId] = approval;
      }
    }
    try {
      const result = await shared.modes.switchMode({
        serverId,
        mode,
        by: context.var.actor.id,
        confirm: body?.confirm === true,
        approvals,
      });
      if ("failures" in result) {
        return context.json(
          {
            ...result,
            error: result.failures.map((failure) => failure.error).join(" "),
          },
          502,
        );
      }
      return context.json(result);
    } catch (error) {
      const refusal = brokerRefusal(
        error,
        "The switch did not finish, and nothing was changed.",
      );
      return context.json({ error: refusal.error }, refusal.status);
    }
  });

  /** Ask a server what it offers now. Reported rather than thrown, so the page can say what broke. */
  routes.post("/servers/:id/refresh", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    try {
      const result = await store.refreshTools(
        context.req.param("id"),
        context.var.actor.id,
      );
      const servers = await store.listServers();
      return context.json({
        tools: result.tools,
        server: servers.find((server) => server.id === context.req.param("id")),
      });
    } catch (error) {
      if (error instanceof CatalogueEntryUnknownError) {
        return context.json({ error: error.message }, 404);
      }
      /*
       * The one audience the sentence was written for, and the only route that may show it.
       *
       * CRITERION. A contradiction between this deployment's own columns comes back to an
       * administrator as itself: a body, naming the row and what to do about it.
       *
       * REASON. Unmapped, it reached the framework's default handler — a 500 with no JSON at all,
       * which the admin page reads as "That did not work", the fallback it uses when a response
       * carries no message. So the one refusal that names exactly which row is wrong and how to
       * correct it was the one an operator could not see, while the same sentence WAS reaching a
       * model on the tool-call path. This route is `requireAdmin`, which is what makes showing it
       * here safe and showing it anywhere else not.
       *
       * 409 rather than 500: nothing broke, and nothing about the request was malformed. Two rows
       * of ours disagree, and the request cannot be answered until one of them changes — which is
       * what the sentence tells the reader to go and do.
       */
      if (isDeploymentFault(error)) {
        // `deploymentFaultSentence` rather than `error.message`: the shelf now includes a query
        // this database refused, and that one's message is the statement and every value bound to
        // it. An administrator is entitled to the reason, not to the dump.
        return context.json({ error: deploymentFaultSentence(error) }, 409);
      }
      throw error;
    }
  });
}