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

package/lib/types/remote-presence-pet.js

@@ -0,0 +1,101 @@
+/**
+ * Remote-presence to pet-visibility link (user requirement): while at least
+ * one paired device is online (an active phone mirror session), the
+ * host-global pet is hidden through the pet's OWN hide switch (the
+ * PetService.setVisible RPC, the same one the pet's hide button uses);
+ * once the last device stays offline past a grace window, the pet is
+ * restored. The pet plugin is optional: without it (or on any pet failure)
+ * the link is a no-op - the remote-control feature never depends on the
+ * pet being installed.
+ *
+ * The visibility is host-global by design (the pet is host-global, no
+ * session dimension): the desktop and the phone share one pet, so the link
+ * hides it while the operator is away on a phone mirror and restores it
+ * when the mirror ends. A manual user hide is respected: if the pet is
+ * already hidden when the first device comes online, nothing is recorded
+ * and nothing is restored later.
+ */
+/** Default restore grace: the presence sweep flips a device offline after
+ * ~25 s, and a phone that was briefly backgrounded should not flicker the
+ * pet; 2 minutes keeps the restore stable. */
+const DEFAULT_RESTORE_AFTER_MS = 120_000;
+const nodeTimers = { setTimeout, clearTimeout };
+/**
+ * Start the presence link. Returns the disposer (withdraws the state
+ * subscription and cancels a pending restore).
+ * @param deps - pairing stream + pet seam (+ test seams).
+ */
+export function startRemotePresencePet(deps) {
+    const restoreAfterMs = deps.restoreAfterMs ?? DEFAULT_RESTORE_AFTER_MS;
+    const timers = deps.timers ?? nodeTimers;
+    let previousOnline = false;
+    let hiddenByRemote = false;
+    let restoreTimer;
+    let disposed = false;
+    const clearRestore = () => {
+        if (restoreTimer !== undefined) {
+            timers.clearTimeout(restoreTimer);
+            restoreTimer = undefined;
+        }
+    };
+    const scheduleRestore = () => {
+        clearRestore();
+        restoreTimer = timers.setTimeout(() => {
+            restoreTimer = undefined;
+            restoreAfterTick();
+        }, restoreAfterMs);
+    };
+    const restoreAfterTick = () => {
+        if (disposed || !hiddenByRemote)
+            return;
+        const pet = deps.pet();
+        if (pet === undefined)
+            return;
+        hiddenByRemote = false;
+        void pet.setVisible(true).catch(() => {
+            // The pet bridge failed (e.g. the pet host was mid-reload): the pet
+            // stays whatever it is; the next connect/disconnect cycle re-evaluates.
+        });
+    };
+    const hideForRemote = () => {
+        if (hiddenByRemote)
+            return;
+        const pet = deps.pet();
+        if (pet === undefined)
+            return;
+        void pet.state().then((value) => {
+            if (disposed || hiddenByRemote)
+                return;
+            const visible = value.display?.visible;
+            if (visible !== true)
+                return;
+            hiddenByRemote = true;
+            return pet.setVisible(false).catch(() => {
+                // Hide failed: leave the flag unset so a later transition retries.
+                hiddenByRemote = false;
+            });
+        }, () => {
+            // The state read failed; do not record a hide we never performed.
+        });
+    };
+    const handle = (snapshot) => {
+        const online = snapshot.phase === 'connected' && snapshot.onlineCount > 0;
+        if (online && !previousOnline) {
+            cancelRestoreAndClear();
+            hideForRemote();
+        }
+        else if (!online && previousOnline) {
+            scheduleRestore();
+        }
+        previousOnline = online;
+    };
+    const cancelRestoreAndClear = () => {
+        clearRestore();
+    };
+    const unsubscribe = deps.onState(handle);
+    return () => {
+        disposed = true;
+        unsubscribe();
+        clearRestore();
+    };
+}

package/lib/types/routes.d.ts

@@ -3,9 +3,14 @@
  * under /api: the webserver matches exact paths before the connection
  * plugin's /api prefix, so these handlers own the full response lifecycle
  * and apply their own trust fence (loopback-only for control endpoints;
- * loopback-or-LAN for the phone-facing accept/heartbeat/status). The
- * cookie set on accept is the device identity the api/gate listener checks
- * on every other /api request.
+ * loopback-or-LAN for the phone-facing accept/heartbeat/status). The cookie
+ * set on accept is the device identity the plugin's own surfaces enforce:
+ * the /remote channel gate and the api/gate listener. Alongside the JSON
+ * family sit the phone-facing top-level pages (exact routes /pair-accept,
+ * /pair-app, /pair-app.sw.js) with their own LAN-or-public fence. Note that
+ * on the 0.1.2-alpha.2 cohort nothing emits api/gate — direct /api is
+ * governed by the harness fence + browser auth — while the /remote channel
+ * always enforces the pairing cookie itself.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
@@ -26,6 +31,16 @@ import { type PairingService, type PairingSnapshot } from './pairing.ts';
  * browser markers are same-origin.
  */
 export declare function isTrustedApiRequest(request: IncomingMessage, trustedHosts: readonly string[]): boolean;
+/**
+ * The rate-limit bucket key for one accept attempt (pure; unit-tested).
+ * The first client-visible XFF hop separates buckets behind the auto-tunnel
+ * (every internet client arrives from 127.0.0.1 there) — but only for
+ * loopback peers, since a direct LAN client can rotate the header freely.
+ * @param socketIp - the socket peer address.
+ * @param forwarded - the first XFF hop, already trimmed, if any.
+ * @param bucket - page (GET /pair-accept) vs api (POST /api/pair/accept).
+ */
+export declare function acceptLimitKey(socketIp: string, forwarded: string | undefined, bucket: 'page' | 'api'): string;
 /**
  * The host authority of a configured public base URL, e.g. `foo.trycloudflare.com`
  * from `https://foo.trycloudflare.com`. Undefined when the URL does not parse —
@@ -35,6 +50,38 @@ export declare function isTrustedApiRequest(request: IncomingMessage, trustedHos
  * @returns the `host[:port]` authority the fence should trust.
  */
 export declare function publicHostOf(url: string | undefined): string | undefined;
+/**
+ * The cookieless device credential: pass the device id from the /pair-app
+ * URL into sessionStorage (and localStorage for tab reloads) before any app
+ * script runs - same key the boot patch and the channel gate read. The
+ * replaceState to '/' hides the credential URL from the address bar and
+ * leaves the SPA at its canonical root path. The reopen service worker is
+ * registered in the same breath: later navigations to '/' (history,
+ * bookmark, tab restore) must not fall through to the harness index gate,
+ * which the cookieless flow can never satisfy.
+ */
+export declare const APP_DEVICE_STORAGE_KEY = "dsh-remote-device";
+export declare function appShellCaptureScript(deviceId: string): string;
+/** Patch the official index document with the device-capture script. */
+export declare function patchAppShell(html: string, deviceId: string): string;
+/**
+ * The reopen service worker served at PAIR_PATHS.appServiceWorker. A paired
+ * phone comes back to `/` from history, bookmarks, or tab restore; the
+ * harness fallback seat answers that navigation with its browser-auth 401,
+ * and the cookieless mobile flow never holds a browser-auth cookie. The
+ * worker owns navigations to `/` instead: network-first through /pair-app
+ * (which validates the device cookie and refreshes its presence), the
+ * cached shell for offline opens, and a pass-through of the original
+ * request when the plugin no longer answers. Plain-HTTP LAN origins are not
+ * secure contexts, so the worker never registers there — the LAN reopen
+ * path stays "scan a fresh QR", which is cheap in-network.
+ *
+ * Kept as a plain string (same pattern as the capture script): it must load
+ * with no build step, run on every JS engine that ships service workers,
+ * and be assertable as source in tests. Bump SHELL_CACHE when the storage
+ * layout changes so old caches are pruned on activate.
+ */
+export declare function appServiceWorkerScript(): string;
 /** Route paths (exact matches under /api). */
 export declare const PAIR_PATHS: {
     readonly issue: "/api/pair/issue";
@@ -44,6 +91,16 @@ export declare const PAIR_PATHS: {
     readonly heartbeat: "/api/pair/heartbeat";
     readonly status: "/api/pair/status";
     readonly events: "/api/pair/events";
+    readonly lanBind: "/api/pair/lan-bind";
+    /** Top-level accept-and-redirect entry the QR link points at. */
+    readonly acceptPage: "/pair-accept";
+    /** The cookieless app landing: serves the official shell for a paired device. */
+    readonly appPage: "/pair-app";
+    /**
+     * The reopen service worker (registered by the capture script). Root-level
+     * path so its default script-directory scope already covers `/`.
+     */
+    readonly appServiceWorker: "/pair-app.sw.js";
 };
 /**
  * /api/pair request payload contracts. Each POST endpoint validates its body
@@ -54,7 +111,6 @@ export declare const PAIR_PATHS: {
  * are tolerated exactly as the previous manual reads ignored them.
  */
 export declare const issuePayloadSchema: z.ZodObject<{
-    workspaceId: z.ZodOptional<z.ZodString>;
     address: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const acceptPayloadSchema: z.ZodObject<{
@@ -86,6 +142,22 @@ export interface PairRoutesDeps {
     lanAddresses: readonly string[];
     /** Current desktop gate policy, re-read for every status response. */
     requirePairingForLan?: boolean | (() => boolean);
+    /**
+     * LAN-bind facts for the settings card (managed patch block state, live
+     * bind host/port, firewall summary). Re-read per request so a hot-reloaded
+     * rebind and a fresh toggle round are both reflected without a restart.
+     * The route is loopback-only; undefined drops it (tests).
+     */
+    lanBindStatus?: () => Record<string, unknown>;
+    /**
+     * The official index document to serve on the /pair-app landing. The
+     * plugin fetches it from the inner loopback with its own credential and
+     * patches it with the device-capture script, so a paired device loads
+     * the app shell WITHOUT passing the harness index gate - the mobile flow
+     * then needs no browser cookie at all (the channel gate accepts the
+     * cookieless header/query credential). Undefined drops the route (tests).
+     */
+    indexDocument?: (deviceId: string) => Promise<string | undefined>;
 }
 /**
  * Build the /api/pair route family.

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

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAA;AACrC,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAIhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6BtG;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOxE;AAKD,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;;CAQb,CAAA;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAA;AACF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,eAAO,MAAM,uBAAuB,gCAA6B,CAAA;AAoBjE,gDAAgD;AAChD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;gBACS,OAAO,EAAE,cAAc;IAInC,4DAA4D;IAC5D,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAiBrD,kEAAkE;IAClE,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAYrC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,cAAc,CAAA;IACvB,0EAA0E;IAC1E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;CACjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,EAAE,CAkO3D"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAA;AACrC,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAKhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6BtG;AAKD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAK9G;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOxE;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAA;AAEzD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAoD/C;AA4BD,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;;;IASrB,iEAAiE;;IAEjE,iFAAiF;;IAEjF;;;OAGG;;CAEK,CAAA;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAA;AACF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,eAAO,MAAM,uBAAuB,gCAA6B,CAAA;AAoBjE,gDAAgD;AAChD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;gBACS,OAAO,EAAE,cAAc;IAInC,4DAA4D;IAC5D,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAiBrD,kEAAkE;IAClE,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAYrC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,cAAc,CAAA;IACvB,0EAA0E;IAC1E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;IAChD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAClE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,EAAE,CAmY3D"}