@linxin666/dsh-remote-web-ui 0.3.5 → 0.3.9

package/src/client/pair-api.ts

@@ -97,7 +97,6 @@ export interface DeviceFrame {
 /**
  * Mint a fresh pairing token (one active token at a time — this invalidates
  * any previous link).
- * @param workspaceId - optional current workspace to deep-link the phone into.
  * @param address - optional LAN IP literal the QR must be built from (the
  * default is the first interface); unknown literals refuse with
  * 'unknown-address'.
@@ -105,12 +104,11 @@ export interface DeviceFrame {
  * 0.0.0.0), or the forbidden refusal (the loopback-only fence rejected this
  * origin — the panel is a desktop control endpoint).
  */
-export async function issuePair(workspaceId?: string, address?: string): Promise<IssueResponse> {
+export async function issuePair(address?: string): Promise<IssueResponse> {
   const response = await fetch('/api/pair/issue', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({
-      ...(workspaceId !== undefined ? { workspaceId } : {}),
       ...(address !== undefined ? { address } : {}),
     }),
   })
@@ -166,15 +164,11 @@ export async function sendHeartbeat(): Promise<void> {
   await fetch('/api/pair/heartbeat', { method: 'POST' })
 }
 
-/** Whether the current page URL carries a pairing token / workspace target. */
-export function readPairParams(search: string): { pair?: string; workspace?: string } {
+/** Whether the current page URL carries a pairing token. */
+export function readPairParams(search: string): { pair?: string } {
   const params = new URLSearchParams(search)
   const pair = params.get('pair')
-  const workspace = params.get('workspace')
-  return {
-    ...(pair !== null && pair !== '' ? { pair } : {}),
-    ...(workspace !== null && workspace !== '' ? { workspace } : {}),
-  }
+  return pair !== null && pair !== '' ? { pair } : {}
 }
 
 /**
@@ -188,11 +182,28 @@ export function stripParam(name: string): string {
   return url.search
 }
 
-/** Convert an issued `/m/` link into the desktop pairing form. */
-export function desktopPairUrl(mobileUrl: string): string {
-  const url = new URL(mobileUrl)
-  url.pathname = '/'
-  return url.href
+/** LAN-bind status frame from the loopback-only card endpoint. */
+export interface LanBindFrame {
+  profile: string
+  /** The config toggle: true/false once flipped, null while untouched. */
+  setting: boolean | null
+  /** The bind default the managed patch block currently pins. */
+  blockHost: string | null
+  /** The live bind of the running web server. */
+  bindHost: string
+  port: number
+  lanUrls: string[]
+  firewall: { ok: boolean; managed: boolean; note?: string }
+  platform: string
+  /** true when the running bind has not caught up with the toggle yet. */
+  pendingRestart?: boolean
+}
+
+/** Read the LAN-bind facts (loopback-only endpoint). */
+export async function readLanBindStatus(): Promise<LanBindFrame> {
+  const response = await fetch('/api/pair/lan-bind')
+  if (!response.ok) throw new Error(`remote-web-ui: lan-bind status failed with ${String(response.status)}`)
+  return await response.json() as LanBindFrame
 }
 
 /** Human-readable expiry clock, e.g. "10:35". */

package/src/client/remote-channel.ts

@@ -133,6 +133,7 @@ export interface ChannelWindow {
   HTMLScriptElement?: SrcConstructor
   HTMLIFrameElement?: SrcConstructor
   location: { origin: string; href: string }
+  sessionStorage?: { getItem(key: string): string | null }
 }
 
 /** Options for {@link installRemoteChannel}. */
@@ -213,6 +214,33 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
   const sameOrigin = (url: URL): boolean => url.origin === window.location.origin
   const rewrite = (raw: string): string => rewriteRawUrl(raw, window.location.href, window.location.origin)
 
+  // The cookieless device credential (set by the /pair-app capture script):
+  // attaches as a header on gated fetches and as the device query on WS and
+  // EventSource handshakes, mirroring the boot patch exactly.
+  const device = (() => {
+    try {
+      return window.sessionStorage?.getItem(RULES.deviceKey) ?? null
+    } catch {
+      return null
+    }
+  })()
+  const attach = (init?: RequestInit): RequestInit | undefined => {
+    if (device === null) return init
+    const headers = init?.headers
+    if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+      try { headers.set(RULES.deviceHeader, device) } catch { /* ignore */ }
+      return init
+    }
+    if (typeof headers === 'object' && headers !== null) {
+      return { ...init, headers: { ...(headers as Record<string, string>), [RULES.deviceHeader]: device } } as RequestInit
+    }
+    return init
+  }
+  const withDeviceQuery = (url: URL): URL => {
+    if (device !== null) url.searchParams.set(RULES.deviceQuery, device)
+    return url
+  }
+
   const patchedFetch: typeof globalThis.fetch = (input, init) => {
     const url = new URL(
       typeof input === 'string' || input instanceof URL ? input.toString() : input.url,
@@ -224,7 +252,7 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
       const next: RequestInfo | URL = typeof input === 'string' || input instanceof URL
         ? rewritten.toString()
         : new Request(rewritten, input)
-      return Promise.resolve(originalFetch.call(window, next, init)).then(async (response) => {
+      return Promise.resolve(originalFetch.call(window, next, attach(init))).then(async (response) => {
         if (await isUnpairedDenied(response.clone())) options.onUnpaired?.()
         else options.onPaired?.()
         return response
@@ -240,7 +268,7 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
       if (wsOrigin !== '' && wsOrigin === window.location.origin && shouldRewriteWsPath(parsed.pathname)) {
         const rewritten = new URL(parsed)
         rewritten.pathname = rewritePath(parsed.pathname)
-        super(rewritten, protocols)
+        super(withDeviceQuery(rewritten), protocols)
         return
       }
       super(url, protocols)
@@ -262,7 +290,7 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
         if (sameOrigin(parsed) && shouldRewriteFetchPath(parsed.pathname)) {
           const rewritten = new URL(parsed)
           rewritten.pathname = rewritePath(parsed.pathname)
-          super(rewritten, eventSourceInitDict)
+          super(withDeviceQuery(rewritten), eventSourceInitDict)
           return
         }
         super(url, eventSourceInitDict)

package/src/client/settings-form.ts

@@ -8,8 +8,9 @@
  * card-store pattern.
  */
 
-import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsScope, SettingsScopeSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 
 /** The write one field's staged text performs when the card is saved. */
 export type FieldWrite =
@@ -23,9 +24,11 @@ export interface FieldSpec {
   /**
    * Whether the Host treats this field as a secret and redacts its value from
    * the read-back (role('secret') in the section schema). Redacted secrets are
-   * never compared against the draft on save; the field lands when the scope
-   * reports the write succeeded (its secret-set marker under the bridge), so
-   * a successful secret save is not misreported as failed.
+   * never compared against the draft on save: the Host strips them from every
+   * wire view layer, so the settled snapshot carries nothing to read back. A
+   * staged secret set is judged by the mutation settling; the rest of its
+   * batch, when one exists, is still judged by read-back, and the atomic
+   * mutation lands every write or none.
    */
   secret?: boolean
   /** Render a stored value as draft text; the empty string when the section carries none. */
@@ -53,8 +56,8 @@ export interface CardShell {
   available: boolean
   /**
    * Whether the namespace is actually served to this client. False when the
-   * Host deployment does not expose it (e.g. the official apiproxy settings
-   * allowlist omits third-party namespaces): the card renders an explanation
+   * Host deployment does not expose it (e.g. the owning plugin's settings
+   * domain is not mounted): the card renders an explanation
    * instead of its form, so a missing namespace never looks like a missing
    * plugin.
    */
@@ -101,13 +104,17 @@ interface StagedEdit {
 interface PlannedWrite {
   /** Field this entry writes. */
   field: string
-  /** The durable write this entry performs, described for a batched scope. */
+  /** The durable write this entry performs, inside the save's one atomic mutation. */
   op: BatchedWrite
-  /** Perform the write and report whether the Host holds the staged value afterwards. */
-  run: (() => Promise<boolean>) | undefined
+  /**
+   * Read the settled snapshot back and report whether the Host holds this
+   * write's effect. Undefined when the draft is not a value the field
+   * accepts: there is nothing to write, and the entry blocks the save.
+   */
+  judge: (() => boolean) | undefined
 }
 
-/** One durable write a batched settings scope performs. */
+/** One durable write inside the save's atomic scope mutation. */
 export interface BatchedWrite {
   /** Field this entry writes. */
   field: string
@@ -117,36 +124,6 @@ export interface BatchedWrite {
   value?: unknown
 }
 
-/** Per-field outcome of one batched scope write. */
-export interface BatchedFieldResult {
-  /** Field this entry writes. */
-  field: string
-  /** Whether the Host accepted this field's write (per the read-back view). */
-  landed: boolean
-}
-
-/**
- * Result of a batched scope write. The bridge scope posts every planned write
- * in one /mutate so the Host validate hook judges baseURL+model together; a
- * batched refusal fails the whole save rather than per-field.
- */
-export interface BatchResult {
-  /** Whether the whole mutate was accepted. */
-  ok: boolean
-  /** Per-field success, in the request order (always present when ok). */
-  fields: BatchedFieldResult[]
-  /** Host rejection code (mutate refused). */
-  code?: string
-  /** Host rejection message (mutate refused). */
-  message?: string
-}
-
-/** The optional batch surface the bridge scope adds over the SettingsScope contract. */
-interface BatchedSettingsScope {
-  /** Write every operation in one scope mutation, reporting per-field success. */
-  mutate: (writes: BatchedWrite[]) => Promise<BatchResult>
-}
-
 /** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
 export interface NumberConstraints {
   /** The accepted value must be a whole number. */
@@ -188,8 +165,8 @@ export function textField(field: string): FieldSpec {
 /**
  * A free-text field the Host treats as a secret and redacts from the read-back
  * (role('secret') in the section schema). The card still edits it like text,
- * but a save never compares the redacted value back and relies on the scope
- * reporting the write landed.
+ * but a save never compares the redacted value back: the staged set is judged
+ * by the mutation settling (see {@link FieldSpec.secret}).
  */
 export function secretField(field: string): FieldSpec {
   return { ...textField(field), secret: true }
@@ -277,7 +254,7 @@ export class CardForm<T> {
       exposed: snapshot.status === 'ready',
       writable: snapshot.writable,
       dirty: plan.length > 0,
-      invalid: plan.some(item => item.run === undefined),
+      invalid: plan.some(item => item.judge === undefined),
       saving: this.saving,
       failed: this.failed,
       ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
@@ -318,21 +295,25 @@ export class CardForm<T> {
   }
 
   /**
-   * Write every staged edit, then re-seed from what the Host accepted.
+   * Write every staged edit in one atomic scope mutation, then re-seed from
+   * what the Host accepted.
    *
-   * When the scope carries the optional batch surface (the dsh-web
-   * bridge scope), every planned write rides one mutation so cross-field
-   * validate hooks (baseURL+model) judge the batch as a unit instead of
-   * deadlocking on per-field writes. Otherwise the per-field loop runs.
-   * A field lands only when the Host reports it held the staged value; a
-   * landed field's draft is dropped, a failed one stays staged for the user.
-   * @returns settlement after every write and the read-back.
+   * The whole batch rides one mutate, so cross-field validate hooks
+   * (baseURL+model) judge it as a unit: the Host either applies every write
+   * or refuses the batch. The 0.1.2 scope contract never rejects a refused
+   * mutation — the scope recovers with a fresh Host view and resolves — so
+   * resolution alone proves nothing: the outcome is judged by reading the
+   * settled snapshot back, one planned write at a time, and one missed write
+   * fails the whole save. A scope that still rejects on refusal (the dsh-web
+   * bridge scope) reports through the same failure path with its rejection
+   * message. A save that did not land keeps its drafts, so the user can
+   * correct them instead of retyping.
+   * @returns settlement after the mutation and the read-back.
    */
   async save(): Promise<void> {
     const plan = this.plan()
-    const valid = plan.filter(item => item.run !== undefined)
+    const valid = plan.filter((item): item is PlannedWrite & { judge: () => boolean } => item.judge !== undefined)
     if (plan.length === 0 || this.saving || valid.length !== plan.length) return
-    const plannedWrites = valid.map(item => item.op)
     // Snapshot the staged entries this save writes, so an edit staged while it
     // is in flight (which replaces the same key) survives: only delete the key
     // when the entry is still the one this save started from.
@@ -342,36 +323,34 @@ export class CardForm<T> {
     this.failed = false
     this.failedReason = undefined
     this.publish()
-    const landed = new Set<string>()
-    const batch = this.batchedScope()
-    if (batch !== undefined) {
-      const result = await batch.mutate(plannedWrites)
-      if (result.ok) {
-        for (const field of result.fields) {
-          if (field.landed) landed.add(field.field)
-        }
-      } else {
-        this.failedReason = result.message
-      }
-    } else {
-      for (const item of valid) {
-        if (await item.run!()) landed.add(item.field)
-      }
+    // One atomic namespace mutation: the 0.1.2 scope contract takes ordered
+    // path operations, so the whole staged batch is validated, persisted, and
+    // recovered together — either every write lands or none does.
+    const ops: Array<{ op: 'set'; path: string[]; value: string | number | boolean } | { op: 'unset'; path: string[] }> = valid.map(item => item.op.op === 'set'
+      ? { op: 'set', path: [item.field], value: (item.op as { value: string | number | boolean }).value }
+      : { op: 'unset', path: [item.field] })
+    let failedReason: string | undefined
+    try {
+      await this.scope.mutate(ops)
+    } catch (error) {
+      failedReason = error instanceof Error ? error.message : String(error)
     }
+    // The 0.1.2 scope resolves even a refused mutation (it recovers with a
+    // fresh view instead of throwing), so resolution alone proves nothing:
+    // judge every planned write against the settled snapshot. The mutation is
+    // atomic, so one missed write fails the whole save and keeps the drafts.
+    const landed = failedReason === undefined && valid.every(item => item.judge())
     for (const [field, before] of pending) {
-      if (landed.has(field) && this.staged.get(field) === before) this.staged.delete(field)
+      if (landed && this.staged.get(field) === before) this.staged.delete(field)
     }
     this.saving = false
-    this.failed = landed.size !== pending.size
+    this.failed = !landed
+    // A read-back failure carries no server reason: the card surfaces its
+    // generic failure copy; a rejecting scope (the bridge) adds its message.
+    this.failedReason = failedReason
     this.publish()
   }
 
-  /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
-  private batchedScope(): BatchedSettingsScope | undefined {
-    const candidate = this.scope as unknown as BatchedSettingsScope | undefined
-    return typeof candidate?.mutate === 'function' ? candidate : undefined
-  }
-
   /**
    * Every staged edit a save would write. An entry whose draft is not a value
    * its field accepts carries no write: the form is still dirty, and the save
@@ -384,33 +363,40 @@ export class CardForm<T> {
     for (const [field, staged] of this.staged) {
       const spec = this.specOf(field)
       if (staged.clear) {
-        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
+        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
         continue
       }
       if (staged.text === spec.format(this.sectionValue(field))) continue
       const write = spec.parse(staged.text)
-      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, run: undefined })
-      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
-      else plan.push({ field, op: { field, op: 'set', value: write.value }, run: () => this.store(field, write.value) })
+      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, judge: undefined })
+      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
+      else plan.push({ field, op: { field, op: 'set', value: write.value }, judge: () => this.landedSet(field, write.value) })
     }
     return plan
   }
 
-  private async clear(field: string): Promise<boolean> {
-    await this.scope.unset(field)
-    return !this.stored(field)
-  }
-
-  private async store(field: string, value: unknown): Promise<boolean> {
-    await this.scope.set(field, value)
-    // A redacted secret never appears in the user layer read-back; judging it
-    // by value would misreport a successful secret save as failed. The bridge
-    // reports secret writes through its secret-set markers (batch path); on
-    // the per-field path the scope resolved, so the write is landed.
+  /**
+   * Read-back judgment for a planned set: the user layer must hold the
+   * intended value once the mutation has settled.
+   */
+  private landedSet(field: string, value: unknown): boolean {
+    // A redacted secret never appears in any wire view layer: the Host strips
+    // role('secret') fields and reports them through a sidecar the scope
+    // snapshot does not expose, so there is nothing to compare the draft
+    // against. Settling is the only signal the form has; the rest of the
+    // batch, when one exists, still carries the atomic verdict by read-back.
     if (this.specOf(field).secret) return true
     return this.userLayer()?.[field] === value
   }
 
+  /**
+   * Read-back judgment for a planned unset: the field must be gone from the
+   * user layer once the mutation has settled.
+   */
+  private landedUnset(field: string): boolean {
+    return !this.stored(field)
+  }
+
   private stage(field: string, edit: StagedEdit): void {
     this.staged.set(field, edit)
     this.failed = false

package/src/dsh-home.ts

@@ -39,4 +39,4 @@ export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: strin
 /** Resolve the DSH home directory from the live environment. */
 export function dshHome(): string {
   return resolveDshHome()
-}
+}

package/src/firewall.ts

@@ -0,0 +1,230 @@
+/**
+ * Host firewall management for the LAN bind toggle: while LAN access is on,
+ * keep one inbound allow rule for the bound port; when it turns off, remove
+ * the rule. Windows manages the Windows Defender Firewall rule via netsh;
+ * Linux uses the first available manager among firewalld / ufw / iptables.
+ * On every other platform (macOS included) the plugin reports the firewall
+ * as unmanaged: the port usually needs no rule there, and managing pf or the
+ * application firewall is out of scope for a distributable plugin.
+ *
+ * Ported from the dsh-LAN reference implementation (MIT), adapted to this
+ * package's structure and test seams.
+ */
+
+import { spawnSync } from 'node:child_process'
+
+/** Rule name shared by every backend so re-runs recreate the same rule. */
+export const FIREWALL_RULE_NAME = 'remote-web-ui (auto)'
+
+/** One command execution result (test seam replaces the runner). */
+export interface ToolResult {
+  ok: boolean
+  out: string
+  err: string
+  /** true when the binary could not be spawned at all (ENOENT et al). */
+  missing?: boolean
+}
+
+/** The command runner seam: spawnSync in production, a stub in tests. */
+export type CommandRunner = (cmd: string, args: readonly string[]) => ToolResult
+
+/** Production runner: spawn without a shell, capture text, 20s timeout. */
+export const spawnRunner: CommandRunner = (cmd, args) => {
+  const result = spawnSync(cmd, args, {
+    shell: false,
+    encoding: 'utf8',
+    windowsHide: process.platform === 'win32',
+    timeout: 20_000,
+  })
+  return {
+    ok: result.status === 0,
+    out: result.stdout ?? '',
+    err: result.stderr ?? '',
+    missing: result.error !== undefined,
+  }
+}
+
+/** A firewall backend manages one allow rule for a TCP port. */
+export interface FirewallBackend {
+  /** Short label surfaced in the settings card (netsh, firewalld, ...). */
+  readonly label: string
+  ruleExists(port: number): boolean
+  addRule(port: number): boolean
+  removeRule(port: number): boolean
+}
+
+function netshBackend(run: CommandRunner): FirewallBackend {
+  // `show rule name=` exits 0 even when nothing matches (the localized "no
+  // rules match" note), so exit-code-only probes always report the rule as
+  // present. The verbose listing echoes the full rule name — the one
+  // locale-independent field — and is matched literally instead.
+  const show = (): boolean => {
+    const result = run('netsh', ['advfirewall', 'firewall', 'show', 'rule', `name=${FIREWALL_RULE_NAME}`, 'verbose'])
+    return result.ok && result.out.includes(FIREWALL_RULE_NAME)
+  }
+  return {
+    label: 'netsh',
+    ruleExists: show,
+    addRule: (port) => run('netsh', [
+      'advfirewall', 'firewall', 'add', 'rule', `name=${FIREWALL_RULE_NAME}`,
+      'dir=in', 'action=allow', 'protocol=TCP', `localport=${String(port)}`, 'profile=private,domain',
+    ]).ok,
+    removeRule: () => {
+      if (!show()) return true
+      return run('netsh', ['advfirewall', 'firewall', 'delete', 'rule', `name=${FIREWALL_RULE_NAME}`]).ok
+    },
+  }
+}
+
+function firewalldBackend(run: CommandRunner): FirewallBackend {
+  return {
+    label: 'firewalld',
+    ruleExists: (port) => run('firewall-cmd', ['--permanent', '--query-port', `${String(port)}/tcp`]).ok,
+    addRule: (port) => {
+      const add = run('firewall-cmd', ['--permanent', '--add-port', `${String(port)}/tcp`])
+      const reload = run('firewall-cmd', ['--reload'])
+      return add.ok && reload.ok
+    },
+    removeRule: (port) => {
+      const del = run('firewall-cmd', ['--permanent', '--remove-port', `${String(port)}/tcp`])
+      const reload = run('firewall-cmd', ['--reload'])
+      return del.ok && reload.ok
+    },
+  }
+}
+
+function ufwBackend(run: CommandRunner): FirewallBackend {
+  return {
+    label: 'ufw',
+    ruleExists: (port) => {
+      const result = run('ufw', ['status'])
+      // Anchored so a superset port's row (1443/tcp) cannot satisfy the
+      // probe for a shorter one (443/tcp).
+      return result.ok && new RegExp(`(^|\\s)${String(port)}/tcp\\s+ALLOW`, 'i').test(result.out)
+    },
+    addRule: (port) => run('ufw', ['allow', `${String(port)}/tcp`]).ok,
+    removeRule: (port) => run('ufw', ['delete', 'allow', `${String(port)}/tcp`]).ok,
+  }
+}
+
+function iptablesBackend(run: CommandRunner): FirewallBackend {
+  const rule = (port: number): string[] => ['INPUT', '-p', 'tcp', '--dport', String(port), '-j', 'ACCEPT']
+  return {
+    label: 'iptables',
+    ruleExists: (port) => run('iptables', ['-C', ...rule(port)]).ok,
+    addRule: (port) => run('iptables', ['-A', ...rule(port)]).ok,
+    removeRule: (port) => run('iptables', ['-D', ...rule(port)]).ok,
+  }
+}
+
+function toolAvailable(run: CommandRunner, cmd: string): boolean {
+  try {
+    // A missing binary reports through the runner's missing flag (spawnSync
+    // sets result.error for ENOENT); any graceful answer counts as present.
+    return run(cmd, ['--version']).missing !== true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Detect the platform firewall manager. Returns undefined when the platform
+ * has no supported manager (macOS, unknown Linux without tools): the port
+ * then usually needs no rule and the UI reports "unmanaged".
+ */
+export function detectFirewallBackend(
+  platform: NodeJS.Platform,
+  run: CommandRunner = spawnRunner,
+): FirewallBackend | undefined {
+  if (platform === 'win32') return netshBackend(run)
+  if (platform !== 'linux') return undefined
+  if (toolAvailable(run, 'firewall-cmd')) {
+    // firewalld only counts when its daemon answers; an installed-but-idle
+    // firewall-cmd would otherwise claim management it cannot exercise.
+    if (run('firewall-cmd', ['--state']).ok) return firewalldBackend(run)
+  }
+  if (toolAvailable(run, 'ufw')) return ufwBackend(run)
+  if (toolAvailable(run, 'iptables')) return iptablesBackend(run)
+  return undefined
+}
+
+let cachedBackend: { platform: NodeJS.Platform; backend: FirewallBackend | undefined } | undefined
+
+/** Cached detection for the running platform (per process). */
+export function firewallBackend(): FirewallBackend | undefined {
+  const platform = process.platform
+  if (cachedBackend === undefined || cachedBackend.platform !== platform) {
+    cachedBackend = { platform, backend: detectFirewallBackend(platform) }
+  }
+  return cachedBackend.backend
+}
+
+/** Firewall state reported to the settings card. */
+export interface FirewallSummary {
+  /** true when the rule state matches the LAN toggle (or nothing to manage). */
+  ok: boolean
+  /** false when no supported firewall manager exists on this platform. */
+  managed: boolean
+  /** Backend label or an explanation for unmanaged platforms. */
+  note?: string
+}
+
+/**
+ * Delete-and-add: recreating the rule is idempotent and locale-proof (netsh
+ * output is localized, so parsing the live rule's port is fragile; the Linux
+ * backends follow the same recreate pattern).
+ */
+export function ensureFirewallRule(port: number): boolean {
+  invalidateFirewallSummary()
+  const backend = firewallBackend()
+  if (backend === undefined) return true
+  backend.removeRule(port)
+  return backend.addRule(port)
+}
+
+export function removeFirewallRule(port: number): boolean {
+  invalidateFirewallSummary()
+  const backend = firewallBackend()
+  if (backend === undefined) return true
+  return backend.removeRule(port)
+}
+
+/**
+ * Human-readable firewall state for the status endpoint. A missing backend
+ * means the platform has nothing to manage; detection stays at the call site
+ * so an explicit undefined cannot silently re-probe the real OS mid-test.
+ */
+export function computeFirewallSummary(
+  port: number,
+  lanEnabled: boolean,
+  backend: FirewallBackend | undefined,
+): FirewallSummary {
+  if (backend === undefined) return { ok: true, managed: false }
+  return { ok: lanEnabled ? backend.ruleExists(port) : !backend.ruleExists(port), managed: true, note: backend.label }
+}
+
+/** How long a firewallSummary answer is reused before the backend is probed again. */
+export const FIREWALL_SUMMARY_TTL_MS = 30_000
+
+let summaryCache: { key: string; at: number; value: FirewallSummary } | undefined
+
+/** Forget the cached summary (rule mutations call this). */
+export function invalidateFirewallSummary(): void {
+  summaryCache = undefined
+}
+
+/**
+ * The settings card polls this every ten seconds; the probes are blocking
+ * spawnSync subprocesses on managed platforms, so short-TTL memoization
+ * keeps one poll from freezing the host event loop per request.
+ */
+export function firewallSummary(port: number, lanEnabled: boolean): FirewallSummary {
+  const key = `${String(port)}|${lanEnabled ? '1' : '0'}`
+  const now = Date.now()
+  if (summaryCache !== undefined && summaryCache.key === key && now - summaryCache.at < FIREWALL_SUMMARY_TTL_MS) {
+    return summaryCache.value
+  }
+  const value = computeFirewallSummary(port, lanEnabled, firewallBackend())
+  summaryCache = { key, at: now, value }
+  return value
+}