@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/lib/types/console-output.js

@@ -0,0 +1,89 @@
+// Generated by scripts/sync-shared.mjs from shared/host/console-output.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Console-output capture shared by the family's Host halves.
+ *
+ * A child process's stdout/stderr are raw bytes, and on Windows a console
+ * program writes the OEM code page (CP936/GBK on a zh-CN system), not UTF-8.
+ * Decoding each chunk on its own corrupts the text twice over: the
+ * encoding is guessed wrong, and a multi-byte character split across two reads
+ * decodes into two replacement characters. This capture accumulates raw bytes
+ * under a byte budget and decodes exactly once, at read time.
+ */
+/** Count the U+FFFD replacement characters one candidate decode produced. */
+function replacementCount(text) {
+    let count = 0;
+    for (const character of text) {
+        if (character === '\uFFFD')
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Decode one console byte buffer. Strict UTF-8 wins whenever it is valid;
+ * otherwise the bytes are not UTF-8 at all and the console wrote its own code
+ * page, so the candidate that loses the least text is taken.
+ * @param bytes - the captured bytes.
+ * @returns the decoded text.
+ */
+export function decodeConsoleBytes(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        // Not valid UTF-8. Prefer whichever candidate leaves the fewest
+        // replacement characters so real UTF-8 text carrying one bad byte is not
+        // rewritten wholesale as GBK gibberish; without the legacy code page
+        // (small-ICU builds) the lenient UTF-8 pass is all that is left.
+        let best;
+        let bestLoss = Number.POSITIVE_INFINITY;
+        for (const label of ['gbk', 'utf-8']) {
+            let text;
+            try {
+                text = new TextDecoder(label).decode(bytes);
+            }
+            catch {
+                continue;
+            }
+            const loss = replacementCount(text);
+            if (loss < bestLoss) {
+                best = text;
+                bestLoss = loss;
+            }
+        }
+        /* v8 ignore next 3 -- reachable only without the legacy code page AND without the lenient pass */
+        if (best === undefined)
+            return Buffer.from(bytes).toString('utf8');
+        return best;
+    }
+}
+/**
+ * Create a capture bounded to a byte budget. Overflow drops from the FRONT
+ * (the tail is what carries a failure reason), and the cut never lands inside
+ * a character: leading UTF-8 continuation bytes are dropped with it, and a
+ * legacy code page's dangling lead byte — indistinguishable from a real byte
+ * without knowing the encoding until the whole buffer is decoded — is removed
+ * with the one replacement character it produced, so an over-long stream still
+ * reads cleanly at the seam.
+ * @param maxBytes - maximum retained bytes.
+ * @returns the capture.
+ */
+export function createOutputCapture(maxBytes) {
+    let buffer = Buffer.alloc(0);
+    let trimmed = false;
+    return {
+        push(chunk) {
+            buffer = buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([buffer, Buffer.from(chunk)]);
+            if (buffer.length <= maxBytes)
+                return;
+            let start = buffer.length - maxBytes;
+            while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+                start += 1;
+            buffer = Buffer.from(buffer.subarray(start));
+            trimmed = true;
+        },
+        read() {
+            const text = decodeConsoleBytes(buffer);
+            return trimmed && text.startsWith('\uFFFD') ? text.slice(1) : text;
+        },
+    };
+}

package/lib/types/http.d.ts

@@ -1,7 +1,9 @@
 /**
  * Shared JSON body/response helpers for the host route families: one strict
  * bounded body reader, one lenient bounded body reader, one JSON object
- * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
+ * were copy-pasted across the
  * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
  * family's route module) with drifting contracts: body caps ranging 4 KiB to
  * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
@@ -34,6 +36,21 @@ export declare function readJsonBody(req: IncomingMessage, opts?: {
 }): Promise<unknown | null>;
 /** Narrow a value to a JSON object, or undefined when it is not one. */
 export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Request init that asks a remote origin for an uncompressed body.
+ *
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
+ * `content-encoding` header and automatic decompression, so a plain fetch
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+ * consumer can read. Every host fetch that parses a remote body must request
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
+ * `identity` because a caller value has no decoder behind it in this host.
+ * @param init - the caller's request init (signal, headers, method, ...).
+ * @returns a copy with `accept-encoding: identity` merged in.
+ */
+export declare function withIdentityEncoding(init?: RequestInit): RequestInit;
 /**
  * Write one JSON response. Default headers are the family defaults
  * (content-type and referrer-policy); caller headers are appended or

package/lib/types/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAWrF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9F;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBzB;AAOD,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAIN"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAWrF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9F;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBzB;AAOD,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,WAAgB,GAAG,WAAW,CAIxE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAIN"}

package/lib/types/http.js

@@ -2,7 +2,9 @@
 /**
  * Shared JSON body/response helpers for the host route families: one strict
  * bounded body reader, one lenient bounded body reader, one JSON object
- * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
+ * were copy-pasted across the
  * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
  * family's route module) with drifting contracts: body caps ranging 4 KiB to
  * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
@@ -80,6 +82,25 @@ function isJsonObject(value) {
 export function asJsonObject(value) {
     return isJsonObject(value) ? value : undefined;
 }
+/**
+ * Request init that asks a remote origin for an uncompressed body.
+ *
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
+ * `content-encoding` header and automatic decompression, so a plain fetch
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+ * consumer can read. Every host fetch that parses a remote body must request
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
+ * `identity` because a caller value has no decoder behind it in this host.
+ * @param init - the caller's request init (signal, headers, method, ...).
+ * @returns a copy with `accept-encoding: identity` merged in.
+ */
+export function withIdentityEncoding(init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set('accept-encoding', 'identity');
+    return { ...init, headers };
+}
 /**
  * Write one JSON response. Default headers are the family defaults
  * (content-type and referrer-policy); caller headers are appended or

package/lib/types/index.d.ts

@@ -34,9 +34,12 @@ export declare const name = "remote-web-ui";
 /** Services required before the pairing surfaces can mount. */
 export declare const inject: string[];
 /**
- * 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.
+ * Settings namespace of the remote-control capability. Under the 0.1.7
+ * settings model the namespace IS the Host profile entry id, so this is also
+ * the id the browser half asks `ctx.configForms` for (the family binder
+ * resolves the same value to the owning entry). Spelled here rather than
+ * imported: the browser half spells the same value and must not depend on a
+ * Host package.
  */
 export declare const REMOTE_WEB_UI_SETTINGS_NAMESPACE: SettingsNamespace;
 /** Plugin config, validated by the same-named schemastery schema. */
@@ -49,22 +52,28 @@ export interface Config {
     maxDevices?: number;
     /**
      * Idle sessions older than this (ms) are deleted from memory and disk.
-     * Default is 7 days; a leftover cookie no longer authorizes after expiry.
+     * Default is 30 days; a leftover cookie no longer authorizes after expiry.
      */
     idleExpireMs?: number;
     /** Cookie name carrying the paired device id. */
     cookieName?: string;
     /**
      * When true (default), a desktop Web GUI opened at a non-loopback origin
-     * rides the gated `/remote/api` channel and must carry a live paired-device
-     * cookie — the QR is the only way into remote desktop, and stop()/revoke()
-     * cut the /remote channel and the pairing cookie off immediately. Scope
+     * rides the gated `/remote/api` channel, whose requests must carry a live
+     * paired-device cookie — the QR is the only way into remote desktop, and
+     * stop()/revoke() cut the channel and the pairing cookie off immediately.
+     * This policy selects the transport; it never loosens the channel, whose
+     * gate is unconditional (issue #1665). Scope
      * note for this cohort: direct /api is governed by the harness fence +
      * browser-auth cookie (the api/gate seam has no emitter on 0.1.2-alpha.2),
      * so a harness browser credential a device has already redeemed is not
      * invalidated by stop() — see the README security model. Set false to keep
      * the desktop on plain `/api` (only useful when that origin is already
-     * trusted for `/api`).
+     * trusted for `/api`). Turning the policy off does NOT open the channel:
+     * the /remote proxy attaches the process's own browser-auth credential only
+     * when the request itself presents a live paired-device credential, so an
+     * unpaired LAN/tunnel caller is forwarded without it and the inner route
+     * answers 401.
      */
     requirePairingForLan?: boolean;
     /**
@@ -164,9 +173,8 @@ type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'trustedHosts' | '
 };
 /**
  * The single mapping from resolved plugin config to the pairing service
- * config. Both the constructed service and every live settings sync reuse
- * it, so no field can be silently dropped when the web settings surface
- * pushes a new value into the running service.
+ * config. Both the constructed service and every later apply of this row
+ * reuse it, so no field can be silently dropped.
  */
 export declare function pairingConfigOf(resolved: Pick<ResolvedConfig, 'tokenTtlMs' | 'offlineAfterMs' | 'maxDevices' | 'idleExpireMs' | 'cookieName' | 'devicesFile'>): PairingConfig;
 /** Default paired-session store: `$DSH_HOME/remote-web-ui-devices.json`. */

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAClE,OAAO,CAAC,MAAM,aAAa,CAAA;AAO3B,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAkCzF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,MAAM;QACd;;;;;;;;;;;WAWG;QACH,UAAU,CACR,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACrC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAC9B;CACF;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,kBAAkB,CAAA;AAEnC,+DAA+D;AAC/D,eAAO,MAAM,MAAM,UAA+C,CAAA;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,EAAsB,iBAAiB,CAAA;AAEpF,qEAAqE;AACrE,MAAM,WAAW,MAAM;IACrB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAgB3B,CAAA;AAYF;;;;GAIG;AACH,KAAK,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC,GAAG;IACvI,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,wFAAwF;IACxF,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,IAAI,CAC5C,cAAc,EACd,YAAY,GAAG,gBAAgB,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,GAAG,aAAa,CAC/F,GAAG,aAAa,CAShB;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAkB,GAAG,MAAM,CAEnE;AAqBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,kBAAuD,CAAA;AAEzE,iBAAS,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CA2mBtD"}

package/lib/types/index.js

@@ -26,6 +26,7 @@ import { isHttpUrl, tunnelPlanOf } from "./tunnel-plan.js";
 import { loadRelayIdentity, RelayRegistrar } from "./relay-registry.js";
 import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf } from "./lan-bind-plan.js";
 import { createInnerAuth } from "./inner-auth.js";
+import { withIdentityEncoding } from "./http.js";
 import { TunnelManager } from "./tunnel.js";
 import { PublicBaseKeeper } from "./public-base.js";
 import { checkUpdates, fetchGitHubReleaseNotes, fetchLatestVersion, RELEASE_NOTES_CACHE_TTL_MS, resolveAnchorManifest, resolveUpdateTarget, runUpdateVerified, } from "./update.js";
@@ -38,9 +39,12 @@ export const name = 'remote-web-ui';
 /** Services required before the pairing surfaces can mount. */
 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.
+ * Settings namespace of the remote-control capability. Under the 0.1.7
+ * settings model the namespace IS the Host profile entry id, so this is also
+ * the id the browser half asks `ctx.configForms` for (the family binder
+ * resolves the same value to the owning entry). 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 = 'remote-web-ui';
 export const Config = z.object({
@@ -62,11 +66,16 @@ export const Config = z.object({
 });
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
 const SWEEP_INTERVAL_MS = 10_000;
+/**
+ * How long one update-status probe answer is reused. The probe fans out one
+ * registry GET per family package plus a GitHub call, and the sidebar update
+ * entry asks for the status on every GUI page load.
+ */
+const UPDATE_STATUS_TTL_MS = 60_000;
 /**
  * The single mapping from resolved plugin config to the pairing service
- * config. Both the constructed service and every live settings sync reuse
- * it, so no field can be silently dropped when the web settings surface
- * pushes a new value into the running service.
+ * config. Both the constructed service and every later apply of this row
+ * reuse it, so no field can be silently dropped.
  */
 export function pairingConfigOf(resolved) {
     return {
@@ -125,30 +134,12 @@ function applyImpl(ctx, config) {
         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 (installSection swaps it when the namespace registers).
-    let current = () => config ?? {};
-    const resolve = () => {
-        const value = current();
-        return {
-            tokenTtlMs: value.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
-            offlineAfterMs: value.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
-            maxDevices: value.maxDevices ?? DEFAULTS.maxDevices,
-            idleExpireMs: value.idleExpireMs ?? DEFAULTS.idleExpireMs,
-            cookieName: value.cookieName ?? DEFAULTS.cookieName,
-            requirePairingForLan: value.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
-            publicBaseUrl: value.publicBaseUrl ?? envPublicBase,
-            trustedHosts: value.trustedHosts,
-            devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
-            autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
-            tunnelToken: value.tunnelToken,
-            relay: value.relay ?? DEFAULTS.relay,
-            lanBind: value.lanBind,
-            profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
-            enabled: value.enabled ?? DEFAULTS.enabled,
-        };
-    };
+    // The effective configuration this activation runs on: under the 0.1.7
+    // settings model the plugin's own Config IS its settings document, so the
+    // Host serves the settings page from this schema and reloads the row after a
+    // save — a live edit re-enters apply() with the new value instead of being
+    // pushed into a running instance.
+    const resolve = () => resolved;
     const service = new PairingService(pairingConfigOf(resolved));
     // ── auto tunnel ─────────────────────────────────────────────────────────
     // The minted public URL becomes the QR base (and the pairing fence's
@@ -271,13 +262,14 @@ function applyImpl(ctx, config) {
             : [];
         service.setLanBases(lanBases);
     }
-    // Push a committed settings section into the service and gate. The service
+    // Push the effective configuration 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
-    // without a restart. When `enabled` turns off, the pairing routes and
-    // sweep timer are dropped and all device/token state is revoked, but the
-    // gate listener stays mounted so a LAN-exposed /api stays behind pairing
-    // (now vetoing every non-loopback request) instead of opening the fence.
+    // gate re-reads its fence flag per request, so a saved edit takes effect
+    // without a restart (the Host reloads this row, and apply re-runs). When
+    // `enabled` is off, the pairing routes and sweep timer are dropped and all
+    // device/token state is revoked, but the gate listener stays mounted so a
+    // LAN-exposed /api stays behind pairing (now vetoing every non-loopback
+    // request) instead of opening the fence.
     let disposeRoutes;
     let disposeSweep;
     // ── remote update ────────────────────────────────────────────────────────
@@ -308,16 +300,34 @@ function applyImpl(ctx, config) {
         releaseNotesCache.set(version, { at: Date.now(), notes });
         return notes;
     };
-    const updateRoutes = makeUpdateRoutes({
-        // Control endpoints are host-surface only: a LAN/phone origin must never
-        // trigger a real install on this machine.
-        fence: request => isTrustedApiRequest(request, []),
-        check: () => checkUpdates({
+    // The status probe fans out one registry GET per family package (plus a
+    // GitHub release-notes call), and the sidebar update entry asks for it on
+    // every GUI page load — so the answer is memoized briefly and concurrent
+    // callers share one probe. A completed update invalidates it.
+    let updateStatusCache;
+    let updateStatusInFlight;
+    const checkStatusCached = () => {
+        const cached = updateStatusCache;
+        if (cached !== undefined && Date.now() - cached.at < UPDATE_STATUS_TTL_MS)
+            return Promise.resolve(cached.value);
+        if (updateStatusInFlight !== undefined)
+            return updateStatusInFlight;
+        updateStatusInFlight = checkUpdates({
             anchorManifestPath: resolveAnchorPath(),
             resolve: hostResolve,
             fetchLatest: name => fetchLatestVersion(name, fetch),
             fetchReleaseNotes: fetchReleaseNotesCached,
-        }),
+        }).then((value) => {
+            updateStatusCache = { at: Date.now(), value };
+            return value;
+        }).finally(() => { updateStatusInFlight = undefined; });
+        return updateStatusInFlight;
+    };
+    const updateRoutes = makeUpdateRoutes({
+        // Control endpoints are host-surface only: a LAN/phone origin must never
+        // trigger a real install on this machine.
+        fence: request => isTrustedApiRequest(request, []),
+        check: () => checkStatusCached(),
         run: async () => {
             const target = resolveUpdateTarget({ anchorManifestPath: resolveAnchorPath() });
             if ('error' in target) {
@@ -334,7 +344,7 @@ function applyImpl(ctx, config) {
             // 11 minimumReleaseAge gate can silently keep the installed versions
             // (same-day releases), which a plain exit-0 check would report as
             // success — the user then restarts and nothing changed.
-            return runUpdateVerified({
+            const result = await runUpdateVerified({
                 run: { profileDir: target.profileDir, packages: target.packages },
                 check: {
                     anchorManifestPath: resolveAnchorPath(),
@@ -343,6 +353,9 @@ function applyImpl(ctx, config) {
                     fetchReleaseNotes: fetchReleaseNotesCached,
                 },
             });
+            // The install moved (or failed) the versions the cached status reported.
+            updateStatusCache = undefined;
+            return result;
         },
     });
     // LAN-bind facts for the settings card, re-read per request so a hot
@@ -416,11 +429,17 @@ function applyImpl(ctx, config) {
             return appShellCache.html;
         const cookie = await innerAuth.ready();
         try {
-            const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, {
+            const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, withIdentityEncoding({
                 headers: cookie !== undefined ? { cookie } : undefined,
-            });
-            if (!response.ok)
+            }));
+            if (!response.ok) {
+                // A stale credential (secret rotation, 30-day TTL) must not wedge every
+                // later landing: drop it so the next attempt re-redeems, exactly as the
+                // proxy path does on an upstream 401.
+                if (response.status === 401 || response.status === 403)
+                    innerAuth.invalidate();
                 return undefined;
+            }
             const html = await response.text();
             appShellCache = { at: Date.now(), html };
             return html;
@@ -458,15 +477,15 @@ function applyImpl(ctx, config) {
                 return list;
             },
         }),
-        // 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
-        // and routes above, so a stale client rewrite on an open-LAN deployment
-        // proxies instead of 403ing.
+        // The remote desktop channel: a paired-credential-gated `/remote` prefix
+        // that re-issues fenced paths to loopback (see remote-api.ts). The gate is
+        // unconditional — requirePairingForLan governs the plain /api surface and
+        // the desktop's client-side rewrite only; it is never an authorization
+        // input here, because this channel attaches the process's own browser
+        // credential to everything it forwards (issue #1665).
         ...makeRemoteApiRoutes({
             service,
             port: ctx.webServer.port,
-            requirePairingForLan: () => resolve().requirePairingForLan,
             auth: innerAuth,
         }),
         ...updateRoutes,
@@ -474,7 +493,6 @@ function applyImpl(ctx, config) {
     const upgrades = makeRemoteApiUpgradeRoutes({
         service,
         port: ctx.webServer.port,
-        requirePairingForLan: () => resolve().requirePairingForLan,
         auth: innerAuth,
     });
     const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled);
@@ -559,6 +577,9 @@ function applyImpl(ctx, config) {
     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)');
     }
+    // Apply the effective configuration to the running surfaces once per
+    // activation: the service tunables, the LAN-bind block/firewall, the tunnel
+    // plan, the pairing routes, the presence sweep, and the posture probe.
     const sync = () => {
         const value = resolve();
         service.config = pairingConfigOf(value);
@@ -655,6 +676,10 @@ function applyImpl(ctx, config) {
                 : { kind: 'quick', targetUrl: plan.targetUrl, originHostHeader });
         }
         else if (plan.mode === 'named') {
+            // The hostname is fixed and known before the process runs, so publish it
+            // now: a named tunnel that fails to start must not leave the previous
+            // mode's ephemeral host as the QR and fence base.
+            publicBase.markRunning(plan.publicUrl);
             tunnel.start({ kind: 'named', token: plan.token, publicUrl: plan.publicUrl });
         }
         else {
@@ -676,8 +701,17 @@ function applyImpl(ctx, config) {
             }
         }
         const enabled = value.enabled;
-        if (!enabled)
+        if (!enabled) {
             service.stop();
+            // The tunnel branch above follows the plan, not the master switch, so an
+            // explicit "off" must also drop the public ingress it started: otherwise
+            // the cloudflared child keeps a live public URL (and the relay keeps its
+            // stable row) while the panel says remote control is stopped. The relay
+            // row is deliberately kept so re-enabling reuses the same origin.
+            tunnel.stop();
+            disposeRelayRegistrar();
+            publicBase.reset();
+        }
         if (disposeRoutes === undefined && enabled) {
             disposeRoutes = ctx.effect(() => {
                 const disposers = [
@@ -726,27 +760,8 @@ function applyImpl(ctx, config) {
             return;
         table.push({ kind: 'script', placement: 'head', text: REMOTE_CHANNEL_BOOT_SCRIPT });
     }), 'remote-web-ui: remote channel boot patch');
-    ctx.inject(['settings'], (settingsCtx) => {
-        try {
-            if (typeof settingsCtx.settings?.installSection === 'function') {
-                settingsCtx.settings.installSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
-                    setSource: (source) => {
-                        current = source;
-                        sync();
-                    },
-                    onChange: sync,
-                });
-            }
-            else if (typeof settingsCtx.settings?.register === 'function') {
-                const scope = settingsCtx.settings.register(REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, { base: config ?? {} });
-                current = () => scope?.get?.() ?? (config ?? {});
-                scope?.watch?.(() => { sync(); });
-                sync();
-            }
-        }
-        catch {
-            // Defensive fallback against settings registration differences
-        }
-    });
+    // No settings registration: the Host derives this plugin's settings page
+    // from the exported `Config` schema and reloads the row after a save, so
+    // every write re-enters apply() with the new config (see `resolve`).
     sync();
 }

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

@@ -7,8 +7,9 @@
  * 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.
+ * pairing gate: the `/remote` channel always requires a live paired-device
+ * credential before this module is consulted, regardless of the
+ * requirePairingForLan LAN policy (issue #1665).
  */
 /** Browser-auth credential the proxy attaches to loopback-bound requests. */
 export interface InnerAuth {

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

@@ -1 +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"}
+{"version":3,"file":"inner-auth.d.ts","sourceRoot":"","sources":["../../src/inner-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;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

@@ -7,8 +7,9 @@
  * 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.
+ * pairing gate: the `/remote` channel always requires a live paired-device
+ * credential before this module is consulted, regardless of the
+ * requirePairingForLan LAN policy (issue #1665).
  */
 /** The harness browser-auth cookie name prefix (see dsh-client-connection). */
 const BROWSER_AUTH_COOKIE_PREFIX = 'dsh-auth-';

package/lib/types/pair-grant.d.ts

@@ -0,0 +1,66 @@
+/**
+ * One-time pairing grants for the /pair-app landing.
+ *
+ * The QR entry (`/pair-accept?pair=<token>`) used to hand the freshly minted
+ * device id to the app landing in its own URL (`/pair-app?device=<id>`). A
+ * device id is a live session credential: the channel gate authorizes every
+ * gated request by it and the cookie it mirrors lives a year, so a URL carrying
+ * it leaks that credential into browser history, the address bar, and every log
+ * on the path. The landing is reached with a one-time grant instead — 256 bits
+ * of entropy, a short TTL, and single-consume semantics — and the device id
+ * reaches the client only inside the server-rendered shell (the capture script
+ * the landing patches in).
+ *
+ * Consume semantics follow the reference implementation's one-time host
+ * capability (zcode `packages/server/src/hostCapability.ts`): the record is
+ * deleted on EVERY consume attempt — success, expiry, or replay — so a captured
+ * grant is worthless after its first use and a replayed one can never resolve,
+ * and only a first use inside the TTL yields a device.
+ *
+ * @module @linxin666/dsh-remote-web-ui/pair-grant
+ */
+/**
+ * Default grant lifetime. The grant only has to survive one redirect chain
+ * from the accept page to the app landing, tunnel round trips included, so it
+ * is far shorter than the device session it stands in for.
+ */
+export declare const DEFAULT_PAIR_GRANT_TTL_MS = 60000;
+/**
+ * Cap on live grants. The accept page is rate-limited per source, but the
+ * table is still caller-driven, so it stays bounded (oldest evicted first)
+ * exactly like the device table.
+ */
+export declare const MAX_LIVE_GRANTS = 256;
+/** Clock/entropy injection for tests. */
+export interface PairGrantStoreOptions {
+    /** Grant lifetime in ms (default {@link DEFAULT_PAIR_GRANT_TTL_MS}). */
+    ttlMs?: number;
+    /** Clock seam (default Date.now). */
+    now?: () => number;
+    /** Entropy seam (default 32 random bytes, base64url). */
+    createGrant?: () => string;
+}
+/** One issued grant and its absolute expiry (both non-secret to the issuer). */
+export interface PairGrantRecord {
+    /** The one-time secret carried in the /pair-app URL. */
+    grant: string;
+    /** Absolute expiry (ms epoch); a consume past this resolves to nothing. */
+    expiresAt: number;
+}
+/** The grant table surface the routes consume. */
+export interface PairGrantStore {
+    /** Mint one grant bound to a device session. */
+    issue(deviceId: string): PairGrantRecord;
+    /** Redeem a grant once, returning its device id (undefined when unusable). */
+    consume(grant: string | undefined): string | undefined;
+    /** Liveness check that does not spend the grant (the fence fallback). */
+    peek(grant: string | undefined): string | undefined;
+    /** Live grant count (tests/diagnostics). */
+    readonly size: number;
+}
+/**
+ * Build the grant table. Pure TypeScript with injected clock/randomness so the
+ * whole one-time semantics are unit-testable without a server.
+ */
+export declare function createPairGrantStore(options?: PairGrantStoreOptions): PairGrantStore;
+//# sourceMappingURL=pair-grant.d.ts.map

package/lib/types/pair-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-grant.d.ts","sourceRoot":"","sources":["../../src/pair-grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAAA;IACxC,8EAA8E;IAC9E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;IACtD,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;IACnD,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAQD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAoDxF"}