@linxin666/dsh-remote-web-ui 0.2.3 → 0.2.5

package/lib/types/pairing.js

@@ -13,10 +13,16 @@
  *   unknown one (no oracle for validity).
  * - `stop()` revokes every device session and clears the token, so paired
  *   devices are cut off on their next gated request.
+ * - `revoke()` drops one device session; idle sessions older than
+ *   `idleExpireMs` are deleted on sweep, load, and the next gated request.
  */
 import { randomBytes } from 'node:crypto';
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+/** Default idle-expiry window: 7 days without heartbeat or a gated request. */
+export const DEFAULT_IDLE_EXPIRE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cap on the persisted/displayed User-Agent string. */
+const MAX_USER_AGENT_CHARS = 180;
 /** Thrown by issue() for an address outside the sampled LAN literals. */
 export class UnknownLanAddressError extends Error {
     /**
@@ -53,6 +59,9 @@ export class PairingService {
     publicBase;
     /** Auto-tunnel status, while the auto-tunnel feature is active. */
     tunnelStatus;
+    posture;
+    /** True when lastSeenAt changed since the last persist (flushed on sweep). */
+    dirty = false;
     /**
      * @param config - tunables. The settings surface replaces the object (a
      * fresh literal) when a committed section changes; every operation reads
@@ -82,12 +91,19 @@ export class PairingService {
                     continue;
                 if (typeof session !== 'object' || session === null)
                     continue;
-                const { createdAt, lastSeenAt } = session;
+                const { createdAt, lastSeenAt, userAgent } = session;
                 if (typeof createdAt !== 'number' || typeof lastSeenAt !== 'number')
                     continue;
-                this.devices.set(deviceId, { createdAt, lastSeenAt });
+                const label = typeof userAgent === 'string' ? sanitizeUserAgent(userAgent) : undefined;
+                this.devices.set(deviceId, {
+                    createdAt,
+                    lastSeenAt,
+                    ...(label !== undefined ? { userAgent: label } : {}),
+                });
             }
             this.clampToMaxDevices();
+            if (this.evictIdle())
+                this.persist();
         }
         catch {
             // Unreadable/corrupt: start empty rather than refusing to boot.
@@ -102,12 +118,24 @@ export class PairingService {
         for (const [id] of ordered.slice(0, overflow))
             this.devices.delete(id);
     }
+    /** Drop sessions whose lastSeenAt is older than idleExpireMs. */
+    evictIdle() {
+        const now = this.clock.now();
+        const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS;
+        let removed = false;
+        for (const [id, session] of [...this.devices]) {
+            if (now - session.lastSeenAt > limit) {
+                this.devices.delete(id);
+                removed = true;
+            }
+        }
+        return removed;
+    }
     /**
      * Write the current device table to the configured file. Called on the
-     * mutation boundaries that change the set of live sessions (accept and
-     * stop); `lastSeenAt` refreshes are deliberately not persisted here so a
-     * per-request write storm is avoided — after a restart the phone's first
-     * heartbeat re-warms its own session.
+     * mutation boundaries that change the set of live sessions (accept, stop,
+     * revoke, idle eviction) and, throttled, from sweep() so lastSeenAt
+     * survives a restart without a write per request.
      *
      * Device ids are session credentials (the gate authorizes requests by the
      * cookie's device id), so the file is written 0600 via a temp file and
@@ -120,8 +148,12 @@ export class PairingService {
         try {
             mkdirSync(dirname(file), { recursive: true });
             const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
-            writeFileSync(temp, JSON.stringify(Object.fromEntries(this.devices)), { mode: 0o600 });
+            const payload = {};
+            for (const [id, session] of this.devices)
+                payload[id] = session;
+            writeFileSync(temp, JSON.stringify(payload), { mode: 0o600 });
             renameSync(temp, file);
+            this.dirty = false;
         }
         catch (error) {
             console.error('remote-web-ui: failed to persist paired devices', error);
@@ -158,6 +190,11 @@ export class PairingService {
         this.tunnelStatus = status;
         this.notify();
     }
+    /** Set the latest /api posture probe result (see posture.ts). */
+    setPosture(snapshot) {
+        this.posture = snapshot;
+        this.notify();
+    }
     /**
      * Issue a fresh token, replacing (invalidating) any previous one. A
      * stopped service re-arms through this call (the panel's refresh button).
@@ -198,9 +235,10 @@ export class PairingService {
      * successful call for the same token is impossible because the first
      * consumes it.
      * @param token - the token secret from the QR link.
+     * @param userAgent - optional User-Agent header captured at accept.
      * @returns the new device id, or a refusal code.
      */
-    accept(token) {
+    accept(token, userAgent) {
         const record = this.tokens.get(token);
         if (record === undefined || record.consumed || this.stopped || this.clock.now() > record.expiresAt) {
             return { ok: false, code: record?.consumed === true ? 'used' : 'invalid' };
@@ -218,7 +256,12 @@ export class PairingService {
             if (oldest !== undefined)
                 this.devices.delete(oldest.id);
         }
-        this.devices.set(deviceId, { createdAt: now, lastSeenAt: now });
+        const label = sanitizeUserAgent(userAgent);
+        this.devices.set(deviceId, {
+            createdAt: now,
+            lastSeenAt: now,
+            ...(label !== undefined ? { userAgent: label } : {}),
+        });
         this.persist();
         this.notify();
         return { ok: true, deviceId };
@@ -235,18 +278,34 @@ export class PairingService {
         this.stopped = true;
         this.notify();
     }
+    /**
+     * Revoke one paired device. The next gated request from that cookie is
+     * refused; other sessions stay live. Unknown ids are a no-op.
+     * @param deviceId - the cookie value of the device to drop.
+     * @returns true when a live session was removed.
+     */
+    revoke(deviceId) {
+        if (this.stopped)
+            return false;
+        if (!this.devices.delete(deviceId))
+            return false;
+        this.persist();
+        this.notify();
+        return true;
+    }
     /**
      * The api/gate path: record activity for a device id and report whether
      * the request may proceed. Unknown or revoked ids (including any device
-     * after stop()) are refused.
+     * after stop() or idle expiry) are refused.
      * @param deviceId - the cookie value of the requesting device.
      * @returns true when the device session is live and was refreshed.
      */
     touchDevice(deviceId) {
-        const session = this.devices.get(deviceId);
-        if (session === undefined || this.stopped)
+        const session = this.liveSession(deviceId);
+        if (session === undefined)
             return false;
         session.lastSeenAt = this.clock.now();
+        this.dirty = true;
         this.notify();
         return true;
     }
@@ -255,17 +314,24 @@ export class PairingService {
         return this.touchDevice(deviceId);
     }
     /**
-     * Periodic sweep: re-evaluate the derived snapshot (a device aging past
-     * the offline window flips the phase to disconnected). Emits only when
-     * the snapshot actually changed.
+     * Periodic sweep: drop idle sessions, flush a dirty lastSeenAt, and
+     * re-evaluate the derived snapshot (a device aging past the offline
+     * window flips the phase to disconnected). Emits only when the snapshot
+     * actually changed.
      */
     sweep() {
+        const evicted = this.evictIdle();
+        if (evicted || this.dirty)
+            this.persist();
         this.notify();
     }
     /** The current snapshot (fresh object per call — stable between emits). */
     snapshot() {
         const now = this.clock.now();
-        const onlineCount = [...this.devices.values()].filter(session => this.isOnlineAt(session, now)).length;
+        const devices = [...this.devices.entries()]
+            .sort((a, b) => a[1].createdAt - b[1].createdAt)
+            .map(([id, session]) => this.toDeviceSnapshot(id, session, now));
+        const onlineCount = devices.filter(device => device.online).length;
         const token = this.activeToken();
         return {
             phase: this.derivePhase(onlineCount, token !== undefined),
@@ -273,15 +339,16 @@ export class PairingService {
             lanAddresses: [...this.lanBases.keys()],
             ...(this.publicBase !== undefined ? { publicUrl: this.publicBase } : {}),
             ...(this.tunnelStatus !== undefined ? { tunnel: this.tunnelStatus } : {}),
+            ...(this.posture !== undefined ? { posture: this.posture } : {}),
             ...(token !== undefined ? { tokenId: token.record.id, tokenExpiresAt: token.record.expiresAt } : {}),
             deviceCount: this.devices.size,
             onlineCount,
+            devices,
         };
     }
-    /** Whether a cookie value names a currently live device session. */
+    /** Whether a cookie value names a currently live (non-idle) device session. */
     hasDevice(deviceId) {
-        const session = this.devices.get(deviceId);
-        return session !== undefined && !this.stopped;
+        return this.liveSession(deviceId) !== undefined;
     }
     /** Subscribe to snapshot changes (each emit passes a fresh snapshot). */
     onState(listener) {
@@ -298,6 +365,34 @@ export class PairingService {
         }
         return undefined;
     }
+    /**
+     * Return a live session, deleting it first when idle-expired. Side-effecting
+     * so a stale cookie cannot pass the gate between sweeps.
+     */
+    liveSession(deviceId) {
+        if (this.stopped)
+            return undefined;
+        const session = this.devices.get(deviceId);
+        if (session === undefined)
+            return undefined;
+        const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS;
+        if (this.clock.now() - session.lastSeenAt > limit) {
+            this.devices.delete(deviceId);
+            this.persist();
+            this.notify();
+            return undefined;
+        }
+        return session;
+    }
+    toDeviceSnapshot(id, session, now) {
+        return {
+            id,
+            createdAt: session.createdAt,
+            lastSeenAt: session.lastSeenAt,
+            online: this.isOnlineAt(session, now),
+            ...(session.userAgent !== undefined ? { userAgent: session.userAgent } : {}),
+        };
+    }
     derivePhase(onlineCount, hasToken) {
         if (this.lanBases.size === 0 && this.publicBase === undefined)
             return 'lan-required';
@@ -340,7 +435,20 @@ function snapshotsEqual(a, b) {
         && a.tokenId === b.tokenId
         && a.tokenExpiresAt === b.tokenExpiresAt
         && a.deviceCount === b.deviceCount
-        && a.onlineCount === b.onlineCount;
+        && a.onlineCount === b.onlineCount
+        && devicesEqual(a.devices, b.devices);
+}
+/** Per-device roster equality (order is pairing time). */
+function devicesEqual(a, b) {
+    return a.length === b.length && a.every((device, index) => {
+        const other = b[index];
+        return other !== undefined
+            && device.id === other.id
+            && device.createdAt === other.createdAt
+            && device.lastSeenAt === other.lastSeenAt
+            && device.online === other.online
+            && device.userAgent === other.userAgent;
+    });
 }
 /** Tunnel frame equality (undefined equals undefined; fields compared shallowly). */
 function tunnelEqual(a, b) {
@@ -351,3 +459,12 @@ function tunnelEqual(a, b) {
 function sameStrings(a, b) {
     return a.length === b.length && a.every((value, index) => value === b[index]);
 }
+/** Strip control characters and cap the User-Agent stored with a session. */
+export function sanitizeUserAgent(raw) {
+    if (raw === undefined)
+        return undefined;
+    const cleaned = raw.replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim();
+    if (cleaned === '')
+        return undefined;
+    return cleaned.length <= MAX_USER_AGENT_CHARS ? cleaned : cleaned.slice(0, MAX_USER_AGENT_CHARS);
+}

package/lib/types/pairing.persist.test.js

@@ -1,19 +1,20 @@
 /**
  * PairingService device-session persistence: with `devicesFile` set, sessions
- * written on accept/stop survive a process restart (a new PairingService
- * instance), so a previously paired phone — whose cookie already lives 365
- * days — never needs to re-scan the QR after `dsh web` restarts.
+ * written on accept/stop/revoke/sweep survive a process restart (a new
+ * PairingService instance). lastSeenAt is flushed on sweep, not on every
+ * touch; idle sessions older than idleExpireMs are dropped on load.
  */
 import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { pairingConfigOf } from './index.js';
-import { PairingService } from './pairing.js';
+import { DEFAULT_IDLE_EXPIRE_MS, PairingService } from './pairing.js';
 const BASE_CONFIG = {
     tokenTtlMs: 60_000,
     offlineAfterMs: 25_000,
     maxDevices: 4,
+    idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
     cookieName: 'dsh_pair',
 };
 /** Deterministic clock: tokens are issued in a fixed, readable sequence. */
@@ -47,7 +48,11 @@ describe('PairingService device persistence', () => {
         const deviceId = pairDevice(first);
         expect(readFileSync(file, 'utf8')).toContain(deviceId);
         // Device ids are session credentials: the persisted file is 0600.
-        expect(statSync(file).mode & 0o777).toBe(0o600);
+        // win32: NTFS has no POSIX mode bits and Node ignores the writeFileSync
+        // mode option there, so the mode assertion only applies on POSIX (#772).
+        if (process.platform !== 'win32') {
+            expect(statSync(file).mode & 0o777).toBe(0o600);
+        }
         // Simulated restart: a brand-new service instance reading the same file.
         const second = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock());
         expect(second.hasDevice(deviceId)).toBe(true);
@@ -58,6 +63,7 @@ describe('PairingService device persistence', () => {
             tokenTtlMs: 60_000,
             offlineAfterMs: 25_000,
             maxDevices: 4,
+            idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
             cookieName: 'dsh_pair',
             devicesFile: file,
         });
@@ -72,6 +78,7 @@ describe('PairingService device persistence', () => {
             tokenTtlMs: 60_000,
             offlineAfterMs: 25_000,
             maxDevices: 4,
+            idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
             cookieName: 'dsh_pair',
             devicesFile: file,
         });
@@ -125,4 +132,52 @@ describe('PairingService device persistence', () => {
         const ghost = join(dir, 'does-not-exist.json');
         expect(() => new PairingService({ ...BASE_CONFIG, devicesFile: ghost }, makeClock())).not.toThrow();
     });
+    it('does not persist lastSeenAt on touch; sweep flushes it', () => {
+        const file = join(dir, 'devices.json');
+        const now = { value: 1_000_000 };
+        let n = 0;
+        const clock = {
+            now: () => now.value,
+            randomToken: () => `tok${(n++).toString().padStart(6, '0')}`,
+        };
+        const first = new PairingService({ ...BASE_CONFIG, devicesFile: file }, clock);
+        const deviceId = pairDevice(first);
+        const afterAccept = JSON.parse(readFileSync(file, 'utf8'));
+        expect(afterAccept[deviceId]?.lastSeenAt).toBe(1_000_000);
+        now.value = 1_500_000;
+        expect(first.touchDevice(deviceId)).toBe(true);
+        const afterTouch = JSON.parse(readFileSync(file, 'utf8'));
+        expect(afterTouch[deviceId]?.lastSeenAt).toBe(1_000_000);
+        first.sweep();
+        const afterSweep = JSON.parse(readFileSync(file, 'utf8'));
+        expect(afterSweep[deviceId]?.lastSeenAt).toBe(1_500_000);
+        const second = new PairingService({ ...BASE_CONFIG, devicesFile: file }, clock);
+        expect(second.hasDevice(deviceId)).toBe(true);
+        expect(second.snapshot().devices[0]?.lastSeenAt).toBe(1_500_000);
+    });
+    it('drops idle sessions on load instead of restoring them', () => {
+        const file = join(dir, 'devices.json');
+        writeFileSync(file, JSON.stringify({
+            stale: { createdAt: 1, lastSeenAt: 1 },
+        }));
+        const clock = {
+            now: () => 1 + DEFAULT_IDLE_EXPIRE_MS + 1,
+            randomToken: () => 'tok',
+        };
+        const service = new PairingService({ ...BASE_CONFIG, devicesFile: file }, clock);
+        expect(service.hasDevice('stale')).toBe(false);
+        const saved = JSON.parse(readFileSync(file, 'utf8'));
+        expect(saved).toEqual({});
+    });
+    it('persists a User-Agent captured at accept', () => {
+        const file = join(dir, 'devices.json');
+        const service = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock());
+        service.setPublicBaseUrl('https://pairing.example.trycloudflare.com');
+        const { token } = service.issue();
+        const result = service.accept(token, 'Mozilla/5.0 TestPhone');
+        expect(result.ok).toBe(true);
+        const saved = JSON.parse(readFileSync(file, 'utf8'));
+        const deviceId = result.ok ? result.deviceId : '';
+        expect(saved[deviceId]?.userAgent).toBe('Mozilla/5.0 TestPhone');
+    });
 });

package/lib/types/posture.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Deployment posture probe: verify that the connection plugin's `/api` fence
+ * actually refuses non-loopback requests for every origin this deployment
+ * advertises (the public tunnel host, the LAN bases). The fence is the SDK's
+ * own Host check — the one seam a plugin cannot mount a gate into — so this
+ * probe is the guardrail that makes a re-opened `/api` (for example a
+ * re-added `--trusted-host`, or the SDK's LAN-literal auto-trust under
+ * `--host 0.0.0.0`) visible instead of silent.
+ *
+ * The probe issues loopback requests with a forged Host header — the exact
+ * shape a tunnel or LAN client produces — and treats anything other than a
+ * 403 as exposed: the fence is documented to refuse with 403, so any other
+ * status means the request reached the RPC bridge.
+ */
+import type { ClientRequest, ClientRequestArgs } from 'node:http';
+/** One probed origin. */
+export interface PostureHost {
+    /** The forged Host header value that was probed. */
+    host: string;
+    /** True when the probe reached past the fence (anything but 403). */
+    exposed: boolean;
+}
+/** One probe round. */
+export interface PostureSnapshot {
+    /** When the round completed (epoch ms). */
+    checkedAt: number;
+    /** Every probed origin and its verdict. */
+    hosts: PostureHost[];
+}
+/** Whether any probed origin is currently exposed. */
+export declare function anyExposed(snapshot: PostureSnapshot): boolean;
+/**
+ * Build the forged Host values to probe: the public base authority (host or
+ * host:port as written in the URL) plus every LAN base literal.
+ * @param publicBaseUrl - the configured public base URL (or undefined).
+ * @param lanAddresses - the LAN interface addresses the QR advertises.
+ * @param port - the local webServer port (LAN hosts are probed as host:port).
+ * @returns Host header values, de-duplicated.
+ */
+export declare function postureTargets(publicBaseUrl: string | undefined, lanAddresses: string[], port: number): string[];
+/** Injectable transport seam (defaults to node:http). */
+export type ProbeRequest = (options: ClientRequestArgs, onStatus: (status: number) => void) => ClientRequest;
+/** Probe options. */
+export interface ProbePostureOptions {
+    /** The local webServer port. */
+    port: number;
+    /** Forged Host header values (see {@link postureTargets}). */
+    targets: string[];
+    /** Transport seam (defaults to node:http). */
+    request?: ProbeRequest;
+    /** Per-host timeout (default 3000 ms). */
+    timeoutMs?: number;
+    /** Clock seam (default Date.now). */
+    now?: () => number;
+}
+/**
+ * Run one posture probe round.
+ * @returns the snapshot for this round.
+ */
+export declare function probePosture(options: ProbePostureOptions): Promise<PostureSnapshot>;
+/**
+ * Reserve an advertised-target key so a second trigger with the same set
+ * does not overlap an in-flight round. Pair with {@link releasePostureKey}
+ * on failure — otherwise that key never retries.
+ */
+export declare function claimPostureKey(current: string | undefined, key: string): {
+    run: boolean;
+    next: string;
+};
+/**
+ * Drop a failed in-flight key so the next trigger re-probes the same targets.
+ * A newer key that started meanwhile is left alone.
+ */
+export declare function releasePostureKey(current: string | undefined, attempted: string): string | undefined;
+//# sourceMappingURL=posture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"posture.d.ts","sourceRoot":"","sources":["../../src/posture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGjE,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,uBAAuB;AACvB,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,2CAA2C;IAC3C,KAAK,EAAE,WAAW,EAAE,CAAA;CACrB;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAehH;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KAAK,aAAa,CAAA;AAyC5G,qBAAqB;AACrB,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CAWzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAGxG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpG"}

package/lib/types/posture.js

@@ -0,0 +1,116 @@
+/**
+ * Deployment posture probe: verify that the connection plugin's `/api` fence
+ * actually refuses non-loopback requests for every origin this deployment
+ * advertises (the public tunnel host, the LAN bases). The fence is the SDK's
+ * own Host check — the one seam a plugin cannot mount a gate into — so this
+ * probe is the guardrail that makes a re-opened `/api` (for example a
+ * re-added `--trusted-host`, or the SDK's LAN-literal auto-trust under
+ * `--host 0.0.0.0`) visible instead of silent.
+ *
+ * The probe issues loopback requests with a forged Host header — the exact
+ * shape a tunnel or LAN client produces — and treats anything other than a
+ * 403 as exposed: the fence is documented to refuse with 403, so any other
+ * status means the request reached the RPC bridge.
+ */
+import http from 'node:http';
+/** Whether any probed origin is currently exposed. */
+export function anyExposed(snapshot) {
+    return snapshot.hosts.some(host => host.exposed);
+}
+/**
+ * Build the forged Host values to probe: the public base authority (host or
+ * host:port as written in the URL) plus every LAN base literal.
+ * @param publicBaseUrl - the configured public base URL (or undefined).
+ * @param lanAddresses - the LAN interface addresses the QR advertises.
+ * @param port - the local webServer port (LAN hosts are probed as host:port).
+ * @returns Host header values, de-duplicated.
+ */
+export function postureTargets(publicBaseUrl, lanAddresses, port) {
+    const targets = [];
+    if (publicBaseUrl !== undefined) {
+        try {
+            const url = new URL(publicBaseUrl);
+            const authority = url.port === '' ? url.hostname : `${url.hostname}:${url.port}`;
+            if (authority !== '')
+                targets.push(authority);
+        }
+        catch {
+            // A malformed base is ignored elsewhere with a warning; nothing to probe.
+        }
+    }
+    for (const address of lanAddresses) {
+        targets.push(`${address}:${String(port)}`);
+    }
+    return [...new Set(targets)];
+}
+const defaultRequest = (options, onStatus) => {
+    const request = http.request(options, response => { onStatus(response.statusCode ?? 0); });
+    request.on('error', () => { onStatus(0); });
+    return request;
+};
+/**
+ * Probe one forged Host against the local `/api` fence.
+ * @param port - the local webServer port.
+ * @param hostHeader - the Host header to forge.
+ * @param request - transport seam.
+ * @param timeoutMs - give up after this long (counts as not exposed; the
+ * fence being unreachable is not evidence it is open).
+ * @returns true when the probe got past the fence.
+ */
+async function probeHost(port, hostHeader, request, timeoutMs) {
+    return await new Promise(resolve => {
+        let settled = false;
+        const finish = (exposed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            handle.destroy();
+            resolve(exposed);
+        };
+        const handle = request({
+            host: '127.0.0.1',
+            port,
+            method: 'POST',
+            path: '/api/session.list',
+            headers: { host: hostHeader, 'content-type': 'application/json' },
+            timeout: timeoutMs,
+        }, status => { finish(status !== 403); });
+        const timer = setTimeout(() => { finish(false); }, timeoutMs + 1_000);
+        handle.on('error', () => { finish(false); });
+        handle.end('{}');
+    });
+}
+/**
+ * Run one posture probe round.
+ * @returns the snapshot for this round.
+ */
+export async function probePosture(options) {
+    const { port, targets } = options;
+    const request = options.request ?? defaultRequest;
+    const timeoutMs = options.timeoutMs ?? 3_000;
+    const now = options.now ?? (() => Date.now());
+    const hosts = [];
+    for (const target of targets) {
+        // Sequential on purpose: one slow host must not multiply the round's latency.
+        hosts.push({ host: target, exposed: await probeHost(port, target, request, timeoutMs) });
+    }
+    return { checkedAt: now(), hosts };
+}
+/**
+ * Reserve an advertised-target key so a second trigger with the same set
+ * does not overlap an in-flight round. Pair with {@link releasePostureKey}
+ * on failure — otherwise that key never retries.
+ */
+export function claimPostureKey(current, key) {
+    if (current === key)
+        return { run: false, next: current };
+    return { run: true, next: key };
+}
+/**
+ * Drop a failed in-flight key so the next trigger re-probes the same targets.
+ * A newer key that started meanwhile is left alone.
+ */
+export function releasePostureKey(current, attempted) {
+    return current === attempted ? undefined : current;
+}

package/lib/types/remote-api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The remote desktop data channel: `/remote` is this plugin's own prefix, so
+ * the paired-device cookie is the access control (exactly like `/m/api`).
+ * After that gate, every fenced same-origin path the browser rewrote here is
+ * re-issued to 127.0.0.1 as a loopback-shaped request so sibling plugin
+ * fences (and the connection plugin's `/api`) accept it — no `--trusted-host`
+ * and no per-plugin pairing consult.
+ *
+ * Security model:
+ * - Every request must carry a live paired-device cookie, enforced before
+ *   any bytes are forwarded and before any host call.
+ * - The SDK's loopback-only privileged methods (native dialogs, the settings
+ *   plane, credentials — the `PRIVILEGED_METHODS` set of client-connection)
+ *   are denied here. The set is pinned by tests/remote-contract.spec.ts.
+ * - `/api/pair/*`, `/api/update/*`, `/api/plugin-manager/*`,
+ *   `/api/dsh-desktop-launcher/*` and `/api/dsh-web-ui-settings/*` stay physically local.
+ * - Everything else is HTTP- or WebSocket-proxied to the local port with
+ *   Host rewritten, Origin and cookies dropped, and a synthetic same-origin
+ *   browser marker added after authentication. Plugin loopback fences then
+ *   pass. The pairing cookie never leaves this process.
+ */
+import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { PairingService } from './pairing.ts';
+export { DESKTOP_LAUNCHER_PATH, LOOPBACK_ONLY_METHODS, PLUGIN_MANAGER_PATH, REMOTE_API_PATHS, REMOTE_PREFIX, REMOTE_UPGRADE_PATHS, WEB_UI_SETTINGS_BRIDGE_PATH, } from './remote-methods.ts';
+export { REMOTE_API_PREFIX } from './remote-methods.ts';
+/** Route-family dependencies. */
+export interface RemoteApiDeps {
+    /** The pairing service (device gate + cookie name). */
+    service: PairingService;
+    /** The local webServer port the loopback proxy connects to. */
+    port: number;
+}
+/**
+ * Map `/remote/...` to the inner path, or undefined when the outer path is
+ * not a safe rewrite target.
+ */
+export declare function innerPathOf(pathname: string): string | undefined;
+/**
+ * Whether a paired inner path must stay physically local.
+ * @returns a denial message, or undefined when the path may be proxied.
+ */
+export declare function loopbackOnlyDenial(innerPath: string): string | undefined;
+/**
+ * Build the remote desktop channel HTTP routes.
+ * @param deps - pairing service + local port.
+ * @returns the routes to register on webServer.
+ */
+export declare function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[];
+/**
+ * Map one outer upgrade URL onto the loopback path (query string included).
+ */
+export declare function upgradeInnerPath(reqUrl: string | undefined, fallbackPath: string): string;
+/**
+ * Build the WebSocket upgrade routes for the event streams and known plugin
+ * sockets. webServer matches upgrades by exact path.
+ * @param deps - pairing service + local port.
+ * @returns the upgrade routes to register on webServer.
+ */
+export declare function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute[];
+//# sourceMappingURL=remote-api.d.ts.map

package/lib/types/remote-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAclD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;CACb;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsBxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CAsCnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CAwBjF"}