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.

10.5 KB
Raw Blame
/**
 * The HTTP half of the capability switches, and the model allowlist.
 *
 * Mounted once in app.ts as `app.use("/api/*", createEnterpriseGate(requireUser))`. A request that
 * matches none of the routes below passes straight through without a session lookup. One that
 * matches is authenticated by the same `requireUser` the route itself uses, checked, and refused with
 * a 403 carrying a sentence the person can act on. The route then runs its own guard as before.
 *
 * Fail closed: a capability that cannot be read refuses (503). Where the enterprise controls were
 * never installed (a unit test, a script) the gate passes everything, which is the product as it was.
 */
import { eq } from "drizzle-orm";
import type { Context, MiddlewareHandler } from "hono";
import { recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import { agents } from "../db/schema";
import { type Capability, capabilityRefusal } from "./capabilities";
import { enterpriseControls } from "./controls";

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

type Rule = {
  method: string | string[];
  path: RegExp;
  /** The capabilities this request needs, possibly depending on its body. */
  needs: (context: Ctx) => Promise<Capability[]>;
};

async function body(context: Ctx): Promise<Record<string, unknown>> {
  try {
    const parsed = await context.req.raw.clone().json();
    return parsed && typeof parsed === "object"
      ? (parsed as Record<string, unknown>)
      : {};
  } catch {
    return {};
  }
}

const COPILOT_BASE = "/api/copilotkit";

/**
 * A run or connect of a Bot through the CopilotKit runtime, matched the way the runtime matches it.
 *
 * The runtime does not anchor its routes: its router (`fetch-router` `matchSegments`) takes any path
 * under its base whose LAST segments are `agent/<id>/run`, `agent/<id>/connect` or `agent/<id>/suggest`
 * (a suggestion runs the Bot's model on whatever messages the caller sends). So
 * `/api/copilotkit/x/agent/<id>/run` runs the Bot exactly as `/api/copilotkit/agent/<id>/run` does,
 * and an anchored pattern here would let the first one through ungoverned.
 */
export function runtimeRun(
  path: string,
): { agentId: string; action: "run" | "connect" | "suggest" } | null {
  if (path !== COPILOT_BASE && !path.startsWith(`${COPILOT_BASE}/`))
    return null;
  const segments = path.split("/").filter(Boolean);
  const count = segments.length;
  const action = segments[count - 1];
  if (count < 3 || segments[count - 3] !== "agent") return null;
  if (action !== "run" && action !== "connect" && action !== "suggest")
    return null;
  try {
    return { agentId: decodeURIComponent(segments[count - 2] ?? ""), action };
  } catch {
    return null;
  }
}

const RUNTIME_RUN: Rule = {
  method: "POST",
  path: /$^/,
  needs: async () => ["useBots"],
};

export const GATED_ROUTES: Rule[] = [
  {
    method: ["POST", "PATCH"],
    path: /^\/api\/agents(\/[^/]+)?$/,
    needs: async (context) =>
      String((await body(context)).visibility ?? "").trim() === "public"
        ? ["useBots", "teamBots"]
        : ["useBots"],
  },
  {
    method: "POST",
    path: /^\/api\/agents\/[^/]+\/duplicate$/,
    needs: async () => ["useBots"],
  },
  {
    method: "POST",
    path: /^\/api\/host-access\/grants$/,
    needs: async () => ["localComputer"],
  },
  {
    method: "POST",
    path: /^\/api\/delivery\/(slack|teams)(\/.*)?$/,
    needs: async () => ["slackTeams"],
  },
  {
    method: ["POST", "PUT", "PATCH"],
    path: /^\/api\/approvals\/(preferences|rules)(\/.*)?$/,
    needs: async () => ["customRules"],
  },
  {
    method: "POST",
    path: /^\/api\/approvals\/[^/]+\/decision$/,
    needs: async (context) =>
      (await body(context)).decision === "allow_always" ? ["customRules"] : [],
  },
  {
    method: ["POST", "PUT", "PATCH"],
    path: /^\/api\/passwords(\/.*)?$/,
    needs: async () => ["passwordManager"],
  },
  {
    method: "POST",
    path: /^\/api\/computers\/[^/]+\/(control|human)\/(secret|sign-in)$/,
    needs: async () => ["passwordManager"],
  },
];

function matches(rule: Rule, method: string, path: string) {
  const methods = Array.isArray(rule.method) ? rule.method : [rule.method];
  return methods.includes(method) && rule.path.test(path);
}

/** The serving model a run's stream names, if it names one: `"model":"..."` in any event. */
const MODEL_IN_STREAM = /"model"\s*:\s*"([^"]{1,200})"/;

export function createEnterpriseGate(
  requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
): MiddlewareHandler<{ Variables: AppVariables }> {
  return async (context, next) => {
    const controls = enterpriseControls();
    /*
     * Both spellings of the path. Hono routes on the DECODED path (`c.req.path`), so
     * `/api/%61gents/<id>` reaches the agents route; a rule tested only against the raw URL would
     * never see it. The runtime, behind its own sub-app, reads the raw URL. A rule that matches
     * either one applies.
     */
    const raw = new URL(context.req.url).pathname;
    const paths = [...new Set([context.req.path, raw])];
    const path = paths[0] ?? raw;
    const method = context.req.method;
    const run =
      method === "POST"
        ? paths.map(runtimeRun).find((found) => found !== null)
        : undefined;
    const rule = controls
      ? run
        ? RUNTIME_RUN
        : GATED_ROUTES.find((candidate) =>
            paths.some((candidatePath) =>
              matches(candidate, method, candidatePath),
            ),
          )
      : undefined;
    if (!controls || !rule) return next();

    let refused: Response | undefined;
    const authenticated = await requireUser(context, async () => {
      let needed: Capability[];
      try {
        needed = await rule.needs(context);
        for (const capability of needed) {
          if (
            !(await controls.capabilityFor(context.var.actor.id, capability))
          ) {
            refused = context.json(
              { error: capabilityRefusal(capability), capability },
              403,
            );
            return;
          }
        }
      } catch (error) {
        console.error(
          JSON.stringify({
            type: "capability-check-failed",
            path,
            error: String(error),
          }),
        );
        refused = context.json(
          {
            error:
              "This deployment's enterprise controls could not be checked, so nothing was done.",
          },
          503,
        );
      }
    });
    // requireUser answered on its own: not signed in, or no role.
    if (authenticated instanceof Response) return authenticated;
    if (refused) return refused;

    // A suggestion runs the model as a run does, so the allowlist governs it the same way.
    if ((run?.action === "run" || run?.action === "suggest") && run.agentId)
      return governRun(context, next, run.agentId);
    return next();
  };
}

/**
 * The model allowlist, and one usage row per run with the model that served it.
 *
 * A built-in Bot runs on the deployment's configured model, so it is known before the run and a model
 * off the list refuses the run outright. A remote Bot chooses its own model; the stream is read as it
 * passes and the first model it names is recorded (`observed`), or `unknown` when it names none.
 */
async function governRun(
  context: Ctx,
  next: () => Promise<void>,
  agentId: string,
): Promise<Response | undefined> {
  const controls = enterpriseControls();
  if (!controls) {
    await next();
    return undefined;
  }
  const request = await body(context);
  const threadId =
    typeof request.threadId === "string" ? request.threadId : null;
  const runId = typeof request.runId === "string" ? request.runId : null;
  const actor = context.var.actor;

  let builtIn = false;
  try {
    const [row] = await controls.deps.database
      .select({ type: agents.type })
      .from(agents)
      .where(eq(agents.id, agentId))
      .limit(1);
    builtIn = row?.type === "built_in";
  } catch {
    builtIn = false;
  }
  const allowlist = controls.snapshot()?.settings.modelAllowlist;
  const isAllowed = (model: string) =>
    !allowlist?.enabled || allowlist.models.includes(model);
  const configured = builtIn ? controls.deps.builtInModel : undefined;

  const record = (
    model: string,
    source: "configured" | "observed" | "unknown",
    allowed: boolean,
  ) =>
    controls.store
      .recordModelUsage({
        userId: actor.id,
        agentId,
        threadId,
        runId,
        model,
        source,
        allowed,
      })
      .catch((error) =>
        console.error(
          JSON.stringify({
            type: "model-usage-write-failed",
            error: String(error),
          }),
        ),
      );

  if (configured && !isAllowed(configured)) {
    await record(configured, "configured", false);
    await recordAuditEvent(controls.deps.auditStore, {
      eventType: "model.refused",
      targetType: "agent",
      targetId: agentId,
      actorUserId: actor.id,
      payload: { model: configured, source: "configured" },
    }).catch(() => undefined);
    return context.json(
      {
        error: `This Bot uses ${configured}, which isn't an allowed model. Ask an admin to allow it.`,
      },
      403,
    );
  }

  await next();

  const response = context.res;
  if (!response.body || configured) {
    if (configured) await record(configured, "configured", true);
    return undefined;
  }

  // A remote Bot: read the model its stream names, without holding the stream back.
  const decoder = new TextDecoder();
  let seen = "";
  let found: string | undefined;
  const tap = new TransformStream<Uint8Array, Uint8Array>({
    transform(chunk, controller) {
      if (!found) {
        seen = (seen + decoder.decode(chunk, { stream: true })).slice(-8_192);
        found = MODEL_IN_STREAM.exec(seen)?.[1];
      }
      controller.enqueue(chunk);
    },
    flush() {
      const model = found ?? `remote:${agentId}`;
      const allowed = found ? isAllowed(found) : !allowlist?.enabled;
      void record(model, found ? "observed" : "unknown", allowed);
      if (!allowed) {
        void recordAuditEvent(controls.deps.auditStore, {
          eventType: "model.refused",
          targetType: "agent",
          targetId: agentId,
          actorUserId: actor.id,
          payload: {
            model,
            source: found ? "observed" : "unknown",
            note: "A remote Bot chooses its own model; this run was recorded against the allowlist after it streamed.",
          },
        }).catch(() => undefined);
      }
    },
  });
  context.res = new Response(response.body.pipeThrough(tap), response);
  return undefined;
}