dsh-browser-plus 0.0.0-stage → 0.5.0

package/src/browser-electron/auth-cookies.ts

@@ -0,0 +1,125 @@
+export interface AuthCookieLike {
+  readonly domain?: string
+  readonly path?: string
+  readonly name: string
+  readonly value: string
+  readonly secure?: boolean
+  readonly httpOnly?: boolean
+  readonly expirationDate?: number
+}
+
+export interface ExportedAuthCookie {
+  readonly url: string
+  readonly name: string
+  readonly value: string
+  readonly domain: string
+  readonly path: string
+  readonly secure: boolean
+  readonly httpOnly: boolean
+  readonly expirationDate: number | undefined
+}
+
+/** Convert Electron cookies into portable auth records, skipping invalid domains. */
+export function exportCookiesForAuth(cookies: readonly AuthCookieLike[]): ExportedAuthCookie[] {
+  return cookies.flatMap(cookie => {
+    const domain = cookie.domain
+    if (typeof domain !== 'string' || domain === '') return []
+    const host = domain.startsWith('.') ? domain.slice(1) : domain
+    const hostPart = host.includes(':') && !host.startsWith('[') ? '[' + host + ']' : host
+    const path = typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/'
+    const secure = cookie.secure === true
+    return [{
+      url: 'http' + (secure ? 's' : '') + '://' + hostPart + path,
+      name: cookie.name,
+      value: cookie.value,
+      domain,
+      path,
+      secure,
+      httpOnly: cookie.httpOnly === true,
+      expirationDate: cookie.expirationDate,
+    }]
+  })
+}
+/**
+ * One cookie selected for removal, plus the URL Electron needs to delete it.
+ */
+export interface CookieClearTarget {
+  readonly name: string
+  readonly domain: string
+  readonly path: string
+  readonly url: string
+}
+
+/**
+ * Which cookies a clear request targets: a domain scope, one exact name within
+ * that scope, or an explicit whole-profile wipe.
+ */
+export interface CookieClearFilter {
+  /** Domain scope; matches the domain itself and every subdomain. */
+  readonly domain?: string
+  /** Exact cookie name to remove within the scope. */
+  readonly name?: string
+  /** Remove every addressable cookie; requires this explicit opt-in. */
+  readonly all?: boolean
+}
+
+/** Normalize a scope/domain for comparison: drop one leading dot, lowercase. */
+function normalizeDomain(domain: string): string {
+  const trimmed = domain.trim().toLowerCase()
+  return trimmed.startsWith('.') ? trimmed.slice(1) : trimmed
+}
+
+/** Whether one cookie domain falls under a scope: the scope itself, or a subdomain. */
+export function cookieMatchesDomain(cookieDomain: string, scope: string): boolean {
+  const cookie = normalizeDomain(cookieDomain)
+  const target = normalizeDomain(scope)
+  if (cookie === '' || target === '') return false
+  return cookie === target || cookie.endsWith('.' + target)
+}
+
+/** Build the URL required to address one cookie for removal. */
+export function cookieRemovalUrl(cookie: AuthCookieLike): string | undefined {
+  const domain = cookie.domain
+  if (typeof domain !== 'string' || domain === '') return undefined
+  const host = domain.startsWith('.') ? domain.slice(1) : domain
+  if (host === '') return undefined
+  const hostPart = host.includes(':') && !host.startsWith('[') ? '[' + host + ']' : host
+  const path = typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/'
+  return 'http' + (cookie.secure === true ? 's' : '') + '://' + hostPart + path
+}
+
+/**
+ * Select the cookies a clear request targets. An unscoped request is refused
+ * unless "all" is explicitly set, so a missing filter can never wipe logins.
+ * @param cookies - the profile's cookies.
+ * @param filter - domain scope, exact name, or an explicit full wipe.
+ * @returns the removable cookies, each with its removal URL.
+ */
+export function selectCookiesForClear(
+  cookies: readonly AuthCookieLike[],
+  filter: CookieClearFilter,
+): CookieClearTarget[] {
+  const domainScope = typeof filter.domain === 'string' && filter.domain.trim() !== '' ? filter.domain : undefined
+  const nameScope = typeof filter.name === 'string' && filter.name !== '' ? filter.name : undefined
+  if (domainScope === undefined && nameScope === undefined && filter.all !== true) {
+    throw new Error('cookie clear requires a domain or name filter; pass all: true to remove every cookie')
+  }
+  const targets: CookieClearTarget[] = []
+  for (const cookie of cookies) {
+    const domain = cookie.domain
+    if (typeof domain !== 'string' || domain === '') continue
+    if (domainScope !== undefined || nameScope !== undefined) {
+      if (domainScope !== undefined && !cookieMatchesDomain(domain, domainScope)) continue
+      if (nameScope !== undefined && cookie.name !== nameScope) continue
+    }
+    const url = cookieRemovalUrl(cookie)
+    if (url === undefined) continue
+    targets.push({
+      name: cookie.name,
+      domain,
+      path: typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/',
+      url,
+    })
+  }
+  return targets
+}

package/src/browser-electron/chrome-state.ts

@@ -0,0 +1,174 @@
+/**
+ * Versioned state exchanged between the self-hosted Electron main process and
+ * the injected page chrome. Keeping the payload declarative makes it possible
+ * to update one task or one trail entry without rebuilding the whole workspace.
+ * @module dsh-browser-plus/browser-electron/chrome-state
+ */
+
+export interface ChromePanels {
+  readonly tasks: boolean
+  readonly trail: boolean
+}
+
+export interface ChromeTrailEntry {
+  readonly action: string
+  readonly params?: Record<string, unknown>
+  readonly ok?: boolean
+  readonly at: number
+}
+
+export interface ChromeTaskLatest {
+  readonly action: string
+  readonly at: number
+}
+
+export interface ChromeTaskSummary {
+  readonly key: string
+  readonly label: string
+  readonly active: boolean
+  readonly background: boolean
+  readonly url: string
+  readonly tabs: number
+  readonly status: 'idle' | 'running' | 'waiting-user' | 'failed'
+  readonly control: 'agent' | 'human'
+  readonly updatedAt: number
+  readonly latest?: ChromeTaskLatest
+  readonly error?: string
+  /**
+   * Bumped when a new image arrives through the 'task.thumbnail' patch. The
+   * image itself is never part of a summary: summaries reach every page.
+   */
+  readonly thumbnailVersion: number
+}
+
+/**
+ * One tab of the selected task, as the tab strip renders it.
+ *
+ * A tab is a host view, so this is the view list for the task in creation
+ * order; `active` marks the one currently shown. Titles and URLs come from the
+ * view itself and are refreshed on navigation.
+ */
+export interface ChromeTabSummary {
+  readonly id: string
+  readonly title: string
+  readonly url: string
+  readonly active: boolean
+  /**
+   * Whether this tab's page is bookmarked.
+   *
+   * The chrome only receives the redacted origin (the page copy lives in the page,
+   * so a full URL would hand it the query string), which means the toolbar cannot
+   * decide this for itself — the host computes it from the real URL.
+   */
+  readonly starred?: boolean
+  /**
+   * Whether the tab has somewhere to go back / forward to.
+   *
+   * Like `starred`, only the host can answer this: the page copy of the chrome
+   * shares the page's own document, but the frame copy does not, and the two
+   * copies must agree. Drives the toolbar's back/forward buttons dimming.
+   */
+  readonly canGoBack?: boolean
+  readonly canGoForward?: boolean
+  /**
+   * True while this tab's document is still loading.
+   *
+   * Drives the two Chrome affordances the strip mirrors: a spinner in place of
+   * the favicon, and the toolbar's reload button turning into stop.
+   */
+  readonly loading?: boolean
+  /**
+   * The page's own favicon, re-encoded by the host as a small data: URL.
+   *
+   * The host fetches it through the view's own session and admits only a few
+   * raster types under a byte cap, so this never becomes a general-purpose
+   * network read. Like the title, it is visible to the page the chrome is
+   * injected into; a favicon is public artwork for a site the page could fetch
+   * itself, and the URL beside it is already reduced to an origin.
+   */
+  readonly favicon?: string
+}
+
+/**
+ * One saved page.
+ *
+ * Bookmarks belong to the profile, not to a page: they are stored by the host
+ * and pushed to the chrome, never kept in the page's own storage. localStorage
+ * is per origin, so a bookmark saved on one site was invisible on every other
+ * (measured: saved on iana.org, absent on example.com).
+ */
+export interface ChromeBookmark {
+  readonly url: string
+  readonly title: string
+}
+
+export interface ChromeWorkspaceState {
+  readonly epoch: number
+  readonly revision: number
+  readonly selectedTaskKey?: string
+  readonly panels: ChromePanels
+  readonly tasks: readonly ChromeTaskSummary[]
+  /** Tabs of the selected task, in creation order. */
+  readonly tabs: readonly ChromeTabSummary[]
+  readonly trail: readonly ChromeTrailEntry[]
+  readonly bookmarks: readonly ChromeBookmark[]
+  /** Chrome's bookmark bar, off until the user turns it on from the ⋮ menu. */
+  readonly bookmarkBar: boolean
+  /** Empty unless the chrome frame view failed to come up; then, why. */
+  readonly frameError?: string
+  /**
+   * What the host's own window reports: visible/minimized/content size/frame size.
+   *
+   * Kept because the window's real state and what a screenshot tool *thinks* it is
+   * are not the same thing — a capture that grabbed a helper window once looked
+   * exactly like the browser window having come up 158x26, and that cost two
+   * rounds before this made it visible.
+   */
+  readonly windowProbe?: string
+}
+
+export interface ChromeBootstrapMessage extends ChromeWorkspaceState {
+  readonly kind: 'bootstrap'
+}
+
+export type ChromePatchOperation =
+  | { readonly op: 'task.upsert'; readonly task: ChromeTaskSummary }
+  | { readonly op: 'task.remove'; readonly key: string }
+  | { readonly op: 'task.active'; readonly key?: string }
+  | { readonly op: 'task.thumbnail'; readonly key: string; readonly version: number; readonly dataUrl?: string }
+  | { readonly op: 'trail.append'; readonly taskKey: string; readonly entry: ChromeTrailEntry }
+  | { readonly op: 'trail.replace'; readonly taskKey?: string; readonly entries: readonly ChromeTrailEntry[] }
+  | { readonly op: 'panels.set'; readonly panels: ChromePanels }
+  | { readonly op: 'tabs.set'; readonly tabs: readonly ChromeTabSummary[] }
+  | { readonly op: 'bookmarks.set'; readonly bookmarks: readonly ChromeBookmark[] }
+  | { readonly op: 'bookmarkbar.set'; readonly visible: boolean }
+  // 切任务/切标签时让**新露出来的那个页面**从表面色淡进来（只在这一刻播，导航不播）。
+  | { readonly op: 'reveal' }
+  /**
+   * A popup the chrome frame view asked the page's copy to show, anchored where the
+   * frame's own button is (the frame is 84px tall — a menu drawn there is clipped).
+   */
+  | { readonly op: 'panel.state'; readonly id: string; readonly open: boolean; readonly left?: number; readonly width?: number }
+  /** One-shot feedback for the user (e.g. the result of importing a cookie file). */
+  | { readonly op: 'notice'; readonly text: string; readonly level?: 'warn' }
+
+export interface ChromePatchMessage {
+  readonly kind: 'patch'
+  readonly epoch: number
+  readonly revision: number
+  readonly operations: readonly ChromePatchOperation[]
+}
+
+export type ChromeMessage = ChromeBootstrapMessage | ChromePatchMessage
+
+export function createBootstrap(state: ChromeWorkspaceState): ChromeBootstrapMessage {
+  return { kind: 'bootstrap', ...state }
+}
+
+export function createPatch(
+  epoch: number,
+  revision: number,
+  operations: readonly ChromePatchOperation[],
+): ChromePatchMessage {
+  return { kind: 'patch', epoch, revision, operations }
+}

package/src/browser-electron/entry.ts

@@ -0,0 +1,115 @@
+/**
+ * Electron browser provider plugin entry: registers the Electron-backed
+ * `BrowserProvider` with `ctx.browser`. The provider needs a view host (real
+ * Electron `WebContentsView` objects). When a desktop shell supplies
+ * `ctx.electronViewHost`, that host is used (embedded, human-machine shared
+ * view). Otherwise the plugin self-hosts: it spawns its own Electron child
+ * (`host-main.js`) and drives it over a local TCP JSON-RPC socket, so
+ * installing the plugin is enough for `browser_*` tools to work on any
+ * surface.
+ * @module dsh-browser-plus/browser-electron
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { BrowserRuntime } from '../browser/runtime.ts'
+import { ElectronBrowserProvider } from './provider.ts'
+import type { ElectronBrowserViewHost } from './provider.ts'
+import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.ts'
+import { defaultWriteRoots } from './write-guard.ts'
+
+export {
+  ELECTRON_BROWSER_PROVIDER_ID,
+  ElectronBrowserProvider,
+} from './provider.ts'
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts'
+export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'browser-electron'
+
+/** The browser seam this provider registers into. */
+export const inject = ['browser']
+
+/** Plugin config: an optional externally-supplied view host. */
+export interface Config {
+  /** View host supplied by a desktop shell; absent -> self-host. */
+  readonly viewHost?: ElectronBrowserViewHost
+  /** Allow navigation only to HTTP(S) URLs. Default true. */
+  readonly httpOnly?: boolean
+  /**
+   * Absolute directories `browser_screenshot` and `browser_download` may
+   * write into. Absent -> the workspace and the OS temp directory. An explicit
+   * empty list denies every write.
+   */
+  readonly writeRoots?: string[]
+  /**
+   * Absolute directories `browser_upload_file` may read from. Absent -> the
+   * same default as writeRoots (the workspace and the OS temp directory).
+   */
+  readonly readRoots?: string[]
+  /**
+   * Which JavaScript world the injected page chrome lives in. `main` (default)
+   * is the proven path; `isolated` keeps the chrome's task state and its
+   * binding token out of the page's own context, at the cost of an extra CDP
+   * context per document. Opt in only after confirming the toolbar in a real
+   * window (see docs/SOAK-CHECKLIST.md).
+   */
+  readonly chromeWorld?: 'main' | 'isolated'
+  /**
+   * Replace the engine's User-Agent verbatim. When absent, Electron's
+   * `Electron/42.9.3` token is stripped and the matching client-hint headers
+   * are added, so the request fingerprint says Chrome instead of "this is a
+   * scripted Electron".
+   */
+  readonly userAgent?: string
+  /**
+   * Keep the automation fingerprint masked. Default true: Electron advertises
+   * itself in the User-Agent and sends no client hints, which is the loudest
+   * thing a bot check can read. Set false to send the engine's own fingerprint.
+   */
+  readonly maskAutomation?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  // Absent on surfaces without a desktop shell; the plugin self-hosts then.
+  viewHost: z.any(),
+  httpOnly: z.boolean().default(true),
+  // The defaults are materialized HERE, not left to the provider's
+  // `?? defaultWriteRoots()`: schemastery turns an absent array key into [],
+  // and an empty array is not nullish, so the provider would see an empty
+  // allow-list and refuse every write. Defaulting in the schema keeps absence
+  // meaning "the documented defaults" while an explicit [] still denies all.
+  writeRoots: z.array(z.string()).default(defaultWriteRoots()),
+  readRoots: z.array(z.string()).default(defaultWriteRoots()),
+  chromeWorld: z.union(['main', 'isolated'] as const).default('main'),
+  userAgent: z.string(),
+  maskAutomation: z.boolean().default(true),
+})
+
+/** Register the Electron browser provider with `ctx.browser`. */
+export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config): void {
+  // External host (desktop shell) wins; otherwise self-host. The self-hosted
+  // child is disposed with the fiber, mirroring the shell's lifetime.
+  const host: ElectronBrowserViewHost = config.viewHost
+    ?? new RemoteElectronViewHost(defaultHostMainPath(), {
+      chromeWorld: config.chromeWorld,
+      maskAutomation: config.maskAutomation,
+      ...config.userAgent === undefined ? {} : { userAgent: config.userAgent },
+    })
+  // Own the disposer on THIS plugin's fiber: registerBrowserProvider's effect
+  // is bound to the seam's own fiber (the browser row), so a reload of this
+  // row would otherwise collide with the still-registered provider
+  // (BROWSER_DUPLICATE_PROVIDER) or leave a stale provider behind.
+  const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, {
+    httpOnly: config.httpOnly,
+    ...config.writeRoots !== undefined ? { writeRoots: config.writeRoots } : {},
+    ...config.readRoots !== undefined ? { readRoots: config.readRoots } : {},
+  }))
+  ctx.effect(() => () => {
+    unregister()
+    if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
+      host.dispose()
+    }
+  })
+}

package/src/browser-electron/fingerprint.ts

@@ -0,0 +1,45 @@
+/**
+ * Request-fingerprint helpers.
+ *
+ * Electron advertises itself in the User-Agent (`Electron/42.9.3`) and sends no
+ * client hints at all, even though its own `navigator.userAgentData` reports
+ * Chromium — so a request claiming Chrome arrived with none of the sec-ch-ua
+ * headers Chrome always sends. These turn the engine's own values into the shape
+ * a real Chrome produces, without inventing a fingerprint the engine cannot
+ * back up: the brands here are the ones the engine itself reports.
+ * @module dsh-browser-plus/browser-electron/fingerprint
+ */
+
+/** Strip Electron's self-advertisement from a User-Agent. */
+export function stripElectronToken(userAgent: string): string {
+  return userAgent.replace(/\sElectron\/[\d.]+/, '')
+}
+
+/** The engine's Chrome major version, used to mirror its client-hint brands. */
+export function chromeMajor(userAgent: string): string | undefined {
+  return /Chrome\/(\d+)/.exec(userAgent)?.[1]
+}
+
+/** Serialize a brand list the way Chromium does in the sec-ch-ua header. */
+export function secChUa(brands: readonly { brand: string; version: string }[]): string {
+  return brands.map(brand => `"${brand.brand}";v="${brand.version}"`).join(', ')
+}
+
+/** sec-ch-ua-platform, spelled the way Chromium spells it per OS. */
+export function clientHintPlatform(platform: NodeJS.Platform = process.platform): string {
+  if (platform === 'win32') return '"Windows"'
+  if (platform === 'darwin') return '"macOS"'
+  return '"Linux"'
+}
+
+/**
+ * The language list to hand Chromium for a locale. Passing it through
+ * `setUserAgent` (rather than rewriting the header) lets Chromium apply its own
+ * q-weights, which is exactly the shape real Chrome produces; Electron otherwise
+ * sends the bare locale alone.
+ */
+export function acceptLanguagesFor(locale: string): string {
+  const base = locale.split('-')[0]
+  // Dedupe so an "en-US" locale does not produce "en-US,en,en".
+  return [...new Set([locale, base, 'en'])].join(',')
+}