dsh-plugin-mobile-link 0.2.0

package/lib/dsh-client.js

@@ -0,0 +1,280 @@
+/**
+ * Client for the *local* DSH instance.
+ *
+ * Responsibilities (spec §4.1):
+ *   1. Discover the endpoint: `$DSH_HOME/desktop-shell/endpoint.json`, then
+ *      `$DSH_WEB_URL`, then `http://127.0.0.1:54499`. The file changes on every
+ *      DSH restart, so it is re-read on every (re)connect.
+ *   2. Exchange `?token=` for a `dsh-auth-*` cookie without following the 303.
+ *      The cookie is bound to the authority, so the client always dials
+ *      `127.0.0.1:<port>` and never rewrites `Host` (see NOTES.md on spec §7).
+ *   3. Unary RPC via `POST /api/<method>` and one shared multiplexing
+ *      WebSocket at `/api/remote.mux` for every logical stream.
+ */
+
+import { EventEmitter } from 'node:events'
+import { readFile } from 'node:fs/promises'
+
+import { defaultEndpointFile, defaultShellLogFile } from './state.js'
+import { connect as wsConnect } from './ws.js'
+
+export class DshUnavailable extends Error {}
+
+const FALLBACK_PORT = 54499
+const MUX_PATH = '/api/remote.mux'
+
+function portOf(url) {
+  if (url.port) return Number(url.port)
+  return url.protocol === 'https:' ? 443 : 80
+}
+
+function parseBase(raw, { forceLoopback = true } = {}) {
+  const url = new URL(raw)
+  const port = portOf(url)
+  const host = forceLoopback ? '127.0.0.1' : url.hostname
+  const scheme = url.protocol === 'https:' ? 'https' : 'http'
+  return {
+    base: `${scheme}://${host}:${port}`,
+    wsBase: `${scheme === 'https' ? 'wss' : 'ws'}://${host}:${port}`,
+    port,
+    token: url.searchParams.get('token') || '',
+  }
+}
+
+/**
+ * Resolve where the local DSH web server lives.
+ * @returns {Promise<{base: string, wsBase: string, port: number, token: string, source: string}>}
+ */
+export async function discoverEndpoint({
+  endpointFile = defaultEndpointFile(),
+  shellLogFile = defaultShellLogFile(),
+  explicitUrl,
+} = {}) {
+  if (explicitUrl) {
+    const parsed = parseBase(explicitUrl, { forceLoopback: false })
+    parsed.source = 'config'
+    return parsed
+  }
+  try {
+    const raw = JSON.parse(await readFile(endpointFile, 'utf8'))
+    const url = typeof raw?.url === 'string' && raw.url ? raw.url : `http://127.0.0.1:${raw?.port ?? FALLBACK_PORT}`
+    const parsed = parseBase(url)
+    if (!parsed.port) parsed.port = Number(raw?.port) || FALLBACK_PORT
+    parsed.base = `http://127.0.0.1:${parsed.port}`
+    parsed.wsBase = `ws://127.0.0.1:${parsed.port}`
+    parsed.token = parsed.token || url.searchParams?.get?.('token') || ''
+    parsed.source = `endpoint.json:${endpointFile}`
+    return parsed
+  } catch {
+    /* fall through to the log, the environment and the built-in default */
+  }
+  // The handoff file can be missing while the host is very much alive: the
+  // desktop shell deletes it when it quits, and a bare `dsh web --port 0` never
+  // writes one at all. The shell's own log keeps every launch line, so the last
+  // one that still answers is the live endpoint. This is the same second source
+  // `test/tools/host.mjs` reads for the same reason.
+  try {
+    const log = await readFile(shellLogFile, 'utf8')
+    const matches = log.match(/http:\/\/127\.0\.0\.1:(\d+)\/\?token=([A-Za-z0-9_-]+)/g)
+    if (matches && matches.length) {
+      const parsed = parseBase(matches[matches.length - 1])
+      parsed.source = `dsh-shell.log:${shellLogFile}`
+      return parsed
+    }
+  } catch {
+    /* fall through to the environment and the built-in default */
+  }
+  if (process.env.DSH_WEB_URL) {
+    const parsed = parseBase(process.env.DSH_WEB_URL)
+    parsed.source = 'DSH_WEB_URL'
+    return parsed
+  }
+  const parsed = parseBase(`http://127.0.0.1:${FALLBACK_PORT}`)
+  parsed.source = 'default'
+  return parsed
+}
+
+function cookieFrom(response) {
+  const list = typeof response.headers.getSetCookie === 'function'
+    ? response.headers.getSetCookie()
+    : [response.headers.get('set-cookie')].filter(Boolean)
+  const cookies = list
+    .map((value) => String(value).split(';')[0].trim())
+    .filter((value) => value.startsWith('dsh-auth-'))
+  return cookies.join('; ')
+}
+
+export class DshClient extends EventEmitter {
+  constructor({ endpointFile, explicitUrl, logger = console, fetchImpl = fetch, connectImpl = wsConnect } = {}) {
+    super()
+    this.endpointFile = endpointFile || defaultEndpointFile()
+    this.explicitUrl = explicitUrl
+    this.logger = logger
+    this.fetchImpl = fetchImpl
+    this.connectImpl = connectImpl
+    this.endpoint = undefined
+    this.cookie = ''
+    this.mux = undefined
+    this.muxOpening = undefined
+    this.muxReady = false
+    this.pendingOpens = []
+    this.lastError = undefined
+  }
+
+  /** Re-read endpoint discovery and re-do the token -> cookie exchange. */
+  async refresh({ force = false } = {}) {
+    const endpoint = await discoverEndpoint({ endpointFile: this.endpointFile, explicitUrl: this.explicitUrl })
+    if (force || !this.endpoint || this.endpoint.base !== endpoint.base) this.cookie = ''
+    this.endpoint = endpoint
+    if (!this.cookie) await this.authenticate()
+    return this.endpoint
+  }
+
+  async authenticate() {
+    const endpoint = this.endpoint ?? await discoverEndpoint({
+      endpointFile: this.endpointFile, explicitUrl: this.explicitUrl,
+    })
+    this.endpoint = endpoint
+    if (!endpoint.token) {
+      throw new DshUnavailable(
+        `no DSH launch token found (looked at ${this.endpoint.source}); restart DSH or set dshUrl in the plugin config`,
+      )
+    }
+    const url = `${endpoint.base}/?token=${encodeURIComponent(endpoint.token)}`
+    let response
+    try {
+      response = await this.fetchImpl(url, { redirect: 'manual' })
+    } catch (error) {
+      throw new DshUnavailable(`cannot reach DSH at ${endpoint.base}: ${error instanceof Error ? error.message : error}`)
+    }
+    const cookie = cookieFrom(response)
+    if (!cookie) {
+      throw new DshUnavailable(`DSH auth handshake returned HTTP ${response.status} without a dsh-auth cookie`)
+    }
+    this.cookie = cookie
+    this.logger.debug?.(`mobile-link: authenticated with DSH at ${endpoint.base}`)
+    return cookie
+  }
+
+  async ensure() {
+    if (!this.endpoint || !this.cookie) await this.refresh()
+    return this.endpoint
+  }
+
+  /** One unary RPC. Returns the DSH `RemoteResult` object verbatim. */
+  async rpc(method, args = {}, { retry = true } = {}) {
+    await this.ensure()
+    const rpcId = `ml-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+    const body = JSON.stringify({
+      type: 'client-request',
+      rpcId,
+      method,
+      payload: { args: args ?? {} },
+    })
+    let response
+    try {
+      response = await this.fetchImpl(`${this.endpoint.base}/api/${method}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', cookie: this.cookie },
+        body,
+      })
+    } catch (error) {
+      throw new DshUnavailable(`DSH request ${method} failed: ${error instanceof Error ? error.message : error}`)
+    }
+    if (response.status === 401 && retry) {
+      this.logger.debug?.(`mobile-link: DSH session expired, re-authenticating (${method})`)
+      this.cookie = ''
+      await this.refresh({ force: true })
+      return this.rpc(method, args, { retry: false })
+    }
+    let json
+    try {
+      json = await response.json()
+    } catch {
+      return { ok: false, error: { code: 'gateway/bad-response', message: `DSH returned HTTP ${response.status}`, details: {} } }
+    }
+    if (json?.result && typeof json.result === 'object') return json.result
+    return { ok: false, error: { code: 'gateway/bad-response', message: 'DSH returned no result', details: {} } }
+  }
+
+  /** The single multiplexing socket; opened lazily and shared by every stream. */
+  async ensureMux() {
+    if (this.muxReady && this.mux && !this.mux.closed) return this.mux
+    if (this.muxOpening) return this.muxOpening
+    this.muxOpening = (async () => {
+      await this.ensure()
+      const handle = await this.connectImpl(`${this.endpoint.wsBase}${MUX_PATH}`, {
+        headers: { cookie: this.cookie },
+        timeoutMs: 20000,
+      })
+      this.mux = handle
+      this.muxReady = true
+      handle.onMessage((text) => this.#onMuxMessage(text))
+      handle.onClose((code, reason) => this.#onMuxDown(`closed (${code ?? '?'} ${reason ?? ''})`))
+      handle.onError((error) => this.logger.debug?.(`mobile-link: mux socket error: ${error?.message ?? error}`))
+      for (const frame of this.pendingOpens.splice(0)) handle.send(frame)
+      this.logger.debug?.('mobile-link: DSH mux socket open')
+      return handle
+    })()
+    try {
+      return await this.muxOpening
+    } catch (error) {
+      this.muxReady = false
+      this.mux = undefined
+      throw error
+    } finally {
+      this.muxOpening = undefined
+    }
+  }
+
+  #onMuxMessage(text) {
+    let frame
+    try {
+      frame = JSON.parse(text)
+    } catch {
+      return
+    }
+    const streamId = frame?.streamId
+    if (typeof streamId !== 'string') return
+    if (frame.type === 'item') this.emit('stream-item', streamId, frame.value)
+    else if (frame.type === 'error') this.emit('stream-error', streamId, frame.error)
+    else if (frame.type === 'end') this.emit('stream-end', streamId)
+  }
+
+  #onMuxDown(reason) {
+    if (!this.muxReady && !this.mux) return
+    this.muxReady = false
+    this.mux = undefined
+    this.logger.debug?.(`mobile-link: DSH mux socket down: ${reason}`)
+    this.emit('mux-down', reason)
+  }
+
+  openStream(muxId, endpoint, args) {
+    const text = JSON.stringify({ type: 'open', streamId: muxId, endpoint, payload: { args: args ?? {} } })
+    if (this.muxReady && this.mux && !this.mux.closed) this.mux.send(text)
+    else this.pendingOpens.push(text)
+  }
+
+  cancelStream(muxId) {
+    const needle = `"streamId":${JSON.stringify(muxId)}`
+    this.pendingOpens = this.pendingOpens.filter((text) => !text.includes(needle))
+    if (this.muxReady && this.mux && !this.mux.closed) {
+      try {
+        this.mux.send(JSON.stringify({ type: 'cancel', streamId: muxId }))
+      } catch {
+        /* socket died between checks */
+      }
+    }
+  }
+
+  close() {
+    this.muxReady = false
+    this.pendingOpens = []
+    try {
+      this.mux?.close(1000, 'agent shutdown')
+    } catch {
+      /* already closed */
+    }
+    this.mux = undefined
+  }
+}

package/lib/enroll.js

@@ -0,0 +1,142 @@
+/**
+ * First-run enrollment: turn an invite code into a durable agent identity.
+ *
+ * Until now an identity could only be provisioned by whoever owns the relay
+ * (`relay/admin.py agent-register --write-config`). That does not distribute:
+ * somebody else installs DSH plus this connector on their own computer and has
+ * to be handed a credential by the operator, out of band.
+ *
+ * So the relay grew `POST /agents/enroll` (relay/api.py), which redeems a
+ * one-time invite code for a fresh `agentId` / `agentSecret`. This module is the
+ * connector half: one call, then the identity is written to the same
+ * `~/.dsh/mobile-link/agent.json` (mode 0600) that `agent-register` writes, so
+ * nothing downstream can tell the two apart.
+ *
+ * Enrollment is deliberately *not* automatic against an open endpoint: an
+ * invite code must be present, because the relay is on the public internet.
+ */
+
+import { enrollEndpoint } from './dlp.js'
+import { DEFAULT_AGENT_NAME, INVITE_ENV, defaultStatePath, readState, writeState } from './state.js'
+
+/** Where the invite code may come from: explicit argument, then environment. */
+export function inviteFrom({ inviteCode, env = process.env } = {}) {
+  const value = typeof inviteCode === 'string' && inviteCode.trim() ? inviteCode : env?.[INVITE_ENV]
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+/**
+ * Whether an enrollment should be attempted, and with what code.
+ *
+ * Enrollment happens only when there is no identity yet; an existing identity is
+ * never replaced behind the user's back (that would silently unpair every phone
+ * they had already paired).
+ */
+export async function enrollPlan({ stateFile, inviteCode, relayUrl, env = process.env } = {}) {
+  const path = stateFile || defaultStatePath()
+  const existing = await readState(path)
+  if (existing?.agentId && existing?.agentSecret) {
+    return { needed: false, stateFile: path, agentId: existing.agentId }
+  }
+  const invite = inviteFrom({ inviteCode, env })
+  const relay = relayUrl || env?.DSH_MOBILE_LINK_RELAY || ''
+  return { needed: true, stateFile: path, invite, relayUrl: relay, canEnroll: Boolean(invite && relay) }
+}
+
+/**
+ * Redeem one invite code and persist the resulting identity.
+ *
+ * The state file is written **after** the relay has answered, and atomically, so
+ * a failure anywhere leaves whatever was there before untouched.
+ *
+ * @param {object} options
+ * @param {string} options.relayUrl relay origin, e.g. `wss://host/dsh-link`
+ * @param {string} options.inviteCode the one-time code
+ * @param {string} [options.name] what this computer is called on the phone
+ * @param {string} [options.stateFile] override, for tests and `$DSH_HOME`
+ * @param {typeof fetch} [options.fetchImpl] injectable for tests
+ * @returns {Promise<{agentId: string, agentSecret: string, agentName: string, relayUrl: string, stateFile: string}>}
+ */
+export async function enrollAgent({
+  relayUrl, inviteCode, name, stateFile, deviceName,
+  fetchImpl = fetch, logger = undefined,
+} = {}) {
+  if (!inviteCode || !String(inviteCode).trim()) {
+    throw new Error('mobile-link: an invite code is required to enroll (--invite <code>)')
+  }
+  if (!relayUrl || !String(relayUrl).trim()) {
+    throw new Error('mobile-link: a relay URL is required to enroll (--relay <url>)')
+  }
+  const path = stateFile || defaultStatePath()
+  const agentName = (name || deviceName || '').trim() || DEFAULT_AGENT_NAME
+
+  let response
+  try {
+    response = await fetchImpl(enrollEndpoint(relayUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ inviteCode: String(inviteCode).trim(), name: agentName }),
+    })
+  } catch (error) {
+    throw new Error(`mobile-link: cannot reach the relay at ${relayUrl}: ${messageOf(error)}`)
+  }
+
+  let body
+  try {
+    body = await response.json()
+  } catch {
+    throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /agents/enroll`)
+  }
+  if (!response.ok || body?.ok !== true || !body.agentId || !body.agentSecret) {
+    throw new Error(describeEnrollFailure(body, response.status))
+  }
+
+  await writeState(path, {
+    relayUrl,
+    agentId: body.agentId,
+    agentSecret: body.agentSecret,
+    agentName: body.agentName || agentName,
+  })
+  logger?.info?.(`mobile-link: enrolled as ${body.agentId} (${body.agentName || agentName})`)
+  return {
+    agentId: body.agentId,
+    agentSecret: body.agentSecret,
+    agentName: body.agentName || agentName,
+    relayUrl,
+    stateFile: path,
+  }
+}
+
+/**
+ * Turn the relay's failure into something a person can act on.
+ *
+ * The three invite failures need different advice, so the relay's error code is
+ * mapped rather than replaced by a generic message.
+ */
+export function describeEnrollFailure(body, status) {
+  const code = body?.error?.code ?? ''
+  const message = body?.error?.message
+  switch (code) {
+    case 'enroll/unknown':
+      return 'mobile-link: that invite code is not valid — check it for a typo, and that it was issued by this relay'
+    case 'enroll/used':
+      return 'mobile-link: that invite code has already been used — each code enrolls exactly one computer'
+    case 'enroll/expired':
+      return 'mobile-link: that invite code has expired — ask for a new one'
+    case 'enroll/rate-limited':
+      return 'mobile-link: too many failed attempts with that code — wait a few minutes and try again'
+    default:
+      return `mobile-link: enrollment failed (HTTP ${status})${message ? `: ${message}` : ''}`
+  }
+}
+
+/** The one-liner a fresh install runs, quoted for copy/paste. */
+export function enrollCommand(relayUrl, name = undefined) {
+  const parts = ['dsh-mobile-link enroll', `--relay ${relayUrl || '<relay-url>'}`, '--invite <code>']
+  if (name) parts.push(`--name ${JSON.stringify(name)}`)
+  return parts.join(' ')
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/lib/files.js

@@ -0,0 +1,127 @@
+/**
+ * Files the phone sends, staged on this computer.
+ *
+ * The Host has no upload endpoint — `workspaceFiles/*` is read-only and the
+ * protocol's `{type:'file', receiptId}` part needs a receipt from an
+ * `uploadFile` call that does not exist on this build. So the link carries the
+ * bytes itself and writes them where the agent can read them with its ordinary
+ * tools.
+ *
+ * The transfer rides the protocol's existing unary `req` frame, addressed to a
+ * reserved method name the connector answers locally instead of forwarding, so
+ * neither the relay nor the protocol needs to change.
+ */
+
+import { mkdirSync, writeFileSync, rmSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+
+/** Reserved method names this module answers; never forwarded to the Host. */
+export const FILE_BEGIN = '_link/fileBegin'
+export const FILE_CHUNK = '_link/fileChunk'
+export const FILE_END = '_link/fileEnd'
+
+export function isFileMethod(method) {
+  return method === FILE_BEGIN || method === FILE_CHUNK || method === FILE_END
+}
+
+/**
+ * One in-flight transfer. Chunks are appended in order and the file only
+ * appears at its final path once the end frame arrives, so a half-sent file is
+ * never mistaken for a complete one.
+ */
+class Transfer {
+  constructor({ sessionId, name, bytes }) {
+    this.sessionId = sessionId
+    this.name = basename(name || 'file')
+    this.bytes = Number.isFinite(bytes) ? bytes : undefined
+    this.parts = []
+    this.received = 0
+    this.expectedSeq = 0
+    this.directory = join(homedir(), '.dsh', 'inbox', sessionId)
+    mkdirSync(this.directory, { recursive: true, mode: 0o700 })
+    this.staging = join(this.directory, `.${this.name}.part`)
+  }
+
+  append(seq, base64) {
+    if (seq !== this.expectedSeq) {
+      throw new Error(`chunk ${seq} arrived out of order (expected ${this.expectedSeq})`)
+    }
+    const buffer = Buffer.from(base64, 'base64')
+    this.parts.push(buffer)
+    this.received += buffer.length
+    this.expectedSeq += 1
+  }
+
+  finish() {
+    const body = Buffer.concat(this.parts)
+    if (this.bytes !== undefined && body.length !== this.bytes) {
+      throw new Error(`expected ${this.bytes} bytes but received ${body.length}`)
+    }
+    writeFileSync(this.staging, body, { mode: 0o600 })
+    // Renamed only now: the final name means "complete".
+    const final = join(this.directory, this.name)
+    rmSync(final, { force: true })
+    writeFileSync(final, body, { mode: 0o600 })
+    rmSync(this.staging, { force: true })
+    return { path: final, bytes: statSync(final).size }
+  }
+
+  dispose() {
+    rmSync(this.staging, { force: true })
+  }
+}
+
+/** Owns the transfers for one connector. */
+export class FileInbox {
+  #transfers = new Map()
+  #logger
+
+  constructor(logger) {
+    this.#logger = logger
+  }
+
+  /** Answers one reserved call. Throws `Error` for the router to report. */
+  handle(method, args = {}) {
+    const transferId = String(args.transferId ?? '')
+    if (!transferId) throw new Error('transferId is required')
+
+    if (method === FILE_BEGIN) {
+      const sessionId = String(args.sessionId ?? '')
+      if (!sessionId) throw new Error('sessionId is required')
+      this.#transfers.get(transferId)?.dispose()
+      this.#transfers.set(
+        transferId,
+        new Transfer({ sessionId, name: args.name, bytes: Number(args.bytes) })
+      )
+      this.#logger.debug?.(`mobile-link: file transfer ${transferId} started for ${sessionId}`)
+      return { accepted: true }
+    }
+
+    const transfer = this.#transfers.get(transferId)
+    if (!transfer) throw new Error(`unknown transfer ${transferId}`)
+
+    if (method === FILE_CHUNK) {
+      transfer.append(Number(args.seq ?? 0), String(args.data ?? ''))
+      return { received: transfer.received }
+    }
+
+    // FILE_END
+    try {
+      const done = transfer.finish()
+      this.#logger.info?.(
+        `mobile-link: file ${transfer.name} (${done.bytes} bytes) staged at ${done.path}`
+      )
+      return done
+    } finally {
+      transfer.dispose()
+      this.#transfers.delete(transferId)
+    }
+  }
+
+  /** Drops every in-flight transfer, e.g. when the link goes down. */
+  clear() {
+    for (const transfer of this.#transfers.values()) transfer.dispose()
+    this.#transfers.clear()
+  }
+}

package/lib/hello.js

@@ -0,0 +1,65 @@
+/**
+ * What this connector is and what it can do.
+ *
+ * The connector and the app are deployed separately, so the app has to ask
+ * rather than assume. It asks over the link — a reserved method the connector
+ * answers locally — because the HTTP status route only exists on the direct
+ * path, and the direct path is not what users run.
+ *
+ * Feature detection, not version comparison: a connector that lacks a
+ * capability simply does not list it, and the app hides that entry instead of
+ * calling something that would come back as a 404 from the Host.
+ */
+
+import { createRequire } from 'node:module'
+
+/** Reserved method the app calls once per connection. */
+export const HELLO_METHOD = '_link/hello'
+
+/**
+ * The connector's own version.
+ *
+ * Read from package.json rather than written out twice: the two drifting apart
+ * is exactly the kind of thing nobody notices until a support question depends
+ * on it (they had drifted: the manifest said 0.1.0 and this said 0.2.0).
+ */
+export const SERVER_VERSION = readManifestVersion()
+
+function readManifestVersion() {
+  try {
+    const require = createRequire(import.meta.url)
+    return require('../package.json').version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+/**
+ * Capabilities the app may rely on.
+ *
+ * - `file-transfer`  files can be staged on the computer (see files.js)
+ * - `events`         the per-device `$events` stream is served
+ * - `session-streams` logical streams (`session/follow`, …) are served
+ * - `pair-code`      this connector can mint a pairing code on request
+ * - `qr-pairing`     this connector can render the pairing QR itself
+ *                    (`GET /mobile-link/qr`), so the desktop needs no client
+ * - `self-enroll`    this connector can register itself with an invite code
+ */
+export const SERVER_CAPABILITIES = [
+  'file-transfer', 'events', 'session-streams', 'pair-code', 'qr-pairing', 'self-enroll',
+]
+
+export function isHelloMethod(method) {
+  return method === HELLO_METHOD
+}
+
+/** The answer to {@link HELLO_METHOD}. */
+export function helloPayload({ protocolVersion, agentId, name } = {}) {
+  return {
+    serverVersion: SERVER_VERSION,
+    capabilities: SERVER_CAPABILITIES,
+    protocolVersion,
+    agentId: agentId ?? null,
+    name: name ?? null,
+  }
+}