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.

22.3 KB
Raw Blame
import { createHash, randomBytes } from "node:crypto";
import { seal, unseal } from "../auth/signed-value";
import { OAUTH_REQUEST_TIMEOUT_MS } from "../timeouts";
import type { CatalogueAuth } from "./catalogue";

/**
 * The connect flow: sending a person to a vendor to consent, and believing what comes back.
 *
 * The browser is in the middle of this, which is the whole difficulty. An authorization code arrives
 * on a request that somebody else's server sent the person to, so nothing on it can be believed on
 * its own — not who is connecting, not which server they meant, not that they ever asked. Two things
 * carry the truth across: a sealed state, which is this deployment's own statement about the request
 * it started, and a PKCE verifier, which proves the code being redeemed belongs to that request.
 *
 * SEALED, not signed, and that distinction is the reason this comment exists. The state carries the
 * PKCE verifier, and the callback URL carries the verifier's state and the authorization code
 * TOGETHER. A dynamically registered client is public — it proves itself with PKCE and no secret —
 * so the verifier is the only thing binding that code to this deployment. A signed state is readable
 * by anybody holding it, and a callback URL is held by every CDN log, proxy log, browser history and
 * vendor log it passes through: any one of those readers could redeem the code. Encrypted, the state
 * says nothing to anybody but this deployment.
 *
 * Everything here fails closed. A state that was tampered with, replayed after it expired, or minted
 * for some other purpose reads back as nothing, because the alternative is attaching one person's
 * Google account to another person's row.
 */

/**
 * The label this deployment's connect states are sealed under.
 *
 * Its own, so a state cannot be opened as a run assertion and vice versa. Every value the deployment
 * hands out under this key would otherwise be a candidate state.
 */
const CONNECT_LABEL = "mcp-oauth-connect";

/**
 * How long somebody has to finish consenting.
 *
 * Long enough to read a consent screen and pick an account, short enough that a link left in a tab
 * overnight is not still redeemable. The state carries no permission by itself, but it does say who
 * the resulting grant gets attached to, which is worth keeping fresh.
 */
const STATE_TTL_MS = 10 * 60_000;

/** The one path a vendor is ever told to send somebody back to. */
const CALLBACK_PATH = "/api/plugins/oauth/callback";

/**
 * Which screen started this, so somebody is returned to the one they left.
 *
 * A closed set of two names, never a URL, and that is the security point rather than a style choice.
 * Carrying a destination through an OAuth flow is how open redirects get built: a
 * `returnTo=https://evil.test` the callback honours turns this deployment into a redirector that
 * arrives with a fresh consent behind it. A name cannot express another origin, and an unrecognised
 * one falls back instead of being followed, so the worst a tampered state achieves is the wrong page
 * of this app.
 *
 * It lives in the SEALED state rather than on the callback URL because the callback is a request
 * somebody else's server sent the browser on. Nothing on it is believable by itself.
 */
export type ConnectOrigin = "settings" | "admin";

export type ConnectState = {
  /** Who is connecting. Taken from their session when the flow starts, never from the callback. */
  userId: string;
  /** Which server they are connecting. Prevents a code for one vendor landing on another's row. */
  serverId: string;
  /**
   * The PKCE verifier, held here rather than in a table because it is single-use and short-lived.
   *
   * It is also why the state is sealed rather than signed: this is a secret travelling beside the
   * code it unlocks, so a state anybody could read would be a code anybody could redeem.
   */
  verifier: string;
  /** Where to go back to. Absent reads as `settings`, which is where every flow used to end. */
  returnTo?: ConnectOrigin;
};

/**
 * What is actually sealed: the state, plus when it stops being one.
 *
 * The expiry travels inside the sealed value because sealing says nothing about freshness. Nobody
 * can move it without the key, and this deployment checks it on the way out.
 */
type SealedState = ConnectState & { exp: number };

/**
 * Where the vendor sends somebody back to.
 *
 * Built from the deployment's own public URL rather than from the incoming request, because this
 * value has to match what an administrator registered with the vendor character for character. A
 * redirect URI assembled from a request header is a redirect URI an attacker has a say in.
 */
export function redirectUriFor(publicUrl: string): string {
  return `${publicUrl.replace(/\/+$/, "")}${CALLBACK_PATH}`;
}

/**
 * Where the callback sends somebody when it is done, succeeded or failed.
 *
 * Absolute, on the app's origin, because the callback lands on the API and those are two different
 * addresses: locally the app is Vite on one port and this server is another. A relative redirect
 * resolves against this server, which serves no pages, so the flow would complete correctly — grant
 * stored, everything right — and drop the person on a 404. Nothing about that reads as a connect
 * failure, which is what makes it worth naming.
 *
 * Relative is still correct for a deployment that serves both from one origin, which is the only
 * case where `appUrl` is absent and the deployment works.
 */
export function connectedAccountsUrlFor(
  appUrl: string | undefined,
  where: { serverId: string } | { failed: true },
  /**
   * Which screen to go back to.
   *
   * An administrator can start this from the connector's own setup page, and sending them to their
   * personal settings afterwards would be the same round trip this was meant to remove — they left a
   * page mid-task and should come back to it. The page they return to shows the same fact either way.
   */
  returnTo: ConnectOrigin = "settings",
): string {
  const origin = appUrl?.replace(/\/+$/, "") ?? "";

  if (returnTo === "admin") {
    /*
     * The admin route takes the server key as its path parameter, so a failure has nowhere generic
     * to land — and a failed state has no key to build one from. Those cases fall through to the
     * settings list below, which is the one screen that draws a failure notice.
     */
    if ("serverId" in where) {
      return `${origin}/admin/plugins/${encodeURIComponent(where.serverId)}`;
    }
  }

  const base = `${origin}/connections`;

  /*
   * Success returns to the account, not the list.
   *
   * That page is where the flow started and it is the page that can now say something new: the
   * account reads Connected, with the scope the vendor granted beside it. The list would only report
   * the same fact one level further away, leaving somebody to find their way back to check.
   *
   * No query parameter either. "It worked" is already told by the thing it is news about, and a
   * banner saying so next to a row that says so is the same sentence twice.
   */
  if ("serverId" in where) {
    return `${base}/${encodeURIComponent(where.serverId)}`;
  }

  /*
   * Failure goes to the list, which is the one screen that draws the notice.
   *
   * It is also the only honest destination when the state could not be read: with no state there is
   * no server id, so there is no account page to return to — and picking one would be a guess about
   * what somebody had been doing.
   */
  return `${base}?connected=failed`;
}

/** A fresh PKCE verifier: unreserved characters only, comfortably over the 43-character floor. */
export function createVerifier(): string {
  return randomBytes(48).toString("base64url");
}

/** The S256 challenge for a verifier. Never `plain`, which would make the challenge worthless. */
export function challengeFor(verifier: string): string {
  return createHash("sha256").update(verifier).digest("base64url");
}

/**
 * The state to send a person to the vendor with.
 *
 * Async because sealing is: the encryption goes through WebCrypto, like every other secret this
 * deployment writes down. It is one call on a path that already makes a network request or two.
 */
export async function sealConnectState(
  state: ConnectState,
  encryptionKey: string,
  now: number = Date.now(),
): Promise<string> {
  const payload: SealedState = { ...state, exp: now + STATE_TTL_MS };
  return seal(JSON.stringify(payload), encryptionKey, CONNECT_LABEL);
}

/**
 * What a state says, or nothing at all.
 *
 * One return for every way of being unacceptable — altered, sealed by another key, sealed for
 * another purpose, expired, malformed, missing a field — because a caller that has to tell those
 * apart is a caller that can get one of them wrong. There is exactly one thing to do with an
 * unusable state, so there is one answer.
 */
export async function readConnectState(
  sealed: string,
  encryptionKey: string,
  now: number = Date.now(),
): Promise<ConnectState | null> {
  const value = await unseal(sealed, encryptionKey, CONNECT_LABEL);
  if (!value) return null;

  try {
    const payload = JSON.parse(value) as Partial<SealedState>;

    if (
      typeof payload.userId !== "string" ||
      !payload.userId ||
      typeof payload.serverId !== "string" ||
      !payload.serverId ||
      typeof payload.verifier !== "string" ||
      !payload.verifier ||
      typeof payload.exp !== "number" ||
      payload.exp <= now
    ) {
      return null;
    }

    return {
      userId: payload.userId,
      serverId: payload.serverId,
      verifier: payload.verifier,
      // Only the one name is recognised; anything else becomes the default rather than being carried.
      returnTo: payload.returnTo === "admin" ? "admin" : "settings",
    };
  } catch {
    return null;
  }
}

/**
 * The six keys that carry this flow's own security: who is asking (`client_id`), where the vendor
 * answers (`redirect_uri`), the grant shape (`response_type`), the sealed state (`state`), and the
 * PKCE proof (`code_challenge`, `code_challenge_method`). A catalogue entry's `authorizationParams`
 * must never rewrite one of these — an entry setting `code_challenge_method: "plain"` would defeat
 * PKCE with nothing here to catch it. The catalogue is frozen, reviewed code today, so nothing can
 * reach this, but a future entry that tried would fail at first connect rather than quietly winning.
 */
const RESERVED_AUTHORIZATION_PARAMS: ReadonlySet<string> = new Set([
  "client_id",
  "redirect_uri",
  "response_type",
  "state",
  "code_challenge",
  "code_challenge_method",
]);

/**
 * The vendor's consent screen, as a URL to send somebody to.
 *
 * Vendor-specific parameters — Google's `offline`/`consent` pair, or nothing at all for a vendor
 * like Notion whose consent screen is itself the scoping — come from the catalogue entry's own
 * `authorizationParams`, never hardcoded here. The rationale for any one vendor's requirements lives
 * on that vendor's entry, because a parameter this function adds for everybody is a parameter an
 * unrelated vendor never asked for and may refuse the whole request over.
 */
export function authorizationUrlFor(input: {
  auth: Extract<CatalogueAuth, { kind: "user-oauth" }>;
  clientId: string;
  redirectUri: string;
  state: string;
  codeChallenge: string;
}): string {
  const url = new URL(input.auth.authorizationUrl);
  const params = new URLSearchParams({
    client_id: input.clientId,
    redirect_uri: input.redirectUri,
    response_type: "code",
    state: input.state,
    code_challenge: input.codeChallenge,
    code_challenge_method: "S256",
  });
  // Empty means the consent screen itself is the scoping; an empty scope= is not "no scope".
  if (input.auth.scopes.length > 0) {
    params.set("scope", input.auth.scopes.join(" "));
  }
  // The vendor's own requirements, from its reviewed entry — never another vendor's.
  for (const [name, value] of Object.entries(
    input.auth.authorizationParams ?? {},
  )) {
    // Applied last, so a reserved name here would quietly rewrite the flow's own security instead
    // of the vendor's. That is a bad entry, and it must fail at first connect, not win silently.
    if (RESERVED_AUTHORIZATION_PARAMS.has(name)) {
      throw new Error(
        `authorizationParams may not set "${name}": it is one of the flow's own security ` +
          "parameters (client_id, redirect_uri, response_type, state, code_challenge, " +
          "code_challenge_method) and must never be rewritten by a catalogue entry.",
      );
    }
    params.set(name, value);
  }
  url.search = params.toString();
  return url.toString();
}

export type RedeemedGrant = {
  refreshToken: string;
  /** What the vendor actually granted, which is not always what was asked for. */
  scope: string;
};

/**
 * Trade an authorization code for the refresh token that stands in for somebody's access.
 *
 * A refusal rather than an exception when the vendor declines, because the most likely causes are
 * ordinary: a redirect URI that does not match what was registered, or somebody taking too long. The
 * vendor's own error body is not passed through — it is written for whoever registered the client and
 * can name the client id.
 */
export async function redeemAuthorizationCode(input: {
  tokenUrl: string;
  clientId: string;
  clientSecret: string;
  code: string;
  redirectUri: string;
  verifier: string;
}): Promise<RedeemedGrant | null> {
  const params = new URLSearchParams({
    grant_type: "authorization_code",
    code: input.code,
    client_id: input.clientId,
    redirect_uri: input.redirectUri,
    code_verifier: input.verifier,
  });
  // A public (DCR) client proves itself with PKCE, and some vendors refuse an unexpected empty field.
  if (input.clientSecret) params.set("client_secret", input.clientSecret);

  /*
   * Our own catalogue, told apart from their outage before a request is attempted.
   *
   * `fetch` refuses a malformed URL by throwing the same kind of error a refused connection does,
   * so without this the two would reach the same catch and read as the same sentence. They are not
   * the same thing: one is a vendor having a bad day and the other is an endpoint in this
   * deployment's own catalogue that nobody can ever connect through. The person gets the ordinary
   * refusal either way, because there is nothing else to give them, and the log is where the
   * difference has to survive.
   *
   * Checking it here is also what leaves the catch below covering only the transport, rather than
   * quietly standing in for a mistake in a frozen literal.
   */
  if (!URL.canParse(input.tokenUrl)) {
    console.error(
      JSON.stringify({
        type: "oauth-token-endpoint-unusable",
        tokenUrl: input.tokenUrl,
        note: "This vendor's token endpoint is not a usable address, so nobody can connect it until the catalogue is fixed.",
      }),
    );
    return null;
  }

  /*
   * A vendor that could not be reached at all, which the refusal below cannot see.
   *
   * `!response.ok` needs a response, and there is none when the connection is refused, the name does
   * not resolve, TLS will not agree, or the timeout on this request fires. Unguarded, that rejection
   * escaped a function whose whole contract is to refuse quietly, and it escaped at the worst
   * available moment: the callback has no failure handler above it, so somebody who had just
   * consented at the vendor got a bare 500 with no Location instead of Settings telling them it did
   * not work. The same reasoning as the defensive read further down, one step earlier in the request.
   *
   * Nothing is read off the error. Which of those it was is a fact about the vendor's infrastructure
   * on a route that answers an unauthenticated caller, and the person is told the same sentence
   * either way.
   */
  let response: Response;
  try {
    response = await fetch(input.tokenUrl, {
      method: "POST",
      headers: { "content-type": "application/x-www-form-urlencoded" },
      body: params,
      /*
       * A redirect is a refusal, not a detour to be followed.
       *
       * `tokenUrl` is pinned in the catalogue because this request carries a client secret and an
       * authorization code, and following a 302 would hand both to whatever address the answer named.
       * Manual leaves the 3xx as the response, which is not `ok`, so it falls into the refusal below.
       */
      redirect: "manual",
      signal: AbortSignal.timeout(OAUTH_REQUEST_TIMEOUT_MS),
    });
  } catch (error) {
    /*
     * Logged, because refusing quietly to the person must not mean refusing quietly to the
     * deployment. Until this, an unreachable token endpoint reached Hono's default handler, which
     * prints the error before its 500; catching it without a line here would have bought the
     * redirect by making a vendor outage look exactly like nobody trying to connect.
     *
     * The status is what a person sees and this is what an operator sees, and only the second one
     * says which vendor and why. Neither the code nor the client secret is in a transport error:
     * they are in the request body, which never got sent.
     */
    console.error(
      JSON.stringify({
        type: "oauth-token-endpoint-unreachable",
        tokenUrl: input.tokenUrl,
        note: "A person's consent could not be redeemed. They were sent back to Settings with a failure.",
        error: String(error),
      }),
    );
    return null;
  }

  if (!response.ok) return null;

  /*
   * Read defensively, because a 200 is not a promise of JSON.
   *
   * A CDN interstitial, a captive portal or a maintenance page answers 200 with HTML, and an
   * unguarded parse would throw a SyntaxError out of a function whose whole contract is to refuse
   * quietly — escaping the callback as a 500 instead of the redirect-with-a-notice a person who has
   * just consented should get, and quoting the vendor's body into whatever logged the throw.
   */
  const body = (await response.json().catch(() => null)) as {
    refresh_token?: unknown;
    scope?: unknown;
  } | null;
  /*
   * No refresh token is a failure, not a partial success.
   *
   * It is what a vendor returns when it believes this person already consented, and storing the
   * access token instead would produce a connection that works for an hour and then cannot be
   * renewed — the worst of the three outcomes, because it looks like success. A body that was not
   * JSON at all arrives here as nothing, which is the same answer: the vendor said something other
   * than a token.
   */
  if (typeof body?.refresh_token !== "string" || !body.refresh_token) {
    return null;
  }

  return {
    refreshToken: body.refresh_token,
    /*
     * Capped where it is read. It is a short string in the protocol and vendor-controlled in fact,
     * and everything downstream shows it to somebody — the connected-accounts page, the
     * `mcp.account_connected` payload, the `scope` column — none of which is a promise about length.
     */
    scope: typeof body.scope === "string" ? body.scope.slice(0, 512) : "",
  };
}

/**
 * Register this deployment as an OAuth client, at the vendor's own registration endpoint.
 *
 * RFC 7591, the shape Notion's hosted MCP expects: a public client (`token_endpoint_auth_method:
 * "none"`) whose proof is PKCE rather than a secret. Null on refusal rather than a throw, for the
 * same reason `redeemAuthorizationCode` refuses quietly: the vendor's error body is written for a
 * developer console and can be surfaced by the caller that knows who is listening.
 */
export async function registerDynamicClient(input: {
  registrationUrl: string;
  redirectUri: string;
}): Promise<{ clientId: string; clientSecret: string } | null> {
  // The same catalogue check the redemption makes, and for the same reason: a registration endpoint
  // that is not an address is this deployment's mistake, not the vendor's outage, and only the log
  // can tell them apart.
  if (!URL.canParse(input.registrationUrl)) {
    console.error(
      JSON.stringify({
        type: "oauth-registration-endpoint-unusable",
        registrationUrl: input.registrationUrl,
        note: "This vendor's registration endpoint is not a usable address, so this deployment can never introduce itself.",
      }),
    );
    return null;
  }

  // A vendor that could not be reached at all — see `redeemAuthorizationCode`, which states the same
  // gap in full. This one lands on an administrator pressing Connect rather than on somebody
  // mid-consent, and null is what turns it into the 502 that route already writes for a vendor that
  // would not register us.
  let response: Response;
  try {
    response = await fetch(input.registrationUrl, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        redirect_uris: [input.redirectUri],
        grant_types: ["authorization_code", "refresh_token"],
        response_types: ["code"],
        token_endpoint_auth_method: "none",
        client_name: "OpenBot",
      }),
      // The registration endpoint is pinned in the catalogue, so a redirect is somebody else deciding
      // where this deployment introduces itself. Left as the response, which is not `ok`.
      redirect: "manual",
      signal: AbortSignal.timeout(OAUTH_REQUEST_TIMEOUT_MS),
    });
  } catch (error) {
    // Logged for the same reason the redemption above is: the caller's 502 tells an administrator
    // to check the vendor's status, and this is the line that says the vendor could not be reached
    // at all rather than that it turned us down.
    console.error(
      JSON.stringify({
        type: "oauth-registration-endpoint-unreachable",
        registrationUrl: input.registrationUrl,
        note: "This deployment could not introduce itself to the vendor. Connect answered 502.",
        error: String(error),
      }),
    );
    return null;
  }
  if (!response.ok) return null;
  // A 200 is not a promise of JSON — see `redeemAuthorizationCode`. A body that will not parse is
  // the vendor answering with something other than a client, which is this function's null.
  const body = (await response.json().catch(() => null)) as {
    client_id?: unknown;
    client_secret?: unknown;
  } | null;
  if (typeof body?.client_id !== "string" || !body.client_id) return null;
  return {
    clientId: body.client_id,
    // A public client has none; a vendor that issues one anyway gets it stored and sent back.
    clientSecret:
      typeof body.client_secret === "string" ? body.client_secret : "",
  };
}