A local-first multi-agent app development platform, built on PenguinHarness
/**
* The built-in browser's rules in the shell — pure, no Electron imports (unit-tested).
* builtin-browser.ts applies them to the <webview> guests it hosts.
*
* Everything here is mechanism: which guests may attach and with what preferences, which
* navigations a guest may make, the user agent sites see, how a relayed frame is read, which
* permission prompts a page gets, the guests' right-click menu, and how a tab's load is added up
* from its processes. What the browser does with its pages — the page scripts, the tab registry,
* import, what load is too much — is the server platform's (packages/server/src/builtin-browser),
* delivered by push.
*/
import type {
DesktopBrowserCommand,
DesktopBrowserCommandMessage,
DesktopBrowserCookie,
} from "@adelie/server/api";
import type { TrayLocale } from "./tray-menu.js";
/** The guests' own session: independent sign-ins and profile, persisted under userData. */
export const BUILTIN_BROWSER_PARTITION = "persist:penguin-browser";
/** What the shell answers `hello` with; the server learns from it that this shell hosts guests. */
export const BUILTIN_BROWSER_PROTOCOL_VERSION = 1;
function schemeOf(url: string): string | null {
const match = /^([a-z][a-z0-9+.-]*):/i.exec(url.trim());
return match === null ? null : match[1]!.toLowerCase();
}
/**
* Whether a <webview> may attach at all: only in the browser's partition, and only starting on
* a web page or a blank one. An element with no `src` yet starts blank, which is harmless.
*/
export function mayAttachGuest(params: { partition?: string; src?: string }): boolean {
if (params.partition !== BUILTIN_BROWSER_PARTITION) return false;
const src = params.src ?? "";
if (src === "" || src === "about:blank") return true;
const scheme = schemeOf(src);
return scheme === "http" || scheme === "https";
}
/**
* Forces a guest's webPreferences into the one hardened shape, whatever the element's
* attributes asked for: the browser's partition (a `webpreferences` attribute is spread over
* the one `partition` set), no preload and no Node, isolated and sandboxed, web security on,
* no nested <webview>, and no background throttling — the agent works in tabs nobody is
* looking at. Mutates, as `will-attach-webview` expects.
*
* Opaque, too: Electron makes a guest transparent by default, which lets the app's own surface
* show through a page that sets no background of its own — dark text on the dark theme. An
* opaque guest gets the canvas Chrome paints: white, or dark for a page that declares a dark
* color scheme.
*
* Popups are let through to the guest's window-open handler (`disablePopups: false`, which is
* what the `allowpopups` attribute would set): with them disabled Chromium refuses window.open
* and target=_blank before any handler runs, so a popup could never become a tab. The handler
* then denies every one of them (builtin-browser.ts), so no guest ever opens a window.
*/
export function hardenGuestPreferences(prefs: Record<string, unknown>): void {
prefs.partition = BUILTIN_BROWSER_PARTITION;
delete prefs.preload;
delete prefs.preloadURL;
prefs.nodeIntegration = false;
prefs.nodeIntegrationInSubFrames = false;
prefs.nodeIntegrationInWorker = false;
prefs.contextIsolation = true;
prefs.sandbox = true;
prefs.webSecurity = true;
prefs.allowRunningInsecureContent = false;
prefs.webviewTag = false;
prefs.backgroundThrottling = false;
prefs.disablePopups = false;
prefs.transparent = false;
}
/** Schemes a guest's main frame may navigate to on its own (a link, a form, script). */
const NAVIGABLE_SCHEMES = new Set(["http", "https", "about", "data", "blob"]);
export function mayNavigate(url: string): boolean {
const scheme = schemeOf(url);
return scheme !== null && NAVIGABLE_SCHEMES.has(scheme);
}
/**
* The longest `data:` favicon a tab carries. Every tab event carries the icon and the server
* sends the whole tab list to the window on each change, so a page that inlines a large icon
* (or keeps swapping one in) would put it on the wire again and again. A 32-pixel PNG fits.
*/
export const MAX_DATA_FAVICON_CHARS = 4 * 1024;
/** The longest favicon address a tab carries; anything longer is not an address worth sending. */
export const MAX_FAVICON_URL_CHARS = 2 * 1024;
/** The favicon a tab reports: the page's first one small enough to ride every tab event. None rather than a cut one. */
export function pickFavicon(favicons: readonly string[]): string | undefined {
return favicons.find(
(url) =>
url.length > 0 &&
url.length <= (/^data:/i.test(url) ? MAX_DATA_FAVICON_CHARS : MAX_FAVICON_URL_CHARS),
);
}
/** A popup, or a link opened in a new tab, becomes a tab only for a web page. */
export function isOpenableUrl(url: string): boolean {
const scheme = schemeOf(url);
return scheme === "http" || scheme === "https";
}
/**
* The user agent sites see: Chrome's own. Electron's default adds an `Electron/x.y.z` token
* and the app's `<name>/<version>` between `(KHTML, like Gecko)` and `Chrome/`; some sites
* refuse or degrade an embedded browser they can name, so both go. The app name may contain
* spaces (a dev build's "… Dev"), hence everything between the two anchors is dropped rather
* than one token.
*/
export function plainChromeUserAgent(userAgent: string): string {
return userAgent
.replace(/\s+Electron\/\S+/g, "")
.replace(/(\(KHTML, like Gecko\))(?:\s+(?!Chrome\/)\S+)+(?=\s+Chrome\/)/, "$1")
.replace(/\s{2,}/g, " ")
.trim();
}
/** Electron's `clearStorageData` storage names (WebSQL is gone from Chromium, and from the list). */
export type StorageDataName =
| "cookies"
| "filesystem"
| "indexdb"
| "localstorage"
| "shadercache"
| "serviceworkers"
| "cachestorage";
/** The `clearStorageData` names behind each of the protocol's storage categories. */
const STORAGE_DATA: Record<"cookies" | "storage", StorageDataName[]> = {
cookies: ["cookies"],
storage: [
"filesystem",
"indexdb",
"localstorage",
"shadercache",
"serviceworkers",
"cachestorage",
],
};
/** What a `clear-data` command does, or null when it names something that is not a category. */
export function clearDataPlan(
storages: unknown,
): { storageData: StorageDataName[]; cache: boolean } | null {
if (!Array.isArray(storages) || storages.length === 0) return null;
const storageData: StorageDataName[] = [];
let cache = false;
for (const storage of storages as unknown[]) {
if (storage === "cache") cache = true;
else if (storage === "cookies" || storage === "storage") {
storageData.push(...STORAGE_DATA[storage]);
} else return null;
}
return { storageData: [...new Set(storageData)], cache };
}
/**
* The permission prompts a page in the browser is granted without asking. Electron grants
* every request by default, which for pages from the open web would mean a silent camera,
* microphone, location or notification grant; everything outside this list is refused.
* The ones kept are what a page needs to work at all: fullscreen video, pointer and keyboard
* lock in web apps, writing to the clipboard, and storage access for sign-ins spread over
* several sites.
*/
const GRANTED_PERMISSIONS = new Set([
"fullscreen",
"pointerLock",
"keyboardLock",
"clipboard-sanitized-write",
"storage-access",
"top-level-storage-access",
]);
export function isGrantedPermission(permission: string): boolean {
return GRANTED_PERMISSIONS.has(permission);
}
// --- the relay ---------------------------------------------------------------
/** One frame read off the port: a command to run, or one that cannot be (answered with the error). */
export type ParsedBrowserCommand =
{ id: string; command: DesktopBrowserCommand } | { id: string; error: string };
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
/** The most tab ids one command may list: far above any browser's tab count, far below harm. */
const MAX_TABS_LISTED = 1000;
/** The CDP events a tab relays: `Domain.event` names, at most a handful. */
function isEventList(value: unknown): value is string[] {
return (
Array.isArray(value) &&
value.length <= 16 &&
value.every((name) => typeof name === "string" && /^[A-Za-z]+\.[A-Za-z]+$/.test(name))
);
}
function isCookie(value: unknown): value is DesktopBrowserCookie {
return (
isRecord(value) &&
typeof value.url === "string" &&
typeof value.name === "string" &&
typeof value.value === "string"
);
}
/**
* Reads one server frame. Null when it is not a browser command at all (another relay's frame),
* and an `error` when it is one this shell cannot run — every command is answered, so the
* server never waits out a timeout on a frame the shell understood to be for it.
*/
export function parseBrowserCommand(data: unknown): ParsedBrowserCommand | null {
if (!isRecord(data)) return null;
const msg = data as Partial<DesktopBrowserCommandMessage>;
if (msg.type !== "desktop-browser-command" || typeof msg.id !== "string") return null;
const { id } = msg;
const command = msg.command as unknown;
if (!isRecord(command)) return { id, error: "bad_command" };
switch (command.op) {
case "hello":
return { id, command: { op: "hello" } };
case "tabs":
return { id, command: { op: "tabs" } };
case "cdp": {
const { tabId, method, params, events } = command;
if (typeof tabId !== "number" || typeof method !== "string" || method === "") {
return { id, error: "bad_command" };
}
if (params !== undefined && !isRecord(params)) return { id, error: "bad_command" };
if (events !== undefined && !isEventList(events)) return { id, error: "bad_command" };
return {
id,
command: {
op: "cdp",
tabId,
method,
...(params ? { params } : {}),
...(events !== undefined ? { events } : {}),
},
};
}
case "set-cookies": {
const { cookies } = command;
if (!Array.isArray(cookies) || !cookies.every(isCookie)) return { id, error: "bad_command" };
return { id, command: { op: "set-cookies", cookies } };
}
case "clear-data": {
const plan = clearDataPlan(command.storages);
if (plan === null) return { id, error: "bad_command" };
return {
id,
command: {
op: "clear-data",
storages: command.storages as ("cookies" | "cache" | "storage")[],
},
};
}
case "throttle": {
const { tabIds } = command;
if (
!Array.isArray(tabIds) ||
tabIds.length > MAX_TABS_LISTED ||
!tabIds.every((tabId) => typeof tabId === "number" && Number.isSafeInteger(tabId))
) {
return { id, error: "bad_command" };
}
return { id, command: { op: "throttle", tabIds } };
}
default:
return { id, error: "unknown_op" };
}
}
// --- load ------------------------------------------------------------------------
/** How often the shell measures its guests while it has any. */
export const METRICS_INTERVAL_MS = 10_000;
/** One process's load, as the shell measures it. */
export interface ProcessLoad {
pid: number;
/** What the process holds on its own (see `privateMemoryKB`). */
memoryKB: number;
/** Since the previous measurement, in percent of one core. */
cpuPercent: number;
}
/** A tab and the processes behind its page: its own renderer and its cross-site frames'. */
export interface TabProcesses {
tabId: number;
pids: readonly number[];
}
/**
* Each tab's load, the processes behind it added up — a process two tabs share counts in both,
* since closing either would not free it — and the pages' total, where each process counts once.
* A process the measurement no longer lists (it just exited) counts as nothing.
*/
export function tabLoads(
processes: readonly ProcessLoad[],
tabs: readonly TabProcesses[],
): { tabs: { tabId: number; memoryKB: number; cpuPercent: number }[]; totalKB: number } {
const byPid = new Map(processes.map((p) => [p.pid, p]));
const counted = new Set<number>();
let totalKB = 0;
const loads = tabs.map(({ tabId, pids }) => {
let memoryKB = 0;
let cpuPercent = 0;
for (const pid of new Set(pids)) {
const load = byPid.get(pid);
if (load === undefined) continue;
memoryKB += load.memoryKB;
cpuPercent += load.cpuPercent;
if (!counted.has(pid)) {
counted.add(pid);
totalKB += load.memoryKB;
}
}
return { tabId, memoryKB: Math.round(memoryKB), cpuPercent: Math.round(cpuPercent * 10) / 10 };
});
return { tabs: loads, totalKB: Math.round(totalKB) };
}
/** A process's private memory from Linux's `/proc/<pid>/status`: resident anonymous pages plus swap, in KB. */
export function procStatusPrivateKB(status: string): number | null {
const field = (name: string): number | null => {
const match = new RegExp(`^${name}:\\s+(\\d+)\\s+kB`, "m").exec(status);
return match === null ? null : Number(match[1]);
};
const anon = field("RssAnon");
return anon === null ? null : anon + (field("VmSwap") ?? 0);
}
/**
* The memory a process holds on its own, in KB: what the system gets back when it exits. Not its
* working set, which counts the pages every Chromium process shares (libraries, shared memory) in
* each of them — twenty tabs' working sets added up to 8 GB where the kernel charged the app
* 3.3 GB. Linux reads the private anonymous memory and swap from `/proc/<pid>/status` (Chrome's
* own "memory footprint" there), Windows takes the private bytes, and macOS, which offers
* neither here, the working set.
*/
export function privateMemoryKB(
platform: string,
memory: { workingSetSize: number; privateBytes?: number },
procStatus: string | null,
): number {
if (platform === "linux" && procStatus !== null) {
const kb = procStatusPrivateKB(procStatus);
if (kb !== null) return kb;
}
if (platform === "win32" && typeof memory.privateBytes === "number") return memory.privateBytes;
return memory.workingSetSize;
}
// --- the guests' context menu ------------------------------------------------
/** What a guest's context-menu entry does when it is clicked. */
export type GuestMenuAction =
| "back"
| "forward"
| "reload"
| "open-link"
| "copy-link"
| "copy-image-address"
| "cut"
| "copy"
| "paste"
| "select-all"
| "inspect"
| "devtools";
export interface GuestMenuItem {
action?: GuestMenuAction;
label?: string;
/** Absent means enabled. */
enabled?: boolean;
type?: "separator";
}
/** What the menu is built from: Electron's ContextMenuParams, reduced to what it reads, plus the tab's history. */
export interface GuestMenuInput {
locale: TrayLocale;
x: number;
y: number;
linkURL: string;
srcURL: string;
mediaType: string;
isEditable: boolean;
selectionText: string;
editFlags: { canCut: boolean; canCopy: boolean; canPaste: boolean; canSelectAll: boolean };
canGoBack: boolean;
canGoForward: boolean;
}
interface GuestMenuLabels {
back: string;
forward: string;
reload: string;
openLink: string;
copyLink: string;
copyImageAddress: string;
cut: string;
copy: string;
paste: string;
selectAll: string;
inspect: string;
devtools: string;
}
/**
* Written here rather than read from the Web App's catalogs for the tray's reason (see
* tray-menu.ts): the shell cannot import from packages/web. The wording is Chrome's own in
* both languages, since that is the menu people know.
*/
export const GUEST_MENU_LABELS: Record<TrayLocale, GuestMenuLabels> = {
en: {
back: "Back",
forward: "Forward",
reload: "Reload",
openLink: "Open link in new tab",
copyLink: "Copy link address",
copyImageAddress: "Copy image address",
cut: "Cut",
copy: "Copy",
paste: "Paste",
selectAll: "Select all",
inspect: "Inspect",
devtools: "Open DevTools",
},
zh: {
back: "返回",
forward: "前进",
reload: "重新加载",
openLink: "在新标签页中打开链接",
copyLink: "复制链接地址",
copyImageAddress: "复制图片地址",
cut: "剪切",
copy: "复制",
paste: "粘贴",
selectAll: "全选",
inspect: "检查",
devtools: "打开开发者工具",
},
};
/**
* A guest's right-click menu, with only the entries that apply where the click landed, grouped
* the way Chrome groups them: the link, the image, the text (edit commands in a field, Copy
* over a selection), or — on the page itself — Back / Forward / Reload. DevTools closes every
* menu: Inspect at the click, or Open DevTools when the click has no position to inspect.
*/
export function guestContextMenu(input: GuestMenuInput): GuestMenuItem[] {
const t = GUEST_MENU_LABELS[input.locale];
const groups: GuestMenuItem[][] = [];
if (input.linkURL !== "") {
groups.push([
...(isOpenableUrl(input.linkURL)
? [{ action: "open-link" as const, label: t.openLink }]
: []),
{ action: "copy-link", label: t.copyLink },
]);
}
if (input.mediaType === "image" && input.srcURL !== "") {
groups.push([{ action: "copy-image-address", label: t.copyImageAddress }]);
}
const edit: GuestMenuItem[] = [];
const flags = input.editFlags;
if (input.isEditable) {
if (flags.canCut) edit.push({ action: "cut", label: t.cut });
if (flags.canCopy) edit.push({ action: "copy", label: t.copy });
if (flags.canPaste) edit.push({ action: "paste", label: t.paste });
if (flags.canSelectAll) edit.push({ action: "select-all", label: t.selectAll });
} else if (input.selectionText.trim() !== "" && flags.canCopy) {
edit.push({ action: "copy", label: t.copy });
}
if (edit.length > 0) groups.push(edit);
if (groups.length === 0) {
groups.push([
{ action: "back", label: t.back, ...(input.canGoBack ? {} : { enabled: false }) },
{ action: "forward", label: t.forward, ...(input.canGoForward ? {} : { enabled: false }) },
{ action: "reload", label: t.reload },
]);
}
const positioned = Number.isFinite(input.x) && Number.isFinite(input.y);
groups.push([
positioned
? { action: "inspect", label: t.inspect }
: { action: "devtools", label: t.devtools },
]);
return groups.flatMap((group, i) =>
i === 0 ? group : [{ type: "separator" as const }, ...group],
);
}