dsh-plugin-mobile-link 0.2.0

package/README.md

@@ -0,0 +1,111 @@
+# dsh-plugin-mobile-link
+
+**The computer half of [DSH Mobile](https://github.com/jayantTang/DSH_Mobile): it
+dials a relay over WSS, so the native iOS client reaches this DSH instance even
+though the computer has no public IP.**
+
+```
+iPhone App ──WSS──▶ Relay（公网，只鉴权与转发）──WSS──▶ this plugin ──HTTP+WS──▶ 127.0.0.1:<port>
+```
+
+The connector always talks to the local DSH as `127.0.0.1:<port>`, so the host's
+authority and its trust fence are unaffected: no `--trusted-host`, no rewritten
+`Host`, no new listening port on this machine.
+
+```
+plugins/mobile-link/
+├── package.json          # type: module, dsh.bundle.patch, bin: dsh-mobile-link
+├── cordis.patch.yml      # bundle patch: the loader row + config reference
+├── lib/
+│   ├── index.js          # cordis plugin: starts the agent, registers 3 routes
+│   ├── link.js           # the DLP agent transport: identity, socket, heartbeat, reconnect
+│   ├── router.js         # frames ⇄ local DSH mux streams, per-device `$events`
+│   ├── dlp.js            # DLP v1 frame codec (shared with the relay)
+│   ├── files.js          # phone → computer file transfers (`_link/file*` methods)
+│   ├── enroll.js         # invite-code redemption, writes ~/.dsh/mobile-link/agent.json
+│   ├── routes.js         # GET /mobile-link/status, POST /pair-code, GET /qr
+│   ├── qr.js             # dependency-free QR SVG
+│   └── cli.js            # dsh-mobile-link: enroll / mint-pair-code
+└── test/                 # node --test, 100+ tests (no DSH, no network)
+```
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-plugin-mobile-link
+```
+
+Then restart DSH (or reload the profile). From a checkout the same command takes
+a path — the leading `./` matters, because DSH anchors a relative spec against
+your current directory instead of resolving it inside the profile:
+
+```bash
+dsh plugin --profile web add ./plugins/mobile-link
+```
+
+## Use
+
+1. Register this computer with a relay (once). Either redeem an invite code:
+
+   ```bash
+   dsh-mobile-link enroll --invite <邀请码> --relay wss://<你的站点>/dsh-link
+   ```
+
+   …or register it on the relay host with `relay/admin.py agent-register
+   --write-config ~/.dsh/mobile-link/agent.json`.
+
+2. Mint a pairing code, and show it as a QR the phone camera can read:
+
+   ```bash
+   dsh-mobile-link --mint-pair-code        # prints JSON: code + relay + agentId
+   ```
+
+   Or open `/mobile-link/qr` on the local DSH (behind DSH's own authentication).
+
+3. Scan it in the iOS app. After that the phone reconnects on its own — nothing
+   else has to be run by hand.
+
+`GET /mobile-link/status` reports whether the link is up, which devices are
+attached, and whether this computer is registered yet.
+
+## Configuration
+
+All optional; the defaults are what a stock deployment needs. Set them in the
+plugin's config block (`cordis.patch.yml`), not by editing this file.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | `false` stops the outbound link without uninstalling |
+| `relayUrl` | from `agent.json` | Relay base URL; a bare deployment dials `<relay>/link/agent` |
+| `agentId` / `agentSecret` | from `agent.json` | Override the enrolled identity |
+| `stateFile` | `~/.dsh/mobile-link/agent.json` | Where the identity lives |
+| `dshUrl` | discovery | Explicit local DSH base URL |
+| `endpointFile` | `$DSH_HOME/desktop-shell/endpoint.json` | DSH endpoint handoff file |
+| `heartbeatMs` | `20000` | DLP ping interval |
+
+Address resolution order: this config block, then `DSH_RELAY_URL` (or
+`DSH_MOBILE_LINK_RELAY`), then the enrolled identity file, then the repository
+placeholder `wss://relay.example.com/dsh-link` — the placeholder being the
+"nothing configured yet" sentinel rather than a real address.
+
+## Design notes
+
+- **No required services.** `inject` is empty and the routes are attached through
+  `ctx.inject([...])`, so a future DSH that renames or drops `webServer` /
+  `connection` cannot make the tunnel fatal on boot.
+- **Protocol-transparent.** Nothing outside `lib/` is imported and no DSH
+  business API is touched: the connector forwards frames, it does not interpret
+  sessions. The relay has the same property.
+- **Disable** by removing the row from the profile's `cordis.patch.yml`, or by
+  setting `enabled: false`.
+
+## Test
+
+```bash
+cd plugins/mobile-link && npm test    # zero dependencies
+```
+
+The wire protocol is specified in
+[`docs/RELAY-PROTOCOL.md`](https://github.com/jayantTang/DSH_Mobile/blob/main/docs/RELAY-PROTOCOL.md).
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,37 @@
+# Bundle patch for dsh-plugin-mobile-link.
+#
+# `dsh plugin --profile web add <this directory>` installs the package into the
+# profile and appends it to dsh.profile.bundles, so the row below joins the tree
+# on every boot with no hand-edited block in the profile's own cordis.patch.yml.
+#
+# `name` is anchored relative to this file (DSH rewrites ./ paths to file URLs),
+# so the plugin keeps resolving wherever the profile lives.
+#
+# Config reference (all optional; the defaults are what a stock deployment
+# needs):
+#   enabled        false disables the outbound link without uninstalling
+#   relayUrl       DLP relay base URL. The relay is published under a path prefix
+#                  on an existing site, so a bare deployment dials
+#                  <relay>/link/agent. The configured path is always kept, never
+#                  replaced. ws:// is accepted for local testing (e.g.
+#                  ws://127.0.0.1:8787). Left unset here on purpose: a value
+#                  pinned in this file outranks both DSH_RELAY_URL and the
+#                  address already enrolled in ~/.dsh/mobile-link/agent.json.
+#   agentId        overrides ~/.dsh/mobile-link/agent.json
+#   agentSecret    overrides ~/.dsh/mobile-link/agent.json
+#   stateFile      agent identity file (default ~/.dsh/mobile-link/agent.json)
+#   dshUrl         explicit local DSH base URL override (default: discovery)
+#   endpointFile   DSH endpoint handoff file (default $DSH_HOME/desktop-shell/endpoint.json)
+#
+# Address resolution order: this config block, then DSH_RELAY_URL (or
+# DSH_MOBILE_LINK_RELAY), then the enrolled identity file, then the repository
+# placeholder wss://relay.example.com/dsh-link — the placeholder being the
+# "nothing configured yet" sentinel rather than a real address.
+
+- insert:
+    - id: mobile-link
+      name: './lib/index.js'
+      config:
+        enabled: true
+        heartbeatMs: 20000
+        reconnect: true

package/lib/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Standalone runner for the DLP agent, outside DSH.
+ *
+ * The cordis plugin is the normal entry point; this CLI exists so the agent can
+ * be exercised (and the whole middle tier integration-tested) without booting a
+ * DSH profile:
+ *
+ *   node lib/cli.js --relay ws://127.0.0.1:8787 \
+ *     --agent-id agt_x --agent-secret as_y --status-file /tmp/mobile-link.json
+ *
+ * It prints one machine-readable line per connection state change:
+ *   MOBILE_LINK_STATE {"state":"connected", ...}
+ *
+ * `--mint-pair-code` skips the link entirely and just asks the relay for a
+ * pairing code (plus its `dsh://pair?...` payload) through the same
+ * prefix-preserving URL join the live agent uses.
+ *
+ * `enroll` is the first-run path for someone else's computer: it redeems an
+ * invite code for an identity and writes `~/.dsh/mobile-link/agent.json`, then
+ * exits. Everything after that is the ordinary agent.
+ */
+
+import { rename, writeFile } from 'node:fs/promises'
+
+import { enrollAgent, inviteFrom } from './enroll.js'
+import { MobileLinkAgent } from './link.js'
+import { mintPairCode } from './pairing.js'
+import { INVITE_ENV, defaultStatePath, resolveIdentity } from './state.js'
+
+/** Atomic status snapshot so readers never observe a half-written file. */
+async function writeJsonAtomic(path, value) {
+  const temporary = `${path}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+  await rename(temporary, path)
+}
+
+function parseArgs(argv) {
+  const args = { _: [] }
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+    if (!token.startsWith('--')) {
+      args._.push(token)
+      continue
+    }
+    const eq = token.indexOf('=')
+    const key = (eq === -1 ? token.slice(2) : token.slice(2, eq)).replace(/-([a-z])/g, (_m, c) => c.toUpperCase())
+    if (eq !== -1) {
+      args[key] = token.slice(eq + 1)
+    } else if (argv[index + 1] !== undefined && !argv[index + 1].startsWith('--')) {
+      args[key] = argv[index + 1]
+      index += 1
+    } else {
+      args[key] = true
+    }
+  }
+  return args
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    process.stdout.write(`usage: cli.js enroll --invite <code> [--relay <ws url>] [--name <label>]
+  Redeem a one-time invite code for an identity in ${defaultStatePath()}.
+  The invite may also arrive as ${INVITE_ENV}. Exits non-zero on failure.
+
+  cli.js --relay <ws url> --agent-id <id> --agent-secret <secret>
+  [--state-file <path>] [--dsh-url <url>] [--endpoint-file <path>]
+  [--status-file <path>] [--heartbeat-ms <n>] [--log-level debug|info|warn]
+
+  cli.js --mint-pair-code --relay <ws url> --agent-id <id> --agent-secret <secret>
+  [--ttl-ms <n>]     print one pairing code as JSON and exit
+`)
+    return 0
+  }
+
+  if (args._[0] === 'enroll' || args.enroll) {
+    const explicit = typeof args.enroll === 'string' ? args.enroll : undefined
+    const settled = await enrollAgent({
+      relayUrl: args.relay,
+      inviteCode: inviteFrom({ inviteCode: explicit ?? args.invite }),
+      name: args.name,
+      stateFile: typeof args.stateFile === 'string' ? args.stateFile : undefined,
+    })
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      agentId: settled.agentId,
+      agentName: settled.agentName,
+      relayUrl: settled.relayUrl,
+      stateFile: settled.stateFile,
+    }, null, 2)}\n`)
+    process.stdout.write('这台电脑已登记。重启 DSH 后连接器会使用新的身份。\n')
+    return 0
+  }
+
+  if (args.mintPairCode) {
+    const identity = await resolveIdentity({
+      stateFile: typeof args.stateFile === 'string' ? args.stateFile : undefined,
+      agentId: args.agentId,
+      agentSecret: args.agentSecret,
+      relayUrl: args.relay,
+    })
+    const minted = await mintPairCode({
+      identity,
+      ttlMs: Number(args.ttlMs) || 10 * 60 * 1000,
+    })
+    process.stdout.write(`${JSON.stringify(minted, null, 2)}\n`)
+    return 0
+  }
+
+  const level = String(args.logLevel ?? process.env.DSH_MOBILE_LINK_LOG ?? 'info')
+  const enabledLevels = level === 'debug' ? ['debug', 'info', 'warn', 'error'] : ['info', 'warn', 'error']
+  const write = (stream, prefix) => (...parts) => {
+    stream.write(`${prefix} ${parts.map(String).join(' ')}\n`)
+  }
+  const logger = {
+    debug: enabledLevels.includes('debug') ? write(process.stdout, '[debug]') : () => {},
+    info: write(process.stdout, '[info]'),
+    warn: write(process.stderr, '[warn]'),
+    error: write(process.stderr, '[error]'),
+  }
+
+  const agent = new MobileLinkAgent({
+    relayUrl: args.relay,
+    agentId: args.agentId,
+    agentSecret: args.agentSecret,
+    stateFile: typeof args.stateFile === 'string' ? args.stateFile : undefined,
+    dshUrl: typeof args.dshUrl === 'string' ? args.dshUrl : undefined,
+    endpointFile: typeof args.endpointFile === 'string' ? args.endpointFile : undefined,
+    heartbeatMs: Number(args.heartbeatMs) || 20000,
+    logger,
+  })
+
+  let previous = ''
+  agent.on('status', () => {
+    const status = agent.status()
+    const stamp = JSON.stringify(status)
+    if (stamp === previous) return
+    previous = stamp
+    if (args.statusFile) {
+      void writeJsonAtomic(String(args.statusFile), status).catch(() => {})
+    }
+    process.stdout.write(`MOBILE_LINK_STATE ${JSON.stringify({
+      state: status.state,
+      connected: status.connected,
+      agentId: status.agentId,
+      relayUrl: status.relayUrl,
+      deviceCount: status.deviceCount,
+      lastError: status.lastError,
+    })}\n`)
+  })
+
+  const shutdown = async (signal) => {
+    logger.info(`received ${signal}, stopping`)
+    await agent.stop()
+    process.exit(0)
+  }
+  process.on('SIGINT', () => void shutdown('SIGINT'))
+  process.on('SIGTERM', () => void shutdown('SIGTERM'))
+
+  await agent.start()
+  if (args.once) {
+    if (agent.state !== 'connected') {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, Number(args.onceMs) || 5000)
+        agent.on('status', () => {
+          if (agent.state === 'connected') {
+            clearTimeout(timer)
+            resolve()
+          }
+        })
+      })
+    }
+    const connected = agent.state === 'connected'
+    await agent.stop()
+    return connected ? 0 : 1
+  }
+  // Keep the process alive until a signal arrives.
+  await new Promise(() => {})
+  return 0
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code
+  },
+  (error) => {
+    process.stderr.write(`mobile-link: fatal: ${error instanceof Error ? error.stack : error}\n`)
+    process.exitCode = 1
+  },
+)

package/lib/dlp.js

@@ -0,0 +1,296 @@
+/**
+ * Pure DLP v1 helpers: frame codec, stream-id mapping, waterfall dedupe and
+ * reconnect backoff. No sockets, no timers, no filesystem — everything here is
+ * driven by `node --test` without a DSH instance.
+ *
+ * Wire contract: docs/RELAY-PROTOCOL.md §3.
+ */
+
+/** Frame ceiling aligned with DSH's image-attachment limit (spec §5). */
+export const MAX_FRAME_BYTES = 32 * 1024 * 1024
+
+export const DEVICE_TO_AGENT = new Set(['req', 'open', 'cancel', 'eventResult', 'ping', 'hello'])
+export const AGENT_TO_DEVICE = new Set(['res', 'item', 'end', 'streamError', 'event', 'hostStatus', 'pong', 'error'])
+/** Relay-internal control frames carrying device lifecycle (see relay/NOTES.md). */
+export const RELAY_CONTROL = new Set(['deviceAttach', 'deviceDetach'])
+
+const ID_FRAMES = new Set(['req', 'open', 'cancel', 'res', 'item', 'end', 'streamError', 'eventResult'])
+
+export function encodeFrame(frame) {
+  return JSON.stringify(frame)
+}
+
+/**
+ * Decode one wire payload.
+ * @returns the frame object, or `undefined` when the payload is unusable
+ *          (not JSON, not an object, or missing a non-empty string `t`).
+ */
+export function decodeFrame(raw) {
+  if (typeof raw !== 'string') return undefined
+  if (raw.length > MAX_FRAME_BYTES) return undefined
+  let value
+  try {
+    value = JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  if (typeof value.t !== 'string' || value.t.length === 0) return undefined
+  return value
+}
+
+export function frameType(frame) {
+  return typeof frame?.t === 'string' ? frame.t : ''
+}
+
+/** Structural check for one device -> agent frame; returns an error string or undefined. */
+export function deviceFrameError(frame) {
+  const kind = frameType(frame)
+  if (!DEVICE_TO_AGENT.has(kind)) return undefined
+  if (ID_FRAMES.has(kind) && !nonEmptyString(frame.id)) return `${kind}: missing \`id\``
+  if (kind === 'req' && !nonEmptyString(frame.method)) return 'req: missing `method`'
+  if (kind === 'open' && !nonEmptyString(frame.endpoint)) return 'open: missing `endpoint`'
+  return undefined
+}
+
+export function nonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+export function deviceIdOf(frame) {
+  return nonEmptyString(frame?.deviceId) ? frame.deviceId : undefined
+}
+
+/**
+ * Exponential backoff with ±jitter, capped (spec §4.2: 1s -> 2s -> ... -> 30s ±20%).
+ * @param attempt zero-based retry index.
+ */
+export function nextBackoff(attempt, { baseMs = 1000, maxMs = 30000, jitter = 0.2, random = Math.random } = {}) {
+  const exponent = Math.max(0, Math.min(30, Number(attempt) || 0))
+  const raw = Math.min(maxMs, baseMs * 2 ** exponent)
+  const spread = raw * jitter
+  const offset = (random() * 2 - 1) * spread
+  return Math.max(0, Math.round(raw + offset))
+}
+
+/**
+ * Split a relay URL into its HTTP and WebSocket bases, keeping the path prefix.
+ *
+ * The relay is published under a path on an existing site, so the configured
+ * base carries a prefix (`wss://relay.example.com/dsh-link`) that must be
+ * *kept* when an endpoint is appended — never replaced. A trailing slash is
+ * tolerated and normalised away. Accepts `wss://host`, `https://host/prefix`,
+ * `ws://127.0.0.1:8787` and bare hosts.
+ */
+export function normalizeRelayUrl(raw) {
+  const text = String(raw ?? '').trim()
+  if (!text) throw new Error('relay URL is required')
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `wss://${text}`
+  const url = new URL(withScheme)
+  const secure = url.protocol === 'wss:' || url.protocol === 'https:'
+  if (!['ws:', 'wss:', 'http:', 'https:'].includes(url.protocol)) {
+    throw new Error(`unsupported relay scheme ${url.protocol}`)
+  }
+  const authority = `${url.host}`
+  const basePath = url.pathname.replace(/\/+$/, '')
+  return {
+    httpBase: `${secure ? 'https' : 'http'}://${authority}${basePath}`,
+    wsBase: `${secure ? 'wss' : 'ws'}://${authority}${basePath}`,
+    secure,
+    authority,
+  }
+}
+
+/**
+ * The relay address the repository ships as a placeholder.
+ *
+ * It is a *sentinel*, not a deployment: a value equal to it means "no relay has
+ * been configured here", never "dial relay.example.com". The distinction is
+ * load-bearing — a configured placeholder used to outrank the identity already
+ * enrolled in `agent.json`, so one DSH restart pointed an enrolled computer at
+ * the placeholder *and* wrote that back over the real address, which left the
+ * phone unable to connect until somebody noticed. Anything that resolves an
+ * address has to recognise the sentinel.
+ */
+export const PLACEHOLDER_RELAY_URL = 'wss://relay.example.com/dsh-link'
+
+/**
+ * True when `raw` is, or normalises to, the repository placeholder — a trailing
+ * slash or an `https://` spelling of the same address still counts.
+ */
+export function isPlaceholderRelayUrl(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return false
+  try {
+    return normalizeRelayUrl(raw).wsBase === normalizeRelayUrl(PLACEHOLDER_RELAY_URL).wsBase
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Join one endpoint onto a relay base without losing the base's path prefix.
+ * `('wss://host/prefix/', '/link/agent')` -> `'wss://host/prefix/link/agent'`.
+ */
+export function joinRelayPath(base, suffix) {
+  const head = String(base ?? '').replace(/\/+$/, '')
+  const tail = String(suffix ?? '').replace(/^\/+/, '')
+  return `${head}/${tail}`
+}
+
+/** The connector's relay endpoint, keeping any configured path prefix. */
+export function agentEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).wsBase, 'link/agent')
+}
+
+/** The relay's pairing-code endpoint, keeping any configured path prefix. */
+export function pairCodeEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'pair/code')
+}
+
+/** The relay's self-service enrollment endpoint (`POST /agents/enroll`). */
+export function enrollEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'agents/enroll')
+}
+
+/**
+ * The `dsh://pair?relay=<relay>&code=<code>` deep link the desktop shows and
+ * the iOS app scans. `relay` keeps the full path prefix so the phone can reach
+ * `/pair/claim` and `/link/device` under exactly the same base.
+ */
+export function qrPayload({ relay, code }) {
+  const params = new URLSearchParams({ relay: String(relay), code: String(code) })
+  return `dsh://pair?${params.toString()}`
+}
+
+/**
+ * DLP id <-> mux streamId mapping. One mux stream per (device, DLP stream) so
+ * two devices can both call their stream `"2"` without colliding.
+ */
+export class StreamTable {
+  constructor() {
+    /** @type {Map<string, {deviceId: string, dlpId: string, muxId: string, endpoint: string}>} */
+    this.byMux = new Map()
+    /** @type {Map<string, string>} `${deviceId}\u0000${dlpId}` -> muxId */
+    this.byDlp = new Map()
+  }
+
+  static key(deviceId, dlpId) {
+    return `${deviceId}\u0000${dlpId}`
+  }
+
+  /** @returns {boolean} false when this device already owns that DLP id. */
+  add({ deviceId, dlpId, muxId, endpoint }) {
+    if (this.byDlp.has(StreamTable.key(deviceId, dlpId))) return false
+    this.byMux.set(muxId, { deviceId, dlpId, muxId, endpoint })
+    this.byDlp.set(StreamTable.key(deviceId, dlpId), muxId)
+    return true
+  }
+
+  muxOf(deviceId, dlpId) {
+    return this.byDlp.get(StreamTable.key(deviceId, dlpId))
+  }
+
+  entryOfMux(muxId) {
+    return this.byMux.get(muxId)
+  }
+
+  /** Remove one (device, DLP) pair; returns its mux streamId when it existed. */
+  removeByDlp(deviceId, dlpId) {
+    const key = StreamTable.key(deviceId, dlpId)
+    const muxId = this.byDlp.get(key)
+    if (muxId === undefined) return undefined
+    this.byDlp.delete(key)
+    this.byMux.delete(muxId)
+    return muxId
+  }
+
+  /** Remove one mux stream; returns its entry when it existed. */
+  removeByMux(muxId) {
+    const entry = this.byMux.get(muxId)
+    if (entry === undefined) return undefined
+    this.byMux.delete(muxId)
+    this.byDlp.delete(StreamTable.key(entry.deviceId, entry.dlpId))
+    return entry
+  }
+
+  /** Every mux streamId owned by one device (used when it disconnects). */
+  removeDevice(deviceId) {
+    const removed = []
+    for (const entry of [...this.byMux.values()]) {
+      if (entry.deviceId === deviceId) {
+        removed.push(entry.muxId)
+        this.byMux.delete(entry.muxId)
+        this.byDlp.delete(StreamTable.key(entry.deviceId, entry.dlpId))
+      }
+    }
+    return removed
+  }
+
+  get size() {
+    return this.byMux.size
+  }
+}
+
+/**
+ * First-answer-wins bookkeeping for `$events` waterfalls (spec §4.1.6).
+ *
+ * `claim` reserves an event synchronously so two devices answering at the same
+ * moment cannot both reach `$events/result`; `release` hands it back when the
+ * reservation failed to produce a delivered answer.
+ */
+export class WaterfallDedupe {
+  constructor({ ttlMs = 5 * 60 * 1000, now = Date.now } = {}) {
+    this.ttlMs = ttlMs
+    this.now = now
+    /** @type {Map<string, number>} eventId -> claimedAt */
+    this.claimed = new Map()
+  }
+
+  /** @returns {boolean} true when this caller won the right to answer. */
+  claim(eventId) {
+    if (!nonEmptyString(eventId)) return false
+    this.prune()
+    if (this.claimed.has(eventId)) return false
+    this.claimed.set(eventId, this.now())
+    return true
+  }
+
+  release(eventId) {
+    this.claimed.delete(eventId)
+  }
+
+  has(eventId) {
+    return this.claimed.has(eventId)
+  }
+
+  prune(at = this.now()) {
+    for (const [eventId, claimedAt] of this.claimed) {
+      if (at - claimedAt > this.ttlMs) this.claimed.delete(eventId)
+    }
+  }
+
+  get size() {
+    return this.claimed.size
+  }
+}
+
+/** `{t:'pong', ts}` for a device/relay heartbeat, preserving `ts` verbatim. */
+export function pongFor(frame) {
+  return { t: 'pong', ts: frame?.ts }
+}
+
+/** `{t:'res', ...}` mapped from a DSH `RemoteResult` (`{ok,value}|{ok:false,error}`). */
+export function resultFrame(dlpId, result, deviceId) {
+  const base = { t: 'res', id: dlpId, deviceId }
+  if (result && result.ok === true) return { ...base, ok: true, value: result.value }
+  const error = result?.error
+  return {
+    ...base,
+    ok: false,
+    error: {
+      code: nonEmptyString(error?.code) ? error.code : 'gateway/failed',
+      message: nonEmptyString(error?.message) ? error.message : 'DSH request failed',
+      details: error && typeof error.details === 'object' && error.details !== null ? error.details : {},
+    },
+  }
+}