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

package/src/remote-methods.ts

@@ -1,6 +1,15 @@
 /**
  * Remote desktop channel constants — SDK-independent so tests and the
  * client half can pin them without importing the host SDK graph.
+ *
+ * Access model on the 0.1.2-alpha.2 line: the host /api surface has no
+ * per-method privilege pin — the "configuration plane is local" behavior
+ * lives in the browser (client plugins branch on connection.isLoopback), and
+ * the paired remote desktop flips into host mode via the transport hook
+ * (ownsHost) while every call rides this gated channel as a loopback-shaped
+ * request. A paired device is therefore a full-control credential by
+ * design; the only paths that stay physically local are the control planes
+ * below (pairing control, self-update, plugin install/remove, host power).
  */
 
 /** Gated mirror of same-origin fenced paths (`/remote` + original pathname). */
@@ -9,10 +18,17 @@ export const REMOTE_PREFIX = '/remote'
 /** Connection-plugin method prefix under the gated channel. */
 export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`
 
-/** WebSocket event-stream paths served by the channel (client rewrites to these). */
+/**
+ * The gated mirrors of the official client WebSocket paths. On the pinned
+ * 0.1.2-alpha.2 line the client opens ONE persistent stream socket — the
+ * Typert gateway mux at `/api/remote.mux` — and every Remote stream
+ * (workspace follow, session feed, ...) rides it. If that socket is not
+ * rewritten onto the gated channel the phone's streams die at the connection
+ * fence and the UI shows an empty workspace/session mirror, so the mux is
+ * the one path that must never be missing here.
+ */
 export const REMOTE_API_PATHS = {
-  mux: `${REMOTE_API_PREFIX}/events.mux`,
-  host: `${REMOTE_API_PREFIX}/events.host`,
+  mux: `${REMOTE_API_PREFIX}/remote.mux`,
 } as const
 
 /**
@@ -21,7 +37,6 @@ export const REMOTE_API_PATHS = {
  */
 export const REMOTE_UPGRADE_PATHS = [
   REMOTE_API_PATHS.mux,
-  REMOTE_API_PATHS.host,
   `${REMOTE_PREFIX}/sidebar/ws/terminal`,
   `${REMOTE_PREFIX}/sidebar/ws/agent-terminals`,
   `${REMOTE_API_PREFIX}/dsh-ssh/terminal`,
@@ -33,30 +48,46 @@ export const PLUGIN_MANAGER_PATH = '/api/plugin-manager'
 /** Desktop-launcher HTTP prefix: shortcut create and host shutdown stay physically local. */
 export const DESKTOP_LAUNCHER_PATH = '/api/dsh-desktop-launcher'
 
-/** Family settings-bridge HTTP prefix: describe/mutate stay physically local. */
+/** Family settings-bridge HTTP prefix — re-exposed to paired devices (plain settings parity). */
 export const WEB_UI_SETTINGS_BRIDGE_PATH = '/api/dsh-web-ui-settings'
 
 /**
- * Loopback-only methods of the host API surface, mirrored from
- * client-connection's `PRIVILEGED_METHODS` (pinned by
- * tests/remote-contract.spec.ts against the installed SDK). They stay
- * unreachable from a paired remote desktop, matching the SDK's own stance
- * that the configuration plane is loopback-same-origin only.
+ * The cookieless device credential: the boot patch reads the device id from
+ * the /pair-app URL, keeps it in sessionStorage, and attaches it to every
+ * gated HTTP call as this header (and to WebSocket upgrades as the `device`
+ * query parameter - WS handshakes cannot carry headers from the Web API).
+ * The channel gate accepts it exactly like the device cookie, so the mobile
+ * flow works even with browser cookies fully blocked; the cookie remains the
+ * primary credential on normal browsers.
+ */
+export const REMOTE_DEVICE_HEADER = 'x-dsh-remote-device'
+export const REMOTE_DEVICE_QUERY = 'device'
+
+/**
+ * Path prefixes that stay physically local even for a paired device. A
+ * paired remote desktop may use the full host API (chat, sessions,
+ * settings, credentials, presets — it is a full-control credential), but it
+ * must not reach the machine-control planes: pairing control itself, the
+ * dsh-web self-update installer, plugin install/remove, and desktop
+ * launcher actions (host shutdown, shortcuts).
+ */
+export const LOCAL_ONLY_PREFIXES: readonly string[] = [
+  '/api/pair',
+  '/api/update',
+  PLUGIN_MANAGER_PATH,
+  DESKTOP_LAUNCHER_PATH,
+] as const
+
+/**
+ * Whether a paired inner path must stay physically local.
+ * @param innerPath - the rewritten inner path (e.g. `/api/session.list`).
+ * @returns a denial message, or undefined when the path may be proxied.
  */
-export const LOOPBACK_ONLY_METHODS = new Set([
-  'agentPreset.read',
-  'agentPreset.copy',
-  'agentPreset.openDocument',
-  'agentPreset.remove',
-  'host.pickDirectory',
-  'host.openPath',
-  'settings.describe',
-  'settings.openDocument',
-  'settings.update',
-  'settings.replace',
-  'settings.mutate',
-  'credentials.describe',
-  'credentials.set',
-  'credentials.unset',
-  'llm.discoverModels',
-])
+export function localOnlyDenial(innerPath: string): string | undefined {
+  for (const prefix of LOCAL_ONLY_PREFIXES) {
+    if (innerPath === prefix || innerPath.startsWith(`${prefix}/`)) {
+      return `${prefix.slice(1)} stays physically local and stays unreachable from a paired remote desktop`
+    }
+  }
+  return undefined
+}

package/src/remote-presence-pet.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ */
+
+/** The pet service seam the link needs (structural slice, no package edge). */
+export interface PresencePetSeam {
+  /** RPC: show or hide the pet. */
+  setVisible(visible: boolean): Promise<unknown>
+  /** Read the current display state (the visibility the user sees). */
+  state(): Promise<{ display?: { visible?: boolean } }>
+}
+
+/** Dependencies of the presence link (all injectable for tests). */
+export interface PresencePetDeps {
+  /** Subscribe to pairing snapshot changes (fires with every state change). */
+  onState(listener: (snapshot: { phase: string; onlineCount: number }) => void): () => void
+  /** Resolve the pet service seam (undefined when the pet plugin is absent). */
+  pet(): PresencePetSeam | undefined
+  /** Grace before restoring the pet after the last device went offline. */
+  restoreAfterMs?: number
+  timers?: {
+    setTimeout(fn: () => void, ms: number): unknown
+    clearTimeout(t: unknown): void
+  }
+}
+
+/** 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: PresencePetDeps): () => void {
+  const restoreAfterMs = deps.restoreAfterMs ?? DEFAULT_RESTORE_AFTER_MS
+  const timers = deps.timers ?? nodeTimers
+  let previousOnline = false
+  let hiddenByRemote = false
+  let restoreTimer: unknown | undefined
+  let disposed = false
+
+  const clearRestore = (): void => {
+    if (restoreTimer !== undefined) {
+      timers.clearTimeout(restoreTimer)
+      restoreTimer = undefined
+    }
+  }
+
+  const scheduleRestore = (): void => {
+    clearRestore()
+    restoreTimer = timers.setTimeout(() => {
+      restoreTimer = undefined
+      restoreAfterTick()
+    }, restoreAfterMs)
+  }
+
+  const restoreAfterTick = (): void => {
+    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 = (): void => {
+    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: { phase: string; onlineCount: number }): void => {
+    const online = snapshot.phase === 'connected' && snapshot.onlineCount > 0
+    if (online && !previousOnline) {
+      cancelRestoreAndClear()
+      hideForRemote()
+    } else if (!online && previousOnline) {
+      scheduleRestore()
+    }
+    previousOnline = online
+  }
+
+  const cancelRestoreAndClear = (): void => {
+    clearRestore()
+  }
+
+  const unsubscribe = deps.onState(handle)
+  return () => {
+    disposed = true
+    unsubscribe()
+    clearRestore()
+  }
+}