@kinocode/dsh-mobile-bridge 0.0.0-stage → 0.3.2

package/lib/control.mjs

@@ -0,0 +1,226 @@
+// Control API served to registered phones, directly on the gateway or through the relay tunnel
+// (docs/PROTOCOL.md v2 §2-§3).
+
+import { AuthError, parseDevicePublicKey, verifySignedRequest } from './auth.mjs'
+import { describe, validateAnswer } from './preview.mjs'
+import { summaryTitle } from './sessions.mjs'
+import { MAX_WATCHES_PER_DEVICE } from './state.mjs'
+
+const MAX_BODY_BYTES = 64 * 1024
+const PATH = /^\/v1\/[a-z0-9/-]{1,64}$/
+const FCM_TOKEN = /^[A-Za-z0-9_:\-.]{20,4096}$/
+const SESSION_ID = /^[A-Za-z0-9_:.-]{1,200}$/
+
+/**
+ * @typedef {object} ControlDeps
+ * @property {import('./state.mjs').StateStore} state
+ * @property {import('./auth.mjs').NonceCache} nonces
+ * @property {import('./auth.mjs').RegistrationCodes} codes
+ * @property {import('./gateway-client.mjs').GatewayClient} gateway
+ * @property {import('./sessions.mjs').SessionTracker} sessions
+ * @property {import('./web-sessions.mjs').WebSessions} webSessions
+ * @property {() => string[]} origins - gateway origins
+ * @property {string} relayUrl
+ * @property {() => Promise<Array<{sessionId: string, running: boolean, updatedAt: number, cwd?: string, parentSessionId?: string, origin?: string, projections?: {values?: Record<string, any>}}>>} listSessions
+ * @property {(eventId: string, deviceId: string) => void} [onAnswered]
+ * @property {string} hostLabel
+ * @property {string} version
+ * @property {number} previewMaxChars
+ * @property {() => number} [now]
+ * @property {(...args: unknown[]) => void} log
+ */
+
+/**
+ * @param {ControlDeps} deps
+ * @returns {{handle: (request: {method: string, path: string, headers: Record<string, string>, body: string, direct?: boolean}) => Promise<{status: number, body: unknown}>, pair: (body: string) => Promise<{status: number, body: unknown}>}}
+ */
+export function createControlHandler(deps) {
+  const now = deps.now ?? Date.now
+
+  async function handle(request) {
+    try {
+      const method = String(request.method).toUpperCase()
+      const path = String(request.path)
+      if (!PATH.test(path)) throw new AuthError(404, 'not_found')
+      if (Buffer.byteLength(request.body ?? '', 'utf8') > MAX_BODY_BYTES) throw new AuthError(413, 'payload_too_large')
+      const headers = lowerCaseHeaders(request.headers)
+
+      const deviceId = verifySignedRequest({
+        method,
+        path,
+        headers,
+        body: request.body ?? '',
+        hostId: deps.state.hostId,
+        lookup: id => deps.state.device(id),
+        nonces: deps.nonces,
+        now,
+      })
+      deps.state.updateDevice(deviceId, (record) => { record.lastSeenAt = now() })
+
+      if (method === 'POST' && path === '/v1/session') {
+        // WebView sessions are only handed out on the gateway itself, never through the relay.
+        if (request.direct !== true) throw new AuthError(404, 'not_found')
+        return ok(deps.webSessions.create(deviceId))
+      }
+      if (method === 'GET' && path === '/v1/status') return ok(status(deviceId))
+      if (method === 'GET' && path === '/v1/pending') return ok({ items: deps.gateway.list().map(p => describe(p, deps.sessions, deps.previewMaxChars)) })
+      if (method === 'POST' && path === '/v1/answer') return await answer(deviceId, parseJson(request.body))
+      if (method === 'POST' && path === '/v1/watch') return watch(deviceId, parseJson(request.body))
+      if (method === 'POST' && path === '/v1/settings') return settings(deviceId, parseJson(request.body))
+      if (method === 'GET' && path === '/v1/sessions') return ok({ items: await sessionList() })
+      if (method === 'POST' && path === '/v1/unregister') {
+        deps.state.removeDevice(deviceId)
+        deps.webSessions.revokeDevice(deviceId)
+        return ok({ ok: true })
+      }
+      throw new AuthError(404, 'not_found')
+    } catch (error) {
+      if (error instanceof AuthError) return { status: error.status, body: { error: error.code } }
+      if (error?.code === 'invalid_value') return { status: 400, body: { error: 'invalid_value', message: error.message } }
+      deps.log('control request failed:', error?.message ?? String(error))
+      return { status: 500, body: { error: 'internal_error' } }
+    }
+  }
+
+  /**
+   * Unsigned pairing on the gateway: a one-time code from the desktop QR plus the device key.
+   * @param {string} text
+   */
+  async function pair(text) {
+    try {
+      const body = parseJson(text)
+      deps.codes.consume(body.code)
+      parseDevicePublicKey(body.publicKey)
+      const fcmToken = body.fcmToken === undefined || body.fcmToken === null ? null : String(body.fcmToken)
+      if (fcmToken !== null && !FCM_TOKEN.test(fcmToken)) throw new AuthError(400, 'invalid_request')
+      const deviceId = deps.state.addDevice({
+        publicKey: body.publicKey,
+        label: typeof body.label === 'string' ? body.label.slice(0, 80) : '',
+        fcmToken,
+        previewMode: body.previewMode === 'full' ? 'full' : 'redacted',
+      })
+      deps.log('device paired', JSON.stringify({ deviceId }))
+      return ok({ deviceId, hostId: deps.state.hostId, hostLabel: deps.hostLabel, relayUrl: deps.relayUrl, origins: deps.origins() })
+    } catch (error) {
+      if (error instanceof AuthError) return { status: error.status, body: { error: error.code } }
+      deps.log('pairing failed:', error?.message ?? String(error))
+      return { status: 500, body: { error: 'internal_error' } }
+    }
+  }
+
+  function status(deviceId) {
+    const device = deps.state.device(deviceId)
+    return {
+      hostId: deps.state.hostId,
+      hostLabel: deps.hostLabel,
+      deviceId,
+      previewMode: device.previewMode,
+      pushEnabled: device.pushEnabled,
+      watchAll: device.watchAll,
+      pluginVersion: deps.version,
+      gatewayReady: deps.gateway.ready,
+      relayUrl: deps.relayUrl,
+      origins: deps.origins(),
+    }
+  }
+
+  async function answer(deviceId, body) {
+    if (typeof body.eventId !== 'string' || body.eventId.length > 100) throw new AuthError(400, 'invalid_request')
+    const pending = deps.gateway.get(body.eventId)
+    if (pending !== undefined) {
+      const value = validateAnswer(describe(pending, deps.sessions, deps.previewMaxChars), body.value)
+      const result = await deps.gateway.answer(body.eventId, value, `device:${deviceId}`)
+      return answerResponse(result, deviceId, body.eventId)
+    }
+    // Not pending: either already settled (409) or unknown/expired (404).
+    const result = await deps.gateway.answer(body.eventId, body.value, `device:${deviceId}`)
+    return answerResponse(result, deviceId, body.eventId)
+  }
+
+  function answerResponse(result, deviceId, eventId) {
+    switch (result.status) {
+      case 200:
+        deps.onAnswered?.(eventId, deviceId)
+        return ok({ ok: true, eventId })
+      case 409:
+        return { status: 409, body: { error: 'already_resolved', by: result.by === `device:${deviceId}` ? 'this_device' : 'other' } }
+      case 404:
+        return { status: 404, body: { error: 'unknown_event' } }
+      default:
+        return { status: 503, body: { error: 'gateway_unavailable' } }
+    }
+  }
+
+  function watch(deviceId, body) {
+    const ids = Array.isArray(body.sessionIds) ? body.sessionIds : []
+    if (ids.length > MAX_WATCHES_PER_DEVICE || !ids.every(id => typeof id === 'string' && SESSION_ID.test(id))) {
+      throw new AuthError(400, 'invalid_request')
+    }
+    const ttlSec = body.ttlSec === undefined ? 86_400 : Number(body.ttlSec)
+    if (!Number.isInteger(ttlSec) || ttlSec < 60 || ttlSec > 604_800) throw new AuthError(400, 'invalid_request')
+    if (body.watchAll !== undefined && typeof body.watchAll !== 'boolean') throw new AuthError(400, 'invalid_request')
+    const current = now()
+    deps.state.updateDevice(deviceId, (record) => {
+      for (const [id, expiry] of Object.entries(record.watches)) if (expiry <= current) delete record.watches[id]
+      for (const id of ids) record.watches[id] = current + ttlSec * 1000
+      const entries = Object.entries(record.watches).sort((a, b) => b[1] - a[1])
+      record.watches = Object.fromEntries(entries.slice(0, MAX_WATCHES_PER_DEVICE))
+      if (body.watchAll !== undefined) record.watchAll = body.watchAll
+    })
+    return ok({ ok: true })
+  }
+
+  function settings(deviceId, body) {
+    if (body.fcmToken !== undefined && body.fcmToken !== null && (typeof body.fcmToken !== 'string' || !FCM_TOKEN.test(body.fcmToken))) {
+      throw new AuthError(400, 'invalid_request')
+    }
+    if (body.previewMode !== undefined && body.previewMode !== 'full' && body.previewMode !== 'redacted') throw new AuthError(400, 'invalid_request')
+    if (body.pushEnabled !== undefined && typeof body.pushEnabled !== 'boolean') throw new AuthError(400, 'invalid_request')
+    deps.state.updateDevice(deviceId, (record) => {
+      if (body.fcmToken !== undefined) record.fcmToken = body.fcmToken
+      if (body.previewMode !== undefined) record.previewMode = body.previewMode
+      if (body.pushEnabled !== undefined) record.pushEnabled = body.pushEnabled
+    }, true)
+    return ok({ ok: true })
+  }
+
+  async function sessionList() {
+    let summaries = []
+    try {
+      summaries = await deps.listSessions()
+    } catch (error) {
+      deps.log('session list unavailable:', error?.message ?? String(error))
+    }
+    deps.sessions.learnTitles(summaries)
+    return summaries
+      .filter(s => s.parentSessionId === undefined && s.origin !== 'subagent')
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, 100)
+      .map(s => ({ sessionId: s.sessionId, title: deps.sessions.title(s.sessionId) || summaryTitle(s), running: s.running, updatedAt: s.updatedAt, cwd: s.cwd ?? '' }))
+  }
+
+  return { handle, pair }
+}
+
+function ok(body) {
+  return { status: 200, body }
+}
+
+function parseJson(text) {
+  if (text === undefined || text === '') return {}
+  try {
+    const value = JSON.parse(text)
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('not an object')
+    return value
+  } catch {
+    throw new AuthError(400, 'invalid_request')
+  }
+}
+
+function lowerCaseHeaders(headers) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  if (headers === null || typeof headers !== 'object') return out
+  for (const [key, value] of Object.entries(headers)) if (typeof value === 'string') out[key.toLowerCase()] = value
+  return out
+}

package/lib/desktop-api.mjs

@@ -0,0 +1,102 @@
+// Owner-only DSH `/api` routes used by the plugin's sidebar panel on the desktop
+// (docs/PROTOCOL.md v2 §2.1). Registered through ctx.connection.fetch, which admits only the owner.
+
+import qrcode from './vendor/qrcode.mjs'
+
+const PREFIX = '/api/dsh-mobile-bridge'
+
+/**
+ * @param {object} deps
+ * @param {import('./state.mjs').StateStore} deps.state
+ * @param {import('./auth.mjs').RegistrationCodes} deps.codes
+ * @param {import('./gateway.mjs').Gateway} deps.gateway
+ * @param {import('./tls-store.mjs').TlsStore} deps.tls
+ * @param {import('./web-sessions.mjs').WebSessions} deps.webSessions
+ * @param {() => {configured: boolean, connected: boolean}} deps.relay
+ * @param {string} deps.hostLabel
+ * @param {string} deps.version
+ * @param {(...a: unknown[]) => void} deps.log
+ * @returns {Array<{path: string, methods: string[], requestBody: 'buffered', fetch: (req: Request) => Promise<Response>}>}
+ */
+export function desktopRoutes(deps) {
+  const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } })
+
+  return [
+    {
+      path: `${PREFIX}/pairing`,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      async fetch() {
+        const origins = deps.gateway.origins()
+        if (origins.length === 0) return json(503, { error: 'gateway_not_listening' })
+        const { code, expiresAt } = deps.codes.issue('desktop')
+        const params = new URLSearchParams({ v: '2', h: deps.state.hostId, fp: deps.tls.ca.fingerprint, c: code, n: deps.hostLabel })
+        for (const origin of origins) params.append('o', origin)
+        const qr = `dshmb://pair?${params.toString()}`
+        const symbol = qrcode(0, 'M')
+        symbol.addData(qr)
+        symbol.make()
+        return json(200, {
+          qr,
+          qrSvg: symbol.createSvgTag({ cellSize: 4, margin: 4, scalable: true }),
+          code,
+          expiresAt,
+          origins,
+          caFingerprint: deps.tls.ca.fingerprint,
+          hostId: deps.state.hostId,
+          hostLabel: deps.hostLabel,
+        })
+      },
+    },
+    {
+      path: `${PREFIX}/status`,
+      methods: ['GET'],
+      requestBody: 'buffered',
+      async fetch() {
+        return json(200, {
+          hostId: deps.state.hostId,
+          hostLabel: deps.hostLabel,
+          version: deps.version,
+          gateway: { running: deps.gateway.running, port: deps.gateway.deps.port, origins: deps.gateway.origins(), caFingerprint: deps.tls.ca?.fingerprint ?? '' },
+          relay: deps.relay(),
+        })
+      },
+    },
+    {
+      path: `${PREFIX}/devices`,
+      methods: ['GET'],
+      requestBody: 'buffered',
+      async fetch() {
+        return json(200, {
+          devices: deps.state.devices().map(([deviceId, d]) => ({
+            deviceId,
+            label: d.label,
+            createdAt: d.createdAt,
+            lastSeenAt: d.lastSeenAt,
+            pushEnabled: d.pushEnabled,
+            hasPush: Boolean(d.fcmToken),
+          })),
+        })
+      },
+    },
+    {
+      path: `${PREFIX}/devices/revoke`,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      async fetch(req) {
+        let body
+        try {
+          body = await req.json()
+        } catch {
+          return json(400, { error: 'invalid_request' })
+        }
+        const deviceId = typeof body?.deviceId === 'string' ? body.deviceId : ''
+        if (!/^[a-f0-9]{32}$/.test(deviceId)) return json(400, { error: 'invalid_request' })
+        if (!deps.state.removeDevice(deviceId)) return json(404, { error: 'unknown_device' })
+        deps.webSessions.revokeDevice(deviceId)
+        deps.log('device removed from desktop', JSON.stringify({ deviceId }))
+        return json(200, { ok: true })
+      },
+    },
+  ]
+}

package/lib/gateway-client.mjs

@@ -0,0 +1,236 @@
+// Joins the DSH Gateway forwarded-event stream (`$events`) as an in-process owner client,
+// exactly like one more GUI window (ADR-0001 §3.1).
+//
+// - It never registers an `approval/request` / `user-questions/request` listener, so it can
+//   neither steal requests nor skip the GUI.
+// - It answers with `$events/result`; the Gateway keeps the first answer from any client and
+//   sends `cancel` to the others, which closes the desktop card.
+// - It never answers `{kind:'next'}`: if every client did, the waterfall would move past the GUI.
+
+import { randomUUID } from 'node:crypto'
+
+const HANDLED_EVENTS = new Set(['approval/request', 'user-questions/request'])
+const SETTLED_TTL_MS = 30 * 60 * 1000
+/** Time to let an already-queued `cancel` frame arrive after our result was accepted. */
+const RACE_SETTLE_MS = 150
+
+/**
+ * @typedef {object} PendingEvent
+ * @property {string} eventId
+ * @property {'approval'|'question'} kind
+ * @property {string} sessionId
+ * @property {Record<string, unknown>} request - JSON request fields from the Gateway
+ * @property {number} receivedAt
+ */
+
+/**
+ * @typedef {object} GatewayClientHooks
+ * @property {(event: PendingEvent) => void} [onPending]
+ * @property {(eventId: string, info: {by: string, pending: PendingEvent|undefined}) => void} [onResolved]
+ * @property {(ready: boolean) => void} [onReadyChange]
+ */
+
+export class GatewayClient {
+  /**
+   * @param {object} deps
+   * @param {() => {createPeer: Function, createSharedFetchHandler: Function}} deps.connection
+   * @param {() => {wireStream: {open: Function}}} deps.gateway
+   * @param {GatewayClientHooks} deps.hooks
+   * @param {(...args: unknown[]) => void} deps.log
+   * @param {() => number} [deps.now]
+   */
+  constructor({ connection, gateway, hooks, log, now = Date.now }) {
+    this.connection = connection
+    this.gateway = gateway
+    this.hooks = hooks
+    this.log = log
+    this.now = now
+    /** @type {Map<string, PendingEvent>} */
+    this.pending = new Map()
+    /** @type {Map<string, {by: string, at: number}>} */
+    this.settled = new Map()
+    /** @type {Map<string, {lost: boolean}>} */
+    this.submitting = new Map()
+    this.clientId = undefined
+    this.peer = undefined
+    this.fetchHandler = undefined
+  }
+
+  get ready() { return this.clientId !== undefined }
+
+  /** @returns {PendingEvent[]} */
+  list() { return [...this.pending.values()].sort((a, b) => a.receivedAt - b.receivedAt) }
+
+  /** @param {string} eventId */
+  get(eventId) { return this.pending.get(eventId) }
+
+  /**
+   * Keep one `$events` generation open until `signal` aborts; reconnect with backoff.
+   * @param {AbortSignal} signal
+   */
+  async run(signal) {
+    let delay = 500
+    const gateway = this.gateway()
+    const connection = this.connection()
+    if (typeof gateway?.wireStream?.open !== 'function' || typeof connection?.createPeer !== 'function'
+      || typeof connection?.createSharedFetchHandler !== 'function') {
+      // Pre-stable Gateway internals moved: fail loudly once instead of retrying forever.
+      this.log('this DSH version does not expose the Gateway event stream this plugin needs; approvals from the phone are disabled')
+      return
+    }
+    while (!signal.aborted) {
+      const generation = new AbortController()
+      const stop = () => generation.abort()
+      signal.addEventListener('abort', stop, { once: true })
+      try {
+        const connection = this.connection()
+        this.peer = connection.createPeer({ principal: { kind: 'owner' }, interactions: 'answer' })
+        this.fetchHandler = connection.createSharedFetchHandler('/api')
+        const uplink = (async function* () {})()
+        const stream = await this.gateway().wireStream.open('$events', { args: {} }, uplink, this.peer, generation.signal)
+        for await (const frame of stream) {
+          this.onFrame(frame)
+          delay = 500
+        }
+        if (!signal.aborted) this.log('event stream ended; reconnecting')
+      } catch (error) {
+        if (signal.aborted) break
+        this.log('event stream unavailable; retrying:', error?.message ?? String(error))
+      } finally {
+        signal.removeEventListener('abort', stop)
+        generation.abort()
+        this.resetGeneration()
+      }
+      if (signal.aborted) break
+      await sleep(delay, signal)
+      delay = Math.min(delay * 2, 15_000)
+    }
+  }
+
+  resetGeneration() {
+    const wasReady = this.ready
+    this.clientId = undefined
+    // Pending events are redelivered with the same eventId by the next generation.
+    this.pending.clear()
+    if (wasReady) this.hooks.onReadyChange?.(false)
+  }
+
+  /** @param {any} frame */
+  onFrame(frame) {
+    if (frame === null || typeof frame !== 'object') return
+    switch (frame.type) {
+      case 'ready':
+        this.clientId = frame.clientId
+        this.hooks.onReadyChange?.(true)
+        return
+      case 'waterfall': {
+        if (!HANDLED_EVENTS.has(frame.event) || typeof frame.eventId !== 'string' || typeof frame.agentId !== 'string') return
+        if (this.pending.has(frame.eventId) || this.settled.has(frame.eventId)) return
+        /** @type {PendingEvent} */
+        const pending = {
+          eventId: frame.eventId,
+          kind: frame.event === 'approval/request' ? 'approval' : 'question',
+          sessionId: frame.agentId,
+          request: frame.request !== null && typeof frame.request === 'object' ? frame.request : {},
+          receivedAt: this.now(),
+        }
+        this.pending.set(pending.eventId, pending)
+        this.hooks.onPending?.(pending)
+        return
+      }
+      case 'cancel': {
+        const eventId = frame.eventId
+        const inFlight = this.submitting.get(eventId)
+        if (inFlight !== undefined) inFlight.lost = true
+        const pending = this.pending.get(eventId)
+        this.pending.delete(eventId)
+        if (pending === undefined && inFlight === undefined) return
+        if (!this.settled.has(eventId) || inFlight !== undefined) this.remember(eventId, 'other')
+        this.hooks.onResolved?.(eventId, { by: 'other', pending })
+        return
+      }
+      default:
+    }
+  }
+
+  /**
+   * Answer one pending event. First answer wins; everything after is a conflict.
+   * @param {string} eventId
+   * @param {unknown} value - already validated for the event kind
+   * @param {string} by - e.g. `device:<id>`
+   * @returns {Promise<{status: 200} | {status: 409, by: string} | {status: 404} | {status: 503}>}
+   */
+  async answer(eventId, value, by) {
+    const settled = this.settled.get(eventId)
+    if (settled !== undefined) return { status: 409, by: settled.by }
+    const pending = this.pending.get(eventId)
+    if (pending === undefined) return { status: 404 }
+    if (!this.ready || this.peer === undefined || this.fetchHandler === undefined) return { status: 503 }
+    // Claim synchronously so a concurrent second answer in this process gets 409.
+    this.pending.delete(eventId)
+    this.remember(eventId, by)
+    const race = { lost: false }
+    this.submitting.set(eventId, race)
+    try {
+      const response = await this.fetchHandler.fetch(new Request('http://in-process/api/$events/result', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          type: 'client-request',
+          rpcId: randomUUID(),
+          method: '$events/result',
+          payload: { args: { clientId: this.clientId, eventId, outcome: { kind: 'result', value } } },
+        }),
+      }), this.peer)
+      const text = await response.text()
+      let ok = response.status === 200
+      try {
+        ok = ok && JSON.parse(text)?.result?.ok === true
+      } catch {
+        ok = false
+      }
+      if (!ok) {
+        // The Gateway refused the result (stale generation, malformed); give the event back.
+        this.settled.delete(eventId)
+        if (!race.lost) this.pending.set(eventId, pending)
+        this.log('gateway rejected answer', JSON.stringify({ eventId, status: response.status }))
+        return race.lost ? { status: 409, by: 'other' } : { status: 503 }
+      }
+      // A result for an event another client already settled is a silent no-op in the
+      // Gateway; the `cancel` frame for it is already queued, so give it a moment to land.
+      await sleep(RACE_SETTLE_MS)
+      if (race.lost) {
+        this.remember(eventId, 'other')
+        return { status: 409, by: 'other' }
+      }
+      this.hooks.onResolved?.(eventId, { by, pending })
+      return { status: 200 }
+    } finally {
+      this.submitting.delete(eventId)
+    }
+  }
+
+  /**
+   * @param {string} eventId
+   * @param {string} by
+   */
+  remember(eventId, by) {
+    const now = this.now()
+    this.settled.set(eventId, { by, at: now })
+    if (this.settled.size > 512) {
+      for (const [id, entry] of this.settled) if (now - entry.at > SETTLED_TTL_MS) this.settled.delete(id)
+    }
+  }
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done() {
+      signal?.removeEventListener('abort', done)
+      clearTimeout(timer)
+      resolve()
+    }
+    signal?.addEventListener('abort', done, { once: true })
+  })
+}