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.

23.5 KB
Raw Blame
import { PERSON_INITIATOR } from "../../audit";
import type { AppVariables } from "../../auth/guards";
import { approveOwnersSharedUse, ownerGrantRefusal } from "../owner-grants";
import {
  asSharedUseApproval,
  exposureOf,
  type SharedUseApproval,
} from "../shared-use";
import {
  CatalogueEntryUnknownError,
  isDeploymentFault,
  type PluginKind,
  PluginRefusedError,
} from "../store";
import type { PluginRouteContext } from "./context";

/**
 * What a grant of one MCP tool must record beside it: the approval for who may use a Shared app's
 * one account through this Bot.
 *
 * Without an approval the gate refuses every call the grant just allowed, so a grant with none sent
 * approves the Bot's exposure as it stands now — unless an approval is already recorded, which is
 * an administrator's earlier decision and not this grant's to widen (one an owner's grant set is not
 * that, and is replaced). "Is Shared" is the app's
 * answer (its answering row), never the granted row's own column. Null `approval` is nothing to
 * record; `unreadable` is an approval sent that this deployment cannot read, which the caller
 * refuses.
 *
 * A FUNCTION RATHER THAN LINES IN THE ROUTE because approving an access request grants through the
 * same rule, and a Shared app granted from the request inbox must land with the same approval it
 * would have had from the grant switch.
 */
export async function sharedGrantApproval(
  { store, shared }: Pick<PluginRouteContext, "store" | "shared">,
  ref: string,
  agentId: string,
  sent: unknown,
): Promise<
  { appId: string; approval: SharedUseApproval | null } | "unreadable"
> {
  if (!shared) return { appId: "", approval: null };
  const [serverId] = ref.split("/");
  const appId = await shared.use.appIdOf(serverId ?? "");
  if ((await store.serverAddress(appId))?.accountMode !== "shared")
    return { appId, approval: null };
  if (sent !== undefined) {
    const approval = asSharedUseApproval(sent);
    return approval ? { appId, approval } : "unreadable";
  }
  /*
   * An audience an owner's grant set is not an administrator's decision, so an administrator
   * granting over it approves the Bot's exposure now, which makes the audience theirs.
   */
  if ((await shared.use.approvalSource(agentId, appId)) === "admin")
    return { appId, approval: null };
  return {
    appId,
    approval: exposureOf(await shared.use.botFacts(agentId)),
  };
}

/** Granting and revoking a server, skill or Bot, and a Bot's tool calls back. */
export function mountGrantRoutes({
  routes,
  store,
  requireUser,
  canUseBot,
  shared,
  composio,
  actorEmail,
  skillActor,
}: PluginRouteContext) {
  /**
   * Grant and revoke, for both kinds, through one pair of endpoints.
   *
   * The store keeps one grant table because the question is the same either way; the API says the
   * same thing, so a reader is never left wondering whether skills are governed differently.
   */

  /**
   * The kinds of grant this API will act on.
   *
   * CHECKED AT RUNTIME, not only in the types. `kind` arrives in a JSON body, so a type annotation
   * on it is a comment: before this, anything at all could be written into the grant table through
   * the ordinary endpoint, and one kind that was never meant to be settable this way already could.
   */
  const GRANT_KINDS = new Set<PluginKind>(["mcp", "skill", "bot"]);
  const asGrantKind = (value: unknown): PluginKind | null =>
    typeof value === "string" && GRANT_KINDS.has(value as PluginKind)
      ? (value as PluginKind)
      : null;

  /**
   * May this Bot's owner, who is not an administrator, give it this one action of an app?
   *
   * The Bot is asked about first, so somebody who does not own it learns nothing about the app from
   * the answer. The ref has to name a row that is the app, not merely a word an app answers to.
   */
  async function ownerMcpRefusal(
    context: { var: AppVariables },
    ref: string,
    agentId: string,
  ): Promise<string | null> {
    const actorId = context.var.actor.id;
    if (
      !(await store.agentIsRegistered(agentId)) ||
      (await store.agentOwner(agentId)) !== actorId
    )
      return "Only an admin can choose which Bots use a tool.";
    const [serverId] = ref.split("/");
    const inspected = serverId
      ? await store.inspectApp({
          app: serverId,
          agentId,
          userId: actorId,
          composioConfigured: Boolean(composio),
        })
      : null;
    if (!inspected?.rowIds.includes(serverId ?? ""))
      return `${serverId} hasn't been added yet. Only an admin can add it.`;
    const refusal = await ownerGrantRefusal(store, actorId, agentId, inspected);
    if (refusal) return refusal;
    /*
     * AN ACTION THE APP ADVERTISES NOW, NOT ANY WORD AFTER THE SLASH. An administrator may grant a
     * tool a server has stopped listing, to restore it (see `enablementRefusal`). An owner may not:
     * a ref naming nothing would sit there until the vendor shipped an action by that name, and the
     * Bot would then hold it with nobody having chosen it — and a bare server ref would mark the app
     * given without giving it a single action.
     */
    if (
      !(await store.appTools(serverId ?? "")).some((tool) => tool.ref === ref)
    )
      return `${inspected.access.displayName} doesn't have that action.`;
    return null;
  }

  /**
   * May this person put this on that Bot?
   *
   * MCP is an administrator's, except one of the owner's own apps on their own Bot (see
   * {@link ownerMcpRefusal}): it reaches another company's system with a stored credential.
   * A skill is an instruction, so somebody may put their own skill on a Bot they own, and neither
   * half alone is enough. Both are checked here rather than in the store, because this is the only
   * place that knows who is asking.
   */
  async function enablementRefusal(
    context: { var: AppVariables },
    kind: PluginKind,
    ref: string,
    agentId: string,
    /**
     * Which way this is going, because they are not symmetric.
     *
     * TAKING SOMETHING AWAY IS ALWAYS ALLOWED. The checks below decide whether a grant should exist,
     * and applying them to a revoke turns every one of them into a trap: a `bot` grant made before
     * the grantee moved to its own endpoint — or before this check existed — could never be removed,
     * because the reason it is wrong is the same reason the revoke was refused. An administrator
     * looking at a dead row in the UI would have had no way to delete it.
     */
    intent: "grant" | "revoke",
  ): Promise<string | null> {
    const actor = skillActor(context);

    if (kind === "mcp") {
      if (!actor.isAdmin) {
        /*
         * A BOT'S OWNER MAY GIVE IT ONE OF THEIR OWN APPS, and nothing else changes for anybody who
         * is not an administrator. The owner rule — their Bot, an app an administrator switched on
         * and opened to owners, the `ownerApps` capability — is {@link ownerGrantRefusal}'s, the
         * same one the card's one press asks. The grant this allows is written `granted_as = owner`
         * by the route below, which is what keeps it on the asker's own account.
         *
         * TAKING AWAY IS NOT RELAXED HERE. An owner takes back what they gave through
         * `DELETE /for/:agentId/apps/:app/give`, which removes only the owner's own grants; this
         * route's revoke would remove an administrator's as readily, so it stays theirs.
         */
        if (intent === "revoke")
          return "Only an admin can choose which Bots use a tool.";
        return ownerMcpRefusal(context, ref, agentId);
      }
      // Taking something away is always allowed: see the note on `intent`. It matters more here
      // than anywhere else, because the rows this check exists to prevent are the same shape as the
      // rows #572's migration had to delete, and an administrator has to be able to remove one by
      // hand rather than wait for a migration.
      if (intent === "revoke") return null;

      /*
       * A grant that could never do anything is refused rather than stored, which is the rule the
       * `bot` branch below already states and this one did not follow.
       *
       * Nothing checked that the app existed. `store.grant` is a bare upsert, so a ref naming an
       * app this deployment has not added was stored and then invisible: the surface that reports a
       * grant nothing advertises is built per server row, and there was no row. #572 fixed the way
       * these rows were MADE — a removal used to leave its grants behind — and added the migration
       * that deleted the ones already there. This is the other door into the same room. Add the app
       * afterwards and the id is the same, the action names are the same, and every one of those
       * grants resolves, with nobody having granted anything and no row in the trail saying so.
       *
       * THE SERVER HALF ONLY. A grant naming a tool the server has stopped advertising is a
       * supported state, held and not offered, because what a vendor lists today is not what
       * somebody decided yesterday — checking the tool here would refuse a re-grant of exactly the
       * tool an administrator is trying to restore. A grant naming no app at all is not that state.
       */
      const [serverId] = ref.split("/");
      if (!(await store.serverExists(serverId ?? ""))) {
        return `${serverId} hasn't been added yet. Add it first, then give its tools to a Bot.`;
      }
      /*
       * The Bot has to exist as well, which the `bot` branch below already says in the same words.
       * `plugin_grants.agent_id` is a foreign key, so a grant naming a Bot nobody has reached the
       * insert and failed there, and a person's mistyped Bot id answered 500 with no body where
       * every other refusal on this route is a 403 with a sentence.
       */
      if (!(await store.agentIsRegistered(agentId)))
        return "There is no such Bot.";
      return null;
    }

    if (kind === "bot") {
      /*
       * THE ROLE IS CHECKED BEFORE ANYTHING IS LOOKED UP, and that ordering is the point.
       *
       * One Bot reaching another lets it spend that Bot's model calls, wake its computer and reach
       * whatever it may reach, so it is an administrator's decision rather than something somebody
       * attaches to a coworker they own. But this route only requires a signed-in user, so every
       * refusal below is readable by anybody: checking whether the Bot exists, and whether it runs
       * here, before this line handed out three distinguishable answers and turned a 403 into an
       * oracle for other people's private Bots. `handoff.ts` in this same feature collapses exactly
       * this, deliberately, and this had it backwards.
       */
      if (!actor.isAdmin) {
        return "Only an admin can choose which Bots hand work to another Bot.";
      }
      // Taking something away is always allowed: see the note on `intent`.
      if (intent === "revoke") return null;

      /*
       * A grant that could never do anything is refused rather than stored, from both ends.
       *
       * The GRANTEE must exist. Remote Bots execute through the same signed callback and handoff
       * desk as built-in Bots, so where their model loop runs does not change the grant.
       *
       * The TARGET only has to exist. Being handed work is not the same as being able to hand it on,
       * so a target at its own endpoint is perfectly ordinary — but `ref` is bare text with no
       * foreign key, so a typo stored happily and every hop then refused as not-granted.
       */
      /*
       * A Bot cannot be granted itself. The desk refuses a self-hop outright — "a Bot cannot hand
       * work to itself" — so the row is dead the moment it is written, and reads as configured.
       */
      if (ref === agentId) {
        return "A Bot cannot be granted itself to hand work to.";
      }
      if (!(await store.agentIsRegistered(agentId)))
        return "There is no such Bot.";
      if (!(await store.agentIsRegistered(ref))) {
        return `There is no Bot called ${ref} to hand work to.`;
      }
      return null;
    }

    if (actor.isAdmin) {
      // Taking something away is always allowed: see the note on `intent`.
      if (intent === "revoke") return null;
      /*
       * A grant naming no skill is refused for an administrator too, as the `mcp` branch refuses a
       * grant naming no app. `store.grant` is a bare upsert and a Bot's skills are read by slug
       * alone, so the row sat there granting nothing until somebody wrote a skill under that name,
       * and then that skill was on this Bot with nobody having put it there. On a Bot the
       * deployment shares, that is one person's instructions answering everybody:
       * `skill-uninstall-grants.integration.test.ts` guards the same room from the uninstall side.
       */
      if ((await store.skillOwner(ref)) === undefined) {
        return `There is no skill called ${ref}.`;
      }
      // And the Bot, for the reason the `mcp` branch gives: an administrator's grant naming one
      // nobody has failed on the foreign key. Everybody else is asked below, through `agentOwner`.
      if (!(await store.agentIsRegistered(agentId)))
        return "There is no such Bot.";
      return null;
    }

    const owner = await store.skillOwner(ref);
    if (owner === undefined) return `There is no skill called ${ref}.`;
    if (owner !== actor.id) {
      return owner === null
        ? `${ref} belongs to everyone. Only an admin can choose which Bots use it.`
        : `${ref} is somebody else's skill.`;
    }

    const botOwner = await store.agentOwner(agentId);
    if (botOwner === undefined) return "There is no such Bot.";
    if (botOwner !== actor.id) {
      // Including the shared Bots this deployment publishes, which have no owner at all: a skill
      // one person wrote would otherwise change how a Bot answers everybody.
      return "You can only put your own skills on Bots you own.";
    }
    return null;
  }

  routes.post("/grants", requireUser, async (context) => {
    const body = (await context.req.json().catch(() => null)) as {
      kind?: unknown;
      ref?: string;
      agentId?: string;
      approval?: unknown;
    } | null;
    const kind = asGrantKind(body?.kind);
    /*
     * The body is JSON, so the annotation is a wish: `{"ref":123,"agentId":[]}` passes a
     * truthiness check and then reaches the store, where Drizzle compares a text column against
     * a number and the request answers 500. A ref and a Bot id are non-empty strings here.
     */
    if (
      !kind ||
      typeof body?.ref !== "string" ||
      !body.ref.trim() ||
      typeof body.agentId !== "string" ||
      !body.agentId.trim()
    ) {
      return context.json(
        { error: "A kind, a ref and a Bot are required." },
        400,
      );
    }
    /*
     * Trimmed before it is checked and before it is stored, the way the DELETE twin below already
     * does. Without this a padded ref refuses with the padding quoted back (`" app" is not an app`),
     * and a grant that did pass would be stored under a ref no revoke could match.
     */
    const grantRef = body.ref.trim();
    const grantAgentId = body.agentId.trim();
    const refusal = await enablementRefusal(
      context,
      kind,
      grantRef,
      grantAgentId,
      "grant",
    );
    if (refusal) return context.json({ error: refusal }, 403);

    /*
     * A SHARED APP'S ACTION IS GRANTED WITH WHO MAY USE IT, in the one request. See
     * {@link sharedGrantApproval} for what is recorded when none is sent.
     */
    /*
     * An owner's grant sends no approval of its own. Where the app is Shared and an administrator
     * lets owners decide, the grant sets the audience itself, below; see `approveOwnersSharedUse`.
     */
    const asOwner = kind === "mcp" && !skillActor(context).isAdmin;
    const decided =
      kind === "mcp" && !asOwner
        ? await sharedGrantApproval(
            { store, shared },
            grantRef,
            grantAgentId,
            body?.approval,
          )
        : null;
    if (decided === "unreadable") {
      return context.json(
        { error: "That approval is not one this deployment can read." },
        400,
      );
    }
    await store.grant(
      kind,
      grantRef,
      grantAgentId,
      actorEmail(context),
      asOwner ? "owner" : "admin",
    );
    if (decided?.approval && shared) {
      await shared.use.setApproval({
        botId: grantAgentId,
        serverId: decided.appId,
        approval: decided.approval,
        by: context.var.actor.id,
      });
    }
    if (asOwner && shared)
      await approveOwnersSharedUse(store, shared.use, {
        botId: grantAgentId,
        serverId: grantRef.split("/")[0] ?? "",
        ownerId: context.var.actor.id,
      });
    return context.json({ ok: true });
  });

  routes.delete("/grants", requireUser, async (context) => {
    const kind = asGrantKind(context.req.query("kind"));
    const ref = context.req.query("ref");
    const agentId = context.req.query("agentId");
    /*
     * Query params are always strings, so truthiness is not enough: `"   "` is truthy and used
     * to pass this check, delete zero rows by exact match, still write a `plugin_revoked` audit
     * row naming whitespace, and answer `ok:true`. The POST twin already requires non-empty
     * strings; this requires the same and acts on the trimmed values.
     */
    if (
      !kind ||
      typeof ref !== "string" ||
      !ref.trim() ||
      typeof agentId !== "string" ||
      !agentId.trim()
    ) {
      return context.json(
        { error: "A kind, a ref and a Bot are required." },
        400,
      );
    }
    const trimmedRef = ref.trim();
    const trimmedAgentId = agentId.trim();
    const refusal = await enablementRefusal(
      context,
      kind,
      trimmedRef,
      trimmedAgentId,
      "revoke",
    );
    if (refusal) return context.json({ error: refusal }, 403);

    await store.revoke(kind, trimmedRef, trimmedAgentId, actorEmail(context));
    return context.json({ ok: true });
  });

  /** What one Bot holds. The runtime reads this to decide what to offer a model. */
  routes.get("/for/:agentId", requireUser, async (context) => {
    const agentId = context.req.param("agentId");
    // A grant list is a fact about the Bot it belongs to. Left open it says which tools somebody
    // else's private coworker has been given.
    if (!(await canUseBot(context.var.actor, agentId))) {
      return context.json({ error: "There is no such Bot." }, 404);
    }
    return context.json(await store.listForAgent(agentId));
  });

  /**
   * Call a tool, as a Bot.
   *
   * The grant, the policy and the audit row all happen inside the store, so this endpoint cannot
   * accidentally satisfy one of them and skip another. A refusal comes back as 403 with the reason
   * the model and the person are both shown, which is the same sentence written to the trail.
   *
   * NOTHING IN THIS REPOSITORY CALLS IT. It is what the browser used to post to when a Bot's tool
   * loop ran client-side; that loop moved to the server, and the client helper for this went with it.
   * Kept rather than removed, because #37 hardened it with `canUseBot` after that move — so removing
   * it belongs in a change that says so, not in a merge resolution.
   */
  routes.post("/call", requireUser, async (context) => {
    const body = (await context.req.json().catch(() => null)) as {
      ref?: string;
      args?: Record<string, unknown>;
      agentId?: string;
    } | null;
    // Same shape lie as `/grants` above: JSON numbers, objects and arrays are truthy, so they
    // must be refused here rather than inside `canUseBot` or the tool call.
    if (
      typeof body?.ref !== "string" ||
      !body.ref.trim() ||
      typeof body.agentId !== "string" ||
      !body.agentId.trim()
    ) {
      return context.json({ error: "A tool and a Bot are required." }, 400);
    }
    // `args` reaches `Object.entries` inside the store, where a string fans out into indexed
    // entries, a number becomes no entries, and an array passes as an object — all escaping as
    // a vendor 502 instead of a 400 for a malformed call.
    if (
      body.args !== undefined &&
      (typeof body.args !== "object" ||
        body.args === null ||
        Array.isArray(body.args) ||
        Object.getPrototypeOf(body.args) !== Object.prototype)
    ) {
      return context.json({ error: "Tool arguments must be an object." }, 400);
    }

    // Asked before the grant is looked up, and before anything reaches a vendor. The grant says this
    // Bot may use the tool; it says nothing about whether this person may act as this Bot, and the
    // call goes out on the deployment's own credential either way.
    if (!(await canUseBot(context.var.actor, body.agentId))) {
      return context.json({ error: "There is no such Bot." }, 404);
    }

    try {
      const result = await store.callTool({
        ref: body.ref,
        args: body.args ?? {},
        botId: body.agentId,
        /*
         * The user id, not the address.
         *
         * `callTool` keys a per-person connection on `users.id`, so an address here finds nothing and
         * every call through this route would be answered "you have not connected your account" —
         * about a connector the person has connected. It never surfaced because a Bot's own tool loop
         * runs on the server and does not come through here.
         *
         * The other uses of `actorEmail` in this file are `by:` on configuration changes, where an
         * address is the useful thing to record. This one is an identity being resolved, not a name
         * being written down, and the two are not interchangeable.
         */
        actorId: context.var.actor.id,
        // A signed-in person calling the tool themselves: say so, because a shared account refuses a
        // call that does not say what started it.
        initiator: PERSON_INITIATOR,
      });
      return context.json(result);
    } catch (error) {
      if (error instanceof PluginRefusedError) {
        return context.json({ error: error.message, rule: error.rule }, 403);
      }
      if (error instanceof CatalogueEntryUnknownError) {
        return context.json({ error: error.message }, 404);
      }
      /*
       * Ours, and so neither the vendor's fault nor this caller's business.
       *
       * CRITERION. A fault on the `isDeploymentFault` shelf is not reported through the branch
       * below, and its sentence does not leave this process by this route.
       *
       * REASON. Two things would be wrong at once. `failed: true` and 502 say somebody else's
       * software did not answer, which is a false statement about a call that never went out —
       * and this route is `requireUser`, not `requireAdmin`, so the sentence naming our columns
       * and the correction to make would be readable by anybody with a session. The operator who
       * can act on it reads it on the refresh route above, which is admin-gated; here the honest
       * answer is that the deployment cannot make this call as it stands.
       */
      if (isDeploymentFault(error)) {
        return context.json(
          {
            error:
              "That tool isn't set up correctly. Ask an admin to check the server it belongs to.",
          },
          500,
        );
      }
      // A server that failed is not a refusal, and saying so matters: one means the deployment
      // decided against it, the other means somebody else's software did not answer.
      return context.json(
        {
          error:
            error instanceof Error
              ? error.message
              : "The server did not answer.",
          failed: true,
        },
        502,
      );
    }
  });
}