@linxin666/dsh-remote-web-ui 0.2.4 → 0.2.6

package/lib/types/client/remote-channel.js

@@ -0,0 +1,246 @@
+/**
+ * The remote desktop channel — browser half. On a non-loopback origin (LAN
+ * address or public tunnel) fenced host routes refuse the request, and
+ * pairing is the real access control — so same-origin traffic the desktop
+ * issues is rewritten onto this plugin's gated `/remote` prefix (host half
+ * in src/remote-api.ts). The host then re-issues the call to 127.0.0.1 so
+ * plugin loopback fences pass.
+ *
+ * The rewrite is deliberately narrow:
+ * - loopback origins are untouched (the desktop at 127.0.0.1 keeps original paths);
+ * - the pairing routes (`/api/pair/*`) stay where they are — accept must
+ *   work BEFORE a device is paired;
+ * - the update endpoints (`/api/update/*`) stay loopback-only;
+ * - desktop-launcher create/shutdown (`/api/dsh-desktop-launcher/*`) stay
+ *   loopback-only (host-local files and process exit);
+ * - the family settings bridge (`/api/dsh-web-ui-settings/*`) stays
+ *   loopback-only (same plane as SDK settings.*);
+ * - `/api/*` (SDK methods and `/api/<plugin>/...` plugin namespaces),
+ *   `/sidebar/*`, `/git/*`, and `/pet/*` ride the channel;
+ * - fetch, EventSource, WebSocket, and img/script/iframe `src` are patched;
+ *   everything else calls the original unchanged.
+ *
+ * Pure helpers are exported for unit tests; `installRemoteChannel` patches
+ * the given window and returns their restore.
+ */
+/** The gated mirror prefix (must match src/remote-methods.ts). */
+export const REMOTE_PREFIX = '/remote';
+/** Connection-plugin method prefix under the gated channel. */
+export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`;
+const API_PREFIX = '/api/';
+const PAIR_PREFIX = '/api/pair/';
+const UPDATE_PREFIX = '/api/update/';
+const DESKTOP_LAUNCHER_PREFIX = '/api/dsh-desktop-launcher';
+const SETTINGS_BRIDGE_PREFIX = '/api/dsh-web-ui-settings';
+const SIDEBAR_PREFIX = '/sidebar/';
+const GIT_PREFIX = '/git/';
+const PET_PREFIX = '/pet/';
+const WS_PATHS = new Set([
+    '/api/events.mux',
+    '/api/events.host',
+    '/sidebar/ws/terminal',
+    '/sidebar/ws/agent-terminals',
+    '/api/dsh-ssh/terminal',
+]);
+/**
+ * Browser-safe loopback classification for the page origin (the SDK client
+ * exports its own; this copy keeps the module dependency-free).
+ * @param hostname - a location hostname (IPv6 without brackets).
+ * @returns true for localhost, IPv6 loopback, or any 127/8 literal.
+ */
+export function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '::1')
+        return true;
+    const parts = hostname.split('.');
+    return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/**
+ * Whether one same-origin path must ride the gated channel (fetch, EventSource,
+ * img/script/iframe src).
+ * @param pathname - the request URL pathname.
+ */
+export function shouldRewriteFetchPath(pathname) {
+    if (pathname.startsWith(PAIR_PREFIX))
+        return false;
+    if (pathname.startsWith(UPDATE_PREFIX))
+        return false;
+    if (pathname === DESKTOP_LAUNCHER_PREFIX || pathname.startsWith(`${DESKTOP_LAUNCHER_PREFIX}/`))
+        return false;
+    if (pathname === SETTINGS_BRIDGE_PREFIX || pathname.startsWith(`${SETTINGS_BRIDGE_PREFIX}/`))
+        return false;
+    if (pathname.startsWith(API_PREFIX))
+        return true;
+    if (pathname.startsWith(SIDEBAR_PREFIX) || pathname === '/sidebar')
+        return true;
+    if (pathname.startsWith(GIT_PREFIX) || pathname === '/git')
+        return true;
+    if (pathname.startsWith(PET_PREFIX) || pathname === '/pet')
+        return true;
+    return false;
+}
+/**
+ * Whether one WebSocket path must ride the gated channel.
+ * @param pathname - the WebSocket URL pathname.
+ */
+export function shouldRewriteWsPath(pathname) {
+    return WS_PATHS.has(pathname);
+}
+/** The gated twin of one fenced path (`/remote` + original pathname). */
+export function rewritePath(pathname) {
+    return `${REMOTE_PREFIX}${pathname}`;
+}
+/**
+ * Rewrite one raw URL string when it is same-origin and fenced. Relative
+ * inputs stay relative so resource loaders do not unexpectedly absolutize.
+ */
+export function rewriteRawUrl(raw, baseHref, origin) {
+    let url;
+    try {
+        url = new URL(raw, baseHref);
+    }
+    catch {
+        return raw;
+    }
+    if (url.origin !== origin)
+        return raw;
+    if (!shouldRewriteFetchPath(url.pathname))
+        return raw;
+    url.pathname = rewritePath(url.pathname);
+    if (raw.startsWith('/') && !raw.startsWith('//')) {
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    return url.href;
+}
+/** Read an unpaired code from either the SDK envelope or a plugin JSON body. */
+function unpairedCodeOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    const nested = record.result;
+    if (typeof nested === 'object' && nested !== null) {
+        const error = nested.error;
+        if (typeof error === 'object' && error !== null && typeof error.code === 'string') {
+            return error.code;
+        }
+    }
+    const error = record.error;
+    if (typeof error === 'object' && error !== null && typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+}
+/**
+ * Whether a gated 403 is the unpaired-device fence (not a loopback-only
+ * method denial, which uses the same status with code `forbidden`).
+ */
+export async function isUnpairedDenied(response) {
+    if (response.status !== 403)
+        return false;
+    try {
+        return unpairedCodeOf(await response.json()) === 'unpaired';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wrap a prototype `src` setter so fenced same-origin URLs ride `/remote`.
+ * No-ops when the constructor is missing or `src` is not configurable.
+ */
+function patchSrcAccessor(ctor, rewrite) {
+    if (ctor === undefined)
+        return () => { };
+    const descriptor = Object.getOwnPropertyDescriptor(ctor.prototype, 'src');
+    if (descriptor === undefined || descriptor.configurable === false)
+        return () => { };
+    if (descriptor.set === undefined)
+        return () => { };
+    const originalSet = descriptor.set;
+    const originalGet = descriptor.get;
+    Object.defineProperty(ctor.prototype, 'src', {
+        configurable: true,
+        enumerable: descriptor.enumerable ?? true,
+        get: originalGet,
+        set(value) {
+            originalSet.call(this, rewrite(String(value)));
+        },
+    });
+    return () => {
+        Object.defineProperty(ctor.prototype, 'src', descriptor);
+    };
+}
+/**
+ * Patch `fetch`, `EventSource`, `WebSocket`, and resource `src` accessors on
+ * one window to route fenced traffic through the gated channel.
+ * @param window - the browser window (or a test double).
+ * @param options - the unpaired callback.
+ * @returns a function restoring the originals.
+ */
+export function installRemoteChannel(window, options = {}) {
+    const originalFetch = window.fetch;
+    const OriginalWebSocket = window.WebSocket;
+    const OriginalEventSource = window.EventSource;
+    const sameOrigin = (url) => url.origin === window.location.origin;
+    const rewrite = (raw) => rewriteRawUrl(raw, window.location.href, window.location.origin);
+    const patchedFetch = (input, init) => {
+        const url = new URL(typeof input === 'string' || input instanceof URL ? input.toString() : input.url, window.location.href);
+        if (sameOrigin(url) && shouldRewriteFetchPath(url.pathname)) {
+            const rewritten = new URL(url);
+            rewritten.pathname = rewritePath(url.pathname);
+            const next = typeof input === 'string' || input instanceof URL
+                ? rewritten.toString()
+                : new Request(rewritten, input);
+            return Promise.resolve(originalFetch.call(window, next, init)).then(async (response) => {
+                if (await isUnpairedDenied(response.clone()))
+                    options.onUnpaired?.();
+                else
+                    options.onPaired?.();
+                return response;
+            });
+        }
+        return originalFetch.call(window, input, init);
+    };
+    class PatchedWebSocket extends OriginalWebSocket {
+        constructor(url, protocols) {
+            const parsed = new URL(url.toString(), window.location.href);
+            const wsOrigin = parsed.protocol === 'wss:' ? `https://${parsed.host}` : parsed.protocol === 'ws:' ? `http://${parsed.host}` : '';
+            if (wsOrigin !== '' && wsOrigin === window.location.origin && shouldRewriteWsPath(parsed.pathname)) {
+                const rewritten = new URL(parsed);
+                rewritten.pathname = rewritePath(parsed.pathname);
+                super(rewritten, protocols);
+                return;
+            }
+            super(url, protocols);
+        }
+    }
+    const restoreSrc = [
+        patchSrcAccessor(window.HTMLImageElement, rewrite),
+        patchSrcAccessor(window.HTMLScriptElement, rewrite),
+        patchSrcAccessor(window.HTMLIFrameElement, rewrite),
+    ];
+    window.fetch = patchedFetch;
+    window.WebSocket = PatchedWebSocket;
+    if (OriginalEventSource !== undefined) {
+        class PatchedEventSource extends OriginalEventSource {
+            constructor(url, eventSourceInitDict) {
+                const parsed = new URL(url.toString(), window.location.href);
+                if (sameOrigin(parsed) && shouldRewriteFetchPath(parsed.pathname)) {
+                    const rewritten = new URL(parsed);
+                    rewritten.pathname = rewritePath(parsed.pathname);
+                    super(rewritten, eventSourceInitDict);
+                    return;
+                }
+                super(url, eventSourceInitDict);
+            }
+        }
+        window.EventSource = PatchedEventSource;
+    }
+    return () => {
+        window.fetch = originalFetch;
+        window.WebSocket = OriginalWebSocket;
+        if (OriginalEventSource !== undefined)
+            window.EventSource = OriginalEventSource;
+        for (const restore of restoreSrc)
+            restore();
+    };
+}

package/lib/types/dsh-home.d.ts

@@ -0,0 +1,17 @@
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Resolve the DSH home directory from the live environment. */
+export declare function dshHome(): string;
+//# sourceMappingURL=dsh-home.d.ts.map

package/lib/types/dsh-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh-home.d.ts","sourceRoot":"","sources":["../../src/dsh-home.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAKH,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAOrG;AAED,gEAAgE;AAChE,wBAAgB,OAAO,IAAI,MAAM,CAEhC"}

package/lib/types/dsh-home.js

@@ -0,0 +1,34 @@
+// Generated by scripts/sync-shared.mjs from shared/host/dsh-home.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export function expandHome(path, home = homedir()) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return join(home, path.slice(2));
+    return path;
+}
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export function resolveDshHome(env = process.env, home = homedir()) {
+    const raw = env.DSH_HOME;
+    if (raw !== undefined && raw.trim() !== '') {
+        const expanded = expandHome(raw.trim(), home);
+        return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded);
+    }
+    return join(home, '.dsh');
+}
+/** Resolve the DSH home directory from the live environment. */
+export function dshHome() {
+    return resolveDshHome();
+}

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

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASvF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAQvE;AAED,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,oBAAoB,GAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAQ,EACtD,OAAO,GAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAQ,GACxC,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAW9H;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAIhG"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASvF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAQvE;AAED,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,oBAAoB,GAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAQ,EACtD,OAAO,GAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAQ,GACxC,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAc9H;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAIhG"}

package/lib/types/gate.js

@@ -78,16 +78,19 @@ export function isLoopbackClient(request) {
  */
 export function makeGateListener(service, requirePairingForLan = true, enabled = true) {
     return (request, _method, next) => {
+        // Loopback clients (desktop at 127.0.0.1) always pass without cookie check.
         if (isLoopbackClient(request))
             return next();
         const active = typeof enabled === 'function' ? enabled() : enabled;
         if (!active)
             return false;
         const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan;
+        // When pairing is not required for LAN, non-loopback requests pass too.
         if (!require)
             return next();
-        // The paired-device cookie is a full host-API credential: it passes this
-        // gate for the whole ApiProxy surface, not just the /m/api allowlist.
+        // Non-loopback origin: verify paired-device cookie. Sibling plugins that
+        // own their own prefixes (/pet, /git, /sidebar, …) consult the same cookie
+        // through the remoteWebUiPairing service — this listener only covers /api.
         return isPairedDeviceRequest(service, request) ? next() : false;
     };
 }

package/lib/types/index.d.ts

@@ -40,13 +40,19 @@ export interface Config {
     offlineAfterMs?: number;
     /** Hard cap on paired device sessions (oldest evicted when full). */
     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.
+     */
+    idleExpireMs?: number;
     /** Cookie name carrying the paired device id. */
     cookieName?: string;
     /**
-     * When true (default), every non-loopback /api request must carry a live
-     * paired-device cookie — the QR is the only way into a LAN-exposed dsh
-     * web, and stop() genuinely cuts paired devices off. Set false to keep
-     * the fence's open-LAN behavior and use pairing only for tokens/status.
+     * 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() cuts
+     * paired devices off. Set false to keep the desktop on plain `/api`
+     * (only useful when that origin is already trusted for `/api`).
      */
     requirePairingForLan?: boolean;
     /**
@@ -60,17 +66,16 @@ export interface Config {
     publicBaseUrl?: string;
     /**
      * Absolute path to a JSON file where paired device sessions are persisted.
-     * When set, a paired phone keeps its session across `dsh web` restarts
-     * (the phone-side cookie already lives 365 days), so re-scanning the QR
-     * after each restart is unnecessary. Unset keeps sessions memory-only
-     * (previous behavior).
+     * Defaults to `$DSH_HOME/remote-web-ui-devices.json` so a paired device
+     * keeps its session across `dsh web` restarts (the cookie already lives
+     * 365 days). Override to another absolute path when needed.
      */
     devicesFile?: string;
     /**
      * When true, the plugin runs its own Cloudflare quick tunnel (the
      * cloudflared binary ships with the package — no user-side install) and
-     * feeds the minted public URL into both the QR base and the /api trust
-     * fence dynamically, so phones anywhere can pair without any manual
+     * feeds the minted public URL into the QR base and the phone-facing
+     * pairing fence dynamically, so phones anywhere can pair without any manual
      * tunnel setup. The manual `publicBaseUrl` is ignored while this is on.
      */
     autoTunnel?: boolean;
@@ -92,7 +97,7 @@ export declare const Config: z<Config>;
  */
 type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile'>> & {
     publicBaseUrl: string | undefined;
-    devicesFile: string | undefined;
+    devicesFile: string;
 };
 /**
  * The single mapping from resolved plugin config to the pairing service
@@ -100,7 +105,9 @@ type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile'>> &
  * it, so no field can be silently dropped when the web settings surface
  * pushes a new value into the running service.
  */
-export declare function pairingConfigOf(resolved: Pick<ResolvedConfig, 'tokenTtlMs' | 'offlineAfterMs' | 'maxDevices' | 'cookieName' | 'devicesFile'>): PairingConfig;
+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`. */
+export declare function defaultDevicesFile(home?: string): string;
 /**
  * Mount the pairing service, routes, gate listener, and presence sweep.
  * @param ctx - host plugin context carrying webServer.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,CAAC,MAAM,aAAa,CAAA;AAE3B,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAmBjE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,MAAM;QACd;;;;;WAKG;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,UAA4B,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,uDAAqC,CAAA;AAElF,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,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAW3B,CAAA;AAKF;;;;GAIG;AACH,KAAK,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC,GAAG;IAC9E,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CAChC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,IAAI,CAC5C,cAAc,EACd,YAAY,GAAG,gBAAgB,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,CAC9E,GAAG,aAAa,CAQhB;AAgBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,kBAAuD,CAAA;AAEzE,iBAAS,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAgOtD"}
+{"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;AAElD,OAAO,CAAC,MAAM,aAAa,CAAA;AAE3B,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAsBzF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,MAAM;QACd;;;;;WAKG;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,UAA4B,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,uDAAqC,CAAA;AAElF,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;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAY3B,CAAA;AAKF;;;;GAIG;AACH,KAAK,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC,GAAG;IAC9E,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;GAKG;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;AAiBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,kBAAuD,CAAA;AAEzE,iBAAS,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAuRtD"}

package/lib/types/index.js

@@ -8,15 +8,19 @@
  * phone-side pair/accept + deep-link flow.
  */
 import { createRequire } from 'node:module';
-import { setInterval as nodeSetInterval } from 'node:timers';
+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 { PairingService } from './pairing.js';
+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 { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from './remote-api.js';
+import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from './posture.js';
 import { lanIPv4Addresses } from './lan.js';
 import { TunnelManager } from './tunnel.js';
 import { checkUpdates, fetchLatestVersion, resolveAnchorManifest, resolveUpdateTarget, runUpdateVerified, } from './update.js';
@@ -36,6 +40,7 @@ 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),
     maxDevices: z.number().step(1).min(1).max(64).default(4),
+    idleExpireMs: z.number().step(1).min(60_000).default(DEFAULT_IDLE_EXPIRE_MS),
     cookieName: z.string().min(1).default('dsh_pair'),
     requirePairingForLan: z.boolean().default(true),
     publicBaseUrl: z.string(),
@@ -57,19 +62,25 @@ export function pairingConfigOf(resolved) {
         tokenTtlMs: resolved.tokenTtlMs,
         offlineAfterMs: resolved.offlineAfterMs,
         maxDevices: resolved.maxDevices,
+        idleExpireMs: resolved.idleExpireMs,
         cookieName: resolved.cookieName,
         devicesFile: resolved.devicesFile,
     };
 }
+/** Default paired-session store: `$DSH_HOME/remote-web-ui-devices.json`. */
+export function defaultDevicesFile(home = dshHome()) {
+    return join(home, 'remote-web-ui-devices.json');
+}
 /** Schema defaults, re-read for hand-built test contexts (the loader applies them normally). */
 const DEFAULTS = {
     tokenTtlMs: 10 * 60_000,
     offlineAfterMs: 25_000,
     maxDevices: 4,
+    idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
     cookieName: 'dsh_pair',
     requirePairingForLan: true,
     publicBaseUrl: undefined,
-    devicesFile: undefined,
+    devicesFile: defaultDevicesFile(),
     autoTunnel: false,
     mobileEnterToSend: true,
     enabled: true,
@@ -85,10 +96,11 @@ function applyImpl(ctx, config) {
         tokenTtlMs: config?.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
         offlineAfterMs: config?.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
         maxDevices: config?.maxDevices ?? DEFAULTS.maxDevices,
+        idleExpireMs: config?.idleExpireMs ?? DEFAULTS.idleExpireMs,
         cookieName: config?.cookieName ?? DEFAULTS.cookieName,
         requirePairingForLan: config?.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
         publicBaseUrl: config?.publicBaseUrl,
-        devicesFile: config?.devicesFile,
+        devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
         autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
         mobileEnterToSend: config?.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
         enabled: config?.enabled ?? DEFAULTS.enabled,
@@ -103,6 +115,7 @@ function applyImpl(ctx, config) {
             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,
@@ -127,6 +140,7 @@ function applyImpl(ctx, config) {
         if (info.phase === 'running' && info.url !== undefined) {
             service.setPublicBaseUrl(info.url);
             service.setTunnelStatus({ state: 'running', url: info.url });
+            runPostureProbe();
         }
         else if (info.phase === 'starting') {
             // A restart mints a NEW hostname: the previous URL dies with the old
@@ -239,10 +253,58 @@ function applyImpl(ctx, config) {
         ...(apiProxy !== undefined
             ? makeMobileApiRoutes({ service, apiProxy, mobileEnterToSend: () => resolve().mobileEnterToSend })
             : []),
+        // The remote desktop channel: paired-cookie-gated `/remote` prefix that
+        // re-issues fenced paths to loopback (see remote-api.ts).
+        ...makeRemoteApiRoutes({ service, port: ctx.webServer.port }),
         ...updateRoutes,
     ];
+    const upgrades = makeRemoteApiUpgradeRoutes({ service, port: ctx.webServer.port });
     const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled);
     ctx.effect(() => ctx.on('api/gate', gate), 'remote-web-ui: api gate');
+    // ── posture probe ─────────────────────────────────────────────────────────
+    // Guardrail for the one seam this plugin cannot mount a gate into: the
+    // connection plugin's /api Host fence. Forged-Host probes against every
+    // advertised origin (public base + LAN bases) make a re-opened /api (a
+    // re-added --trusted-host, or the SDK's LAN auto-trust under 0.0.0.0)
+    // visible on the panel and the log instead of silently trusted.
+    let postureKey;
+    let postureWasExposed = false;
+    const runPostureProbe = () => {
+        if (!resolve().enabled)
+            return;
+        const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, ctx.webServer.port);
+        if (targets.length === 0) {
+            postureKey = undefined;
+            service.setPosture(undefined);
+            return;
+        }
+        const key = targets.join('|');
+        const claim = claimPostureKey(postureKey, key);
+        if (!claim.run)
+            return;
+        postureKey = claim.next;
+        void probePosture({ port: ctx.webServer.port, targets }).then((snapshot) => {
+            service.setPosture(snapshot);
+            const exposedHosts = snapshot.hosts.filter(host => host.exposed).map(host => host.host);
+            const exposed = exposedHosts.length > 0;
+            if (exposed && !postureWasExposed) {
+                console.error(`remote-web-ui: CRITICAL — the /api fence is OPEN for [${exposedHosts.join(', ')}]: unpaired clients reach the full host API. Remove --trusted-host for these hosts (pairing covers them) or bind loopback.`);
+            }
+            else if (!exposed && postureWasExposed) {
+                console.log('remote-web-ui: the /api posture probe is clean again (every advertised origin refused with 403).');
+            }
+            postureWasExposed = exposed;
+        }).catch(() => {
+            // Keep the previous snapshot; drop the in-flight key so the same
+            // targets retry instead of sticking on a failed round.
+            postureKey = releasePostureKey(postureKey, key);
+        });
+    };
+    // The first round waits for the connection plugin's /api route: a probe
+    // before it mounts would read the SPA fallback and false-positive.
+    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
     // plugin is not installed; stop() / enabled=false still refuse cookies.
     new RemoteWebUiPairing(ctx, (request) => {
@@ -280,7 +342,10 @@ function applyImpl(ctx, config) {
             service.stop();
         if (disposeRoutes === undefined && enabled) {
             disposeRoutes = ctx.effect(() => {
-                const disposers = routes.map(route => ctx.webServer.register(route));
+                const disposers = [
+                    ...routes.map(route => ctx.webServer.register(route)),
+                    ...upgrades.map(route => ctx.webServer.registerUpgrade(route)),
+                ];
                 return () => { for (const dispose of disposers)
                     dispose(); };
             }, 'remote-web-ui: pairing routes');
@@ -300,6 +365,9 @@ function applyImpl(ctx, config) {
             disposeSweep();
             disposeSweep = undefined;
         }
+        // Settings changed the reachable posture (manual publicBaseUrl, bind):
+        // re-probe unless the target set is unchanged.
+        runPostureProbe();
     };
     installSettingsSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
         setSource: (source) => {

package/lib/types/loopback-proxy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loopback-shaped reverse proxy used by the remote desktop channel: after
+ * the pairing cookie gate, traffic is re-issued to 127.0.0.1 so sibling
+ * plugin fences (socket + Host loopback) accept it. Origin, cookies, and
+ * caller-controlled Sec-Fetch markers are dropped. HTTP requests receive a
+ * synthetic same-origin marker after the pairing gate so sibling loopback
+ * routes that require a browser tripwire accept the authenticated proxy.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+/**
+ * Pipe one HTTP request to loopback and stream the response back.
+ * @param req - the already-gated outer request.
+ * @param res - the outer response.
+ * @param port - local webServer port.
+ * @param upstreamPath - path + query on 127.0.0.1 (must start with `/`).
+ */
+export declare function proxyLoopbackHttp(req: IncomingMessage, res: ServerResponse, port: number, upstreamPath: string): void;
+/**
+ * Rebuild a WebSocket handshake as loopback-shaped and pipe both directions.
+ * @param req - the already-gated upgrade request.
+ * @param socket - the client duplex.
+ * @param head - bytes already read past the handshake.
+ * @param port - local webServer port.
+ * @param upstreamPath - path + query on 127.0.0.1.
+ */
+export declare function proxyLoopbackUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, port: number, upstreamPath: string): void;
+//# sourceMappingURL=loopback-proxy.d.ts.map

package/lib/types/loopback-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-proxy.d.ts","sourceRoot":"","sources":["../../src/loopback-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAuB,cAAc,EAAE,MAAM,WAAW,CAAA;AAGrF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAqBzC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,IAAI,CAmCN;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,IAAI,CA6BN"}