getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/browser-handover.ts

@@ -0,0 +1,175 @@
+import type { BrowserHandoverInput, HandoverKey, HandoverMod } from '../../shared/types.ts';
+import { HANDOVER_KEYS } from '../../shared/util.ts';
+import { HttpError } from './store.ts';
+
+/*
+ * The owner's handover of a Boton's browser, as pure parts: what an input may be, and the limits on how often. The
+ * owner signs a Boton's browser in (or looks at a page) themselves, from one paired device, while the Boton can't
+ * use it; browser.ts runs it, as a live view (a screencast) the owner drives with fixed inputs a person makes: open an
+ * address, back, forward, reload; the pointer's moves, presses and clicks at a point; the wheel; text typed or pasted;
+ * one key, with Shift, or with Control only for editing (EDIT_COMBOS); a copy of the owner's own selection; the page's
+ * size following the view. Nothing runs the page's script for it, reads its cookies or reaches Chromium's DevTools for
+ * the page: the one read is a copy, of the selection alone (never from a password field), in a world of its own the
+ * page's script can't reach, and its text goes only to the device that drives it. Typed and pasted text goes into the
+ * page and nowhere else: never into a message, the log, the journal, the audit or an error, which say only that text
+ * was typed.
+ *
+ * Network authority while the owner has the browser: it loads reads (GET, HEAD) from the Boton's sites as at any
+ * time, and sends what a page sends otherwise (a sign-in form's POST, a script's) only to those sites and only within
+ * INTENT_MS of the owner's own press, click, key, typing or paste (never a move, a wheel or a resize): a page's
+ * background request (a poll, a beacon) made at any other moment is refused, and nothing goes after the owner
+ * finishes. Opening an address, going back or forward and reloading
+ * end that moment at once and cut what the page had open, so what a page sends as it unloads is refused too. The
+ * proxy decides this for every request as it leaves, HTTPS included (it ends that browser's TLS itself), whatever in
+ * Chromium sent it; Chromium's routing also refuses, where it sees them, writes from a worker or from a page the
+ * owner is not on. Within the moment the proxy can't tell which of them sent a write: it goes, and is journaled.
+ * The Boton has no say in any of it: its browser tools are refused for as long as the handover lasts.
+ */
+
+/** The page's size until the owner's view says otherwise: clicks are in these coordinates, and frames are this size. */
+export const VIEWPORT = { width: 1280, height: 800 } as const;
+/** The sizes the page may take to fit the owner's view (a phone's narrow sheet up to a large screen). */
+export const VIEWPORT_MIN = { width: 320, height: 320 } as const;
+export const VIEWPORT_MAX = { width: 1920, height: 1400 } as const;
+/** The most text one input types, and one paste puts in. */
+export const MAX_OWNER_TEXT = 1000;
+export const MAX_PASTE = 5000;
+/** The most of a selection one copy gives back to the owner's device. */
+export const MAX_COPY = 20_000;
+/** After the owner's click, key or typing, how long what the page sends because of it may go. */
+export const INTENT_MS = 10_000;
+/** A handover with no input and no view open for this long ends on its own, and the Boton has its browser back. */
+export const IDLE_MS = 10 * 60_000;
+/** And it ends after this long, whatever happens: a forgotten tab doesn't keep the Boton's browser. */
+export const MAX_HANDOVER_MS = 30 * 60_000;
+/** At most one polled frame in this long (and one at a time): the fallback when the live view can't stream. */
+export const FRAME_MIN_MS = 200;
+/** At most this many inputs in INPUT_WINDOW_MS: enough to type and move the pointer as a person does. */
+export const MAX_INPUTS = 600;
+export const INPUT_WINDOW_MS = 10_000;
+
+const ACTIONS = ['open', 'resume', 'click', 'down', 'up', 'move', 'wheel', 'type', 'paste', 'copy', 'key', 'scroll', 'back', 'forward', 'reload', 'resize'] as const;
+const MODS: readonly HandoverMod[] = ['Shift', 'Control', 'Meta'];
+/**
+ * With Control (or Meta, which is Control here): only editing inside the page, never a browser shortcut (address bar,
+ * tabs, print, save, find, devtools). Copy and paste are inputs of their own: a copy reads only the owner's selection,
+ * a paste types the owner's text.
+ */
+const EDIT_COMBOS = new Set(['a', 'z', 'y', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Backspace', 'Delete', 'Home', 'End']);
+
+/** The page's size for a view of `width` × `height` CSS pixels: whole pixels within the bounds. */
+export function fitViewport(width: number, height: number): { width: number; height: number } {
+  const fit = (v: number, min: number, max: number) => Math.min(max, Math.max(min, Math.round(Number.isFinite(v) ? v : min)));
+  return { width: fit(width, VIEWPORT_MIN.width, VIEWPORT_MAX.width), height: fit(height, VIEWPORT_MIN.height, VIEWPORT_MAX.height) };
+}
+
+/**
+ * An input as the API received it, checked: a fixed action with values in range, or 400. The messages are fixed
+ * words: they never repeat what was sent (it may be a password). Points are in the page's CSS pixels (browser.ts keeps
+ * them inside the page's current size).
+ */
+export function parseOwnerInput(raw: unknown): BrowserHandoverInput {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new HttpError(400, 'Send an input as an object');
+  const v = raw as Record<string, unknown>;
+  if (typeof v.handover !== 'string' || !/^ho_[A-Za-z0-9_-]{8,40}$/.test(v.handover)) throw new HttpError(400, 'handover must be the id of the handover');
+  const handover = v.handover;
+  const action = v.action;
+  if (typeof action !== 'string' || !(ACTIONS as readonly string[]).includes(action)) throw new HttpError(400, `action must be one of ${ACTIONS.join(', ')}`);
+  const int = (x: unknown, min: number, max: number, what: string) => {
+    if (typeof x !== 'number' || !Number.isFinite(x) || x < min || x > max) throw new HttpError(400, `${what} must be a number from ${min} to ${max}`);
+    return Math.round(x);
+  };
+  const point = () => ({ x: int(v.x, 0, VIEWPORT_MAX.width - 1, 'x'), y: int(v.y, 0, VIEWPORT_MAX.height - 1, 'y') });
+  const button = () => {
+    if (v.button === undefined) return 'left' as const;
+    if (v.button !== 'left' && v.button !== 'right' && v.button !== 'middle') throw new HttpError(400, 'button must be left, right or middle');
+    return v.button;
+  };
+  const text = (max: number, lines: boolean) => {
+    const t = v.text;
+    if (typeof t !== 'string' || !t.length) throw new HttpError(400, `${action} needs text`);
+    if (t.length > max) throw new HttpError(400, `${action} takes at most ${max} characters at a time`);
+    // Keys are pressed with `key`: control characters are refused, not typed (a paste may hold new lines and tabs).
+    if ((lines ? /[\u0000-\u0008\u000b-\u001f\u007f]/ : /[\u0000-\u001f\u007f]/).test(t)) {
+      throw new HttpError(400, lines ? 'paste takes text without control characters' : 'type takes text without new lines or control characters (press Enter or Tab with key)');
+    }
+    return t;
+  };
+  switch (action as (typeof ACTIONS)[number]) {
+    case 'open': {
+      if (typeof v.url !== 'string' || !v.url.trim() || v.url.length > 2000) throw new HttpError(400, 'open needs an address (at most 2000 characters)');
+      return { handover, action: 'open', url: v.url.trim() };
+    }
+    case 'click': {
+      const count = v.count === undefined ? 1 : int(v.count, 1, 3, 'count');
+      return { handover, action: 'click', ...point(), ...(count > 1 ? { count } : {}) };
+    }
+    case 'down':
+    case 'up': {
+      // The press's count (a double or triple click is the second or third press in a row).
+      const count = v.count === undefined ? 1 : int(v.count, 1, 3, 'count');
+      return { handover, action: action as 'down' | 'up', ...point(), button: button(), ...(count > 1 ? { count } : {}) };
+    }
+    case 'move':
+      return { handover, action: 'move', ...point() };
+    case 'wheel':
+      return { handover, action: 'wheel', ...point(), dx: int(v.dx ?? 0, -4000, 4000, 'dx'), dy: int(v.dy ?? 0, -4000, 4000, 'dy') };
+    case 'type':
+      return { handover, action: 'type', text: text(MAX_OWNER_TEXT, false) };
+    case 'paste':
+      return { handover, action: 'paste', text: text(MAX_PASTE, true) };
+    case 'copy':
+      return { handover, action: 'copy' };
+    case 'resume':
+      return { handover, action: 'resume' };
+    case 'key': {
+      const key = v.key;
+      const named = typeof key === 'string' && HANDOVER_KEYS.includes(key as HandoverKey);
+      if (!named && !(typeof key === 'string' && /^[a-z]$/.test(key))) throw new HttpError(400, `key must be one of ${HANDOVER_KEYS.join(', ')}, or a letter with Control`);
+      const raw = v.mods === undefined ? [] : v.mods;
+      if (!Array.isArray(raw) || raw.length > MODS.length || raw.some((m) => !MODS.includes(m as HandoverMod)) || new Set(raw).size !== raw.length) {
+        throw new HttpError(400, `mods must be some of ${MODS.join(', ')}`);
+      }
+      const mods = raw as HandoverMod[];
+      const control = mods.includes('Control') || mods.includes('Meta');
+      if (control && !EDIT_COMBOS.has(key as string)) throw new HttpError(400, 'That shortcut is not sent to the page: only editing ones (select all, undo, redo, word and line moves)');
+      if (!named && !control) throw new HttpError(400, 'Letters are typed with type, not pressed with key');
+      if (key === 'Shift+Tab' && mods.length) throw new HttpError(400, 'Shift+Tab takes no other keys');
+      return { handover, action: 'key', key: key as HandoverKey | string, ...(mods.length ? { mods } : {}) } as BrowserHandoverInput;
+    }
+    case 'scroll':
+      return { handover, action: 'scroll', dy: int(v.dy, -4000, 4000, 'dy') };
+    case 'back':
+      return { handover, action: 'back' };
+    case 'forward':
+      return { handover, action: 'forward' };
+    case 'reload':
+      return { handover, action: 'reload' };
+    case 'resize':
+      return { handover, action: 'resize', width: int(v.width, 1, 10_000, 'width'), height: int(v.height, 1, 10_000, 'height') };
+  }
+}
+
+/** The key as Playwright presses it, its modifiers first (Meta is Control here: the owner's Mac shortcut on Chromium for Linux). */
+export const pressed = (k: string, mods: readonly HandoverMod[] = []): string => {
+  const key = k === 'Space' ? ' ' : k;
+  const held = [...new Set(mods.map((m) => (m === 'Meta' ? 'Control' : m)))].sort((a, b) => MODS.indexOf(a) - MODS.indexOf(b));
+  return [...held, key].join('+');
+};
+
+/** At most `limit` takes in any `ms`. */
+export class RateWindow {
+  #times: number[] = [];
+  #limit: number;
+  #ms: number;
+  constructor(limit: number, ms: number) {
+    this.#limit = limit;
+    this.#ms = ms;
+  }
+  take(now = Date.now()): boolean {
+    this.#times = this.#times.filter((t) => now - t < this.#ms);
+    if (this.#times.length >= this.#limit) return false;
+    this.#times.push(now);
+    return true;
+  }
+}

package/payload/server/src/browser-policy.ts

@@ -0,0 +1,210 @@
+import { isIP } from 'node:net';
+import type { AccessLevel, BrowserPolicy, BrowserPolicyInput } from '../../shared/types.ts';
+import { BROWSER_CONNECTOR, MAX_BROWSER_SITES } from '../../shared/util.ts';
+import { allowance, refusedAddress } from './ssrf.ts';
+import { HttpError } from './store.ts';
+
+/*
+ * The managed browser's rules, as pure functions: which sites a Boton's browser may reach, and that it only reads
+ * (GET and HEAD). The browser (browser.ts) enforces them where the Boton can't reach: in the server's own proxy,
+ * which every request the browser makes goes through, and in its request routing, before a request leaves Chromium.
+ */
+
+export const NO_BROWSER: BrowserPolicy = { sites: [], updatedAt: null };
+
+/**
+ * A new Boton's browser (blank, from a template or a starter): on, for any public site. "*" never covers this machine
+ * or a private network (covers), and every write still waits on the owner's card.
+ */
+export const NEW_BOTON_SITES = ['*'];
+
+/** A new Boton's connectors with the built-in browser among them (first, as the catalog lists it). */
+export function withBrowser(ids: string[]): string[] {
+  return ids.includes(BROWSER_CONNECTOR) ? ids : [BROWSER_CONNECTOR, ...ids];
+}
+
+/** Whether a brain can run the managed browser: only an agent CLI's turns drive it (an API key brain's tools can't). */
+export const drivesBrowser = (provider: { cli?: unknown } | null | undefined): boolean => !!provider?.cli;
+
+/**
+ * A new Boton's connectors: the ones the request names, exactly; otherwise `saved` (a template's, those this server
+ * has) with the browser, when its brain can run one (drivesBrowser), and without it when it can't.
+ */
+export const newBotonConnections = (asked: string[] | undefined, saved: string[], browser: boolean): string[] =>
+  asked ?? (browser ? withBrowser(saved) : saved.filter((id) => id !== BROWSER_CONNECTOR));
+
+/** Whether a Boton given the browser has one: not on a server found to have no Chromium (its turns go without it). */
+export const browserUsable = (enabled: boolean, known: { available: boolean } | null): boolean => enabled && known?.available !== false;
+
+const MAX_SITES = MAX_BROWSER_SITES;
+const HOST = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+const LOCAL_NAME = /(^|\.)localhost$/;
+
+/** A site entry: "*", "example.com" (and its subdomains), or "host:port" (exactly that address). */
+export interface Site {
+  any: boolean;
+  host: string;
+  port: number | null;
+}
+
+function parseHostPort(entry: string): { host: string; port: number | null } | null {
+  const v6 = /^\[([0-9a-f:.]+)\](?::(\d{1,5}))?$/.exec(entry);
+  if (v6) return isIP(v6[1]) === 6 ? { host: v6[1], port: v6[2] ? Number(v6[2]) : null } : null;
+  const m = /^([^:/\s]+)(?::(\d{1,5}))?$/.exec(entry);
+  if (!m) return null;
+  const host = m[1].replace(/\.$/, '');
+  if (!isIP(host) && !HOST.test(host)) return null;
+  const port = m[2] ? Number(m[2]) : null;
+  if (port !== null && (port < 1 || port > 65535)) return null;
+  return { host, port };
+}
+
+export function parseSite(raw: string): Site | null {
+  const entry = raw.trim().toLowerCase();
+  if (entry === '*') return { any: true, host: '', port: null };
+  const hp = parseHostPort(entry.replace(/^\*\./, ''));
+  return hp ? { any: false, ...hp } : null;
+}
+
+/** Literal loopback, private or reserved addresses, and localhost names: the host's own services. */
+export function isPrivateHost(host: string): boolean {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+  if (LOCAL_NAME.test(h)) return true;
+  if (isIP(h)) return refusedAddress(h, allowance([])) !== null;
+  return false;
+}
+
+export const siteText = (s: Site): string => (s.any ? '*' : `${s.host.includes(':') ? `[${s.host}]` : s.host}${s.port ? `:${s.port}` : ''}`);
+
+/**
+ * Whether `site` covers host:port. A name covers itself and its subdomains on any port; an address only itself;
+ * with a port, only that port. "*" covers any public host, never a private one.
+ */
+export function covers(site: Site, host: string, port: number): boolean {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  if (site.any) return !isPrivateHost(h);
+  if (site.port !== null && site.port !== port) return false;
+  if (h === site.host) return true;
+  return !isIP(site.host) && !isIP(h) && h.endsWith(`.${site.host}`);
+}
+
+/** The entry that lets the browser reach host:port, or null. A private host needs an entry that names its port. */
+export function siteFor(sites: string[], host: string, port: number): Site | null {
+  const priv = isPrivateHost(host);
+  for (const raw of sites) {
+    const s = parseSite(raw);
+    if (!s || !covers(s, host, port)) continue;
+    if (priv && s.port === null) continue;
+    return s;
+  }
+  return null;
+}
+
+/**
+ * Whether a site entry may name loopback or private addresses: only with a port, and for a Workspace Boton only one the
+ * operator allowed. "*" is any public site at either access: it never covers a private one.
+ */
+function siteProblem(s: Site, access: AccessLevel, allowPrivate: string[]): string | null {
+  if (s.any) return null;
+  if (!isPrivateHost(s.host)) return null;
+  if (s.port === null) return `${siteText(s)} is this machine or a private network: name it with its port (host:port)`;
+  if (access !== 'host' && !allowPrivate.includes(siteText(s))) {
+    return `${siteText(s)} is this machine or a private network, which a Workspace Boton's browser can't reach (BOTONS_BROWSER_ALLOW can allow one address)`;
+  }
+  return null;
+}
+
+function cleanSites(v: unknown, field: string, access: AccessLevel, allowPrivate: string[]): string[] {
+  if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) throw new HttpError(400, `${field} must be a list of sites such as example.com`);
+  const out: string[] = [];
+  for (const raw of v as string[]) {
+    if (!raw.trim()) continue;
+    const s = parseSite(raw);
+    if (!s) throw new HttpError(400, `${field}: "${raw.slice(0, 100)}" is not a site: use a host name such as example.com, or host:port`);
+    const problem = siteProblem(s, access, allowPrivate);
+    if (problem) throw new HttpError(400, `${field}: ${problem}`);
+    const text = siteText(s);
+    if (!out.includes(text)) out.push(text);
+  }
+  if (out.length > MAX_SITES) throw new HttpError(400, `${field}: at most ${MAX_SITES} sites`);
+  return out;
+}
+
+/** The owner's change, checked against the Boton's access. */
+export function applyPolicy(before: BrowserPolicy, input: BrowserPolicyInput, access: AccessLevel, allowPrivate: string[]): BrowserPolicy {
+  if (!input || typeof input !== 'object') throw new HttpError(400, 'Send the browser settings as an object');
+  const sites = input.sites === undefined ? before.sites : cleanSites(input.sites, 'sites', access, allowPrivate);
+  return { sites, updatedAt: new Date().toISOString() };
+}
+
+/**
+ * The sites as they apply under `access` now: a Boton moved to Workspace access loses the private addresses the
+ * operator didn't allow, without the owner having to edit its list.
+ */
+export function effectiveSites(sites: string[], access: AccessLevel, allowPrivate: string[]): string[] {
+  return sites.filter((raw) => {
+    const s = parseSite(raw);
+    return !!s && siteProblem(s, access, allowPrivate) === null;
+  });
+}
+
+export function parsePolicy(raw: string | undefined): BrowserPolicy {
+  if (!raw) return { ...NO_BROWSER };
+  try {
+    const v = JSON.parse(raw);
+    const list = (x: unknown) => (Array.isArray(x) ? x.filter((s): s is string => typeof s === 'string') : []);
+    return { sites: list(v.sites), updatedAt: typeof v.updatedAt === 'string' ? v.updatedAt : null };
+  } catch {
+    return { ...NO_BROWSER };
+  }
+}
+
+/** What the browser may do with one request: load it, or refuse it with why (`write`: a write to an allowed site, which a card may let through once). */
+export type RequestVerdict = { ok: true } | { ok: false; why: string; write?: true };
+
+/**
+ * The browser reads on its own: anything else (a form, a script's POST, a beacon, a CORS preflight for one) is refused
+ * before it leaves Chromium, and again in the proxy for plain HTTP. The one way past is the owner's card: while the
+ * Boton clicks or types, the first write to an allowed site is held, shown in full and sent once if allowed
+ * (browser.ts, browser-request.ts).
+ */
+export const READ_METHODS = new Set(['GET', 'HEAD']);
+
+/** Requests that change something, which the browser sends only through a card. Anything else not a read is refused. */
+export const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+export function portOf(u: URL): number {
+  return u.port ? Number(u.port) : u.protocol === 'https:' || u.protocol === 'wss:' ? 443 : 80;
+}
+
+export const hostOf = (u: URL) => u.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+
+/** For the journal and the cards: never a query, fragment or credentials, which may be secrets. */
+export function displayUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    if (u.protocol === 'about:' || u.protocol === 'data:' || u.protocol === 'blob:') return `${u.protocol}…`;
+    return `${u.protocol}//${u.host}${u.pathname}${u.search ? '?…' : ''}`;
+  } catch {
+    return '(not a URL)';
+  }
+}
+
+/** A request the page makes: only http(s) to allowed sites, and only reads. Where the browser is off, see browser.ts. */
+export function judgeRequest(raw: string, method: string, sites: string[]): RequestVerdict {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return { ok: false, why: 'not a URL' };
+  }
+  if (u.protocol === 'data:' || u.protocol === 'blob:' || u.protocol === 'about:') return { ok: true };
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, why: `${u.protocol} addresses are not for the browser` };
+  if (u.username || u.password) return { ok: false, why: 'an address with a user name or password in it' };
+  const host = hostOf(u);
+  const port = portOf(u);
+  if (!siteFor(sites, host, port)) return { ok: false, why: `${u.host} is not one of the allowed sites` };
+  const m = method.toUpperCase();
+  if (!READ_METHODS.has(m)) return { ok: false, why: `a ${m} request to ${u.host}: the browser only reads pages, unless you allow one on a card`, ...(WRITE_METHODS.has(m) ? { write: true as const } : {}) };
+  return { ok: true };
+}