Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

11.4 KB
Raw Blame
/**
 * The policy the gateway is currently enforcing, and the ability to change it while running.
 *
 * It survives a restart. A rule held only in memory vanishes the next time the process comes up, and
 * the trail shows it being added without showing that it stopped applying. A reader would believe a
 * boundary held at a moment when it did not, and a form going through after a restart is
 * indistinguishable from a rule that never applied.
 *
 * Memory is the cache, and the table is the record. The gateway asks for the policy on every single
 * action, so `get` stays synchronous and reads from memory; the write goes through to the database
 * and the memory copy is only updated once it has. A store that answered from the database on every
 * click would put a query on the path of every keystroke a Bot makes.
 *
 * Memory is a cache of a shared record, not a per-process copy of it. OpenBot runs several servers
 * behind a load balancer, and an administrator's new rule arrives at exactly one of them. Kept only
 * in that process, the rule applies to roughly one action in N while the admin screen and the audit
 * row both report success, which is the boundary silently not applying: the failure this whole file
 * exists to prevent, in a different shape. So a write announces itself on Postgres and every server
 * re-reads. Same mechanism as channel activity, for the same reason.
 *
 * Without a database it still works in memory. Tests that only care about decision logic do not need
 * Postgres.
 */
import { eq, sql } from "drizzle-orm";
import type { Database } from "../db/client";
import { actionPolicy } from "../db/schema";
import type { ActionPolicy, RuleLabel } from "./policy";

/** There is one boundary per deployment, so there is one row. */
const CURRENT = "current";

/**
 * What a server announces on when the boundary changes, and what every server listens to.
 *
 * The payload is deliberately empty: it says "re-read", not what to read. A rule list can outgrow
 * NOTIFY's 8000-byte cap, and a listener that took the payload as truth would be enforcing whatever
 * fitted rather than what was saved.
 */
export const ACTION_POLICY_TOPIC = "action_policy_changed";

/**
 * What a deployment allows when it has not said otherwise.
 *
 * Permissive, and written down rather than implied. The policy engine is fail-closed: an absent
 * policy denies, and a broken rule denies. This default is a separate decision, and it is deliberately
 * an explicit `allow` rather than a special "unconfigured" case, because a Bot that can look at a page
 * and touch nothing is not a product, and the first thing a person does is ask it to fill something in.
 *
 * Out of the box, OpenBot lets a Bot act, records every action and gives an administrator somewhere
 * to write the first restriction.
 */
export const DEFAULT_ACTION_POLICY: ActionPolicy = {
  mode: "enforce",
  deny: [],
  allow: ["true"],
};

export type PolicyStore = {
  /** Synchronous on purpose: this is asked on every action. */
  get: () => ActionPolicy;
  /** Persisted before the in-memory copy changes, so a reported success is a saved rule. */
  set: (policy: ActionPolicy, by?: string) => Promise<void>;
  /** Back to what configuration says, forgetting the saved one. */
  reset: () => Promise<void>;
  /** Read the saved policy at boot. Returns where the live policy came from. */
  load: () => Promise<"the database" | "configuration">;
  /**
   * Re-read because another server changed it.
   *
   * Separate from `load` so the caller reads as what it is. `load` reports where the policy came
   * from for the boot audit row; this is the running deployment keeping up.
   */
  refresh: () => Promise<void>;
};

export function createPolicyStore(
  initial: ActionPolicy,
  /** Absent keeps everything in memory, which is what a test without a database wants. */
  database?: Database,
): PolicyStore {
  const configured = clone(initial);
  let current = clone(initial);

  return {
    get: () => current,

    set: async (policy, by) => {
      const next = clone(policy);
      if (database) {
        // Written before it is enforced. If the write fails this throws and the caller reports a
        // failure, which is the honest outcome: an administrator who is told a rule was saved must
        // not be enforcing a rule that will disappear at the next restart.
        //
        // The announcement goes in the same transaction, so it is delivered on commit: a write that
        // rolls back announces nothing, and there is no window where the row has changed and the
        // other servers have not been told. Same shape as `channels/routes.ts`.
        await database.transaction(async (transaction) => {
          await transaction
            .insert(actionPolicy)
            .values({
              id: CURRENT,
              mode: next.mode,
              deny: next.deny,
              allow: next.allow,
              labels: next.labels ?? {},
              updatedBy: by ?? null,
              updatedAt: new Date(),
            })
            .onConflictDoUpdate({
              target: actionPolicy.id,
              set: {
                mode: next.mode,
                deny: next.deny,
                allow: next.allow,
                labels: next.labels ?? {},
                updatedBy: by ?? null,
                updatedAt: new Date(),
              },
            });

          // Every server hears it, including this one, which re-reads and arrives at what it
          // already has.
          await announce(transaction);
        });
      }
      current = next;
    },

    reset: async () => {
      // The saved policy is removed rather than overwritten with the configured one, so "reset" means
      // this deployment has no boundary of its own again, and changing what configuration says then
      // changes what it enforces, which is what an operator expects of a reset.
      if (database) {
        await database.transaction(async (transaction) => {
          await transaction
            .delete(actionPolicy)
            .where(eq(actionPolicy.id, CURRENT));
          await announce(transaction);
        });
      }
      current = clone(configured);
    },

    load: async () => {
      if (!database) return "configuration";
      const [row] = await database
        .select()
        .from(actionPolicy)
        .where(eq(actionPolicy.id, CURRENT))
        .limit(1);
      if (!row) return "configuration";

      current = fromRow(row);
      return "the database";
    },

    refresh: async () => {
      if (!database) return;
      const [row] = await database
        .select()
        .from(actionPolicy)
        .where(eq(actionPolicy.id, CURRENT))
        .limit(1);

      // No row means somebody reset it, and reset means this deployment goes back to what
      // configuration says. Leaving the last saved rules in memory here would make a reset apply on
      // the server that served it and nowhere else, which is the bug this function exists to fix.
      current = row ? fromRow(row) : clone(configured);
    },
  };
}

/**
 * Tell every server the boundary moved.
 *
 * Never fatal. The rule is already saved and this process is already enforcing it, so a failed
 * announcement costs the other servers their update until their next restart, which is worth a loud
 * log and is not worth failing a write an administrator has been told succeeded.
 */
async function announce(database: Pick<Database, "execute">): Promise<void> {
  try {
    await database.execute(sql`select pg_notify(${ACTION_POLICY_TOPIC}, '')`);
  } catch (error) {
    console.error(
      JSON.stringify({
        type: "action-policy-notify-failed",
        note: "The boundary was saved but other servers were not told. They keep enforcing the previous rules until they restart.",
        error: String(error),
      }),
    );
  }
}

function clone(policy: ActionPolicy): ActionPolicy {
  return {
    mode: policy.mode,
    deny: [...policy.deny],
    allow: [...policy.allow],
    ...(policy.labels ? { labels: { ...policy.labels } } : {}),
  };
}

function fromRow(row: typeof actionPolicy.$inferSelect): ActionPolicy {
  return {
    mode: row.mode as ActionPolicy["mode"],
    deny: [...row.deny],
    allow: [...row.allow],
    labels: { ...row.labels },
  };
}

const MAX_LABEL_NAME = 80;
const MAX_LABEL_DESCRIPTION = 300;

/**
 * Each rule's name and description, kept only for rules the policy still has.
 *
 * A label for a rule that is not in either list is dropped rather than refused: it is what removing a
 * rule from a policy read moments ago leaves behind, and it can never be shown against anything.
 */
function parseLabels(
  input: unknown,
  rules: string[],
):
  | { ok: true; labels: Record<string, RuleLabel> }
  | { ok: false; error: string } {
  if (input === undefined) return { ok: true, labels: {} };
  if (!input || typeof input !== "object" || Array.isArray(input)) {
    return { ok: false, error: "labels must map each rule to a name." };
  }
  const known = new Set(rules);
  const labels: Record<string, RuleLabel> = {};
  for (const [rule, value] of Object.entries(input)) {
    const label = value as Partial<RuleLabel> | null;
    const name = typeof label?.name === "string" ? label.name.trim() : "";
    const description =
      label?.description === undefined
        ? ""
        : typeof label.description === "string"
          ? label.description.trim()
          : null;
    if (!name || name.length > MAX_LABEL_NAME) {
      return {
        ok: false,
        error: `Each rule needs a name of at most ${MAX_LABEL_NAME} characters.`,
      };
    }
    if (description === null || description.length > MAX_LABEL_DESCRIPTION) {
      return {
        ok: false,
        error: `A rule's description must be at most ${MAX_LABEL_DESCRIPTION} characters.`,
      };
    }
    if (known.has(rule)) labels[rule] = { name, description };
  }
  return { ok: true, labels };
}

/**
 * Validate a policy that arrived over HTTP.
 *
 * Rejects rather than coerces. A policy is the thing standing between a Bot and somebody's live
 * website, and "we accepted your rule but not in the shape you wrote it" is the one behaviour that
 * must never happen here: an operator would believe a restriction is in force when it is not.
 *
 * Expressions are NOT validated for correctness on the way in, only for being strings. Whether a rule
 * is meaningful is the policy engine's business, it fails closed there, and pre-validating here would
 * mean two parsers to keep in agreement.
 */
export function parseActionPolicy(
  input: unknown,
): { ok: true; policy: ActionPolicy } | { ok: false; error: string } {
  if (!input || typeof input !== "object") {
    return { ok: false, error: "A policy must be an object." };
  }
  const candidate = input as Record<string, unknown>;

  const mode = candidate.mode;
  if (mode !== "enforce" && mode !== "dry-run") {
    return {
      ok: false,
      error: 'mode must be "enforce" or "dry-run".',
    };
  }

  const lists: Record<"deny" | "allow", string[]> = { deny: [], allow: [] };
  for (const key of ["deny", "allow"] as const) {
    const value = candidate[key] ?? [];
    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
      return { ok: false, error: `${key} must be a list of expressions.` };
    }
    lists[key] = value as string[];
  }

  const labels = parseLabels(candidate.labels, [...lists.deny, ...lists.allow]);
  if (!labels.ok) return labels;

  return {
    ok: true,
    policy: {
      mode,
      deny: lists.deny,
      allow: lists.allow,
      labels: labels.labels,
    },
  };
}