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.

20.4 KB
Raw Blame
import type { Hono, MiddlewareHandler } from "hono";
import type { BotAccessCheck } from "../../agents/profile-policy";
import type { AppVariables } from "../../auth/guards";
import { BROKERED_PROFILE, type BrokerProvider } from "../access";
import type { AccountModeSwitch } from "../account-mode";
import {
  type AuthorizationFlow,
  BrokerReturnUrlError,
  brokerSentence,
  type ComposioBroker,
} from "../broker";
import { vendorSentence } from "../composio";
import type { AccountRef } from "../shared-accounts";
import type { SharedUseStore } from "../shared-use-store";
import type { PluginStore } from "../store";

/**
 * What the plugin route groups share. See `../routes.ts`, which builds one of these and mounts
 * every group on it in order.
 */

/**
 * Whether the person a consent was started for still has access to this deployment.
 *
 * A seam rather than an import, because these routes have no business knowing what a person is or
 * where the deny list lives — and because the answer has to come from the deployment as it is when
 * the callback lands, not from what was true when the flow started.
 *
 * False for somebody who was removed while they were away at the vendor's consent screen, and false
 * for a user id that names nobody at all. Both are the same refusal: there is no live person for
 * this grant to belong to.
 */
export type ConnectingPersonCheck = (userId: string) => Promise<boolean>;

/**
 * What somebody is told when the broker itself failed, and what is deliberately kept out of it.
 *
 * EVERY BROKERED ROUTE NEEDS THIS AND NONE OF THEM USED TO HAVE IT. A listing, a connect, a confirm
 * and a disconnect all end in a call to another company's API, and an unhandled rejection out of any
 * of them is a bare 500 with the vendor's thrown object on this deployment's console. That object is
 * the whole HTTP response — headers, trace ids, rate-limit counters — and the person reading the 500
 * gets none of it and no sentence either. A wrong `COMPOSIO_API_KEY` is the first failure a new
 * operator meets, and it is the one this used to answer worst.
 *
 * `vendorSentence` IS THE SAME ONE THE TRANSPORT USES, for the same reason it exists there: the
 * useful sentence — "Invalid API key", "No connected account found for user …" — is nested two
 * levels inside `cause` beside everything that must not be shown, so this reaches in for that one
 * string and takes nothing else. Null from it is a failure this deployment cannot explain, and the
 * caller's own generic sentence is what a reader gets instead of the vendor's placeholder.
 *
 * NOTHING FROM THE REQUEST OR THE ANSWER TRAVELS WITH IT. Not the API key, which never leaves the
 * adapter; not a connect link, which is a bearer capability handed to one browser; and not the
 * thrown object, whether by spreading it, stringifying it or logging it.
 *
 * 502 RATHER THAN 500, because nothing here broke: this deployment asked a third party and the third
 * party did not answer usefully, which is the same reading the dynamic-registration failure below
 * already gives.
 *
 * `./broker`'s `BrokerRefusalError` IS THE EXCEPTION, AND IT IS A WIDER ONE THAN IT WAS. It used to
 * be the one no-key state; it is now every refusal the broker layer AUTHORED — no key, an app whose
 * authorization config this deployment never created or cannot use, a consent the vendor answered
 * with nowhere to send anybody, a catalogue too large to be sure of. All of them share the property
 * that made the first one special: Composio answered, this deployment decided, and the sentence
 * already names the step that fixes it. So the message is passed through and the status stays 503,
 * which reads correctly for every one of them — the brokered surface is unavailable for this app
 * until somebody changes something here, rather than unavailable because a third party is down. The
 * generic sentence below is for failures this deployment genuinely cannot explain, and answering one
 * of these with it would tell an administrator to check a key that is fine.
 */
export function brokerRefusal(
  error: unknown,
  generic: string,
): { error: string; status: 502 | 503 } {
  const authored = brokerSentence(error);
  if (authored) return { error: authored, status: 503 };
  return { error: vendorSentence(error) ?? generic, status: 502 };
}

/**
 * A return address this deployment could not use, said once where an operator will read it.
 *
 * THE REMEDY AND THE READER HAD COME APART, WHICH IS WHAT THIS CLOSES. Both routes that check a
 * return address are `requireUser`, so the sentence they answer with reaches somebody who pressed
 * Connect — and `OPENBOT_APP_URL` is a variable they cannot set, named beside a vendor they may not
 * even be on. {@link BrokerReturnUrlError} answers them with neither now, which would leave the
 * operator's half nowhere at all if it were not written here: a misconfigured address would be
 * invisible to the one person who can correct it.
 *
 * A LOG AND NOT A RESPONSE, because that is the difference between the two readers. The log is the
 * operator's screen, and the sentence it carries is the error's own — written in `./broker`, naming
 * the ACTIVE provider, and quoting no address, which is the promise that makes it safe to write
 * down at all. Anything else thrown past this is somebody else's to explain, so it is ignored here
 * rather than logged generically.
 */
export function logReturnUrlRefusal(error: unknown, serverId: string): void {
  if (!(error instanceof BrokerReturnUrlError)) return;
  console.error(
    JSON.stringify({
      type: "broker-return-url-unusable",
      serverId,
      note: error.operatorMessage,
    }),
  );
}

/**
 * What a reader is told when the active broker would not answer with its directory.
 *
 * One function because two routes make that call — browsing the catalogue and enabling an app out of
 * it — and a reader meeting the same failure through two doors should not meet two sentences. It
 * names the setting rather than quoting it: a key that was pasted with a space in it, or one for
 * another project, is the likeliest reason the vendor will not talk to this deployment at all.
 *
 * THE VENDOR AND ITS SETTING COME OFF THE ACTIVE PROVIDER'S PROFILE, because the client shows the
 * server's sentence in preference to its own fallback: a sentence that spelled one broker was read
 * by an operator of the other.
 */
export function directoryUnavailable(provider: BrokerProvider): string {
  const { vendor, envVar } = BROKERED_PROFILE[provider];
  return `${vendor} would not answer with its app directory, and said nothing about why. Check that ${envVar} is this project's key, and check ${vendor}'s status if it persists.`;
}

/**
 * Where a browser with no session is sent when it lands on the verifier, carrying what it arrived
 * with.
 *
 * ABSOLUTE ON THE APP'S ORIGIN, for the reason {@link connectedAccountsUrlFor} is: the verifier
 * lands on the API and the sign-in screen is a page, and locally those are two different ports — a
 * relative `Location` would resolve against this server, which serves no pages at all. A deployment
 * that serves both from one origin has no `appUrl`, and relative is correct there.
 *
 * THE HANDLE TRAVELS AS ITSELF AND NOT AS A RETURN ADDRESS. A `next=` parameter holding a URL is a
 * redirect target somebody else gets a say in; this carries the one opaque value the return leg
 * arrived with, so signing back in as the same person has everything it needs to resume and nothing
 * it could be pointed elsewhere with. Encoded, because it is somebody else's id and this deployment
 * does not know what is in it.
 */
export function signInUrlFor(
  appUrl: string | undefined,
  flowId: string,
): string {
  const base = `${appUrl?.replace(/\/+$/, "") ?? ""}/sign`;
  return flowId ? `${base}?flow_id=${encodeURIComponent(flowId)}` : base;
}

/**
 * WHY THE VERIFIER REFUSED, AS AN OPAQUE CODE — and the CLOSED SET of them.
 *
 * THE CODE TRAVELS AND THE SENTENCE DOES NOT. Each of these is rendered by the connected-accounts
 * list, which holds the words; a message rendered from a query string is a message anybody can
 * author on this deployment's own origin, and the code is also what keeps the copy in ONE place
 * rather than in two that drift. The parameter is `?authorized=`, a channel of its own: `?connected=`
 * belongs to the Composio OAuth callback and is neither reused nor widened here.
 *
 * ASSERTED AS A SET so another cannot be added without a test going red, and so the app's own map
 * can be held to exactly the same list.
 */
export const AUTHORIZATION_REFUSALS = [
  // This deployment reaches no broker at all, so there is no return leg to verify.
  "no-broker",
  // The broker it reaches declares no correlated authorization flow.
  "not-supported",
  // The link arrived without the part that says which authorization it finishes.
  "missing-handle",
  // Nothing USABLE of this person's is waiting: never started, expired, another session's, a mint
  // that never answered with an id, or a row that cannot say whose account it is for.
  "no-attempt",
  // The vendor was asked and did not answer.
  "vendor-unavailable",
  // The link, or the authorization behind it, is not the one this person is holding.
  "not-your-authorization",
  // The consent has not finished at the vendor yet. The attempt is LEFT STANDING for a retry.
  "not-finished",
  // The vendor says the authorization did not complete.
  "authorization-failed",
  // The app's account context moved on while the consent was open (D28).
  "context-changed",
  // The person can no longer act on the app's account — a Shared app's administrator was demoted,
  // or the app itself stopped resolving to an account — so the consent was closed and nothing moved.
  "not-permitted",
  // The attempt was cancelled, or otherwise ended, while its return leg was being finished.
  "cancelled",
  // The same, except the grant the return carried was not withdrawn — doing so would have ended a
  // connection nobody asked to end, or the withdrawal was not confirmed — so the vendor may still
  // allow the cancelled action.
  "cancelled-left-live",
  // This deployment could not write what it had, so it wrote none of it.
  "not-recorded",
] as const;

export type AuthorizationRefusal = (typeof AUTHORIZATION_REFUSALS)[number];

/** Whether two account references name the same account, holder included. */
export function sameAccount(left: AccountRef, right: AccountRef): boolean {
  if (left.vendorUserId !== right.vendorUserId) return false;
  if (left.holder === "person") {
    return right.holder === "person" && left.userId === right.userId;
  }
  return right.holder === "deployment";
}

/**
 * A BROKER CALL THAT DID NOT ANSWER INSIDE ITS BOUND, AND CARRYING NOTHING OF THE VENDOR'S (D31).
 *
 * The message names this deployment's own bound and the thrown object has no `cause`, deliberately:
 * a call that times out on the return leg is a call whose answer would have carried a LIVE provider
 * access token and a full profile, and the one thing certain about a half-read answer is that
 * nobody has narrowed it yet. So there is nothing here to attach, log or quote — which is the same
 * promise {@link brokerRefusal} makes about the vendor's own errors, kept by having no vendor
 * material to begin with.
 *
 * It is an ordinary `Error` to every reader of it: `brokerSentence` does not author it and
 * `vendorSentence` finds no nested body, so every call site below answers it with its OWN generic
 * sentence and a 502 — "we asked and got nothing back", which is exactly what happened.
 *
 * NOT EXPORTED, because nothing outside this file should be branching on it: every exit it can
 * reach is already one of this file's own refusals, and a caller matching on the class would be
 * re-deciding what the catch blocks here have decided.
 */
class VendorTimeoutError extends Error {
  constructor(afterMs: number) {
    super(`The broker did not answer within ${afterMs}ms.`);
    this.name = "VendorTimeoutError";
  }
}

/**
 * How long ONE outbound call to the broker may take before this deployment stops waiting on it.
 *
 * EVERY CALL OUT OF THIS FILE GOES THROUGH {@link withVendorDeadline}, and that is the invariant
 * rather than the number. A bound on how MANY times something is attempted is not a bound at all
 * while each attempt is unbounded: a vendor that accepts the connection and then never writes a
 * byte holds the socket, the handler and the browser open for as long as it cares to, and no retry
 * limit, poll count or loop condition is ever reached because the first wait never ends.
 */
const VENDOR_CALL_TIMEOUT_MS = 10_000;

/**
 * The same bound on ONE return-leg status poll, and tighter because a browser is held open on it.
 *
 * Five polls at two seconds with four one-second pauses is a worst case of FOURTEEN seconds for the
 * whole wait, and that arithmetic is the point of stating both numbers here.
 */
export const STATUS_CALL_TIMEOUT_MS = 2_000;

/**
 * At most five polls, pausing BETWEEN them — so four pauses, not five. NEVER the SDK's unbounded
 * `waitForCompletion`.
 */
const STATUS_POLLS = 5;
const STATUS_PAUSE_MS = 1000;

/**
 * One outbound vendor call under a deadline, with an `AbortSignal` for the seams that take one.
 *
 * THE SIGNAL IS THE HALF THAT MATTERS UPSTREAM AND THE RACE IS THE HALF THAT MATTERS HERE. The race
 * is what lets the handler answer and the browser go; aborting is what stops this deployment from
 * holding a socket open against a vendor it has already given up on, and the seams that can carry
 * a signal take it (see {@link AuthorizationFlow}). A seam that cannot is still bounded by the
 * race — a timeout is a timeout to the person waiting either way — and its call is simply
 * abandoned rather than cancelled.
 *
 * THE TIMER IS CLEARED ON BOTH OUTCOMES. A pending timer on a call that answered in time would keep
 * an event loop alive for the rest of the bound, which in a test run is a suite that will not exit
 * and in a deployment is a handler that has returned still holding a reason not to.
 *
 * NOTHING IS RETRIED HERE. A deadline that retried would be the very shape this fix exists to
 * remove, one layer up.
 */
export function withVendorDeadline<T>(
  call: (signal: AbortSignal) => Promise<T>,
  afterMs: number = VENDOR_CALL_TIMEOUT_MS,
): Promise<T> {
  const controller = new AbortController();
  let timer: ReturnType<typeof setTimeout> | undefined;
  const deadline = new Promise<never>((_resolve, reject) => {
    timer = setTimeout(() => {
      controller.abort();
      reject(new VendorTimeoutError(afterMs));
    }, afterMs);
  });
  /*
   * A CALL THAT THROWS BEFORE IT RETURNS A PROMISE IS A REJECTION, NOT AN ESCAPE. The deadline is
   * already armed by this line, so invoking `call` bare inside the race would let a synchronous
   * throw — `brokerReturnUrl` refusing a scheme-less `OPENBOT_APP_URL` while the callback builds its
   * argument is the one that happens — leave this function before the race and its `.finally`
   * exist: the timer stays armed, aborts nothing anybody is waiting on and rejects `deadline` with
   * no one subscribed, and a caller's `.catch(...)` on the returned promise is skipped entirely.
   * Calling it inside an executor turns that throw into this promise's rejection, still
   * synchronously and still exactly once.
   */
  const answer = new Promise<T>((resolve) => resolve(call(controller.signal)));
  /*
   * `Promise.race` subscribes to both, so a call that answers AFTER the deadline has its rejection
   * observed here and never surfaces as an unhandled one. Its answer is dropped unread, which is
   * also the D31-safe thing to do with it.
   */
  return Promise.race([answer, deadline]).finally(() => {
    if (timer !== undefined) clearTimeout(timer);
  });
}

/**
 * Where one authorization has got to, waited for with a BOUND ON THE WHOLE WAIT AND ON EACH CALL.
 *
 * `pending` is the only state worth asking again about, and five polls at two seconds each with a
 * one-second pause between them — at most fourteen seconds, and the pauses are BETWEEN the polls,
 * so four of them and not five — is the whole of the patience this has. A timeout is neither a
 * success nor a failure, so what comes back is the last answer read and the caller decides; nothing
 * here writes, retries forever or blocks a browser on a vendor that has stopped answering.
 *
 * THE POLL COUNT ALONE NEVER BOUNDED ANYTHING. It bounded how many times `flow.status` was CALLED,
 * while each call waited as long as the vendor liked — so a vendor that accepted the connection and
 * never answered held this request open forever, which is the one case the paragraph above claims
 * to prevent. {@link withVendorDeadline} is what makes the claim true, and a poll that spends its
 * own bound THROWS rather than counting: a vendor that will not answer in two seconds is a vendor
 * that is not answering, and the caller's `vendor-unavailable` refusal leaves the attempt row
 * standing exactly as the exhausted-polls refusal does.
 *
 * WHAT COMES BACK IS THE SEAM'S THREE FIELDS AND NOTHING MORE (D31). The vendor's own status reply
 * carries a live provider access token and the person's full profile; the adapter drops them, and
 * this function must never widen what it hands on, log it, or attach it as a `cause`.
 */
export async function settledStatus(
  flow: AuthorizationFlow,
  id: string,
): Promise<Awaited<ReturnType<AuthorizationFlow["status"]>>> {
  const poll = () =>
    withVendorDeadline(
      (signal) => flow.status(id, { signal }),
      STATUS_CALL_TIMEOUT_MS,
    );
  let answer = await poll();
  for (
    let polls = 1;
    polls < STATUS_POLLS && answer.status === "pending";
    polls += 1
  ) {
    await new Promise((resolve) => setTimeout(resolve, STATUS_PAUSE_MS));
    answer = await poll();
  }
  return answer;
}

/** What the connect flow needs that the store does not hold. See `createPluginRoutes`. */
export type PluginConnectOptions = {
  encryptionKey: string;
  /**
   * Whether the person a state names may still connect an account here.
   *
   * Required rather than optional, unlike everything else that arrived on this object as "one more
   * parameter". The callback is sessionless on purpose, so this is the ONLY thing asking whether
   * the identity in the state is still one this deployment recognises — and a deployment that
   * forgot to pass it would complete a consent for somebody who was removed ten minutes ago and
   * write a live refresh token nothing will ever revoke.
   */
  personHasAccess: ConnectingPersonCheck;
  /**
   * Whether this deployment holds a shared secret a Bot may present when calling a tool back.
   *
   * A boolean about configuration, never the secret. Without it, a Bot can only call back if it
   * holds a credential issued to it alone, and a Bot with neither is refused before the call ever
   * reaches the grant, the boundary or the trail. The Bots screen needs this to stop promising a
   * grant the deployment cannot honour.
   */
  botsMayCallBack?: boolean;
  publicUrl: string | undefined;
  /**
   * Where the app is, which is not where this API is.
   *
   * The callback lands here and has to send the person back to a page. A relative redirect would
   * put them on this server's origin, which locally is a Vite-less port that serves no pages at
   * all — so the flow would complete correctly and end on a 404.
   */
  appUrl: string | undefined;
};

/**
 * Everything a group of plugin routes is mounted with: the router they are added to, what
 * `createPluginRoutes` was given, and the per-request helpers more than one group asks.
 */
export type PluginRouteContext = {
  routes: Hono<{ Variables: AppVariables }>;
  store: PluginStore;
  requireUser: MiddlewareHandler<{ Variables: AppVariables }>;
  canUseBot: BotAccessCheck;
  connect: PluginConnectOptions | undefined;
  composio: { broker: ComposioBroker; provider: BrokerProvider } | undefined;
  shared: { modes: AccountModeSwitch; use: SharedUseStore } | undefined;
  /** The provider this deployment's brokered rows belong to. See `createPluginRoutes`. */
  activeProvider: BrokerProvider;
  /** {@link activeProvider}'s name as the sentences on this layer spell it. */
  activeVendor: string;
  /** Which app a brokered row is, read by {@link activeProvider}'s own parser. */
  appOfUrl: (url: string) => string | null;
  actorEmail: (context: { var: AppVariables }) => string;
  skillActor: (context: { var: AppVariables }) => {
    id: string;
    isAdmin: boolean;
  };
  skillRefusal: (
    context: { var: AppVariables },
    slug: string,
  ) => Promise<string | null>;
};