dsh-plugin-mobile-link 0.2.0

package/lib/state.js

@@ -0,0 +1,148 @@
+/**
+ * Agent identity persistence: `~/.dsh/mobile-link/agent.json`, mode 0600.
+ *
+ * The file holds the long-lived `agentId` / `agentSecret` for this computer.
+ * There are two ways it gets there, and they are deliberately indistinguishable
+ * afterwards: the relay operator provisions it by hand (relay/admin.py
+ * `agent-register --write-config`), or the person running the computer redeems
+ * an invite code themselves (`dsh-mobile-link enroll`, see enroll.js).
+ * Environment variables and the plugin config block override the file, which is
+ * how the integration test injects a throwaway identity.
+ */
+
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { isPlaceholderRelayUrl } from './dlp.js'
+
+/**
+ * Raised when no identity exists yet — a *setup* state, not a failure.
+ *
+ * The live agent treats it differently from a transport error: retrying a
+ * missing credential forever would be noise, and the fix is a person running
+ * one command, not a reconnect.
+ */
+export class MissingIdentity extends Error {
+  constructor(message, { stateFile } = {}) {
+    super(message)
+    this.name = 'MissingIdentity'
+    this.stateFile = stateFile
+  }
+}
+
+/** The environment variable a packaged install can pre-seed with an invite. */
+export const INVITE_ENV = 'DSH_MOBILE_LINK_INVITE'
+
+/** What a computer calls itself before its owner renames it. */
+export const DEFAULT_AGENT_NAME = 'My computer'
+
+export function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
+
+export function defaultStatePath() {
+  return join(dshHome(), 'mobile-link', 'agent.json')
+}
+
+export function defaultEndpointFile() {
+  return join(dshHome(), 'desktop-shell', 'endpoint.json')
+}
+
+/**
+ * The desktop shell's log, which is the *second* place the live endpoint can be
+ * read from.
+ *
+ * The shell writes `endpoint.json` as a handoff, but it also removes it again
+ * (observed after the shell quit and re-attached to an already running `dsh
+ * web`), and a machine whose host was started as a bare `dsh web --port 0` only
+ * ever sees the URL printed into this log. Both spellings appear here, so the
+ * log is a usable last resort — without it the connector sits at the default
+ * port with no launch token and every phone request fails.
+ */
+export function defaultShellLogFile() {
+  return join(dshHome(), 'desktop-shell', 'dsh-shell.log')
+}
+
+/** @returns {Promise<Record<string, unknown> | undefined>} */
+export async function readState(path) {
+  try {
+    const raw = JSON.parse(await readFile(path, 'utf8'))
+    return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Write the identity atomically and with mode 0600. */
+export async function writeState(path, state) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+  await rename(temporary, path)
+  await chmod(path, 0o600).catch(() => {})
+  return path
+}
+
+/**
+ * Resolve the effective identity from (in order) explicit config, the
+ * environment, then the state file. Secrets are never logged.
+ *
+ * One exception to that order: the repository's placeholder relay address (see
+ * `PLACEHOLDER_RELAY_URL`) counts as *unset*, so an address already enrolled in
+ * the state file outranks it. Without this, the placeholder — which ships in the
+ * plugin config and is what an unconfigured environment falls back to — would
+ * beat the real address of a computer that is already enrolled, and the next
+ * restart would both dial the placeholder and overwrite the file with it.
+ *
+ * When the identity comes from config or the environment (rather than the file)
+ * and differs from what is on disk, it is persisted to `stateFile` with mode
+ * 0600 — that is how a fresh install turns a pasted config into the durable
+ * `~/.dsh/mobile-link/agent.json` the spec calls for. A read-only home
+ * directory is not fatal: the in-memory identity is still returned.
+ */
+export async function resolveIdentity({ stateFile, agentId, agentSecret, relayUrl } = {}) {
+  const path = stateFile || defaultStatePath()
+  const file = await readState(path)
+  const configured = relayUrl || process.env.DSH_MOBILE_LINK_RELAY || ''
+  const resolved = {
+    stateFile: path,
+    relayUrl: isPlaceholderRelayUrl(configured) ? (file?.relayUrl || configured) : (configured || file?.relayUrl || ''),
+    agentId: agentId || process.env.DSH_MOBILE_LINK_AGENT_ID || file?.agentId || '',
+    agentSecret: agentSecret || process.env.DSH_MOBILE_LINK_AGENT_SECRET || file?.agentSecret || '',
+    agentName: file?.agentName || '',
+    exists: Boolean(file),
+  }
+  if (!resolved.agentId || !resolved.agentSecret) {
+    throw new MissingIdentity(
+      `mobile-link: this computer is not registered yet. Run "dsh-mobile-link enroll`
+      + ` --invite <code> --relay <relay-url>" with the invite code you were given, or set`
+      + ` ${INVITE_ENV} and restart DSH. (Provisioning by hand is still possible:`
+      + ` "python3 relay/admin.py agent-register --account <acc> --name <name>`
+      + ` --write-config ${path}".)`,
+      { stateFile: path },
+    )
+  }
+  if (!resolved.relayUrl) throw new Error('mobile-link: no relay URL configured')
+
+  const stale = !file
+    || file.agentId !== resolved.agentId
+    || file.agentSecret !== resolved.agentSecret
+    || file.relayUrl !== resolved.relayUrl
+  if (stale) {
+    try {
+      await writeState(path, {
+        relayUrl: resolved.relayUrl,
+        agentId: resolved.agentId,
+        agentSecret: resolved.agentSecret,
+        ...(resolved.agentName ? { agentName: resolved.agentName } : {}),
+      })
+      resolved.exists = true
+      resolved.persisted = true
+    } catch (error) {
+      resolved.persisted = false
+      resolved.persistError = error instanceof Error ? error.message : String(error)
+    }
+  }
+  return resolved
+}

package/lib/ws.js

@@ -0,0 +1,183 @@
+/**
+ * A tiny WebSocket adapter.
+ *
+ * DSH runs on modern Node, where `globalThis.WebSocket` exists and accepts a
+ * non-standard `{ headers }` option — that is what carries the DLP bearer token
+ * without putting it in the URL. When the global is missing we fall back to the
+ * `ws` package resolved from the DSH install. Everything above this file only
+ * sees `send` / `close` / `onMessage` / `onClose` / `onError`, so a future
+ * transport swap stays local.
+ */
+
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+export class SocketError extends Error {}
+
+let cachedFactory
+
+function candidateAnchors() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const anchors = [import.meta.url]
+  anchors.push(join(home, 'profiles', 'web', 'package.json'))
+  anchors.push(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'))
+  if (process.argv[1]) anchors.push(process.argv[1])
+  return anchors
+}
+
+/** Resolve a WebSocket constructor, or throw with an actionable message. */
+export function resolveWebSocket() {
+  if (cachedFactory) return cachedFactory
+  if (typeof globalThis.WebSocket === 'function') {
+    cachedFactory = globalThis.WebSocket
+    return cachedFactory
+  }
+  for (const anchor of candidateAnchors()) {
+    try {
+      const require = createRequire(anchor)
+      const loaded = require('ws')
+      const Ctor = loaded?.WebSocket ?? loaded
+      if (typeof Ctor === 'function') {
+        cachedFactory = Ctor
+        return cachedFactory
+      }
+    } catch {
+      /* try the next anchor */
+    }
+  }
+  throw new SocketError(
+    'no WebSocket implementation available: DSH mobile-link needs Node >= 22 (global WebSocket) or the `ws` package',
+  )
+}
+
+function isEventTargetStyle(socket) {
+  return typeof socket.addEventListener === 'function' && typeof socket.removeEventListener === 'function'
+}
+
+export class WebSocketHandle {
+  constructor(socket) {
+    this.socket = socket
+    this.closed = false
+    this.closeCode = undefined
+    this.closeReason = undefined
+    this._messageHandlers = []
+    this._closeHandlers = []
+    this._errorHandlers = []
+    this._opened = new Promise((resolve, reject) => {
+      this._resolveOpen = resolve
+      this._rejectOpen = reject
+    })
+    this._opened.catch(() => {})
+    this._attach()
+  }
+
+  _attach() {
+    const socket = this.socket
+    if (isEventTargetStyle(socket)) {
+      socket.addEventListener('open', () => this._resolveOpen())
+      socket.addEventListener('message', (event) => {
+        const data = event?.data
+        if (typeof data === 'string') this._emitMessage(data)
+        else if (data instanceof ArrayBuffer) this._emitMessage(Buffer.from(data).toString('utf8'))
+        else if (ArrayBuffer.isView(data)) this._emitMessage(Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8'))
+        else this._emitMessage(undefined, true)
+      })
+      socket.addEventListener('close', (event) => this._finish(event?.code, event?.reason))
+      socket.addEventListener('error', (event) => this._emitError(event?.error ?? new SocketError('websocket error')))
+      return
+    }
+    socket.on('open', () => this._resolveOpen())
+    socket.on('message', (data, isBinary) => {
+      if (isBinary) this._emitMessage(undefined, true)
+      else if (typeof data === 'string') this._emitMessage(data)
+      else this._emitMessage(Buffer.from(data).toString('utf8'))
+    })
+    socket.on('close', (code, reason) => this._finish(code, reason === undefined ? undefined : String(reason)))
+    socket.on('error', (error) => this._emitError(error instanceof Error ? error : new SocketError(String(error))))
+    socket.on('unexpected-response', (_request, response) => {
+      this._emitError(new SocketError(`relay rejected the upgrade with HTTP ${response?.statusCode}`))
+    })
+  }
+
+  _emitMessage(text, binary = false) {
+    for (const handler of [...this._messageHandlers]) {
+      try {
+        handler(text, binary)
+      } catch {
+        /* a handler must never break the socket loop */
+      }
+    }
+  }
+
+  _emitError(error) {
+    for (const handler of [...this._errorHandlers]) handler(error)
+    this._rejectOpen(error)
+  }
+
+  _finish(code, reason) {
+    if (this.closed) return
+    this.closed = true
+    this.closeCode = code
+    this.closeReason = reason
+    this._rejectOpen(new SocketError(`websocket closed before opening (${code ?? 'unknown'})`))
+    for (const handler of [...this._closeHandlers]) handler(code, reason)
+  }
+
+  /** @returns {Promise<void>} resolves once the upgrade completed. */
+  opened(timeoutMs = 20000) {
+    if (timeoutMs <= 0) return this._opened
+    return Promise.race([
+      this._opened,
+      new Promise((_resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new SocketError(`websocket did not open within ${timeoutMs}ms`)),
+          timeoutMs,
+        )
+        timer.unref?.()
+        this._opened.then(() => clearTimeout(timer), () => clearTimeout(timer))
+      }),
+    ])
+  }
+
+  onMessage(handler) {
+    this._messageHandlers.push(handler)
+  }
+
+  onClose(handler) {
+    this._closeHandlers.push(handler)
+  }
+
+  onError(handler) {
+    this._errorHandlers.push(handler)
+  }
+
+  send(text) {
+    if (this.closed) throw new SocketError('websocket is closed')
+    this.socket.send(text)
+  }
+
+  close(code = 1000, reason = '') {
+    this.closed = true
+    try {
+      this.socket.close(code, reason)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Open a WebSocket and resolve once it is usable. */
+export async function connect(url, { headers = {}, timeoutMs = 20000, impl } = {}) {
+  const factory = impl ?? resolveWebSocket()
+  let socket
+  try {
+    socket = new factory(url, { headers })
+  } catch (error) {
+    throw new SocketError(`cannot open ${url}: ${error instanceof Error ? error.message : error}`)
+  }
+  const handle = new WebSocketHandle(socket)
+  await handle.opened(timeoutMs)
+  return handle
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "dsh-plugin-mobile-link",
+  "version": "0.2.0",
+  "description": "Put your PC's DeepSeek Harness in your pocket: dials a relay over WSS so the native iOS client reaches this machine even without a public IP.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "remote",
+    "relay",
+    "ios",
+    "mobile",
+    "websocket"
+  ],
+  "license": "MIT",
+  "author": "jayantTang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayantTang/DSH_Mobile.git",
+    "directory": "plugins/mobile-link"
+  },
+  "homepage": "https://github.com/jayantTang/DSH_Mobile#readme",
+  "bugs": {
+    "url": "https://github.com/jayantTang/DSH_Mobile/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "dsh-mobile-link": "lib/cli.js"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./dlp": "./lib/dlp.js",
+    "./link": "./lib/link.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}