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.

21.5 KB
Raw Blame
import type { MiddlewareHandler } from "hono";
import { Hono } from "hono";
import type { BotAccessCheck } from "../agents/profile-policy";
import type { AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import { requireAdmin } from "../auth/guards";
import { DATA_FUNCTIONS, dataFunction } from "./functions";
import {
  SandboxedNotFoundError,
  SandboxedPublicationRefusedError,
  type SandboxedStore,
} from "./sandboxed";
import {
  ComponentNotFoundError,
  type ComponentStore,
  SandboxedPublicationRequiredError,
} from "./store";

/**
 * The local development actor, which is not a row in `users`.
 *
 * The audit table has a foreign key to that table, so writing this id would fail the constraint and
 * lose the row entirely. Who it was is in the payload either way.
 */
const DEV_ACTOR_EMAIL = "[email protected]";

/**
 * Granting, publishing and asking whether a Bot may use a component.
 *
 * Reading is open to any signed-in person; changing is not. Which components a Bot holds is what the
 * surface in front of that person is built from, and what a Bot may do is not a secret from the
 * person talking to it. Deciding it is an administrator's job.
 *
 * The decision endpoint is the part that matters. The app already knows what it registered, so
 * asking again before every render looks redundant, and is not. The list of tools a run is offered
 * is a snapshot taken when that run started, so a grant revoked one second later is still in the
 * model's hands. Asking at call time is what makes "revoke it and watch it go" true rather than
 * nearly true, and it is where a refusal becomes a row somebody can see.
 */
export function createComponentRoutes(
  store: ComponentStore,
  requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
  auditStore: AuditStore | undefined,
  /**
   * Whether the caller may act as the Bot they named. What a Bot may draw, and the data a drawing
   * reads, are facts about that Bot; an administrator granting one is a separate question and stays
   * behind `requireAdmin`.
   */
  canUseBot: BotAccessCheck,
  /**
   * The source half of a playground component's publication.
   *
   * The generic switch is the only publication UI for both kinds, so this route owns the choice to
   * delegate. The component store still refuses a generic write for a sandboxed row, which keeps a
   * caller that reaches `publish` directly from creating the same half-published state.
   */
  sandboxedStore?: SandboxedStore,
) {
  const routes = new Hono<{ Variables: AppVariables }>();

  const audit = async (
    context: { var: AppVariables },
    eventType: Parameters<typeof recordAuditEvent>[1]["eventType"],
    targetId: string,
    payload: Record<string, unknown>,
  ) => {
    if (!auditStore) return;
    const actor = context.var.actor;
    await recordAuditEvent(auditStore, {
      eventType,
      targetType: "component",
      targetId,
      ...(actor?.id && actor.email !== DEV_ACTOR_EMAIL
        ? { actorUserId: actor.id }
        : {}),
      payload: { actor: actor?.email ?? "unknown", ...payload },
    });
  };

  /** Everything a person needs to see the whole grant surface at once. */
  routes.get("/", requireUser, async (context) =>
    context.json({ components: await store.list() }),
  );

  /**
   * A build announcing what it can draw.
   *
   * The build knows what exists; this deployment decides what it may do. A component is an ordinary
   * React file, so the only thing that can truthfully enumerate them is the app that compiled them.
   * A second list kept here would be a copy to keep in step, and the first thing to fall out of it.
   * Drop a file in and it appears here, published, and any Bot may draw it until somebody says
   * otherwise.
   *
   * Additive only, and not an administrator action: any signed-in person's browser announces it on
   * load, and it cannot change who may use a component, its publication state or its description.
   */
  routes.put("/catalogue", requireUser, async (context) => {
    const body = (await context.req.json().catch(() => null)) as {
      components?: unknown;
    } | null;
    const entries = Array.isArray(body?.components) ? body.components : null;
    if (!entries) {
      return context.json({ error: "A list of components is required." }, 400);
    }

    /*
     * All or nothing, and a 400 names the entry. This used to drop malformed entries and
     * answer 200 with whatever was left, so a deploy that typo'd `kind` as an object or
     * sent a blank `description` got a success response while publishing nothing: `{added: []}`
     * is also what "already in sync" looks like. The operator found out from a missing
     * component, not from the API. A build announcing an empty catalogue sends `[]`, which
     * still syncs to nothing and answers 200.
     */
    const valid: {
      name: string;
      title: string;
      kind: string;
      description: string;
    }[] = [];
    for (const [index, entry] of entries.entries()) {
      if (!entry || typeof entry !== "object") {
        return context.json(
          {
            error: `Component at index ${index} needs a name, a title, a kind and a description.`,
          },
          400,
        );
      }
      const { name, title, kind, description } = entry as Record<
        string,
        unknown
      >;
      if (
        typeof name !== "string" ||
        !name.trim() ||
        typeof title !== "string" ||
        !title.trim() ||
        typeof kind !== "string" ||
        !kind.trim() ||
        typeof description !== "string" ||
        !description.trim()
      ) {
        return context.json(
          {
            error: `Component at index ${index} needs a name, a title, a kind and a description.`,
          },
          400,
        );
      }
      // Trimmed, because that is the string the guard above just approved. A component's `name` is
      // its identity -- `syncCatalogue` compares it against what is already published, `decide` and
      // `listForAgent` look it up by it, and a grant names it -- so publishing " weatherPanel "
      // adds a second component beside `weatherPanel` that nobody has granted and no Bot can be
      // held back from by the name people use.
      valid.push({
        name: name.trim(),
        title: title.trim(),
        kind: kind.trim(),
        description: description.trim(),
      });
    }

    const { added } = await store.syncCatalogue(valid);
    // Only arrivals are recorded. Announcing happens on every page load, and a row per load would
    // bury the trail it is written into.
    for (const name of added) {
      await audit(context, "component.published", name, {
        note: "First seen in a build, published and available to every Bot.",
      });
    }
    return context.json({ added });
  });

  /**
   * What one Bot holds. Polled by the app, which turns it into the tools that Bot is offered.
   *
   * Deliberately says nothing about the components this Bot does NOT hold. A list of everything it
   * is missing would be a list the surface could accidentally register.
   */
  routes.get("/for-agent/:agentId", 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({ components: await store.listForAgent(agentId) });
  });

  /**
   * May this Bot use this component, right now?
   *
   * A POST because it writes: a refusal is recorded. Answering 200 with `allowed: false` rather than
   * 403 is deliberate, the caller is the app asking a question on the Bot's behalf, and it is not
   * itself forbidden from asking. The refusal travels in the body, where the handler turns it into
   * something the model reads.
   */
  routes.post("/:name/decision", requireUser, async (context) => {
    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      agentId?: unknown;
      functions?: unknown;
    } | null;
    const agentId =
      typeof body?.agentId === "string" ? body.agentId.trim() : "";
    if (!agentId) {
      return context.json({ error: "The Bot is required." }, 400);
    }
    // Asked before the grant is, because the grant belongs to the Bot and says nothing about who is
    // asking on its behalf.
    if (!(await canUseBot(context.var.actor, agentId))) {
      return context.json({ error: "There is no such Bot." }, 404);
    }
    /*
     * Every entry, or a 400. This used to filter non-strings out, so
     * `{"functions": [123, null, {}]}` became `[]`, the loop below never ran, and a
     * governance question about X and Y was answered `allowed: true` because X and Y
     * were not strings. A caller asking "may it call these" must get a verdict about the
     * ones it named, not about none of them. Absent still means none.
     */
    const rawFunctions = body?.functions;
    if (
      rawFunctions !== undefined &&
      (!Array.isArray(rawFunctions) ||
        rawFunctions.some(
          (entry) => typeof entry !== "string" || !entry.trim(),
        ))
    ) {
      return context.json(
        { error: "Functions must be a list of function names." },
        400,
      );
    }
    const functions = (
      Array.isArray(rawFunctions) ? rawFunctions : []
    ) as string[];

    const decision = await store.decide(name, agentId);
    if (!decision.allowed) {
      await audit(context, "component.refused", name, {
        bot: agentId,
        reason: decision.reason,
      });
      return context.json({ allowed: false, reason: decision.reason });
    }

    /*
     * The data the component will read, decided here as well.
     *
     * Both decisions are enforced at `/call`, but that runs while the component renders, after
     * whoever asked for it has been answered. A caller that says which functions the component
     * needs gets one verdict covering what it will do, rather than one covering only its name.
     */
    for (const functionName of functions) {
      if (await store.mayCall(name, functionName)) continue;
      const reason = `${name} can't use the function ${functionName}. An admin has to give it to this component.`;
      await audit(context, "component.function_refused", name, {
        bot: agentId,
        function: functionName,
        reason,
      });
      return context.json({ allowed: false, reason });
    }

    return context.json({ allowed: true });
  });

  /** The data functions this build ships, for an administrator deciding what to grant. */
  routes.get("/functions", requireUser, (context) =>
    context.json({
      functions: DATA_FUNCTIONS.map((entry) => ({
        name: entry.name,
        description: entry.description,
        reads: entry.reads,
      })),
    }),
  );

  /**
   * A component fetching its own data.
   *
   * Permission is enforced here. A compiled React component has
   * the whole application and could call any endpoint directly, so an allow-list held beside it in
   * the browser is documentation. The only place that can refuse is the place holding the data.
   *
   * Two decisions are enforced: whether this Bot may use the component at all, and whether the
   * component may call this particular function. Passing one is not passing the other.
   */
  routes.post("/:name/call", requireUser, async (context) => {
    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      function?: unknown;
      args?: unknown;
      agentId?: unknown;
    } | null;
    const functionName =
      typeof body?.function === "string" ? body.function : "";
    const agentId = typeof body?.agentId === "string" ? body.agentId : "";
    if (!functionName || !agentId) {
      return context.json(
        { error: "The function and the Bot are both required." },
        400,
      );
    }
    // A string `args` would reach `fn.run` and fail as a 502 data error instead of a malformed
    // call. Arrays and prototype-polluted objects are refused for the same reason.
    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: "Function arguments must be an object." },
        400,
      );
    }
    // Before the grant, and before anything runs. This is the route that executes, so borrowing a
    // Bot here borrows whatever its components were granted.
    if (!(await canUseBot(context.var.actor, agentId))) {
      return context.json({ error: "There is no such Bot." }, 404);
    }

    const refuse = async (reason: string) => {
      await audit(context, "component.function_refused", name, {
        bot: agentId,
        function: functionName,
        reason,
      });
      return context.json({ allowed: false, reason });
    };

    // The component itself, first. A component this Bot may not use may not read on its behalf.
    const decision = await store.decide(name, agentId);
    if (!decision.allowed) return refuse(decision.reason);

    const fn = dataFunction(functionName);
    if (!fn) {
      // Named separately from a refusal so an administrator is not sent looking for a grant to give
      // for something this build does not have.
      return refuse(
        `There is no data function called ${functionName} in this deployment.`,
      );
    }

    if (!(await store.mayCall(name, functionName))) {
      return refuse(
        `${name} can't use the function ${functionName}. An admin has to give it to this component.`,
      );
    }

    try {
      const data = await store.callFunction(
        functionName,
        (body?.args ?? {}) as Record<string, unknown>,
      );
      await audit(context, "component.function_called", name, {
        bot: agentId,
        function: functionName,
        reads: fn.reads,
      });
      return context.json({ allowed: true, data });
    } catch (error) {
      // A function that threw is not a refusal and must not read as one: nothing was forbidden, the
      // read failed. Recorded as its own thing so a broken query is not filed as a policy event.
      await audit(context, "component.function_failed", name, {
        bot: agentId,
        function: functionName,
        failure: error instanceof Error ? error.message : "The read failed.",
      });
      return context.json(
        { allowed: true, error: "That data could not be read." },
        502,
      );
    }
  });

  routes.post("/:name/functions", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      function?: unknown;
    } | null;
    const functionName =
      typeof body?.function === "string" ? body.function : "";
    if (!functionName || !dataFunction(functionName)) {
      return context.json(
        { error: "A function this deployment ships is required." },
        400,
      );
    }

    try {
      await store.grantFunction(name, functionName, context.var.actor.email);
    } catch (error) {
      if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      }
      throw error;
    }

    await audit(context, "component.function_granted", name, {
      function: functionName,
    });
    return context.json({ granted: true });
  });

  routes.delete("/:name/functions/:function", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const functionName = context.req.param("function");
    // An empty function name would revoke zero rows yet answer `revoked:true` with an audit row
    // naming nothing. Refused at the edge like the grant path.
    if (!functionName.trim()) {
      return context.json({ error: "A function is required." }, 400);
    }
    try {
      await store.revokeFunction(name, functionName);
    } catch (error) {
      if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      }
      throw error;
    }
    await audit(context, "component.function_revoked", name, {
      function: functionName,
    });
    return context.json({ revoked: true });
  });

  routes.post("/:name/grants", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      agentId?: unknown;
    } | null;
    // A whitespace-only id is truthy and would be written as a grant row naming nothing.
    const agentId =
      typeof body?.agentId === "string" ? body.agentId.trim() : "";
    if (!agentId) {
      return context.json({ error: "The Bot is required." }, 400);
    }
    try {
      await store.grant(name, agentId);
    } catch (error) {
      if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      }
      throw error;
    }

    await audit(context, "component.granted", name, { bot: agentId });
    return context.json({ granted: true });
  });

  routes.delete("/:name/grants/:agentId", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const agentId = context.req.param("agentId");
    // Revoking `"   "` would delete zero rows yet answer `revoked:true` with an audit row.
    if (!agentId.trim()) {
      return context.json({ error: "The Bot is required." }, 400);
    }
    try {
      await store.revoke(name, agentId, context.var.actor.email);
    } catch (error) {
      if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      }
      throw error;
    }
    await audit(context, "component.revoked", name, { bot: agentId });
    return context.json({ revoked: true });
  });

  routes.post("/:name/publication", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      published?: unknown;
    } | null;
    /*
     * A real boolean, not truthiness. This used to read `body?.published !== false`, so an
     * empty body, invalid JSON, `{}`, `"no"`, `0` and `null` all evaluated to true and
     * *published* the component with a 200 and a `component.published` audit row. A toggle
     * that publishes on malformed input fails open on the endpoint that decides what every
     * Bot may draw, and the sibling toggles (`PUT /routines/:id/enabled`, channel pin/busy)
     * all answer 400 on non-boolean. Only an explicit true or false moves anything.
     */
    if (typeof body?.published !== "boolean") {
      return context.json({ error: "published must be true or false." }, 400);
    }
    const published = body.published;

    let recordedBySource = false;
    try {
      if (published) {
        await store.publish(name, context.var.actor.email);
      } else {
        await store.unpublish(name, context.var.actor.email);
      }
    } catch (error) {
      if (error instanceof SandboxedPublicationRequiredError) {
        if (!sandboxedStore) {
          return context.json(
            {
              error:
                "The playground source is unavailable, so the component was not published.",
            },
            409,
          );
        }
        try {
          if (published) {
            await sandboxedStore.publish(name, context.var.actor.email);
          } else {
            await sandboxedStore.unpublish(name, context.var.actor.email);
          }
          recordedBySource = true;
        } catch (sourceError) {
          if (sourceError instanceof SandboxedPublicationRefusedError) {
            return context.json({ error: sourceError.message }, 409);
          }
          if (sourceError instanceof SandboxedNotFoundError) {
            return context.json({ error: sourceError.message }, 404);
          }
          throw sourceError;
        }
      } else if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      } else {
        throw error;
      }
    }

    if (recordedBySource) return context.json({ published });

    await audit(
      context,
      published ? "component.published" : "component.unpublished",
      name,
      {},
    );
    return context.json({ published });
  });

  /**
   * Edit the draft. Changes nothing a model can see until it is published, which is the point of
   * having a draft at all.
   */
  routes.put("/:name/draft", requireUser, async (context) => {
    const forbidden = requireAdmin(context);
    if (forbidden) return forbidden;

    const name = context.req.param("name");
    const body = (await context.req.json().catch(() => null)) as {
      description?: unknown;
    } | null;
    const description =
      typeof body?.description === "string" ? body.description.trim() : "";
    if (!description) {
      return context.json({ error: "A description is required." }, 400);
    }

    try {
      await store.saveDraft(name, description, context.var.actor.email);
    } catch (error) {
      if (error instanceof ComponentNotFoundError) {
        return context.json({ error: error.message }, 404);
      }
      throw error;
    }

    await audit(context, "component.draft_saved", name, {});
    return context.json({ saved: true });
  });

  return routes;
}