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.

11.6 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import { accessFor, ServerRowAmbiguousError } from "../src/plugins/access";
import type { CatalogueEntry } from "../src/plugins/catalogue";
import { catalogueEntry, resolveServerUrl } from "../src/plugins/catalogue";

/**
 * How a server row is reached, resolved once.
 *
 * WHY THIS FILE IS THE IMPORTANT ONE. Three separate decisions used to be derived independently at
 * three call sites: which protocol dials, whose credential is spent, and whose name goes in the audit
 * row. Each derived it from a different field, and a Composio row — which has no catalogue entry at
 * all — answered every one of them wrongly by default: MCP would dial `composio://gmail` as if it
 * were an HTTP server, the credential branch would return no token and proceed, and the trail would
 * say the deployment made a call that ran in somebody's mailbox.
 *
 * One table of expected answers, one row per row-shape that exists. A new kind of server that nobody
 * adds a row for here is a test that fails, which is the property the old three-string-checks
 * arrangement could not have.
 */
describe("accessFor", () => {
  test("a Composio app is dialled through Composio, brokered, and reached as the person", () => {
    // No entry, because an app an operator enabled is a row and not something we shipped.
    expect(
      accessFor(
        {
          provenance: "composio",
          url: "composio://gmail",
          authScheme: "API_KEY",
        },
        null,
      ),
    ).toEqual({
      transport: "composio",
      credential: "brokered",
      reachedAs: "person",
      toolkit: "gmail",
    });
  });

  /**
   * AND A BROKERED APP THAT NEEDS NO CREDENTIAL IS REACHED AS THE DEPLOYMENT.
   *
   * CRITERION. A `composio` row whose recorded scheme is `NO_AUTH` answers `deployment`, while every
   * other brokered row — an unrecorded scheme included — still answers `person`.
   *
   * REASON. This answered `person` for every brokered row, because the only fields it had were the
   * provenance and the url and neither can tell. A `NO_AUTH` app has no account and no
   * `composio_connections` row: `connectionTokenFor` lets such a call through with no row at all and
   * `/servers/:id/connect` refuses to ever create one. So for Hacker News — Composio's own `NO_AUTH`
   * — every audit row wrote `reachedAs: <actorId>`, each one claiming the call ran in that person's
   * own account at the vendor: an account they never connected and cannot disconnect. That is
   * exactly what the field's docblock names as `deployment`: "a public endpoint reached with no
   * credential at all, where every person's call sees the same data and naming the asker would
   * assert an attribution that does not exist."
   *
   * THE UNRECORDED SCHEME IS THE THIRD ROW AND IS THE DELIBERATE DIRECTION. A brokered row whose
   * column was never written is far likelier to be a key or consent app than a no-auth one, and
   * `person` is the answer that does not under-attribute a call that really did run in somebody's
   * mailbox.
   */
  test.each([
    ["NO_AUTH", "deployment"],
    ["API_KEY", "person"],
    ["OAUTH2", "person"],
    [null, "person"],
  ] as const)(
    "a brokered row recording %s is reached as the %s",
    (authScheme, reachedAs) => {
      expect(
        accessFor(
          { provenance: "composio", url: "composio://hackernews", authScheme },
          null,
        ),
      ).toEqual({
        transport: "composio",
        credential: "brokered",
        reachedAs,
        toolkit: "hackernews",
      });
    },
  );

  test("a server somebody added by URL is MCP, on the deployment's own token", () => {
    expect(
      accessFor(
        {
          provenance: "custom",
          url: "https://mcp.example.com/mcp",
          authScheme: null,
        },
        null,
      ),
    ).toEqual({
      transport: "mcp",
      credential: "deployment-token",
      reachedAs: "deployment",
      toolkit: null,
    });
  });

  test("Notion is MCP, on the asking person's own grant", () => {
    const notion = catalogueEntry("notion");
    expect(notion).not.toBeNull();
    if (!notion) return;
    const notionUrl = `${notion.host}${notion.path}`;
    expect(
      accessFor(
        { provenance: "first-party", url: notionUrl, authScheme: null },
        notion,
      ),
    ).toEqual({
      transport: "mcp",
      credential: "person-oauth",
      reachedAs: "person",
      toolkit: null,
    });
  });

  test("Drive is its REST adapter, on the asking person's own grant", () => {
    const drive = catalogueEntry("google-drive");
    if (!drive) return;
    const driveUrl = `${drive.host}${drive.path}`;
    expect(
      accessFor(
        { provenance: "first-party", url: driveUrl, authScheme: null },
        drive,
      ),
    ).toEqual({
      transport: "google-drive-rest",
      credential: "person-oauth",
      reachedAs: "person",
      toolkit: null,
    });
  });

  test("Routines is in-process, with no credential, and acts as the person", () => {
    // Resolved the way a row is written rather than spelled by hand. The url this used to carry —
    // `openbot://routines` — is a scheme this codebase does not have anywhere, so the row shape the
    // test claims to cover was not the one being passed in.
    const routines = resolveServerUrl("routines");
    if (!routines) {
      throw new Error(
        "catalogue slug `routines` no longer resolves, so this test asserts nothing about it",
      );
    }
    expect(
      accessFor(
        { provenance: "first-party", url: routines.url, authScheme: null },
        routines.entry,
      ),
    ).toEqual({
      transport: "builtin-routines",
      credential: "none",
      reachedAs: "person",
      toolkit: null,
    });
  });

  test("an entry that needs no credential reaches nobody's account, so the trail says the deployment", () => {
    // Constructed here, because no catalogue slug is `auth: { kind: "none" }` yet. Whoever adds the
    // first one gets this answer, and `none` sharing a credential source with `builtin` must not
    // drag it to the person: a public endpoint answers everybody identically.
    const publicEntry: CatalogueEntry = {
      key: "public-thing",
      title: "Public Thing",
      vendor: "Somebody",
      summary: "A server that answers without being told who is asking.",
      // Scheme included, because every non-builtin entry carries one — pinned by
      // `plugin-catalogue.test.ts`. A bare host here made this stand for an entry the catalogue
      // would reject, and the row url below is joined from it so the two cannot drift apart.
      host: "https://mcp.example.com",
      path: "/mcp",
      auth: { kind: "none" },
      writeTools: [],
      docsUrl: "https://example.com/docs",
    };
    expect(
      accessFor(
        {
          provenance: "first-party",
          url: `${publicEntry.host}${publicEntry.path}`,
          authScheme: null,
        },
        publicEntry,
      ),
    ).toEqual({
      transport: "mcp",
      credential: "none",
      reachedAs: "deployment",
      toolkit: null,
    });
  });

  test("a curated entry wins over provenance, so a slug cannot be shadowed into a broker", () => {
    const notion = catalogueEntry("notion");
    // Thrown rather than returned. A missing slug here does not make the property hold, it makes
    // this test stop checking it — and the whole point of the test is that the protection is never
    // unguarded. Renaming the slug must break this file, not quietly empty it.
    if (!notion) {
      throw new Error(
        "catalogue slug `notion` is gone, so nothing here checks that an entry beats provenance",
      );
    }
    // A row whose provenance was tampered with must not turn a reviewed vendor into a brokered one,
    // and must not acquire an app at the broker either — a url edited to `composio://gmail` on a
    // curated slug is the same tampering by another field.
    //
    // `composio` is deliberately NOT the value used here. That one combination is now refused
    // outright rather than overruled — see the test below for why the entry cannot arbitrate it —
    // and this test is about every other value the column can hold, where the entry still decides.
    const shadowed = accessFor(
      { provenance: "custom", url: "composio://gmail", authScheme: null },
      notion,
    );
    expect(shadowed.transport).toBe("mcp");
    expect(shadowed.credential).toBe("person-oauth");
    expect(shadowed.toolkit).toBeNull();
  });

  test("a brokered row that carries a curated slug is refused, not dialled at the curated vendor", () => {
    const notion = catalogueEntry("notion");
    // Thrown for the reason the test above throws: a renamed slug must break this file rather than
    // quietly stop checking the protection it exists for.
    if (!notion) {
      throw new Error(
        "catalogue slug `notion` is gone, so nothing here checks that a colliding row is refused",
      );
    }
    // Two different rows produce this pair of arguments and nothing in them tells the two apart: a
    // curated Notion row whose provenance column was edited to `composio`, and a genuinely brokered
    // Notion app whose id happens to be the catalogue's slug. Entry-wins answered as though only
    // the first existed, so the second was dialled as MCP at Notion's pinned host on the
    // deployment's grant rather than the person's brokered connection. Refusing is the only answer
    // that is not wrong in one of the two worlds.
    expect(() =>
      accessFor(
        {
          provenance: "composio",
          url: "composio://notion",
          authScheme: "API_KEY",
        },
        notion,
      ),
    ).toThrow(ServerRowAmbiguousError);

    // The url is not what makes it ambiguous. The ID is, and `entry` is how this function is told
    // the id collided — so a brokered row pointed at some other app is refused on the same ground,
    // and nothing here can be satisfied by reading the url more carefully.
    expect(() =>
      accessFor(
        {
          provenance: "composio",
          url: "composio://gmail",
          authScheme: "API_KEY",
        },
        notion,
      ),
    ).toThrow(ServerRowAmbiguousError);

    // And the refusal is the collision's, not the provenance value's: the same row with no curated
    // entry behind its id resolves exactly as any other brokered row does.
    expect(
      accessFor(
        {
          provenance: "composio",
          url: "composio://notion",
          authScheme: "API_KEY",
        },
        null,
      ),
    ).toEqual({
      transport: "composio",
      credential: "brokered",
      reachedAs: "person",
      toolkit: "notion",
    });
  });

  test("which app a Composio row is comes from its url, not from its id", () => {
    // The id is a display key and the url is what the transport dials, so the url is what decides.
    // A row named `gmail` at `composio://slack` used to be checked against a Gmail connection and
    // then run as Slack, because three places derived this fact and none of them compared answers.
    expect(
      accessFor(
        {
          provenance: "composio",
          url: "composio://slack",
          authScheme: "API_KEY",
        },
        null,
      ).toolkit,
    ).toBe("slack");

    // No app in the url is no app at all. `store.ts` refuses a brokered row that reaches it, rather
    // than falling back to the id — see the narrowing throw beside its connection gate.
    expect(
      accessFor(
        {
          provenance: "composio",
          url: "https://example.com/mcp",
          authScheme: "API_KEY",
        },
        null,
      ).toolkit,
    ).toBeNull();
  });
});