dsh-browser-plus 0.0.0-stage → 0.5.0

package/src/browser-electron/task-summary.ts

@@ -0,0 +1,10 @@
+/** Return a page-safe task location without path, query, or fragment data. */
+export function taskSummaryUrl(raw: string): string {
+  if (raw === '') return ''
+  try {
+    const origin = new URL(raw).origin
+    return origin === 'null' ? '' : origin
+  } catch {
+    return ''
+  }
+}

package/src/browser-electron/task-thumbnail.ts

@@ -0,0 +1,17 @@
+export const TASK_THUMBNAIL_WIDTH = 288
+export const TASK_THUMBNAIL_JPEG_QUALITY = 58
+export const MAX_TASK_THUMBNAIL_BYTES = 180 * 1024
+
+export interface ThumbnailImage {
+  resize(options: { width: number }): {
+    toJPEG(quality: number): Buffer
+  }
+}
+
+export function taskThumbnailDataUrl(image: ThumbnailImage): string | undefined {
+  const jpeg = image.resize({ width: TASK_THUMBNAIL_WIDTH }).toJPEG(TASK_THUMBNAIL_JPEG_QUALITY)
+
+  if (jpeg.length === 0 || jpeg.length > MAX_TASK_THUMBNAIL_BYTES) return undefined
+
+  return `data:image/jpeg;base64,${jpeg.toString('base64')}`
+}

package/src/browser-electron/write-guard.ts

@@ -0,0 +1,134 @@
+/**
+ * Write-path admission for browser-produced files (screenshots, downloads).
+ *
+ * The provider — not the host — owns this guard so one implementation covers
+ * the self-hosted Electron host and desktop-shell handles alike, and so it can
+ * be exercised without Electron. Roots are resolved through the deepest
+ * existing ancestor, which keeps a symlinked or `..`-laden target from
+ * escaping a root it only appears to sit inside.
+ * @module dsh-browser-plus/browser-electron/write-guard
+ */
+
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { BrowserError } from '../browser/types.ts'
+
+/**
+ * Roots a browser write may target when the config does not name any: the
+ * DSH workspace (the process working directory) and the OS temp directory.
+ * This mirrors the DSH file sandbox's "write inside the workspace" boundary.
+ */
+export function defaultWriteRoots(): string[] {
+  return [process.cwd(), tmpdir()]
+}
+
+/** Windows paths compare case-insensitively; POSIX paths do not. */
+function comparable(value: string): string {
+  return process.platform === 'win32' ? value.toLowerCase() : value
+}
+
+/**
+ * Resolve symlinks on the deepest ancestor that exists, then re-append the
+ * segments that do not. A save target usually does not exist yet, so the
+ * target itself cannot be realpath'd — but its parent usually can.
+ */
+function realpathOfNearestAncestor(target: string): string {
+  let current = target
+  const tail: string[] = []
+  for (;;) {
+    try {
+      const real = realpathSync.native(current)
+      return tail.length === 0 ? real : join(real, ...[...tail].reverse())
+    } catch {
+      const parent = dirname(current)
+      // Reached the filesystem root without finding anything real: fall back
+      // to the lexical path rather than denying a legitimate write.
+      if (parent === current) return target
+      tail.push(basename(current))
+      current = parent
+    }
+  }
+}
+
+/** True when `candidate` is `root` itself or lives beneath it. */
+function within(candidate: string, root: string): boolean {
+  if (candidate === root) return true
+  return candidate.startsWith(root.endsWith(sep) ? root : root + sep)
+}
+
+/** Real, comparable forms of both sides; roots are normalized exactly once per call. */
+function resolvedPair(candidate: string, roots: readonly string[]): { target: string; roots: string[] } {
+  return {
+    target: comparable(realpathOfNearestAncestor(resolve(candidate))),
+    roots: roots.map(root => comparable(realpathOfNearestAncestor(resolve(root)))),
+  }
+}
+
+/**
+ * Whether a path would be admitted by {@link resolveWritePath}, without
+ * throwing. Exposed for focused tests and for callers that want to probe.
+ * @param candidate - the path to test.
+ * @param roots - the allowed roots.
+ */
+export function isWithinRoots(candidate: string, roots: readonly string[]): boolean {
+  const { target, roots: resolved } = resolvedPair(candidate, roots)
+  return resolved.some(root => within(target, root))
+}
+
+/**
+ * Resolve a write target and admit it only when it lands inside one of the
+ * allowed roots. Returns the absolute path to write.
+ * @param savePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every write.
+ * @throws BrowserError `BROWSER_WRITE_PATH_DENIED` when the path is unusable or outside every root.
+ */
+export function resolveWritePath(savePath: string, roots: readonly string[]): string {
+  if (typeof savePath !== 'string' || savePath.trim() === '') {
+    throw new BrowserError('browser: refusing to write without a save path', 'BROWSER_WRITE_PATH_DENIED')
+  }
+  const absolute = resolve(savePath)
+  if (!isWithinRoots(absolute, roots)) {
+    // This message reaches the model context and, through a task's error field,
+    // the page itself — so it never names an absolute path.
+    const hint = roots.length === 0 ? ' (none configured)' : ''
+    throw new BrowserError(
+      `browser: refusing to write "${savePath}" outside the allowed roots${hint}; `
+      + 'add the directory to the browser-electron "writeRoots" config to allow it',
+      'BROWSER_WRITE_PATH_DENIED',
+    )
+  }
+  return absolute
+}
+
+/**
+ * Resolve a file the browser is about to hand to a page and admit it only when
+ * it lands inside one of the allowed roots. Unlike a write target the file must
+ * already exist, so the path itself is realpath'd: a symlink to a permitted
+ * file is admitted, a symlink that leaves the roots is not.
+ * @param filePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every read.
+ * @throws BrowserError `BROWSER_READ_PATH_DENIED` when the path is unusable, missing, or outside every root.
+ */
+export function resolveReadPath(filePath: string, roots: readonly string[]): string {
+  if (typeof filePath !== 'string' || filePath.trim() === '') {
+    throw new BrowserError('browser: refusing to read without a file path', 'BROWSER_READ_PATH_DENIED')
+  }
+  const absolute = resolve(filePath)
+  let real: string
+  try {
+    real = realpathSync.native(absolute)
+  } catch {
+    throw new BrowserError(`browser: refusing to read "${filePath}": the file does not exist`, 'BROWSER_READ_PATH_DENIED')
+  }
+  const allowed = roots.map(root => comparable(realpathOfNearestAncestor(resolve(root))))
+  if (!allowed.some(root => within(comparable(real), root))) {
+    const hint = roots.length === 0 ? ' (none configured)' : ''
+    throw new BrowserError(
+      `browser: refusing to read "${filePath}" outside the allowed roots${hint}; `
+      + 'add the directory to the browser-electron "readRoots" config to allow it',
+      'BROWSER_READ_PATH_DENIED',
+    )
+  }
+  return absolute
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * dsh-browser-plus plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser-plus/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-browser-plus/browser-electron` -> the Electron CDP provider
+ *   - `dsh-browser-plus/tool-browser`     -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ * @module dsh-browser-plus
+ */
+
+export { BrowserError } from './browser/types.ts'
+export type {
+  BrowserChallenge,
+  BrowserContentFormat,
+  BrowserControlOwner,
+
+  BrowserContentRequest,
+  BrowserContentResult,
+  BrowserDragRequest,
+  BrowserDragResult,
+  BrowserExecuteRequest,
+  BrowserPointerResult,
+  BrowserPointerTarget,
+  BrowserExecuteResult,
+  BrowserFillField,
+  BrowserFillRequest,
+  BrowserFillResult,
+  BrowserHandoffState,
+  BrowserNavigateRequest,
+  BrowserOpenRequest,
+  BrowserProvider,
+  BrowserRefRequest,
+  BrowserScreenshotRequest,
+  BrowserScrollIntoViewRequest,
+  BrowserScrollRequest,
+  BrowserScrollResult,
+  BrowserScreenshotResult,
+  BrowserSessionId,
+  BrowserSnapshotElement,
+  BrowserSnapshotResult,
+  BrowserTab,
+  BrowserTaskInfo,
+  BrowserTaskStatus,
+  BrowserTaskUpdate,
+  BrowserTypeRequest,
+  ExportedCookie,
+} from './browser/types.ts'
+export { BrowserRuntime } from './browser/runtime.ts'
+export { ElectronBrowserProvider } from './browser-electron/provider.ts'
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './browser-electron/provider.ts'
+export { RemoteElectronViewHost, defaultHostMainPath } from './browser-electron/remote-host.ts'