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.

37.4 KB
Raw Blame
import type { Context } from "hono";
import { type AppVariables, requireAdmin } from "../../auth/guards";
import { BROKERED_PROFILE, type BrokerProvider } from "../access";
import type {
  AppAccess,
  AppAccessRequestKind,
  OwnerGrants,
  Unavailable,
} from "../app-access";
import type { CatalogueEntry } from "../catalogue";
import {
  approveOwnersSharedUse,
  ownerAppsAllowed,
  ownerGrantRefusal,
  withdrawOwnersSharedUse,
} from "../owner-grants";
import type {
  AppAccessRequestRecord,
  AppDirectory,
} from "../plugin-store/app-access";
import {
  CatalogueEntryUnknownError,
  CustomServerRefusedError,
  deploymentFaultSentence,
  isDeploymentFault,
} from "../store";
import { enableComposioApp } from "./composio-apps";
import type { PluginRouteContext } from "./context";
import { sharedGrantApproval } from "./grants";

type RouteContext = Context<{ Variables: AppVariables }>;

/**
 * The longest app name or Bot id a request may carry — the same cap the `show_app_access` tool puts
 * on what a model may ask about. Both are written into the trail when a filing is refused, and an
 * app's name becomes the title an administrator reads in the inbox, so neither is a field a caller
 * may fill with whatever they like.
 */
const MAX_NAME = 200;

/**
 * How many requests one person may have waiting at once. A real person asks about the handful of
 * apps a question needed; past this the inbox is being filled rather than asked, and each extra row
 * is one an administrator has to answer by hand.
 */
export const MAX_PENDING_REQUESTS = 20;

/**
 * What enabling a catalogue entry would need that only an administrator can type, or null when
 * adding its row is the whole of it.
 *
 * A vendor that gives every customer their own host needs that host; a deployment token needs the
 * token; an OAuth client that does not register itself needs the client. Approving a request
 * cannot invent any of those, so it says which one is missing and leaves the request pending.
 */
function adminInputFor(entry: CatalogueEntry): string | null {
  if (entry.host === null) return `the address of your ${entry.title} instance`;
  if (entry.auth.kind === "deployment-bearer")
    return "the token it is reached with";
  if (
    entry.auth.kind === "user-oauth" &&
    entry.auth.clientRegistration !== "dynamic"
  )
    return "an OAuth client registered with the vendor";
  return null;
}

/**
 * The sentence an approval is refused with when the app is there and still cannot be used.
 *
 * The broker's name and key come from {@link BROKERED_PROFILE}, so an Arcade deployment is told
 * to set ARCADE_API_KEY in the words a Composio one is told to set COMPOSIO_API_KEY.
 */
function unavailableSentence(
  reason: Unavailable,
  title: string,
  provider: BrokerProvider,
  again = "approve this request again",
): string {
  switch (reason) {
    case "absent":
      return `${title} can't be turned on from here.`;
    case "composio_unconfigured": {
      const { vendor, envVar } = BROKERED_PROFILE[provider];
      const article = /^[aeiou]/i.test(vendor) ? "an" : "a";
      return `${title} is ${article} ${vendor} app, and ${envVar} isn't set. Set it, then ${again}.`;
    }
    case "scheme_unreadable":
      return `${title} is turned on, but OpenBot can't read how it connects. Remove it and turn it on again under Plugins, then ${again}.`;
    case "oauth_client_missing":
      return `${title} has no OAuth client yet. Register one on its page under Plugins, then ${again}.`;
    case "token_missing":
      return `${title} has no token yet. Add one on its page under Plugins, then ${again}.`;
  }
}

/**
 * Where a person sees which work apps a Bot can use for them, asks an administrator for the ones
 * only an administrator can fix, and where the administrator answers.
 *
 * THE STATE IS ALWAYS THE SERVER'S. A person's browser names a Bot and an app; what the app is for
 * them, and therefore what a request asks for, is computed here from the same tables every gate
 * reads. A request cannot be filed for a state the app is not in, and approving one does the thing
 * that state was missing — switching the app on, granting it to the Bot — in the same press.
 *
 * WHY NOT `shared_use_requests`. That table answers a different question: a Shared app whose team
 * account IS connected, and whether an administrator approves the audience a Bot exposes it to.
 * "Please connect the team account" is a request about the account itself, before any audience can
 * matter, and has none of that table's columns to fill. The style, the conditional decide and the
 * audit vocabulary are that flow's; the rows are not.
 */
export function mountAppAccessRoutes({
  routes,
  store,
  requireUser,
  canUseBot,
  composio,
  shared,
  actorEmail,
  activeProvider,
  activeVendor,
}: PluginRouteContext) {
  const composioConfigured = Boolean(composio);
  /*
   * Asked only to name an app this deployment has no row for — see `readDirectory` in the store.
   * The adapter caches the listing, so a card asking about an app nobody enabled costs a vendor
   * call at most once per cache window rather than once per render.
   */
  const directory: AppDirectory | undefined = composio
    ? () => composio.broker.listApps()
    : undefined;
  /*
   * What the shared-use gate would answer this person's chat through this Bot, so a Shared app
   * whose audience was never approved reads as refused rather than ready. Without the store there
   * is no gate to ask, and the call path refuses every Shared call anyway; the state says `ready`
   * there exactly as it did before this was asked.
   */
  const sharedAudience = shared?.use.admitsPerson;

  const refused = async (
    context: RouteContext,
    input: {
      app: string;
      reason: string;
      error: string;
      status: 400 | 403 | 404 | 409 | 429 | 502 | 503;
      request?: string;
      bot?: string | null;
      kind?: string;
    },
  ) => {
    await store.recordAppAccessEvent({
      eventType: "app_access.refused",
      targetId: input.app,
      actorUserId: context.var.actor.id,
      payload: {
        app: input.app,
        reason: input.reason,
        ...(input.request ? { request: input.request } : {}),
        ...(input.bot !== undefined ? { bot: input.bot } : {}),
        ...(input.kind ? { kind: input.kind } : {}),
      },
    });
    return context.json({ error: input.error }, input.status);
  };

  /**
   * Carry out a request already claimed by this administrator: switch the app on, grant its tools to
   * the Bot, or — for a team account, which only a consent screen can connect — confirm it has been
   * connected. Answers with the response to send, and marks `done` once the change is carried out;
   * one that was not leaves the claim for the caller to put back.
   *
   * SHARED BY THE INBOX'S APPROVE AND AN ADMINISTRATOR'S ONE PRESS ON A CARD, so the second can never
   * grant more, check less or leave a thinner trail than the first. `direct` marks the trail row of
   * the one press, whose request was filed and approved by the same person in the same breath.
   */
  const carryOut = async (
    context: RouteContext,
    request: AppAccessRequestRecord,
    chosen: string[] | undefined,
    done: { carriedOut: boolean },
    direct = false,
  ): Promise<Response> => {
    const deny = (
      reason: string,
      error: string,
      status: 400 | 404 | 409 | 502 | 503,
    ) =>
      refused(context, {
        app: request.appKey,
        request: request.id,
        bot: request.agentId,
        kind: request.kind,
        reason,
        error,
        status,
      });

    const inspect = () =>
      store.inspectApp({
        app: request.appKey,
        agentId: request.agentId ?? "",
        userId: null,
        composioConfigured,
        directory,
      });

    // The one press filed no request the admin could approve again: they press again instead.
    const again = direct ? "try again" : "approve this request again";

    let inspected = await inspect();
    if (!inspected)
      return deny(
        "no_such_app",
        `${request.appTitle} isn't available anymore.`,
        409,
      );

    let enabled = false;
    if (request.kind !== "connect_shared" && inspected.unavailable) {
      const title = inspected.access.displayName;
      if (inspected.unavailable !== "absent")
        return deny(
          inspected.unavailable,
          unavailableSentence(
            inspected.unavailable,
            title,
            activeProvider,
            again,
          ),
          inspected.unavailable === "composio_unconfigured" ? 503 : 409,
        );
      if (inspected.toolkit) {
        if (!composio)
          return deny(
            "composio_unconfigured",
            unavailableSentence(
              "composio_unconfigured",
              title,
              activeProvider,
              again,
            ),
            503,
          );
        const outcome = await enableComposioApp(
          { store, composio, activeProvider, activeVendor },
          inspected.toolkit,
          actorEmail(context),
        );
        if (!outcome.ok)
          return deny("enable_failed", outcome.error, outcome.status);
      } else if (inspected.entry) {
        const needed = adminInputFor(inspected.entry);
        if (needed)
          return deny(
            "needs_admin_input",
            `${title} needs ${needed}. Add it on its page under Plugins, then ${again}.`,
            409,
          );
        try {
          await store.addServer({
            key: inspected.entry.key,
            by: actorEmail(context),
          });
        } catch (error) {
          if (
            error instanceof CatalogueEntryUnknownError ||
            error instanceof CustomServerRefusedError
          )
            return deny("enable_failed", error.message, 400);
          if (isDeploymentFault(error))
            return deny("enable_failed", deploymentFaultSentence(error), 409);
          throw error;
        }
      } else {
        return deny(
          "absent",
          unavailableSentence("absent", title, activeProvider),
          409,
        );
      }
      enabled = true;
      inspected = await inspect();
      if (!inspected || inspected.unavailable)
        return deny(
          "enable_failed",
          `${title} was turned on but still can't be used. Open its page under Plugins to see why.`,
          409,
        );
    }

    let granted: string[] = [];
    if (
      request.kind !== "connect_shared" &&
      request.agentId &&
      !inspected.access.granted
    ) {
      const agentId = request.agentId;
      const serverId = inspected.answeringId;
      const name = inspected.access.displayName;
      if (!(await store.agentIsRegistered(agentId)) || !serverId)
        return deny("no_such_bot", "That Bot is no longer here.", 409);
      const tools = await store.appTools(serverId);
      const advertised = tools.map((tool) => tool.ref);
      const refs =
        chosen ?? tools.filter((tool) => tool.read).map((tool) => tool.ref);
      const outside = refs.filter((ref) => !advertised.includes(ref));
      if (outside.length > 0)
        return deny(
          "refs_outside_app",
          `${outside.join(", ")} ${outside.length === 1 ? "is" : "are"} not among ${name}'s tools.`,
          400,
        );
      if (advertised.length === 0)
        return deny(
          "no_tools",
          `${name} has no tools to give yet. Refresh its tools on its page under Plugins, then ${again}.`,
          409,
        );
      if (refs.length === 0)
        return deny(
          "no_read_only_tools",
          `None of ${name}'s actions are marked read-only, so approving here gives this Bot nothing. Choose its actions on ${name}'s page under Plugins, then ${again}.`,
          409,
        );
      for (const ref of refs) {
        await store.grant("mcp", ref, agentId, actorEmail(context));
      }
      const sharedDecision = await sharedGrantApproval(
        { store, shared },
        refs[0] ?? "",
        agentId,
        undefined,
      );
      if (sharedDecision !== "unreadable" && sharedDecision.approval && shared)
        await shared.use.setApproval({
          botId: agentId,
          serverId: sharedDecision.appId,
          approval: sharedDecision.approval,
          by: context.var.actor.id,
        });
      granted = refs;
    }

    if (
      request.kind === "connect_shared" &&
      inspected.access.account === "shared" &&
      !inspected.sharedUsable
    )
      return deny(
        "shared_not_connected",
        `The shared ${inspected.access.displayName} account is not connected yet. Connect it on ${inspected.access.displayName}'s page under Plugins, then approve this request.`,
        409,
      );

    done.carriedOut = true;
    const closed = request;
    await store.recordAppAccessEvent({
      eventType: "app_access.approved",
      targetId: closed.appKey,
      actorUserId: context.var.actor.id,
      payload: {
        request: closed.id,
        app: closed.appKey,
        bot: closed.agentId,
        kind: closed.kind,
        enabled,
        granted: granted.length,
        ...(direct ? { direct: true } : {}),
      },
    });
    return context.json({ request: closed, enabled, granted });
  };

  /**
   * Every work app this Bot holds, with what each one is for the person asking.
   *
   * Only for a Bot the person may use, and answered 404 otherwise, for the reason the grant list
   * beside it gives: what a private Bot holds is a fact about that Bot.
   */
  routes.get("/for/:agentId/apps", requireUser, async (context) => {
    const agentId = context.req.param("agentId");
    if (!(await canUseBot(context.var.actor, agentId)))
      return context.json({ error: "There is no such Bot." }, 404);
    return context.json({
      apps: await store.appAccessForBot({
        userId: context.var.actor.id,
        agentId,
        composioConfigured,
        directory,
        sharedAudience,
        ownerGrantsAllowed: await ownerAppsAllowed(context.var.actor.id),
      }),
    });
  });

  /**
   * One app, by key or by name, whether or not this Bot holds it — so a card in a conversation can
   * say an app is switched off or not granted, and offer the request that fixes it.
   */
  routes.get("/for/:agentId/apps/:app", requireUser, async (context) => {
    const agentId = context.req.param("agentId");
    if (!(await canUseBot(context.var.actor, agentId)))
      return context.json({ error: "There is no such Bot." }, 404);
    const app = context.req.param("app");
    const inspected =
      app.length > MAX_NAME
        ? null
        : await store.inspectApp({
            app,
            agentId,
            userId: context.var.actor.id,
            composioConfigured,
            directory,
            sharedAudience,
            ownerGrantsAllowed: await ownerAppsAllowed(context.var.actor.id),
          });
    if (!inspected)
      return context.json({ error: `OpenBot has no app called ${app}.` }, 404);
    return context.json({ app: inspected.access });
  });

  /**
   * The app a request would be about, or the refusal: the Bot and the app named, the Bot one this
   * person may use, the app one something vouches for, and a state only an administrator can fix.
   * What filing a request checks, and what an administrator's one press checks before it files and
   * approves in the same breath — so neither can be pressed for something the other would refuse.
   */
  const requestable = async (
    context: RouteContext,
    rawAgentId: unknown,
    rawApp: unknown,
  ): Promise<
    | Response
    | { agentId: string; access: AppAccess; requestKind: AppAccessRequestKind }
  > => {
    const agentId = typeof rawAgentId === "string" ? rawAgentId.trim() : "";
    const app = typeof rawApp === "string" ? rawApp.trim() : "";
    if (!agentId || !app)
      return context.json({ error: "Name the Bot and the app." }, 400);
    if (agentId.length > MAX_NAME || app.length > MAX_NAME)
      return context.json(
        {
          error: `Bot and app names are ${MAX_NAME} characters at most.`,
        },
        400,
      );
    if (!(await canUseBot(context.var.actor, agentId)))
      return refused(context, {
        app,
        bot: agentId,
        reason: "no_such_bot",
        error: "There is no such Bot.",
        status: 404,
      });
    const found = await store.inspectApp({
      app,
      agentId,
      userId: context.var.actor.id,
      composioConfigured,
      directory,
      sharedAudience,
      ownerGrantsAllowed: await ownerAppsAllowed(context.var.actor.id),
    });
    const inspected =
      found && (found.vouched || found.access.granted) ? found : null;
    if (!inspected)
      return refused(context, {
        app,
        bot: agentId,
        reason: "no_such_app",
        error: `OpenBot has no app called ${app}.`,
        status: 404,
      });
    const { access } = inspected;
    if (!access.requestKind)
      return refused(context, {
        app: access.key,
        bot: agentId,
        reason: `nothing_to_request:${access.state}`,
        error:
          access.state === "ready"
            ? `${access.displayName} is ready to use. There's nothing to ask an admin for.`
            : access.state === "owner_grantable"
              ? `This is your Bot, so you can give it ${access.displayName} yourself.`
              : `${access.displayName} needs your own account, not an admin. Connect it yourself.`,
        status: 409,
      });
    return { agentId, access, requestKind: access.requestKind };
  };

  /**
   * Ask an administrator for access. The body names the Bot and the app; the kind is the server's.
   *
   * A SECOND PRESS IS THE FIRST REQUEST. One pending request per person, app, Bot and kind, so
   * asking again answers with the one already waiting and `created: false`, and writes no second
   * trail row.
   *
   * ONLY FOR AN APP SOMETHING VOUCHES FOR, AND ONLY SO MANY. Asking to enable a `composio-` id the
   * directory does not list would put whatever the caller typed in front of an administrator as an
   * app's name, for an approval that can only fail; it is answered as no such app, unless the Bot
   * already holds a grant for it and the request is about putting back something it was given. And
   * a person with {@link MAX_PENDING_REQUESTS} waiting is told to wait for those to be answered.
   */
  routes.post("/access-requests", requireUser, async (context) => {
    const body = (await context.req.json().catch(() => null)) as {
      agentId?: unknown;
      app?: unknown;
    } | null;
    const asked = await requestable(context, body?.agentId, body?.app);
    if (asked instanceof Response) return asked;
    const { agentId, access, requestKind } = asked;
    /*
     * The one already waiting is answered as itself before the cap is counted, so a person at the
     * cap pressing again on a request they filed is shown it, not refused.
     */
    if (
      !access.request &&
      (await store.countPendingAppAccessRequests(context.var.actor.id)) >=
        MAX_PENDING_REQUESTS
    )
      return refused(context, {
        app: access.key,
        bot: agentId,
        reason: "too_many_pending",
        kind: requestKind,
        error: `You already have ${MAX_PENDING_REQUESTS} requests waiting for an admin. Withdraw one, or wait for an answer, then ask again.`,
        status: 429,
      });
    const filed = await store.fileAppAccessRequest({
      requestedBy: context.var.actor.id,
      agentId,
      appKey: access.key,
      appTitle: access.displayName,
      kind: requestKind,
    });
    return context.json(filed, filed.created ? 201 : 200);
  });

  /**
   * An administrator's one press on a card: file the request this app needs on this Bot, and
   * approve it, as one step. Their own request, approved by themselves, so the trail reads exactly
   * as the two presses would — `app_access.requested`, then `app_access.approved` marked `direct` —
   * and nothing about it is a second way to grant.
   *
   * THE SAME CHECKS, THE SAME CHANGE. What may be asked for is {@link requestable}'s answer, and
   * what approving does is {@link carryOut}'s; this route only joins them. No `refs`: the one press
   * grants what the inbox's Approve grants without them, the app's read-only actions, and anything
   * that sends or writes is still chosen action by action on the Bot's page.
   *
   * A PRESS THAT CANNOT BE CARRIED OUT LEAVES NOTHING WAITING. The request this press filed is
   * withdrawn again, since an administrator's own inbox holding a request they could not carry out
   * a moment ago is noise; the refusal's sentence says what is missing. A request of theirs that was
   * already waiting is put back as it was.
   */
  routes.post(
    "/for/:agentId/apps/:app/approve",
    requireUser,
    async (context) => {
      const forbidden = requireAdmin(context);
      if (forbidden) return forbidden;
      const asked = await requestable(
        context,
        context.req.param("agentId"),
        context.req.param("app"),
      );
      if (asked instanceof Response) return asked;
      const { agentId, access, requestKind } = asked;
      const by = context.var.actor.id;
      const filed = await store.fileAppAccessRequest({
        requestedBy: by,
        agentId,
        appKey: access.key,
        appTitle: access.displayName,
        kind: requestKind,
      });
      const claimed = await store.claimAppAccessRequest({
        id: filed.request.id,
        by,
      });
      if (!claimed)
        return refused(context, {
          app: access.key,
          request: filed.request.id,
          bot: agentId,
          kind: requestKind,
          reason: "already_resolved",
          error: "That request has already been answered.",
          status: 409,
        });
      const done = { carriedOut: false };
      try {
        return await carryOut(context, claimed, undefined, done, true);
      } finally {
        if (!done.carriedOut) {
          await store.releaseAppAccessRequest({ id: claimed.id, by });
          /*
           * Withdrawn with the row a withdrawal always writes, so the trail does not hold an
           * `app_access.requested` that nothing ever answered.
           */
          const withdrawn = filed.created
            ? await store.closeAppAccessRequest({
                id: claimed.id,
                status: "cancelled",
                by,
                requestedBy: by,
              })
            : null;
          if (withdrawn)
            await store.recordAppAccessEvent({
              eventType: "app_access.cancelled",
              targetId: withdrawn.appKey,
              actorUserId: by,
              payload: {
                request: withdrawn.id,
                app: withdrawn.appKey,
                bot: withdrawn.agentId,
                kind: withdrawn.kind,
                direct: true,
              },
            });
        }
      }
    },
  );

  /**
   * The Bot and the app an owner's give or take-back names, inspected for this person: the Bot one
   * they may use, the app one this deployment can name. The refusal otherwise.
   */
  const ownersApp = async (context: RouteContext) => {
    const agentId = context.req.param("agentId")?.trim() ?? "";
    const app = context.req.param("app")?.trim() ?? "";
    if (
      !agentId ||
      !app ||
      agentId.length > MAX_NAME ||
      app.length > MAX_NAME ||
      !(await canUseBot(context.var.actor, agentId))
    )
      return context.json({ error: "There is no such Bot." }, 404);
    const found = await store.inspectApp({
      app,
      agentId,
      userId: context.var.actor.id,
      composioConfigured,
      directory,
      sharedAudience,
      ownerGrantsAllowed: await ownerAppsAllowed(context.var.actor.id),
    });
    if (!found || !(found.vouched || found.access.granted))
      return context.json({ error: `OpenBot has no app called ${app}.` }, 404);
    return { agentId, inspected: found };
  };

  /**
   * A Bot's owner giving it one of their own apps, as one press: the card's "Let Research Bot use
   * your Gmail?", a switch on the Bot's page, a box left ticked on the New Bot sheet.
   *
   * WHAT MAY BE GIVEN IS {@link ownerGrantRefusal}'S ANSWER: their own Bot, an app an administrator
   * switched on and opened to owners, and the `ownerApps` capability. Refused 403 with the sentence
   * otherwise, and the refusal is in the trail.
   *
   * WHAT IS GIVEN IS WHAT AN ADMINISTRATOR'S ONE PRESS GIVES: the app's read-only actions, through
   * the same `appTools` reading, so an owner never gets more by asking themselves than an
   * administrator's approval would have given. Anything that sends or writes is chosen action by
   * action: by an administrator, or by the owner one advertised action at a time through
   * `POST /grants`, still on the asker's own account and still behind the approval gate. ONE EXCEPTION, the built-in Routines: every action it has keeps,
   * changes or drops the asking person's own standing instructions and nothing else, and "every
   * morning, …" is a write — given only its reads, a Bot could list routines and never make one.
   *
   * Every grant is `granted_as = owner`, which keeps each call on the asking person's own account
   * (`credentialActorFor`). A Bot that already holds any of the app is answered with nothing given.
   */
  routes.post("/for/:agentId/apps/:app/give", requireUser, async (context) => {
    const found = await ownersApp(context);
    if (found instanceof Response) return found;
    const { agentId, inspected } = found;
    const { access } = inspected;
    const deny = (reason: string, error: string, status: 403 | 409) =>
      refused(context, {
        app: access.key,
        bot: agentId,
        reason,
        error,
        status,
      });
    const refusal = await ownerGrantRefusal(
      store,
      context.var.actor.id,
      agentId,
      inspected,
    );
    if (refusal) return deny("owner_grant_refused", refusal, 403);
    const serverId = inspected.answeringId ?? "";
    /*
     * A SHARED APP OWNERS MAY GIVE IS USABLE AT ONCE: the grant sets who may use the team account
     * through this Bot, the people who can use the Bot, and nobody else (`approveOwnerGrant`). Asked
     * again of a Bot that already holds the owner's grant too, so pressing give puts back an
     * audience withdrawn while an administrator had owners' choice switched off.
     */
    const approveShared = async () => {
      if (shared)
        await approveOwnersSharedUse(store, shared.use, {
          botId: agentId,
          serverId,
          ownerId: context.var.actor.id,
        });
    };
    if (access.granted) {
      if (access.givenByOwner) await approveShared();
      return context.json({ granted: [] });
    }
    const tools = await store.appTools(serverId);
    if (tools.length === 0)
      return deny(
        "no_tools",
        `${access.displayName} has nothing to give yet. Ask an admin to refresh it.`,
        409,
      );
    const builtin = inspected.entry?.auth.kind === "builtin";
    const refs = tools
      .filter((tool) => builtin || tool.read)
      .map((tool) => tool.ref);
    if (refs.length === 0)
      return deny(
        "no_read_only_tools",
        `${access.displayName} has nothing a Bot can only read with. Ask an admin to choose what this Bot can do with it.`,
        409,
      );
    for (const ref of refs)
      await store.grant("mcp", ref, agentId, actorEmail(context), "owner");
    await store.recordAppAccessEvent({
      eventType: "app_access.owner_granted",
      targetId: access.key,
      actorUserId: context.var.actor.id,
      payload: { app: access.key, bot: agentId, refs },
    });
    await approveShared();
    return context.json({ granted: refs });
  });

  /**
   * A Bot's owner taking back what they gave it on one app. Only the owner's own grants go: one an
   * administrator made stays, because it was not the owner's to give. Still asks that the Bot is
   * theirs; it does not ask whether the app is still open to owners, since taking away is always
   * allowed (see `enablementRefusal`'s note on `intent`).
   */
  routes.delete(
    "/for/:agentId/apps/:app/give",
    requireUser,
    async (context) => {
      const found = await ownersApp(context);
      if (found instanceof Response) return found;
      const { agentId, inspected } = found;
      if ((await store.agentOwner(agentId)) !== context.var.actor.id)
        return refused(context, {
          app: inspected.access.key,
          bot: agentId,
          reason: "owner_revoke_refused",
          error: "You can only change apps on Bots you own.",
          status: 403,
        });
      const ids = [
        ...new Set([
          inspected.access.key,
          ...inspected.rowIds,
          ...(inspected.answeringId ? [inspected.answeringId] : []),
        ]),
      ];
      const refs = await store.revokeOwnerGrants(
        ids,
        agentId,
        actorEmail(context),
      );
      if (refs.length > 0)
        await store.recordAppAccessEvent({
          eventType: "app_access.owner_revoked",
          targetId: inspected.access.key,
          actorUserId: context.var.actor.id,
          payload: { app: inspected.access.key, bot: agentId, refs },
        });
      /*
       * The Shared-account audience the owner's grant set goes with it. One an administrator
       * approved stays, as their grants do.
       */
      if (shared && inspected.answeringId)
        await withdrawOwnersSharedUse(store, shared.use, {
          serverId: inspected.answeringId,
          botId: agentId,
          actorId: context.var.actor.id,
          why: "owner_took_back",
        });
      return context.json({ revoked: refs });
    },
  );

  /**
   * The apps this person could give their own Bots: what the New Bot sheet offers ticked, and the
   * switches on a Bot's page. Empty where an administrator switched the feature off for them.
   */
  routes.get("/giveable", requireUser, async (context) => {
    if (!(await ownerAppsAllowed(context.var.actor.id)))
      return context.json({ apps: [] });
    return context.json({
      apps: await store.giveableApps({
        userId: context.var.actor.id,
        composioConfigured,
      }),
    });
  });

  /**
   * Who may give an app to a Bot: any Bot's owner (`any`), only an administrator (`admin`), or the
   * default for the app's account (`null`). Admin only, and in the trail.
   */
  routes.put("/servers/:id/owner-grants", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;
    const body = (await context.req.json().catch(() => null)) as {
      ownerGrants?: unknown;
    } | null;
    const value = body?.ownerGrants;
    if (value !== null && value !== "any" && value !== "admin")
      return context.json(
        { error: "Choose any, admin, or null for the default." },
        400,
      );
    const changed = await store.setOwnerGrants({
      serverId: context.req.param("id"),
      ownerGrants: value as OwnerGrants | null,
      by: actorEmail(context),
    });
    if (!changed)
      return context.json({ error: "That app hasn't been added." }, 404);
    /*
     * Owners no longer decide, so the Shared-account audiences their grants set are withdrawn.
     * The grants stay, an administrator's to keep or take, and their calls are refused until an
     * administrator approves who may use the account. (`approvalFor` would not read those audiences
     * now anyway; this removes them rather than leaving them to come back if the rule does.)
     */
    if (value !== "any" && shared)
      await withdrawOwnersSharedUse(store, shared.use, {
        serverId: context.req.param("id"),
        actorId: context.var.actor.id,
        why: "owner_grants_changed",
      });
    return context.json({ ok: true });
  });

  /** The person's own pending requests, newest first. */
  routes.get("/access-requests/mine", requireUser, async (context) =>
    context.json({
      requests: await store.pendingAppAccessRequests({
        requestedBy: context.var.actor.id,
      }),
    }),
  );

  /**
   * Withdraw one's own pending request. Somebody else's reads exactly like one that does not exist,
   * so this route cannot be used to learn who asked for what.
   */
  routes.delete("/access-requests/:id", requireUser, async (context) => {
    const id = context.req.param("id");
    const closed = await store.closeAppAccessRequest({
      id,
      status: "cancelled",
      by: context.var.actor.id,
      requestedBy: context.var.actor.id,
    });
    if (!closed) {
      const existing = await store.appAccessRequest(id);
      const mine = existing?.requestedBy === context.var.actor.id;
      return refused(context, {
        app: mine ? (existing?.appKey ?? "") : "",
        request: id,
        reason: mine ? "already_resolved" : "no_such_request",
        error: mine
          ? "That request has already been answered."
          : "There is no such request.",
        status: mine ? 409 : 404,
      });
    }
    await store.recordAppAccessEvent({
      eventType: "app_access.cancelled",
      targetId: closed.appKey,
      actorUserId: context.var.actor.id,
      payload: {
        request: closed.id,
        app: closed.appKey,
        bot: closed.agentId,
        kind: closed.kind,
      },
    });
    return context.json({ request: closed });
  });

  /**
   * Every pending request, for an administrator: one app's with `?app=`, or all of them, and a
   * count per app either way so the Plugins list can badge each app without a second read.
   */
  routes.get("/access-requests", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;
    const all = await store.pendingAppAccessRequests({});
    const byApp: Record<string, number> = {};
    for (const request of all)
      byApp[request.appKey] = (byApp[request.appKey] ?? 0) + 1;
    const app = context.req.query("app")?.trim();
    return context.json({
      requests: app ? all.filter((request) => request.appKey === app) : all,
      counts: { total: all.length, byApp },
    });
  });

  /**
   * Approve a request by doing what it asks: switch the app on, grant its tools to the Bot, or —
   * for a team account, which only a consent screen can connect — confirm it has been connected.
   *
   * CLAIMED, THEN CHANGED. The request is closed as approved by this administrator before anything
   * is changed, so a dismiss, a withdrawal or a second approval arriving meanwhile finds it answered
   * and loses, and the change can never land under a request somebody else answered. A change that
   * cannot be carried out puts the request back, and it waits again with the step that is missing;
   * so does one that throws. See `claimAppAccessRequest` in the store, which says why this is not a
   * row lock held across the change.
   *
   * `refs` NARROWS THE GRANT, AND WITHOUT IT ONLY THE READS ARE GRANTED. One press in the inbox
   * gives the Bot every action the app has marked read-only — what the Bot page's bulk switch
   * offers, and nothing that sends, writes or deletes. Anything more is chosen action by action, on
   * the Bot's page for the app or by naming them here. An app with no read-only action is refused
   * with that sentence rather than granted everything. A ref outside the app is refused rather than
   * dropped.
   */
  routes.post("/access-requests/:id/approve", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;
    const id = context.req.param("id");
    const body = (await context.req.json().catch(() => null)) as {
      refs?: unknown;
    } | null;
    if (
      body?.refs !== undefined &&
      (!Array.isArray(body.refs) ||
        body.refs.some((ref) => typeof ref !== "string"))
    )
      return context.json({ error: "Tools must be a list of refs." }, 400);
    const chosen = body?.refs as string[] | undefined;

    const claimed = await store.claimAppAccessRequest({
      id,
      by: context.var.actor.id,
    });
    if (!claimed) {
      const existing = await store.appAccessRequest(id);
      return refused(context, {
        app: existing?.appKey ?? "",
        request: id,
        reason: existing ? "already_resolved" : "no_such_request",
        error: existing
          ? "That request has already been answered."
          : "There is no such request.",
        status: existing ? 409 : 404,
      });
    }
    const done = { carriedOut: false };
    try {
      return await carryOut(context, claimed, chosen, done);
    } finally {
      if (!done.carriedOut)
        await store.releaseAppAccessRequest({ id, by: context.var.actor.id });
    }
  });

  /** Dismiss a request: nothing changes but the request, which stops waiting. */
  routes.post("/access-requests/:id/dismiss", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;
    const id = context.req.param("id");
    const closed: AppAccessRequestRecord | null =
      await store.closeAppAccessRequest({
        id,
        status: "dismissed",
        by: context.var.actor.id,
      });
    if (!closed) {
      const existing = await store.appAccessRequest(id);
      return refused(context, {
        app: existing?.appKey ?? "",
        request: id,
        reason: existing ? "already_resolved" : "no_such_request",
        error: existing
          ? "That request has already been answered."
          : "There is no such request.",
        status: existing ? 409 : 404,
      });
    }
    await store.recordAppAccessEvent({
      eventType: "app_access.dismissed",
      targetId: closed.appKey,
      actorUserId: context.var.actor.id,
      payload: {
        request: closed.id,
        app: closed.appKey,
        bot: closed.agentId,
        kind: closed.kind,
      },
    });
    return context.json({ request: closed });
  });
}