@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.249.1

package/server/browser-cursor.test.ts

@@ -0,0 +1,64 @@
+/** Exercise the actual page program with bounded DOM fixtures; native geometry is covered by smoke. */
+import { runInNewContext } from "node:vm";
+import { expect, it } from "vitest";
+import { browserCursorExpression } from "./browser-cursor";
+
+function fixture({
+  cursor = "auto",
+  userSelect = "auto",
+  writingMode = "horizontal-tb",
+  editable = false,
+  contains = true,
+  legacy = false,
+} = {}) {
+  const node = { nodeType: 3, length: 5 };
+  const element = { isContentEditable: editable, contains: () => contains };
+  const range = {
+    setStart() {},
+    setEnd() {},
+    getClientRects: () => [{ left: 10, right: 40, top: 10, bottom: 25 }],
+  };
+  const position = { offsetNode: node, offset: 2 };
+  const document = {
+    elementFromPoint: () => element,
+    createRange: () => range,
+    ...(legacy
+      ? { caretRangeFromPoint: () => ({ startContainer: node, startOffset: 2 }) }
+      : { caretPositionFromPoint: () => position }),
+  };
+  return {
+    document,
+    sample: (x = 20, y = 15) =>
+      runInNewContext(browserCursorExpression(x, y), {
+        document,
+        getComputedStyle: () => ({ cursor, userSelect, writingMode }),
+      }),
+  };
+}
+
+it("resolves auto over selectable text, including the legacy caret API", () => {
+  expect(fixture().sample()).toBe("text");
+  expect(fixture({ legacy: true }).sample()).toBe("text");
+});
+
+it("preserves explicit cursor choices even over selectable text", () => {
+  expect(fixture({ cursor: "default" }).sample()).toBe("default");
+  expect(fixture({ cursor: "pointer" }).sample()).toBe("pointer");
+});
+
+it("does not mistake nearby text, overlays or non-selectable content for text", () => {
+  expect(fixture().sample(90, 15)).toBe("default");
+  expect(fixture({ contains: false }).sample()).toBe("default");
+  expect(fixture({ userSelect: "none" }).sample()).toBe("default");
+});
+
+it("resolves empty editing surfaces and vertical text without moving selection", () => {
+  expect(fixture({ editable: true }).sample(90, 15)).toBe("text");
+  expect(fixture({ writingMode: "vertical-rl" }).sample()).toBe("vertical-text");
+});
+
+it("rejects invalid coordinates before constructing page code", () => {
+  for (const x of [Number.NaN, Number.POSITIVE_INFINITY, -1]) {
+    expect(() => browserCursorExpression(x, 10)).toThrow("finite non-negative");
+  }
+});

package/server/browser-cursor.ts

@@ -0,0 +1,69 @@
+/**
+ * Read-only cursor resolution for the guarded native page in agent-browser-runtime.
+ * CSS keeps `auto` as its computed value; resolve selectable glyphs/editing surfaces
+ * without exporting page text, changing selection, or inspecting a whole subtree.
+ * The page program handles the top document and exposed shadow roots. Opaque
+ * frames remain subject to the existing top-document hit-test limitation.
+ */
+const CURSOR_HIT_TEST = `(x, y) => {
+  let element = document.elementFromPoint(x, y);
+  if (!element) return null;
+
+  const shadowRoots = [];
+  // Bound descent and retain roots for Chromium's caret hit-test options.
+  for (let depth = 0; depth < 16 && element.shadowRoot; depth++) {
+    const root = element.shadowRoot;
+    const inner = root.elementFromPoint(x, y);
+    if (!inner || inner === element) break;
+    shadowRoots.push(root);
+    element = inner;
+  }
+
+  const style = getComputedStyle(element);
+  if (style.cursor !== 'auto') return style.cursor;
+  if (style.userSelect === 'none') return 'default';
+
+  const textCursor = style.writingMode.startsWith('vertical') ||
+    style.writingMode.startsWith('sideways') ? 'vertical-text' : 'text';
+  if (element.isContentEditable) return textCursor;
+
+  // Explicit auto on text controls must also work over empty editable space.
+  const textInputTypes = ['text', 'search', 'url', 'tel', 'email', 'password', 'number'];
+  const textControl = element.tagName === 'TEXTAREA' ||
+    (element.tagName === 'INPUT' && textInputTypes.includes(element.type));
+  if (textControl && !element.disabled) return textCursor;
+
+  let node;
+  let offset;
+  if (document.caretPositionFromPoint) {
+    const position = document.caretPositionFromPoint(x, y, { shadowRoots });
+    node = position?.offsetNode;
+    offset = position?.offset;
+  } else if (document.caretRangeFromPoint) {
+    const position = document.caretRangeFromPoint(x, y);
+    node = position?.startContainer;
+    offset = position?.startOffset;
+  }
+  if (!node || node.nodeType !== 3 || !element.contains(node) ||
+      !Number.isInteger(offset) || node.length === 0) return 'default';
+
+  // Caret APIs can snap to nearby text even over padding. Check only adjacent
+  // glyph rectangles so blank areas and overlays never inherit a text cursor.
+  const range = document.createRange();
+  range.setStart(node, Math.max(0, offset - 1));
+  range.setEnd(node, Math.min(node.length, offset + 1));
+  for (const rect of range.getClientRects()) {
+    if (x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom) {
+      return textCursor;
+    }
+  }
+  return 'default';
+}`;
+
+/** Build the fixed page program with numeric CSS coordinates, never executable caller input. */
+export function browserCursorExpression(x: number, y: number): string {
+  if (!Number.isFinite(x) || !Number.isFinite(y) || x < 0 || y < 0) {
+    throw new Error("Cursor coordinates must be finite non-negative CSS pixels");
+  }
+  return `(${CURSOR_HIT_TEST})(${x}, ${y})`;
+}

package/server/browser-frame-context.ts

@@ -0,0 +1,22 @@
+/** Matches issued pixels to their exact browser attachment and display generations. */
+import type { BrowserFrame, BrowserState } from "../shared/browser";
+
+/** Pixel equality alone cannot authorize a different document, runtime or viewport. */
+export function frameMatchesBrowserContext(
+  frame: Pick<
+    BrowserFrame,
+    "sessionId" | "runtimeId" | "captureEpoch" | "navigationGeneration" | "viewportGeneration"
+  >,
+  state: Pick<
+    BrowserState,
+    "sessionId" | "runtimeId" | "bridgeEpoch" | "navigationGeneration" | "viewportGeneration"
+  >,
+): boolean {
+  return (
+    frame.sessionId === state.sessionId &&
+    frame.runtimeId === state.runtimeId &&
+    frame.captureEpoch === state.bridgeEpoch &&
+    frame.navigationGeneration === state.navigationGeneration &&
+    frame.viewportGeneration === state.viewportGeneration
+  );
+}

package/server/browser-frame-epoch.test.ts

@@ -0,0 +1,95 @@
+import { expect, it } from "vitest";
+import type { BrowserState } from "../shared/browser";
+import { SessionManager } from "./browser-policy";
+
+/** Snapshot the current attachment, independently of a previously painted token. */
+function expected(state: BrowserState) {
+  return {
+    sessionId: state.sessionId,
+    runtimeId: state.runtimeId!,
+    bridgeEpoch: state.bridgeEpoch!,
+    navigationGeneration: state.navigationGeneration,
+    viewportGeneration: state.viewportGeneration,
+  };
+}
+
+it("revokes old bridge pixel tokens and admits a new capture without publishing stale input", async () => {
+  let ids = 0;
+  const calls: string[] = [];
+  const manager = new SessionManager({
+    validateWorkspace: async () => true,
+    issueToken: () => String(++ids).padStart(32, "0"),
+    client: {
+      connect: async () => ({ epoch: 1 }),
+      ensureWorkspace: async (workspaceId) => ({
+        workspaceId,
+        runtimeId: "r".repeat(32),
+        createdAt: 1,
+      }),
+      archiveWorkspace: async () => {},
+      closeWorkspace: async () => {},
+      disconnect: () => {},
+      requestWorkspace: async (_workspace, operation) => {
+        calls.push(operation);
+        if (operation === "identity") return { userAgent: "Fixture" };
+        if (operation === "state")
+          return {
+            url: "https://fixture.invalid/",
+            title: "Fixture",
+            inputGeneration: "1:1",
+            canGoBack: false,
+            canGoForward: false,
+          };
+        if (operation === "frame")
+          return {
+            dataBase64: "AA==",
+            byteLength: 1,
+            width: 1280,
+            height: 800,
+            capturedAt: new Date().toISOString(),
+          };
+        return null;
+      },
+    },
+  });
+  try {
+    await manager.connect();
+    const { viewerToken } = await manager.attach("owned", "Fixture");
+    const { controlToken } = await manager.acquireControl(viewerToken);
+    const captured = await manager.capture(viewerToken);
+    manager.setBridgeEpoch(2);
+    const { state } = await manager.status(viewerToken);
+    const old = captured.frame!;
+    const refused = await manager.beginGesture({
+      viewerToken,
+      controlToken,
+      pointerKind: "mouse",
+      expected: expected(state),
+      target: {
+        frameId: old.frameId,
+        navigationGeneration: old.navigationGeneration,
+        viewportGeneration: old.viewportGeneration,
+      },
+    });
+    expect(refused).toMatchObject({ admission: "stale-frame" });
+    expect(calls).not.toContain("input.begin");
+
+    const fresh = await manager.capture(viewerToken);
+    expect(fresh.frame!.captureEpoch).toBe(2);
+    const admitted = await manager.beginGesture({
+      viewerToken,
+      controlToken,
+      pointerKind: "mouse",
+      expected: expected(fresh.state),
+      target: {
+        frameId: fresh.frame!.frameId,
+        navigationGeneration: fresh.frame!.navigationGeneration,
+        viewportGeneration: fresh.frame!.viewportGeneration,
+      },
+    });
+    expect(admitted).toHaveProperty("gestureId");
+    expect(calls).toContain("input.begin");
+  } finally {
+    manager.disconnect();
+  }
+});

package/server/browser-frame-rejection.ts

@@ -0,0 +1,17 @@
+/**
+ * Explains stale input observations through ordinary RPC errors. Only fixed
+ * stage/reason labels and bounded elapsed age leave the policy boundary; frame
+ * IDs, page details and control authority stay private. Diagnostics grant no
+ * retry or non-publication guarantee for an already admitted input.
+ */
+export function createBrowserFrameRejection(
+  stage: "admission" | "admitted-input",
+  reason: "expired" | "missing-or-revoked" | "context-changed",
+  ageMs?: number,
+): Error {
+  const details = [`stage=${stage}`, `reason=${reason}`];
+  if (ageMs !== undefined && Number.isFinite(ageMs)) {
+    details.push(`ageMs=${Math.min(60_000, Math.max(0, Math.floor(ageMs)))}`);
+  }
+  return new Error(`Browser frame is stale (${details.join("; ")})`);
+}

package/server/browser-gesture.ts

@@ -0,0 +1,120 @@
+/**
+ * One ordered live input channel, anchored to a decoded frame by browser-policy.
+ * Owns only bounded gesture state/coordinates. The host supplies serialized
+ * authority checks and transport cleanup; this module never grants a lease.
+ */
+import type { BrowserGestureEvent, Viewport } from "../shared/browser";
+import { MAX_HELD_BROWSER_KEYS, mapDisplayedPoint } from "../shared/browser";
+
+export const GESTURE_IDLE_MS = 5_000;
+export const GESTURE_LIFETIME_MS = 5 * 60_000;
+
+export class BrowserGesture {
+  nextSequence = 1;
+  idleUntil: number;
+  readonly expiresAt: number;
+  readonly buttons = new Set<string>();
+  readonly touches = new Set<number>();
+  readonly keys = new Set<string>();
+  private display: { width: number; height: number } | null = null;
+  timer: ReturnType<typeof setTimeout> | null = null;
+  lastPoint: { x: number; y: number } | null = null;
+
+  constructor(
+    readonly id: string,
+    readonly viewerToken: string,
+    readonly controlToken: string,
+    readonly pointerKind: "mouse" | "touch",
+    readonly expected: {
+      sessionId: string;
+      runtimeId: string;
+      bridgeEpoch: number;
+      navigationGeneration: number;
+      viewportGeneration: number;
+    },
+    readonly viewport: Viewport,
+    now: number,
+    readonly runtimeInputGeneration: string | null = null,
+  ) {
+    this.idleUntil = now + GESTURE_IDLE_MS;
+    this.expiresAt = now + GESTURE_LIFETIME_MS;
+  }
+
+  /** Reject dropped/replayed packets and expire even if a delayed queue resumes later. */
+  assertSequence(sequence: number, now: number): void {
+    if (sequence !== this.nextSequence) throw new Error("Browser gesture sequence is stale");
+    if (now >= this.idleUntil || now >= this.expiresAt) throw new Error("Browser gesture expired");
+  }
+
+  /** Pin displayed geometry on first point; a mid-gesture local layout change must cancel. */
+  mapPoint(point: { x: number; y: number; width: number; height: number }) {
+    if (!this.display) this.display = { width: point.width, height: point.height };
+    if (this.display.width !== point.width || this.display.height !== point.height) {
+      throw new Error("Browser gesture display geometry changed");
+    }
+    const mapped = mapDisplayedPoint(point, this.viewport);
+    this.lastPoint = mapped;
+    return mapped;
+  }
+
+  /** Validate edges before publication. Continuation never invents a missing button/touch start. */
+  validate(event: BrowserGestureEvent): void {
+    if (event.kind === "leave" && this.buttons.size > 0)
+      throw new Error("Release held mouse buttons before leaving");
+    if (event.kind === "key") {
+      if (event.type === "down" && this.keys.has(event.code) !== event.repeat) {
+        throw new Error(
+          event.repeat ? "Key repeat has no matching press" : "Key is already pressed",
+        );
+      }
+      if (event.type === "up" && !this.keys.has(event.code)) {
+        throw new Error("Key release has no matching press");
+      }
+      if (
+        event.type === "down" &&
+        !this.keys.has(event.code) &&
+        this.keys.size >= MAX_HELD_BROWSER_KEYS
+      ) {
+        throw new Error("Too many simultaneously held browser keys");
+      }
+      return;
+    }
+    if (event.kind === "text") return;
+    if ((event.kind === "touch") !== (this.pointerKind === "touch"))
+      throw new Error("Browser gesture pointer kind changed");
+    if (event.kind === "down" && this.buttons.has(event.button))
+      throw new Error("Mouse button is already pressed");
+    if (event.kind === "up" && !this.buttons.has(event.button))
+      throw new Error("Mouse button is not pressed");
+    if (event.kind === "touch") {
+      if (
+        event.type === "move" &&
+        (this.touches.size === 0 || event.points.some((point) => !this.touches.has(point.id)))
+      ) {
+        throw new Error("Touch move has no matching start");
+      }
+      if (event.type === "start" && event.points.every((point) => this.touches.has(point.id))) {
+        throw new Error("Touch start must add a touch identifier");
+      }
+    }
+  }
+
+  /** Commit the acknowledged edge, preserving explicitly released touch IDs. */
+  acknowledge(event: BrowserGestureEvent, now: number): void {
+    if (event.kind === "key" && event.type === "down") this.keys.add(event.code);
+    if (event.kind === "key" && event.type === "up") this.keys.delete(event.code);
+    if (event.kind === "down") this.buttons.add(event.button);
+    if (event.kind === "up") this.buttons.delete(event.button);
+    if (event.kind === "touch") {
+      this.touches.clear();
+      for (const point of event.points) this.touches.add(point.id);
+    }
+    this.nextSequence += 1;
+    this.idleUntil = now + GESTURE_IDLE_MS;
+  }
+
+  /** Only an unpressed mouse move leaves existing bounded frame authority usable for a new press. */
+  isHover(event: BrowserGestureEvent): boolean {
+    return (event.kind === "move" || event.kind === "leave") && this.buttons.size === 0;
+  }
+}

package/server/browser-operation-diagnostics.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import {
+  type BrowserFailureDiagnostic,
+  classifyBrowserFailure,
+  createBrowserOperationDiagnostics,
+} from "./browser-operation-diagnostics";
+
+describe("browser operation diagnostics", () => {
+  it("does not copy an arbitrary method-shaped secret into logs", () => {
+    expect(classifyBrowserFailure(new Error("Page.SecretPassword timed out"))).toEqual({
+      category: "timeout",
+    });
+  });
+  it("classifies protocol codes independently of their user-facing message", () => {
+    expect(
+      classifyBrowserFailure(
+        Object.assign(new Error("Shared Browser supervisor is busy; retry the request"), {
+          code: "RUNTIME_BUSY",
+        }),
+      ),
+    ).toEqual({ category: "capacity" });
+    expect(
+      classifyBrowserFailure(
+        Object.assign(new Error("Obsolete connection"), { code: "BRIDGE_FENCED" }),
+      ),
+    ).toEqual({ category: "expired-authority" });
+  });
+  it("retains the failed CDP method without recording a URL, token or input", () => {
+    const error = new Error(
+      "Workspace frame failed: Page.getLayoutMetrics timed out after 15000ms https://private.invalid/?token=secret typed password",
+    );
+    expect(classifyBrowserFailure(error)).toEqual({
+      category: "timeout",
+      cdpMethod: "Page.getLayoutMetrics",
+    });
+  });
+
+  it("rate limits independently, preserves errors and admits a later report", async () => {
+    let now = 0;
+    const reports: BrowserFailureDiagnostic[] = [];
+    const diagnose = createBrowserOperationDiagnostics({
+      now: () => now,
+      report: (value) => reports.push(value),
+    });
+    const error = new Error("Viewer token is invalid or expired: secret");
+    const fail = async () => {
+      now += 10;
+      throw error;
+    };
+    await expect(diagnose("capture", fail)).rejects.toBe(error);
+    await expect(diagnose("capture", fail)).rejects.toBe(error);
+    await expect(diagnose("video.read", fail)).rejects.toBe(error);
+    expect(reports).toHaveLength(2);
+    expect(reports[0]).toEqual({
+      operation: "capture",
+      category: "expired-authority",
+      durationMs: 10,
+    });
+    now += 30_000;
+    await expect(diagnose("capture", fail)).rejects.toBe(error);
+    expect(reports).toHaveLength(3);
+  });
+
+  it("does not alter successful results or let a failing logger replace errors", async () => {
+    const diagnose = createBrowserOperationDiagnostics({
+      report() {
+        throw new Error("logger failed");
+      },
+    });
+    const value = {};
+    expect(await diagnose("capture", async () => value)).toBe(value);
+    const error = new Error("private unrelated message");
+    await expect(
+      diagnose("capture", async () => {
+        throw error;
+      }),
+    ).rejects.toBe(error);
+  });
+});

package/server/browser-operation-diagnostics.ts

@@ -0,0 +1,103 @@
+/**
+ * Records bounded, redacted RPC failures in the plugin process so Paseo retains
+ * them. Never log URLs, input text, credentials, tokens or raw remote messages.
+ * Repeated failures in one operation/category emit at most once each 30 seconds.
+ */
+const REPORT_INTERVAL_MS = 30_000;
+const MAX_DIAGNOSTIC_KEYS = 64;
+const SAFE_CDP_TIMEOUT_METHODS = new Set([
+  "Page.enable",
+  "Page.getLayoutMetrics",
+  "Page.captureScreenshot",
+  "Page.startScreencast",
+  "Page.stopScreencast",
+  "Runtime.enable",
+  "Runtime.evaluate",
+  "Runtime.addBinding",
+  "Target.createTarget",
+  "Target.attachToTarget",
+  "Target.getTargets",
+  "Target.closeTarget",
+  "Performance.enable",
+  "Performance.getMetrics",
+  "Emulation.setDeviceMetricsOverride",
+  "Emulation.setTouchEmulationEnabled",
+  "Emulation.setUserAgentOverride",
+  "Input.dispatchMouseEvent",
+  "Input.dispatchKeyEvent",
+  "Input.dispatchTouchEvent",
+  "Input.insertText",
+]);
+
+export interface BrowserFailureDiagnostic {
+  operation: string;
+  category: "timeout" | "stale-frame" | "expired-authority" | "capacity" | "connection" | "other";
+  cdpMethod?: string;
+  durationMs: number;
+}
+
+/** Return only fixed categories and a fixed allowlisted CDP method from an error. */
+export function classifyBrowserFailure(
+  error: unknown,
+): Omit<BrowserFailureDiagnostic, "operation" | "durationMs"> {
+  const message = error instanceof Error ? error.message : "";
+  const code = error instanceof Error && "code" in error ? error.code : undefined;
+  if (code === "RUNTIME_BUSY") return { category: "capacity" };
+  if (code === "BRIDGE_FENCED") return { category: "expired-authority" };
+  const candidateMethod =
+    /\b((?:Page|Runtime|Target|Input|Emulation|Performance|Browser)\.[A-Za-z]{1,64}) timed out\b/.exec(
+      message,
+    )?.[1];
+  const method =
+    candidateMethod && SAFE_CDP_TIMEOUT_METHODS.has(candidateMethod) ? candidateMethod : undefined;
+  if (/timed out|timeout/i.test(message))
+    return { category: "timeout", ...(method ? { cdpMethod: method } : {}) };
+  if (/frame is stale/i.test(message)) return { category: "stale-frame" };
+  if (/token is invalid or expired|lease is invalid or expired|BRIDGE_FENCED/.test(message))
+    return { category: "expired-authority" };
+  if (/RUNTIME_BUSY|capacity|too many/i.test(message)) return { category: "capacity" };
+  if (/connection closed|unavailable|disconnected/i.test(message))
+    return { category: "connection" };
+  return { category: "other" };
+}
+
+/** Wrap one operation, preserving its original error and success result exactly. */
+export function createBrowserOperationDiagnostics(
+  options: { now?: () => number; report?: (diagnostic: BrowserFailureDiagnostic) => void } = {},
+) {
+  const now = options.now ?? Date.now;
+  const report =
+    options.report ??
+    ((diagnostic) => console.warn("[shared-browser] operation failed", diagnostic));
+  const lastReported = new Map<string, number>();
+  return async function diagnose<T>(operation: string, perform: () => Promise<T>): Promise<T> {
+    const startedAt = now();
+    try {
+      return await perform();
+    } catch (error) {
+      const details = classifyBrowserFailure(error);
+      // Operations come from internal method names, not client-provided strings.
+      const safeOperation = /^[a-z][a-z.-]{0,63}$/.test(operation) ? operation : "unknown";
+      const key = `${safeOperation}:${details.category}`;
+      const previous = lastReported.get(key);
+      const observedAt = now();
+      if (previous === undefined || observedAt - previous >= REPORT_INTERVAL_MS) {
+        if (lastReported.size >= MAX_DIAGNOSTIC_KEYS) {
+          const oldest = lastReported.keys().next().value;
+          if (oldest !== undefined) lastReported.delete(oldest);
+        }
+        lastReported.set(key, observedAt);
+        try {
+          report({
+            operation: safeOperation,
+            ...details,
+            durationMs: Math.max(0, observedAt - startedAt),
+          });
+        } catch {
+          // Observability must never replace the original operation failure.
+        }
+      }
+      throw error;
+    }
+  };
+}