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.

146 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import { createApp } from "../src/app";
import { DEV_ACTOR } from "../src/auth/dev-actor";
import { loadConfig } from "../src/config";
import { ServerRowAmbiguousError } from "../src/plugins/access";
import {
  type BrokerApp,
  type BrokerConnection,
  type BrokerField,
  BrokerRefusalError,
  schemeKind,
} from "../src/plugins/broker";
import type { AccountRef } from "../src/plugins/shared-accounts";
import {
  CatalogueEntryUnknownError,
  CustomServerRefusedError,
  PluginInvariantError,
  PluginRefusedError,
  type PluginStore,
  type ServerRecord,
} from "../src/plugins/store";
import { testEnvironment } from "./support/environment";

/**
 * The sentence a PERSON is shown where no broker is configured, written out rather than imported
 * from the class that makes it: a test that read it back from the source would pass whatever the
 * source said. Identical on both providers, and it names no vendor and no setting.
 */
const PERSON_UNCONFIGURED =
  "Connecting apps isn't set up yet, so nothing was asked. Ask an admin to set it up.";

/**
 * The handful of reads one route makes, typed against the store that really answers them.
 *
 * ONE CAST, IN ONE PLACE, WITH ITS INPUT CHECKED. A route test supplies four or five methods where
 * the real store has ninety, so something has to widen the handful into the parameter's type. Every
 * call site here used to spell that as `store as never`, and `never` widens the METHODS along with
 * the object: a stub whose `brokeredConnectionsFor` answered three fields where the real one
 * answers seven typechecked in silence, and every assertion above it then passed whether or not the
 * route carried the other four. `Partial<PluginStore>` is the same widening with the signatures
 * kept, so a stub that answers a shape the real store cannot is a compile error here rather than a
 * green test.
 *
 * AND THE FILLERS BELOW HAD TO GO WITH IT, which is the half that looks unrelated and is not.
 * `createApp` takes thirty positional stores, and the spread that skipped to the fifteenth was
 * an array of unknown LENGTH — so TypeScript had no idea which parameter the store landed on and
 * checked it against the next one in the signature. Typing the store without fixing that only moves
 * the silence: see {@link UP_TO_PLUGIN_STORE}.
 */
function pluginStore(reads: Partial<PluginStore>): PluginStore {
  // Every real store is built with the provider its rows belong to; the routes read it and never
  // guess one, so a stand-in says which deployment it is standing in for.
  return { brokerProvider: "composio", ...reads } as PluginStore;
}

/**
 * `createApp`'s positions 4-14, which no test on this surface supplies.
 *
 * A FIXED-LENGTH TUPLE RATHER THAN `Array.from({ length: 11 }) as never[]`, which is what every
 * call site here spread before. An array whose length TypeScript does not know tells it nothing
 * about which parameter the argument AFTER it lands on, so the plugin store was being checked
 * against position 5 — `credentialService` — and the `as never` on it is the only reason that was
 * quiet. With the length written down, the store is checked against `pluginStore`, which is the
 * whole point of typing it at all.
 */
const UP_TO_PLUGIN_STORE = [
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
] as const;

/** `createApp`'s positions 16-29, between the plugin store and the broker. See {@link UP_TO_PLUGIN_STORE}. */
const UP_TO_BROKER = [
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
] as const;

/** One row of what {@link PluginStore.connectionsFor} answers: this deployment's own vault. */
type HeldConnection = Awaited<
  ReturnType<PluginStore["connectionsFor"]>
>[number];

/**
 * One row of what {@link PluginStore.brokeredConnectionsFor} answers.
 *
 * Spelled as the store's own return type rather than re-typed here, because the four fields this
 * read adds over {@link HeldConnection} — `verified`, `verifiedAt`, `probe`, `checkable` — are the
 * whole of the verification surface, and a fixture free to omit them is a fixture that cannot tell
 * whether the route carries them.
 */
type BrokeredConnection = Awaited<
  ReturnType<PluginStore["brokeredConnectionsFor"]>
>[number];

/**
 * A server row as the store really answers one, from the two columns a test cares about.
 *
 * EVERY FIELD BECAUSE THE STORE ANSWERS EVERY FIELD. The stubs here used to hand back `{ id, url }`,
 * which is not a row any deployment can produce — and a route reaching for `authScheme` or `tools`
 * on it would find `undefined` and behave in a way no real store could reproduce. The values are
 * the empty ones on purpose: nothing on these routes reads them, and a fixture that invented
 * interesting ones would be inviting an assertion about a fact it made up.
 */
function serverRecord(row: { id: string; url: string }): ServerRecord {
  return {
    id: row.id,
    title: row.id,
    logo: null,
    vendor: "composio",
    url: row.url,
    summary: "",
    docsUrl: "",
    provenance: "custom",
    hasCredential: false,
    toolsRefreshedAt: null,
    lastError: null,
    addedBy: null,
    dynamicClient: false,
    skippedTools: [],
    authScheme: null,
    accountMode: null,
    sharedVendorConnected: false,
    ownerGrants: "admin",
    ownerGrantsChosen: null,
    tools: [],
    withdrawn: [],
  };
}

/**
 * What a refused add looks like to the administrator who made it.
 *
 * The store's refusals are tested where they are decided. What is worth pinning here is the mapping,
 * because an unmapped throw leaves the route on its default path: the refusal becomes a 500, the
 * screen says something went wrong, and a correctable mistake reads as a broken deployment. The
 * curated route mapped one refusal and not the other, which is exactly the shape that is invisible
 * until somebody hits it.
 */

const ADMIN = {
  id: "admin-1",
  email: "[email protected]",
  name: "An Administrator",
  image: null,
};

function appWith(
  addServer: () => Promise<never>,
  role: "admin" | "user" = "admin",
) {
  const store = pluginStore({
    addServer,
    // Every read the plugins surface makes on its way to the route under test.
    listServers: async () => [],
    listSkills: async () => [],
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    { rolesForUser: async () => [role] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
  );

  return (body: unknown) =>
    app.request("http://openbot.test/api/plugins/servers", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    });
}

describe("adding a curated server", () => {
  test("a refused credential comes back as a refusal with its reason", async () => {
    const request = appWith(async () => {
      throw new CustomServerRefusedError(
        "That is not a credential this server can use. Add the server's own token instead.",
      );
    });

    const response = await request({
      key: "google-drive",
      credentialId: "11111111-1111-1111-1111-111111111111",
    });

    expect(response.status).toBe(400);
    expect(await response.json()).toEqual({
      error:
        "That is not a credential this server can use. Add the server's own token instead.",
    });
  });

  test("an unknown catalogue key still comes back the same way", async () => {
    const request = appWith(async () => {
      throw new CatalogueEntryUnknownError("nope");
    });

    expect((await request({ key: "nope" })).status).toBe(400);
  });

  test("a row the deployment cannot resolve comes back with its sentence", async () => {
    /*
     * ADDING REFRESHES, which is what puts this fault on this route.
     *
     * `addServer` asks the vendor what it offers before it answers — deliberately, so a bad
     * credential is reported now rather than the first time a Bot uses one — so everything
     * `refreshTools` raises arrives here as well: a vendor listing one action twice, a query of
     * ours failing, a row whose two columns contradict each other. Unmapped, all of it left the
     * route on the default path and the admin page said "That did not work", while the SAME fault
     * on the refresh button said which row and what to do about it.
     */
    const sentence =
      "notion: the actions this app listed were not stored, so what it already had is unchanged.";
    const request = appWith(async () => {
      throw new PluginInvariantError(sentence);
    });

    const response = await request({ key: "notion" });

    expect(response.status).toBe(409);
    expect(await response.json()).toEqual({ error: sentence });
  });

  test("a failure that is not a refusal is not dressed up as one", async () => {
    // The must-not case. Mapping every throw to 400 would tell an administrator to correct their
    // input when the database is down, and would hide a real fault behind a message about
    // credentials.
    const request = appWith(async () => {
      throw new Error("the database is unreachable");
    });

    expect((await request({ key: "google-drive" })).status).toBe(500);
  });

  test("somebody who is not an administrator cannot add one at all", async () => {
    const request = appWith(async () => {
      throw new Error("the store must not be reached");
    }, "user");

    expect((await request({ key: "google-drive" })).status).toBe(403);
  });
});

/**
 * What a refresh that cannot be resolved at all looks like to the administrator who pressed it.
 *
 * CRITERION. A contradiction between two of this deployment's own columns comes back with a body
 * that names the row and says what to correct, on this route and only on this route.
 *
 * REASON. `ServerRowAmbiguousError` was mapped nowhere, so it left the route on the framework's
 * default path: a 500 whose body is not JSON, which the admin client turns into its fallback
 * sentence — "That did not work" — having found no `error` field to read. The one refusal that
 * names exactly which row is wrong was the one an operator could not see, while the same sentence
 * was reaching a model on the tool-call path. This route is admin-gated, which is what makes
 * showing it here the right answer and showing it anywhere else the wrong one.
 */
function refreshApp(
  refreshTools: () => Promise<never>,
  role: "admin" | "user" = "admin",
) {
  const store = pluginStore({
    refreshTools,
    // Every read the plugins surface makes on its way to the route under test.
    listServers: async () => [],
    listSkills: async () => [],
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    { rolesForUser: async () => [role] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
  );

  return () =>
    app.request("http://openbot.test/api/plugins/servers/notion/refresh", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: "{}",
    });
}

describe("refreshing a server that cannot be resolved", () => {
  test("the administrator is told which row and what to do about it", async () => {
    const sentence =
      "notion is a server this deployment ships an entry for, and a row with that id says its " +
      "provenance is composio. Rename it, or correct its provenance.";
    const request = refreshApp(async () => {
      throw new ServerRowAmbiguousError(sentence);
    });

    const response = await request();

    // 409 rather than 500: nothing broke and nothing about the request was malformed. Two rows
    // disagree, and the request cannot be answered until one of them changes.
    expect(response.status).toBe(409);
    // A body at all is the fix. Unmapped, this was a 500 carrying no JSON, and the page said
    // "That did not work" because that is what it says when it finds no message.
    expect(await response.json()).toEqual({ error: sentence });
  });

  test("a failed query comes back as the reason, never as the statement", async () => {
    /*
     * The shape drizzle throws: `Failed query:` plus the whole statement, then `params:` and every
     * value bound to it, with the driver's own error on `cause`. It is on the same shelf as the
     * refusals above — not a vendor's doing, not the asker's to act on — so this route is where an
     * operator is told about it, and it is the one member of that shelf whose `message` must not be
     * what they are told.
     */
    const request = refreshApp(async () => {
      throw Object.assign(
        new Error(
          'Failed query: select "credential_id" from "mcp_user_credentials" where "user_id" = $1 params: someone',
        ),
        {
          query: 'select "credential_id" from "mcp_user_credentials"',
          params: ["someone"],
          cause: new Error("canceling statement due to statement timeout"),
        },
      );
    });

    const response = await request();
    expect(response.status).toBe(409);
    const body = (await response.json()) as { error?: string };
    // The reason, which is what an administrator can act on.
    expect(body.error).toContain(
      "canceling statement due to statement timeout",
    );
    // And none of the query. This route answers an administrator, but the browser it answers is
    // still on somebody's laptop and the sentence still ends up in a screenshot and a ticket.
    expect(body.error).not.toContain("Failed query");
    expect(body.error).not.toContain("params:");
    expect(body.error).not.toContain("mcp_user_credentials");
  });

  test("a failure that is not one of ours is still not dressed up as one", async () => {
    // The must-not case, the same one the add route above carries: a database that is down is not
    // a row an administrator can go and correct, and answering 409 would send them to do it.
    const request = refreshApp(async () => {
      throw new Error("the database is unreachable");
    });

    expect((await request()).status).toBe(500);
  });

  test("somebody who is not an administrator cannot press it at all", async () => {
    const request = refreshApp(async () => {
      throw new Error("the store must not be reached");
    }, "user");

    // Which is what makes showing the sentence above safe: nobody else reaches this route.
    expect((await request()).status).toBe(403);
  });
});

/**
 * Granting one Bot to another, through the API an administrator actually has.
 *
 * The grant table gained a `bot` kind and the store learned it, but these two endpoints did not.
 * Revoke rejected it outright, so enabling the capability meant writing a row by hand and revoking
 * it was not possible at all — while the design says a revoked grant applies to the very next hop.
 *
 * `kind` also arrives in a JSON body, so a type annotation on it is a comment. It is checked here.
 */
function grantsApp(
  role: "admin" | "user" = "admin",
  canHandOn: (agentId: string) => boolean | undefined = (agentId) => {
    // Undefined is "no such Bot", which is what the store answers for one nobody registered.
    if (agentId === "never-registered") return undefined;
    return true;
  },
) {
  /**
   * Every write that reached the store, in the shape the store really takes.
   *
   * ALL FOUR ARGUMENTS, WHICH IS NOT A TIDINESS. `grant` and `revoke` take `(kind, ref, agentId,
   * by)`, and this stub used to drop the second half: the row is written against the BOT, so a
   * route that passed the wrong `agentId` would put one Bot's capability on another's row — the
   * grant tested here lets one Bot spend another's model calls and reach whatever that Bot may
   * reach — and `by` is the only name the audit trail has for who did it. Neither was asserted
   * anywhere, so a route that granted the right thing to the wrong Bot under nobody's name passed
   * every test in this file.
   *
   * `by` IS THE SESSION'S AND NEVER THE REQUEST'S, which is the point of asserting it at all: the
   * body below carries a Bot and a ref and no actor, and the trail has to name the administrator
   * whose session made the call.
   */
  const calls: Array<{
    verb: string;
    kind: string;
    ref: string;
    agentId: string;
    by: string;
  }> = [];
  const store = pluginStore({
    listServers: async () => [],
    listSkills: async () => [],
    grant: async (kind: string, ref: string, agentId: string, by: string) => {
      calls.push({ verb: "grant", kind, ref, agentId, by });
    },
    revoke: async (kind: string, ref: string, agentId: string, by: string) => {
      calls.push({ verb: "revoke", kind, ref, agentId, by });
    },
    skillOwner: async () => null,
    agentOwner: async () => null,
    agentCanHandOn: async (agentId: string) => canHandOn(agentId),
    agentIsRegistered: async (agentId: string) =>
      agentId !== "never-registered",
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    { rolesForUser: async () => [role] },
    ...UP_TO_PLUGIN_STORE,
    store,
  );

  return { calls, app };
}

describe("granting one Bot to another", () => {
  test("an administrator can grant it", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "knowledge",
          agentId: "assistant",
        }),
      },
    );

    expect(response.status).toBe(200);
    // The Bot named in the body got it, and the trail names the session's administrator: the row is
    // written against the Bot, and `by` is all anybody reading the trail later has. See
    // {@link calls}.
    expect(calls).toEqual([
      {
        verb: "grant",
        kind: "bot",
        ref: "knowledge",
        agentId: "assistant",
        by: ADMIN.email,
      },
    ]);
  });

  /*
   * The half that was missing entirely. "Nothing about who may address whom is cached in a process"
   * is only true if there is a way to stop it.
   */
  test("and revoke it again", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants?kind=bot&ref=knowledge&agentId=assistant",
      { method: "DELETE" },
    );

    expect(response.status).toBe(200);
    // Off the Bot the query names, under the session's administrator — the same two facts the grant
    // above asserts, and here they arrive in a query string rather than a body.
    expect(calls).toEqual([
      {
        verb: "revoke",
        kind: "bot",
        ref: "knowledge",
        agentId: "assistant",
        by: ADMIN.email,
      },
    ]);
  });

  /*
   * It lets one Bot spend another's model calls, wake its computer and reach whatever that Bot may
   * reach. That is not an instruction somebody attaches to a coworker they own.
   */
  test("somebody who is not an administrator cannot", async () => {
    const { calls, app } = grantsApp("user");

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "knowledge",
          agentId: "assistant",
        }),
      },
    );

    expect(response.status).toBe(403);
    expect(await response.json()).toEqual({
      error: "Only an admin can choose which Bots hand work to another Bot.",
    });
    expect(calls).toEqual([]);
  });

  test("a kind nobody defined is refused rather than written", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "anything",
          ref: "x",
          agentId: "assistant",
        }),
      },
    );

    expect(response.status).toBe(400);
    expect(calls).toEqual([]);
  });
});

/**
 * A grant that could never do anything.
 *
 * A remote Bot calls the deployment's signed coordination callback to hand work on. Its grant is
 * governed in exactly the same way as one held by a Bot running here.
 */
describe("granting a hop to a Bot that runs somewhere else", () => {
  test("can be granted a coworker through the governed callback", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "knowledge",
          agentId: "at-an-endpoint",
        }),
      },
    );

    expect(response.status).toBe(200);
    expect(calls).toEqual([
      {
        verb: "grant",
        kind: "bot",
        ref: "knowledge",
        agentId: "at-an-endpoint",
        by: ADMIN.email,
      },
    ]);
  });

  test("a Bot nobody has heard of is refused too", async () => {
    // Undefined is "no such Bot", which must not read as "runs somewhere else" or as permission.
    const { calls, app } = grantsApp("admin", () => undefined);

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "knowledge",
          agentId: "never-registered",
        }),
      },
    );

    expect(response.status).toBe(403);
    expect((await response.json()).error).toBe("There is no such Bot.");
    expect(calls).toEqual([]);
  });

  test("a Bot that does run here is granted as before", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "knowledge",
          agentId: "general-assistant",
        }),
      },
    );

    expect(response.status).toBe(200);
    // A DIFFERENT BOT FROM THE TEST ABOVE, and the assertion says so: this case is about which Bot
    // the route acted on, so a stub that recorded only the kind and the ref would make its two
    // expectations identical and neither of them about the name that differs.
    expect(calls).toEqual([
      {
        verb: "grant",
        kind: "bot",
        ref: "knowledge",
        agentId: "general-assistant",
        by: ADMIN.email,
      },
    ]);
  });
});

/**
 * What a refusal tells somebody who is not an administrator.
 *
 * This route only requires a signed-in user. Checking whether a Bot exists, and whether it runs
 * here, before checking the role handed out three distinguishable 403s and turned the refusal into
 * an oracle for other people's private Bots — the exact property `handoff.ts` collapses on purpose.
 */
describe("what a bot grant refusal reveals", () => {
  const refusalFor = async (
    agentId: string,
    role: "admin" | "user",
    ref = "knowledge",
  ) => {
    const { calls, app } = grantsApp(role);
    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ kind: "bot", ref, agentId }),
      },
    );
    return { status: response.status, body: await response.json(), calls };
  };

  test("a non-administrator gets one answer, whatever the Bot is", async () => {
    const said = new Set<string>();
    for (const agentId of [
      "general-assistant",
      "at-an-endpoint",
      "never-registered",
    ]) {
      const { status, body, calls } = await refusalFor(agentId, "user");
      expect(status).toBe(403);
      expect(calls).toEqual([]);
      said.add(body.error);
    }
    // One sentence for all three, so nothing distinguishes "exists" from "does not".
    expect(said.size).toBe(1);
    expect([...said][0]).toBe(
      "Only an admin can choose which Bots hand work to another Bot.",
    );
  });

  test("an administrator still gets the reason", async () => {
    expect((await refusalFor("at-an-endpoint", "admin")).status).toBe(200);
    expect((await refusalFor("never-registered", "admin")).body.error).toBe(
      "There is no such Bot.",
    );
  });

  /*
   * The target is bare text with no foreign key. A typo stored happily, `message_bot` was offered,
   * and every hop then refused as not-granted.
   */
  test("a target nobody has heard of is refused", async () => {
    const { status, body, calls } = await refusalFor(
      "general-assistant",
      "admin",
      "never-registered",
    );
    expect(status).toBe(403);
    expect(body.error).toContain("no Bot called never-registered");
    expect(calls).toEqual([]);
  });
});

/*
 * The desk refuses a self-hop outright — "a Bot cannot hand work to itself" — so a grant of a Bot to
 * itself is dead the moment it is written, and reads as configured.
 */
describe("granting a Bot itself", () => {
  test("is refused rather than stored", async () => {
    const { calls, app } = grantsApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/grants",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          kind: "bot",
          ref: "general-assistant",
          agentId: "general-assistant",
        }),
      },
    );

    expect(response.status).toBe(403);
    expect((await response.json()).error).toContain("cannot be granted itself");
    expect(calls).toEqual([]);
  });
});

/**
 * The app directory an administrator picks a brokered app out of.
 *
 * TWO THINGS ARE BEING PINNED, and they are the two a reader would assume the vendor does for us.
 * The search is ours, because `@composio/core` forwards only category, managed_by, sort_by, cursor
 * and limit and drops a search term without saying so — a forwarded term comes back as an
 * unfiltered first page, which looks exactly like a result. And the slug on a POST is checked
 * against the directory that was just read, because that slug becomes the url every future call
 * for the app runs against.
 *
 * The no-broker answer is a 503 naming the setting rather than an empty list: an empty directory
 * and an absent one are different facts, and only one of them has a remedy.
 */
const DIRECTORY: BrokerApp[] = [
  {
    slug: "slack",
    name: "Slack",
    description: "Post messages and read channels.",
    logo: "https://example.com/slack.svg",
    categories: ["communication"],
    actionCount: 63,
    classifiedCount: null,
    permissionCount: null,
    scopedActionCount: null,
    connection: { kind: "consent" },
  },
  {
    slug: "gmail",
    name: "Gmail",
    description: "Read and send mail.",
    logo: null,
    categories: ["communication"],
    actionCount: 24,
    classifiedCount: null,
    permissionCount: null,
    scopedActionCount: null,
    connection: { kind: "consent" },
  },
  {
    slug: "linear",
    name: "Linear",
    description: "Track issues.",
    logo: null,
    categories: ["project-management"],
    actionCount: 18,
    classifiedCount: null,
    permissionCount: null,
    scopedActionCount: null,
    connection: { kind: "consent" },
  },
  {
    /*
     * The fourth app is one Composio publishes and this deployment cannot drive: connecting it
     * wants an OAuth application registered by whoever runs the deployment, and there is nowhere
     * here to keep one. Fifty-six of the catalogue's apps are this, which is why the fixture
     * carries one rather than pretending the catalogue is uniform.
     */
    slug: "docusign",
    name: "DocuSign",
    description: "Send documents for signature.",
    logo: null,
    categories: ["documents"],
    actionCount: 31,
    classifiedCount: null,
    permissionCount: null,
    scopedActionCount: null,
    connection: {
      kind: "unsupported",
      reason:
        "DocuSign needs an OAuth application registered by whoever runs this deployment, and this deployment holds no place to put its own OAuth client for a brokered app.",
    },
  },
];

function directoryApp(
  /** Null is a deployment with no COMPOSIO_API_KEY, which is the shipped default. */
  listApps: (() => Promise<typeof DIRECTORY>) | null = async () => DIRECTORY,
  role: "admin" | "user" = "admin",
  /** What this deployment has already added, which is where `enabled` comes from. */
  servers: Array<{ id: string; url: string }> = [],
  /**
   * How enabling fails, for the cases that are about the failing half. Null is the store that
   * works: it records the call and answers a row. Enabling is where the second half of this
   * surface's failures are decided, and none of them could be tested while the only store here
   * succeeded.
   */
  enable: (() => Promise<never>) | null = null,
  /**
   * How the read of what is already enabled fails, for the case that is about that read. Null is
   * the store that works. It sits outside the `try` the vendor call is wrapped in, which is what
   * made it the one store call on this route that nothing answered for.
   */
  failServerUrls: (() => Promise<never>) | null = null,
) {
  const added: Array<{
    slug: string;
    title: string;
    by: string;
    connection: BrokerConnection;
  }> = [];
  /**
   * Which of this store's ID-BEARING reads the route made, in order.
   *
   * THE FIXTURE'S IDS WERE UNREACHABLE WITHOUT THIS, AND AN UNREACHABLE ID IS AN ASSERTION THAT
   * CANNOT FAIL. The rows below have always carried an id that names a different app than their
   * url, to say that `enabled` is decided by the url — but the only method this store exposed was
   * `serverUrls`, which drops the id on the way out, so the route had nothing to read wrongly and
   * the "not by the row's id" half of that test was true of any implementation whatsoever.
   * `listServers` is the read that DOES carry ids, so offering it here is what makes the wrong
   * implementation expressible: a route resolving an app off `id` marks the wrong one enabled and
   * leaves its name in this list.
   */
  const idReads: string[] = [];
  const store = pluginStore({
    // Every read the plugins surface makes on its way to the route under test. The directory asks
    // for urls and is handed urls; `listServers` is here to be left alone. See {@link idReads}.
    serverUrls: async () =>
      failServerUrls ? failServerUrls() : servers.map((server) => server.url),
    listServers: async () => {
      idReads.push("listServers");
      return servers.map(serverRecord);
    },
    listSkills: async () => [],
    addBrokeredApp: async (input: {
      slug: string;
      title: string;
      by: string;
      connection: BrokerConnection;
    }) => {
      if (enable) return enable();
      added.push(input);
      return serverRecord({
        id: `composio-${input.slug}`,
        url: `composio://${input.slug}`,
      });
    },
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    { rolesForUser: async () => [role] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
    // Positions 16-29 are the stores after it; the broker is 30, `composio`.
    ...UP_TO_BROKER,
    listApps ? ({ broker: { listApps } } as never) : undefined,
  );

  return { added, app, idReads };
}

describe("the Composio directory", () => {
  test("a deployment with no broker is told which setting to set", async () => {
    const { app } = directoryApp(null);

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );

    // 503 rather than `{ apps: [] }`. An empty directory and an absent one are different facts,
    // and a page shown the empty one draws "no apps available" over a deployment that simply has
    // no key.
    expect(response.status).toBe(503);
    expect((await response.json()).error).toContain("COMPOSIO_API_KEY");
  });

  test("a search term filters the directory here, not at the vendor", async () => {
    /*
     * `@composio/core` forwards only category, managed_by, sort_by, cursor and limit, and silently
     * drops anything else — so a term handed to their client comes back as an unfiltered first
     * page that reads as a result. The filter is ours, over slug, name and description.
     */
    const { app } = directoryApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps?q=sla",
    );

    expect(response.status).toBe(200);
    expect(
      (await response.json()).apps.map((app: { slug: string }) => app.slug),
    ).toEqual(["slack"]);
  });

  test("an app this deployment could not connect is never offered", async () => {
    /*
     * COMPOSIO PUBLISHES 1540 APPS AND FIFTY-SIX OF THEM CANNOT BE CONNECTED FROM HERE: they want
     * an OAuth client registered by whoever runs the deployment, and this deployment holds nowhere
     * to put one. Listed, they are a row an administrator presses Add on and meets the vendor's
     * refusal at — a dead end offered as a choice. Hidden in the route rather than asked of the
     * vendor, because which apps are connectable is a fact about what this deployment can drive,
     * not about what Composio publishes.
     */
    const { app } = directoryApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );

    expect(response.status).toBe(200);
    const slugs = (await response.json()).apps.map(
      (entry: { slug: string }) => entry.slug,
    );
    expect(slugs).not.toContain("docusign");
    expect(slugs).toEqual(["slack", "gmail", "linear"]);

    // And the search branch reads the same filtered list, not the raw directory. Searching is what
    // an administrator does to a 1540-app picker, so a term that names the unconnectable app is
    // the request most likely to hand one back.
    const searched = await app.request(
      "http://openbot.test/api/plugins/composio/apps?q=docu",
    );
    expect((await searched.json()).apps).toEqual([]);
  });

  test("an app is enabled by the url of the row, not by the row's id", async () => {
    /*
     * Which app a row is comes off its url and only off its url, because that is where the
     * transport reads it from. An id read as an app name is a different question wearing the same
     * answer's clothes, and it works right up until somebody renames a row.
     *
     * SO THE ROW BELOW DISAGREES WITH ITSELF, AND NAMES A SECOND APP THAT IS REALLY IN THE
     * DIRECTORY. Its id reads as Gmail and its url is Slack's — which is a renamed Slack row, and
     * the only fixture that can tell the two readings apart. The id used to be
     * `an-id-nobody-should-read`, a string no implementation would resolve to any app at all: under
     * it, a route keyed on ids would have marked NOTHING enabled and the assertions below would
     * have read exactly as they do now. The test's own name was the only place the property lived.
     *
     * AND THE ID-BEARING READ IS ASSERTED UNMADE, which is the structural half the route's comment
     * claims: `serverUrls` hands over urls and nothing else, so there is no id here to read by
     * mistake. That is a claim about which call is made, and only a store offering the other call
     * can check it. See `directoryApp`'s `idReads`.
     */
    const { app, idReads } = directoryApp(undefined, "admin", [
      { id: "composio-gmail", url: "composio://slack" },
    ]);

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );

    const apps = (await response.json()).apps as Array<{
      slug: string;
      enabled: boolean;
    }>;
    expect(apps.find((entry) => entry.slug === "slack")?.enabled).toBe(true);
    expect(apps.find((entry) => entry.slug === "gmail")?.enabled).toBe(false);
    expect(idReads).toEqual([]);
  });

  test("a slug the directory never answered with is refused", async () => {
    /*
     * THE VALIDATION IS THE WHOLE ROUTE. The slug becomes `composio://<slug>`, which is the url
     * every future call for the app is resolved against, so a slug nobody listed is a row pointing
     * at an app that does not exist — added, grantable, and dead at the first call.
     */
    const { added, app } = directoryApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "not-an-app" }),
      },
    );

    expect(response.status).toBe(400);
    expect(added).toEqual([]);
  });

  test("an app this deployment cannot connect is refused before the store", async () => {
    /*
     * THE ASYMMETRY THIS CLOSES. The GET hides every `unsupported` app, so an administrator
     * cannot press Add on one through the picker; the POST validates against the unfiltered
     * catalogue, so a request naming one by hand walks straight past that. What it would reach is
     * `addBrokeredApp`, whose `schemeFor` records `null` for an unsupported app — and `null` on
     * that column is read everywhere else as "not a brokered row at all". So the row this would
     * write is one that lies about its own kind.
     *
     * The derivation's own `reason` is the answer, because it is the sentence that names what is
     * missing for THIS app, and 503 because it is a refusal this deployment authored — the same
     * status `brokerRefusal` gives one raised a layer down, and not a 400, which would read as a
     * malformed request about an app Composio really does publish.
     */
    const { added, app } = directoryApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "docusign" }),
      },
    );

    expect(response.status).toBe(503);
    expect(((await response.json()) as { error: string }).error).toContain(
      "OAuth application registered by whoever runs this deployment",
    );
    // AND THE STORE WAS NEVER ASKED, which is the whole point of the guard: the misleading row is
    // not written and then answered around, it is never reachable.
    expect(added).toEqual([]);
  });

  test("an app the directory does list is added", async () => {
    const { added, app } = directoryApp();

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "slack" }),
      },
    );

    expect(response.status).toBe(201);
    // The title comes off the directory entry, never off the request: the caller chose an app, not
    // a name for it.
    // And so does the connection: how an app connects is read off the catalogue row that was
    // chosen, not derived a second time on the way to the store.
    expect(added).toEqual([
      {
        slug: "slack",
        title: "Slack",
        logo: "https://example.com/slack.svg",
        by: ADMIN.email,
        connection: { kind: "consent" },
      },
    ]);
  });

  test("somebody who is not an administrator sees none of it", async () => {
    // Enabling an app writes every one of its actions in front of a model, which is the same
    // decision as adding an MCP server and stays an administrator's.
    const { added, app } = directoryApp(undefined, "user");

    expect(
      (await app.request("http://openbot.test/api/plugins/composio/apps"))
        .status,
    ).toBe(403);

    const posted = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "slack" }),
      },
    );
    expect(posted.status).toBe(403);
    expect(added).toEqual([]);
  });

  test("a vendor failure is Composio's own sentence on both doors, not a 500", async () => {
    /*
     * THE WRONG KEY IS WHERE THIS FAILS FIRST, and nothing on either route caught anything: the
     * administrator who had just pasted a key was shown a bare 500 and the vendor's whole response
     * object went to the console, headers and trace id included.
     *
     * Both routes make the same call, so both answer in the same words. The POST is the one that
     * mattered most: it is pressed by somebody who has just set the key and is waiting to hear
     * whether it works.
     */
    const failing = async (): Promise<typeof DIRECTORY> => {
      throw WRONG_KEY;
    };

    const listed = await directoryApp(failing).app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );
    const added = await directoryApp(failing).app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "slack" }),
      },
    );
    const listedBody = await listed.text();
    const addedBody = await added.text();

    expect(listed.status).toBe(502);
    expect(added.status).toBe(502);
    expect(JSON.parse(listedBody).error).toBe("Invalid API key provided.");
    expect(JSON.parse(addedBody).error).toBe("Invalid API key provided.");
    expect(listedBody).not.toContain("req_a_trace_id_nobody_should_read");
    expect(addedBody).not.toContain("req_a_trace_id_nobody_should_read");
  });

  test("a failure the vendor did not explain names the setting to check", async () => {
    // Null from `vendorSentence` leaves the route to say something itself, and what it says is the
    // one thing an operator meeting this can act on: the key. Never the thrown object's own text,
    // which on this path is as likely to be a stack frame as a sentence.
    const { app } = directoryApp(async () => {
      throw new Error("fetch failed");
    });

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );

    expect(response.status).toBe(502);
    const refusal = (await response.json()).error as string;
    expect(refusal).toContain("COMPOSIO_API_KEY");
    expect(refusal).not.toContain("fetch failed");
  });

  test("a refusal while enabling reaches the administrator who pressed the button", async () => {
    /*
     * THE DEAD BUTTON. An administrator pressed Add and Composio answered "Default auth config not
     * found for toolkit linear_mcp. Composio does not have managed credentials for this toolkit." —
     * everything needed to explain the failure, and a step somebody here can take. The route mapped
     * that sentence for the directory read and for nothing else, so a refusal out of enabling left
     * as an unhandled throw: a bodyless 500, and the browser's own "That app could not be added."
     * over the top of a reason that existed.
     *
     * 503 with the refusal's own words, because a refusal this deployment authored is not a third
     * party being down and the generic sentence would send an administrator to check a key that is
     * fine.
     *
     * A CONNECTABLE APP IS PRESSED HERE, and it has to be. The fixture's `unsupported` row would
     * be the natural choice — the refusal below is the one DocuSign would really raise — but the
     * route now refuses an unsupported app itself, before the store is called at all, so pressing
     * that row would answer 503 with the catalogue's own sentence and never reach the failing
     * store this case exists to exercise. Linear is connectable, and a refusal can still come back
     * out of enabling it: Composio holding no managed credentials is a fact about the vendor's
     * side, not about what this deployment can drive.
     */
    const { app } = directoryApp(undefined, "admin", [], async () => {
      throw new BrokerRefusalError(
        "Linear was not enabled: Composio holds no managed credentials for this toolkit, so there is no auth config for this deployment to create.",
      );
    });

    const said: string[] = [];
    const realError = console.error;
    console.error = (...args: unknown[]) => {
      said.push(args.map(String).join(" "));
    };

    try {
      const response = await app.request(
        "http://openbot.test/api/plugins/composio/apps",
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ slug: "linear" }),
        },
      );

      expect(response.status).toBe(503);
      expect(((await response.json()) as { error: string }).error).toContain(
        "no managed credentials for this toolkit",
      );
    } finally {
      console.error = realError;
    }

    // AND NOTHING ON THE CONSOLE. The log below this branch is for the failure whose explanation
    // cannot be read off the response; this refusal's explanation is the response. Widen that
    // guard to fire on every refusal — or add a third sentence source and leave the guard out of
    // step with it — and an operator gets a console line per dead button, about failures they can
    // already read in the browser.
    expect(
      said.find((line) => line.includes("composio-app-not-enabled")),
    ).toBeUndefined();
  });

  test("a deployment fault while enabling is still a 409 in its own words", async () => {
    /*
     * WHAT THE BROKER MAPPING MUST NOT SWALLOW. The catch on this route now ends in
     * `brokerRefusal`, and where that mapping sits decides the answer for three whole classes of
     * failure: the deployment faults — an ambiguous server row, a broken invariant, a query this
     * database refused — are recognised one branch ABOVE it and answered 409 with the sentence
     * they carry. Move the broker mapping up and every one of them turns into a 502 saying
     * "Composio said nothing about why" about a failure Composio had no part in, which would send
     * an administrator to check a key that is fine and hide the row they actually have to fix.
     *
     * Nothing else on this route pins that ordering, so this is the case that stops a later reader
     * tidying the branches into the wrong sequence.
     */
    const { app } = directoryApp(undefined, "admin", [], async () => {
      throw new ServerRowAmbiguousError(
        "Two rows claim the url composio://slack, and this deployment cannot tell which one an enable belongs to.",
      );
    });

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "slack" }),
      },
    );

    expect(response.status).toBe(409);
    const refusal = ((await response.json()) as { error: string }).error;
    expect(refusal).toContain("Two rows claim the url");
    expect(refusal).not.toContain("Composio said nothing about why");
  });

  test("a failure nobody explained is a 502 in the route's own words", async () => {
    /*
     * THE LAST CLASS ON THIS ROUTE, and the only one that gets logged. A refusal this deployment
     * authored carries its own sentence, and a sentence Composio wrote carries Composio's; a bare
     * `Error` carries neither, which is what `brokerSentence` and `vendorSentence` both answering
     * null means. That is most often a programmer error on this side, so the route writes it to the
     * console — the one failure whose explanation cannot be read off the response, because the
     * response is the generic sentence and nothing more.
     *
     * SO THE CONSOLE IS READ HERE, not only the body. The response half alone pins nothing about
     * the guard — `brokerRefusal` produces that same 502 whether the log block exists or not — so
     * the line itself is asserted: it has to carry the sentence the response withholds, and the app
     * it was about. Delete the guard and this case fails; widen its condition to log every refusal
     * and the authored refusal above fails.
     *
     * THE FAKE KEY ON THE THROWN OBJECT pins the restraint the route's comment promises. The error
     * is stringified, never spread, logged as an object or reached into, so a property that rode
     * along on it reaches nobody. `JSON.stringify(error)` in place of `String(error)` is the quiet
     * way to lose that, and it is what these last two assertions catch.
     */
    const { app } = directoryApp(undefined, "admin", [], async () => {
      throw Object.assign(
        new Error("Cannot read properties of undefined (reading 'slug')"),
        { apiKey: "ak_a_key_nobody_should_read" },
      );
    });
    const said: string[] = [];
    const realError = console.error;
    console.error = (...args: unknown[]) => {
      said.push(args.map(String).join(" "));
    };

    try {
      const response = await app.request(
        "http://openbot.test/api/plugins/composio/apps",
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ slug: "slack" }),
        },
      );

      expect(response.status).toBe(502);
      const refusal = ((await response.json()) as { error: string }).error;
      expect(refusal).toContain("Composio said nothing about why");
      // Never the thrown object's own text: on this path it is as likely to be a stack frame as a
      // sentence, and it is the console line that carries it to an operator.
      expect(refusal).not.toContain("Cannot read properties");
    } finally {
      console.error = realError;
    }

    const line = said.find((said) => said.includes("composio-app-not-enabled"));
    expect(line).toBeDefined();
    // Which app an operator is about to be asked about, and the cause the browser was not given —
    // the complement of the assertion above, and the whole point of the guard.
    expect(line).toContain("slack");
    expect(line).toContain("Cannot read properties");
    expect(line).not.toContain("ak_a_key_nobody_should_read");
  });
});

/**
 * What one person's connected accounts are, when some of them are brokered.
 *
 * CRITERION. A brokered connection appears in `GET /connections` for the person who holds it, and
 * for nobody else, in the same list as this deployment's own OAuth connections.
 *
 * REASON. The route answered out of `connectionsFor` alone, which reads the vault's join table, so
 * an app connected through Composio was invisible to the browser however live it was. The settings
 * page could then only lie about it or say nothing, and it said nothing. The two reads are separate
 * because the tables are — one holds a refresh token, the other holds only the fact that Composio
 * said yes — and this pins that the API does not make the reader care which.
 *
 * SCOPING IS THE OTHER HALF, and it is a per-person read with no `requireAdmin` in front of it: a
 * union assembled from the wrong id would put somebody else's connected mailbox on this page.
 *
 * THE TWO ROW TYPES ARE THE STORE'S OWN, and that is what makes the verification half of this route
 * testable at all. The brokered fixture used to be re-typed here as the three fields it shares with
 * a held row, so `verified`, `verifiedAt`, `probe` and `checkable` never entered the harness and
 * nothing above could notice a route that dropped them on the way out.
 */
function connectionsApp(
  person: { id: string; email: string },
  held: HeldConnection[],
  brokered: Array<{ userId: string; row: BrokeredConnection }>,
) {
  const store = pluginStore({
    // Every read the plugins surface makes on its way to the route under test.
    listServers: async () => [],
    listSkills: async () => [],
    connectionsFor: async (userId: string) =>
      userId === person.id ? held : [],
    brokeredConnectionsFor: async (userId: string) =>
      brokered
        .filter((connection) => connection.userId === userId)
        .map((connection) => connection.row),
    // No Shared app in this fixture: every connection here is somebody's own.
    sharedConnections: async () => [],
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: {
        getSession: async () => ({
          user: { ...person, name: "Somebody", image: null },
        }),
      },
    } as never,
    { rolesForUser: async () => ["user"] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
  );

  return () => app.request("http://openbot.test/api/plugins/connections");
}

const ASKER = { id: "user_asker", email: "[email protected]" };
const SOMEBODY_ELSE = { id: "user_other", email: "[email protected]" };

/** This deployment's own OAuth grant, which is what `connectionsFor` answers and all it answers. */
const HELD_NOTION: HeldConnection = {
  serverId: "notion",
  scope: "read",
  connectedAt: "2026-01-01T00:00:00.000Z",
  revoked: false,
};

/**
 * One account Composio holds on this deployment's behalf, in the shape the store really answers.
 *
 * EVERY ONE OF THE FOUR EXTRA FIELDS CARRIES A VALUE THAT IS NOT ITS OWN DEFAULT, which is what
 * makes them assertable rather than decorative. `verified` false beside a NAMED probe is the state
 * that only this field can express — the action ran in this person's account and the vendor refused
 * the key — and `checkable` true beside it is the other half: the app still publishes something to
 * spend, so the page may offer Re-check. A row of `false`/`null`/`null`/`false` would be
 * indistinguishable from a route that invented defaults for fields it had dropped.
 */
const BROKERED_SLACK: BrokeredConnection = {
  serverId: "composio-slack",
  scope: "",
  connectedAt: "2026-02-02T00:00:00.000Z",
  verified: false,
  verifiedAt: null,
  probe: "SLACK_LIST_CHANNELS",
  checkable: true,
};

describe("a person's own connections", () => {
  test("a brokered connection is in the list beside the OAuth ones", async () => {
    const request = connectionsApp(
      ASKER,
      [HELD_NOTION],
      [{ userId: ASKER.id, row: BROKERED_SLACK }],
    );

    const response = await request();

    expect(response.status).toBe(200);
    const body = (await response.json()) as {
      connections: Array<{ serverId: string }>;
    };
    // Sorted, so two requests answer in the same order: concatenating two lists that are each
    // ordered within their own table does not produce an ordered list.
    expect(body.connections.map((row) => row.serverId)).toEqual([
      "composio-slack",
      "notion",
    ]);
  });

  test("and what can be re-checked about it travels with it", async () => {
    /*
     * THE WHOLE VERIFICATION SURFACE, AT THE LEVEL THAT ACTUALLY SHIPS IT.
     *
     * CRITERION. The four fields `brokeredConnectionsFor` adds over a held row leave this route
     * verbatim, and a held row carries none of them.
     *
     * REASON. The route concatenates the two reads without rewriting either, so nothing here looks
     * like code that could drop a field — which is exactly why nothing pinned it. A `.map` added
     * later to normalise the union, or a Zod response schema stripping unknown keys, takes all four
     * out in one line and every other test on this route goes on passing: they assert on
     * `serverId`, and `serverId` survives. What does not survive is the settings page, which then
     * draws "Connected" over a key the vendor has refused, with no Re-check button to find out.
     *
     * THE WHOLE ROW RATHER THAN FIELD BY FIELD, because the failure to catch is a route that keeps
     * the field name and answers something else for it — a `verified: false` defaulted in for a
     * dropped `verified`, or a `probe` flattened to null. Comparing the row the store handed over
     * with the row the browser is given is the one assertion that cannot be satisfied by a
     * plausible-looking substitute.
     *
     * AND THE HELD ROW IS IN THE SAME COMPARISON, which is the other half and not a second thought.
     * A held connection has nothing to re-check — no secret of ours stands behind it to have been
     * spent — so these four fields being ABSENT from its row is what tells the two reads apart on
     * the page, and a route defaulting them onto everything would put a Re-check button over an
     * OAuth grant. `toEqual` on the whole list refuses an extra key as readily as a missing one, so
     * both mistakes land on this line.
     */
    const request = connectionsApp(
      ASKER,
      [HELD_NOTION],
      [{ userId: ASKER.id, row: BROKERED_SLACK }],
    );

    const response = await request();

    expect(response.status).toBe(200);
    const connections = ((await response.json()) as { connections: unknown[] })
      .connections;
    // `holder: "person"` is the route's own addition, over both reads alike: a personal
    // connection, brokered or held, is always the asker's own account.
    expect(connections).toEqual([
      { ...BROKERED_SLACK, holder: "person" },
      { ...HELD_NOTION, holder: "person" },
    ]);
  });

  test("and is nobody else's", async () => {
    // The must-not case. This route is behind `requireUser` and nothing else: a union read for the
    // wrong person would show one person's connected account on another person's settings page.
    const request = connectionsApp(
      SOMEBODY_ELSE,
      [],
      [{ userId: ASKER.id, row: BROKERED_SLACK }],
    );

    const response = await request();

    expect(response.status).toBe(200);
    expect((await response.json()).connections).toEqual([]);
  });
});

/**
 * The url a person is sent to when they connect a brokered app to their own account.
 *
 * A constant rather than a literal at each assertion, because the thing being asserted about it is
 * mostly where it does NOT appear: it is handed to the browser that asked and to nothing else.
 */
const AUTHORIZATION_URL = "https://backend.composio.dev/s/a-bearer-capability";

/**
 * The account `brokeredApp`'s fixture resolves ADMIN to for a Personal app, which is every row in
 * this file but the one added for the Shared case: `holder: "person"`, and `vendorUserId` the same
 * as `userId` because nothing here has ever renamed ADMIN at the vendor.
 */
const ADMIN_ACCOUNT: AccountRef = {
  holder: "person",
  userId: ADMIN.id,
  vendorUserId: ADMIN.id,
};

/** The same, for the single-user deployment's own {@link DEV_ACTOR}. */
const DEV_ACTOR_ACCOUNT: AccountRef = {
  holder: "person",
  userId: DEV_ACTOR.id,
  vendorUserId: DEV_ACTOR.id,
};

/**
 * Where this deployment tells Composio to send somebody back to, written out rather than composed.
 *
 * BUILT FROM THE DEPLOYMENT AND FROM NOTHING IN THE REQUEST, which is the property the tests below
 * are about. The origin is `testEnvironment`'s own — no `OPENBOT_APP_URL` is set, so it falls back
 * through to `BETTER_AUTH_URL` — and the path is the account's page, which is where the person
 * pressed Connect and the page that asks Composio whether it worked.
 *
 * Two of them because a caller may name one of two PAGES and nothing else: an administrator who
 * started this from the app's own admin screen comes back to that screen. A literal at each
 * assertion rather than a call to `connectedAccountsUrlFor`, because an assertion that builds the
 * expected value the way the code does cannot fail when the code's answer changes.
 */
const RETURN_URL = "http://localhost:3001/connections/composio-linear";
const ADMIN_RETURN_URL = "http://localhost:3001/admin/plugins/composio-linear";

/**
 * A failure in the shape `vendorSentence` reaches into, with the vendor's sentence at the bottom.
 *
 * The sentence the vendor actually sends for the failure a new operator meets first, nested exactly
 * as `@composio/core` nests it: two levels inside `cause`, beside the whole HTTP response. The
 * `headers` and `requestId` beside it are the point of this fixture — they are what must not come
 * back out.
 */
const WRONG_KEY = Object.assign(new Error("Request failed"), {
  cause: {
    error: {
      error: { message: "Invalid API key provided." },
      headers: { "x-request-id": "req_a_trace_id_nobody_should_read" },
    },
    status: 401,
  },
});

/**
 * What the key app publishes, which is both the form a person is drawn and the list a submission
 * is checked against.
 *
 * TWO FIELDS AND ONE OF THEM OPTIONAL, because the filter has to be shown to be about NAMES rather
 * than about completeness: a submission naming only the required one is a person leaving the
 * optional box alone, and it must connect.
 */
const PUBLISHED: BrokerField[] = [
  {
    name: "api_key",
    label: "API key",
    help: "Your Firecrawl API key, a token starting with fc-",
    required: true,
    secret: true,
  },
  {
    name: "base_url",
    label: "Base URL",
    help: "Leave this alone unless you run Firecrawl yourself.",
    required: false,
    secret: false,
    default: "https://api.firecrawl.dev",
  },
];

/**
 * One brokered app, added, and the person connecting their own account to it.
 *
 * WHICH APP THIS IS COMES OFF THE ROW'S URL. `serverAddress` answers one row whose url is
 * `composio://linear`, and the branch under test reads the app out of it with `toolkitOf` rather
 * than off the id — the id is a row name (`composio-linear`) and reading one as the other works
 * right up until somebody renames a row.
 *
 * `redirectUrl` NULL IS A DEPLOYMENT WITH NO COMPOSIO_API_KEY, the same way `directoryApp`'s null
 * listing is: there is no broker at all, which is the shipped default and a state the surface has
 * to answer honestly rather than by pretending nobody is connected.
 */
function brokeredApp(
  /** What this deployment already holds for this person and this app. Null is nobody connected. */
  connection: { connectedAt: string } | null = null,
  /** Null is a deployment with no COMPOSIO_API_KEY, which is the shipped default. */
  redirectUrl: string | null = AUTHORIZATION_URL,
  /**
   * The deployment as it is when something about it is what is under test.
   *
   * Every field is absent for the flows that work, which is most of this file. A failure needs a
   * deployment that fails in one named way: a broker that throws where the vendor would have, a
   * store whose brokered calls throw for the same reason one layer down, or an environment with no
   * app URL to send anybody back to.
   */
  deployment: {
    authorizeThrows?: unknown;
    storeThrows?: unknown;
    /** A broker that will not say what an app asks for, which is the fields call failing. */
    fieldsThrow?: unknown;
    /**
     * What the app publishes, when the list itself is what is under test.
     *
     * Defaulted to {@link PUBLISHED}, which is the ordinary app with one required box and one
     * optional one. The case this exists for is the empty list: a scheme whose whole meaning is a
     * secret somebody types, published with nothing to type it into.
     */
    published?: BrokerField[];
    environment?: Record<string, string | undefined>;
  } = {},
) {
  const authorized: Array<{
    account: AccountRef;
    toolkit: string;
    returnUrl: string;
  }> = [];
  const queried: Array<{ toolkit: string; account: AccountRef }> = [];
  const confirmed: Array<{ toolkit: string; account: AccountRef; by: string }> =
    [];
  /** Every re-check that reached the store, so who it was made about is an assertion. */
  const rechecked: Array<{
    toolkit: string;
    account: AccountRef;
    by: string;
  }> = [];
  const disconnected: Array<{
    toolkit: string;
    account: AccountRef;
    by: string;
    reason: string;
  }> = [];
  /** Every time the route went and asked Composio what an app wants typed in. */
  const asked: Array<{ toolkit: string; authScheme: string }> = [];
  /**
   * Every submission that reached the store, which is what the filter is asserted through.
   *
   * The values are recorded because the assertion is about WHICH NAMES travel and not about what a
   * person typed: a key the app never published must not be in here, and the published ones must
   * arrive unchanged.
   */
  const submitted: Array<{
    toolkit: string;
    account: AccountRef;
    by: string;
    values: Record<string, string>;
  }> = [];

  const rows: Array<{
    id: string;
    title: string;
    url: string;
    authScheme: string | null;
    /** Absent is Personal, which is every row below but the one added for the Shared case. */
    accountMode?: "shared";
  }> = [
    {
      id: "composio-linear",
      // The app's name, which is the one of the two a person has ever seen. The refusal below
      // reads it off the row, and the id beside it is what that refusal used to quote instead.
      title: "Linear",
      url: "composio://linear",
      /*
       * The scheme this app's config was created as, which is what decides which of the two
       * brokered flows the route opens. `OAUTH2` is a consent app: there is no form to draw, and
       * every assertion above about a minted link depends on this row being read as one.
       */
      authScheme: "OAUTH2",
    },
    /*
     * An app whose secret the person holds and types in, which is the other half of the brokered
     * surface and the one with a form rather than a consent screen.
     *
     * A SECOND ROW RATHER THAN A SECOND SCHEME ON THE FIRST, because the two flows have to be
     * shown not to reach each other: the consent tests below press Connect on Linear and must
     * still get a link, and the form tests press it on this row and must never mint one. One row
     * switching scheme between tests would prove one flow at a time and nothing about the fork.
     */
    {
      id: "composio-firecrawl",
      title: "Firecrawl",
      url: "composio://firecrawl",
      authScheme: "API_KEY",
    },
    /*
     * An app that needs no credential at all, which is the third brokered kind and the one the
     * fork above forgets.
     *
     * A SEPARATE ROW FOR THE SAME REASON FIRECRAWL IS ONE: the three flows have to be shown not to
     * reach each other, and a row switching scheme between tests would prove one at a time.
     *
     * `NO_AUTH` is the literal `connectionOf` resolves thirty-four of Composio's toolkits to, and
     * it is what `addBrokeredApp` records for them. Composio refuses to hold an authorization
     * config for one, so there is nothing to consent to, nothing to type, and no row in
     * `composio_connections` that could ever be written — which is exactly what
     * `connectionTokenFor` already acts on when it lets a call through with no connection at all.
     */
    {
      id: "composio-hackernews",
      title: "Hacker News",
      url: "composio://hackernews",
      authScheme: "NO_AUTH",
    },
    /*
     * An ordinary OAuth row, so that "this app is not brokered" is a real row and not a missing
     * one. The two routes below answer the same way for both, and this is the half that would
     * otherwise go untested: an id naming nothing at all is easy to refuse, while a server this
     * deployment really has whose connection simply does not live at Composio is where a
     * confusing answer would come from.
     */
    {
      id: "notion",
      title: "Notion",
      url: "https://notion.test/mcp",
      // Null is not an older brokered row; it is a row that is not brokered at all.
      authScheme: null,
    },
    /*
     * A BROKERED ROW WITH NO SCHEME RECORDED ON IT, which is what every brokered row in a
     * deployment older than migration 0030 looks like.
     *
     * The three rows above each name a scheme, so the connect fork was only ever entered by
     * DECISION — and its consent arm is reached by ELIMINATION: `NO_AUTH` is answered, a field
     * scheme is answered, and everything else falls through to minting a link. "Everything else"
     * is the arm with no fixture behind it, and the row shape that lands there most often is this
     * one: `auth_scheme` was added as a nullable column and backfilled for nobody, so every app
     * connected before that migration carries a null to this day.
     *
     * AND IT IS THE RIGHT ANSWER FOR IT, which is why this is a fixture rather than a bug report.
     * Consent was the only kind this deployment had when those rows were written, so a null means
     * consent — and it means it by elimination, which is exactly the reading nothing checked.
     */
    {
      id: "composio-slack",
      title: "Slack",
      url: "composio://slack",
      authScheme: null,
    },
    /*
     * AND A SCHEME THIS DEPLOYMENT HAS NEVER HEARD OF, which is the same arm entered the other way.
     *
     * `OAUTH1` is a real Composio scheme — `connectionOf` resolves it to `consent` and Composio
     * itself calls it redirectable — and it is neither `NO_AUTH` nor a member of `isFieldScheme`'s
     * list. So the row is recorded with a word this route never names, and reaches the consent arm
     * because nothing above it claimed it. Any scheme the vendor adds tomorrow arrives the same
     * way, and the answer has to be a link rather than a 500 or a form drawn for a flow that has
     * none.
     */
    {
      id: "composio-trello",
      title: "Trello",
      url: "composio://trello",
      authScheme: "OAUTH1",
    },
    /*
     * A KEY-TYPE APP SWITCHED TO SHARED, for the one case below where whose account this is
     * matters before the form is even drawn: a non-admin pressing Connect on it must be refused
     * for want of an administrator, never answered the fields a personal app would be.
     */
    {
      id: "composio-firecrawl-shared",
      title: "Firecrawl",
      url: "composio://firecrawl",
      authScheme: "API_KEY",
      accountMode: "shared",
    },
  ];

  const store = pluginStore({
    /*
     * Every read the plugins surface makes on its way to the route under test.
     *
     * Three columns, looked up by id, because that is all these routes ask for: the url they read
     * the app out of and the title a refusal names. The whole server list is what they used to ask
     * for, and a stub that still answered one would be pretending they need more than they do.
     */
    serverAddress: async (serverId: string) =>
      rows.find((row) => row.id === serverId),
    listSkills: async () => [],
    /**
     * Whose account a row acts for, the same way the real one answers it: the actor's own for a
     * Personal app, the deployment's for a Shared one, and a refusal for one needing no account
     * at all — read off this fixture's `accountMode` and `authScheme` rather than off a request,
     * which is the one property every route calling this depends on.
     */
    accountRefFor: async (serverId: string, actorId: string) => {
      const row = rows.find((candidate) => candidate.id === serverId);
      if (!row) {
        return {
          refusal: `${serverId} is not an app this deployment has added.`,
        };
      }
      if (schemeKind(row.authScheme) === "none") {
        return { refusal: `${row.title} needs no account.` };
      }
      if (row.accountMode === "shared") {
        return {
          ref: {
            holder: "deployment" as const,
            vendorUserId: `${row.id}-deployment-account`,
          },
          title: row.title,
          mode: "shared" as const,
        };
      }
      return {
        ref: {
          holder: "person" as const,
          userId: actorId,
          vendorUserId: actorId,
        },
        title: row.title,
        mode: "personal" as const,
      };
    },
    brokeredConnection: async (input: {
      toolkit: string;
      account: AccountRef;
    }) => {
      queried.push(input);
      return connection;
    },
    confirmBrokeredConnection: async (input: {
      toolkit: string;
      account: AccountRef;
      by: string;
    }) => {
      confirmed.push(input);
      // Thrown from where the store asks the broker, because that is where it throws in the
      // product: `confirmBrokeredConnection` calls `isConnected` and catches nothing.
      if (deployment.storeThrows) throw deployment.storeThrows;
      return { connected: connection !== null };
    },
    recheckBrokeredConnection: async (input: {
      toolkit: string;
      account: AccountRef;
      by: string;
    }) => {
      rechecked.push(input);
      // Thrown from where the store raises it in the product: a probe that ran and was refused is a
      // {@link PluginRefusedError}, and a broker that would not answer at all is the vendor's own
      // object one layer down. Both leave this method the same way — by throwing.
      if (deployment.storeThrows) throw deployment.storeThrows;
      /*
       * All three fields, because all three are what the row reads. `verifiedAt` is the date the
       * sentence is drawn from and `probe` is what says a call was really made, which `verified`
       * alone cannot.
       */
      return {
        verified: true,
        verifiedAt: "2026-09-13T10:00:00.000Z",
        probe: "LINEAR_GET_ME",
      };
    },
    connectBrokeredWithFields: async (input: {
      toolkit: string;
      account: AccountRef;
      by: string;
      values: Record<string, string>;
    }) => {
      submitted.push(input);
      if (deployment.storeThrows) throw deployment.storeThrows;
      /*
       * All three fields, because all three are what the browser reads. `probe` named beside
       * `verified: true` is the one state that says a call was really made with the key; the row
       * cannot tell that apart from "there was nothing safe to try" without it.
       */
      return {
        connected: true as const,
        verified: true,
        probe: "FIRECRAWL_SCRAPE",
      };
    },
    disconnectBrokered: async (input: {
      toolkit: string;
      account: AccountRef;
      by: string;
      reason: string;
    }) => {
      disconnected.push(input);
      // The revoke comes before the delete, so a throw here is the product's own ordering: the
      // account is still live at the vendor and the row is still here.
      if (deployment.storeThrows) throw deployment.storeThrows;
      return { vendorRevocationRequested: true };
    },
  });

  const app = createApp(
    loadConfig(testEnvironment(deployment.environment)),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    // Connecting an account is not an administrator's act: an administrator adds the app once, and
    // then everybody connects their own.
    { rolesForUser: async () => ["user"] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
    // Positions 16-29 are the stores after it; the broker is 30, `composio`.
    ...UP_TO_BROKER,
    redirectUrl
      ? ({
          broker: {
            authorize: async (request: {
              account: AccountRef;
              toolkit: string;
              returnUrl: string;
            }) => {
              // Recorded BEFORE the throw, so a test about a failing broker can still say the
              // address it was asked with was this deployment's own.
              authorized.push(request);
              if (deployment.authorizeThrows) throw deployment.authorizeThrows;
              return { redirectUrl, authorizationId: null };
            },
            connectionFields: async (request: {
              toolkit: string;
              authScheme: string;
            }) => {
              asked.push(request);
              if (deployment.fieldsThrow) throw deployment.fieldsThrow;
              return deployment.published ?? PUBLISHED;
            },
          },
        } as never)
      : undefined,
  );

  return {
    authorized,
    queried,
    confirmed,
    rechecked,
    disconnected,
    asked,
    submitted,
    /**
     * The same route aimed at the app whose secret a person types.
     *
     * Its own helper rather than a fifth argument to `connect` below, because the two are different
     * requests: that one is a consent app and carries a query and headers the tests about return
     * addresses need, and this one carries a body and nothing else.
     */
    connectFields: (body?: unknown) =>
      app.request(
        "http://openbot.test/api/plugins/servers/composio-firecrawl/connect",
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
        },
      ),
    /**
     * The same route aimed at the app that needs no account at all.
     *
     * Its own helper beside the other two, because the assertion is that this press reaches
     * neither of them: no form is asked for and no consent link is minted.
     */
    connectNoAuth: (body?: unknown) =>
      app.request(
        "http://openbot.test/api/plugins/servers/composio-hackernews/connect",
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
        },
      ),
    /**
     * The same route aimed at whichever row a test names, with nothing else moved.
     *
     * Its own helper beside {@link connect}, which is fixed on the consent app: the two cases below
     * are about a row whose scheme this route never names, and the only thing that can express them
     * is the id. The body is empty because these are first presses and nothing about them is about
     * what a caller sends.
     */
    connectAt: (serverId: string) =>
      app.request(
        `http://openbot.test/api/plugins/servers/${serverId}/connect`,
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({}),
        },
      ),
    connect: (
      body: unknown,
      query = "",
      /**
       * Headers a caller controls, for the cases that assert none of them is read.
       *
       * A browser sends `Referer` and `Origin` on an ordinary same-origin POST without being asked,
       * so a route reading either would be taking a return address from the request while looking
       * like it took none. Defaulted empty, because every other case here is about the body.
       */
      headers: Record<string, string> = {},
    ) =>
      app.request(
        `http://openbot.test/api/plugins/servers/composio-linear/connect${query}`,
        {
          method: "POST",
          headers: { "content-type": "application/json", ...headers },
          body: JSON.stringify(body),
        },
      ),
    /*
     * The two routes a person's own settings page drives, with every input a caller controls left
     * open: which row, what is in the body, and what is in the query. The tests below hand all
     * three a user id that is not the session's, because the assertion is that none of them
     * changed who was acted on.
     */
    confirm: (options: Caller = {}) =>
      app.request(
        `http://openbot.test/api/plugins/servers/${options.serverId ?? "composio-linear"}/connection/confirm${options.query ?? ""}`,
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(options.body ?? {}),
        },
      ),
    /*
     * The button beside them, and the one that is never pressed by a page.
     *
     * Given the same open inputs as the two below — the row, a body and a query — because it is the
     * same identity question: a re-check spends a call on somebody's own account at the vendor, so a
     * caller who could name a person would be spending a stranger's rate limit and rewriting the
     * verification on their row.
     */
    recheck: (options: Caller = {}) =>
      app.request(
        `http://openbot.test/api/plugins/servers/${options.serverId ?? "composio-linear"}/connection/recheck${options.query ?? ""}`,
        {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(options.body ?? {}),
        },
      ),
    disconnect: (options: Caller = {}) =>
      app.request(
        `http://openbot.test/api/plugins/servers/${options.serverId ?? "composio-linear"}/connection${options.query ?? ""}`,
        {
          method: "DELETE",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(options.body ?? {}),
        },
      ),
  };
}

/** Everything a caller of those two routes gets to choose. */
type Caller = {
  /** Which server row the route is aimed at. Defaults to the brokered one. */
  serverId?: string;
  body?: unknown;
  /** A query string, leading `?` included. */
  query?: string;
};

describe("connecting a brokered app", () => {
  test("the link is minted for the session's own person, whatever the body says", async () => {
    /*
     * THE USER ID COMES FROM THE SESSION AND FROM NOWHERE ELSE.
     *
     * A brokered call opens whichever account the user id names, so a route that would take one
     * out of a request body is one POST away from attaching somebody else's Linear to this
     * person's row — or, the same defect turned around, minting a link that connects this person's
     * account under somebody else's name. It is the defect the prior art this design copies
     * shipped and fixed three separate times, which is why the body here carries a user id at all:
     * the assertion is that it changed nothing.
     */
    const { authorized, queried, connect } = brokeredApp();

    const response = await connect({ userId: "user_somebody_else" });

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({
      authorizationUrl: AUTHORIZATION_URL,
    });
    expect(authorized).toEqual([
      { account: ADMIN_ACCOUNT, toolkit: "linear", returnUrl: RETURN_URL },
    ]);
    // And the read that decided there was no connection yet asked about the same account.
    expect(queried).toEqual([{ toolkit: "linear", account: ADMIN_ACCOUNT }]);
  });

  test("a brokered row never reaches the checks that belong to the OAuth flow", async () => {
    /*
     * The ordering, stated as its own case. This deployment has no OPENBOT_PUBLIC_URL and
     * `composio-linear` is in nobody's catalogue, so a brokered row that fell through to either of
     * the two checks below the branch would be answered "no public URL" or "is not connected as an
     * individual person" — the second of which is the opposite of true. Neither check applies: no
     * authorization code comes back to us, no refresh token is stored, and no redirect URI of ours
     * is registered anywhere.
     */
    const { connect } = brokeredApp();

    const body = await (await connect({})).json();

    expect(body.authorizationUrl).toBe(AUTHORIZATION_URL);
  });

  /**
   * THE ARM THAT USED TO BE REACHED BY ELIMINATION, AGAINST THE TWO ROW SHAPES THAT REACH IT.
   *
   * CRITERION. A brokered row recorded with NO scheme, and one recorded with a scheme this route
   * never names, are both REFUSED, and nothing is minted at Composio for either.
   *
   * REASON. The fork used to decide `NO_AUTH` first and a field scheme second, and consent was what
   * was left — so the consent arm was the one arm no row was ever chosen FOR. Both shapes below
   * exist in live databases: `auth_scheme` arrived as a nullable column with no backfill, so every
   * app connected before migration 0030 carries a null, and the catalogue is the vendor's, so a
   * scheme this deployment has never heard of is one Composio release away. What each of them got
   * was a real act performed at the vendor — an authorization link minted for an app this
   * deployment cannot say it holds a consent config for — on the strength of an answer nobody
   * decided.
   *
   * AND THIS TEST USED TO ASSERT THE OPPOSITE, ON AN ARGUMENT WORTH RECORDING RATHER THAN DELETING.
   * It said: neither row can be answered a form, so refusing what the route cannot name leaves every
   * pre-0030 brokered app with a Connect button that says the app is not one this deployment can
   * connect, and the remedy — an administrator removing the app and adding it again — takes every
   * grant on it with it. That is a true cost, and it is the smaller one. A minted link is a
   * capability handed out about an app whose connection kind is unknown, and the three readers of
   * this same column in `plugins/store.ts` all fail closed on that value: the re-check refuses, the
   * disconnect claims no revocation, and the mount-time confirm writes nothing. A route that failed
   * open was the last one that did, and a person told to ask an administrator gets a sentence naming
   * the act that fixes it — which is more than the consent arm's dead end offered them.
   *
   * NOTHING MINTED IS THE HALF THAT MATTERS, which is what `authorized` carries: a link is a
   * capability, and one minted for an app nobody could classify is one nobody chose to hand out.
   */
  test("a brokered row whose scheme this route cannot name is refused rather than sent to consent", async () => {
    const { authorized, connectAt } = brokeredApp();

    // The pre-0030 row: brokered, connected, and carrying no scheme at all.
    const held = await connectAt("composio-slack");
    expect(held.status).toBe(400);
    expect(String((await held.json()).error)).toMatch(/can't tell how/);

    // And a scheme the vendor names that this deployment does not.
    const drifted = await connectAt("composio-trello");
    expect(drifted.status).toBe(400);
    expect(String((await drifted.json()).error)).toMatch(/can't tell how/);

    expect(authorized).toEqual([]);
  });

  test("a second connection is refused with the step to take", async () => {
    const { authorized, connect } = brokeredApp({
      connectedAt: "2026-02-02T00:00:00.000Z",
    });

    const response = await connect({});

    expect(response.status).toBe(409);
    const refusal = (await response.json()).error as string;
    // Naming the remedy rather than only refusing: the person has an account attached already, and
    // the only way to a new link is through disconnecting the one they have.
    expect(refusal.toLowerCase()).toContain("disconnect");
    /*
     * THE APP'S TITLE, AND NOT THE ROW'S ID. "Linear" is the name of the thing this person
     * connected; `composio-linear` is how this deployment keys a table, which they have never seen
     * and cannot act on. The second assertion is not the first one twice: a sentence that named the
     * app and then quoted the row id beside it would satisfy one and fail the other.
     */
    expect(refusal).toContain("Linear");
    expect(refusal).not.toContain("composio-linear");
    // And nothing was minted, which is the half that matters: a link handed out here would attach
    // a second account behind a row that already says connected.
    expect(authorized).toEqual([]);
  });

  test("a deployment with no broker is told which setting to set", async () => {
    // The same answer the directory gives, for the same reason: nobody was asked, and the remedy
    // is one environment variable long.
    const { connect } = brokeredApp(null, null);

    const response = await connect({});

    expect(response.status).toBe(503);
    const refusal = (await response.json()).error as string;
    expect(refusal).toBe(PERSON_UNCONFIGURED);
    expect(refusal).not.toMatch(/composio|COMPOSIO_API_KEY/i);
  });

  test("the address Composio sends somebody back to is built here, never taken from the request", async () => {
    /*
     * THE RETURN ADDRESS IS THIS DEPLOYMENT'S, AND A CALLER HAS NO SAY IN IT.
     *
     * Whoever names it names where a person lands holding a just-completed consent, so a url read
     * off the body, the query or a header would be an open redirect with a consent screen in front
     * of it — the same defect this repository's OAuth `returnTo` is narrowed to two names to
     * avoid. The request below names an address in all three places at once, so a route that read
     * any one of them fails here rather than passing on the two it ignored.
     */
    const { authorized, connect } = brokeredApp();

    const response = await connect(
      { returnUrl: "https://evil.test/harvest", returnTo: "https://evil.test" },
      "?returnUrl=https%3A%2F%2Fevil.test%2Fharvest&callbackUrl=https%3A%2F%2Fevil.test",
      {
        returnUrl: "https://evil.test/harvest",
        referer: "https://evil.test",
        origin: "https://evil.test",
        "x-forwarded-host": "evil.test",
      },
    );

    expect(response.status).toBe(200);
    expect(authorized).toEqual([
      { account: ADMIN_ACCOUNT, toolkit: "linear", returnUrl: RETURN_URL },
    ]);
  });

  test("an administrator who started on the app's own page is sent back to it", async () => {
    /*
     * The one thing a caller does get to choose, and it is a NAME rather than an address: `admin`
     * or anything else, resolved against this deployment's own origin either way. An administrator
     * connecting their account from the app's setup page left a page mid-task, and sending them to
     * their personal settings afterwards is the round trip this exists to remove.
     */
    const { authorized, connect } = brokeredApp();

    await connect({}, "?returnTo=admin");

    expect(authorized).toEqual([
      {
        account: ADMIN_ACCOUNT,
        toolkit: "linear",
        returnUrl: ADMIN_RETURN_URL,
      },
    ]);
  });

  test("a returnTo naming somewhere else is the default, not a destination", async () => {
    // Narrowed to one of two names on the way in, so an unrecognised value never reaches the url
    // that gets built. A full address in that parameter is the attack this shape refuses.
    const { authorized, connect } = brokeredApp();

    await connect({}, "?returnTo=https%3A%2F%2Fevil.test");

    expect(authorized).toEqual([
      { account: ADMIN_ACCOUNT, toolkit: "linear", returnUrl: RETURN_URL },
    ]);
  });

  test("a deployment with no app URL is refused rather than handed a link with no way back", async () => {
    /*
     * A CONSENT WITH NOWHERE TO RETURN TO STRANDS SOMEBODY, so no link is minted at all.
     *
     * The consent screen is on Composio's origin, so the address has to be absolute, and a
     * deployment that cannot say where its own pages are has none to give. Minting the link anyway
     * would leave a person on Composio's hosted page having just granted access to their mailbox,
     * with no route back and nothing here knowing it happened.
     *
     * Single-user with no sign-in is the one deployment shape that genuinely has no app URL:
     * everywhere else `OPENBOT_APP_URL`, `TRUSTED_ORIGINS` or the sign-in address supplies one.
     */
    const { authorized, connect } = brokeredApp(null, AUTHORIZATION_URL, {
      environment: {
        OPENBOT_SINGLE_USER: "true",
        BETTER_AUTH_URL: undefined,
        BETTER_AUTH_SECRET: undefined,
        GOOGLE_OAUTH_CLIENT_ID: undefined,
        GOOGLE_OAUTH_CLIENT_SECRET: undefined,
        INITIAL_ADMIN_EMAILS: undefined,
      },
    });

    const response = await connect({});

    expect(response.status).toBe(503);
    // The setting, because it is the whole remedy and nothing else on the screen names it.
    expect((await response.json()).error).toContain("OPENBOT_APP_URL");
    expect(authorized).toEqual([]);
  });

  test("a broker that throws answers with Composio's own sentence, not a 500", async () => {
    /*
     * A WRONG KEY IS THE FIRST FAILURE A NEW OPERATOR MEETS, and it used to be the least legible:
     * nothing on this path caught anything, so the person pressing Connect got a bare 500 and the
     * vendor's whole thrown object went to the console.
     *
     * What comes back is the one sentence the vendor wrote and nothing else that travelled with
     * it: not the request id, not the response headers, and not the link that was being minted
     * when it failed — which is a bearer capability and belongs in one browser or nowhere.
     */
    const { connect } = brokeredApp(null, AUTHORIZATION_URL, {
      authorizeThrows: WRONG_KEY,
    });

    const response = await connect({});
    const body = await response.text();

    // 502 rather than 500: nothing here broke, and a third party did not answer usefully.
    expect(response.status).toBe(502);
    expect(JSON.parse(body).error).toBe("Invalid API key provided.");
    expect(body).not.toContain("req_a_trace_id_nobody_should_read");
    expect(body).not.toContain(AUTHORIZATION_URL);
  });

  test("a failure the vendor did not explain still says what to do", async () => {
    // Null from `vendorSentence` is a failure this deployment cannot explain — a socket that hung
    // up, an answer in a shape nobody recognises — and the fallback names the app and the step
    // rather than echoing whatever the thrown object happened to stringify as.
    const { connect } = brokeredApp(null, AUTHORIZATION_URL, {
      authorizeThrows: new Error("socket hang up"),
    });

    const response = await connect({});

    expect(response.status).toBe(502);
    const refusal = (await response.json()).error as string;
    expect(refusal).toContain("Linear");
    expect(refusal).not.toContain("socket hang up");
  });
});

/**
 * The other half of the same route: an app whose secret the person holds and types in.
 *
 * CRITERION. A key app answers the form on the first press and the connection on the second, the
 * person it connects is the session's whatever the body says, every three of `connectBrokeredWithFields`'s
 * fields reach the browser, and a name the app did not publish never reaches the store at all.
 *
 * REASON. Most Composio apps are not consent apps, so this branch is the ordinary path rather than
 * the exotic one, and it is the only place in this deployment where a request body is forwarded to
 * a vendor. What is submitted is spread into Composio's own field object, so an unfiltered body is
 * two separate holes at once: a `status` key would sit beside the literal this deployment sets, and
 * anything else a caller invents would travel unexamined. The filter is asserted by what is
 * recorded in `submitted` rather than by the answer, because the answer is the same either way.
 */
describe("connecting an app whose secret a person types", () => {
  test("the first press answers what the app publishes, and connects nobody", async () => {
    /*
     * NO BODY AT ALL, which is what the browser really sends on this press: it is a question about
     * the app rather than about anybody's account. A route that required a body to answer the form
     * would answer this request by trying to connect an empty one.
     */
    const { asked, submitted, authorized, connectFields } = brokeredApp();

    const response = await connectFields();

    expect(response.status).toBe(200);
    // The vendor's own list, passed through rather than restated: `help` is written for the person
    // filling the box in, and nothing here is in a position to improve on it.
    expect(await response.json()).toEqual({ fields: PUBLISHED });
    /*
     * ASKED WITH THE SCHEME RECORDED ON THE ROW, never one derived again here. A form drawn for
     * `BASIC` in front of a config created for `API_KEY` asks for boxes the person's app does not
     * have.
     */
    expect(asked).toEqual([{ toolkit: "firecrawl", authScheme: "API_KEY" }]);
    // And nothing was connected and no consent link minted: this press writes nothing.
    expect(submitted).toEqual([]);
    expect(authorized).toEqual([]);
  });

  test("what the person typed connects them, and all three states come back", async () => {
    /*
     * THE PERSON IS THE SESSION'S HERE TOO, which is why the body carries somebody else's id: the
     * values are a credential being attached to whichever account the user id names, so a route
     * reading one off the body would hang this person's key off another person's row.
     */
    const { submitted, authorized, connectFields } = brokeredApp();

    const response = await connectFields({
      values: { api_key: "fc-live-a-secret" },
      userId: SOMEBODY_ELSE.id,
    });

    expect(response.status).toBe(200);
    /*
     * ALL THREE FIELDS, AND `probe` IS THE ONE THE ROW CANNOT DO WITHOUT. `verified` alone means
     * three different things — nothing safe to try, tried and passed, tried and rejected — and two
     * of them share the flag. A browser given only the boolean would tell somebody whose key the
     * vendor rejected that nothing was ever checked.
     */
    expect(await response.json()).toEqual({
      connected: true,
      verified: true,
      probe: "FIRECRAWL_SCRAPE",
    });
    expect(submitted).toEqual([
      {
        toolkit: "firecrawl",
        account: ADMIN_ACCOUNT,
        by: ADMIN.id,
        values: { api_key: "fc-live-a-secret" },
      },
    ]);
    // And no consent link was minted for an app that has no consent screen.
    expect(authorized).toEqual([]);
  });

  test("a name the app never published is refused, and nothing is sent", async () => {
    /*
     * `status` IS THE SHARPEST CASE AND THAT IS WHY IT IS THE ONE SUBMITTED. The values are spread
     * into the object the adapter builds for Composio, beside the literal `status: "ACTIVE"` that
     * call sets, so an unfiltered body lets a caller write over it. Every other invented name is
     * the same hole with a less interesting key in it.
     *
     * A person cannot type a name the form did not draw, so this request is either a caller doing
     * something deliberate or an app whose published fields have moved — and neither is answered by
     * connecting them anyway with part of what they sent.
     */
    const { submitted, connectFields } = brokeredApp();

    const response = await connectFields({
      values: { api_key: "fc-live-a-secret", status: "ACTIVE" },
    });

    expect(response.status).toBe(400);
    const refusal = (await response.json()).error as string;
    expect(refusal).toContain("Firecrawl");
    /*
     * THE SENTENCE CARRIES NOTHING THAT WAS SUBMITTED. The values are somebody's own credential and
     * belong in no message, and the names are the caller's text rather than the vendor's on exactly
     * the request where they are wrong.
     */
    expect(refusal).not.toContain("fc-live-a-secret");
    expect(refusal).not.toContain("ACTIVE");
    // The half that matters: the key never left this deployment.
    expect(submitted).toEqual([]);
  });

  test("a value that is not text is refused rather than forwarded as one", async () => {
    // The names are checked against the published list and the values against being values at all:
    // a number under a published name typechecks nowhere and reaches the vendor as whatever JSON
    // makes of it.
    const { submitted, connectFields } = brokeredApp();

    const response = await connectFields({ values: { api_key: 12 } });

    expect(response.status).toBe(400);
    expect(submitted).toEqual([]);
  });

  test("a required box the submission leaves out is refused, and named", async () => {
    /*
     * THE SHAPE WAS NEVER THE QUESTION A REQUIRED FIELD ASKS. Every name here is published and
     * every value is text — vacuously, because there are none — so a guard that checked only those
     * two things let an empty body through, and what it made at Composio is an account carrying no
     * credential at all. Composio does not grade what it is given, and an app with nothing safe to
     * probe leaves the row written and every screen here drawing it as connected.
     */
    const { submitted, connectFields } = brokeredApp();

    const response = await connectFields({ values: {} });

    expect(response.status).toBe(400);
    const refusal = (await response.json()).error as string;
    // The app's name and the box that is missing, which is the whole of what fixes it. The name is
    // the vendor's own here rather than the caller's text, which is what makes it safe to quote.
    expect(refusal).toContain("Firecrawl");
    expect(refusal).toContain("api_key");
    expect(submitted).toEqual([]);
  });

  test("a required box holding only spaces is the empty box it looks like", async () => {
    /*
     * WHITESPACE IS ABSENCE, AND THE SERVER IS THE ONLY PLACE THAT CAN SAY SO. The browser's
     * `required` attribute refuses an empty box and accepts a space, so a space is exactly what
     * reaches here from a form that believes it is filled in — and a key made of spaces is a
     * credential in no sense anything downstream would notice: Composio accepts it, the row is
     * written, and the person is told they are connected.
     */
    const { submitted, connectFields } = brokeredApp();

    const response = await connectFields({
      values: { api_key: "   ", base_url: "https://api.firecrawl.dev" },
    });

    expect(response.status).toBe(400);
    expect(submitted).toEqual([]);
  });

  test("an optional box left empty is not a refusal", async () => {
    /*
     * THE OTHER HALF, AND THE ONE THIS GUARD COULD EASILY BREAK. The form seeds a box from the
     * default the app published and sends every published name back whether or not it was touched,
     * so a blank optional value is what an ordinary submission carries — not an incomplete one. A
     * guard that read "blank" as "missing" without reading `required` first would refuse the
     * commonest submission this route handles.
     */
    const { submitted, connectFields } = brokeredApp();

    const response = await connectFields({
      values: { api_key: "fc-live-a-secret", base_url: "" },
    });

    expect(response.status).toBe(200);
    expect(submitted).toEqual([
      {
        toolkit: "firecrawl",
        account: ADMIN_ACCOUNT,
        by: ADMIN.id,
        values: { api_key: "fc-live-a-secret", base_url: "" },
      },
    ]);
  });

  test("an app that publishes no boxes connects nobody, form or no form", async () => {
    /*
     * A FIELD SCHEME IS A SECRET SOMEBODY TYPES, so an app publishing nothing to type it into
     * cannot be connected at all: there is no required box to be missing, and every check the
     * submission passes it passes for want of anything to check. The press answers with a refusal
     * rather than an account, and the form press above it still answers the empty list honestly.
     */
    const { submitted, connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      published: [],
    });

    expect(await (await connectFields()).json()).toEqual({ fields: [] });

    const response = await connectFields({ values: {} });

    expect(response.status).toBe(400);
    expect((await response.json()).error as string).toContain("Firecrawl");
    expect(submitted).toEqual([]);
  });

  test("an app that requires none of its boxes connects nobody, blank or seeded", async () => {
    /*
     * THE SAME CREDENTIAL-LESS ACCOUNT AS THE EMPTY LIST ABOVE, REACHED WITH BOXES ON THE SCREEN.
     * A field scheme is Composio's own statement that this person holds a secret, so an app
     * publishing not one box it says has to be filled in leaves the required guard nothing to be
     * about: `{}` passes it vacuously, a box holding spaces passes it, and so does the very default
     * the form seeded itself from. Every one of the three makes an account carrying no credential,
     * which Composio answers `ACTIVE` for because it does not grade what it is handed, and which an
     * app with nothing safe to probe leaves recorded and drawn as connected on every screen here.
     *
     * THE SEEDED DEFAULT IS THE CASE A GUARD ON THE SUBMISSION WOULD LET THROUGH, and it is the
     * ordinary press rather than a contrived one: the form draws `base_url` already holding the
     * default the app published and posts every published name back whether or not anybody touched
     * it, so somebody who types nothing at all submits a non-blank value they did not choose.
     * Counting non-blank values would call that a credential.
     *
     * AND THE FORM PRESS IS STILL ANSWERED HONESTLY, as it is for the empty list one test above:
     * the list is a true answer to what the app asks for. What is false is the account the NEXT
     * press would make, so that is the press that is refused.
     */
    const { submitted, connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      published: [
        {
          name: "base_url",
          label: "Base URL",
          help: "Leave this alone unless you run Firecrawl yourself.",
          required: false,
          secret: false,
          default: "https://api.firecrawl.dev",
        },
      ],
    });

    const form = await connectFields();
    expect(form.status).toBe(200);
    expect(
      ((await form.json()).fields as BrokerField[]).map((field) => field.name),
    ).toEqual(["base_url"]);

    for (const values of [
      {},
      { base_url: "   " },
      { base_url: "https://api.firecrawl.dev" },
    ]) {
      const response = await connectFields({ values });

      expect(response.status).toBe(400);
      const refusal = (await response.json()).error as string;
      // The app's name rather than the row's id, as everywhere else in this branch.
      expect(refusal).toContain("Firecrawl");
      expect(refusal).not.toContain("composio-firecrawl");
      /*
       * AND NOTHING THAT WAS SUBMITTED. The seeded default is still a value off the request, and a
       * refusal that echoed it would be echoing whatever a caller sent under that name instead.
       * The vendor's field NAME is what the sentence may carry, and it does.
       */
      expect(refusal).not.toContain("https://api.firecrawl.dev");
      expect(refusal).toContain("base_url");
    }

    expect(submitted).toEqual([]);
  });

  test("a box named after something every object already has is still an empty box", async () => {
    /*
     * THE NAME IS THE VENDOR'S AND THE BAG IT IS PUT IN IS THIS DEPLOYMENT'S, which is the whole of
     * why this case exists. The submitted values are collected into a plain `{}` and each published
     * name is then read back off it — so a field Composio names `constructor` or `toString` is a
     * name JavaScript answers for before the submission does: the read finds a function hanging off
     * `Object.prototype` rather than the `undefined` that means "nobody filled this in". What the
     * required guard then does with it is call `.trim()` on a function, which is a 500 in front of
     * somebody who typed nothing wrong — and a prototype value that HAD been text would have been
     * worse, because the guard would have counted a credential nobody supplied.
     *
     * BOTH NAMES, because the two are not one case: `constructor` is the one an attacker reaches
     * for and `toString` is the one an app could plausibly publish, and a bag that answers for
     * either answers for every other name on that prototype too.
     *
     * THE ANSWER IS THE ORDINARY REFUSAL. Nothing about this submission is exotic from the person's
     * side — they left two required boxes empty — so what they get is the sentence that names the
     * boxes, and nothing reaches the store.
     */
    const { submitted, connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      published: [
        {
          name: "constructor",
          label: "Instance",
          help: "Which instance this account lives on.",
          required: true,
          secret: false,
        },
        {
          name: "toString",
          label: "Rendering",
          help: "How this account names itself.",
          required: true,
          secret: false,
        },
      ],
    });

    const response = await connectFields({ values: {} });

    expect(response.status).toBe(400);
    const refusal = (await response.json()).error as string;
    expect(refusal).toContain("Firecrawl");
    // The vendor's own names, which is what this branch may quote and all it quotes.
    expect(refusal).toContain("constructor");
    expect(refusal).toContain("toString");
    expect(submitted).toEqual([]);
  });

  test("a box named __proto__ carries what was typed rather than vanishing on the way", async () => {
    /*
     * THE OTHER HALF OF THE SAME BAG, AND IT FAILS SILENTLY RATHER THAN LOUDLY. Assigning
     * `values["__proto__"] = "acme"` on a plain object does not store anything under that name — it
     * reaches the prototype setter, which ignores a string — so the value a person typed is dropped
     * between the check that admitted it and the store that was supposed to receive it. Composio
     * then makes an account missing one of the values the app publishes, answers `ACTIVE` for it
     * because it does not grade what it is handed, and every screen here draws the row as connected.
     *
     * OPTIONAL, SO THE DROP IS THE ONLY THING UNDER TEST. A required `__proto__` would be caught by
     * the guard above for a different reason; leaving it optional means this submission is complete,
     * the request succeeds, and the only question left is whether what was typed arrived.
     */
    const { submitted, connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      published: [
        {
          name: "api_key",
          label: "API key",
          help: "Your Firecrawl API key, a token starting with fc-",
          required: true,
          secret: true,
        },
        {
          name: "__proto__",
          label: "Tenant",
          help: "The tenant this key belongs to.",
          required: false,
          secret: false,
        },
      ],
    });

    const response = await connectFields({
      values: { api_key: "fc-live-a-secret", ["__proto__"]: "acme" },
    });

    expect(response.status).toBe(200);
    expect(submitted).toHaveLength(1);
    // Read as own names rather than by lookup, because a lookup is the very thing that went wrong.
    expect(Object.keys(submitted[0].values).sort()).toEqual([
      "__proto__",
      "api_key",
    ]);
    expect(submitted[0].values).toEqual({
      api_key: "fc-live-a-secret",
      ["__proto__"]: "acme",
    });
  });

  test("an account already connected is refused before the form is drawn", async () => {
    /*
     * THE ONE-ACCOUNT GUARD STILL RUNS FIRST, which is the ordering both branches were put after on
     * purpose. Drawing the form for somebody who already has an account attached invites them to
     * type a key that would be refused after they had entered it, and asking Composio what the app
     * wants is a call made on behalf of a request that is going to be refused anyway.
     */
    const { asked, submitted, connectFields } = brokeredApp({
      connectedAt: "2026-02-02T00:00:00.000Z",
    });

    const response = await connectFields();

    expect(response.status).toBe(409);
    const refusal = (await response.json()).error as string;
    expect(refusal.toLowerCase()).toContain("disconnect");
    // The app's name rather than the row's id, as on the consent half above.
    expect(refusal).toContain("Firecrawl");
    expect(refusal).not.toContain("composio-firecrawl");
    expect(asked).toEqual([]);
    expect(submitted).toEqual([]);
  });

  test("a consent app is untouched by either branch, whatever the body carries", async () => {
    /*
     * THE FORK IS ON THE SCHEME RECORDED ON THE ROW AND ON NOTHING IN THE REQUEST. A body carrying
     * values is not a statement about how an app connects, and a route that read it as one would
     * send somebody's typed key at a config created for a consent screen — which has nowhere to put
     * it — instead of minting the link they pressed for.
     */
    const { asked, submitted, authorized, connect } = brokeredApp();

    const response = await connect({ values: { api_key: "fc-live-a-secret" } });

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({
      authorizationUrl: AUTHORIZATION_URL,
    });
    expect(authorized).toEqual([
      { account: ADMIN_ACCOUNT, toolkit: "linear", returnUrl: RETURN_URL },
    ]);
    expect(asked).toEqual([]);
    expect(submitted).toEqual([]);
  });

  test("a key app connects on a deployment with no app URL to come back to", async () => {
    /*
     * A SETTING WITH NO BEARING ON THIS FLOW DOES NOT GET TO REFUSE IT.
     *
     * `OPENBOT_APP_URL` is where Composio sends somebody back to once they have consented, and this
     * half has no consent screen to come back from: the key is typed here, no link is minted, and
     * nobody ever leaves the deployment. The guard for it used to stand in front of the fork, so a
     * single-user deployment with no sign-in — the one shape that genuinely has no app URL — could
     * connect none of the key apps that make up most of Composio's catalogue, and was told to set a
     * variable that would not have changed anything about the press it refused.
     *
     * The same environment as the consent refusal above, which is what makes the pair meaningful:
     * one deployment, one missing setting, and the two halves of this route answering differently
     * because only one of them has a return leg.
     */
    const { asked, submitted, authorized, connectFields } = brokeredApp(
      null,
      AUTHORIZATION_URL,
      {
        environment: {
          OPENBOT_SINGLE_USER: "true",
          BETTER_AUTH_URL: undefined,
          BETTER_AUTH_SECRET: undefined,
          GOOGLE_OAUTH_CLIENT_ID: undefined,
          GOOGLE_OAUTH_CLIENT_SECRET: undefined,
          INITIAL_ADMIN_EMAILS: undefined,
        },
      },
    );

    const response = await connectFields({
      values: { api_key: "fc-live-a-secret" },
    });

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({
      connected: true,
      verified: true,
      probe: "FIRECRAWL_SCRAPE",
    });
    // The key reached the store rather than a 503, and the form was drawn from the vendor on the
    // way through.
    expect(asked).toEqual([{ toolkit: "firecrawl", authScheme: "API_KEY" }]);
    expect(submitted).toEqual([
      {
        toolkit: "firecrawl",
        account: DEV_ACTOR_ACCOUNT,
        by: DEV_ACTOR.id,
        values: { api_key: "fc-live-a-secret" },
      },
    ]);
    // And still no consent link, which is the whole reason the setting has no bearing here.
    expect(authorized).toEqual([]);
  });

  test("a broker that will not say what an app asks for answers with its own sentence", async () => {
    // The same mapping every other brokered call in this file makes: the vendor's one sentence, a
    // 502 rather than a 500, and nothing else that travelled with it.
    const { connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      fieldsThrow: WRONG_KEY,
    });

    const response = await connectFields();
    const body = await response.text();

    expect(response.status).toBe(502);
    expect(JSON.parse(body).error).toBe("Invalid API key provided.");
    expect(body).not.toContain("req_a_trace_id_nobody_should_read");
  });

  test("a key the vendor rejected comes back in the words the store refused it with", async () => {
    /*
     * A MISTYPED KEY IS THE ORDINARY FAILURE HERE AND ITS SENTENCE IS THE WHOLE REMEDY. The store
     * raises a refusal that already says what happened and what to do about it, and flattening that
     * into "Composio said nothing about why" would leave the person who pasted a key with a newline
     * in it reading a sentence about this deployment's API key.
     */
    const { connectFields } = brokeredApp(null, AUTHORIZATION_URL, {
      storeThrows: new PluginRefusedError(
        "firecrawl would not answer with what was entered: 401 unauthorized. Nothing was saved, so entering it again is the whole of the retry.",
        null,
      ),
    });

    const response = await connectFields({ values: { api_key: "wrong" } });

    expect(response.status).toBe(400);
    expect((await response.json()).error).toContain("401 unauthorized");
  });
});

/**
 * A key-type app switched to Shared, pressed by somebody who is not an administrator.
 *
 * CRITERION. Whose account a Shared app's connection belongs to is settled by `brokeredAccountFor`
 * before the key-app branch ever asks Composio what to draw a form from: a non-admin's first press
 * is refused 403, in the same words every other route refuses a non-admin reaching a Shared app's
 * account, and nothing is asked of the broker on the way.
 *
 * REASON. `connectionFields` is a call to the vendor made on behalf of a press that is going to be
 * refused anyway once whose account this is is known — the same waste the "account already
 * connected" case above exists to avoid, and the sharper case here: an app switched to Shared
 * cannot be connected by anybody but an administrator at all, so asking the broker first would
 * draw a form for a press nobody may ever complete.
 */
describe("connecting a key-type Shared app", () => {
  test("a non-admin's first press is refused before the broker is ever asked", async () => {
    const { asked, submitted, connectAt } = brokeredApp();

    const response = await connectAt("composio-firecrawl-shared");

    expect(response.status).toBe(403);
    expect((await response.json()).error).toBe(
      "Only an admin can connect shared apps.",
    );
    // Nothing was asked of Composio and nothing was sent: the refusal happens before either.
    expect(asked).toEqual([]);
    expect(submitted).toEqual([]);
  });
});

/**
 * The third half of the same route, which is the one it did not have: an app needing no credential.
 *
 * CRITERION. Pressing Connect on a `NO_AUTH` app is answered with what is true of it — there is no
 * account to make — in a sentence naming the app rather than the row, and nothing is asked of
 * Composio on the way: no form is drawn, no consent link is minted, and no key travels. The answer
 * is the same on a deployment with no `OPENBOT_APP_URL`, because that setting is where a consent
 * comes back to and this flow has no consent to come back from.
 *
 * REASON. Thirty-four of Composio's toolkits resolve to `no-auth`, and `NO_AUTH` is the literal
 * recorded on their rows. It is not a field scheme, so the fork above dropped every one of them
 * into the consent arm, where they met one of two dead ends: a 503 demanding `OPENBOT_APP_URL` for
 * a return leg that does not exist, or `broker.authorize`, which can only fail because
 * `ensureAuthConfig` deliberately creates no config for an app Composio refuses to hold one for —
 * answered with a sentence telling the person to remove the app and add it again, which would
 * produce the same row and the same failure. `connectionTokenFor` already settles what is true
 * here: a `NO_AUTH` app has no connection row, cannot have one, and its tools run without one.
 */
describe("connecting an app that needs no account", () => {
  test("the press is answered with what is true of the app, and nothing is asked of Composio", async () => {
    const { asked, authorized, submitted, queried, connectNoAuth } =
      brokeredApp();

    const response = await connectNoAuth();

    /*
     * A REFUSAL RATHER THAN A 200 SAYING CONNECTED, because no row was written and none ever can
     * be. `composio_connections` is the whole of the permission for a brokered call and every row
     * in it means a person granted access to an account; a route answering `connected: true` here
     * would have the settings page draw an account that does not exist, offer a Disconnect that
     * ends nothing, and put this app in front of offboarding as something to revoke.
     *
     * 400 for the reason the OAuth branch below refuses a row that is not connected as an
     * individual person with one: the act does not apply to this kind of row, and the sentence
     * says what is true instead.
     */
    expect(response.status).toBe(400);
    const refusal = (await response.json()).error as string;
    /*
     * THE APP'S TITLE, AND NOT THE ROW'S ID, as on both other halves of this route. "Hacker News"
     * is the name of the thing the person is looking at; `composio-hackernews` is how this
     * deployment keys a table.
     */
    expect(refusal).toContain("Hacker News");
    expect(refusal).not.toContain("composio-hackernews");
    /*
     * AND IT NAMES NO REMEDY, BECAUSE NOTHING IS WRONG. The sentence this used to produce told the
     * person to remove the app and add it again — a step that rebuilds the identical row and fails
     * identically. What is true is that the app works as it is.
     */
    expect(refusal.toLowerCase()).not.toContain("add it again");
    expect(refusal.toLowerCase()).not.toContain("administrator");

    // Neither of the other two branches was entered: no form drawn, no key sent, no link minted.
    expect(asked).toEqual([]);
    expect(submitted).toEqual([]);
    expect(authorized).toEqual([]);
    /*
     * The no-auth answer comes before any account lookup, which is the opposite ordering from
     * the other two branches: `schemeKind(row.authScheme) === "none"` is answered straight off
     * the row, before `brokeredAccountFor` — and so `accountRefFor`, and the one-account guard
     * it resolves through — is ever asked whose press this is. Nothing was queried.
     */
    expect(queried).toEqual([]);
  });

  test("a deployment with no app URL answers the same way, because there is no return leg", async () => {
    /*
     * A SETTING WITH NO BEARING ON THIS FLOW DOES NOT GET TO REFUSE IT — the same case the key
     * branch makes one describe above, and the sharper version of it: a key app at least had a
     * form to draw once the guard moved, while a no-auth app has nothing at all to do and was
     * being refused for the want of an address nobody was ever going to be sent to.
     *
     * Single-user with no sign-in is the one deployment shape that genuinely has no app URL, and
     * it is the shape most likely to be running the apps that need no account.
     */
    const { authorized, connectNoAuth } = brokeredApp(null, AUTHORIZATION_URL, {
      environment: {
        OPENBOT_SINGLE_USER: "true",
        BETTER_AUTH_URL: undefined,
        BETTER_AUTH_SECRET: undefined,
        GOOGLE_OAUTH_CLIENT_ID: undefined,
        GOOGLE_OAUTH_CLIENT_SECRET: undefined,
        INITIAL_ADMIN_EMAILS: undefined,
      },
    });

    const response = await connectNoAuth();

    expect(response.status).toBe(400);
    const refusal = (await response.json()).error as string;
    expect(refusal).toContain("Hacker News");
    expect(refusal).not.toContain("OPENBOT_APP_URL");
    expect(authorized).toEqual([]);
  });

  test("a body carrying values is not a statement about how the app connects", async () => {
    /*
     * THE FORK IS THE SCHEME RECORDED ON THE ROW AND NOTHING IN THE REQUEST, which the consent
     * half asserts for itself and which matters once more here: values in a body must not talk a
     * route into sending somebody's typed secret at an app Composio holds no config for.
     */
    const { asked, submitted, connectNoAuth } = brokeredApp();

    const response = await connectNoAuth({
      values: { api_key: "hn-a-secret" },
    });

    expect(response.status).toBe(400);
    expect(await response.text()).not.toContain("hn-a-secret");
    expect(asked).toEqual([]);
    expect(submitted).toEqual([]);
  });
});

/**
 * Confirming a brokered connection, and ending one.
 *
 * CRITERION. Both routes act on the connection of the person whose session made the request, and on
 * nobody else's, whatever a body or a query says; both refuse a row that is not brokered in so many
 * words; and both tell a deployment with no broker which setting to set.
 *
 * REASON. The store's behaviour is pinned where it is decided — what a confirm writes, what a
 * disconnect revokes — so what is left here is the routing, and the routing is where the damage
 * would be. A user id these handlers could take from a caller turns one DELETE into a revoke of
 * somebody else's grant at the vendor and one POST into a connection recorded under a person who
 * never made one. It is the defect the prior art this design follows shipped three separate times,
 * and the first test of each pair hands the route a body AND a query naming somebody else so that
 * reading either is a failure rather than a silent pass.
 *
 * Neither route is admin-gated, deliberately: an administrator adds the app once and everybody then
 * manages their own account, so `requireUser` is the whole of the gate and the identity is the whole
 * of the scoping.
 */
describe("confirming and ending a brokered connection", () => {
  test("confirm asks about the session's own person, whatever the caller says", async () => {
    const { confirmed, confirm } = brokeredApp({
      connectedAt: "2026-02-02T00:00:00.000Z",
    });

    const response = await confirm({
      body: { userId: SOMEBODY_ELSE.id },
      query: `?userId=${SOMEBODY_ELSE.id}`,
    });

    expect(response.status).toBe(200);
    // The store's answer, passed through rather than restated: `connected` is what the vendor said.
    expect(await response.json()).toEqual({ connected: true });
    expect(confirmed).toEqual([
      { toolkit: "linear", account: ADMIN_ACCOUNT, by: ADMIN.id },
    ]);
  });

  test("disconnect ends the session's own account, whatever the caller says", async () => {
    const { disconnected, disconnect } = brokeredApp({
      connectedAt: "2026-02-02T00:00:00.000Z",
    });

    const response = await disconnect({
      body: { userId: SOMEBODY_ELSE.id },
      query: `?userId=${SOMEBODY_ELSE.id}`,
    });

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({ vendorRevocationRequested: true });
    /*
     * The owner and the actor are the same person, and `reason` is the word that says why. The
     * trail tells this apart from an administrator offboarding somebody by those three fields and
     * by nothing else, so a route that filed `person_removed` here, or named a different owner,
     * would leave a record of an act that did not happen.
     */
    expect(disconnected).toEqual([
      {
        toolkit: "linear",
        account: ADMIN_ACCOUNT,
        by: ADMIN.id,
        reason: "self",
      },
    ]);
  });

  test("an app that is not brokered is refused for what is actually wrong", async () => {
    // `notion` is a row this deployment really has. What is wrong is not that it is missing but
    // that its connection does not live at Composio, and the sentence says so rather than talking
    // about a broker setting or an app nobody has heard of.
    const { confirmed, disconnected, confirm, disconnect } = brokeredApp();

    const confirmResponse = await confirm({ serverId: "notion" });
    const disconnectResponse = await disconnect({ serverId: "notion" });

    expect(confirmResponse.status).toBe(400);
    expect(disconnectResponse.status).toBe(400);
    expect((await confirmResponse.json()).error).toBe(
      "That app doesn't connect this way.",
    );
    expect((await disconnectResponse.json()).error).toBe(
      "That app doesn't connect this way.",
    );
    // And the store was left alone: a confirm here would write a row for an app whose connection
    // is not Composio's to answer about, and a disconnect would ask the broker to revoke a grant
    // it never issued.
    expect(confirmed).toEqual([]);
    expect(disconnected).toEqual([]);
  });

  test("a deployment with no broker is told which setting to set", async () => {
    // The same answer the directory and connect give, for the same reason: nobody was asked, and
    // the remedy is one environment variable long. Answering "not connected" instead would draw a
    // settled state over a deployment that has no broker to have connected anybody at.
    const { confirmed, disconnected, confirm, disconnect } = brokeredApp(
      null,
      null,
    );

    const confirmResponse = await confirm();
    const disconnectResponse = await disconnect();

    expect(confirmResponse.status).toBe(503);
    expect(disconnectResponse.status).toBe(503);
    // A PERSON'S route: no vendor, no variable they cannot set (spec D11).
    for (const refusal of [
      (await confirmResponse.json()).error as string,
      (await disconnectResponse.json()).error as string,
    ]) {
      expect(refusal).toBe(PERSON_UNCONFIGURED);
      expect(refusal).not.toContain("COMPOSIO_API_KEY");
      expect(refusal).not.toMatch(/composio/i);
    }
    expect(confirmed).toEqual([]);
    expect(disconnected).toEqual([]);
  });

  test("a broker that throws reaches both routes as Composio's own sentence", async () => {
    /*
     * NEITHER OF THESE HAD ANY ERROR HANDLING, and there is no framework-level handler behind
     * them, so a wrong key answered both with a bare 500 and put the vendor's whole response
     * object on the console.
     *
     * Confirm is the sharper of the two. It runs on every page load, so the tempting answer to a
     * failure is `{ connected: false }` — which would be this deployment inventing a fact only
     * Composio holds, drawing "Not connected" over a live account and then deleting the row that
     * said otherwise. A failure is not a no.
     */
    const { confirm, disconnect } = brokeredApp(
      { connectedAt: "2026-02-02T00:00:00.000Z" },
      AUTHORIZATION_URL,
      { storeThrows: WRONG_KEY },
    );

    const confirmResponse = await confirm();
    const disconnectResponse = await disconnect();
    const confirmBody = await confirmResponse.text();
    const disconnectBody = await disconnectResponse.text();

    expect(confirmResponse.status).toBe(502);
    expect(disconnectResponse.status).toBe(502);
    expect(JSON.parse(confirmBody).error).toBe("Invalid API key provided.");
    expect(JSON.parse(disconnectBody).error).toBe("Invalid API key provided.");
    // And nothing else that travelled with the failure: the response headers it was carrying are
    // a request id in an error body, which is somebody's trace and nobody's remedy.
    expect(confirmBody).not.toContain("req_a_trace_id_nobody_should_read");
    expect(disconnectBody).not.toContain("req_a_trace_id_nobody_should_read");
  });

  test("a failure the vendor did not explain still says what to do on both routes", async () => {
    // The fallback says what a person can act on rather than guessing how far the call got: what
    // the page shows is the vendor's last answer and not this one, and a disconnect is safe to
    // press again because the revoke runs before anything here is deleted.
    const { confirm, disconnect } = brokeredApp(
      { connectedAt: "2026-02-02T00:00:00.000Z" },
      AUTHORIZATION_URL,
      { storeThrows: new Error("socket hang up") },
    );

    const confirmRefusal = (await (await confirm()).json()).error as string;
    const disconnectRefusal = (await (await disconnect()).json())
      .error as string;

    expect(confirmRefusal).toContain("last answer");
    expect(disconnectRefusal).toContain("Disconnect again");
    expect(confirmRefusal).not.toContain("socket hang up");
    expect(disconnectRefusal).not.toContain("socket hang up");
  });
});

/**
 * Re-checking a brokered connection, which is a button and never a page load.
 *
 * CRITERION. The route acts on the connection of the person whose session made the request whatever
 * a body or a query says; it refuses a row that is not brokered and a deployment with no broker in
 * the same words the other two do; and a probe that RAN AND FAILED reaches the browser as a failure
 * carrying the vendor's sentence rather than as a 200 saying the connection is not verified.
 *
 * REASON. The store decides what a re-check writes and what it refuses; what is left here is the
 * routing, and two things about it would do damage. A user id taken from a caller would spend a
 * stranger's rate limit at the vendor and rewrite the verification on their row from one POST. And
 * an answer of `{ verified: false }` for a probe that ran and was refused would be
 * indistinguishable, to the row drawing it, from an app that publishes nothing to check against —
 * so the Re-check button would quietly disappear for the one person who most needs it, the one who
 * has just fixed their key.
 *
 * IT IS NOT CALLED ON MOUNT, unlike confirm, and nothing here calls it twice. Composio never
 * re-checks a key by itself, so this is the only thing that can; but the call is spent against the
 * person's own quota at the vendor, and verifying on every render would burn it to redraw one word.
 */
describe("re-checking a brokered connection", () => {
  test("the re-check is made about the session's own person, whatever the caller says", async () => {
    const { rechecked, recheck } = brokeredApp({
      connectedAt: "2026-02-02T00:00:00.000Z",
    });

    const response = await recheck({
      body: { userId: SOMEBODY_ELSE.id },
      query: `?userId=${SOMEBODY_ELSE.id}`,
    });

    expect(response.status).toBe(200);
    // The store's answer, passed through: what was checked, when, and with which action.
    expect(await response.json()).toEqual({
      verified: true,
      verifiedAt: "2026-09-13T10:00:00.000Z",
      probe: "LINEAR_GET_ME",
    });
    expect(rechecked).toEqual([
      { toolkit: "linear", account: ADMIN_ACCOUNT, by: ADMIN.id },
    ]);
  });

  test("a probe that ran and failed is a failure, not an answer saying not verified", async () => {
    /*
     * THE MUST-NOT CASE OF THIS ROUTE. The store raises for a key the vendor rejected, and the
     * sentence it raises with carries Composio's own words — so the route has to pass it through as
     * a refusal. Catching it and answering `{ verified: false }` instead would lose the sentence and
     * hand the row a flag it cannot read: the same `false` an app with nothing to probe produces.
     */
    const { recheck } = brokeredApp(
      { connectedAt: "2026-02-02T00:00:00.000Z" },
      AUTHORIZATION_URL,
      {
        storeThrows: new PluginRefusedError(
          "Linear would not answer with the key it is holding: Invalid API key provided. Your connection is recorded here as unchecked until a key that works is entered.",
          null,
        ),
      },
    );

    const response = await recheck();
    const body = await response.text();

    expect(response.status).toBe(400);
    expect(JSON.parse(body).error).toContain("Invalid API key provided.");
    // And it is a refusal rather than an answer: nothing in it for a row to read as a verification.
    expect(JSON.parse(body).verified).toBeUndefined();
  });

  test("an app that is not brokered is refused for what is actually wrong", async () => {
    // `notion` is a row this deployment really has; what is wrong is that its connection does not
    // live at Composio, so there is nothing here to re-check. Same sentence as the other two.
    const { rechecked, recheck } = brokeredApp();

    const response = await recheck({ serverId: "notion" });

    expect(response.status).toBe(400);
    expect((await response.json()).error).toBe(
      "That app doesn't connect this way.",
    );
    expect(rechecked).toEqual([]);
  });

  test("a deployment with no broker is told which setting to set", async () => {
    const { rechecked, recheck } = brokeredApp(null, null);

    const response = await recheck();

    expect(response.status).toBe(503);
    const refusal = (await response.json()).error as string;
    expect(refusal).toBe(PERSON_UNCONFIGURED);
    expect(refusal).not.toMatch(/composio|COMPOSIO_API_KEY/i);
    expect(rechecked).toEqual([]);
  });

  test("a broker that throws reaches the browser as Composio's own sentence", async () => {
    // The other half of the failure mapping: a vendor object is not a refusal this deployment
    // authored, so it comes back as the vendor's sentence at 502 — and nothing else that travelled
    // with it, which is a request id nobody outside Composio can act on.
    const { recheck } = brokeredApp(
      { connectedAt: "2026-02-02T00:00:00.000Z" },
      AUTHORIZATION_URL,
      { storeThrows: WRONG_KEY },
    );

    const response = await recheck();
    const body = await response.text();

    expect(response.status).toBe(502);
    expect(JSON.parse(body).error).toBe("Invalid API key provided.");
    expect(body).not.toContain("req_a_trace_id_nobody_should_read");
  });
});

/**
 * What an administrator is told when removing a server did not finish.
 *
 * CRITERION. `DELETE /servers/:id` answers every refusal its store call can raise, in the words
 * that refusal carries, and never as the framework's bodyless 500.
 *
 * REASON. The route mapped nothing at all, and what it is calling is the loudest method in the
 * store: `removeServer` revokes every person's brokered account at Composio BEFORE it deletes a
 * row, deliberately, so that a failure leaves access dead-and-present rather than live-and-
 * unreachable. Every one of those refusals is authored — a partial revoke naming how many configs
 * went, an auth-config listing Composio described unreadably — and every one of them reached
 * Hono's default handler instead, where a body is not a thing that exists. So the administrator
 * who had just half-withdrawn an app from everybody was told nothing whatever, on the one act in
 * this file whose half-done state somebody has to go and finish by hand.
 */
function removalApp(
  removeServer: () => Promise<never>,
  role: "admin" | "user" = "admin",
) {
  const store = pluginStore({
    removeServer,
    // Every read the plugins surface makes on its way to the route under test.
    listServers: async () => [],
    listSkills: async () => [],
  });

  const app = createApp(
    loadConfig(testEnvironment()),
    {
      handler: () => new Response(null, { status: 204 }),
      api: { getSession: async () => ({ user: ADMIN }) },
    } as never,
    { rolesForUser: async () => [role] },
    // Positions 4-14 are the other stores; `store` is 15, pluginStore.
    ...UP_TO_PLUGIN_STORE,
    store,
  );

  return () =>
    app.request("http://openbot.test/api/plugins/servers/composio-slack", {
      method: "DELETE",
    });
}

describe("removing a server that could not be fully withdrawn", () => {
  test("a partial revoke is the broker's own sentence, not a bodyless 500", async () => {
    /*
     * THE HALF-DONE REMOVAL. `deleteAuthConfig` drops this deployment's own configs one at a time
     * and reports what was left standing, because a config left behind is a live grant the removal
     * was supposed to end. That count is the whole remedy — one of two went, so pressing Remove
     * again asks only for what is left — and it is exactly what an unmapped throw threw away.
     *
     * 503 with the refusal's own words, because a refusal this deployment authored is not a third
     * party being down: Composio answered, this deployment read the answer and decided.
     */
    const sentence =
      "Composio removed 1 of this deployment's 2 authorization configs for slack and the app has " +
      "not been fully withdrawn. Removing it again asks only for what is left.";
    const response = await removalApp(async () => {
      throw new BrokerRefusalError(sentence);
    })();

    expect(response.status).toBe(503);
    expect(await response.json()).toEqual({ error: sentence });
  });

  test("an unreadable auth-config listing reaches the administrator too", async () => {
    // The other loud refusal on this path, and the one whose remedy is NOT the button that was
    // just pressed: a row Composio described with no id and no name will be exactly as unreadable
    // next time, so the sentence names the dashboard instead. A 500 named neither.
    const sentence =
      "Composio described 1 of its authorization configs for slack in a way this deployment " +
      "cannot read, so whether one of them is already its own is not something it can tell.";
    const response = await removalApp(async () => {
      throw new BrokerRefusalError(sentence);
    })();

    expect(response.status).toBe(503);
    expect(((await response.json()) as { error: string }).error).toContain(
      "cannot read",
    );
  });

  test("a contradiction in this deployment's own rows is a 409 in its own words", async () => {
    /*
     * `accessFor` is asked which app this row stands for before anything is revoked, and a row
     * claiming to be two servers at once raises there. It is on the `isDeploymentFault` shelf, so
     * it is answered one branch above the broker mapping — and this route is admin-gated, which is
     * what makes showing that sentence here the right answer.
     */
    const sentence =
      "composio-slack resolves to a brokered credential with no app in its url, so there is " +
      "nothing to ask what it offers.";
    const response = await removalApp(async () => {
      throw new PluginInvariantError(sentence);
    })();

    expect(response.status).toBe(409);
    /*
     * THE BODY WHOLE, which is what pins the ordering. Move the broker mapping above the shelf and
     * this same throw comes back 502 saying "neither this deployment nor Composio said why" about a
     * disagreement between two of this deployment's own columns — sending an operator to check a
     * key that is fine, over a row only they can correct. Nothing else on this route pins that
     * sequence.
     */
    expect(await response.json()).toEqual({ error: sentence });
  });

  test("a failure nobody explained says what to press, and is logged", async () => {
    /*
     * The last class, and the one the default handler used to serve well: a bare `Error` carries
     * no sentence from either side, and an unhandled throw at least put the stack where an
     * operator could find it. Catching it fixes the answer and would silence the log, so the log
     * is kept — the same shape and the same restraint the enable route's is held to.
     *
     * The sentence blames neither side, because this call path is half this deployment's own
     * writes and half the broker's, and which half failed is precisely what nobody said.
     */
    const said: string[] = [];
    const realError = console.error;
    console.error = (...args: unknown[]) => {
      said.push(args.map(String).join(" "));
    };

    try {
      const response = await removalApp(async () => {
        throw Object.assign(new Error("fetch failed"), {
          apiKey: "ak_a_key_nobody_should_read",
        });
      })();

      expect(response.status).toBe(502);
      const refusal = ((await response.json()) as { error: string }).error;
      expect(refusal).toContain("Remove");
      // Never the thrown object's own text: on this path it is as likely to be a stack frame as a
      // sentence, and the console line is what carries it to an operator.
      expect(refusal).not.toContain("fetch failed");
    } finally {
      console.error = realError;
    }

    const line = said.find((said) => said.includes("mcp-server-not-removed"));
    expect(line).toBeDefined();
    expect(line).toContain("composio-slack");
    expect(line).toContain("fetch failed");
    expect(line).not.toContain("ak_a_key_nobody_should_read");
  });

  test("somebody who is not an administrator never reaches the store", async () => {
    let asked = false;
    const response = await removalApp(async () => {
      asked = true;
      throw new Error("unreachable");
    }, "user")();

    expect(response.status).toBe(403);
    expect(asked).toBe(false);
  });
});

describe("enabling an app whose row was written before the failure", () => {
  test("a row that cannot be read back is not Composio's fault", async () => {
    /*
     * WHERE THIS ARRIVES FROM. `addBrokeredApp` creates the auth config, inserts the row and
     * writes its `configuration.changed` trail entry, and only THEN refreshes and reads the row
     * back out of `listServers` — raising {@link CatalogueEntryUnknownError} when it is not
     * there. Every one of those steps has already committed by that point.
     *
     * Unmapped, it fell through to the broker tail, which said "Slack could not be enabled, and
     * Composio said nothing about why. Try again, and check this deployment's Composio key" — a
     * 502 that is wrong three times over: the app WAS enabled, Composio was never involved in the
     * step that failed, and the administrator was sent to check a key that is fine while a row
     * they now hold went unmentioned.
     *
     * This is also the one refusal the three sibling add routes all map and this one did not.
     */
    const { app } = directoryApp(undefined, "admin", [], async () => {
      throw new CatalogueEntryUnknownError("composio-slack");
    });

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ slug: "slack" }),
      },
    );

    // 409 rather than the 400 its siblings give this class: there, an unknown key is a caller
    // naming a server this deployment will not connect to. Here the row was written and this
    // deployment cannot see it, which is two of its own reads disagreeing.
    expect(response.status).toBe(409);
    const refusal = ((await response.json()) as { error: string }).error;
    // What actually happened, which is the half the administrator has to act on: the app is added.
    expect(refusal).toContain("was added");
    // And none of the vendor blame the generic tail carries.
    expect(refusal).not.toContain("could not be enabled");
    expect(refusal).not.toContain("Composio said nothing about why");
    expect(refusal).not.toContain("COMPOSIO_API_KEY");
  });
});

describe("the directory read that is not the vendor's", () => {
  test("a failed query on what is already enabled is a 409, not a 500", async () => {
    /*
     * THE CALL OUTSIDE THE `try`. This route wraps `listApps` — the vendor half — and then reads
     * `serverUrls` to mark which apps are already enabled, outside any mapping at all. A query
     * this database refused there left an administrator with the framework's bodyless 500 on the
     * one screen where a Composio key has just been set, which is the reading most likely to send
     * them back to the key over a fault that has nothing to do with it.
     *
     * The same 409 and the same sentence its sibling admin routes give the shelf, which is the
     * criterion those routes state: every admin route whose store call can reach a fault on the
     * `isDeploymentFault` shelf answers with the sentence rather than leaving it to the default
     * handler.
     */
    const { app } = directoryApp(undefined, "admin", [], null, async () => {
      throw Object.assign(
        new Error(
          'Failed query: select "url" from "mcp_servers" params: composio',
        ),
        {
          query: 'select "url" from "mcp_servers"',
          params: ["composio"],
          cause: new Error("canceling statement due to statement timeout"),
        },
      );
    });

    const response = await app.request(
      "http://openbot.test/api/plugins/composio/apps",
    );

    expect(response.status).toBe(409);
    const refusal = ((await response.json()) as { error: string }).error;
    expect(refusal).toContain("canceling statement due to statement timeout");
    // And none of the statement, for the reason the refresh route's own case gives: an
    // administrator is entitled to the reason, not to the dump.
    expect(refusal).not.toContain("Failed query");
    expect(refusal).not.toContain("mcp_servers");
    // Never the vendor sentence: Composio answered this request perfectly well.
    expect(refusal).not.toContain("COMPOSIO_API_KEY");
  });
});