dsh-builtin-browser 0.4.1 → 0.4.5

package/src/browser-electron/remote-host.ts

@@ -19,9 +19,11 @@
  * that connection proves knowledge of the random per-spawn token (passed to
  * the child via its stdin (first line, never in argv). A local process that
  * connects to the loopback port without the token can neither impersonate the
- * child nor inject replies — it is disconnected immediately. Commands are
- * only written after the hello authenticates, so a spoofed socket never
- * sees traffic.
+ * child nor inject replies — it is disconnected as soon as its first line
+ * arrives. Commands are only written after the hello authenticates, and every
+ * other inbound op (including the fire-and-forget `userAction` / `viewClosed`
+ * notifications) is dispatched only once that check has passed, so an
+ * unauthenticated peer can neither read traffic nor drive a session.
  * @module dsh-browser/browser-electron/remote-host
  */
 
@@ -501,6 +503,9 @@ class ElectronChildClient {
       const line = `${hostStamp()} spawn error: ${String(error)} electron=${electron} hostMain=${this.hostMainPath}`
       process.stderr.write(`[dsh-browser host] ${line}\n`)
       appendHostLog(`${line}\n`)
+      // The cached availability answer is retired by `onExit` below, which this reaches
+      // through fail(): the decision needs the host's view of what is on disk, not the
+      // client's.
       this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
     })
     this.child.on('exit', (code, signal) => {
@@ -523,11 +528,43 @@ class ElectronChildClient {
     })
   }
 
+  /**
+   * Drop the escalation kill once there is nothing left for it to target.
+   *
+   * Called on the paths where the child is known to be gone — after an observed exit, and on
+   * release. It is deliberately NOT called from `fail()`: a dead socket says nothing about the
+   * process on the other end, and the timer exists for exactly the case where the child ignores
+   * the socket closing. Clearing it there disarmed the only escalation there was, which is how
+   * a child that ignored its socket could outlive dispose() and keep holding the profile.
+   */
+  private clearKillGrace(): void {
+    if (this.killGraceTimer === undefined) return
+    clearTimeout(this.killGraceTimer)
+    this.killGraceTimer = undefined
+  }
+
+  /** Drop the "did not authenticate" deadline once it can no longer be meaningful. */
+  private clearHelloTimer(): void {
+    if (this.helloTimer === undefined) return
+    clearTimeout(this.helloTimer)
+    this.helloTimer = undefined
+  }
+
   /** Reject everything in flight, mark the client dead, and notify the host. */
   private fail(err: Error): void {
     if (this.dead) return
     this.dead = true
     this.connected = false
+    // The authentication deadline outlives the socket it was armed for otherwise: it is
+    // keyed on `awaitingHello` alone, so a client that already failed on some other path
+    // kept a live timer until it fired (harmless, but it is a dangling timer in a process
+    // that may be shutting down).
+    this.clearHelloTimer()
+    // NOT clearKillGrace(): this path runs when the SOCKET died, which says nothing about
+    // whether the process did. Clearing the escalation here disarmed it for exactly the case it
+    // exists for — a child that ignores its socket closing — so dispose() could return with the
+    // child still running and still holding the profile. The timer clears itself when the child
+    // exits, and `kill()` replaces it on an explicit release.
     // Tag every failure as "host gone" so the view layer can tell a dead host
     // apart from a page-level error and rebuild against a fresh child.
     const wrapped = err instanceof HostGoneError ? err : new HostGoneError(err.message)
@@ -600,19 +637,34 @@ class ElectronChildClient {
         // Non-protocol line; ignore.
         continue
       }
-      if (msg.op === 'userAction') {
-        // Fire-and-forget notification from the child's own UI (toolbar):
-        // there is no reply and no pending id — route it straight to the
-        // host's user-action handler (which the provider registered).
-        this.onUserAction?.(msg.action as BrowserUserAction)
-        continue
-      }
-      if (msg.op === 'viewClosed') {
-        // Fire-and-forget notification from the child's own UI: the human closed
-        // the window, so the interface that session showed is gone. The provider
-        // decides what that ends — browsing history and login state survive on
-        // disk, only the session itself does not.
-        this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+      if (msg.op === 'userAction' || msg.op === 'viewClosed') {
+        // A fire-and-forget notification from the child's own UI (toolbar). These carry no
+        // reply and no pending id, and they hand the provider a session-level verb — so they
+        // are dispatched ONLY once the peer has proved it knows the spawn token.
+        //
+        // They used to be handled before the hello check, while the module comment claimed an
+        // unauthenticated peer "is disconnected immediately … a spoofed socket never sees
+        // traffic". Both were wrong: any loopback process that won the race for the single
+        // accepted socket could inject `viewClosed` and end the human's browser session
+        // before the token check rejected it. Only the loopback interface can connect, so
+        // this is a same-machine race rather than a remote attack — which is exactly the
+        // kind of thing the token exists to close.
+        if (this.awaitingHello) {
+          this.awaitingHello = false
+          this.clearHelloTimer()
+          this.socket?.destroy()
+          this.fail(new Error('dsh-builtin-browser: browser host sent a notification before authenticating'))
+          return
+        }
+        if (msg.op === 'userAction') {
+          // Route it straight to the host's user-action handler (which the provider registered).
+          this.onUserAction?.(msg.action as BrowserUserAction)
+        } else {
+          // The human closed the window, so the interface that session showed is gone. The
+          // provider decides what that ends — browsing history and login state survive on
+          // disk, only the session itself does not.
+          this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+        }
         continue
       }
       if (this.awaitingHello) {
@@ -620,10 +672,7 @@ class ElectronChildClient {
         // Anything else (or a wrong token) means a spoofed connection: drop
         // it and fail every pending call rather than trust the line.
         this.awaitingHello = false
-        if (this.helloTimer !== undefined) {
-          clearTimeout(this.helloTimer)
-          this.helloTimer = undefined
-        }
+        this.clearHelloTimer()
         if (msg.op !== 'hello' || msg.token !== this.token) {
           this.socket?.destroy()
           this.fail(new Error('dsh-builtin-browser: browser host authentication failed'))
@@ -673,10 +722,38 @@ class ElectronChildClient {
     })
   }
 
-  /** Terminate the child. */
+  /**
+   * How long the child gets to exit by itself after the socket closes, before it is killed.
+   * The child quits on that signal, so in practice this is a few dozen milliseconds; the timer
+   * exists for the case where it does not, and it is deliberately NOT unref'd — the parent must
+   * stay alive long enough to enforce it, or the escalation would be dropped with the process.
+   */
+  private static readonly KILL_GRACE_MS = 500
+  private killGraceTimer: NodeJS.Timeout | undefined
+
+  /**
+   * Terminate the child, after giving it the chance to shut down properly.
+   *
+   * The socket goes first, because that is the signal the child actually handles: its `close`
+   * listener quits the app, and a normal quit is what lets Chromium write its profile out. Only
+   * a child still alive after the grace period is killed outright.
+   *
+   * This order used to be the other way round, justified by a comment claiming the child's own
+   * path "closes its window and flushes the profile", which made killing first the safer order.
+   * Both halves of that were wrong: the path ran `app.exit(0)`, which skips before-quit/will-quit
+   * and does not flush Chromium's profile writers at all; and on Windows `child.kill()` is
+   * TerminateProcess, which lands before the child can run any handler whatsoever. So the
+   * graceful path that comment was protecting never got to start, and the profile went
+   * unflushed on every single dispose.
+   */
   kill(): void {
+    this.clearHelloTimer()
     try { this.socket?.destroy() } catch { /* already closed */ }
-    this.child.kill()
+    const child = this.child
+    this.clearKillGrace()
+    this.killGraceTimer = setTimeout(() => {
+      try { child.kill() } catch { /* already gone */ }
+    }, ElectronChildClient.KILL_GRACE_MS)
   }
 }
 
@@ -730,6 +807,30 @@ const PROBE_RETRY_MS = (() => {
   return Number.isFinite(raw) && raw >= 0 ? raw : 30000
 })()
 
+/**
+ * Retry schedule for a browser host that will not stay up, in milliseconds, indexed by the
+ * number of consecutive failed starts (see {@link RemoteElectronViewHost.noteStartFailure}).
+ *
+ * The first entry is 0 on purpose: an ordinary one-off death must still heal on the very
+ * next call, which is the behaviour remote-host-recovery.test.mjs pins. From the second
+ * failure on, each attempt is spaced. `available()` can only answer "is there a binary",
+ * so a binary that exists and crashes on every launch (`code=1` with empty stderr) would
+ * otherwise produce an endless crash loop, one window per tool call, with nothing to make
+ * it stop.
+ */
+const START_RETRY_SCHEDULE_MS: readonly number[] = [0, 500, 2_000, 8_000, 30_000]
+
+/** Attempts after which the host stops retrying immediately and keeps the longest delay. */
+const START_FAILURES_MAX = START_RETRY_SCHEDULE_MS.length
+
+/** Two reports within this window describe the same dying child, not two attempts. */
+const START_FAILURE_DEDUPE_MS = 1_000
+
+/** Render a delay for a human-readable log line. */
+function formatDelay(ms: number): string {
+  return ms >= 1_000 ? `${(ms / 1_000).toFixed(1)}s` : `${String(ms)}ms`
+}
+
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -747,6 +848,12 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private electronAvailable: boolean | undefined
   /** Earliest time the next probe may run after a negative one. */
   private nextProbeAt = 0
+  /** Consecutive child starts that did not survive; drives {@link startRetryAt}. */
+  private startFailures = 0
+  /** Earliest time `ready()` may spawn another child after a failed start. */
+  private startRetryAt: number | undefined
+  /** When the last start failure was reported, used to keep one death to one log line. */
+  private lastStartFailureAt = 0
   /** Window groups (windowId per view), re-sent on every materialization so
    *  a restarted child still places views in the right windows. */
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
@@ -799,6 +906,38 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     return this.electronAvailable
   }
 
+  /**
+   * Retire the cached "an Electron binary is here" answer.
+   *
+   * A success is cached for the host's lifetime because rescanning on every tool call was
+   * the original bug — but the probe reads the FILESYSTEM, so it cannot see a binary that
+   * stops being usable afterwards. Only a real spawn attempt can observe that, which is why
+   * the two failure paths in {@link RemoteElectronViewHost.start} call this: the next
+   * `available()` rescans and reports what is actually on disk, instead of advertising a
+   * provider that cannot start.
+   */
+  private forgetBinary(): void {
+    this.electronAvailable = undefined
+    this.nextProbeAt = 0
+  }
+
+  /**
+   * Whether the binary the host would spawn — or the entry it needs — is no longer there.
+   *
+   * Only asked after a launch actually failed, so a healthy path never pays for it. The
+   * entry script counts because Electron exits 1 with empty stderr when it cannot load it,
+   * and resolution itself throws exactly when it can find nothing, which is the same answer.
+   * @returns true when the next `available()` must rescan instead of reusing its cache.
+   */
+  private binaryIsGone(): boolean {
+    if (!existsSync(this.hostMainPath)) return true
+    try {
+      return !existsSync(this.spawnExecutable ?? resolveElectronPath())
+    } catch {
+      return true
+    }
+  }
+
   /**
    * Ensure the child is up and ready (lazy on first use; restarts after a crash).
    *
@@ -821,25 +960,105 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       return gone
     }
     if (this.readyPromise !== undefined) return this.readyPromise
+    // Backoff gate for a host that keeps failing to START (see START_RETRY_SCHEDULE_MS).
+    // The client is undefined exactly when the previous child is gone — a start failure, or
+    // a child that died after it came up — so this only delays restarts, never first use.
+    const retryAt = this.startRetryAt
+    if (retryAt !== undefined && Date.now() < retryAt && this.client === undefined) {
+      const waitMs = retryAt - Date.now()
+      const waiting = Promise.reject(new HostGoneError(
+        `browser host did not start; retrying in ${formatDelay(waitMs)} `
+        + `(attempt ${String(this.startFailures)}${this.startFailures >= START_FAILURES_MAX ? ', start attempts are now spaced out rather than immediate' : ''})`,
+      ))
+      // Keep the rejection observable to callers while marking it handled here: the
+      // fire-and-forget callers that drive this path attach their own handler, but one that
+      // forgets must not turn the recovery gate into an unhandled rejection.
+      waiting.catch(() => undefined)
+      return waiting
+    }
     const started = this.start()
-    const wrapped = started.catch(error => {
-      // A failed startup must not poison the host forever: tear down whatever
-      // was half-created and let the next call retry from scratch.
-      if (this.readyPromise === wrapped) {
-        this.readyPromise = undefined
-        this.client?.kill()
-        this.client = undefined
-        this.server?.close()
-        this.server = undefined
-        this.pendingSocket?.destroy()
-        this.pendingSocket = undefined
-      }
-      throw error
-    })
+    const wrapped = started.then(
+      () => {
+        // A child that came up clears the record: the next death is a new failure, not
+        // another entry in this run of them.
+        this.startFailures = 0
+        this.startRetryAt = undefined
+      },
+      error => {
+        // Record the failure BEFORE tearing anything down, and gate the teardown on the
+        // retry state being gone rather than on readyPromise alone. Ordering matters: a
+        // child that exits while the readiness call is still in flight fires the client's
+        // 'exit' handler first (onChildExit invalidates this promise and starts the retry
+        // clock), and the rejection then lands here — at which point clearing startRetryAt
+        // would erase the very backoff that was just armed, so every tool call spawned
+        // another dying child. noteStartFailure's dedupe window counts that pair once.
+        this.noteStartFailure(error)
+        // A failed startup must not poison the host forever: tear down whatever
+        // was half-created and let the next call retry from scratch.
+        if (this.readyPromise === wrapped) {
+          this.readyPromise = undefined
+          this.client?.kill()
+          this.client = undefined
+          this.server?.close()
+          this.server = undefined
+          this.pendingSocket?.destroy()
+          this.pendingSocket = undefined
+        }
+        throw error
+      },
+    )
     this.readyPromise = wrapped
     return wrapped
   }
 
+  /**
+   * Record one child that did not survive, and set the earliest retry time.
+   *
+   * `available()` answers "is there a binary to spawn" from the FILESYSTEM, and a success
+   * there is cached for the host's lifetime (correctly — rescanning on every tool call was
+   * the bug). That probe therefore cannot see the failure mode where the binary exists and
+   * crashes on every launch: the signature `code=1` with empty stderr that host-log.test.mjs
+   * asserts. Each browser call then spawned a child that died within milliseconds, with no
+   * backoff and nothing that ever gives up — an endless crash loop, each iteration a window
+   * flashing on screen.
+   *
+   * The first retry is immediate, so the ordinary transient death (the DSH restart in
+   * remote-host-recovery.test.mjs) still heals on the very next call. After that the delay
+   * grows: once {@link START_FAILURES_MAX} attempts have failed, every later attempt is
+   * spaced by the table's last entry — the host keeps trying, but a permanently broken
+   * install now costs one spawn per 30s instead of one per tool call. Nothing is marked
+   * dead for good: a repaired installation heals on the next attempt, and `dispose()`
+   * still stops everything immediately.
+   * @param error - what the failed attempt reported.
+   */
+  private noteStartFailure(error: unknown): void {
+    // The same death arrives twice: the child's exit reports it, and ready() rejecting
+    // reports it again. Counting both pushed the first retry to the 500ms step and made
+    // the log say "attempt 2" for a first failure, while START_RETRY_SCHEDULE_MS[0] = 0
+    // exists precisely so an ordinary death heals on the next call. So a report inside the
+    // window is dropped ENTIRELY — the count and the log line alike.
+    //
+    // That last part used to be split in two: the guard below, and a second dedupe that only
+    // suppressed the LOG. The second one read `now - this.lastStartFailureAt` after the line
+    // above had already stored `failureAt` into that same field, so its window was 0-1ms wide
+    // and the comparison was unconditionally true — the log line was never written at all.
+    // Nothing noticed, because this function exists to make a silent failure visible and its
+    // only output was the thing being dropped: a child that exists and dies instantly (code=1,
+    // empty stderr) left no trace anywhere.
+    const failureAt = Date.now()
+    if (this.lastStartFailureAt !== undefined && failureAt - this.lastStartFailureAt < START_FAILURE_DEDUPE_MS) return
+    this.lastStartFailureAt = failureAt
+    this.startFailures += 1
+    const index = Math.min(this.startFailures, START_RETRY_SCHEDULE_MS.length) - 1
+    const delayMs = START_RETRY_SCHEDULE_MS[index] ?? 0
+    this.startRetryAt = delayMs > 0 ? failureAt + delayMs : undefined
+    const line = `${hostStamp()} browser host start failed (attempt ${String(this.startFailures)}`
+      + `${this.startFailures >= START_FAILURES_MAX ? ', giving up on immediate retries' : ''}): ${String(error)}`
+      + `${delayMs > 0 ? ` — next attempt in ${formatDelay(delayMs)}` : ''}`
+    process.stderr.write(`[dsh-browser host] ${line}\n`)
+    appendHostLog(`${line}\n`)
+  }
+
   private async start(): Promise<void> {
     // Listen on an ephemeral loopback port; the child connects back. The
     // server accepts exactly one connection: the child's. Any further
@@ -912,6 +1131,18 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     // ever kill it. Only the restart is suppressed, not the cleanup.
     const wasDisposed = this.disposed
     if (!wasDisposed) process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n')
+    // A child that started and then died is also a failed start, and it is the shape a crash
+    // loop takes (the child comes up far enough to be pending on `ping`, then exits): count
+    // it so the restart is spaced instead of attempted on every single tool call.
+    if (!wasDisposed) this.noteStartFailure('the browser host process exited')
+    // The cached `available()` answer came from the FILESYSTEM, so only a real attempt can
+    // contradict it. A binary that stops being usable after the probe said yes — an
+    // interrupted reinstall, a removed mount, a wiped cache — kept the provider advertised
+    // as available for the rest of the process's life, because provider selection reads
+    // that same cached yes; every later call then paid a doomed spawn. Both failure routes
+    // (a spawn error, and a child that exits) arrive here, so this is the one place that
+    // observes the loss, and it costs two stats on a path that is already failing.
+    if (this.binaryIsGone()) this.forgetBinary()
     this.client = undefined
     this.server?.close()
     this.server = undefined
@@ -1072,10 +1303,17 @@ class DeferredRemoteView implements ElectronViewHandle {
   private materializeOnce(): Promise<RemoteView> {
     if (this.materialized === undefined) {
       const pending = this.materialize()
-      this.materialized = pending.catch(error => {
-        if (this.materialized === pending) this.materialized = undefined
+      // Compare against the promise actually stored — the derived one — not against `pending`.
+      // Storing `pending.catch(...)` and comparing `this.materialized === pending` compared two
+      // different objects, so the test was never true and the reset never ran: a materialization
+      // that failed with anything other than a HostGoneError (the child alive but not answering
+      // a ping, say) poisoned the handle for good, and the retry the comment below promises was
+      // unreachable.
+      const guarded = pending.catch(error => {
+        if (this.materialized === guarded) this.materialized = undefined
         throw error
       })
+      this.materialized = guarded
     }
     return this.materialized
   }

package/src/browser-electron/rpc-ops.ts

@@ -0,0 +1,41 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+
+/** Operations the parent asks the child to perform. */
+export const RPC_OPS = [
+  'ping',
+  'createView',
+  'destroyView',
+  'showView',
+  'groupView',
+  'focus',
+  'command',
+  'capture',
+  'download',
+  'flushAuth',
+  'restoreAuth',
+  'navigate',
+  'new-tab',
+  'activate',
+  'close',
+  'back',
+  'forward',
+  'reload',
+  'userActionError',
+] as const
+
+/** Notifications the child sends the parent, which carry no reply. */
+export const RPC_NOTIFICATIONS = ['userAction', 'viewClosed'] as const
+
+/** One operation name. */
+export type RpcOp = (typeof RPC_OPS)[number]

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

@@ -0,0 +1,87 @@
+/**
+ * Admission for the settings route: who may read the document, and who may write it.
+ *
+ * Its own module for a blunt reason — `entry.ts` imports the host's peer packages (cordis, the
+ * tools registry) and therefore cannot be loaded by the test suite, while this is precisely the
+ * logic whose failure is invisible in a browser: too strict and the panel silently stops being
+ * able to save, too loose and any process on the machine can rewrite the operator's switches.
+ *
+ * It is NOT authentication, and cannot be. The plugin has no credential to check: DSH hands
+ * plugin routes the raw request (`packages/host/webserver/src/index.ts` registers handlers with
+ * no gate of its own), so the strongest same-origin evidence available is what a browser
+ * reliably sends.
+ *
+ * What that buys and what it does not:
+ *   - a plain HTTP client (curl, a script, another process) cannot WRITE, because it sends no
+ *     `user-agent` and no `accept-language`;
+ *   - a page of THIS origin can, because a browser sending a same-origin write looks exactly
+ *     like the panel. That is inherent to exposing an HTTP endpoint at all, and it is why the
+ *     settings panel's own text must not promise a lock that does not exist.
+ */
+import type { IncomingMessage } from 'node:http'
+
+/** The shell's own URL schemes. Only the shell can mint a document on one of these. */
+const APP_SCHEMES = ['dsh-app:', 'dsh-desktop:']
+
+/**
+ * The scheme of a header value, when it names a URL.
+ * @param value - a raw header value.
+ * @returns the scheme, or undefined when the value is absent, opaque or unparseable.
+ */
+function schemeOf(value: string): string | undefined {
+  if (value === '' || value === 'null') return undefined
+  try {
+    return new URL(value).protocol
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether a request may touch the settings document.
+ * @param request - the incoming request.
+ * @param writing - true for PUT/POST, which is held to the stricter rule.
+ * @returns whether the request is admitted.
+ */
+export function sameOrigin(request: IncomingMessage, writing = false): boolean {
+  const origin = String(request.headers.origin ?? '').trim()
+  const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase()
+
+  // A shell URL, in either the Origin or the referrer: the strongest evidence there is.
+  if (APP_SCHEMES.includes(schemeOf(origin) ?? '')) return true
+  if (APP_SCHEMES.includes(schemeOf(String(request.headers.referer ?? '')) ?? '')) return true
+
+  // MEASURED on the running desktop, and what three earlier attempts each guessed wrong: a
+  // request from the shell's own settings panel carries NO origin, NO sec-fetch-site and NO
+  // referer. It is not "dsh-app://app" and it is not "null" — the headers are simply absent,
+  // because Chromium attaches no cross-origin metadata to a request leaving a custom scheme.
+  //
+  // So the rule for that shape cannot be "a request without an Origin is a script", which is
+  // what refused every desktop save, and it cannot lean on `Sec-Fetch-Site` either. It has to
+  // test what a hand-rolled client does not send:
+  //   - a renderer sends a full Mozilla-compatible `user-agent` AND an `accept-language`;
+  //   - curl sends neither unless told to, and a local process that forges both can also read
+  //     the settings document directly — it sits readable on disk, as the panel's own text
+  //     says. This was never the boundary it looked like.
+  if (origin === '') {
+    const agent = String(request.headers['user-agent'] ?? '')
+    const language = String(request.headers['accept-language'] ?? '')
+    if (/^Mozilla\/5\.0/.test(agent) && language !== '') return true
+    // Reads stay open: they return the document the panel is already showing, and refusing them
+    // would only break hand-inspection of a file that sits readable on disk anyway.
+    return !writing
+  }
+
+  // `cross-site` is another origin entirely; `same-site` is another origin of the same site
+  // (a.example.com -> b.example.com), which is not this panel either. Both are refused.
+  if (site === 'cross-site' || site === 'same-site') return false
+  // `Origin: null` is a sandboxed or opaque-origin document. Never this panel.
+  if (origin === 'null') return false
+  try {
+    const parsed = new URL(origin)
+    // The host comparison is for http(s), where a page and its route share one host.
+    return parsed.host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
+  } catch {
+    return false
+  }
+}