@ricsam/r5d-browser 0.0.137 → 0.0.139

package/dist/mjs/personal-main.mjs

@@ -0,0 +1,159 @@
+import { PersonalPortForwardManager, PersonalForwardResponseError } from "./personal-port-forward.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { BrowserRuntime } from "./browser-runtime.mjs";
+import { launchStableChrome } from "./chrome-launcher.mjs";
+import { BrowserKeeper } from "./runtime/keeper.mjs";
+import { browserRuntimeExecutor } from "./runtime/browser-executor.mjs";
+import { PersonalBrowserProcessor } from "./personal-relay-client.mjs";
+import { assertPrivatePath, readPrivateFile } from "./runtime/private-paths.mjs";
+import { PersonalBrowserRelayShutdown } from "./personal-relay-shutdown.mjs";
+import { browserErrorCategory, personalBrowserDiagnosticObserver } from "./personal-diagnostics.mjs";
+const Binding = z.object({ origin: z.string(), installationId: z.string(), userId: z.string(), resourceId: z.string(), instanceId: z.string() }).strict();
+function atomicJson(filename, value) {
+  const temporary = `${filename}.${randomUUID()}.next`;
+  const fd = fs.openSync(temporary, "wx", 384);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(value));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temporary, filename);
+  const directory = fs.openSync(path.dirname(filename), "r");
+  try {
+    fs.fsyncSync(directory);
+  } finally {
+    fs.closeSync(directory);
+  }
+}
+function personalBrowserConnection(options) {
+  const config = fs.existsSync(options.configPath) ? JSON.parse(readPrivateFile(fs.realpathSync(options.configPath), 128e3).toString()) : {};
+  const value = options.baseUrl ?? process.env.R5D_BASE_URL ?? process.env.R5DCTL_BASE_URL ?? config.baseUrl ?? "https://r5d.dev";
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.origin !== String(value).replace(/\/+$/, "") || url.username || url.password) throw new Error("Personal browser requires an HTTPS server origin");
+  const token = options.token ?? process.env.R5D_BROWSER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
+  if (typeof token !== "string" || !token) throw new Error("Run r5dctl auth login or supply --token/--api-key");
+  return { origin: url.origin, token };
+}
+function personalBrowserStateDirectory(origin, rootPath) {
+  const base = rootPath === void 0 ? path.join(fs.realpathSync(os.homedir()), ".r5d", "personal-browser") : path.resolve(rootPath);
+  const root = path.join(base, createHash("sha256").update(origin).digest("hex").slice(0, 24));
+  fs.mkdirSync(root, { recursive: true, mode: 448 });
+  assertPrivatePath(root, "directory");
+  return root;
+}
+async function startPersonalBrowser(options, version) {
+  const diagnostic = personalBrowserDiagnosticObserver(process.env.R5D_BROWSER_DIAGNOSTICS === "1");
+  const { origin, token } = personalBrowserConnection(options);
+  const root = personalBrowserStateDirectory(origin, options.rootPath);
+  const bindingPath = path.join(root, "binding.json");
+  const previous = fs.existsSync(bindingPath) ? Binding.parse(JSON.parse(readPrivateFile(bindingPath, 128e3).toString())) : void 0;
+  const resourceId = previous?.resourceId ?? randomUUID(), instanceId = previous?.instanceId ?? randomUUID();
+  const hostInfo = { hostname: os.hostname(), platform: process.platform, arch: process.arch, version, capabilities: { readPage: true, passwordRedaction: true, refActions: true, waitFor: true, formInput: true, typedKeys: true, screenshotFullPage: true, viewportSizing: true, fileUploads: true, runJsArtifacts: true } };
+  const request = async (route2, body, pollSignal) => {
+    const timeout = AbortSignal.timeout(3e4);
+    const response = await fetch(`${origin}/api/personal/resources${route2}`, { method: "POST", redirect: "error", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body), signal: pollSignal ? AbortSignal.any([timeout, pollSignal]) : timeout });
+    if (!response.ok) {
+      const error = await response.json().catch(() => null);
+      const code = typeof error?.error === "string" && /^[a-z_]{1,100}$/.test(error.error) ? error.error : void 0;
+      throw new PersonalForwardResponseError(response.status, response.status === 401 || response.status === 403 ? "Personal browser credential is no longer authorized" : `Personal browser relay returned ${response.status}${code ? ` (${code})` : ""}`, code);
+    }
+    return await response.json();
+  };
+  const enrolled = await request("/register", { kind: "browser", resourceId, instanceId, label: `browser-${resourceId.slice(0, 12)}`, metadata: { hostInfo, tabs: [], version } });
+  const binding = Binding.parse({ origin, installationId: enrolled.installationId, userId: enrolled.userId, resourceId, instanceId });
+  if (previous && JSON.stringify(binding) !== JSON.stringify(previous)) throw new Error("Browser profile belongs to a different account or environment");
+  atomicJson(bindingPath, binding);
+  const downloads = path.join(root, "downloads"), uploads = path.join(root, "uploads");
+  fs.mkdirSync(downloads, { recursive: true, mode: 448 });
+  fs.mkdirSync(uploads, { recursive: true, mode: 448 });
+  const launch = await launchStableChrome({ profilePath: path.resolve(options.profilePath ?? path.join(root, "chrome-profile")), chromePath: options.chromePath, playwrightDownloadsPath: path.join(downloads, ".playwright"), lockPath: path.join(root, "run.lock") });
+  const runtime = new BrowserRuntime(launch.context, downloads, uploads);
+  let keeper;
+  const shutdown = new PersonalBrowserRelayShutdown();
+  let heartbeatBusy = false;
+  const route = `/browser/${resourceId}`;
+  const forwards = new PersonalPortForwardManager(async (value) => (await request(`${route}/forward`, { instanceId, request: value })).result, diagnostic);
+  const stop = () => shutdown.stop();
+  const events = process;
+  events.on("SIGINT", stop);
+  events.on("SIGTERM", stop);
+  let metadata = { hostInfo: { ...hostInfo, chromiumVersion: launch.chromeVersion }, version, tabs: await runtime.listTabs() };
+  let pollSequence = 0, appliedPollSequence = 0;
+  const poll = async () => {
+    const sequence = ++pollSequence;
+    const result = await request(`${route}/poll`, { instanceId, metadata: { ...metadata, portForwards: forwards.list() } }, shutdown.pollSignal);
+    if (result.installationId !== binding.installationId || result.userId !== binding.userId || result.instanceId !== instanceId || result.resourceId !== resourceId) throw new Error("Browser relay identity mismatch");
+    if (!shutdown.stopping && sequence > appliedPollSequence) {
+      appliedPollSequence = sequence;
+      await forwards.reconcile(result.forwards ?? []);
+    }
+    return result;
+  };
+  const heartbeat = setInterval(() => {
+    if (heartbeatBusy || shutdown.stopping) return;
+    heartbeatBusy = true;
+    void poll().catch(() => {
+    }).finally(() => {
+      heartbeatBusy = false;
+    });
+  }, 1e4);
+  void launch.disconnected.then(stop);
+  void launch.exited.then(stop);
+  try {
+    const executor = browserRuntimeExecutor(runtime);
+    keeper = new BrowserKeeper({ directory: path.join(root, "ledger"), installationId: binding.installationId, userId: binding.userId, instanceId, releaseId: "personal-browser-keeper", executor: {
+      execute: async (operation) => {
+        try {
+          return await executor.execute(operation);
+        } catch (error) {
+          diagnostic({ phase: "action-error", action: operation.kind, category: browserErrorCategory(error) });
+          throw error;
+        }
+      }
+    } });
+    const counterPath = path.join(root, "epoch.json");
+    let epoch = fs.existsSync(counterPath) ? z.number().int().nonnegative().parse(JSON.parse(readPrivateFile(counterPath, 100).toString())) : 0;
+    const processor = new PersonalBrowserProcessor(keeper, binding, () => {
+      epoch = Math.max(epoch + 1, Date.now());
+      if (!Number.isSafeInteger(epoch)) throw new Error("Browser epoch exhausted");
+      atomicJson(counterPath, epoch);
+      return epoch;
+    });
+    process.stdout.write(`[r5d-browser] Connected to ${origin}; Chrome and action receipts stay on this machine.
+`);
+    while (!shutdown.stopping) {
+      try {
+        metadata = { ...metadata, tabs: await runtime.listTabs(), portForwards: forwards.list() };
+        const polled = await poll();
+        if (polled.installationId !== binding.installationId || polled.userId !== binding.userId || polled.instanceId !== instanceId || polled.resourceId !== resourceId) throw new Error("Browser relay identity mismatch");
+        await shutdown.dispatch(polled.actions ?? [], (action) => processor.execute(action), (receipt) => request(`${route}/ack`, { instanceId, ...receipt }));
+        await new Promise((resolve) => setTimeout(resolve, 300));
+      } catch {
+        if (!shutdown.stopping) await new Promise((resolve) => setTimeout(resolve, 2e3));
+      }
+    }
+  } finally {
+    shutdown.stop();
+    clearInterval(heartbeat);
+    try {
+      await forwards.close();
+      await keeper?.close();
+      runtime.closeUploads();
+      await runtime.drainDownloads();
+      await launch.close();
+    } finally {
+      events.off("SIGINT", stop);
+      events.off("SIGTERM", stop);
+    }
+  }
+}
+export {
+  personalBrowserConnection,
+  personalBrowserStateDirectory,
+  startPersonalBrowser
+};

package/dist/mjs/personal-port-forward.mjs

@@ -0,0 +1,183 @@
+import net, {} from "node:net";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+const Definition = z.object({ forwardId: z.string().min(1).max(160), browserPort: z.number().int().min(1).max(65535) }).strict();
+class PersonalForwardResponseError extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+  status;
+  code;
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class PersonalPortForwardManager {
+  constructor(call, observer) {
+    this.call = call;
+    this.observer = observer;
+  }
+  call;
+  observer;
+  active = /* @__PURE__ */ new Map();
+  failures = /* @__PURE__ */ new Map();
+  queue = Promise.resolve();
+  stopping = false;
+  observe(event) {
+    try {
+      this.observer?.(event);
+    } catch {
+    }
+  }
+  list() {
+    return [...this.active.values()].map((value) => ({ forwardId: value.definition.forwardId, ready: true, activeConnections: value.streams.size, lastError: value.lastError })).concat([...this.failures].map(([forwardId, lastError]) => ({ forwardId, ready: false, activeConnections: 0, lastError })));
+  }
+  reconcile(raw) {
+    const definitions = z.array(Definition).max(32).parse(raw);
+    const next = this.queue.then(async () => {
+      for (const [id, value] of this.active) {
+        const expected = definitions.find((definition) => definition.forwardId === id);
+        if (!expected || expected.browserPort !== value.definition.browserPort) await this.stop(value);
+      }
+      for (const id of this.failures.keys()) if (!definitions.some((row) => row.forwardId === id)) this.failures.delete(id);
+      if (this.stopping) return;
+      for (const definition of definitions) {
+        if (this.active.has(definition.forwardId) || this.failures.has(definition.forwardId)) continue;
+        try {
+          await this.start(definition);
+        } catch (error) {
+          this.failures.set(definition.forwardId, { error: error instanceof Error ? error.message : "Could not bind browser loopback port", at: (/* @__PURE__ */ new Date()).toISOString() });
+        }
+      }
+    });
+    this.queue = next.catch(() => {
+    });
+    return next;
+  }
+  async start(definition) {
+    const active = { definition, servers: [], streams: /* @__PURE__ */ new Set(), lastError: null };
+    try {
+      for (const host of ["127.0.0.1", "::1"]) {
+        const server = net.createServer({ allowHalfOpen: true }, (socket) => this.accept(active, socket));
+        active.servers.push(server);
+        await new Promise((resolve, reject) => {
+          server.once("error", reject);
+          server.listen({ host, port: definition.browserPort, ipv6Only: host === "::1", exclusive: true }, () => {
+            server.off("error", reject);
+            resolve();
+          });
+        });
+        server.on("error", (error) => {
+          active.lastError = { error: error.message, at: (/* @__PURE__ */ new Date()).toISOString() };
+        });
+      }
+      this.active.set(definition.forwardId, active);
+    } catch (error) {
+      await this.stop(active);
+      throw error;
+    }
+  }
+  async stop(active) {
+    this.active.delete(active.definition.forwardId);
+    for (const stream of active.streams) {
+      stream.closed = true;
+      stream.socket.destroy();
+    }
+    await Promise.all(active.servers.map((server) => new Promise((resolve) => {
+      if (!server.listening) resolve();
+      else server.close(() => resolve());
+    })));
+  }
+  accept(active, socket) {
+    if (active.streams.size >= 32 || this.stopping) {
+      socket.destroy();
+      return;
+    }
+    this.observe({ phase: "accepted" });
+    const stream = { id: randomUUID(), socket, closed: false, closeSent: false };
+    active.streams.add(stream);
+    socket.pause();
+    socket.setNoDelay(true);
+    let writeOffset = 0, readOffset = 0, sequence = 0;
+    const action = async (command, closing = false) => {
+      const request = { forwardId: active.definition.forwardId, streamId: stream.id, requestId: `${stream.id}-${++sequence}`, command };
+      for (; ; ) {
+        if (this.stopping || stream.closed && !closing) throw new Error("Browser stream closed");
+        try {
+          this.observe({ phase: "request", method: command.method, ...command.method === "write" ? { bytes: Buffer.byteLength(command.base64 ?? "", "base64") } : {} });
+          const result = await this.call(request);
+          this.observe({ phase: "response", method: command.method, ...command.method === "read" && typeof result?.base64 === "string" ? { bytes: Buffer.byteLength(result.base64, "base64") } : {} });
+          return result;
+        } catch (error) {
+          this.observe({ phase: "failure", method: command.method, ...error instanceof PersonalForwardResponseError ? { status: error.status, code: error.code } : {} });
+          active.lastError = { error: error instanceof PersonalForwardResponseError ? error.message : "Personal forwarding request lost its acknowledgement", at: (/* @__PURE__ */ new Date()).toISOString() };
+          if (error instanceof PersonalForwardResponseError && error.status >= 400 && error.status < 500 && ![408, 429].includes(error.status)) throw error;
+          await delay(200);
+        }
+      }
+    };
+    const cleanup = () => {
+      if (stream.closeSent) return;
+      stream.closed = true;
+      stream.closeSent = true;
+      active.streams.delete(stream);
+      socket.destroy();
+      this.observe({ phase: "closed" });
+      if (!this.stopping) void action({ method: "close" }, true).catch(() => {
+      });
+    };
+    const fail = (error) => {
+      active.lastError = { error: error instanceof Error ? error.message : "Browser forwarding failed", at: (/* @__PURE__ */ new Date()).toISOString() };
+      cleanup();
+    };
+    const connected = action({ method: "connect" }).then((result) => {
+      if (result?.connected !== true) throw new Error("Worker did not acknowledge the TCP connection");
+    });
+    let writes = connected;
+    const write = (bytes, end = false) => {
+      socket.pause();
+      writes = writes.then(async () => {
+        for (let start = 0; start < bytes.length || end && start === 0; start += 32 * 1024) {
+          const chunk = bytes.subarray(start, start + 32 * 1024);
+          const result = await action({ method: "write", offset: writeOffset, base64: chunk.toString("base64"), ...end ? { end: true } : {} });
+          if (result?.nextOffset !== writeOffset + chunk.length) throw new Error("Worker TCP write cursor mismatch");
+          writeOffset = result.nextOffset;
+        }
+        if (!stream.closed && !end) socket.resume();
+      }).catch(fail);
+    };
+    socket.on("data", (chunk) => {
+      this.observe({ phase: "received", bytes: chunk.length });
+      write(Buffer.from(chunk));
+    });
+    socket.on("end", () => write(Buffer.alloc(0), true));
+    socket.on("error", fail);
+    socket.on("close", cleanup);
+    socket.pause();
+    void connected.then(async () => {
+      socket.resume();
+      while (!stream.closed && !this.stopping) {
+        const result = await action({ method: "read", after: readOffset });
+        const parsed = z.object({ base64: z.string().max(9e4), nextOffset: z.number().int().nonnegative(), eof: z.boolean() }).parse(result);
+        const bytes = Buffer.from(parsed.base64, "base64");
+        if (parsed.nextOffset !== readOffset + bytes.length) throw new Error("Worker TCP read cursor mismatch");
+        if (bytes.length) await new Promise((resolve, reject) => socket.write(bytes, (error) => error ? reject(error) : resolve()));
+        readOffset = parsed.nextOffset;
+        if (parsed.eof) {
+          socket.end();
+          break;
+        }
+        if (!bytes.length) await delay(100);
+      }
+    }).catch(fail);
+  }
+  async close() {
+    this.stopping = true;
+    await this.queue;
+    await Promise.all([...this.active.values()].map((active) => this.stop(active)));
+  }
+}
+export {
+  PersonalForwardResponseError,
+  PersonalPortForwardManager
+};

package/dist/mjs/personal-relay-client.mjs

@@ -0,0 +1,33 @@
+import { BrowserKeeper } from "./runtime/keeper.mjs";
+import { BrowserAction, BROWSER_KEEPER_CAPABILITY } from "./runtime/protocol.mjs";
+import { canonicalJson } from "@ricsam/r5d-api/runtime-protocol";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+const PersonalBrowserAction = z.object({ id: z.string(), requestHash: z.string().regex(/^[a-f0-9]{64}$/), request: z.object({ action: BrowserAction, input: z.record(z.string(), z.unknown()) }).strict() }).strict();
+class PersonalBrowserProcessor {
+  constructor(keeper, identity, nextEpoch) {
+    this.keeper = keeper;
+    this.identity = identity;
+    this.nextEpoch = nextEpoch;
+  }
+  keeper;
+  identity;
+  nextEpoch;
+  epoch = Date.now();
+  async execute(raw) {
+    const message = PersonalBrowserAction.parse(raw);
+    const hash = createHash("sha256").update(canonicalJson(message.request)).digest("hex");
+    if (hash !== message.requestHash) throw new Error("Browser request hash mismatch");
+    const { installationId, userId, instanceId } = this.identity;
+    const hello = { installationId, instanceId, releaseId: "personal-browser-client", role: "browser-adapter", protocol: { min: 1, max: 1 }, capabilities: [BROWSER_KEEPER_CAPABILITY] };
+    const userAction = ["list_tabs", "list_downloads", "get_download", "open_tab"].includes(message.request.action);
+    const operation = { protocol: 1, installationId, userId, operationId: message.id, kind: message.request.action, payload: message.request.input, fence: { installationId, resourceType: userAction ? "browser-user" : "browser-tab", resourceId: userAction ? userId : z.string().min(1).parse(message.request.input.tabId), ownerId: instanceId, epoch: this.nextEpoch ? this.nextEpoch() : this.epoch = Math.max(this.epoch + 1, Date.now()) } };
+    const principal = { installationId, userId, ownerId: instanceId };
+    await this.keeper.handle({ hello, request: { method: "claim", userId, fence: operation.fence, expiresAt: Date.now() + 12e4 } }, principal);
+    return await this.keeper.handle({ hello, request: { method: "execute", operation } }, principal);
+  }
+}
+export {
+  PersonalBrowserAction,
+  PersonalBrowserProcessor
+};

package/dist/mjs/personal-relay-shutdown.mjs

@@ -0,0 +1,46 @@
+class PersonalBrowserRelayShutdown {
+  polls = new AbortController();
+  get stopping() {
+    return this.polls.signal.aborted;
+  }
+  get pollSignal() {
+    return this.polls.signal;
+  }
+  stop() {
+    this.polls.abort();
+  }
+  async dispatch(actions, execute, acknowledge) {
+    for (const action of actions) {
+      if (this.stopping) break;
+      let state = "completed", result;
+      try {
+        result = await execute(action);
+      } catch {
+        state = "unknown";
+        result = { operationId: action.id, state: "unknown", reason: "browser_boundary_failed" };
+      }
+      const receipt = { id: action.id, requestHash: action.requestHash, state, result };
+      for (; ; ) {
+        try {
+          await acknowledge(receipt);
+          break;
+        } catch {
+          if (this.stopping) break;
+          await new Promise((resolve) => {
+            const done = () => {
+              clearTimeout(timer);
+              this.pollSignal.removeEventListener("abort", done);
+              resolve();
+            };
+            const timer = setTimeout(done, 1500);
+            this.pollSignal.addEventListener("abort", done, { once: true });
+          });
+          if (this.stopping) break;
+        }
+      }
+    }
+  }
+}
+export {
+  PersonalBrowserRelayShutdown
+};

package/dist/mjs/runtime/browser-executor.mjs

@@ -0,0 +1,11 @@
+function browserRuntimeExecutor(runtime) {
+  return {
+    execute: async (operation) => {
+      const result = await runtime.execute(operation.kind, operation.payload);
+      return JSON.parse(JSON.stringify(result ?? null));
+    }
+  };
+}
+export {
+  browserRuntimeExecutor
+};

package/dist/mjs/runtime/chromium-factory.mjs

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { chromium } from "playwright-core";
+import { z } from "zod";
+import { BrowserRuntime } from "../browser-runtime.mjs";
+import { browserRuntimeExecutor } from "./browser-executor.mjs";
+import { freshBrowserRun } from "./isolated-root.mjs";
+import { readPrivateFile } from "./private-paths.mjs";
+import { BrowserKeeperError } from "./protocol.mjs";
+const origin = z.string().refine((value) => {
+  try {
+    const url = new URL(value);
+    return url.origin === value && url.protocol === "http:" && url.hostname === "127.0.0.1" && !!url.port;
+  } catch {
+    return false;
+  }
+}, "Only explicit loopback fake-site HTTP origins are supported");
+const ChromiumFactoryApproval = z.object({
+  kind: z.literal("isolated-chromium-v1"),
+  executablePath: z.string().refine(path.isAbsolute),
+  allowedOrigins: z.array(origin).min(1).max(16)
+}).strict();
+function loadApprovedChromiumFactory(filename, sha256) {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) throw new BrowserKeeperError("invalid_factory_digest");
+  const bytes = readPrivateFile(filename, 16 * 1024, true);
+  if (createHash("sha256").update(bytes).digest("hex") !== sha256) throw new BrowserKeeperError("factory_digest_mismatch");
+  const parsed = ChromiumFactoryApproval.safeParse(JSON.parse(bytes.toString("utf8")));
+  if (!parsed.success) throw new BrowserKeeperError("unapproved_browser_factory");
+  const stat = fs.lstatSync(parsed.data.executablePath);
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 18) !== 0 || (stat.mode & 73) === 0 || fs.realpathSync(parsed.data.executablePath) !== parsed.data.executablePath)
+    throw new BrowserKeeperError("unsafe_chromium_executable");
+  return parsed.data;
+}
+async function createIsolatedChromiumRuntime(input) {
+  const approval = ChromiumFactoryApproval.parse(input.approval);
+  const run = freshBrowserRun(input.runs);
+  const context = await chromium.launchPersistentContext(run.profile, {
+    executablePath: approval.executablePath,
+    headless: true,
+    acceptDownloads: true,
+    downloadsPath: run.downloads,
+    serviceWorkers: "block",
+    viewport: null,
+    // Never inherit account credentials, personal HOME, DISPLAY, proxy, or Chrome environment overrides.
+    env: { PATH: "/usr/bin:/bin", HOME: run.home, TMPDIR: path.dirname(input.runs), LANG: "C.UTF-8" },
+    args: [
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-sync",
+      "--force-webrtc-ip-handling-policy=disable_non_proxied_udp"
+    ]
+  });
+  let runtime;
+  try {
+    const allowed = new Set(approval.allowedOrigins);
+    await context.route("**/*", (route) => {
+      return allowed.has(new URL(route.request().url()).origin) ? route.continue() : route.abort("blockedbyclient");
+    });
+    await context.routeWebSocket("**/*", (socket) => socket.close());
+    const browser = context.browser();
+    if (!browser) throw new BrowserKeeperError("chromium_process_unavailable");
+    const cdp = await browser.newBrowserCDPSession();
+    const info = await cdp.send("SystemInfo.getProcessInfo");
+    await cdp.detach();
+    const pid = info.processInfo.find((entry) => entry.type === "browser")?.id;
+    if (!pid || !Number.isSafeInteger(pid)) throw new BrowserKeeperError("chromium_process_unavailable");
+    runtime = new BrowserRuntime(context, run.downloads, run.uploads);
+    const executor = browserRuntimeExecutor(runtime);
+    const identity = {
+      runId: run.id,
+      browserPid: pid,
+      keeperPid: process.pid,
+      profile: run.profile,
+      downloads: run.downloads,
+      uploads: run.uploads
+    };
+    fs.writeFileSync(path.join(run.directory, "identity.json"), JSON.stringify(identity), { flag: "wx", mode: 384 });
+    return {
+      identity,
+      executor: {
+        execute: executor.execute,
+        dispose: async () => {
+          await context.close();
+          runtime?.closeUploads();
+          fs.rmSync(run.directory, { recursive: true });
+        }
+      }
+    };
+  } catch (error) {
+    await context.close();
+    runtime?.closeUploads();
+    fs.rmSync(run.directory, { recursive: true });
+    throw error;
+  }
+}
+export {
+  ChromiumFactoryApproval,
+  createIsolatedChromiumRuntime,
+  loadApprovedChromiumFactory
+};

package/dist/mjs/runtime/ipc.mjs

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { BrowserKeeper } from "./keeper.mjs";
+import { BrowserKeeperError } from "./protocol.mjs";
+async function serveBrowserKeeper(options) {
+  const { keeper, socketPath, authenticate } = options;
+  const directory = fs.lstatSync(path.dirname(socketPath));
+  if (!directory.isDirectory() || directory.isSymbolicLink() || (directory.mode & 63) !== 0 || directory.uid !== process.getuid?.()) {
+    throw new BrowserKeeperError("unsafe_socket_directory");
+  }
+  const maxFrameBytes = options.maxFrameBytes ?? 3 * 1024 * 1024;
+  const maxConnections = options.maxConnections ?? 64;
+  const sockets = /* @__PURE__ */ new Set();
+  const server = net.createServer((socket) => {
+    if (sockets.size >= maxConnections) {
+      socket.destroy();
+      return;
+    }
+    sockets.add(socket);
+    socket.on("error", () => {
+    });
+    socket.once("close", () => sockets.delete(socket));
+    socket.setTimeout(6e4, () => socket.destroy());
+    let buffer = Buffer.alloc(0);
+    let handled = false;
+    const reply = (data) => {
+      if (!socket.destroyed) socket.end(`${JSON.stringify(data)}
+`);
+    };
+    socket.on("data", (chunk) => {
+      if (handled) {
+        socket.destroy();
+        return;
+      }
+      if (buffer.byteLength + chunk.byteLength > maxFrameBytes) {
+        socket.destroy();
+        return;
+      }
+      buffer = Buffer.concat([buffer, chunk]);
+      const end = buffer.indexOf(10);
+      if (end === -1) return;
+      handled = true;
+      if (end !== buffer.byteLength - 1) {
+        socket.destroy();
+        return;
+      }
+      let principal;
+      let message;
+      try {
+        const value = JSON.parse(buffer.subarray(0, end).toString("utf8"));
+        buffer = Buffer.alloc(0);
+        if (!value || typeof value !== "object" || Object.keys(value).sort().join(",") !== "message,token" || typeof value.token !== "string" || value.token.length < 16 || value.token.length > 4096)
+          throw new Error();
+        principal = authenticate(value.token);
+        message = value.message;
+      } catch {
+        reply({ ok: false, code: "invalid_request" });
+        return;
+      }
+      if (!principal) {
+        reply({ ok: false, code: "unauthorized_peer" });
+        return;
+      }
+      void keeper.handle(message, principal).then(
+        (result) => reply({ ok: true, result }),
+        (error) => reply({ ok: false, code: error instanceof BrowserKeeperError ? error.code : "keeper_error" })
+      );
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      try {
+        fs.chmodSync(socketPath, 384);
+        resolve();
+      } catch (error) {
+        server.close();
+        reject(error);
+      }
+    });
+  });
+  return {
+    async close() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+    }
+  };
+}
+function callBrowserKeeper(options) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(options.socketPath);
+    let buffer = Buffer.alloc(0);
+    let settled = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      if (error) reject(error);
+      else resolve(result);
+    };
+    socket.setTimeout(options.timeoutMs ?? 6e4, () => finish(new BrowserKeeperError("response_lost")));
+    socket.once("error", () => finish(new BrowserKeeperError("transport_unavailable")));
+    socket.once("close", () => finish(new BrowserKeeperError("response_lost")));
+    socket.once("connect", () => socket.write(`${JSON.stringify({ token: options.token, message: options.message })}
+`));
+    socket.on("data", (chunk) => {
+      if (buffer.byteLength + chunk.byteLength > (options.maxReplyBytes ?? 17 * 1024 * 1024)) {
+        finish(new BrowserKeeperError("reply_too_large"));
+        return;
+      }
+      buffer = Buffer.concat([buffer, chunk]);
+      const end = buffer.indexOf(10);
+      if (end === -1) return;
+      try {
+        const reply = JSON.parse(buffer.subarray(0, end).toString("utf8"));
+        if (reply.ok === true) finish(null, reply.result);
+        else finish(new BrowserKeeperError(typeof reply.code === "string" ? reply.code : "invalid_reply"));
+      } catch {
+        finish(new BrowserKeeperError("invalid_reply"));
+      }
+    });
+  });
+}
+export {
+  callBrowserKeeper,
+  serveBrowserKeeper
+};