@linxin666/dsh-remote-web-ui 0.4.1 → 0.4.3

package/src/lan-bind.ts

@@ -21,6 +21,7 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve, sep } from 'node:path'
+import { parseDocument } from 'yaml'
 import { dshHome } from './dsh-home.ts'
 
 /** Profile names safe to interpolate into the patch path: one path segment, no traversal. */
@@ -34,7 +35,7 @@ export type LanBindHost = '0.0.0.0' | '127.0.0.1'
 
 /**
  * The absolute path of the profile patch file this toggle manages. The value
- * is config-controlled (and the DSH_PROFILE env fallback bypasses schema
+ * is config-controlled (and the runtime/environment fallbacks bypass schema
  * validation entirely), so the path is guarded twice: the profile must be a
  * single safe path segment, and the resolved file must stay under the
  * profiles directory.
@@ -69,6 +70,62 @@ export function stripManagedBlock(content: string): string {
   return content.replace(pattern, '\n')
 }
 
+/**
+ * Render the managed block for one bind state. The values are static: the
+ * user patch layer has no reliable lazy service evaluation, and the plugin
+ * re-asserts the block at every boot so CLI flags (--port, --host) win by
+ * rewriting it before the next start.
+ */
+/**
+ * Whether the base opens a flow collection at the root. That is the shape the
+ * plugin manager's YAML document round-trip leaves behind when it appends rows
+ * to the profile's placeholder `[]`: `[ { id: … }, … ]`. Every other base
+ * (empty, block sequence, comment-only prefix) keeps the historical string
+ * concatenation, so the common paths stay byte-identical.
+ */
+function isFlowRoot(base: string): boolean {
+  return base.trimStart().startsWith('[')
+}
+
+/** Force one parsed collection (and its item collections) into block style. */
+function toBlockStyle(node: unknown): void {
+  if (typeof node !== 'object' || node === null) return
+  const collection = node as { flow?: boolean; items?: unknown[] }
+  if (!Array.isArray(collection.items) && typeof collection.flow !== 'boolean') return
+  collection.flow = false
+  for (const item of collection.items ?? []) toBlockStyle(item)
+}
+
+/** Plain-value view of one parsed node (YAML nodes keep their own accessors). */
+function plainOf(node: unknown): unknown {
+  if (typeof node !== 'object' || node === null) return node
+  const json = (node as { toJSON?: () => unknown }).toJSON
+  return typeof json === 'function' ? json.call(node) : node
+}
+
+/**
+ * Produce the file text for one bind state. A flow-style base is re-emitted as
+ * a block sequence before the managed block is appended, so the file stays
+ * exactly one valid YAML document; concatenating the block onto a non-empty
+ * flow array produced two root documents and the profile failed to parse at
+ * `dsh web` startup (#1675). A base that cannot be parsed is refused with the
+ * file path rather than written half-valid.
+ */
+function mergePatchContent(base: string, block: string, file: string): string {
+  if (base.length === 0) return block
+  if (!isFlowRoot(base)) return `${base}\n\n${block}`
+  const doc = parseDocument(base, { uniqueKeys: false })
+  if (doc.errors.length > 0 || doc.contents === null) {
+    throw new Error(`remote-web-ui: cannot update the lan-bind block in ${file}: ${doc.errors[0]?.message ?? 'the patch file is not a YAML document'}`)
+  }
+  if (!('items' in (doc.contents as { items?: unknown[] }))) {
+    throw new Error(`remote-web-ui: cannot update the lan-bind block in ${file}: the patch file is not a top-level patch list`)
+  }
+  toBlockStyle(doc.contents)
+  const rendered = doc.toString({ lineWidth: 0 }).trimEnd()
+  return `${rendered}\n\n${block}`
+}
+
 /**
  * Render the managed block for one bind state. The values are static: the
  * user patch layer has no reliable lazy service evaluation, and the plugin
@@ -130,6 +187,10 @@ export function lanBindState(profile: string, home: string = dshHome()): { block
  * unterminated block (BEGIN marker without END, which stripManagedBlock
  * cannot match) is truncated at its BEGIN marker first so the rewrite can
  * never stack a second webserver row onto the orphan.
+ *
+ * The written file is always exactly one valid YAML document: a base the
+ * plugin manager left in flow style is re-emitted as a block sequence before
+ * the managed block is appended (see mergePatchContent).
  */
 export function writeLanBind(host: LanBindHost, port: number, profile: string, home: string = dshHome()): void {
   const file = profilePatchFile(profile, home)
@@ -138,7 +199,7 @@ export function writeLanBind(host: LanBindHost, port: number, profile: string, h
   const rawBase = (orphanBegin === -1 ? stripped : stripped.slice(0, orphanBegin)).trimEnd()
   const base = rawBase.replace(/\[\s*\]\s*$/, '').trimEnd()
   const block = managedBlock(host, port)
-  const content = base.length > 0 ? `${base}\n\n${block}` : block
+  const content = mergePatchContent(base, block, file)
   const mode = existsSync(file) ? statSync(file).mode & 0o777 : 0o600
   mkdirSync(dirname(file), { recursive: true })
   const temp = `${file}.remote-web-ui-tmp-${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`

package/src/mount-once.ts

@@ -5,44 +5,138 @@
  * the loader accepts a standalone install of the same package side by side;
  * without this guard the second instance would still re-register the same
  * webserver routes, tools, settings namespaces, and system-prompt sections
- * and fail the boot. mountOnce makes the second host apply a no-op for the
- * lifetime of the first instance (the browser half is already deduped by
- * package name in the client module host).
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
+ * no-op for as long as the first instance lives (the browser half is already
+ * deduped by package name in the client module host).
+ *
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
+ * long after the refused mount ran its course: the Host reloads a profile by
+ * creating the new loader entries before the old ones are torn down (a
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
+ * previous entry still owns the name. Dropping that refused mount lost the
+ * plugin for good - the previous entry then disposed its own mount, releasing
+ * the name with nobody left to take it, and the family row stayed listed as
+ * active while its host routes 404ed (the task-board panel showed
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
+ * restart recovered it).
+ *
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
+ * the holder releases the name - if the waiting fiber is still alive then. The
+ * single-instance guarantee is unchanged: exactly one mount is live per
+ * package name, and the replay re-enters the guard so a later mount still
+ * dedupes against it.
  *
  * The registry rides a global symbol so two module instances of the same
- * package (npm copy vs repository link) still share one verdict. cordis
- * `ctx.effect` runs its callback immediately and treats the callback's
+ * package (npm copy vs repository link) still share one verdict. That symbol
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
+ * dsh-community-plugins) are separate repositories carrying their own copy of
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+ * must keep the shape every published copy reads (a `Set` of package names
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
+ * under their own additive key, and the registry reads back a `Set` even when
+ * some other build left a different value there. Changing `MOUNTED`'s shape
+ * in place broke that contract once: a satellite's legacy copy created a
+ * `Set`, the family's new copy read it as a `Map`, and every family row
+ * mounted after it failed with "claims.get is not a function".
+ *
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
  * return value as the fiber disposer, so the unmarker is returned, not run.
  */
 
+/** Published cross-repository contract: package names currently mounted. */
 const MOUNTED = Symbol.for('dsh-web.mounted-plugins')
 
+/** Additive key this guard owns: refused mounts waiting for the name. */
+const WAITERS = Symbol.for('dsh-web.mounted-plugins.waiters')
+
+/** The slice of a cordis context this guard touches. */
+interface MountContext {
+  effect?: (effect: () => unknown) => unknown
+}
+
+/** One mount that was refused while another fiber owned the package name. */
+interface PendingMount {
+  /** Replay the refused mount; a no-op once its own fiber has been disposed. */
+  run(): void
+}
+
 interface MountRegistry {
-  [MOUNTED]?: Set<string>
+  [MOUNTED]?: unknown
+  [WAITERS]?: Map<string, PendingMount[]>
 }
 
+/**
+ * The shared name registry, always a `Set` whatever another build stored here:
+ * a foreign value (an interim shape, a hand-written global) must not take every
+ * family plugin down with it.
+ * @returns the process-wide set of mounted package names.
+ */
 function mountedSet(): Set<string> {
   const registry = globalThis as MountRegistry
-  return (registry[MOUNTED] ??= new Set())
+  const existing = registry[MOUNTED]
+  if (existing instanceof Set) return existing as Set<string>
+  const created = new Set<string>()
+  registry[MOUNTED] = created
+  return created
+}
+
+/** Queue per package name for mounts refused while a holder was alive. */
+function mountWaiters(): Map<string, PendingMount[]> {
+  const registry = globalThis as MountRegistry
+  return (registry[WAITERS] ??= new Map())
 }
 
 /**
  * Wrap a cordis plugin apply so the package runs at most once per process.
- * The first mount registers normally and unmarks when its fiber disposes;
- * any later mount of the same package name is a no-op.
+ * The first mount registers normally and releases the name when its fiber
+ * disposes; a mount refused while that name is held waits for the release and
+ * then runs, unless its own fiber disposes first.
  * @param packageName - npm package identity shared by every install source.
  * @param fn - the original plugin apply.
  * @returns an apply of the same shape.
  */
 export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
-  return ((...args: unknown[]) => {
+  const mount = (...args: unknown[]): unknown => {
     const mounted = mountedSet()
-    if (mounted.has(packageName)) return
+    const ctx = args[0] as MountContext | undefined
+    if (mounted.has(packageName)) {
+      // Another fiber (the aggregate row, a standalone install, or a copy built
+      // from an older revision of this guard) owns the name. Queue instead of
+      // dropping: dropping lost the plugin for the rest of the process when the
+      // holder was disposed by a reload.
+      const waiters = mountWaiters()
+      const queue = waiters.get(packageName) ?? []
+      let alive = true
+      const pending: PendingMount = {
+        run: () => {
+          if (alive) mount(...args)
+        },
+      }
+      // A fiber that dies while it waits must not be replayed afterwards: its
+      // context is disposed and registering effects on it would throw.
+      ctx?.effect?.(() => () => {
+        alive = false
+        const index = queue.indexOf(pending)
+        if (index >= 0) queue.splice(index, 1)
+      })
+      queue.push(pending)
+      waiters.set(packageName, queue)
+      return
+    }
     mounted.add(packageName)
-    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
     ctx?.effect?.(() => () => {
       mounted.delete(packageName)
+      const waiters = mountWaiters()
+      const queue = waiters.get(packageName)
+      if (queue === undefined) return
+      waiters.delete(packageName)
+      // Defer the handover one microtask so the disposing mount's own effects
+      // (routes, ledger, timers) are torn down before the next one registers.
+      for (const waiter of queue.splice(0)) queueMicrotask(() => { waiter.run() })
     })
     return fn(...args)
-  }) as T
+  }
+  return mount as T
 }

package/src/pairing.persist.test.ts

@@ -96,17 +96,61 @@ describe('PairingService device persistence', () => {
     expect(restarted.hasDevice(deviceId)).toBe(true)
   })
 
-  it('clamps a persisted table to maxDevices when the file holds more sessions', () => {
+  // #1696: the constructor runs before the saved settings row is applied, so
+  // its cap can still be the schema default. Restoring must not enforce it —
+  // trimming there silently revokes authorizations the user never revoked,
+  // and the trimmed table reaches disk on the next heartbeat/sweep write.
+  it('operator: every valid persisted session survives a restart under the startup cap', () => {
     const file = join(dir, 'devices.json')
+    // Given a store holding three devices while the startup cap reads 4
+    // (the schema default) and the saved settings value is 12.
     writeFileSync(file, JSON.stringify({
       dev1: { createdAt: 1_000, lastSeenAt: 1_000 },
       dev2: { createdAt: 2_000, lastSeenAt: 2_000 },
       dev3: { createdAt: 3_000, lastSeenAt: 3_000 },
     }))
-    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
-    expect(service.hasDevice('dev3')).toBe(true)
+    // When a new process restores the store.
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 4, devicesFile: file }, makeClock())
+    // Then no paired device lost its authorization to the transient cap.
+    expect(service.hasDevice('dev1')).toBe(true)
     expect(service.hasDevice('dev2')).toBe(true)
+    expect(service.hasDevice('dev3')).toBe(true)
+  })
+
+  it('operator: a restored over-cap table is not trimmed by a heartbeat and sweep', () => {
+    const file = join(dir, 'devices.json')
+    // Given twelve persisted devices restored under the default cap of 4.
+    const rows = Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`dev${i}`, { createdAt: 1_000 + i, lastSeenAt: 1_000 + i }]),
+    )
+    writeFileSync(file, JSON.stringify(rows))
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 4, devicesFile: file }, makeClock())
+    // When the saved cap of 12 arrives and normal traffic writes the store.
+    service.config = { ...service.config, maxDevices: 12 }
+    service.heartbeat('dev0')
+    service.sweep()
+    // Then the file still names all twelve devices.
+    const persisted = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    expect(Object.keys(persisted)).toHaveLength(12)
+    expect(service.deviceCount()).toBe(12)
+  })
+
+  it('operator: the cap is enforced when a device is admitted, not before', () => {
+    const file = join(dir, 'devices.json')
+    // Given three persisted devices restored under a cap of 2.
+    writeFileSync(file, JSON.stringify({
+      dev1: { createdAt: 1_000, lastSeenAt: 1_000 },
+      dev2: { createdAt: 2_000, lastSeenAt: 2_000 },
+      dev3: { createdAt: 3_000, lastSeenAt: 3_000 },
+    }))
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
+    expect(service.deviceCount()).toBe(3)
+    // When one more device pairs.
+    const paired = pairDevice(service)
+    // Then the table is trimmed to the cap, oldest first, keeping the newcomer.
+    expect(service.deviceCount()).toBe(2)
     expect(service.hasDevice('dev1')).toBe(false)
+    expect(service.hasDevice(paired)).toBe(true)
   })
 
   it('keeps sessions memory-only when devicesFile is unset', () => {

package/src/pairing.ts

@@ -248,6 +248,14 @@ export class PairingService {
    * Restore device sessions persisted by a previous process run. A corrupt
    * or missing file is tolerated (an empty device table, never a throw) —
    * persistence is an availability convenience, not a security boundary.
+   *
+   * Every still-valid session is restored, deliberately without applying
+   * `maxDevices`: the constructor runs with whatever cap the configuration
+   * layer has delivered so far (the schema default until the saved settings
+   * row is applied), and trimming here would permanently drop authorizations
+   * the user never revoked — the trimmed table reaches disk on the next
+   * heartbeat/sweep write. The cap is enforced where a device is admitted
+   * (see `accept`), against the configuration in force at that moment.
    */
   private loadPersisted(): void {
     const file = this.config.devicesFile
@@ -271,21 +279,12 @@ export class PairingService {
           ...(label !== undefined ? { userAgent: label } : {}),
         })
       }
-      this.clampToMaxDevices()
       if (this.evictIdle()) this.persistRevocation()
     } catch {
       // Unreadable/corrupt: start empty rather than refusing to boot.
     }
   }
 
-  /** FIFO-cap the device table (a persisted file may outlive a lowered cap). */
-  private clampToMaxDevices(): void {
-    if (this.devices.size <= this.config.maxDevices) return
-    const overflow = this.devices.size - this.config.maxDevices
-    const ordered = [...this.devices.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt)
-    for (const [id] of ordered.slice(0, overflow)) this.devices.delete(id)
-  }
-
   /** Drop sessions whose lastSeenAt is older than idleExpireMs. */
   private evictIdle(): boolean {
     const now = this.clock.now()
@@ -457,13 +456,18 @@ export class PairingService {
     }
     const deviceId = this.clock.randomToken()
     const now = this.clock.now()
-    if (this.devices.size >= this.config.maxDevices) {
-      // Evict the oldest session (FIFO) before binding a new device.
+    // FIFO-evict until a slot is free. The loop (not a single delete) covers a
+    // table that is already over the cap: restore keeps every persisted session
+    // (see loadPersisted), so the excess is collected here, once the store is
+    // actually asked to admit a new device, rather than at startup on a cap the
+    // configuration may not have delivered yet.
+    while (this.devices.size >= this.config.maxDevices) {
       let oldest: { id: string; createdAt: number } | undefined
       for (const [id, session] of this.devices) {
         if (oldest === undefined || session.createdAt < oldest.createdAt) oldest = { id, createdAt: session.createdAt }
       }
-      if (oldest !== undefined) this.devices.delete(oldest.id)
+      if (oldest === undefined) break
+      this.devices.delete(oldest.id)
     }
     const label = sanitizeUserAgent(userAgent)
     this.devices.set(deviceId, {
@@ -570,6 +574,16 @@ export class PairingService {
     return this.liveSession(deviceId) !== undefined
   }
 
+  /**
+   * Number of device sessions in the table, including idle ones whose idle
+   * window has not been swept yet. Restore keeps every persisted session
+   * (see `loadPersisted`), so this can exceed the configured cap until the
+   * next `accept` trims the excess.
+   */
+  deviceCount(): number {
+    return this.devices.size
+  }
+
   /** Subscribe to snapshot changes (each emit passes a fresh snapshot). */
   onState(listener: (snapshot: PairingSnapshot) => void): () => void {
     this.listeners.add(listener)

package/src/remote-channel-boot.ts

@@ -45,10 +45,20 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
   return '(function(){' +
     'try{' +
     'var w=window,loc=w.location,h=loc.hostname;' +
-    // Loopback origins (including the bracketed IPv6 literal WHATWG returns)
-    // keep the original paths (mirrors isLoopbackHostname).
-    "if(h==='localhost'||h==='::1'||h==='[::1]'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
     'var R=' + json + ';' +
+    // A page the machine itself serves keeps the original paths and no
+    // channel: loopback names (including the bracketed IPv6 literal WHATWG
+    // returns), any scheme no web transport carries (an application on this
+    // machine delivered it - the desktop shell's own scheme, a file page, a
+    // scheme a newer shell introduces), or a shell the official transport
+    // already declared the host owner. This mirrors isLocalPage in
+    // remote-channel-rules.ts, which owns the decision.
+    "if(h==='localhost'||h==='::1'||h==='[::1]'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
+    'var pr=loc.protocol;' +
+    'if(typeof pr==="string"&&pr!==""&&R.webProtocols.indexOf(pr)===-1)return;' +
+    // ownsHost alone does not lift the fence: the plugin's own device-gated
+    // landing grants it to a paired LAN/tunnel page, which must stay gated.
+    'try{if(w.__DSH_TRANSPORT__&&w.__DSH_TRANSPORT__.ownsHost===true&&h.indexOf(".")===-1&&h.indexOf(":")===-1)return}catch(e){}' +
     // Host mode is server-granted: only the device-gated app landing
     // publishes the grant marker (in a capture script that runs ahead of
     // this one), so a shell that merely sits on a non-loopback origin - an

package/src/remote-channel-rules.ts

@@ -11,6 +11,111 @@ export const REMOTE_PREFIX = '/remote'
 
 import { REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY } from './remote-methods.ts'
 
+/**
+ * The schemes that can deliver a page a remote party controls: the network
+ * transports, plus the documents a network page can mint. Every other scheme
+ * is registered and served by an application on this machine, so its page is
+ * the machine's own page whatever the application calls the scheme.
+ *
+ * The list is deliberately the *web* side rather than an allowlist of known
+ * desktop shells. The official DSH Desktop shell serves its Web GUI from
+ * `dsh-app://app/` (`location.hostname === 'app'`), which no hostname
+ * predicate can recognise; a scheme allowlist fixed that instance (#1682) but
+ * left the next shell — or a `file:` page — fenced behind a pairing page it
+ * can never complete, because a pairing link is reachable only over the
+ * network. Naming the web side instead makes an unknown application scheme
+ * local by construction.
+ *
+ * `blob:`, `data:`, `about:` and `filesystem:` stay on the web side: a
+ * network page mints those documents, so they must keep the fence.
+ */
+export const WEB_PAGE_PROTOCOLS: readonly string[] = [
+  'http:',
+  'https:',
+  'blob:',
+  'data:',
+  'about:',
+  'filesystem:',
+]
+
+/**
+ * Whether one page scheme can carry a document a remote party controls.
+ * @param protocol - `location.protocol` of the page (for example `https:`).
+ * @returns true for the network transports and the documents they mint.
+ */
+export function isWebPageProtocol(protocol: string): boolean {
+  return WEB_PAGE_PROTOCOLS.includes(protocol)
+}
+
+/**
+ * Hostname-only loopback classification: localhost, the IPv6 loopback literal
+ * (WHATWG keeps its brackets) and any 127/8 IPv4 literal. Kept string-in,
+ * boolean-out and dependency-free so the browser half and the inlined boot
+ * script can both run it verbatim.
+ * @param hostname - a page/cookie hostname, IPv6 literals bracketed.
+ * @returns true for a loopback name or literal.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Whether the current page is served from the machine running the host, so
+ * its same-origin traffic must NOT be fenced behind the pairing channel.
+ * Three independent facts all describe the page itself and any one is enough:
+ *
+ * - the page's own hostname is loopback;
+ * - the page's protocol is not a {@link WEB_PAGE_PROTOCOLS} web scheme, so an
+ *   application on this machine delivered it — the desktop shell's
+ *   `dsh-app://app/` is one such page, and a scheme this build has never
+ *   heard of is another;
+ * - the official connection transport already declared this shell the host
+ *   owner (`__DSH_TRANSPORT__.ownsHost === true`) AND the page is not a
+ *   network origin. The official client reads the same hook to derive
+ *   `connection.isLoopback`, and the desktop shell sets it before any boot
+ *   entry — without this term the plugin's predicate contradicts the host's
+ *   own conclusion (#1682). The network-origin guard is deliberate: this
+ *   plugin's own device-gated landing (a LAN or tunnel page) publishes the
+ *   same hook to grant a paired remote the full UI, and that page must keep
+ *   riding the gated channel — `ownsHost` buys the presentation, never an
+ *   exemption from the pairing fence.
+ *
+ * The order matters: loopback is checked first so a loopback page keeps its
+ * exemption even on a scheme no list carries, and the scheme test runs before
+ * the hook test so a web page always reaches the network-origin guard. A
+ * missing or empty scheme is not evidence of a local page - the fence stays
+ * up - because a real document always reports its own scheme.
+ *
+ * @param hostname - `location.hostname` of the page.
+ * @param protocol - `location.protocol` of the page (for example `https:`).
+ * @param transportOwnsHost - `__DSH_TRANSPORT__?.ownsHost` as read by the caller.
+ * @returns true when the page is local and needs no remote channel.
+ */
+export function isLocalPage(hostname: string, protocol?: string, transportOwnsHost?: boolean): boolean {
+  if (isLoopbackHostname(hostname)) return true
+  // A missing or empty scheme is not evidence of a local page: a real
+  // document always reports one, so the fence stays up when it is unreadable.
+  if (protocol !== undefined && protocol !== '' && !isWebPageProtocol(protocol)) return true
+  // A granted remote also sets ownsHost; only a page whose own origin is
+  // otherwise local may treat the hook as proof of a local page.
+  return transportOwnsHost === true && !isNetworkOrigin(hostname)
+}
+
+/**
+ * Whether a hostname can only be reached across a network, so a page on it is
+ * remote whatever transport hook it carries: any IPv4/IPv6 literal (a dot or a
+ * colon) or any dotted DNS name. A hostname with no dot and no colon is a
+ * scheme-local authority (the desktop shell's `app`), which is why this test,
+ * not a loopback test, is what the `ownsHost` term is gated on.
+ * @param hostname - the page hostname.
+ * @returns true when the page cannot be the machine's own local page.
+ */
+function isNetworkOrigin(hostname: string): boolean {
+  return hostname.includes('.') || hostname.includes(':')
+}
+
 export { REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY }
 
 /** Connection-plugin method prefix under the gated channel. */
@@ -44,6 +149,13 @@ export interface RemoteChannelRules {
   readonly uploadPath: string
   /** Page global the pre-Cordis upload hook is published under. */
   readonly uploadHookGlobal: string
+  /**
+   * Schemes that can carry a remotely controlled document (see
+   * WEB_PAGE_PROTOCOLS): a page on any other scheme is delivered by an
+   * application on this machine. Carried in the rules so the inlined boot
+   * script applies the same list.
+   */
+  readonly webProtocols: readonly string[]
   /**
    * Page global carrying the server-issued host-mode grant. Only the plugin's
    * own device-gated app landing (/pair-app) publishes it; the boot patch
@@ -79,6 +191,7 @@ export const REMOTE_CHANNEL_RULES: RemoteChannelRules = {
   deviceQuery: REMOTE_DEVICE_QUERY,
   uploadPath: '/api/session/uploadFileBinary',
   uploadHookGlobal: '__DSH_FILE_UPLOAD__',
+  webProtocols: WEB_PAGE_PROTOCOLS,
   hostGrantGlobal: REMOTE_HOST_GRANT_GLOBAL,
 }