dsh-builtin-browser 0.4.1 → 0.4.5

package/src/browser-electron/settings-store.ts

@@ -9,7 +9,7 @@
  * @module dsh-browser/browser-electron/settings-store
  */
 
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import type { BrowserChannel } from './system-browser.js'
@@ -50,6 +50,22 @@ export interface BrowserSettings {
   readonly credentials: {
     readonly allowRead: boolean
   }
+  /**
+   * What the agent is allowed to DO, as opposed to what it may look at.
+   *
+   * These are OPERATOR switches: the settings panel is not reachable from the model, so a
+   * value here refuses whatever the model asks for, and no tool can lift it. That is what
+   * separates them from `browser_restrict`, which is the model's own soft guardrail. All
+   * three default to on, which is the documented out-of-the-box behaviour.
+   */
+  readonly actions: {
+    /** Run arbitrary page scripts in the active tab (`browser_execute`). */
+    readonly allowExecute: boolean
+    /** Download a URL to disk (`browser_download`). */
+    readonly allowDownload: boolean
+    /** Write cookies — importing login state (`browser_auth` restore). */
+    readonly allowCredentialWrite: boolean
+  }
 }
 
 /** Defaults for every switch: the documented out-of-the-box behaviour. */
@@ -63,6 +79,7 @@ export const DEFAULT_SETTINGS: BrowserSettings = {
   // it starts a real Chrome/Edge with its own profile.
   browser: { channel: 'bundled' },
   credentials: { allowRead: true },
+  actions: { allowExecute: true, allowDownload: true, allowCredentialWrite: true },
 }
 
 /**
@@ -80,6 +97,38 @@ function bool(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback
 }
 
+/**
+ * Coerce one boolean field that GATES A CAPABILITY.
+ *
+ * The difference from {@link bool} is what a mistyped value means. Absent still takes the
+ * default — a document written before the switch existed is the documented behaviour. But
+ * present-and-not-a-boolean is a document this code cannot read, and for a switch that gates
+ * something the operator chose to limit, unreadable resolves to OFF. `bool`'s fallback made
+ * `"false"` (a string), `null` (a truncated write) and `1` all mean the same as `true`, so a
+ * single dropped byte reopened every capability that had been turned off.
+ * @param value - the raw value from the settings document.
+ * @param fallback - the default, used only when the field is absent.
+ * @returns the value when it is a boolean, `false` when it is anything else.
+ */
+function gate(value: unknown, fallback: boolean): boolean {
+  if (value === undefined) return fallback
+  return value === true
+}
+
+/**
+ * What an unreadable document resolves to.
+ *
+ * Only the capability gates are refused; everything else keeps its default. The distinction is
+ * deliberate: refusing history, presentation or browser choice would punish the user for a
+ * corrupt file without protecting anything, while refusing the gates is the whole point —
+ * "the operator's intent cannot be read" must not resolve to "the operator permits".
+ */
+const SETTINGS_WHEN_UNREADABLE: BrowserSettings = {
+  ...DEFAULT_SETTINGS,
+  credentials: { allowRead: false },
+  actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
+}
+
 /**
  * Coerce the browser channel, keeping the default when it is not one of the
  * known choices. A hand-edited typo must not silently select a different browser.
@@ -87,20 +136,42 @@ function bool(value: unknown, fallback: boolean): boolean {
  * @returns a valid channel.
  */
 function resolveChannel(value: unknown): BrowserChannel {
-  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
     ? value
     : DEFAULT_SETTINGS.browser.channel
 }
 
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  const floored = Math.floor(value)
+  // A fractional value below 1 floors to 0, and 0 is not "very few" in either place these are
+  // used: as a history entry cap it means `slice(len - 0)`, i.e. keep nothing, so a hand-typed
+  // `0.5` silently wiped the history file on the next rewrite. Anything that survives the
+  // floor has to still be a usable limit.
+  return floored > 0 ? floored : fallback
 }
 
 /** Read one nested section of an unknown document, or an empty object. */
-function section(source: Record<string, unknown>, key: string): Record<string, unknown> {
+/**
+ * Read one section of the document, distinguishing ABSENT from UNREADABLE.
+ *
+ * Absent (the key is not there at all) is a document written before the section existed, and
+ * the defaults apply — that is the documented behaviour. Present-but-not-an-object
+ * (`"actions": false`, `null` from a truncated write, a stray string) is a document this code
+ * cannot read, and returning `{}` for it made every gate inside look absent, so each one took
+ * its permissive default. A whole section mistyped is exactly the shape a careless hand edit
+ * produces, and it opened every capability the section was there to bound.
+ * @param source - the parsed document.
+ * @param key - the section name.
+ * @returns the section, or undefined when it is present but not an object.
+ */
+function section(source: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
   const value = source[key]
-  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {}
+  if (value === undefined) return {}
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
 }
 
 /**
@@ -118,21 +189,44 @@ export function resolveSettings(raw: unknown): BrowserSettings {
   const vision = section(source, 'vision')
   const credentials = section(source, 'credentials')
   const browser = section(source, 'browser')
+  const actions = section(source, 'actions')
+  // A section that is present but unreadable refuses its gates rather than defaulting them
+  // open. The rest of a broken section keeps its defaults: refusing history or presentation
+  // would punish the user for a bad file without protecting anything.
+  const credentialsUsable = credentials ?? {}
+  const actionsUsable = actions ?? {}
   return {
     history: {
-      enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
-      maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
-      maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+      enabled: bool(history?.enabled, DEFAULT_SETTINGS.history.enabled),
+      maxEntries: count(history?.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+      maxAgeDays: count(history?.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
     },
-    cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+    cookies: { persist: bool(cookies?.persist, DEFAULT_SETTINGS.cookies.persist) },
     ui: {
-      autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
-      closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
-      virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+      autoExpandOnce: bool(ui?.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+      closeWithSession: bool(ui?.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+      virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+    },
+    vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+    browser: { channel: resolveChannel(browser?.channel) },
+    credentials: {
+      // `gate` returns false for anything present-and-not-a-boolean, so an unreadable section
+      // is refused here for free: the section itself is the "present but wrong" value.
+      allowRead: credentials === undefined
+        ? false
+        : gate(credentialsUsable.allowRead, DEFAULT_SETTINGS.credentials.allowRead),
+    },
+    actions: {
+      allowExecute: actions === undefined
+        ? false
+        : gate(actionsUsable.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
+      allowDownload: actions === undefined
+        ? false
+        : gate(actionsUsable.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
+      allowCredentialWrite: actions === undefined
+        ? false
+        : gate(actionsUsable.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
     },
-    vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-    browser: { channel: resolveChannel(browser.channel) },
-    credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
   }
 }
 
@@ -163,18 +257,33 @@ export class SettingsStore {
    */
   get(): BrowserSettings {
     let mtimeMs = -1
-    let text: string | undefined
     try {
-      if (existsSync(this.file)) {
-        mtimeMs = statSync(this.file).mtimeMs
-        text = readFileSync(this.file, 'utf8')
-      }
+      // stat directly: existsSync costs about thirteen times what the stat does, and the
+      // stat already throws when the file is missing — which the catch below handles.
+      mtimeMs = statSync(this.file).mtimeMs
     } catch {
       // Unreadable file: fall through to defaults below.
       mtimeMs = -1
-      text = undefined
     }
+    // Return the cache BEFORE reading. The read used to happen first "just in case", which
+    // made the cache pointless: every call paid for a synchronous read of the whole file and
+    // then discarded it. This is on the path of every tool call that consults a setting, so
+    // it was a stat plus a read per call where a single stat will do.
     if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs) return this.cached
+
+    let text: string | undefined
+    if (mtimeMs !== -1) {
+      try {
+        text = readFileSync(this.file, 'utf8')
+      } catch {
+        // It was there a moment ago (the stat above) and cannot be read now: permissions, a
+        // lock, a directory in the way. That is not "no document" — the file is not absent, so
+        // what it said is unknown, and unknown resolves to the refusing document.
+        this.cached = SETTINGS_WHEN_UNREADABLE
+        this.cachedMtimeMs = mtimeMs
+        return this.cached
+      }
+    }
     try {
       // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
       // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
@@ -184,8 +293,12 @@ export class SettingsStore {
       const body = text?.replace(/^\uFEFF/, '')
       this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body))
     } catch {
-      // Malformed JSON: behave as defaults rather than fail startup.
-      this.cached = DEFAULT_SETTINGS
+      // A document that EXISTS but cannot be parsed is not the same as no document at all: the
+      // first is a corrupted or half-written file whose contents were the operator's decisions,
+      // the second is a first run. Resolving both to the defaults meant a kill during the write,
+      // or one stray character, silently reopened the capabilities that had been switched off —
+      // so this side refuses them instead (see SETTINGS_WHEN_UNREADABLE).
+      this.cached = SETTINGS_WHEN_UNREADABLE
     }
     this.cachedMtimeMs = mtimeMs
     return this.cached
@@ -201,7 +314,7 @@ export class SettingsStore {
     const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
     try {
       mkdirSync(dirname(this.file), { recursive: true })
-      writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`)
+      writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`)
     } catch (error) {
       // Do NOT publish the new value as cached, and do not pretend the file changed: a
       // reader compares the file's mtime against this stamp, so stamping "now" on a failed
@@ -218,6 +331,42 @@ export class SettingsStore {
   }
 }
 
+/**
+ * Replace a file's contents atomically: write a sibling temporary file, then rename it over
+ * the target.
+ *
+ * `writeFileSync(target, …)` truncates and rewrites in place, so a crash, a full disk or an
+ * antivirus lock in the middle leaves HALF a JSON document. That used to be silent: the reader
+ * resolved an unparseable file to the defaults, so a torn write flipped `credentials.allowRead`
+ * and the action switches back ON, and the next successful update wrote those defaults to disk
+ * for good. The read side no longer does that (see {@link SETTINGS_WHEN_UNREADABLE}) — but the
+ * write side still has to stop producing torn files at all, because half a document is not
+ * something this plugin should ever leave behind.
+ *
+ * The rename is the commit point: a reader sees either the old document or the new one,
+ * never a partial one. It stays in the same directory so the rename is atomic on Windows
+ * as well as POSIX (`renameSync` maps to MoveFileEx there: same-volume replaces are
+ * atomic, cross-volume ones are not supported at all).
+ *
+ * The temporary is written with a unique suffix rather than a fixed `.tmp`, so two writers
+ * (the settings panel and a second DSH process) cannot rename each other's half-written
+ * file into place. Shared with the history store, which had the same hole.
+ * @param file - the target path.
+ * @param contents - the complete new document.
+ */
+export function writeFileAtomic(file: string, contents: string): void {
+  const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`
+  try {
+    writeFileSync(temporary, contents)
+    renameSync(temporary, file)
+  } catch (error) {
+    // The rename is the commit point, so a failure before it leaves the target untouched —
+    // only the temporary has to go, and it must not be left behind as garbage.
+    try { rmSync(temporary, { force: true }) } catch { /* the temp is already the least of it */ }
+    throw error
+  }
+}
+
 /** One-level-deep merge over the settings sections (patch wins). */
 function deepMerge(base: Record<string, unknown>, patch: unknown): Record<string, unknown> {
   if (typeof patch !== 'object' || patch === null) return base