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.

6.2 KB
Raw Blame
import { generateNonce, sign, type WebBotSigner } from "web-bot-auth";
import { signerFromJWK } from "web-bot-auth/crypto";

/**
 * Signing a Bot's browser requests with the deployment's Web Bot Auth key.
 *
 * The API server holds the key and publishes its public half at
 * `/.well-known/http-message-signatures-directory` (`server/src/web-bot-auth.ts`), then hands the key
 * to each computer alongside the network policy it already pushes. Every request the browser sends
 * then carries three headers, in the form Cloudflare's verifier reads
 * (https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/):
 *
 *   Signature-Agent: "https://openbot.example.com"
 *   Signature-Input: sig1=("@authority" "signature-agent");created=…;keyid="…";alg="ed25519";expires=…;nonce="…";tag="web-bot-auth"
 *   Signature: sig1=:…:
 *
 * `Signature-Agent` is a bare string rather than the dictionary the newer draft uses, because that is
 * what Cloudflare documents and what it verifies. The headers are added inside the browser (see
 * `page-network.ts`), after the request leaves the page and before it reaches the egress filter, so
 * the filter still judges every connection and TLS is still Chromium's own.
 *
 * The key reaching the computer means a Bot's computer can sign as the deployment, which is what it
 * is for. It is a key of its own, derived one way from the deployment key or given separately, so
 * nothing else the deployment holds can be recovered from it, and rotating it is changing
 * `WEB_BOT_AUTH_KEY`.
 */

/** Short, because the signature covers the host and not the request: it is good for any request there. */
const SIGNATURE_LIFETIME_MS = 60_000;

export type WebBotAuthPush = { agent: string; jwk: JsonWebKey };

type Identity = {
  /** The `Signature-Agent` value: the agent URL as a quoted structured-field string. */
  header: string;
  signer: WebBotSigner;
  /** The public key, which is what tells one pushed key from the next. */
  x: string;
};

let current: Identity | null = null;
const listeners = new Set<() => void>();

/** Signing is on. Read on every request, so a push turns it on or off without a restart. */
export function webBotAuthEnabled(): boolean {
  return current !== null;
}

/** Called whenever signing turns on or off, so open pages can follow. */
export function onWebBotAuthChange(listener: () => void): () => void {
  listeners.add(listener);
  return () => listeners.delete(listener);
}

/**
 * Read the `webBotAuth` member of a policy push. Absent or null is off: an API server that predates
 * Web Bot Auth, or one with it switched off, pushes neither.
 */
export function parseWebBotAuthPush(
  input: unknown,
): { ok: true; push: WebBotAuthPush | null } | { ok: false; error: string } {
  if (input === undefined || input === null) return { ok: true, push: null };
  if (typeof input !== "object") {
    return { ok: false, error: "webBotAuth must be an object." };
  }
  const { agent, jwk } = input as { agent?: unknown; jwk?: unknown };
  let url: URL;
  try {
    url = new URL(String(agent));
  } catch {
    return { ok: false, error: "webBotAuth.agent must be a URL." };
  }
  if (url.protocol !== "https:" || url.origin !== agent) {
    return {
      ok: false,
      error: "webBotAuth.agent must be an https origin with no path.",
    };
  }
  const key = jwk as JsonWebKey | undefined;
  if (
    !key ||
    typeof key !== "object" ||
    key.kty !== "OKP" ||
    key.crv !== "Ed25519" ||
    typeof key.d !== "string" ||
    typeof key.x !== "string"
  ) {
    return {
      ok: false,
      error: "webBotAuth.jwk must be an Ed25519 private key.",
    };
  }
  return { ok: true, push: { agent: url.origin, jwk: key } };
}

/** Install the pushed identity, or with null stop signing. */
export async function setWebBotAuth(
  push: WebBotAuthPush | null,
): Promise<void> {
  if (!push) {
    if (current === null) return;
    current = null;
    for (const listener of listeners) listener();
    return;
  }
  const header = JSON.stringify(push.agent);
  if (current && current.x === push.jwk.x && current.header === header) return;
  const signer = await signerFromJWK({
    kty: "OKP",
    crv: "Ed25519",
    d: push.jwk.d,
    x: push.jwk.x,
  });
  const wasOff = current === null;
  current = { header, signer, x: push.jwk.x as string };
  if (wasOff) for (const listener of listeners) listener();
}

/**
 * Apply what a policy push carried. A malformed member turns signing off and says so, rather than
 * refusing the push: the network policy in the same body has to land whatever happens here.
 */
export async function applyWebBotAuthPush(input: unknown): Promise<void> {
  const parsed = parseWebBotAuthPush(input);
  if (!parsed.ok) {
    console.warn(
      JSON.stringify({
        type: "computer-web-bot-auth-refused",
        error: parsed.error,
      }),
    );
  }
  await setWebBotAuth(parsed.ok ? parsed.push : null);
}

const SIGNATURE_HEADERS = new Set([
  "signature",
  "signature-input",
  "signature-agent",
]);

/**
 * The request's headers with this deployment's signature added, or undefined to leave the request as
 * it is (signing off, or a scheme that has no authority to sign).
 *
 * Any signature headers the page set itself are replaced, so a request never carries two
 * `Signature-Agent` values for a verifier to choose between.
 */
export async function signedHeaders(
  method: string,
  url: string,
  headers: Record<string, string>,
  now: Date = new Date(),
): Promise<{ name: string; value: string }[] | undefined> {
  const identity = current;
  if (!identity) return undefined;
  if (!url.startsWith("https:") && !url.startsWith("http:")) return undefined;
  const fields = await sign(
    {
      kind: "request",
      method,
      targetUri: url,
      fields: [{ name: "signature-agent", value: identity.header }],
    },
    {
      signer: identity.signer,
      created: now,
      expires: new Date(now.getTime() + SIGNATURE_LIFETIME_MS),
      nonce: generateNonce(),
    },
  );
  return [
    ...Object.entries(headers)
      .filter(([name]) => !SIGNATURE_HEADERS.has(name.toLowerCase()))
      .map(([name, value]) => ({ name, value })),
    { name: "Signature-Agent", value: identity.header },
    { name: "Signature-Input", value: fields.signatureInput },
    { name: "Signature", value: fields.signature },
  ];
}