dsh-mobilecode 0.2.1 → 0.4.0

package/lib/stream-access.js

@@ -0,0 +1,220 @@
+/**
+ * dsh-mobilecode — capability tokens and the transport fence for the live
+ * stream routes.
+ *
+ * Ported from ZSeven-W/dsh-android (stream-access.ts, MIT), same security
+ * posture:
+ * - HMAC-SHA256 capabilities `base64url(payload).base64url(mac)`, signed with a
+ *   32-byte per-install key (`~/.dsh/mobilecode/stream-access.key`, created
+ *   atomically); tokens expire within 10 minutes.
+ * - Every route applies the loopback / trusted-browser transport fence (peer
+ *   address, loopback Host, Sec-Fetch-Site / Origin) BEFORE any capability is
+ *   consulted — Host/Origin are caller-controlled, so a LAN client cannot spoof
+ *   localhost and a DNS-rebinding Host is rejected.
+ *
+ * The screenshot-cache containment walk of the reference is not ported: this
+ * plugin serves only the live stream over its routes (device_screen writes PNGs
+ * to disk directly), so there is no arbitrary-path-serving surface to fence.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { HOME } from './setup.js'
+
+/** Hard capability lifetime (tokens expire within 10 minutes). */
+export const TOKEN_TTL_MS = 10 * 60 * 1000
+
+const KEY_BYTES = 32
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/
+const MAX_TOKEN_LENGTH = 16 * 1024
+/** Signing may run ahead of verification by this much before the TTL cap trips. */
+const CLOCK_SKEW_MS = 60 * 1000
+
+/** adb device serials: `emulator-5554`, `RFCX123ABC`, or `host:port` for network adb. */
+export const SERIAL_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
+
+function keyPath() {
+  return path.join(HOME, 'stream-access.key')
+}
+
+function mac(key, payload) {
+  return createHmac('sha256', key).update(payload).digest()
+}
+
+function safeEqual(left, right) {
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+/** Load or atomically create the per-install 32-byte signing key. */
+export async function prepareStreamAccessKey() {
+  await mkdir(HOME, { recursive: true })
+  const file = keyPath()
+  if (existsSync(file)) {
+    const key = await readFile(file)
+    if (key.length === KEY_BYTES) return key
+    throw new Error('dsh-mobilecode: stream access key has an invalid length')
+  }
+  const candidate = randomBytes(KEY_BYTES)
+  try {
+    await writeFile(file, candidate, { flag: 'wx', mode: 0o600 })
+    return candidate
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+    const key = await readFile(file)
+    if (key.length !== KEY_BYTES) throw new Error('dsh-mobilecode: stream access key has an invalid length')
+    return key
+  }
+}
+
+function parseStreamPayload(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  if (
+    value.v !== 1
+    || value.kind !== 'mobilecode-stream'
+    || typeof value.serial !== 'string'
+    || !SERIAL_PATTERN.test(value.serial)
+    || typeof value.exp !== 'number'
+    || !Number.isSafeInteger(value.exp)
+  ) return undefined
+  return { v: 1, kind: 'mobilecode-stream', serial: value.serial, exp: value.exp }
+}
+
+/** HMAC capability encoder/verifier for the live stream URL. */
+export class StreamAccessController {
+  #routeCount = 0
+  #keyPromise
+
+  constructor(resolveKey = prepareStreamAccessKey) {
+    this.resolveKey = resolveKey
+  }
+
+  /** Whether at least one HTTP carrier currently owns the routes. */
+  get routeAvailable() {
+    return this.#routeCount > 0
+  }
+
+  /** Mark one route attachment; the returned disposer removes it. */
+  attachRoute() {
+    this.#routeCount += 1
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      this.#routeCount -= 1
+    }
+  }
+
+  /** Mint a stream capability for one device serial. */
+  async signStreamToken(serial, options = {}) {
+    if (!SERIAL_PATTERN.test(serial)) throw new TypeError('dsh-mobilecode: signStreamToken requires a device serial')
+    const key = await this.#key()
+    const payload = { v: 1, kind: 'mobilecode-stream', serial, exp: Date.now() + this.#ttl(options.ttlMs) }
+    const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url')
+    return { token: `${encoded}.${mac(key, encoded).toString('base64url')}`, expiresAt: payload.exp }
+  }
+
+  async verifyStreamToken(token) {
+    if (token.length === 0 || token.length > MAX_TOKEN_LENGTH || !TOKEN_PATTERN.test(token)) return undefined
+    const [encoded, signature] = token.split('.')
+    if (encoded === undefined || signature === undefined) return undefined
+    const key = await this.#key().catch(() => undefined)
+    if (key === undefined) return undefined
+    let supplied
+    try {
+      supplied = Buffer.from(signature, 'base64url')
+    } catch {
+      return undefined
+    }
+    if (!safeEqual(mac(key, encoded), supplied)) return undefined
+    try {
+      const payload = parseStreamPayload(JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8')))
+      if (payload === undefined) return undefined
+      const now = Date.now()
+      if (payload.exp <= now) return undefined
+      if (payload.exp - now > TOKEN_TTL_MS + CLOCK_SKEW_MS) return undefined
+      return payload
+    } catch {
+      return undefined
+    }
+  }
+
+  #ttl(ttlMs) {
+    if (ttlMs === undefined || !Number.isFinite(ttlMs)) return TOKEN_TTL_MS
+    return Math.min(TOKEN_TTL_MS, Math.max(1, Math.floor(ttlMs)))
+  }
+
+  #key() {
+    this.#keyPromise ??= this.resolveKey()
+    return this.#keyPromise
+  }
+}
+
+// ── loopback / trusted-browser transport fence ───────────────────────────────
+
+function isIpv4LoopbackAddress(address) {
+  const parts = address.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Trust the transport peer, never forwarded or caller-controlled host data.
+ * Node may expose an IPv4 peer directly or as an IPv4-mapped IPv6 address,
+ * including the compact hexadecimal form used by some platforms.
+ */
+export function isLoopbackRemoteAddress(address) {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase().split('%', 1)[0]
+  if (normalized === '::1' || isIpv4LoopbackAddress(normalized)) return true
+  if (!normalized.startsWith('::ffff:')) return false
+  const mapped = normalized.slice('::ffff:'.length)
+  if (isIpv4LoopbackAddress(mapped)) return true
+  const hexadecimal = /^([a-f0-9]{1,4}):([a-f0-9]{1,4})$/.exec(mapped)
+  return hexadecimal !== null && (Number.parseInt(hexadecimal[1], 16) >>> 8) === 127
+}
+
+function isLoopbackHostname(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]' || hostname === '::1') return true
+  return isIpv4LoopbackAddress(hostname)
+}
+
+function requestAuthority(req) {
+  const host = req.headers.host
+  if (typeof host !== 'string') return undefined
+  try {
+    const parsed = new URL(`http://${host}`)
+    if (parsed.pathname !== '/' || parsed.search !== '' || parsed.hash !== '' || parsed.username !== '' || parsed.password !== '') {
+      return undefined
+    }
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+
+function isLoopbackRequest(req) {
+  if (!isLoopbackRemoteAddress(req.socket?.remoteAddress)) return false
+  const authority = requestAuthority(req)
+  return authority !== undefined && isLoopbackHostname(authority.hostname)
+}
+
+function isTrustedBrowserRequest(req, requireOrigin) {
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = req.headers.origin
+  if (origin === undefined) return !requireOrigin
+  if (typeof origin !== 'string') return false
+  const authority = requestAuthority(req)
+  if (authority === undefined) return false
+  try {
+    const parsed = new URL(origin)
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && parsed.host === authority.host
+  } catch {
+    return false
+  }
+}
+
+/** The transport fence applied to every stream route. */
+export function isTrustedRequest(req, requireOrigin = false) {
+  return isLoopbackRequest(req) && isTrustedBrowserRequest(req, requireOrigin)
+}

package/lib/vision.js

@@ -0,0 +1,130 @@
+/**
+ * dsh-mobilecode — native multimodal delivery.
+ *
+ * When the routed model declares image input, the capture tools hand the model
+ * the screenshot ITSELF (a `{type:'image', attachment}` block) instead of only a
+ * file path it would have to open. DSH 0.1.1 carries images end to end: tool
+ * results may contain image blocks, bytes live in the durable attachment store
+ * (`ctx.get('attachments')`), and `llm.resolveModelInfo(...).inputModalities`
+ * says whether the routed model accepts images. This mirrors the in-tree
+ * `read_image` tool in dsh-tool-fs.
+ *
+ * The deliberate difference from `read_image`: where that tool REFUSES on a
+ * text-only route (the image is its whole point), the capture tools here
+ * DEGRADE. The primary output is always the JSON summary; the image block is an
+ * enhancement added only when (a) the attachment store is mounted, (b) the
+ * calling route's resolved model declares `image` input, and (c) admission
+ * succeeds. Any failure in that chain silently keeps the text-only behavior, so
+ * text-only routes, headless profiles, and older hosts never see a new error.
+ *
+ * Everything is typed structurally — the plugin is plain JS and must not depend
+ * on the host's attachment type exports.
+ * @module vision
+ */
+
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * Resolve the optional vision services from the plugin context. Both come back
+ * absent on hosts that do not mount them; every consumer treats that as
+ * "stay text-only".
+ */
+export function resolveVisionServices(ctx) {
+  const get = typeof ctx?.get === 'function' ? ctx.get.bind(ctx) : undefined
+  if (get === undefined) return {}
+  const attachments = get('attachments')
+  const llm = get('llm')
+  return {
+    ...(attachments !== undefined && typeof attachments.saveImage === 'function' ? { attachments } : {}),
+    ...(llm !== undefined && typeof llm.resolveModelInfo === 'function' ? { llm } : {}),
+  }
+}
+
+/**
+ * True when the calling route's resolved model declares `image` input. Mirrors
+ * `read_image`'s gate (request-header config first, then agent options) but
+ * answers false instead of throwing: a tool result that enters durable history
+ * must not carry an image its route cannot replay.
+ */
+export async function imageInputActive(services, exec) {
+  if (services.llm === undefined || services.attachments === undefined) return false
+  try {
+    const routed = exec?.agent?.session?.requestHeader?.()?.config
+    const provider = routed?.provider ?? exec?.agent?.options?.provider
+    const model = routed?.model ?? exec?.agent?.options?.model
+    if (provider === undefined || model === undefined) return false
+    const info = await services.llm.resolveModelInfo(provider, model, exec?.signal)
+    return info?.inputModalities?.includes('image') === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Durably commit one screenshot PNG and return the plain reference for the
+ * result value, or undefined when the store is absent or admission fails
+ * (oversized, malformed) — never an error, per the degrade-not-refuse rule.
+ */
+export async function saveScreenshotAttachment(services, png, name) {
+  const attachments = services.attachments
+  if (attachments === undefined) return undefined
+  try {
+    const ref = await attachments.saveImage({ data: png, mediaType: 'image/png', name })
+    if (typeof ref?.attachmentId !== 'string' || ref.attachmentId === '') return undefined
+    return {
+      attachmentId: ref.attachmentId,
+      mediaType: ref.mediaType,
+      bytes: ref.bytes,
+      width: ref.width,
+      height: ref.height,
+      ...(ref.name === undefined ? {} : { name: ref.name }),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Convenience for the capture tools: gate on the route, read the file, and save
+ * the attachment — returning undefined (degrade) on any miss. Never throws.
+ */
+export async function maybeAttachScreenshot(services, filePath, exec) {
+  if (services.attachments === undefined || typeof filePath !== 'string' || filePath === '') return undefined
+  if (!(await imageInputActive(services, exec))) return undefined
+  try {
+    const data = await readFile(filePath)
+    return await saveScreenshotAttachment(services, data, path.basename(filePath))
+  } catch {
+    return undefined
+  }
+}
+
+/** Output-schema fragment for the optional `image` result field. */
+export const IMAGE_REF_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  description: 'Durable attachment reference for the screenshot delivered to the model as an image block '
+    + '(present only when the routed model declares image input).',
+  properties: {
+    attachmentId: { type: 'string', required: true },
+    mediaType: { type: 'string', required: true },
+    bytes: { type: 'number', required: true },
+    width: { type: 'number', required: true },
+    height: { type: 'number', required: true },
+    name: { type: 'string' },
+  },
+}
+
+/**
+ * Append the image block to a render's content blocks when the value carries an
+ * `image` ref — so an image-capable model SEES the screen. Returns the same
+ * array for chaining.
+ */
+export function appendImageBlock(blocks, value) {
+  const image = value?.image
+  if (image !== undefined && typeof image.attachmentId === 'string') {
+    blocks.push({ type: 'image', attachment: image })
+  }
+  return blocks
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mobilecode",
   "description": "MobileCode for the dsh web GUI: detect iOS/Android projects, run serve-sim / serve-avd preview servers, and build-install-launch the app on the simulator or emulator from the session — plus agent tools (device_run, device_detect). Hot-pluggable — mounted via the profile bundle list + cordis.patch.yml, no dsh source changes.",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {