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

package/lib/types/index.js

@@ -10,20 +10,20 @@
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { setInterval as nodeSetInterval, setTimeout as nodeSetTimeout } from 'node:timers';
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
 import z from 'schemastery';
 import { DEFAULT_IDLE_EXPIRE_MS, PairingService } from "./pairing.js";
 import { dshHome } from "./dsh-home.js";
 import { isPairedDeviceRequest, makeGateListener } from "./gate.js";
 import { RemoteWebUiPairing } from "./pairing-access.js";
 import { isTrustedApiRequest, makeRoutes } from "./routes.js";
-import { makeMobileRoutes } from "./mobile-routes.js";
-import { makeMobileApiRoutes } from "./mobile-api.js";
-import { PendingTracker } from "./mobile-pending.js";
-import { makePairedModelCatalogRoutes } from "./paired-model-catalog.js";
 import { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from "./remote-api.js";
+import { startRemotePresencePet } from "./remote-presence-pet.js";
 import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from "./posture.js";
 import { lanIPv4Addresses } from "./lan.js";
+import { ensureFirewallRule, firewallSummary, removeFirewallRule } from "./firewall.js";
+import { lanBindState, writeLanBind } from "./lan-bind.js";
+import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf } from "./lan-bind-plan.js";
+import { createInnerAuth } from "./inner-auth.js";
 import { TunnelManager } from "./tunnel.js";
 import { checkUpdates, fetchGitHubReleaseNotes, fetchLatestVersion, RELEASE_NOTES_CACHE_TTL_MS, resolveAnchorManifest, resolveUpdateTarget, runUpdateVerified, } from "./update.js";
 import { makeUpdateRoutes } from "./update-routes.js";
@@ -33,13 +33,13 @@ import { UUID_POLYFILL_SCRIPT } from "./uuid-polyfill.js";
 /** Stable cordis plugin name. */
 export const name = 'remote-web-ui';
 /** Services required before the pairing surfaces can mount. */
-export const inject = ['webServer', 'apiProxy', 'commands', 'agents'];
+export const inject = ['webServer', 'typertGateway', 'connection'];
 /**
  * Settings namespace of the remote-control capability — the section the web
  * settings surface edits. Spelled here rather than imported: the browser
  * half spells the same value and must not depend on a Host package.
  */
-export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = settingsNamespace('remote-web-ui');
+export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = 'remote-web-ui';
 export const Config = z.object({
     tokenTtlMs: z.number().step(1).min(60_000).default(10 * 60_000),
     offlineAfterMs: z.number().step(1).min(5_000).default(25_000),
@@ -50,7 +50,8 @@ export const Config = z.object({
     publicBaseUrl: z.string(),
     devicesFile: z.string(),
     autoTunnel: z.boolean().default(false),
-    mobileEnterToSend: z.boolean().default(true),
+    lanBind: z.boolean(),
+    profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
     enabled: z.boolean().default(true),
 });
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
@@ -86,7 +87,8 @@ const DEFAULTS = {
     publicBaseUrl: undefined,
     devicesFile: defaultDevicesFile(),
     autoTunnel: false,
-    mobileEnterToSend: true,
+    lanBind: undefined,
+    profile: process.env.DSH_PROFILE ?? 'web',
     enabled: true,
 };
 /**
@@ -106,12 +108,13 @@ function applyImpl(ctx, config) {
         publicBaseUrl: config?.publicBaseUrl,
         devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
         autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
-        mobileEnterToSend: config?.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
+        lanBind: config?.lanBind,
+        profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
         enabled: config?.enabled ?? DEFAULTS.enabled,
     };
     // The live source the pairing service and the gate read: the settings
     // section once the web settings surface is served, the composition entry
-    // otherwise (installSettingsSection swaps it when the namespace registers).
+    // otherwise (installSection swaps it when the namespace registers).
     let current = () => config ?? {};
     const resolve = () => {
         const value = current();
@@ -125,14 +128,15 @@ function applyImpl(ctx, config) {
             publicBaseUrl: value.publicBaseUrl,
             devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
             autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
-            mobileEnterToSend: value.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
+            lanBind: value.lanBind,
+            profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
             enabled: value.enabled ?? DEFAULTS.enabled,
         };
     };
     const service = new PairingService(pairingConfigOf(resolved));
     // ── auto tunnel ─────────────────────────────────────────────────────────
     // The minted public URL becomes the QR base (and the pairing fence's
-    // trusted host). Phone /api traffic rides the plugin's own /m/api channel,
+    // trusted host). Phone /api traffic rides the plugin's own /remote channel,
     // which is NOT subject to the connection trust fence — so no fence
     // mutation is needed here (a distributable plugin must not change the
     // harness's connection plugin).
@@ -165,11 +169,18 @@ function applyImpl(ctx, config) {
     // sampling stance. The QR can only advertise addresses the fence accepts;
     // every interface gets its own base URL so a multi-homed machine can pick
     // the network the phone can actually reach.
-    const lanBases = ctx.webServer.host === '0.0.0.0'
-        ? lanIPv4Addresses().map(address => ({ address, base: `http://${address}:${String(ctx.webServer.port)}` }))
-        : [];
-    service.setLanBases(lanBases);
-    const lanAddresses = lanBases.map(entry => entry.address);
+    // A recompose pass can hand the plugin a webServer whose facts have not
+    // settled yet (host unset, port undefined); deriving LAN bases from that
+    // would advertise :undefined links or clear a working set, so the bases
+    // only update when both facts are readable.
+    const bindKnown = (ctx.webServer.host === '0.0.0.0' || ctx.webServer.host === '127.0.0.1')
+        && Number.isFinite(ctx.webServer.port);
+    if (bindKnown) {
+        const lanBases = ctx.webServer.host === '0.0.0.0'
+            ? lanIPv4Addresses().map(address => ({ address, base: `http://${address}:${String(ctx.webServer.port)}` }))
+            : [];
+        service.setLanBases(lanBases);
+    }
     // Push a committed settings section into the service and gate. The service
     // config object is read per operation (token mint, touch, sweep), and the
     // gate re-reads its fence flag per request, so a live edit takes effect
@@ -179,12 +190,6 @@ function applyImpl(ctx, config) {
     // (now vetoing every non-loopback request) instead of opening the fence.
     let disposeRoutes;
     let disposeSweep;
-    // The phone's data channel: pairing routes + the /m page + the /m/api
-    // proxy (which needs the host ApiProxy service; the plugin injects it).
-    const apiProxy = ctx.get('apiProxy');
-    if (apiProxy === undefined) {
-        console.warn('remote-web-ui: apiProxy service unavailable — the mobile data channel is disabled');
-    }
     // ── remote update ────────────────────────────────────────────────────────
     // The dsh-web self-update surface: probe the npm registry for family
     // releases and run `pnpm update --latest` in the owning profile. Resolutions
@@ -262,31 +267,98 @@ function applyImpl(ctx, config) {
             });
         },
     });
+    // LAN-bind facts for the settings card, re-read per request so a hot
+    // rebind (the patch watcher recomposes the process) and a fresh toggle
+    // round are both reflected without a restart.
+    let lastKnownPort;
+    let lastFirewallApplied;
+    const lanBindStatus = () => {
+        const resolvedNow = resolve();
+        let state;
+        try {
+            state = lanBindState(resolvedNow.profile);
+        }
+        catch {
+            // An unsafe profile value must not take the whole status endpoint down.
+            state = { blockPresent: false };
+        }
+        const lanOn = state.host === '0.0.0.0';
+        const port = Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : lastKnownPort;
+        if (Number.isFinite(ctx.webServer.port))
+            lastKnownPort = ctx.webServer.port;
+        const startup = ctx.get('webStartup');
+        const desiredHost = resolvedNow.lanBind === undefined
+            ? undefined
+            : desiredBindHost(resolvedNow.lanBind === true, startup?.host);
+        return {
+            profile: resolvedNow.profile,
+            setting: resolvedNow.lanBind ?? null,
+            blockHost: state.host ?? null,
+            bindHost: ctx.webServer.host,
+            port,
+            lanUrls: ctx.webServer.host === '0.0.0.0' && port !== undefined
+                ? lanIPv4Addresses().map(address => `http://${address}:${String(port)}`)
+                : [],
+            firewall: port !== undefined ? firewallSummary(port, lanOn) : { ok: true, managed: false },
+            platform: process.platform,
+            // The running bind does not follow the block on every deployment (the
+            // live patch watcher is profile-shape dependent): flag the divergence
+            // so the card can ask for a restart instead of looking broken. The
+            // comparison uses the effective desired host (a CLI --host wins over
+            // the toggle), not the raw toggle.
+            pendingRestart: pendingRestartOf(resolvedNow.lanBind, desiredHost, ctx.webServer.host),
+        };
+    };
+    // The process's inner browser credential: the proxied /api re-issues to
+    // 127.0.0.1, where the connection route enforces the harness browser-auth
+    // cookie (authority-bound; no loopback exemption on this cohort), so a
+    // device's own cookie can never satisfy the inner check. The plugin
+    // redeems its own launch token once and attaches the cookie to inner
+    // requests; the credential is only ever exercised behind the pairing gate
+    // in remote-api.ts.
+    const innerAuth = createInnerAuth(() => {
+        if (!Number.isFinite(ctx.webServer.port))
+            return undefined;
+        try {
+            return ctx.connection.authenticatedUrl?.(`http://127.0.0.1:${String(ctx.webServer.port)}/`);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // The official index document for the /pair-app landing, fetched from the
+    // inner loopback with the process credential and cached briefly (the shell
+    // is static; skins/injections settle right after boot).
+    const APP_SHELL_TTL_MS = 30_000;
+    let appShellCache;
+    const fetchAppShell = async () => {
+        if (!Number.isFinite(ctx.webServer.port))
+            return undefined;
+        if (appShellCache !== undefined && Date.now() - appShellCache.at < APP_SHELL_TTL_MS)
+            return appShellCache.html;
+        const cookie = await innerAuth.ready();
+        try {
+            const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, {
+                headers: cookie !== undefined ? { cookie } : undefined,
+            });
+            if (!response.ok)
+                return undefined;
+            const html = await response.text();
+            appShellCache = { at: Date.now(), html };
+            return html;
+        }
+        catch {
+            return undefined;
+        }
+    };
     const routes = [
-        ...makeRoutes({ service, lanAddresses, requirePairingForLan: () => resolve().requirePairingForLan }),
-        ...makeMobileRoutes(),
-        ...(apiProxy !== undefined
-            ? makeMobileApiRoutes({
-                service,
-                apiProxy,
-                pendingTracker: new PendingTracker(),
-                mobileEnterToSend: () => resolve().mobileEnterToSend,
-                commandDispatcher: ctx.commands !== undefined && ctx.agents !== undefined
-                    ? {
-                        async execute(sessionId, line, signal) {
-                            const agent = ctx.agents.get(sessionId);
-                            if (agent === undefined)
-                                return { error: 'session-not-found' };
-                            const execution = await ctx.commands.execute(agent, line, [], signal);
-                            if (execution === undefined)
-                                return { error: 'unknown-command' };
-                            return { ok: true, result: execution.result };
-                        },
-                    }
-                    : undefined,
-            })
-            : []),
-        ...(apiProxy !== undefined ? makePairedModelCatalogRoutes({ service, apiProxy, lanAddresses }) : []),
+        ...makeRoutes({
+            service,
+            lanAddresses: service.lanAddresses,
+            requirePairingForLan: () => resolve().requirePairingForLan,
+            lanBindStatus,
+            indexDocument: fetchAppShell,
+        }),
         // The remote desktop channel: policy-gated `/remote` prefix that
         // re-issues fenced paths to loopback (see remote-api.ts). The live
         // requirePairingForLan is re-read per request, same as the gate listener
@@ -296,6 +368,7 @@ function applyImpl(ctx, config) {
             service,
             port: ctx.webServer.port,
             requirePairingForLan: () => resolve().requirePairingForLan,
+            auth: innerAuth,
         }),
         ...updateRoutes,
     ];
@@ -303,6 +376,7 @@ function applyImpl(ctx, config) {
         service,
         port: ctx.webServer.port,
         requirePairingForLan: () => resolve().requirePairingForLan,
+        auth: innerAuth,
     });
     const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled);
     ctx.effect(() => ctx.on('api/gate', gate), 'remote-web-ui: api gate');
@@ -350,20 +424,92 @@ function applyImpl(ctx, config) {
     const initialPostureTimer = nodeSetTimeout(() => { runPostureProbe(); }, 5_000);
     initialPostureTimer.unref();
     ctx.effect(() => () => { clearTimeout(initialPostureTimer); }, 'remote-web-ui: posture probe boot');
-    // Sibling plugins (aionui-panel, …) look this up by name. Absent when this
+    // Sibling plugins (dsh-better-sidebar, …) look this up by name. Absent when this
     // plugin is not installed; stop() / enabled=false still refuse cookies.
     new RemoteWebUiPairing(ctx, (request) => {
         if (!resolve().enabled)
             return false;
         return isPairedDeviceRequest(service, request);
     });
-    if (lanAddresses.length > 0) {
-        const urls = lanAddresses.map(ip => `http://${ip}:${String(ctx.webServer.port)}/m/`).join(' , ');
-        console.log(`remote-web-ui: mobile UI reachable on LAN at ${urls}`);
+    // Remote-presence to pet-visibility link: while a paired device is online
+    // (an active phone mirror), hide the host-global pet through the pet's OWN
+    // hide switch; when the last device has been offline for a grace window,
+    // show it again (user design; the pet plugin is optional, so the seam is
+    // resolved per transition and every failure degrades to a no-op).
+    const presencePet = startRemotePresencePet({
+        onState: listener => service.onState(listener),
+        pet: () => {
+            try {
+                return ctx.get('pet');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    });
+    ctx.effect(() => presencePet, 'remote-web-ui: remote-presence pet visibility');
+    if (service.lanAddresses.length > 0) {
+        const urls = service.lanAddresses.map(ip => `http://${ip}:${String(ctx.webServer.port)}`).join(' , ');
+        console.log(`remote-web-ui: the paired Web GUI is reachable on LAN at ${urls}`);
+    }
+    // Cohort honesty (see the README security model): the pairing gate covers
+    // the plugin's own /remote channel; direct /api from LAN origins is
+    // governed by the harness fence + browser-auth cookie, and this cohort's
+    // api/gate seam has no emitter — so stop()/revoke() cannot invalidate a
+    // browser credential a device has already redeemed.
+    if (ctx.webServer.host === '0.0.0.0') {
+        console.warn('remote-web-ui: LAN-exposed bind — pairing gates the /remote channel; direct /api stays under the harness fence + browser auth (stop() does not revoke an already-redeemed browser credential)');
     }
     const sync = () => {
         const value = resolve();
         service.config = pairingConfigOf(value);
+        // LAN bind toggle: only write the managed patch block once the user has
+        // flipped it (undefined = untouched, never write). Desired host/port come
+        // from the CLI flags when given (flags win), else from the toggle and
+        // the currently bound port. The block takes effect on the next start, so
+        // the re-assert at every boot keeps it in sync with both the toggle and
+        // the flags.
+        if (value.lanBind !== undefined) {
+            const startup = ctx.get('webStartup');
+            const desiredHost = desiredBindHost(value.lanBind === true, startup?.host);
+            const desiredPort = desiredBindPort(startup?.port, Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : undefined);
+            if (desiredPort === undefined) {
+                console.error('remote-web-ui: cannot assert the lan-bind block — the web server port is not known yet');
+            }
+            else {
+                try {
+                    const current = lanBindState(value.profile);
+                    if (current.host !== desiredHost || current.port !== desiredPort) {
+                        writeLanBind(desiredHost, desiredPort, value.profile);
+                        console.log(`remote-web-ui: lan-bind block written for profile ${value.profile} (${desiredHost}:${String(desiredPort)}); it takes effect when the profile next applies (the card reports pendingRestart until the running bind follows)`);
+                    }
+                }
+                catch (error) {
+                    console.error(`remote-web-ui: failed to write the lan-bind block: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Keep the firewall rule aligned with the toggle (managed platforms
+            // only; see firewall.ts). The probes and rule rewrites are blocking
+            // subprocesses, so they run only when the desired state actually moved
+            // — not on every unrelated settings save. The port is the live bind
+            // port; without it there is nothing to align yet.
+            const livePort = Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : undefined;
+            if (livePort === undefined) {
+                console.error('remote-web-ui: cannot align the host firewall rule — the web server port is not known yet');
+            }
+            else {
+                const nextFirewall = { enabled: value.lanBind === true, port: livePort };
+                if (firewallActionNeeded(lastFirewallApplied, nextFirewall)) {
+                    const ruleOk = nextFirewall.enabled ? ensureFirewallRule(nextFirewall.port) : removeFirewallRule(nextFirewall.port);
+                    if (ruleOk) {
+                        lastFirewallApplied = nextFirewall;
+                    }
+                    else {
+                        console.error('remote-web-ui: the host firewall rule could not be updated (admin rights required on managed platforms)');
+                    }
+                }
+            }
+        }
         // The auto tunnel owns the public base while enabled: the minted URL
         // lands in the service through the tunnel's phase listener. The manual
         // publicBaseUrl applies only when the auto tunnel is off.
@@ -437,12 +583,14 @@ function applyImpl(ctx, config) {
             return;
         table.push({ kind: 'script', placement: 'head', text: REMOTE_CHANNEL_BOOT_SCRIPT });
     }), 'remote-web-ui: remote channel boot patch');
-    installSettingsSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
-        setSource: (source) => {
-            current = source;
-            sync();
-        },
-        onChange: sync,
+    ctx.inject(['settings'], (settingsCtx) => {
+        settingsCtx.settings.installSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
+            setSource: (source) => {
+                current = source;
+                sync();
+            },
+            onChange: sync,
+        });
     });
     sync();
 }

package/lib/types/inner-auth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The inner browser credential for the remote desktop channel. The proxied
+ * /api re-issues requests to 127.0.0.1, where the connection plugin's route
+ * enforces the harness browser-auth cookie — an authority-bound signed cookie
+ * with no loopback exemption on this cohort line, so a cookie minted for the
+ * device's own authority can never satisfy the inner check. The process
+ * therefore redeems its own launch token (the same one-time exchange every
+ * paired device's first navigation performs) and attaches the resulting
+ * cookie to inner requests. The credential is only ever exercised behind the
+ * pairing gate: while requirePairingForLan is on, every proxied call already
+ * carried a live paired-device cookie before this module is consulted.
+ */
+/** Browser-auth credential the proxy attaches to loopback-bound requests. */
+export interface InnerAuth {
+    /**
+     * Resolve the `name=value` cookie pair for inner requests, or undefined
+     * when the launch token is unavailable (the proxy then sends without a
+     * credential and the inner route answers 401, exactly as before).
+     */
+    ready(): Promise<string | undefined>;
+    /** Drop the cached credential; the next ready() re-redeems. */
+    invalidate(): void;
+}
+/**
+ * Build the inner-auth handle.
+ * @param launchUrl - the launch-token URL for the inner loopback authority
+ *   (the connection service's authenticatedUrl of `http://127.0.0.1:<port>/`),
+ *   or undefined when the connection service or port is unavailable.
+ * @param fetchImpl - injectable fetch (tests).
+ */
+export declare function createInnerAuth(launchUrl: () => string | undefined, fetchImpl?: typeof fetch): InnerAuth;
+//# sourceMappingURL=inner-auth.d.ts.map

package/lib/types/inner-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inner-auth.d.ts","sourceRoot":"","sources":["../../src/inner-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACpC,+DAA+D;IAC/D,UAAU,IAAI,IAAI,CAAA;CACnB;AAKD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,MAAM,GAAG,SAAS,EACnC,SAAS,GAAE,OAAO,KAAa,GAC9B,SAAS,CA8CX"}

package/lib/types/inner-auth.js

@@ -0,0 +1,72 @@
+/**
+ * The inner browser credential for the remote desktop channel. The proxied
+ * /api re-issues requests to 127.0.0.1, where the connection plugin's route
+ * enforces the harness browser-auth cookie — an authority-bound signed cookie
+ * with no loopback exemption on this cohort line, so a cookie minted for the
+ * device's own authority can never satisfy the inner check. The process
+ * therefore redeems its own launch token (the same one-time exchange every
+ * paired device's first navigation performs) and attaches the resulting
+ * cookie to inner requests. The credential is only ever exercised behind the
+ * pairing gate: while requirePairingForLan is on, every proxied call already
+ * carried a live paired-device cookie before this module is consulted.
+ */
+/** The harness browser-auth cookie name prefix (see dsh-client-connection). */
+const BROWSER_AUTH_COOKIE_PREFIX = 'dsh-auth-';
+/**
+ * Build the inner-auth handle.
+ * @param launchUrl - the launch-token URL for the inner loopback authority
+ *   (the connection service's authenticatedUrl of `http://127.0.0.1:<port>/`),
+ *   or undefined when the connection service or port is unavailable.
+ * @param fetchImpl - injectable fetch (tests).
+ */
+export function createInnerAuth(launchUrl, fetchImpl = fetch) {
+    let cached;
+    let inflight;
+    const redeem = async () => {
+        const url = launchUrl();
+        if (url === undefined)
+            return undefined;
+        try {
+            // redirect: 'manual' keeps the 303's set-cookie readable instead of
+            // following it; the exchange itself is a plain GET with the token in
+            // the query, exactly what a first browser visit performs.
+            const response = await fetchImpl(url, { redirect: 'manual' });
+            const raw = response.headers.get('set-cookie');
+            if (raw === null)
+                return undefined;
+            // Generated cookie values are base64url and never contain commas, so a
+            // comma split followed by a prefix match finds the browser-auth entry
+            // even when the exchange sets several cookies.
+            const entry = raw
+                .split(',')
+                .map((part) => part.trim())
+                .find((part) => part.startsWith(BROWSER_AUTH_COOKIE_PREFIX));
+            if (entry === undefined)
+                return undefined;
+            const pair = entry.split(';')[0]?.trim();
+            return pair !== undefined && pair.includes('=') ? pair : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        ready() {
+            if (cached !== undefined)
+                return Promise.resolve(cached);
+            inflight ??= redeem().then((value) => {
+                if (value !== undefined)
+                    cached = value;
+                inflight = undefined;
+                return value;
+            }, () => {
+                inflight = undefined;
+                return undefined;
+            });
+            return inflight;
+        },
+        invalidate() {
+            cached = undefined;
+        },
+    };
+}

package/lib/types/lan-bind-plan.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure decision helpers shared by the lan-bind sync path (index.ts) and the
+ * status path (lanBindStatus). Extracted so the flags-win precedence, the
+ * pending-restart divergence check, and the firewall re-apply gate have one
+ * implementation and direct unit coverage.
+ */
+/** The two bind hosts the managed block pins. */
+export type LanBindPlanHost = '0.0.0.0' | '127.0.0.1';
+/** webStartup facts the CLI hands the process (absent unless a flag was passed). */
+export interface StartupFacts {
+    host?: string;
+    port?: number;
+}
+/**
+ * The bind host the managed block should pin: an explicit CLI --host wins,
+ * otherwise the toggle decides. CLI hosts outside the two managed literals
+ * (a pinned specific IP) are not a state the toggle manages — the toggle
+ * decides, and the card surfaces the divergence honestly.
+ * @param lanBind - the toggle value.
+ * @param startupHost - the CLI-provided bind host, when given.
+ * @returns the desired bind host literal.
+ */
+export declare function desiredBindHost(lanBind: boolean, startupHost: string | undefined): LanBindPlanHost;
+/**
+ * The port the managed block should pin: the CLI port when given, else the
+ * currently bound port. Undefined when neither is readable yet (the caller
+ * skips the write and reports why).
+ * @param startupPort - the CLI-provided port, when given.
+ * @param livePort - the currently bound port, when finite.
+ */
+export declare function desiredBindPort(startupPort: number | undefined, livePort: number | undefined): number | undefined;
+/**
+ * Whether the running bind has not caught up with what the toggle (plus a
+ * possibly overriding CLI host) will pin. Compared against the effective
+ * desired host — not the raw toggle — so a flag-managed bind is not reported
+ * as pending forever.
+ * @param lanBind - the toggle value (undefined = untouched, never pending).
+ * @param desiredHost - the effective desired host, or undefined when untouched.
+ * @param liveHost - the currently bound host.
+ */
+export declare function pendingRestartOf(lanBind: boolean | undefined, desiredHost: LanBindPlanHost | undefined, liveHost: string | undefined): boolean;
+/** The last firewall state this process applied. */
+export interface AppliedFirewallState {
+    enabled: boolean;
+    port: number;
+}
+/**
+ * Whether the firewall rule must be (re)applied: only when the toggle or the
+ * bound port moved since the last application. Keeps unrelated settings
+ * saves from spawning netsh/firewall-cmd delete+add churn.
+ * @param previous - the state applied earlier by this process, if any.
+ * @param next - the state the settings now ask for, if derivable.
+ */
+export declare function firewallActionNeeded(previous: AppliedFirewallState | undefined, next: AppliedFirewallState | undefined): boolean;
+//# sourceMappingURL=lan-bind-plan.d.ts.map

package/lib/types/lan-bind-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan-bind-plan.d.ts","sourceRoot":"","sources":["../../src/lan-bind-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,CAAA;AAErD,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAGlG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjH;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,WAAW,EAAE,eAAe,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAGT;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,EAAE,oBAAoB,GAAG,SAAS,GACrC,OAAO,CAIT"}

package/lib/types/lan-bind-plan.js

@@ -0,0 +1,60 @@
+/**
+ * Pure decision helpers shared by the lan-bind sync path (index.ts) and the
+ * status path (lanBindStatus). Extracted so the flags-win precedence, the
+ * pending-restart divergence check, and the firewall re-apply gate have one
+ * implementation and direct unit coverage.
+ */
+/**
+ * The bind host the managed block should pin: an explicit CLI --host wins,
+ * otherwise the toggle decides. CLI hosts outside the two managed literals
+ * (a pinned specific IP) are not a state the toggle manages — the toggle
+ * decides, and the card surfaces the divergence honestly.
+ * @param lanBind - the toggle value.
+ * @param startupHost - the CLI-provided bind host, when given.
+ * @returns the desired bind host literal.
+ */
+export function desiredBindHost(lanBind, startupHost) {
+    if (startupHost === '0.0.0.0' || startupHost === '127.0.0.1')
+        return startupHost;
+    return lanBind ? '0.0.0.0' : '127.0.0.1';
+}
+/**
+ * The port the managed block should pin: the CLI port when given, else the
+ * currently bound port. Undefined when neither is readable yet (the caller
+ * skips the write and reports why).
+ * @param startupPort - the CLI-provided port, when given.
+ * @param livePort - the currently bound port, when finite.
+ */
+export function desiredBindPort(startupPort, livePort) {
+    if (typeof startupPort === 'number' && Number.isFinite(startupPort))
+        return startupPort;
+    return typeof livePort === 'number' && Number.isFinite(livePort) ? livePort : undefined;
+}
+/**
+ * Whether the running bind has not caught up with what the toggle (plus a
+ * possibly overriding CLI host) will pin. Compared against the effective
+ * desired host — not the raw toggle — so a flag-managed bind is not reported
+ * as pending forever.
+ * @param lanBind - the toggle value (undefined = untouched, never pending).
+ * @param desiredHost - the effective desired host, or undefined when untouched.
+ * @param liveHost - the currently bound host.
+ */
+export function pendingRestartOf(lanBind, desiredHost, liveHost) {
+    if (lanBind === undefined || desiredHost === undefined)
+        return false;
+    return liveHost !== desiredHost;
+}
+/**
+ * Whether the firewall rule must be (re)applied: only when the toggle or the
+ * bound port moved since the last application. Keeps unrelated settings
+ * saves from spawning netsh/firewall-cmd delete+add churn.
+ * @param previous - the state applied earlier by this process, if any.
+ * @param next - the state the settings now ask for, if derivable.
+ */
+export function firewallActionNeeded(previous, next) {
+    if (next === undefined)
+        return false;
+    if (previous === undefined)
+        return true;
+    return previous.enabled !== next.enabled || previous.port !== next.port;
+}